# 动态工作流（Dynamic Workflows）

子代理已经能帮你"派出一个分身"去并行调查某件事。但当一个任务大到需要"派出一支队伍"——比如把整个仓库扫一遍、给每个模块都写一份评审，单个子代理就不够看了。这时候就轮到**动态工作流（Dynamic Workflows）**登场。

动态工作流让 Claude Code 一次性编排**数十到上百个后台子代理**，各自领一块活儿并行干，你则继续做自己的事。它运行在 Claude Code 当前配置的模型上——所以只要把 Claude Code 指向 QCode，工作流就直接能用。

## 它解决什么问题

普通子代理适合"少量、可控"的并行：派 2~3 个分身分别查 API、查 schema、查测试覆盖率。但有些任务的并行度天然很高：

- 给一个有 200 个文件的仓库**逐文件做安全/质量评审**
- 把一套旧 API 调用**在整个代码库里批量迁移**到新写法
- 围绕一个主题，对几十个目录**分别做调研并汇总**

如果用串行方式，你得等 Claude 一个一个慢慢过；如果手动开几十个子代理，你又得自己拆任务、自己盯进度。动态工作流把"拆分 → 分发 → 后台执行 → 汇总"这一整套都交给 Claude Code 自己编排。

## 如何触发

动态工作流不需要额外安装，触发方式很轻量：

- 在你的提示里包含关键词 **`ultracode`**；或
- 直接让它**"跑一个工作流（run a workflow）"**。

Claude Code 识别到意图后，会自行规划要派多少个后台子代理、每个负责哪一块，然后开始并行执行。

```
> ultracode 把 src/ 下每个子模块都做一次代码评审，重点看错误处理和输入校验，
> 每个模块输出一份简短报告，最后汇总成一个总览。
```

或者用自然语言：

```
> 帮我跑一个工作流：扫描整个仓库里所有调用旧版 httpClient 的地方，
> 评估迁移到新版 fetch 封装的改动量，按目录分组汇总。
```

## 用 /workflows 查看运行

工作流派出的子代理会在**后台持续运行**，不会卡住你的主会话——你可以继续问别的问题、继续写代码。想查看当前有哪些工作流在跑、进度如何，用：

```
/workflows
```

它会列出正在运行和已完成的工作流运行（runs），方便你跟踪整体进度、查看各子代理的产出。

> 后台执行意味着大任务不再阻塞交互。你抛出指令后可以去做别的事，回头用 `/workflows` 收结果。

## 什么时候用工作流，什么时候用单个子代理

两者是同一套"并行委派"思路的不同规模，选择标准很简单：**看并行度和是否需要后台化**。

| 维度 | 单个子代理 | 动态工作流 |
|------|-----------|-----------|
| 并行规模 | 少量（几个）独立子任务 | 数十到上百个子任务 |
| 触发方式 | 让 Claude "派一个子代理去查 X" | 关键词 `ultracode` 或"跑一个工作流" |
| 执行位置 | 完成后把摘要返回主会话 | 后台持续运行，不阻塞主会话 |
| 查看方式 | 结果随对话返回 | 用 `/workflows` 查看运行列表 |
| 典型场景 | 并行查 API / schema / 测试 | 全仓评审 / 批量迁移 / 大规模调研 |

经验法则：

- 子任务**只有几个**、你想立刻拿到结果 → 用[子代理](/docs/advanced/subagents)。
- 子任务**几十上百个**、可以放后台慢慢跑 → 用动态工作流。

> 动态工作流本质上就是子代理的"规模化"版本。先把[子代理](/docs/advanced/subagents)的概念吃透，再上工作流会更顺手。

## 通过 QCode 使用

动态工作流跑在 **Claude Code 当前所连的模型**上，本身不依赖任何特定供应商。也就是说，只要你把 Claude Code 指向 QCode，工作流派出的所有后台子代理都会走 QCode 的接入点——同一把 `cr_` 开头的 API Key 全程通用。

最小配置（Anthropic 协议）：

```bash
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_你的密钥"

# 国内用户优先用 asia 接入点
# export ANTHROPIC_BASE_URL="https://asia.qcode.cc/api"
```

> `BASE_URL` 末尾**不要**带斜杠。直接访问该地址返回 `401` 属于正常现象——说明路径正确，只是缺少鉴权。

配好之后，正常启动 Claude Code，再用 `ultracode` 触发工作流即可。完整的接入点说明、四个域名（api / asia / us / eu）与各协议路径，见[接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

工作流里每个后台子代理消耗的 token 都按你在 QCode 选用的模型计费。大规模工作流会同时跑很多个子代理，token 消耗也会相应放大——大任务前不妨先用旗舰模型（如 `claude-opus-5`，$5/$25 每百万 token、1M 上下文）跑一个小范围试点，确认产出质量后再全量铺开。

## 实战示例

### 示例 1：全仓代码评审

让工作流给仓库里每个主要模块都出一份评审，关注点统一、产出统一，最后汇总：

```
> ultracode 对 packages/ 下每个子包做一次独立代码评审。
> 每份评审覆盖：错误处理、边界条件、是否有未处理的 Promise、命名一致性。
> 每个子包输出不超过 20 行的要点清单，最后汇总成一份按严重程度排序的总表。
```

派出去之后，你可以继续做别的事，过一会儿用 `/workflows` 看进度，等所有子代理跑完再统一看汇总表。

### 示例 2：大规模 API 迁移调研

在动手改之前，先用工作流摸清改动面：

```
> 帮我跑一个工作流：在整个代码库里找出所有直接使用 axios 的地方，
> 按目录分组，评估改成项目内 httpClient 封装的工作量和风险，
> 输出一张"目录 / 出现次数 / 迁移难度 / 注意事项"的表格。
```

得到全景之后，你就能基于真实数据决定迁移顺序，而不是凭感觉。

## 小贴士与注意事项

- **先小后大**：第一次跑工作流，先把范围圈在一个目录或一个包上，验证产出格式和质量符合预期，再扩到全仓。
- **统一产出格式**：在提示里明确每个子代理"输出什么、多长、如何排序"，汇总时会省很多事。
- **后台不等于无人值守**：工作流跑着的时候你可以做别的，但记得回头用 `/workflows` 收尾确认。
- **关于图像**：动态工作流处理的是文本/代码任务。如果你要让 Claude Code **读图**（截图、架构图、错误截图），那是视觉输入能力，与工作流无关；如果你要**生成图像**，请用 [gpt-image-2 图像生成](/docs/usage/image-2)。
- 想把工作流接进 CI/脚本，可结合无头模式与结构化输出，见[自动化与 CI/CD](/docs/advanced/headless)。

> 想用旗舰模型跑大规模工作流，又关心成本？看看 [QCode 定价](https://qcode.cc/pricing)，同一把 API Key 即可在所有接入点畅用。