> ## 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、如何划分阶段、如何合并中间结果，以及最终把什么结果返回到当前会话。

## **什么时候使用动态工作流**

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

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

## **动态工作流能做什么**

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

## **运行动态工作流**

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

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

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

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

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

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

## **Deep Research**

`deep-research` 是一个内置动态工作流，适合需要广泛检索网页、比较多个来源并逐条验证结论的问题。你可以用一个明确的研究问题直接调用：

```text theme={null}
/deep-research 比较 2026 年面向消费者的 Web 应用采用通行密钥和密码时，在安全性与运维方面的取舍。
```

如果问题过于宽泛，无法直接开始调研，Qoder CLI 会先询问澄清问题，再把细化后的问题传给动态工作流。

动态工作流分为五个阶段：

| 阶段 | 执行内容 |
| :- | :- |
| **Scope** | 将问题拆解为互补的检索角度，并根据问题所属领域选择角度。 |
| **Search** | 为每个角度并行启动一个 Web 搜索 Agent。每个 Agent 根据原始问题对结果排序，并排除明显低质量或不相关的页面。 |
| **Fetch** | 对 URL 去重，抓取相关公开页面，评估来源质量，并提取有原文支持、可被验证或证伪的具体论断。 |
| **Verify** | 由多个独立 Agent 质疑提取出的论断。未通过交叉验证的论断会被排除；无法完成验证的论断会标记为“未验证”，而不是“已反驳”。 |
| **Synthesize** | 合并语义重复的论断，组织相关发现，标注置信度，并生成包含执行摘要、注意事项、开放问题和来源引用的报告。 |

最终报告会为主要发现提供证据、置信度和来源 URL。验证失败的论断不会进入主要发现；如果 Agent 或网络请求在完成验证前失败，报告会将相关论断列为“未验证”，而不是将其视为“已反驳”。

Deep Research 通过子 Agent 使用 Web 搜索和网页内容获取工具。需要登录、属于私有内容、位于付费墙之后或不可访问的页面可能无法提供有效内容。该动态工作流会启动多个 Agent，可能较快消耗 token；建议从范围明确的问题开始，并在必要时限定时间、地区、受众或决策标准。

## **查看动态工作流**

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

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

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

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

## **保存动态工作流**

保存后的动态工作流可以通过名称复用。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` 传入。

## **动态工作流如何运行**

动态工作流脚本是普通 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` 下的当前会话目录。

## **权限与安全**

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

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

使用 [权限](https://docs.qoder.com/zh/cli/06-配置与安全/permissions.md) 控制动态工作流子 Agent 能做什么；使用 [Hooks](https://docs.qoder.com/zh/cli/04-扩展QoderCLI/hooks.md) 在工具调用前后执行组织级策略。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.