# dsh-ob-agent 使用文档

统一管理 DSH 的 Agent 类工具：聊天框总开关、角色条目、每会话勾选，以及模型自助创建角色。

- 当前插件：**0.3.0**。
- 本版变更（全局子代理模型）：[0.3.0 升级说明](<v0.3.0.md>)。
- 上一版变更与团队切换：[0.2.0 升级说明](<v0.2.0.md>)。
- 当前验证宿主：**DSH 0.2.1-rc.2**。
- 模型工具说明：[model-guide.md](<model-guide.md>)。
- 本次迁移与验证记录：[DSH 0.2.1 兼容说明](<dsh-0.2.1-compatibility.md>)。

## 1. 升级变化

### 1.1 全局子代理模型（0.3.0）

设置页「全局」卡片新增**全局子代理模型**下拉：一次选择本插件装配的所有子代理默认使用的
provider / model / 思考档位。模型清单读取 DSH 自己的模型设置（`remote.session.modelCatalog()`），
与条目级下拉同源，不需要在插件里重复维护模型列表。

优先级固定为「条目钉死 > 全局设置 > 继承主会话」：

- 条目里单独钉死模型的角色继续使用自己的路由（固定角色可复现）；
- 未钉死模型的条目使用全局设置；
- 全局选择「继承主会话模型」时行为与本版之前完全一致（跟随会话当前模型）。

系统提示与 `agent_list` 会显示每条子代理实际使用的路由（含「全局默认」标记），
避免模型误以为自己仍在继承主会话。全局设置只影响本插件装配的子代理；DSH 原生工具条目的
模型仍由 DSH 自己的设置决定。

### 1.2 新版宿主接口

DSH 的 `dsh-tool-subagent.apply()` 已改为异步，并拒绝旧 `persona` / `toolFilter` 字段。
0.1.9 不再发送这些字段，也不发送已退役的 `backgroundMode` / `enableRunInBackground`。

为保留条目的身份与权限，本插件在公开 `startActivation()` 边界预留带命名空间的子代理 ID，
先保存不可变策略快照，再在宿主串行等待的 `agent/created` 阶段装配身份和工具守卫。
不复制 Agent Preset，不创建替代 provider，不修改 DSH 的内部注册表。

### 1.3 移除一次性模式

**按用户要求，插件跟随当前 DSH 移除新建一次性子代理，不模拟一次性生命周期。**

- 设置页不再显示一次性选项或双模式复选框。
- 新建条目固定为 `continuable`，工具名统一为 `subagent_<id>_session`。
- 旧 `one-shot` 或双模式条目读取后自动归一为 `['continuable']`。
- 角色 ID、身份、模型、权限、默认勾选及会话选择保留；不会为了迁移恢复出厂。
- `agent_create` / `agent_update` 显式传入 `one-shot` 会收到中文拒绝。
- 老工具名不再提供别名。例如旧 `subagent_code_review` 改为 `subagent_code_review_session`；
  已开始的会话中模型若记住旧名字，应以新一轮工具清单为准。
- 历史 descriptor 的 `one-shot` 读取仅用于识别旧会话，避免给历史一次性会话提供无效回发通道。

所有新委派都立即返回持久子代理 ID，完成后由宿主通知；用 `send_message` 继续原子代理，
用 `interrupt_agent` 请求中止。没有 `run_in_background` 参数，也不返回用于收集委派结果的 job ID。

## 2. 安装与生效

本插件暂无 npm 发布包，使用本地构建依赖：

```powershell
# 在插件源码目录
npm install --legacy-peer-deps
npm run check

# 安装到已有 web profile（不会启动替代服务器）
dsh plugin --profile web add file:C:/Users/17737/Code/other/DSH/plugins/dsh-OB-agent
```

路径按实际 checkout 调整。更新前备份 profile 的配置、依赖清单和锁文件。
曾从 profile 禁用插件的用户，应从备份恢复**仅本插件的 id 级配置段**，不要覆盖整个 profile。

**安装/源码更新后需要重启原 DSH 进程，再在现有 GUI 刷新页面。**
`npm run build` 只以源码目录的 `lib/` 为目标；普通独立副本需要重新安装/同步。本机本次安装创建了 hardlink，已核对哈希一致，但不能据此假定其他环境也会自动更新。
不要用另起一个 Web 服务来代替更新原 GUI，也不承诺安全策略可通过热卸载无缝切换。

### 2.1 策略快照与备份

默认位置：

```text
$DSH_HOME/plugins/dsh-ob-agent/child-policies/
# DSH_HOME 未设置时：~/.dsh/plugins/dsh-ob-agent/child-policies/
```

高级设置可通过启动环境变量 `DSH_OB_AGENT_POLICY_DIR` 指定独立目录。
目录应位于可靠的本地存储，由当前 DSH 用户读写，不要存放在待审查项目工作目录中。

- 一个受管子代理一份不可覆盖的 JSON 快照，绑定子代理 ID、父会话 ID、身份和白名单。
- 文件可能含用户撰写的身份提示词，按配置数据保密；不要把密钥写入角色提示词。
- 创建失败可能留下孤立快照；本版不自动清理，避免删掉仍需冷恢复的策略。
- **备份/迁移会话时同时备份此目录。** 不要仅复制会话日志后删除策略目录。
- 插件命名空间 `obagent-<UUID>` 的策略缺失、损坏、版本未知或父子身份不符时，拒绝启动/冷恢复，
  不会默认为完全权限。原生非命名空间子代理不受此校验影响。
- 已启动子代理继续使用创建时的快照；设置页改权限只影响之后新建的子代理。
- 这是工具执行策略，不是能抵御本机全权限进程修改配置的 OS 安全隔离。

## 3. 界面

### 3.1 聊天框「子代理」条

输入框上方的总开关按会话保存：关闭后继承面的 Agent 工具隐藏，残留自有层工具也被守卫拒绝。
打开后只放行已勾选的条目，同时把「何时调用」写入系统提示。

出厂有 8 条：代码审查、通用子代理、Agent 自助管理，以及折叠的 5 条 DSH 原生工具。
原生分组默认收起，不能因为收起而绕过总开关。

「代码审查」默认按**代码编写阶段**触发：同一批改动（一个功能、一次重构、一处修复）全部写完后
统一审查一次，不逐文件触发；任务包含多个独立阶段时每个阶段各审一次。时机文案可在设置页
条目里改，已保存的设置会随出厂版本迁移到新文案（模型、权限与会话勾选保留）。

### 3.2 设置页

- 全局：全局子代理模型、新会话总开关默认值、续话工具自动放行、子代理回发、只读工具白名单、提示词变量。
- 条目：名称、描述、调用时机、身份提示词、spawn/fork、模型/思考档位、权限、默认勾选及纳管状态。
  条目级模型优先于全局子代理模型；条目未钉死模型时，界面会显示它跟随的全局路由。
- 运行模式：固定可继续对话。
- 自助管理：模型创建/修改权限、可修改范围和条目上限。
- 高级闸门：名称前缀、精确工具名、豁免名单及逃生舱。
- 恢复出厂需确认，会重置可编辑全局/条目；不会重置会话选择。

提示词变量必须严格写为 `{{cwd}}` / `{{model}}` 这类已注册的小写变量。
`{{ cwd }}`、未知变量等会在校验时被拒；不确定当前 preset 是否注册变量时，请不使用变量。

## 4. 权限与工具语义

### 4.1 闸门三层

1. `tools.restrict({ deny })`：隐藏不允许的继承工具。
2. `tools.guard()`：执行层单调拒绝，包括本作用域自有工具。
3. 作用域重挂：调用新版原生实现包装配所选工具；异步拒绝被等待、记录并释放失败装配。

工具枚举使用 `tools.schemas(agent)` / `tools.get(name, agent)`；scope 是 Agent 本身，不是 `agent.ctx`。
只根据实际装配结果宣传能力；缺包、缺 provider、缺服务时不把不存在的名字列给模型。
provider 晚就绪或重新注册会触发重算。

### 4.2 只读权限

基础白名单与父会话当前可见工具求交集，交集为空则条目不可用，不降级为完全权限。
默认文件工具为 `read / read_image / glob / grep`。
若允许子代理回发，额外保留 `send_message`，且只允许发给快照绑定的直接父代理。

子代理首次请求前安装白名单隐藏和执行层守卫。自有层工具、新增 MCP 工具或之后注册的写工具，
即使仍能出现在清单中，也不能绕过守卫。`run_code` 传输工具不能加入白名单。
不要把可执行任意命令或写操作的工具加入「只读」白名单，否则该自定义授权本身就不再是只读。

### 4.3 子代理回发

子代理不再委派、不装配工作流或 Ralph。默认只允许 `send_message` 向直接父代理回发进度或问题。
关闭回发开关后，不再装配此通道。历史一次性 descriptor 不放行回发。

### 4.4 模型自助管理

`agent_create / agent_update / agent_list` 默认只能改模型自建条目，内置和用户条目只读。
写入统一过校验并留审计日志，新工具在下一轮模型请求可见。

### 4.5 原生工具三档

- 已存在：直接放行，不重复注册。
- 当前 preset 没提供但实现包可用：在 Agent 作用域重挂。
- 缺实现/provider/workflowEngine 或白名单为空：本会话不可用并记录中文原因。

### 4.6 自有层边界

DSH restriction 只限制继承面，不能隐藏提供方注册在 Agent 自有层的名字。
因此总开关关闭时，某些宿主组合的原生 `subagent` 可能仍显示，但必须被执行层守卫拒绝。
不要通过修改请求快照或私有登记表伪装隐藏成功，也不要为了一个残留名字反复重装限制形成循环。

### 4.7 全局子代理模型

设置页「全局」卡片的全局子代理模型写入设置段的 `subagentModel` 字段：

- 形状为 `{ provider, model, reasoningEffort? }`；provider / model 必须成对且非空，
  半填状态在保存前被校验拒绝。
- 缺省或 `null` = 继承主会话模型（与旧版本行为一致）。
- 生效方式是把它作为**条目未钉死模型时**的 `agentOptions` 传给
  `@deepseek-ai/dsh-tool-subagent`；条目自己钉死的模型优先，不会被全局设置覆盖。
- 模型清单来自 DSH 的 `modelCatalog`；清单读取失败时设置页降级为手填 provider / model，
  仍可保存，但插件不校验该路由是否存在——真实可用性由 DSH 在启动子代理时预检。
- 只影响本插件装配的子代理（`spawn` / `fork` 条目）。DSH 原生工具条目（`workflow`、
  `ralph`、原生具名子代理等）的模型由 DSH 自己的设置决定，本插件不代为改写。
- 全局设置属于用户配置，`agent_create` / `agent_update` 只读写条目级模型，不能修改它。

## 5. 验收与开发

```powershell
npm run typecheck
npm test -- tests/implement.spec.ts tests/subagent-compat.spec.ts
# 指向正在验证的真实宿主，而不是旧缓存：
$env:DSH_PROFILE_NODE_MODULES = 'C:\path\to\current-dsh\node_modules'
npm test -- tests/dsh-compat.spec.ts
npm run check
```

真实运行时测试覆盖原生异步 apply、旧字段拒绝、spawn/fork 的 activation 路径、真实作用域的
身份覆盖、工具隐藏和新注册工具守卫。使用服务桩避免付费模型调用，不等于实机模型往返验收。
普通 CI 没有宿主时真实接口组会明确跳过，不能把跳过当兼容通过。

重启原 GUI 后验收：面板和设置页出现；旧一次性条目变为可继续；总开关开关生效；
勾选角色后出现 `_session` 工具；返回 ID、完成通知、续话/回发/中止正常；只读子代理不能写文件或跑命令。
本次不会为了测试真实写操作而修改用户业务文件。

## 6. 排障与范围

| 现象 | 处理 |
| --- | --- |
| `persona is no longer supported` | 安装副本仍是旧版，核对版本和构建哈希，更新后重启原 DSH。 |
| 旧 `subagent_<id>` unknown tool | 该一次性工具已移除，使用当前清单中的 `subagent_<id>_session`。 |
| 策略缺失/损坏导致恢复拒绝 | 从同一会话的备份恢复相应策略文件；不要改成完全权限或生成空白策略绕过。 |
| 条目/全局模型路由不可用 | 在设置页选实际存在的 provider/model，或清空条目模型以跟随全局、清空全局以继承主会话；插件不擅自替换用户模型。 |
| 子代理跑在非预期模型上 | 先看条目是否钉死了模型（条目优先于全局），再看全局子代理模型；`agent_list` 会显示实际路由。 |
| 面板不显示/设置页空白 | 核对安装副本、宿主 UI 版本、客户端加载日志；重启后刷新。 |
| 某工具可见却拒绝 | 先查总开关、勾选及子代理限制，再区分自有层无法隐藏的边界。 |
| `workflow` 不可用 | 当前 preset 需提供 `@deepseek-ai/dsh-workflow` 的 workflowEngine。 |

其他插件的 `webRuntime` 等错误不是本插件能修复的，本次只处理 `dsh-ob-agent`，不改其他插件。