> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 动态工作流

动态工作流让 Qoder CLI 可以在后台运行结构化的多 Agent 流程。它适合需要分阶段执行、大规模并发、交叉验证，或需要复用固定流程的任务。

动态工作流会把编排计划放到一段 JavaScript 脚本里。脚本决定启动哪些子 Agent、如何划分阶段、如何合并中间结果，以及最终把什么结果返回到当前会话。

<div id="when-to-use-workflows">
  ## **什么时候使用动态工作流**
</div>

| 使用方式     | 适合场景                              |
| :------- | :-------------------------------- |
| Subagent | 单个聚焦子任务，只需要把总结返回主会话。              |
| Skill    | 可复用的说明、领域知识，或主 Agent 应该遵循的流程。     |
| 动态工作流    | 需要多个子 Agent、多个阶段、并行分支或验证轮次的可复用编排。 |

当任务明显大于一次 Agent 调用时，可以使用动态工作流：仓库审计、深度研究、迁移规划、发版检查、跨文件扫描，或需要多个独立视角后再汇总的评审流程。

<div id="what-workflows-do">
  ## **动态工作流能做什么**
</div>

| 能力         | 说明                           |
| :--------- | :--------------------------- |
| 脚本化编排      | 将循环、分支、阶段和中间状态保存在动态工作流脚本中。   |
| 多 Agent 分发 | 为相互独立的工作切片启动多个子 Agent。       |
| 分阶段执行      | 用扫描、分析、验证、总结等命名阶段展示进度。       |
| 并行或流水线处理   | 并发运行独立分支，或让每个条目依次经过多个处理阶段。   |
| 后台运行       | 启动动态工作流后，可以继续使用 Qoder CLI。   |
| 流程复用       | 将常用流程保存为项目级、用户级、插件级或内置动态工作流。 |

<div id="run-a-workflow">
  ## **运行动态工作流**
</div>

你可以用自然语言让 Qoder CLI 使用动态工作流：

```text theme={null}
使用动态工作流审查这个仓库的安全风险，并总结发现。
```

也可以直接按名称调用已保存或内置的动态工作流：

```text theme={null}
使用 deep-research 动态工作流调研这个架构决策的取舍。
```

Qoder CLI 可能会为当前请求创建一个动态工作流，也可能在已有动态工作流与任务匹配时直接使用它。动态生成的工作流在执行前会展示计划；你可以运行、查看原始脚本、带反馈拒绝，或取消。

动态工作流会作为后台任务运行。启动后，Qoder CLI 会返回运行 ID，并在任务界面中持续展示执行进度。

<div id="monitor-workflows">
  ## **查看动态工作流**
</div>

在 TUI 中使用 `/workflows` 打开动态工作流任务面板。

```text theme={null}
/workflows
```

你可以在面板中查看运行中和已完成的动态工作流，检查状态、阶段、Agent、日志、输出路径、错误和最终结果。`/tasks` 也会和其他后台任务一起显示动态工作流任务。

动态工作流运行时，可以在详情页查看单个 Agent。如果某个 Agent 仍可控制，可以在详情页跳过或重试这个 Agent。

<div id="saved-workflows">
  ## **保存动态工作流**
</div>

保存后的动态工作流可以通过名称复用。Qoder CLI 会从以下位置发现动态工作流：

| 范围     | 位置                   | 使用场景                 |
| :----- | :------------------- | :------------------- |
| 项目级    | `.qoder/workflows`   | 动态工作流属于当前仓库或团队。      |
| 用户级    | `~/.qoder/workflows` | 个人动态工作流，需要跨项目使用。     |
| Plugin | Plugin 提供的动态工作流      | 动态工作流随插件分发。          |
| 内置     | Qoder CLI 内置动态工作流    | 动态工作流由 Qoder CLI 提供。 |

当名称冲突时，项目级动态工作流的优先级高于插件级和内置动态工作流。团队共享流程适合放在项目级目录；不应该提交到仓库的个人流程适合放在用户级目录。

保存的动态工作流是一个以 `meta` 导出对象开头的 JavaScript 文件。元信息用于告诉 Qoder CLI 动态工作流的名称、说明、阶段，以及可选的使用场景或输入 schema。

```js theme={null}
export const meta = {
  name: "repo-audit",
  description: "Audit a repository area and summarize risks",
  whenToUse: "Use when the user asks for a structured repository audit",
  phases: [
    { title: "Scan", detail: "Find relevant files and areas" },
    { title: "Analyze", detail: "Run focused analysis agents" },
    { title: "Summarize", detail: "Merge findings into a final report" }
  ]
};
```

保存到 `.qoder/workflows/repo-audit.js` 后，可以这样让 Qoder CLI 使用它：

```text theme={null}
运行 repo-audit 动态工作流，目标是 authentication 模块。
```

保存的动态工作流可以通过 `args` 接收输入。目标路径、issue ID、研究问题、选项，或任何每次运行不同但不应该修改脚本的值，都适合通过 `args` 传入。

<div id="how-workflows-run">
  ## **动态工作流如何运行**
</div>

动态工作流脚本是普通 JavaScript。脚本可以使用 `agent()`、`parallel()`、`pipeline()`、`phase()`、`log()`、`workflow()`、`args` 和 `budget` 等辅助函数。

1. Qoder CLI 为任务选择已保存的动态工作流，或创建新的动态工作流。
2. 如果需要审查，Qoder CLI 会展示动态工作流名称、阶段、脚本和运行选项。
3. 动态工作流作为后台任务启动。
4. 脚本启动子 Agent，并把它们归入不同阶段。
5. 中间结果保存在动态工作流运行时中，不会填满主会话上下文。
6. 最终结果写入动态工作流运行输出，并回到当前会话中总结。

动态工作流运行过程中的脚本、manifest、journal、transcript 和输出会写入 `.qoder/sessions` 下的当前会话目录。

<div id="permissions-and-safety">
  ## **权限与安全**
</div>

动态工作流可能会运行多个子 Agent，并较快消耗 token。验证大型或高成本动态工作流时，建议先从较小范围开始。

动态工作流脚本不能直接访问 shell、文件系统、网络、Node.js API 或 MCP 服务。所有副作用都通过子 Agent 发生，而子 Agent 仍然会经过 Qoder CLI 的工具、权限、Hooks 和沙箱设置。

使用 [权限](/zh/cli/permissions) 控制动态工作流子 Agent 能做什么；使用 [Hooks](/zh/cli/hooks) 在工具调用前后执行组织级策略。