From 377b7254dc50e3ca2cccc04e7e757eff8efbbf81 Mon Sep 17 00:00:00 2001 From: Yige Date: Sun, 6 Sep 2026 12:19:03 -0400 Subject: [PATCH] =?UTF-8?q?docs(feishu-orchestrator):=20=E8=A1=A5=20USAGE.?= =?UTF-8?q?md=20=E4=BD=BF=E7=94=A8=E8=AF=B4=E6=98=8E=E5=B9=B6=E9=87=8D?= =?UTF-8?q?=E6=96=B0=20pin=20/=20add=20USAGE.md=20and=20repin=20(#137)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 背景 / 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](https://github.com/desirecore-agent/feishu-orchestrator/commit/6116ad4ac7c0b90d44145a3d6ba86e89a33d6c3f)） - 本条目重新 pin 到该 commit，证据六项同步更新 ## 为什么放上游而不是条目目录 / Why upstream `sync/market.ts` 有两条读取路径，只有一条读本地条目目录： | 方法 | 本地条目目录基线 | 远程 | |---|---|---| | `readAgentDetail`（inline 形态） | ✅ `readUsageDocFromDir` | 有则覆盖 | | `readAgentDetailFromPointer`（**本条目**） | ❌ 无 | 仅远程 | 所以 pointer 条目的使用说明只能来自上游仓库。条目目录放 `USAGE.md` 对本条目无效。 ## 为什么只有无后缀版本 / Why no locale variants 远程抓取时，`USAGE..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 ``` --- agents/feishu-orchestrator/catalog-metadata.v1.json | 12 ++++++------ agents/feishu-orchestrator/entry.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/agents/feishu-orchestrator/catalog-metadata.v1.json b/agents/feishu-orchestrator/catalog-metadata.v1.json index ae3df45..cc46283 100644 --- a/agents/feishu-orchestrator/catalog-metadata.v1.json +++ b/agents/feishu-orchestrator/catalog-metadata.v1.json @@ -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 } diff --git a/agents/feishu-orchestrator/entry.json b/agents/feishu-orchestrator/entry.json index 5e56dcf..7d206d0 100644 --- a/agents/feishu-orchestrator/entry.json +++ b/agents/feishu-orchestrator/entry.json @@ -39,6 +39,6 @@ "kind": "git", "repoUrl": "https://github.com/desirecore-agent/feishu-orchestrator.git", "repoBranch": "main", - "ref": "d5b0a786a5b429f46bccb3a93a5396904072c854" + "ref": "6116ad4ac7c0b90d44145a3d6ba86e89a33d6c3f" } }