# dsh-subagents

**面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）的聚焦子代理委派与多代理工作流。**

> 这是 [`pi-subagents`](https://github.com/nicobailon/pi-subagents) 的忠实移植版，重建在 DSH **原生**的 `subagent` / `subagent_fork` / `workflow` 工具之上 —— 既得到精心设计的角色与工作流，又保留 DSH 内置的委派能力。

- [English](README.md)

## 为什么需要它

DSH 已经内置委派（`subagent`、`subagent_fork`、`workflow`、`agent_teams`）和按需加载的技能系统，但**没有**现成的「该委派给谁、如何串起来」这一套。

`dsh-subagents` 补上的正是这块：

| 需求 | 你得到的 |
| --- | --- |
| 动手前多一双眼睛 | `reviewer` 角色：P0/P1/P2 结论 + 合入判定 |
| 高风险决策前的把脉 | `oracle` 角色：只挑战假设、不改文件 |
| 快速摸清陌生代码 | `scout` 角色：入口、数据流、风险 |
| 可信的外部事实 | `researcher` 角色：带来源的调研简报 |
| 谨慎的实现者 | `worker` 角色：最小改动、未决事项上报而非猜测 |
| 编排审查/实现循环 | `parallel-review`、`review-loop`、`council`、`parallel-research`、`parallel-cleanup`、`gather-context` 工作流 |

**解决什么问题：** 不用手写提示词、不用记各角色的工具白名单、不用重造审查循环。装一次，说一句「用 reviewer 审查这个 diff」就能得到有纪律的审查。

**有何不同：** 它不是一个新的 agent 运行时，而是一层薄薄的、几乎零依赖的技能层（纯 ESM、零运行时依赖），教模型怎么用 DSH 自己的工具，因此能和你 profile 里的一切（AgentTeams、MCP 服务器、技能、主题）共存。

## 安装

```bash
dsh plugin --profile web add dsh-subagents
# 或本地目录：
dsh plugin --profile web add /path/to/dsh-subagents
```

重启 dsh 进程即生效 —— 无需配置、无需斜杠命令。

## 先试这个

- “用 reviewer 审查一下这个 diff。”
- “让 oracle 对我的当前计划给个第二意见。”
- “用 scout 理解一下这段代码。”
- “并行跑几个 reviewer：一个看正确性、一个看测试、一个看简洁性。”

模型会加载对应的 `subagents-*` 技能并用原生工具委派。你无需创建 agent、写配置或记命令。

## 内置角色

| 角色 | 适用场景 |
| --- | --- |
| `scout` | 快速代码库侦察：相关文件、入口、数据流、风险。 |
| `researcher` | 带来源的网络/文档调研，产出精简简报。 |
| `worker` | 实现工作：改文件、验证，未经批准的决策上报而非猜测。 |
| `reviewer` | 带 P0/P1/P2 结论与合入判定的代码/方案审查。 |
| `oracle` | 行动前的第二意见；只挑战假设、不改文件。 |
| `delegate` | 贴近父会话的轻量通用委派。 |

## 工作流

| 想要 | 技能 |
| --- | --- |
| 辩论一个重大决策 | `subagents-council` —— 有边界、父会话主持的顾问委员会 |
| 对抗式审查 diff | `subagents-parallel-review` —— 多个全新上下文 reviewer、各负责一个角度 |
| 实现 → 审查 → 修复直到干净 | `subagents-review-loop` —— 默认最多 3 轮 |
| 得出有据可依的多角度答案 | `subagents-parallel-research` —— researcher + scout |
| 清理 AI 陈词滥调 / 啰嗦 | `subagents-parallel-cleanup` —— deslop + verbosity 两道审查 |
| 先收集上下文再澄清 | `subagents-gather-context` —— scout/researcher，然后向用户提问 |

## 与 DSH 的映射

| pi-subagents | dsh-subagents / DSH |
| --- | --- |
| `subagent` 工具 | `subagent`（全新上下文）/ `subagent_fork`（继承对话） |
| `workflowScript` | `workflow` |
| 多代理团队 | `agent_teams`（原生） |
| 内置 agent（`.md` frontmatter） | 技能 `subagents-scout`、`subagents-reviewer` 等 |
| prompt 快捷方式 | 技能 `subagents-council`、`subagents-parallel-review` 等 |
| `context: fresh` / `fork` | `subagent` / `subagent_fork` |
| async / background | `run_in_background: true` + `job_output` / `job_kill` |
| `subagent({action:"list"})` | `list_agents`（子代理）+ 技能目录 |

> **角色说明：** DSH 的 `subagent` 工具把 persona/工具白名单固定在配置层，而非每次调用。因此这里的角色切换是「提示词驱动」的：每个角色都是一个技能，把其 persona 文本写进子代理的 `prompt`。要做到每角色的硬工具隔离，需要 DSH 的 agent-preset 组合层 —— 见[限制](#限制)。

## 目录结构

```
lib/index.js        宿主插件 —— 注册技能 + 用法说明
skills/*.md         各角色与工作流的正文
cordis.patch.yml    把插件挂载到 profile 的宿主组合
```

## 环境要求

- Node ≥ 20（ESM）。
- profile 的基础 bundle 挂载了 `skills` 与 `systemPrompt`（标准 profile 默认具备）。

## 限制

- 角色 persona 是**软**约束：子代理继承 DSH 的工具集，并按 persona 里的工具指引自我约束，没有「每次调用的工具白名单」强制。
- `council` 的交叉质询用的是「全新重新发起」而非续跑同一个子代理，因为 DSH 的一次性子代理不可续跑（需要续跑时可用 `subagent_fork` + `send_message`）。

## 贡献

欢迎提 Bug 和 PR。开始非平凡工作前，请先开一个 [issue](https://github.com/geekyfoxlab/dsh-subagents/issues)。本项目无构建步骤 —— 插件是纯 ESM，`node --check lib/index.js` 加一次 mock `apply()` 就是冒烟测试。

## 许可证

[MIT](LICENSE)。移植自 [pi-subagents](https://github.com/nicobailon/pi-subagents)（MIT，© Nico Bailon）。