CodeWhale Workflow教程：用.workflow.js写Agent编排脚本的完整指南

CodeWhale Workflow教程：用.workflow.js写Agent编排脚本的完整指南

【免费下载链接】CodeWhale Open-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome. 项目地址: https://gitcode.com/GitHub_Trending/de/CodeWhale

CodeWhale 是一款用 Rust 构建的开源终端编码 Agent，其中的 Workflow 功能允许你用 .workflow.js 文件编写 Agent 编排脚本，把"多智能体并行执行、分阶段推进、结果汇总"变成可复用、可回放的标准作业流程。本教程面向新手，带你从零理解 Workflow 的核心概念，学会编写、运行和监控第一个编排脚本，全程只需几行声明式配置。

什么是 .workflow.js：Agent 编排脚本

在开始之前，先回答一个关键问题：什么时候需要写编排脚本？

普通的多 Agent 任务不需要手写文件——你用自然语言描述目标，CodeWhale 会自动决定是否需要编排。而 Workflow 是为以下场景准备的：

• 有序阶段：必须先实现、再验证、最后汇总
• 并行分叉：多个子 Agent 同时侦察、互不干扰
• 确定性汇合：所有分支结果必须汇总成一个结论
• 共享预算：统一控制 token 消耗上限
• 可回放：脚本存进仓库，团队协作可复用

💡 核心理念：.workflow.js 只是一个协调器，它自己不能碰文件系统、不能执行命令、不能联网——真正的脏活累活都交给它派生的子 Agent 完成。这种"编排与执行分离"的设计是 Workflow 安全性的根基。

一步上手：运行你的第一个编排脚本

仓库里已经附带了一批可直接运行的示例，位于 workflows/ 目录：

在 CodeWhale 的 TUI 中，只需输入：

/workflow run workflows/issue_audit.workflow.js

脚本会原样启动。如果你只想给目标让模型现场生成并执行一个编排，直接输入 /workflow <你的目标> 即可。运行期间的管理命令全部免费、不消耗模型回合：

/workflow status [run_id]     # 查看运行状态
/workflow cancel [run_id]     # 取消运行（模型忙碌时也能生效）
/workflow settings            # 查看当前 [workflow] 配置

按 /workflows 还能打开运行仪表盘：所有历史运行按最新排序，Enter 展开详情查看每个子 Agent 的状态，x 取消运行中的任务。

两种编写风格：声明式节点 vs 脚本式

CodeWhale 支持两种等价的写法，选你顺手的即可（详见 docs/WORKFLOW_AUTHORING.md）。

风格一：声明式节点（推荐新手）

issue_audit.workflow.js 展示了典型结构——branch 负责并行分叉，reduce 负责结果汇合：

export default workflow({
  "id": "issue-audit-js",
  "goal": "Audit an issue fix with parallel specialist agents",
  "nodes": [
    { "branch": {
        "id": "parallel-audit",
        "parallel": true,
        "children": [
          { "agent": { "id": "code-audit",  "prompt": "检查实现正确性", "agent_type": "review" } },
          { "agent": { "id": "test-audit",  "prompt": "检查测试覆盖",   "agent_type": "verifier" } },
          { "agent": { "id": "docs-audit",  "prompt": "检查文档是否需更新", "agent_type": "review" } }
        ] } },
    { "reduce": {
        "id": "summary",
        "inputs": ["code-audit", "test-audit", "docs-audit"],
        "prompt": "汇总三方发现，输出发布风险摘要" } }
  ]
});

支持的节点类型有：agent（单个子 Agent）、branch（并行分支）、sequence（顺序执行）、reduce（结果汇合）、loop_until（循环直到满足条件）、cond（条件分支）、expand（动态展开子节点）等。

风格二：脚本式（更灵活）

operate_staged_fix.workflow.js 展示脚本式写法，读起来更像普通程序：

export default async function (args) {
  phase("Implement");
  const implement = await task({
    label: "implementer",
    worktree: true,               // 在隔离工作树中写文件
    prompt: "对目标文件做最小化修改……",
  });

  phase("Verify");
  const verify = await task({
    label: "verifier",
    prompt: `验证上一步的修改。implementer_result:\n${implement}`,
  });

  return { implement, verify };
}

脚本可用的宿主函数只有：task()、parallel()、pipeline()、phase()、log()、budget()、args。没有 文件、网络、环境变量、时钟和随机数——编译器会直接拒绝 import、fetch、process 等一切副作用构造。详见 docs/SANDBOX.md。

关键机制：parallel() 的容错语义

这是新手最容易踩坑也最值得理解的一点：

• parallel() 采用**"部分成功"**语义——某个子 Agent 失败时，对应槽位变成 null，整个流程不会中止；
• 汇总前先用 .filter((s) => s != null) 过滤掉失败槽位，剩下的结果照样能产出完整摘要；
• 但如果声明了 responseSchema 且子 Agent 返回不符合契约，则视为契约失败，会让整个运行报错而不是静默降级。

operate_parallel_scout.workflow.js 就是故意让一个侦察员失败的演示脚本，值得通读一遍。

规模与安全：你能派多少子 Agent？

默认硬性上限（可在 config.example.toml 的 [workflow] 段调整）：

写权限是显式声明的：需要写文件的子 Agent 必须声明 writeAuthority 和具体的 writeRoots / exactFiles；仅给 prompt 的一般任务默认只读。涉及写入、网络、密钥的高权限操作会弹出审批卡片，展示目标、子 Agent 摘要和预算后才放行（参见 docs/AUTOMATIC_WORKFLOWS.md）。

进阶学习路径

1. 通读官方文档：docs/WORKFLOW_AUTHORING.md 是编写规范，docs/FLEET_WORKFLOW_TUTORIAL.md 提供了从 Fleet 任务规格到 Workflow 监控的完整手动演练；
2. 对照 dogfood 用例：docs/examples/dogfood-automatic/ 下 4 个脚本分别覆盖只读审计、分阶段修复、部分失败合成、运行中取消四大场景；
3. 实验搜索模式：想尝试 best-of-N 式的候选生成与评审，见 docs/WORKFLOW_EXPERIMENTAL_SEARCH.md；
4. 研究运行时实现：编排引擎位于 crates/workflow/，JS 沙箱在 crates/workflow-js/。

总结

CodeWhale Workflow 的设计哲学可以浓缩为一句话：脚本只管编排，Agent 负责干活。.workflow.js 没有文件、Shell、网络权限，把多智能体的并行、阶段、预算和容错变成可读、可审查、可入仓的声明式配置。从 workflows/issue_audit.workflow.js 这个 50 行的示例起步，你就能掌握绝大多数编排场景的写法。

【免费下载链接】CodeWhale Open-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome. 项目地址: https://gitcode.com/GitHub_Trending/de/CodeWhale