mirror of
https://git.openapi.site/https://github.com/desirecore/market.git
synced 2026-10-21 01:24:36 +08:00
docs(feishu-orchestrator): 补 USAGE.md 使用说明并重新 pin / add USAGE.md and repin (#137)
## 背景 / 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
```
This commit is contained in:
@@ -36,7 +36,7 @@
|
||||
"timestamps": {
|
||||
"catalogUpdatedAt": {
|
||||
"state": "known",
|
||||
"value": "2026-09-04",
|
||||
"value": "2026-09-06",
|
||||
"precision": "day"
|
||||
},
|
||||
"releasePublishedAt": {
|
||||
@@ -46,12 +46,12 @@
|
||||
},
|
||||
"reviewedAt": {
|
||||
"state": "known",
|
||||
"value": "2026-09-04",
|
||||
"value": "2026-09-06",
|
||||
"precision": "day"
|
||||
},
|
||||
"upstreamObservedAt": {
|
||||
"state": "known",
|
||||
"value": "2026-09-01T00:00:00Z",
|
||||
"value": "2026-09-06T00:00:00Z",
|
||||
"precision": "second"
|
||||
}
|
||||
},
|
||||
@@ -59,7 +59,7 @@
|
||||
"content": {
|
||||
"kind": "git",
|
||||
"url": "https://github.com/desirecore-agent/feishu-orchestrator.git",
|
||||
"ref": "d5b0a786a5b429f46bccb3a93a5396904072c854"
|
||||
"ref": "6116ad4ac7c0b90d44145a3d6ba86e89a33d6c3f"
|
||||
}
|
||||
},
|
||||
"governance": {
|
||||
@@ -87,8 +87,8 @@
|
||||
"compliance": {
|
||||
"licenseEvidencePath": "LICENSE",
|
||||
"noticePath": "NOTICE",
|
||||
"reviewedRef": "d5b0a786a5b429f46bccb3a93a5396904072c854",
|
||||
"reviewedAt": "2026-09-04",
|
||||
"reviewedRef": "6116ad4ac7c0b90d44145a3d6ba86e89a33d6c3f",
|
||||
"reviewedAt": "2026-09-06",
|
||||
"reviewedBy": "yi-ge",
|
||||
"upstreamEndorsed": true
|
||||
}
|
||||
|
||||
@@ -39,6 +39,6 @@
|
||||
"kind": "git",
|
||||
"repoUrl": "https://github.com/desirecore-agent/feishu-orchestrator.git",
|
||||
"repoBranch": "main",
|
||||
"ref": "d5b0a786a5b429f46bccb3a93a5396904072c854"
|
||||
"ref": "6116ad4ac7c0b90d44145a3d6ba86e89a33d6c3f"
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user