# dsh-ob-agent 模型使用手册

> 这份文档是写给**模型**看的：它描述你在本部署里能用哪些 Agent 能力、工具的确切契约、
> 以及创建 Agent 时的写法规范。用户侧的说明见 `USAGE.md`。

> 版本 0.3.0 / DSH 0.2.1-rc.2：所有新建子代理均可继续对话；旧一次性工具已移除。关闭总开关后禁止沿用历史工具调用；团队模式下本插件交还管理权，以官方团队的工具清单和提示为准。
> 子代理实际使用的模型由用户配置：条目钉死的路由优先，其次是用户的全局子代理模型，都没有时继承主会话；系统提示与 `agent_list` 会给出每条子代理的实际路由。
>
> `agent_update` 仅 `id` 必填，其余省略保持原值（含模型/档位）。设置模型时 `modelProvider` 和 `model` 必须成对；可选 `reasoningEffort` 指定档位，空串清除档位。切换路由未给档位时不继承旧档位。`inheritModel: true` 显式恢复 DSH 继承，与路由和档位参数互斥。`enableNow: true` 创建/更新时补勾选，不开启总开关；`false` 不改变已有勾选。

## 1. 这个插件做了什么

本部署把 DSH 里**全部 agent 类工具**（委派、子代理续话、工作流、Ralph、以及自助管理）
收口到插件 `dsh-ob-agent` 统一管理。对你的直接影响有两条：

1. **总开关**：聊天框「子代理」条上的开关由用户控制。**关闭时你完全不能使用任何
   命中闸门的 agent 类工具**——继承工具会从清单隐藏，提供方自有层工具可能仍会显示，
   但调用一样被拒绝。这不是故障，是用户的选择：请正常完成当前任务，需要委派时用一句话
   说明「需要用户打开子代理总开关」。
2. **按条目勾选**：开关打开后，只有被勾选的条目对应的工具才被放行。以本部署系统提示里
   「本会话已启用以下 Agent 能力」一段和执行层授权为准，**不要调用清单里没有的工具名，
   也不要把清单里的残留名字当成已授权能力**。当前原生 `subagent` 的自有层边界见
   [使用文档 4.6](<USAGE.md#46-自有层边界>)。

系统提示里每个条目都带这些信息：工具名、模式/权限/上下文、**实际模型路由**，以及
**何时调用**（`whenPrompt`）。`whenPrompt` 由用户或你自己撰写，是本部署对调用时机的
权威说明；模型路由中的「全局默认」表示用户设置了全局子代理模型，「继承 DSH 主会话」表示
子代理跟随会话当前模型。不要假设子代理一定跑在与会话相同的模型上。

## 2. 你能用的工具

| 工具 | 来源 | 契约 |
| --- | --- | --- |
| `subagent_<id>_session` | 条目 `id` + 可继续对话模式 | 参数为 `description`、`prompt`、可选 `cwd`。立即返回**持久子代理 id**，完成后宿主通知；之后用 `send_message` 续话、`interrupt_agent` 中止。没有 `run_in_background` 参数或委派 job id。 |
| `send_message` / `interrupt_agent` | 原生控制工具 | 需要「子代理续话与中止」条目被勾选（勾选可继续对话的子代理时通常会自动放行）。`send_message` 在可继续对话的子代理内部也默认可用，但那里它只能发给自己的直接父代理。 |
| `list_agents` | 原生清单工具（本插件补了能力清单） | 查看当前会话有哪些子代理。结果分两段：**已启用的子代理工具**（能力清单，含工具名/模式/权限/模型）与**子代理实例**（仅「可继续对话」的实例会保留，含 id 与状态）。实例为空**不等于**没有子代理可用——新会话没有任何实例；回答「有几个子代理」时必须看能力清单。清单只列**本次真的装配成功**的工具：条目声明了、但当前会话预设没有提供的名字（例如某个具名子代理）不会出现，因此清单里的名字可以直接调用。 |
| `workflow` | DSH 工作流编排 | 脚本化扇出/分阶段；只在需要大量独立子任务时使用。 |
| `ralph` | DSH 深度迭代 | 只有用户明确要求「Ralph / 无人值守多轮推进」时才用。 |
| `agent_create` / `agent_update` / `agent_list` | 本插件 | 见第 3、4 节。 |

**并行**：相互独立的 agent 任务应在**同一条助手回复里同时发起调用**，不要串行等待。
需要子代理结果时等待宿主完成通知，不要重复派发同一任务。

**子代理看不到你的对话**：它只能看到你在 `prompt` 里写的内容（`fork` 后端例外，它继承
本会话已完成轮次）。任务说明必须自包含。

**子代理可以回发给你（仅限可继续对话的子代理）**：在默认设置下，可继续对话的子代理内部
会拿到一个 `send_message`，用于向它的**直接父代理**（也就是你）回发进度、追问或方向性
变更；系统提示里会给出你的会话 id。上游默认还会要求子代理在结束前把结果回发给你（父代理看不到子代理的
对话、工具输出与推理）。子代理的回发是**消息**而不是工具结果：它不会打断你当前的回合，
你会在下一个合适的时机收到。委派时若希望它中途汇报，请在 `prompt` 里写明。

## 3. 什么时候该自建 Agent

先用 `agent_list` 查重，再决定：

**值得创建**（会反复出现、值得固化成固定角色）：

- 同类委派你已经做过至少两次，且每次都要重复交代同样的身份、边界与产出格式；
- 任务需要**固定的权限**（例如只读审查，绝不允许改代码）或**固定的模型**（例如审计必须
  用某个强模型）；
- 任务一旦跑起来就不需要你介入，且产出格式固定（报告、清单、结构化结果）。

**不要创建**：

- 一次性小任务——直接自己做，或用已有的通用子代理；
- 只是为了少写几句 prompt 的临时委派；
- 需要你频繁看中间结果再决定下一步的任务（那适合可继续对话的既有子代理，而不是新建角色）。

**创建后不会立刻可用**：新工具在**下一轮请求**才进入你的工具清单。不要在同一轮里调用
刚创建的工具；先向用户确认，或在下一轮再用。

## 4. 字段与写法规范

### 4.1 字段表

| 字段 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- |
| `id` | 是 | 2-24 位，小写字母开头，仅 `a-z0-9_`，全局唯一 | 派生工具名 `subagent_<id>_session`，创建后不要改 |
| `name` | 是 | ≤ 60 字符 | 界面显示名，出现在系统提示的启用清单里 |
| `whenPrompt` | 是 | ≤ 4000 字符 | ① 给**你**看的「何时调用」，进入每轮请求的系统提示 |
| `identityPrompt` | 是 | ≤ 4000 字符 | ② 给**子代理**看的身份提示词（persona），子代理看不到父会话，必须自包含 |
| `description` | 否 | ≤ 300 字符 | 界面展示用 |
| `modes` | 否 | 只接受 `["continuable"]`，默认同此值 | 一次性模式已移除；显式传入 `one-shot` 会被拒绝 |
| `provider` | 否 | `spawn`（默认，全新上下文）/ `fork`（继承本会话已完成轮次） | 无关任务用 `spawn`；需要延续讨论才用 `fork` |
| `permission` | 否 | `full`（默认）/ `readonly` | `readonly` 只给文件读取类工具，**不能运行命令**；实际生效白名单是它与该子代理真实可见工具的交集，交集为空则该条目不可用 |
| `readOnlyAllow` | 否 | 工具名数组 | 覆盖全局只读白名单；只在 `permission: readonly` 时生效 |
| `modelProvider` + `model` | 否 | 必须成对且非空；创建省略时跟随用户的全局子代理模型（未设置则继承主会话），更新省略时保持原值 | 钉死子代理模型路由，由 DSH 预检可用性 |
| `reasoningEffort` | 否 | 仅适用于固定路由；空串清除档位 | 同路由省略保持，换路由省略不沿用旧档位 |
| `inheritModel` | 否 | `true` 与路由/档位参数互斥 | 显式清除固定路由并恢复继承 |
| `defaultEnabled` | 否 | 默认 `false` | 新会话是否默认勾选（对当前会话无影响） |
| `enableNow` | 否 | 默认 `true`；`false` 不取消已有勾选 | 创建/更新时补入当前会话勾选；总开关仍由用户控制 |

上表的必填约束用于 `agent_create`；`agent_update` 仅 `id` 必填，省略字段保留原值。团队模式下本插件不提供这些管理工具；历史请求若调用写工具会被拒绝。

**提示词变量**：`whenPrompt` / `identityPrompt` 里可以写 `{{cwd}}`、`{{model}}` 等
**当前预设确实注册过的变量**（默认允许列表见系统提示或设置页）。两条硬约束：

1. 形式必须**严格**是 `{{小写名字}}`：不允许空格（`{{ cwd }}`）、不允许大写（`{{Cwd}}`）、
   不允许其它字符（`{{cwd-x}}`）。运行时的插值器只认这一种写法，其余一律抛错并**打断整个
   请求**，因此这类写法在写入时就会被拒绝。
2. 名字必须是当前会话装配里真实注册过的变量。不确定就不要写变量——写错的表现是整个请求
   失败，而不是这一句话失效。

### 4.2 `whenPrompt` 怎么写

它是你未来的决策依据，必须包含**正例与反例**：

```
用户明确要求审查时立即调用。没有明确要求时按「代码编写阶段」触发，不要每改一个文件就调用：
同一批相关改动（一个功能、一次重构、一处修复）全部写完后，统一审查一次。
阶段边界以「写完了没有」为准：该阶段要改的文件都已落盘、准备进入运行测试、构建或交付时再调用；
阶段内的反复编辑、增删文件与连续修补都算同一批，中途不触发。
不要推迟到整个任务结束：任务包含多个相互独立的实现阶段时，每个阶段各审一次；
纯问答与只读探索不调用，只改文档措辞且无行为变化时并入同阶段的审查、不单独触发。
一次工具调用同时修改多个文件按同一阶段处理，只审一次；只有相互独立的阶段才分别审查。
审查建议须自行核实，误报或收益低于修改成本的建议可以不采纳；
落实本次审查建议的修改属于同一阶段，默认不再复审。
只有修复引入新的、测试无法覆盖的高风险行为时才针对新风险额外聚焦复审一次；
后续独立阶段的新改动仍按上述规则触发，同一问题最多一次，不要循环审查。
```

反例（不要这样写）：`用于代码审查。` —— 没有时机、没有边界，等于没写。
也**不要**写「每改一个文件就立即审查」：那会把阶段内的正常编辑拆成多次审查，成本高且看不到整体改动。
出厂「代码审查」条目就是按阶段边界触发的，可作为参考。

### 4.3 `identityPrompt` 怎么写

它是子代理的 persona。子代理看不到你，因此必须自包含：**身份 + 边界 + 流程 + 产出格式 + 纪律**。

```
你是独立代码审查员，只看改动和必要上下文，不修改代码。
优先检查有现实影响的正确性、安全、数据完整性和兼容性问题；只报告有证据且值得修复的风险，
注明文件:行号、触发条件、影响和最小修复方向。疑点标明待验证，不为凑数提出风格建议。
没有值得修复的问题就直接说明；避免无关的全仓扫描、重复测试和无收益的复审要求。
```

**边界必须写死**：能改什么、绝对不能改什么、失败时怎么办（如实报告而不是自作主张）。

## 5. 权限与可用性

- `permission: readonly` 的子代理**只能读文件**：没有 shell、没有写文件、没有 MCP 工具
  的写能力。它适合审查、分析、调研。
- 若只读白名单与它真实可见的工具没有交集，该条目会在装配期被**停用**（不会降级为完全
  权限），你会在系统提示里看不到它。
- 子代理**不能再委派**：任何层级的委派与编排调用都会被拒绝；即使因上游自有层注册而看见
  原生 `subagent`，也不代表可以使用。唯一默认放行的 Agent 工具是可继续对话子代理向直接
  父代理回发的 `send_message`。不要设计「让子代理再开子代理」的方案，改成主代理分两轮做。

## 6. 常见错误与自愈

| 现象 | 原因 | 怎么办 |
| --- | --- | --- |
| 工具返回「已被用户关闭」 | 用户在设置里关掉了自助管理 | 停止创建，改为用已有条目；如确有必要，请用户开启 |
| 「标识已被占用」 | `id` 与现有条目冲突 | 先 `agent_list`，换一个语义清晰的 `id` |
| 「提示词变量 {{x}} 不在允许列表内」/「无法解析的变量引用」 | 用了未注册变量，或写法不规范（空格/大写/其它字符） | 去掉变量，或改成严格的 `{{小写名字}}` 并让用户把它加进允许列表 |
| 「不是模型创建的条目」 | 默认作用域只允许改你自建的条目 | 内置/用户条目只能由用户在设置页修改；必要时新建一个自己的条目 |
| 「条目总数已达上限」 | 超过用户设定的上限 | 请用户删除不用的条目，或复用已有条目 |
| 新建的工具调用不了 | 新工具下一轮才可见 | 本轮不要调用；或总开关未打开、条目未勾选 |
| 工具被拒绝：「…被 dsh-ob-agent 拦截」 | 总开关关闭或条目未勾选 | 说明需要用户开启并勾选，不要反复重试同一个调用 |

## 7. 生效与审计

- 条目的创建/修改会**立即写入设置**（无需重启），但**工具可见性在下一轮请求生效**。
- 每次创建/修改都会留下一条中文审计日志（`dsh-ob-agent 审计：…`），用户可以在日志与会话
  里看到你改了什么。不要试图绕过它。
- 设置页会把你创建的条目标为「模型自建」，用户可随时停用或删除。

## 8. 不要做的事

- 不要创建身份含混、边界不清的「万能子代理」；
- 不要把用户的隐私、凭据、密钥写进提示词（提示词会进入系统提示与子代理 persona）；
- 不要为了让某个工具出现而反复创建条目（先查重、先问用户）；
- 不要在总开关关闭时反复尝试调用 agent 类工具。