mirror of
https://git.openapi.site/https://github.com/desirecore/market.git
synced 2026-10-21 05:04:36 +08:00
Yige
377b7254dc
## 背景 / Background
主仓 [#2600](https://github.com/desirecore/desirecore/pull/2600)
给市场详情页加了「使用说明」区块，按约定文件名 `USAGE.md` 消费。飞书编排助手此前没有这个文件，详情页不渲染该区块——README
里的前置条件、授权步骤与边界，只有访问 GitHub 才看得到，而真正需要它的是市场里正准备安装的人。
The market detail page gained a Usage section in desirecore#2600,
sourced from a conventional `USAGE.md`. This agent had none, so the
section stayed hidden — its prerequisites, auth steps and limits were
reachable only by visiting GitHub.
## 改动 / Changes
- 上游新增
`USAGE.md`（[desirecore-agent/feishu-orchestrator@6116ad4](6116ad4ac7)）
- 本条目重新 pin 到该 commit，证据六项同步更新
## 为什么放上游而不是条目目录 / Why upstream
`sync/market.ts` 有两条读取路径，只有一条读本地条目目录：
| 方法 | 本地条目目录基线 | 远程 |
|---|---|---|
| `readAgentDetail`（inline 形态） | ✅ `readUsageDocFromDir` | 有则覆盖 |
| `readAgentDetailFromPointer`（**本条目**） | ❌ 无 | 仅远程 |
所以 pointer 条目的使用说明只能来自上游仓库。条目目录放 `USAGE.md` 对本条目无效。
## 为什么只有无后缀版本 / Why no locale variants
远程抓取时，`USAGE.<locale>.md` 的探测列表由 `extractDeclaredLocales` 从**上游
agent.json 的 `i18n.locales`** 得出；无后缀 `USAGE.md` 则总是被抓。
而 `agentConfigSchema` 顶层没有 `i18n`，根级 `additionalProperties: false`——给上游
agent.json 加这个字段会让 pointer 形态的安装校验直接失败。因此本条目只提供无后缀 `USAGE.md`。
## 内容 / Content
按 `usage-doc.ts` 的定位写「装之前该知道什么」，不是全量文档（3212 字符，上限
16000）：第三方分发免责、四步授权、审批模式取舍、安全边界、已验证/未验证清单。各业务域的实测细节仍在上游 `docs/` 的 13 篇里。
两处与既有同类文档（`dingtalk-workspace/USAGE.md`）不同，是核对 `app/data/i18n/zh-CN.ts`
后的修正而非照搬：
- 审批模式是 **7 种**不是 6 种，补上 `allow-all`（全部放行）
- `ask-external` 的语义是「内置工具与命令放行，仅
MCP、HTTP、脚本等外部工具需审批」，**不是**「交给外部系统裁决」——两者含义相反，照搬会让用户以为自己收紧了，实际放宽了命令执行
## 验证 / Verification
证据六项一致性自检全部通过：
```
content.ref == entry.source.ref ✅ 6116ad4ac
reviewedRef == content.ref ✅
timestamps.reviewedAt == compliance.reviewedAt ✅ 2026-09-06
availability ✅ installable
license ✅ known + LICENSE
requiredClientVersion ✅ 10.0.144
```