# 第 9 章：MCP、子代理与工作流

> 本章目标：了解 dsh 的三项扩展能力——MCP（接入外部工具）、子代理（并行任务）、工作流（多步编排）。**这些是把 dsh 从"单 Agent"升级为"Agent 系统"的开关。**

> ⚠️ 本章基于官方架构文档（`packages/AGENTS.md`）与包结构整理；部分功能示例标注「待实测」——rc 版本迭代快，具体用法以官方 changelog 为准。

## TL;DR（本章核心，30 秒版）

1. **MCP = 给 Agent 插外部工具**：通过 MCP 协议接入数据库、浏览器、公司内部系统等——先跑通内置工具，有明确缺口再加 MCP
2. **子代理 = 并行干活**：把任务委派给子 Agent 并行执行（大仓调研、长任务分解、独立验证）——先用好单 Agent 再上子代理
3. **工作流 = 确定性流程编排**：和"多轮对话"不同，工作流把步骤定义成流程按顺序/条件执行——适合数据拉取→清洗→报表→校验
4. **组合起来 = Agent 系统**：父 Agent 规划 → 子代理并行调研 → 工具链 + MCP → 工作流汇总 → 产物
5. **新手路径四阶段**：单 Agent + 内置工具 → + MCP → + 子代理 → + 工作流（逐步叠加，别跳级）

<details><summary>本章导航</summary>
- [9.1 MCP：接入外部工具生态](#91-mcp接入外部工具生态)
- [9.2 子代理（subagent）：并行干活](#92-子代理subagent并行干活)
- [9.3 工作流（workflow）：多步编排](#93-工作流workflow多步编排)
- [9.4 组合起来：一个"Agent 系统"长什么样](#94-组合起来一个agent-系统长什么样)
- [9.5 社区生态示例（2026-08-13 快照）](#95-社区生态示例2026-08-13-快照)
- [9.6 MCP 接入配置示例](#96-mcp-接入配置示例)
- [9.7 子代理配置示例](#97-子代理配置示例)
- [9.8 工作流 YAML 示例](#98-工作流-yaml-示例)
- [9.9 三者对比表](#99-三者对比表)
- [9.10 踩坑补充](#910-踩坑补充)
- [9.11 四阶段新手路径（含验收标准）](#911-四阶段新手路径含验收标准)
</details>

## 9.1 MCP：接入外部工具生态

**MCP（Model Context Protocol）**是"给 Agent 插外部工具"的开放协议。dsh 提供 `mcp` 客户端包（`@deepseek-ai/dsh-mcp-client`）。

**能做什么**：通过 MCP 接入任何 MCP 服务器（数据库、浏览器、图表、公司内部系统……）——比如社区已出现的 `dsh-plugin-cost-tracker`（追踪 token）就是 MCP/插件形态。

**新手定位**：MCP 是"生态扩展"，等你在 dsh 里有了明确的工具缺口再来接。先跑通内置工具，再加 MCP。

## 9.2 子代理（subagent）：并行干活

**是什么**：把任务委派给子 Agent 并行执行（`packages/subagent/*`）。

**典型场景**：
- 大仓库多模块调研（各模块一个子代理）
- 长任务分解（父代理规划，子代理执行）
- 独立验证（子代理交叉检查）

**对新手**：子代理是"高阶武器"——先用好单 Agent，理解任务分解后再上子代理。错误示范是"什么任务都开子代理"，反而增加协调开销。

**已知限制（社区反馈）**：当前**不能动态指定子代理模型**——子代理模型跟随父 Agent 配置，社区已在讨论区反馈（[#118](https://github.com/deepseek-ai/deepseek-harness/discussions/118) 评论区，对比 Claude Code"可指定子代理模型"的体验）。需要不同模型能力时，目前只能整体切换父 Agent 的模型配置，或拆成独立会话分别指定。

## 9.3 工作流（workflow）：多步编排

**是什么**：`packages/workflow/*` 提供多步工作流编排（worker-thread provider + tool Consumer）。

**和"多轮对话"的区别**：普通对话是"模型自由发挥"，工作流是"把步骤定义成流程，按顺序/条件执行"——适合**确定性流程**（如：拉取数据 → 清洗 → 生成报表 → 校验）。

**官方示例**（`packages/examples/`）：有可运行的 cordis.yml 工作流示例。

## 9.4 组合起来：一个"Agent 系统"长什么样

<!-- [style] 流程图代码块统一补 text 语言标签 -->
```text
你的提示词（目标）
  ↓
父 Agent（规划）
  ├── 子代理 A：调研模块 A（并行）
  ├── 子代理 B：调研模块 B（并行）
  └── 工具链：read/grep/bash + MCP（数据库）
  ↓
工作流（如：校验 → 汇总 → 输出报告）
  ↓
产物（可打开/追踪）
```

**新手路径建议**：
1. **阶段一**：单 Agent + 内置工具（第 2-5 章）
2. **阶段二**：+ MCP（接外部工具）
3. **阶段三**：+ 子代理（并行）
4. **阶段四**：+ 工作流（确定性流程）

## 9.5 社区生态示例（2026-08-13 快照）

官方 Discussion 里已出现的社区项目：
- `dsh-plugin-cost-tracker`——实时追踪 token 成本（插件/MCP 形态）
- 插件开发/提速类（如本白皮书第 4 章的示例提速插件）

生态正在快速生长——**现在是进场搭积木的好时候**。

## 9.6 MCP 接入配置示例

以下给出在 `cordis.patch.yml` 中挂载 MCP 客户端的**配置片段**（语法与第 3 章 3.2 节一致，以社区 token 追踪插件为例）：

```yaml
- insert:
    - id: mcp-client
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        servers:
          - name: cost-tracker
            command: npx
            args: ['-y', 'dsh-plugin-cost-tracker']
            env:
              DSH_API_KEY: '${DSH_API_KEY}'
```

**字段说明**：`id`（cordis 链标识）、`name`（npm 包名）、`config.servers`（服务器列表，每服务器独立进程）、`command`/`args`（启动命令与参数）、`env`（环境变量，支持 `${VAR}` 引用宿主变量）。

> ⚠️ 上述配置基于 `packages/mcp/` 目录结构与 cordis 挂载语法推断，具体字段以官方文档为准（rc 阶段可能变动）。验证思路（推断，待实测）：挂载后重启 `dsh web`，发涉及 token 计数的任务，观察日志是否出现 MCP 调用记录。

## 9.7 子代理配置示例

并行子代理通过 `packages/subagent/*` 提供。以下是在 `cordis.patch.yml` 中**启用子代理能力**的配置片段：

```yaml
- insert:
    - id: subagent
      name: '@deepseek-ai/dsh-subagent'
      config:
        maxConcurrency: 3
        timeout: 120000
```

**适用场景与并发策略**：

| 场景 | 子代理数 | 父代理职责 | 子代理职责 |
|---|---|---|---|
| 大仓库多模块调研 | 3-5 个 | 划分模块边界、汇总结论 | 各模块独立调研 |
| 长任务分解 | 2-3 个 | 拆分子任务、校验完整性 | 各子任务独立执行 |
| 独立验证 | 1-2 个 | 提供结论与验证标准 | 交叉检查 |
| 多文件并行编辑 | 2-4 个 | 锁定文件范围、避免冲突 | 各子代理写不同文件 |

> ⚠️ `maxConcurrency` 与 `timeout` 基于包名与 cordis 惯例推断（推断，待实测）。上下文隔离机制需查阅官方 `packages/subagent/README.md`。

## 9.8 工作流 YAML 示例

以下是一个**确定性工作流**的 `cordis.patch.yml` 片段，模拟"数据拉取 → 清洗 → 报表 → 校验"四步（参考第 10 章案例 A 的任务结构）：

```yaml
- insert:
    - id: workflow
      name: '@deepseek-ai/dsh-workflow'
      config:
        steps:
          - id: fetch
            tool: bash
            command: 'curl -o raw.json https://api.example.com/data'
          - id: clean
            tool: bash
            command: 'python clean.py raw.json cleaned.json'
            dependsOn: [fetch]
          - id: report
            tool: bash
            command: 'python visualize.py cleaned.json chart.png'
            dependsOn: [clean]
          - id: validate
            tool: bash
            command: 'python verify.py cleaned.json'
            dependsOn: [report]
```

**与案例 A 的对应**：工作流 `dependsOn` 显式定义顺序，而案例 A 的"多轮对话"由模型自由决定工具。工作流适合"步骤固定"；自由对话适合"探索性"。

> ⚠️ `steps`/`dependsOn` 基于 `packages/workflow/` 包名与常见 DSL 推断（推断，待实测）。官方 `packages/examples/` 有可运行示例，建议以其为准。

## 9.9 三者对比表

| 维度 | MCP | 子代理 | 工作流 |
|---|---|---|---|
| **适用场景** | 接入外部系统（数据库/浏览器/内部 API） | 大任务并行分解（调研/验证/多模块） | 确定性流水线（拉取→清洗→报表→校验） |
| **复杂度** | 中（需配置服务器 + 理解协议） | 高（需任务分解设计 + 结果汇总） | 低-中（YAML 配置，调试依赖图较繁琐） |
| **失败处理** | 服务器崩溃 → 重连或报错（推断，待实测） | 单个子代理失败 → 父代理决定重试/忽略/终止 | 单步失败 → 可选暂停/跳过/回滚（推断，待实测） |
| **性能开销** | 额外进程通信开销（stdio/sse） | 并发节省墙钟时间，但增加协调开销 | 串行执行，无额外模型开销，但无并行收益 |

**决策建议**：有明确工具缺口 → MCP；任务能拆成互不依赖的几块 → 子代理；步骤固定、需严格按序 → 工作流。三者可组合：子代理并行调研 → 内部用 MCP 查数据库 → 工作流汇总报告。

## 9.10 踩坑补充

| # | 坑 | 现象 | 解法 |
|---|---|---|---|
| 1 | MCP 连接失败 | 挂载后启动报错或 MCP 工具无响应 | 检查 `command`/`args`；先手动跑 `npx -y xxx` 验证（推断，待实测） |
| 2 | 子代理上下文隔离 | 子代理看不到父 Agent 历史，导致重复提问 | 父代理委派时把关键上下文写进任务描述（推断，待实测） |
| 3 | 工作流单步失败 | 某步 `bash` 返回非零，后续步骤继续执行 | 配置 `onError: pause` 或每步后加校验脚本（推断，待实测） |
| 4 | 子代理文件冲突 | 多个子代理同时写同一个文件 | 父代理规划时划分文件边界（推断，待实测） |
| 5 | MCP 环境变量未注入 | `${DSH_API_KEY}` 解析为空 | 确认宿主 shell 已 `export`；或写死（仅本地测试）（推断，待实测） |

> 所有标注"推断，待实测"的内容均基于 `packages/` 目录结构与 cordis 配置惯例推断，非本白皮书实机验证结果。rc 阶段请以官方文档为准。

## 9.11 四阶段新手路径（含验收标准）

把 9.4 节的"四阶段"扩展为**每阶段有明确验收标准**的升级路径：

| 阶段 | 能力 | 验收标准（怎么知道自己该进入下一阶段） | 参考章节 |
|---|---|---|---|
| **阶段一** | 单 Agent + 内置工具 | 能独立完成：创建文件 → 搜索 → 编辑 → 运行验证，全程不卡壳 | 第 2-5 章 |
| **阶段二** | + MCP | 成功挂载一个 MCP 服务器，任务中调用其工具且日志证明调用发生 | 9.1 节 + 9.6 节 |
| **阶段三** | + 子代理 | 成功发起一次并行子代理任务（如同时调研 2 个模块），父代理能汇总结果 | 9.2 节 + 9.7 节 |
| **阶段四** | + 工作流 | 成功配置并执行一个 3 步以上工作流，每步按 `dependsOn` 顺序执行 | 9.3 节 + 9.8 节 |

**为什么不要跳级**：阶段一没跑通 → 阶段二报错无法判断是配置错还是基础工具链不会用；阶段二没跑通 → 阶段三并行放大问题；阶段三没跑通 → 阶段四 YAML 写出来也是错的。阶段一到阶段二之间，先读第 8 章 8.1 节能力包地图——确认需求是否已内置，避免为"已有能力"配 MCP。

---

## 动手练习（检验你是否真懂了）

1. **理解题**：说出 MCP、子代理、工作流各自解决什么问题。三者之间有什么联系？（自查：9.1-9.3 节首段 + 9.9 节对比表）
2. **理解题**：解释"工作流"和"多轮对话"的区别。什么场景该用工作流？（自查：9.3 节 + 9.8 节）
3. **动手题**：在 `dsh web` 里发"调研仓库目录结构并生成报告"，观察是否自动调用 `read`/`glob`/`grep`。想加"查数据库"能力，该用 MCP 还是 host 插件？（自查：9.1 节 + 9.9 节）
4. **动手题**：设计"子代理并行调研"：调研 3 个模块（src/lib/src/cli/src/web），写出父 Agent 规划 + 3 个子代理任务描述（自查：9.2 节 + 9.7 节）
5. **思考题**：任务"读 100 个文件后汇总"，单 Agent 串行、5 个子代理并行、工作流分 5 批串行，各有什么优劣？（自查：9.9 节对比表）
6. **思考题**：想让 dsh "查公司内部员工信息"，走官方内置工具、MCP、host 插件三条路各需什么条件？哪条最快？（自查：第 8 章 8.1 节 + 本章 9.1 节 + 第 3 章 3.4 节）

## 常见疑问 FAQ

**Q1：MCP 是什么？和 dsh 插件有什么区别？**
MCP 是"给 Agent 插外部工具"的开放协议。插件在 dsh 运行时内注册能力（host 半跑在 Node 进程）；MCP 服务器是独立进程，通过协议通信。插件深度集成、性能好；MCP 解耦、可复用、适合接入现有系统。

**Q2：子代理是怎么"并行"的？会不会有冲突？**
子代理由父 Agent 委派，各自独立执行（`packages/subagent/*`）。并行时各子代理有自己的上下文，不会互相干扰。但多个子代理改同一个文件可能冲突——建议任务分解时避免交叉。

**Q3：工作流的"确定性流程"是什么意思？和模型自由发挥有什么区别？**
工作流把步骤定义成流程（如 cordis.yml），按顺序/条件执行，每步做什么是指定的。多轮对话是"模型自由发挥"。确定性流程适合"必须按固定步骤走"的场景，自由发挥适合"探索性任务"。

**Q4：我想接一个 MCP 服务器（比如数据库），具体怎么操作？**
（以官方 changelog 为准）① 安装 `@deepseek-ai/dsh-mcp-client`；② 在 `cordis.patch.yml` 挂载（参考 9.6 节）；③ 配置服务器地址/命令；④ 重启 `dsh web`。详见官方 `packages/mcp/` 文档。

**Q5：子代理和"开多个 dsh 进程"有什么区别？**
子代理是 dsh 内部委派机制（`packages/subagent/*`），共享父 Agent 上下文和会话。多进程是完全独立的会话。子代理适合"任务分解后并行执行 + 结果汇总"，多进程适合"完全独立的任务"。

**Q6：本章说部分功能"待实测"，我怎么知道哪些功能已经可用？**
查官方 `packages/AGENTS.md` 和 `packages/` 目录。有完整源码 + 示例的功能基本可用；只有包名没有文档的可能还在开发中。rc 阶段以官方 changelog 为准。

---

**附录 A**：[术语表与命令速查](./appendix-glossary.md)