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:
2026-09-06 12:19:03 -04:00
committed by GitHub
parent 41c0badfcb
commit 377b7254dc
2 changed files with 7 additions and 7 deletions

View File

@@ -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
}

View File

@@ -39,6 +39,6 @@
"kind": "git",
"repoUrl": "https://github.com/desirecore-agent/feishu-orchestrator.git",
"repoBranch": "main",
"ref": "d5b0a786a5b429f46bccb3a93a5396904072c854"
"ref": "6116ad4ac7c0b90d44145a3d6ba86e89a33d6c3f"
}
}