feat(dingtalk-workspace): add USAGE.md and wire feature docs into skill references (#113)

## 背景 / Background

`agents/dingtalk-workspace` 条目把 13 篇使用文档放在 `docs/` 目录，但**两侧都读不到**：

- 市场详情页只渲染 `agent.json` 的元数据字段，不扫描条目目录下的 `docs/`
- Agent 自身的上下文只挂载 `persona.md` / `principles.md` / `memory/` /
`skills/`，`docs/` 不在其中

The listing kept 13 usage documents under `docs/`, but nothing consumed
them: the
market detail page only projects `agent.json` metadata, and the agent's
own context
mounts `persona.md` / `principles.md` / `memory/` / `skills/` only.

## 变更 / Changes

配合 DesireCore 主仓库的 `USAGE.md` 平台约定（ADR-143）与既有技能 `references` 机制，分别解决两侧。
Pairs with the new `USAGE.md` platform convention (ADR-143) in the
DesireCore repo.

| 变更 / Change | 说明 / Detail |
| --- | --- |
| 新增 `USAGE.md` | 安装前该知道的内容：第三方 CLI 依赖声明、5
步快速开始、六种审批模式取舍、安全与已知边界。**刻意不含图片**——详情页的 markdown 渲染器会移除普通 `img src` |
| 新增私有技能 `dingtalk-guide` | 只做索引，正文用 `${SKILL_DIR}/references/` 绝对路径指向
13 篇文档，Agent 按需 `Read`。单产品问题（如「钉盘同步怎么用」）可触发查文档再作答，不占每轮上下文 |
| `docs/` → `dingtalk-guide/references/` | 整体移入并拍平。原 12
篇无交叉链接、无图片，移动无需改写正文 |
| `docs/README.md` 拆分 | 安装部分 → `USAGE.md`；界面与审批部分连同两张截图 →
`references/界面与审批.md` |
| `README.md` | 补 `USAGE.md` 约定说明与目录树条目 |
| `manifest.json` | 1.5.0 → 1.5.1（条目内容新增；计数不变，经校验器实跑确认） |

**单一真相源 / Single source of truth**：每篇文档只有一份，归 `dingtalk-guide` 技能所有；
不存在 `docs/` 与 `references/` 两份副本。`dingtalk-onboarding` 与
`dingtalk-workflows`
两个既有技能不变。

## 校验 / Validation

README 记录的 7 条 CI 校验命令全部实跑通过（改动前后各一轮）：

```
scripts/i18n/test_validate_i18n.py                              exit=0
scripts/catalog/test_validate_catalog_metadata.py               exit=0
scripts/catalog/test_collection_generator.py                    exit=0
scripts/catalog/validate_catalog_metadata.py --require-complete  exit=0
scripts/i18n/validate-i18n.py                                   exit=0
scripts/i18n/translate.py --check                               exit=0
scripts/gen-collection-children.py --check                      exit=0
```

`manifest.json#stats` 由 `validate_catalog_metadata` 输出实跑确认（agents=3,
teams=1,
publishableSkills=69），非算术推导，故不变。

## 公开信息边界 / Public information boundary

全树扫描零命中：改动文件、新增路径名、分支名、commit 主题与正文、本 PR 文本均不含
租户/客户/伙伴/个人身份。两张截图已逐张目视复核——仅含 DesireCore 自身界面、Agent 名称与
通用 `dws` 命令，返回结果为空列表，不含组织名或任何组织形态。

Full-tree scan returned zero results. Both screenshots were reviewed
individually:
they show only DesireCore's own UI, the agent name, and generic `dws`
commands.

## 依赖 / Dependency

`USAGE.md` 的详情页渲染依赖 DesireCore 主仓库的配套 PR。在其发布前，本条目的
`USAGE.md` 仍是仓库内可读的普通文件，不影响现有行为。

Detail-page rendering depends on the companion PR in the DesireCore
repository.
Until it ships, `USAGE.md` is simply a readable file in the listing and
changes nothing.

README.md

@@ -14,7 +14,8 @@ DesireCore 官方市场仓库，存放官方维护的 Agent/Team/Skill 定义，
 │   │   └── agent.json
 │   └── <agent-listing>/
 │       ├── agent.json
-│       └── catalog-metadata.v1.json
+│       ├── catalog-metadata.v1.json
+│       └── USAGE.md            # Optional usage notes (USAGE.<locale>.md for variants)
 ├── teams/
 │   └── <team>/
 │       └── entry.json
@@ -222,6 +223,19 @@ or simultaneous primary files are rejected. For a pointer, `entry.id` and sideca
 `identity.id` use the catalog directory slug and `identity.kind` is `agent`; the
 upstream AgentFS `agent.json.id` remains its own UUID and must not be rewritten.
 
+An agent listing may also carry an optional `USAGE.md` next to `agent.json`. The
+client renders it as a separate "Usage" section on the agent detail page, kept
+apart from `fullDesc` (which is persona text and also enters the agent's runtime
+context). Localized variants use `USAGE.<locale>.md`, resolved through the same
+fallback chain as the `i18n` block: requested locale, then `i18n.source_locale`,
+then `i18n.default_locale`, then the unsuffixed file. Its scope is what a reader
+needs *before* installing — prerequisites, authorization steps, capability and
+safety boundaries — not full documentation; clients truncate overlong content.
+Longer material belongs in a skill's `references/` directory, which the agent
+loads on demand. Listings without the file are unaffected and render no section.
+Relative image references do not render on the detail page, so keep `USAGE.md`
+text-only. See ADR-143 in the DesireCore repository.
+
 Agent pointers first pass the complete raw client contract in
 [`schemas/market-agent-entry.client.schema.json`](schemas/market-agent-entry.client.schema.json),
 exported from `marketAgentEntrySchema` in the DesireCore repository at commit

agents/dingtalk-workspace/USAGE.md

@@ -0,0 +1,131 @@
+# 使用说明
+
+把自然语言意图翻译成钉钉官方 CLI（`dws`）的正确调用，并对结果负责。覆盖通讯录、群聊消息、
+日程会议、待办、审批、考勤、日志、文档、表格、AI 多维表、钉盘、知识库、邮件、AI 听记、DING、
+实时事件等钉钉产品域。
+
+**它不是钉钉命令的说明书。** 命令目录由钉钉官方技能与 `dws schema` 提供，随二进制升级而更新。
+本 Agent 做的是官方技能不覆盖的四件事：
+
+| 增量 | 说明 |
+| --- | --- |
+| **接入** | 钉钉官方 CLI 的 Agent 分发列表里没有 DesireCore，装到 DesireCore 的路径无人覆盖 |
+| **纪律** | 钉钉 CLI 有 339 个「自己不拦」的写操作（占全部写操作 56%），由本 Agent 把关 |
+| **编排** | 跨产品工作流；官方 SKILL.md 明写「定时调度由外层工作流负责」 |
+| **降级** | 没装 / 没授权 / 没权限 / 没开通时如实停下，绝不编造成功 |
+
+---
+
+## 装之前必须知道
+
+本 Agent 依赖一个**由第三方独立分发**的命令行程序。DesireCore 不打包、不分发、不授权、
+不安装、不代付、不运营该程序及其背后的钉钉产品。凭据与费用由你与钉钉之间的服务条款约束。
+
+装完本 Agent 还**不能直接用**，必须自行完成下面 5 步。
+
+---
+
+## 快速开始
+
+### 1. 安装钉钉官方 CLI
+
+```bash
+npm i -g dingtalk-workspace-cli
+```
+
+⚠️ 这一步会顺带往你机器上**其它 AI 编程工具的技能目录**写入钉钉技能
+（`~/.claude/skills/`、`~/.cursor/skills/` 等，共 80+ 个框架）。这是上游 `dws` 的
+postinstall 行为，不是 DesireCore 做的。
+
+### 2. 把官方产品技能装进 DesireCore
+
+装完 CLI 后技能已解包在 `~/.dws/skills/multi/`，拷进 DesireCore 全局技能目录：
+
+```bash
+DC_ROOT="${DESIRECORE_TEST_ROOT:-${DESIRECORE_HOME:-$HOME/.desirecore}}"
+mkdir -p "$DC_ROOT/skills"
+cp -R ~/.dws/skills/multi/dingtalk-* "$DC_ROOT/skills/"
+```
+
+共 14 个：`aisearch` `aitable` `calendar` `chat` `contact` `doc` `drive` `event`
+`mail` `minutes` `misc` `shared` `todo` `wiki`。
+
+> **为什么不走市场安装**：市场里有 `dingtalk-cli` 条目，但钉钉官方仓库未公开（HTTP 404），
+> 客户端按 git 源拉不到内容。该条目的作用是让你在市场里发现这个能力并看到装法，不是分发通道。
+>
+> **代价**：这样装的技能没有 provenance 记录，市场同步视为孤儿——既不自动更新也不自动卸载。
+> **每次 `dws upgrade` 后要重跑一次上面的拷贝。**
+
+### 3. 授权
+
+```bash
+dws auth login              # 本机有浏览器
+dws auth login --device     # 无浏览器 / SSH / 容器，出设备码
+```
+
+⚠️ **钉钉不支持账号密码登录**，也不支持手机验证码、纯应用凭证。只有 OAuth 回环、设备流、
+`--token`、自有应用 OAuth 四种。
+
+授权成功后 access token 约 2 小时、refresh token 约 30 天自动刷新，之后无需再打扰。
+
+### 4. 把 `dws` 加进命令白名单（强烈建议）
+
+实测每条 `dws` 命令都会被判**高风险**并弹审批卡片——18 个测试用例里 34 次 Bash 调用触发了
+**41 次审批**。不加白名单的话你要不停点确认。
+
+点输入框左下角的审批模式胶囊即可切换。六种模式的取舍：
+
+| 模式 | 行为 | 适合 |
+| --- | --- | --- |
+| **AI 审批**（默认） | 前台保留 30 秒真人抢先窗口，AI 建议到达即收敛 | 日常，但**需要配好审批 chat 模型** |
+| 完全 AI 审批 | AI 建议到达立即决策 | 无人值守 |
+| 仅 AI 建议 | AI 只提供参考，永不自动决策，无截止时间等待真人 | 高风险场景 |
+| 每次确认 | 每次执行命令都要你审批 | 最保守 |
+| **白名单** | 仅白名单中的命令可自动执行 | **推荐**：把 `dws` 加进去 |
+| 外部工具审批 | 交给外部系统裁决 | 有审批中台时 |
+
+⚠️ **默认的「AI 审批」需要一个可用的审批 chat 模型。** 没配的话所有命令会被 fail-closed
+拦掉，报「AI 审批后端不可用，命令未执行」——连本 Agent 自己写计划文件都会被拦。要么去
+资源管理面板 → 算力配一个 chat 模型，要么换成「白名单」或「每次确认」。
+
+### 5. 自检
+
+```bash
+dws doctor
+```
+
+四项：登录状态 / 钥匙串 / 网络连通性 / 版本更新。
+
+---
+
+## 安全边界
+
+本 Agent 继承钉钉官方的执行契约，并补了 DesireCore 侧的一层：
+
+- **只走 `dws`**，不用 curl、不自拼 HTTP
+- **不编造标识符**——userId / docId / baseId 一律从命令返回中提取
+- **写操作先确认**，判据是 `effect == destructive || risk == high || confirmation == user_required`
+  三元组兜底（不能只看 `confirmation` 字段：1256 个工具里有 339 个是 `dws` 自己不拦的 silent-write）
+- **单次批量 ≤ 30 条**
+- **多候选禁止默认取第一个**；多组织时解析、读取、执行必须用同一个 profile
+- **退出码不等于成功**——只有 `data.complete=true` 才能说「全部」，响应里缺少集合不能当空结果
+- **禁止轮询**消息历史或审批列表，实时需求走长连接
+
+---
+
+## 已知边界
+
+| 限制 | 说明 |
+| --- | --- |
+| 视频会议 | **CLI 无入口**。会前（排日程订会议室）与会后（纪要/逐字稿/行动项）可用，会中控制需在钉钉客户端操作 |
+| 消息搜索 | 需要**消息搜索权益**，未开通时返回 `SearchRightsDenied`。其余 chat 能力（发消息、群管理、机器人）不受影响 |
+| 组织权限 | 能力覆盖取决于 OAuth 授权范围与你所在组织开通的产品，本 Agent 会在受限时如实说明 |
+
+---
+
+## 更详细的功能文档
+
+按产品域的能力覆盖、边界与权益门槛，随 Agent 一起安装在私有技能
+`dingtalk-guide` 的 `references/` 目录下（通讯录、群聊、日程、待办审批、文档表格、
+钉盘知识库、邮件、AI 听记、考勤日志、实时事件、跨产品工作流、界面与审批、故障排查共 13 篇）。
+装好后直接问本 Agent「钉盘同步怎么用」这类问题即可，它会自己去读对应文档再回答。

agents/dingtalk-workspace/docs/README.md

@@ -1,141 +0,0 @@
-# 钉钉工作台助手
-
-把自然语言意图翻译成钉钉官方 CLI 的正确调用，并对结果负责。
-
-覆盖钉钉 **29 个产品、1256 个工具**：通讯录、群聊消息、日程会议、待办、审批、考勤、日志、文档、表格、AI 多维表、钉盘、知识库、邮件、AI 听记、DING、实时事件等。
-
----
-
-## 它长什么样
-
-![审批闸门与命令执行](assets/审批与执行.png)
-
-这是一次真实对话（问「我这边有哪些可用的机器人？」）。三件事值得注意：
-
-1. **每条 `dws` 命令都过审批闸门**，标注风险等级，你可以逐条批准或拒绝
-2. **先查 schema 再执行** —— 前两条是 `dws schema --cli-path ...` 确认命令结构与参数，第三条才真正执行
-3. **答案带着依据** —— 「开放平台应用列表为空，**且分页已完整结束**」。只有确认分页走到底才敢说「没有」，不会让你被一个假的空结果误导
-
-## 它是什么，不是什么
-
-**是**：钉钉能力的入口与编排层。你说要做什么，它负责找对产品域、选对命令、拿到可信结果。
-
-**不是**：钉钉命令的说明书。命令目录由钉钉官方技能与 `dws schema` 提供，随二进制升级而更新——官方文档自己就写明「命令可用性以当前 dws 二进制为准，本文档可能滞后于二进制」。所以这个助手**不复制命令表**，它做的是官方技能不管的四件事：
-
-| 增量 | 说明 |
-| --- | --- |
-| **接入** | 钉钉官方 CLI 的 Agent 分发列表里**没有 DesireCore**，装到 DesireCore 的路径无人覆盖 |
-| **纪律** | 钉钉 CLI 有 339 个「自己不拦」的写操作（占全部写操作 56%），由助手把关 |
-| **编排** | 跨产品工作流；官方 SKILL.md 明写「定时调度由外层工作流负责」 |
-| **降级** | 没装 / 没授权 / 没权限 / 没开通时如实停下，**绝不编造成功** |
-
----
-
-## 快速开始
-
-### 1. 安装钉钉官方 CLI
-
-```bash
-npm i -g dingtalk-workspace-cli
-```
-
-⚠️ 这一步会顺带往你机器上**其它 AI 编程工具的技能目录**写入钉钉技能（`~/.claude/skills/`、`~/.cursor/skills/` 等，共 80+ 个框架）。这是上游 `dws` 的 postinstall 行为，不是 DesireCore 做的。
-
-### 2. 把官方产品技能装进 DesireCore
-
-装完 CLI 后技能已解包在 `~/.dws/skills/multi/`，拷进 DesireCore 全局技能目录：
-
-```bash
-DC_ROOT="${DESIRECORE_TEST_ROOT:-${DESIRECORE_HOME:-$HOME/.desirecore}}"
-mkdir -p "$DC_ROOT/skills"
-cp -R ~/.dws/skills/multi/dingtalk-* "$DC_ROOT/skills/"
-```
-
-共 14 个：`aisearch` `aitable` `calendar` `chat` `contact` `doc` `drive` `event` `mail` `minutes` `misc` `shared` `todo` `wiki`。
-
-> **为什么不走市场安装**：市场里有 `dingtalk-cli` 条目，但钉钉官方仓库未公开（HTTP 404），客户端按 git 源拉不到内容。该条目的作用是**让你在市场里发现这个能力并看到装法**，不是分发通道。
->
-> **代价**：这样装的技能没有 provenance 记录，市场同步视为孤儿——既不自动更新也不自动卸载。**每次 `dws upgrade` 后要重跑一次上面的拷贝。**
-
-### 3. 授权
-
-```bash
-dws auth login              # 本机有浏览器
-dws auth login --device     # 无浏览器 / SSH / 容器，出设备码
-```
-
-⚠️ **钉钉不支持账号密码登录**，也不支持手机验证码、纯应用凭证。只有 OAuth 回环、设备流、`--token`、自有应用 OAuth 四种。
-
-授权成功后 access token 约 2 小时、refresh token 约 30 天自动刷新，之后无需再打扰。
-
-### 4. 把 `dws` 加进命令白名单（强烈建议）
-
-实测每条 `dws` 命令都会被判**高风险**并弹审批卡片——18 个测试用例里 34 次 Bash 调用触发了 **41 次审批**。不加白名单的话你要不停点确认。
-
-点输入框左下角的审批模式胶囊即可切换：
-
-![审批模式](assets/审批模式.png)
-
-六种模式的取舍：
-
-| 模式 | 行为 | 适合 |
-| --- | --- | --- |
-| **AI 审批**（默认） | 前台保留 30 秒真人抢先窗口，AI 建议到达即收敛 | 日常，但**需要配好审批 chat 模型** |
-| 完全 AI 审批 | AI 建议到达立即决策 | 无人值守 |
-| 仅 AI 建议 | AI 只提供参考，永不自动决策，**无截止时间等待真人** | 高风险场景 |
-| 每次确认 | 每次执行命令都要你审批 | 最保守 |
-| **白名单** | 仅白名单中的命令可自动执行 | **推荐**：把 `dws` 加进去 |
-| 外部工具审批 | 交给外部系统裁决 | 有审批中台时 |
-
-⚠️ **默认的「AI 审批」需要一个可用的审批 chat 模型。** 没配的话所有命令会被 fail-closed 拦掉，报「AI 审批后端不可用，命令未执行」——连助手自己写计划文件都会被拦。要么去资源管理面板 → 算力配一个 chat 模型，要么换成「白名单」或「每次确认」。
-
-### 5. 自检
-
-```bash
-dws doctor
-```
-
-四项：登录状态 / 钥匙串 / 网络连通性 / 版本更新。
-
----
-
-## 功能文档
-
-| 文档 | 覆盖 |
-| --- | --- |
-| [通讯录与找人](功能/通讯录与找人.md) | 精确查询 vs 语义搜索的分界、多候选处理 |
-| [群聊与消息](功能/群聊与消息.md) | 发消息、撤回、机器人、会话分组；**消息搜索需单独权益** |
-| [日程与会议](功能/日程与会议.md) | 日程、会议室、闲忙；**视频会议无 CLI 入口** |
-| [待办与审批](功能/待办与审批.md) | 待办增删改查、指派；OA 审批查询与处理 |
-| [文档与表格](功能/文档与表格.md) | 在线文档、电子表格、AI 多维表的边界与导出 |
-| [钉盘与知识库](功能/钉盘与知识库.md) | 存储层 vs 内容层的判据 |
-| [邮件](功能/邮件.md) | 收发、搜索、附件 |
-| [AI 听记](功能/AI听记.md) | 摘要、逐字稿、行动项 |
-| [考勤与日志](功能/考勤与日志.md) | 打卡、排班；日志模板填报 |
-| [实时事件](功能/实时事件.md) | 长连接监听；**禁止轮询** |
-| [跨产品工作流](功能/跨产品工作流.md) | 晨间简报、会议闭环、逾期巡检、周报、归档 |
-| [故障排查](故障排查.md) | 错误分诊表 |
-
----
-
-## 安全边界
-
-这个助手继承了钉钉官方的执行契约，并补了 DesireCore 侧的一层：
-
-- **只走 `dws`**，不用 curl、不自拼 HTTP
-- **不编造标识符**——userId / docId / baseId 一律从命令返回中提取
-- **写操作先确认**，判据是 `effect == destructive || risk == high || confirmation == user_required` 三元组兜底（**不能只看 `confirmation` 字段**：1256 个工具里有 339 个是 dws 自己不拦的 silent-write）
-- **单次批量 ≤ 30 条**
-- **多候选禁止默认取第一个**；多组织时解析、读取、执行必须用同一个 profile
-- **退出码不等于成功**——只有 `data.complete=true` 才能说「全部」，响应里缺少集合不能当空结果
-- **禁止轮询**消息历史或审批列表，实时需求走长连接
-
----
-
-## 已知边界
-
-| 限制 | 说明 |
-| --- | --- |
-| 视频会议 | **CLI 无入口**。会前（排日程订会议室）与会后（纪要/逐字稿/行动项）可用，会中控制需在钉钉客户端操作 |
-| 消息搜索 | 需要**消息搜索权益**，未开通时返回 `SearchRightsDenied`。其余 chat 能力（发消息、群管理、机器人）不受影响 |
-| 组织权限 | 能力覆盖取决于 OAuth 授权范围与你所在组织开通的产品，助手会在受限时如实说明 |

agents/dingtalk-workspace/skills/dingtalk-guide/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: dingtalk-guide
+description: >-
+  钉钉能力覆盖与边界查询。Use when 用户问某个钉钉产品「怎么用 / 支不支持 / 能不能做 /
+  有什么限制 / 为什么不行」，或需要按产品域查功能覆盖、权益门槛、已知边界（如「钉盘同步怎么用」
+  「消息搜索为什么返回受限」「视频会议能做到哪一步」「为什么每条命令都要审批」）。也用于 dws
+  报错后的分诊。本技能只回答「能力与边界」，不执行钉钉业务操作——具体命令走 dingtalk-* 官方技能，
+  安装与自检走 dingtalk-onboarding，跨产品编排走 dingtalk-workflows。
+metadata:
+  category: reference
+  requires:
+    tools: [Read]
+---
+
+# 钉钉能力说明查询
+
+本技能不含答案正文，只含**索引**。回答前先 Read 下表中匹配的参考文件，按文件内容作答；
+不要凭记忆回答产品边界与权益门槛——这些随钉钉侧开通状态变化，写死会误导用户。
+
+## 使用方式
+
+1. 从用户问题里识别产品域，在下表定位文件
+2. `Read` 该文件的绝对路径（`${SKILL_DIR}` 会被替换成本技能目录）
+3. 按文件内容作答；文件没覆盖的，如实说不确定，并给出 `dws schema` 的自查方式
+4. 命中多个产品域时按需读多个文件，不要只读第一个
+
+## 参考文件索引
+
+| 问题涉及 | Read 这个文件 |
+| --- | --- |
+| 找人、通讯录、语义搜索、多候选 | `${SKILL_DIR}/references/通讯录与找人.md` |
+| 发消息、撤回、群管理、机器人、**消息搜索权益** | `${SKILL_DIR}/references/群聊与消息.md` |
+| 日程、会议室、闲忙、**视频会议边界** | `${SKILL_DIR}/references/日程与会议.md` |
+| 待办、TODO、OA 审批查询与处理 | `${SKILL_DIR}/references/待办与审批.md` |
+| 在线文档、电子表格、AI 多维表、导出 | `${SKILL_DIR}/references/文档与表格.md` |
+| 钉盘、知识库、文件与节点的分界 | `${SKILL_DIR}/references/钉盘与知识库.md` |
+| 邮件收发、搜索、附件 | `${SKILL_DIR}/references/邮件.md` |
+| AI 听记、摘要、逐字稿、行动项 | `${SKILL_DIR}/references/AI听记.md` |
+| 考勤打卡、排班、日志日报周报 | `${SKILL_DIR}/references/考勤与日志.md` |
+| 实时事件、长连接、**为什么禁止轮询** | `${SKILL_DIR}/references/实时事件.md` |
+| 跨产品工作流、晨间简报、会议闭环、周报 | `${SKILL_DIR}/references/跨产品工作流.md` |
+| 审批闸门、审批模式、命令一直被拦 | `${SKILL_DIR}/references/界面与审批.md` |
+| 报错分诊、`dws` 命令失败 | `${SKILL_DIR}/references/故障排查.md` |
+
+## 边界
+
+- 本技能**不执行**任何钉钉命令。用户确认要做某件事时，交回对应的 `dingtalk-*` 官方技能
+- 命令目录（有哪些命令、参数是什么）不在这些文件里，也不该写进来——那由 `dws schema`
+  与官方技能提供，随二进制升级变化。这里只写**能力覆盖、边界与权益门槛**
+- 参考文件里的结论若与 `dws schema` 实际输出冲突，以 schema 为准，并如实告知用户文档可能滞后

agents/dingtalk-workspace/skills/dingtalk-guide/references/界面与审批.md

@@ -0,0 +1,53 @@
+# 界面表现与审批闸门
+
+用户问「为什么每条命令都要我点确认」「这个审批模式该选哪个」「怎么关掉」时读这篇。
+
+---
+
+## 一次真实对话长什么样
+
+![审批闸门与命令执行](assets/审批与执行.png)
+
+上图是问「我这边有哪些可用的机器人？」的完整过程。三件事值得注意：
+
+1. **每条 `dws` 命令都过审批闸门**，标注风险等级，用户可以逐条批准或拒绝
+2. **先查 schema 再执行** —— 前两条是 `dws schema --cli-path ...` 确认命令结构与参数，第三条才真正执行
+3. **答案带着依据** —— 「开放平台应用列表为空，**且分页已完整结束**」。只有确认分页走到底才敢说「没有」，不会让用户被一个假的空结果误导
+
+---
+
+## 为什么每条命令都触发审批
+
+实测每条 `dws` 命令都会被判**高风险**并弹审批卡片——18 个测试用例里 34 次 Bash 调用触发了 **41 次审批**。这不是配置错误，是默认行为。
+
+出路是把 `dws` 加进命令白名单，而不是降低风险判定。
+
+---
+
+## 六种审批模式
+
+点输入框左下角的审批模式胶囊即可切换：
+
+![审批模式](assets/审批模式.png)
+
+| 模式 | 行为 | 适合 |
+| --- | --- | --- |
+| **AI 审批**（默认） | 前台保留 30 秒真人抢先窗口，AI 建议到达即收敛 | 日常，但**需要配好审批 chat 模型** |
+| 完全 AI 审批 | AI 建议到达立即决策 | 无人值守 |
+| 仅 AI 建议 | AI 只提供参考，永不自动决策，**无截止时间等待真人** | 高风险场景 |
+| 每次确认 | 每次执行命令都要用户审批 | 最保守 |
+| **白名单** | 仅白名单中的命令可自动执行 | **推荐**：把 `dws` 加进去 |
+| 外部工具审批 | 交给外部系统裁决 | 有审批中台时 |
+
+---
+
+## 最常见的踩坑：默认模式需要审批模型
+
+**默认的「AI 审批」需要一个可用的审批 chat 模型。** 没配的话所有命令会被 fail-closed 拦掉，报「AI 审批后端不可用，命令未执行」——连助手自己写计划文件都会被拦。
+
+两条出路：
+
+- 去资源管理面板 → 算力，配一个 chat 模型
+- 或换成「白名单」/「每次确认」
+
+用户报「命令一直执行不了 / 一直说后端不可用」时，先问这一条。

manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "DesireCore Official Market",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "schemaVersion": "1.1.0",
   "supportedLocales": [
     "zh-CN",