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

# Devin 动态工作流程

> 使用确定性的 Python 脚本编排多个 Devin session：分发任务、在各阶段间传递结构化结果，并从中断处恢复运行。

<Info>
  任何 Devin session 都可使用动态工作流程——只需描述任务，并让 Devin 将其作为工作流程运行。

  \*\*Enterprise 账户：\*\*在企业管理员于 [企业设置 > Devin](https://app.devin.ai/settings/enterprise-devin) 中启用 **动态工作流程** 之前，此功能处于关闭状态。在此之前，Devin 不会在该 Enterprise 的任何组织中运行工作流程。
</Info>

<div id="what-are-dynamic-workflows">
  ## 什么是动态工作流程？
</div>

动态工作流程是一种**以确定性方式编排 Devin Agent 团队的 Python 脚本**。Devin 会编写并运行该脚本；脚本决定运行哪些 Agent、运行顺序以及向每个 Agent 提供哪些指令——利用前序 Agent 的结构化结果构建后续 Agent 的提示。

每次 Agent 调用都会被记录，因此工作流程在运行过程中可观测，中断后也可恢复：已完成的 Agent 会立即重放记录的结果，只有未完成的工作会重新运行。

这比[托管 Devins](/zh/work-with-devin/advanced-capabilities#managed-devins)更进一步：后者需要协调会话手动启动并监控子会话。在工作流程中，编排本身就是代码。

<div id="when-to-use-a-workflow">
  ## 何时使用工作流程
</div>

当任务具有明确的结构时，建议使用工作流程：

* **大范围并行后汇总** — 大约五个或更多彼此独立的单元 (文件、模块、端点、工单) ，每个单元都需要判断或验证，随后再汇总结果。
* **分阶段流水线** — 后续阶段会使用前一阶段的结构化输出，例如 *审计 → 修复 → 验证*。

在以下情况下，请使用普通 session (或几个[托管 Devins](/zh/work-with-devin/advanced-capabilities#managed-devins)) ：

* 变更是机械性的 — codemod、linter 自动修复或生成器能比 Agent 更快、更可靠地完成。
* 只需一两个独立 session，且它们之间无需传递数据。
* 任务因共享状态而紧密耦合，或者规模较小且需要按顺序完成。

<div id="example-prompts">
  ### 提示示例
</div>

你描述任务并请求一个工作流程；Devin 会编写脚本。

**迁移** — 为每个单元分配一个 Agent，使其在各自的分支上工作，然后汇总：

```text theme={null}
使用工作流程将 jobs/ 目录下的每个 job 从旧的 cron runner 迁移到我们新的
scheduler API —— 每个 job 分配一个 agent，各自在独立分支上工作并运行该
job 的测试 —— 最后汇总出哪些 job 需要手动处理
```

**调研**——并行收集证据，然后综合分析：

```text theme={null}
用一个工作流程为新的事件服务评估 Postgres、DynamoDB 和 CockroachDB：每个方案配一个
agent，按照我们的延迟、成本和运维要求给它打分，最后由一个 agent 对比各方 evidence
并推荐其中一个
```

**代码审查** — 每个文件由一位审查者审核，然后进行合并：

```text theme={null}
使用工作流程，对照 CONTRIBUTING.md 审查此分支上改动的每个文件——每个文件
指派一名审查者——然后将所有发现项合并为一份按严重程度排序的去重列表
```

**全代码库审计** — 分阶段执行的*审计 → 修复 → 验证*流程：

```text theme={null}
使用工作流程审查 reporting 模块中的每一条 SQL 查询，排查缺失分页和 N+1 查询
模式的问题，为每个确认的问题各开一个分支进行修复，并在修复前后各执行一次
EXPLAIN 来验证效果
```

**循环**——重复执行，直到检查通过或进展停滞：

```text theme={null}
使用工作流程让不稳定的集成测试套件恢复全绿：运行测试，修复所有失败项，
如此反复，直到连续三次运行全部通过，或者某一轮不再修复出任何新问题为止
```

<div id="how-a-run-works">
  ## 运行流程
</div>

1. **Devin 将脚本写入文件**并启动运行。除非你已在 **Settings → Preferences → 自动批准工作流程** 中开启自动批准，否则需要先批准。
2. **脚本在 Devin's machine 上运行。** 工作流程原语会自动注入，无需安装或导入任何内容。
3. **每次 Agent 调用都会启动一个 Agent**，并等待其结构化输出。默认情况下，该 Agent 是在独立 VM 上运行的独立 Devin session。
4. **进度会实时同步到 session 中。** 工作流程面板会显示每个阶段、对应的 Agent 及其实时状态；你可以从那里打开任意 Agent 的 session。
5. \*\*结果会按运行 ID 记录，\*\*因此可以恢复运行。

运行会在后台执行，因此 session 仍可响应——执行期间，你可以继续与 Devin 交流、请求进度摘要，或要求它停止运行。停止运行会取消脚本，并让剩余的 child sessions 进入休眠状态；已记录的所有内容仍可恢复。

<div id="authoring-model">
  ## 编写模型
</div>

脚本使用原生 Python 编写。Devin 会编写脚本，但在审查时了解其结构会有所帮助：

| 基元                                     | 作用                                                           |
| -------------------------------------- | ------------------------------------------------------------ |
| `register_workflow(meta)`              | 声明工作流程的名称、描述和阶段。必须在运行任何 Agent 之前 await 此函数。                  |
| `agent(prompt, phase=..., schema=...)` | 运行一个 Agent，并以 dict 形式返回其结构化输出。                               |
| `pipeline(items, stage1, stage2, ...)` | 让每个项目独立依次经过各个阶段——阶段之间没有屏障，因此项目 A 可以处于第 3 阶段，而项目 B 仍处于第 1 阶段。 |
| `parallel([...])`                      | 并发运行异步可调用对象，并等待它们全部完成。仅在某个阶段确实需要此前所有结果时使用，例如合并或去重步骤。         |
| `log("message")`                       | 写入一条进度日志，在运行尚未结束时可见。                                         |

每次 `agent()` 调用都会接收一个 JSON Schema，并返回符合该 Schema 的 dict；这样，一个阶段的发现项就能成为下一阶段的提示。保持 schema 简洁且扁平。

<div id="example">
  ### 示例
</div>

跨三个模块的“先审计，后修复”流水线：

```python theme={null}
import asyncio
import json

REPO = "github.com/acme/api"
MODULES = ["auth", "billing", "search"]

META = {
    "name": "error-handling-audit",
    "description": "Audit and fix error-handling bugs across api modules",
    "phases": [
        {"title": "analyze", "detail": "audit each module for error-handling bugs"},
        {"title": "fix", "detail": "fix confirmed issues and push a branch"},
    ],
}

FINDINGS_SCHEMA = {
    "type": "object",
    "properties": {
        "module": {"type": "string"},
        "issues": {"type": "array", "items": {"type": "string"}},
    },
    "required": ["module", "issues"],
}

FIX_SCHEMA = {
    "type": "object",
    "properties": {"branch": {"type": "string"}, "summary": {"type": "string"}},
    "required": ["branch", "summary"],
}

async def analyze(module):
    return await agent(
        f"In {REPO}, audit the '{module}' module for error-handling bugs. "
        "Report each issue as a one-line string.",
        phase="analyze",
        schema=FINDINGS_SCHEMA,
        label=f"analyze-{module}",
    )

async def fix(findings):
    if not findings["issues"]:
        return None
    return await agent(
        f"In {REPO}, fix these issues in the '{findings['module']}' module:\n"
        + json.dumps(findings["issues"], sort_keys=True)
        + "\nPush your work to a new git branch (do not open a PR) and "
        "report the branch name and a one-line summary.",
        phase="fix",
        schema=FIX_SCHEMA,
        label=f"fix-{findings['module']}",
    )

async def main():
    await register_workflow(META)
    results = await pipeline(MODULES, analyze, fix)
    for module, result in zip(MODULES, results):
        log(f"{module}: {result['branch'] if result else 'no fix needed/failed'}")

asyncio.run(main())
```

<div id="where-agents-run">
  ## Agent 的运行位置
</div>

默认情况下，每个 Agent 都在独立的 VM 上运行，也可以固定到编排会话所在的机器上。

<CardGroup cols={2}>
  <Card title="独立 VM（默认）" icon="server">
    一个完整的子 Devin 会话，拥有自己的机器、仓库克隆和[环境](/zh/onboard-devin/environment/blueprints)。它无法访问编排会话的文件，因此代码交接需通过 git 分支进行：每个 Agent 推送一个分支并报告分支名称，后续阶段再从结构化输出中读取该名称。
  </Card>

  <Card title="共享 VM" icon="folder-tree">
    Agent 在编排会话所在的机器上运行，并共享其工作树，包括未提交的更改，因此无需通过 git 交接。当 Agent 必须读取或编辑当前工作树，或者仓库仅存在于该机器上时，请使用此选项。
  </Card>
</CardGroup>

共享 VM 的 Agent 会与会话争用 CPU、内存和磁盘资源，并且并发上限更低。由于它们共享同一个工作树，彼此之间没有隔离，并行写入的 Agent 必须分配到完全不重叠的文件或目录。

还可以将 Agent 固定到特定的 Devin 模式，例如在大规模扇出场景中，使用成本更低的 Devin Lite 对各项任务进行分类。

<div id="determinism-and-resuming">
  ## 确定性与恢复执行
</div>

恢复运行时，工作流程脚本会从头重新执行，每次 Agent 调用则通过其提示、模式和执行设置的哈希值来确定。所有已完成的部分都会重放其已记录的结果；其余部分会使用新会话重新运行。

这只有在脚本每次都进行相同调用时才有效。工作流程逻辑和提示不得依赖当前时间或日期、随机性、生成的 ID、环境变量、文件系统状态或网络响应。任何需要检查外部世界的信息都应放在 `agent()` 调用中，其记录的输出由脚本其余部分使用。

有两个需要注意的结果：

* **编辑提示会重新运行该 Agent** 及其所有下游内容，而未修改的早期 Agent 仍会重放。
* **超时或中断的运行会从上次停止的位置继续执行**，恢复时需使用其运行 ID。一次运行的默认和最大预算均为七天。

如果 Agent 失败——其会话终止，或未产生有效的结构化输出——脚本将决定如何处理：跳过该项、使用默认值替代、重试，或使该运行失败。恢复运行会使用新会话重试失败的 Agent。

<div id="cost">
  ## 成本
</div>

工作流程中的每个 Agent 都是一个 Devin session，因此一次运行消耗的 ACU 可能远高于在单个 session 中完成同一任务。将工作流程应用到整个 repo 之前，先在一小部分内容上运行——例如一个 directory、三个 module 或一个范围更窄的问题——并在工作流程面板中查看各 Agent 的 ACU 用量。对于逐项分类等高频阶段，选择成本更低的 [mode](/zh/essential-guidelines/when-to-use-devin)，也能让大规模扇出保持在可负担的范围内。

<div id="saving-a-workflow-for-reuse">
  ## 保存工作流程以供复用
</div>

工作流程验证可用后，可以将其作为 [技能](/zh/product-guides/skills) 提交到你的 repo：创建一个 `workflow.py` 文件，并在旁边提供 `SKILL.md` 说明其适用场景。之后，Devin 会在处理后续任务时发现并重新运行该工作流程，而无需重新编写脚本。让 Devin 保存工作流程，它会为你创建所需文件。

<div id="related">
  ## 相关内容
</div>

* [高级功能](/zh/work-with-devin/advanced-capabilities) — 直接编排托管 Devins
* [Skills](/zh/product-guides/skills) — 在你的代码仓库中保存可复用步骤和工作流程
* [Devin MCP](/zh/work-with-devin/devin-mcp) — 以编程方式创建和监控会话