CodeWhale Fleet Workflow 实战教程用持久化 Worker 与声明式编排搭建可审计的多 Agent 流水线【免费下载链接】CodewhaleOpen-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导读本教程面向希望手动编写 fleet 任务规格task spec并把 Workflow 文件纳入版本库的运维/进阶使用者完整讲解 Codewhale 中 Fleet 与 Workflow 的分工、工作区初始化、codewhale fleet run任务规格的字段语义、启动/监控/恢复的完整命令面以及把并行 Agent 与归约节点声明成.workflow.js的写法。读完你可以独立完成一次「从自然语言需求 → 编写任务规格 → 派发持久 Worker → 编排多阶段流水线 → 事后恢复」的全流程。全文以 docs/FLEET_WORKFLOW_TUTORIAL.md 为骨架并补充仓库源码与官方 smoke 示例等一手佐证。Fleet 与 Workflow 各自解决什么问题Fleet 和 Workflow 被设计为协同工作、但职责不同的两套机制Fleet负责运行持久化的 worker记录一份账本ledger保存日志与产物并暴露 status / restart / stop 等控制入口。Workflow负责描述编排逻辑阶段phase、分支branch、归约reduce、循环loop以及可以经由 fleet / 子 Agent 运行时派发的叶子节点。需要特别强调的是仓库对两者有一套清晰的「三层所有权」表述Workflow 拥有计划阶段、分支、循环、归约器与中间结果Fleet 拥有持久名册成员身份、语义角色以及保存下来的 provider/model 固定或继承Runtime委托协调器拥有执行工具姿态tool posture、并发、租约、心跳、日志、回执以及 resume/stop/restart 控制。Fleet 本身不执行、也不授权工作当 fleet 解析出该由谁参与之后委托协调器会以无头方式启动一次codewhale exec运行再由 Runtime 做持久跟踪。相关架构细节可继续阅读 docs/FLEET.md 与 docs/AGENT_RUNTIME.md。默认产品路径先问一句而不是先写文件默认产品路径是用自然语言提出请求Operate 在当前姿态posture下可以直接使用工具当工作相互独立、可并行、相互隔离或耗时长时更倾向于使用一个或多个后台 fleet worker。把工作放进后台可以保持 composer 空闲以继续对话。只有当有序阶段、门禁gates、共享预算或确定性扇入确实带来价值时才会选用 Workflow——普通多 Agent 工作并不需要编写 Workflow 文件。这一点在 docs/AUTOMATIC_WORKFLOWS.md 中有完整说明。本教程聚焦的是手动 fleet task spec / 纳入版本库的 Workflow路径面向希望拥有持久宿主机 worker 与可审查规格的运维场景。即便是一句话的请求也不应被静默地自动生成tasks.jsonworker 卡片与权限姿态让派发过程对用户可见而不必暴露底层编写机制。命名约定文档示例统一使用codewhale fleet与/fleet磁盘路径、配置键以及 Workflow 的--fleet旗标都沿用 Fleet 这个名字。这是承重命名边界改动会破坏既有 workspace、receipt 或脚本。1. 准备工作区init 与持久名册从你希望 worker 检查或修改的 workspace 运行codewhale fleet init该命令会在工作区创建持久账本.codewhale/fleet.jsonlworker 日志与受限产物位于.codewhale/fleet/下宿主机适配器host adapter日志位于.codewhale/fleet-host/下。这套目录布局在源码与 docs/FLEET.md 中被列为承重路径。如果需要命名且可复用的 worker打开 TUI 并运行/fleet setup向导会依次引导你完成选择一个角色role决定该档案是否继承 operator 路由还是固定到某个具体 provider/model选择档案存放位置This project→.codewhale/agents/role.toml仅本项目可见Personal→$CODEWHALE_HOME/agents/role.toml跨仓库可用同 id 的项目档案优先级更高会覆盖个人档案审阅最终生成的文件、权限/工具/路由姿态并保存。保存控件会明确标注其效果Save to this project / Save as Personal profile而覆盖已有文件时总会要求第二次确认。fleet 任务规格可以通过worker.agent_profile或更短的别名worker.profile引用上述任一已解析档案。这样得到的 fleet 定义是跨仓库的而不是某个正在运行的会话的临时权威。要做多仓库操作时请从共享父 workspace 启动 Codewhale。档案可用性并不会授予文件系统访问权——会话的 workspace、显式信任路径、trust 模式与权限姿态仍然具有最终权威。这与 docs/FLEET.md 中Runtime 在成员选择之后才施加并钳制策略若选定成员无法在有效包络内运行则失败关闭fail closed而非另选他人的表述一致。2. 编写 fleet 任务规格task speccodewhale fleet run接受 JSON 或 TOML。仓库内已维护了一个真实的 smoke 示例 docs/examples/fleet-dogfood.toml。下面用 JSON 演示同样的编写形态一个只读 reviewer、一个有界 docs-note 写入 worker。重要安全语义活动的 Runtime 策略控制 secrets 与 trustfleet 身份既不携带 secrets也不携带 trust。{ name: docs readiness check, labels: { kind: tutorial }, tasks: [ { id: map-docs, name: Map current docs, objective: Find the docs that describe fleet and Workflow., instructions: Read docs/FLEET.md and docs/WORKFLOW_AUTHORING.md. Report the command surfaces, current limitations, and any confusing gaps., worker: { role: reviewer, profile: reviewer, tools: [rg, sed, git], model: deepseek-v4-flash }, workspace: { required_files: [docs/FLEET.md, docs/WORKFLOW_AUTHORING.md], writable_paths: [], environment: { required: [], allowlist: [] } }, input_files: [docs/FLEET.md, docs/WORKFLOW_AUTHORING.md], expected_artifacts: [log, report], scorer: { kind: manual }, retry_policy: { max_attempts: 1 } }, { id: draft-gap-note, name: Draft gap note, objective: Draft a short local note for any missing tutorial steps., instructions: Write a concise Markdown note with the missing fleet Workflow tutorial steps. Do not edit public docs unless explicitly asked., worker: { role: builder, tools: [rg, sed] }, workspace: { required_files: [docs/FLEET.md], writable_paths: [.codewhale/fleet], environment: { allowlist: [] } }, expected_artifacts: [log, report], scorer: { kind: manual } } ] }把它保存为tasks.json即可用于codewhale fleet run。常见任务字段速查FieldPurposeid,name稳定的任务标识与显示名。objective,instructionsWorker 的目标与精确操作指令。worker.role内置或自定义角色意图例如reviewer、builder、read-only、smoke-runner。worker.profile/worker.agent_profile已保存的 fleet 名册档案从项目.codewhale/agents/、个人$CODEWHALE_HOME/agents/或[fleet.profiles]解析。worker.tools任务期望 worker 使用的工具名。worker.model优选的显式模型固定。provider/model 的合法性校验仍由路由解析负责。worker.model_class,worker.loadout为旧任务规格保留的兼容性路由提示新规格请优先用worker.profile 档案内保存的路由固定。workspace.required_files任务开始前必须存在的文件。workspace.writable_paths当有效 Runtime 姿态允许写入时任务被允许写入的路径。workspace.environment必需或放行的环境变量仅按名称。input_files,context额外要注入任务 prompt 的文件与字符串。expected_artifacts期望出现的产物类型log、report、patch、test_result、checkpoint、receipt。scorer确定性或人工验证规则。retry_policy,timeout_seconds,budget重试与预算控制。更完整的 TOML 形态budget、scorer 与重试仓库中 docs/examples/fleet-dogfood.toml 展示了生产级别更完整的字段组合可作为扩展参考[[tasks]] id cargo-check name Workspace check objective Verify the workspace compiles cleanly with zero errors. instructions Run cargo check --workspace in the repo root. ... just report what you found. worker { role release-checker, tool_profile read-only, tools [cargo], capabilities [rust] } workspace { required_files [Cargo.toml], writable_paths [.codewhale/fleet], environment { required [PATH] } } input_files [Cargo.toml] context [You are running in a fleet smoke test. Be concise. Only report the pass/fail and any specific errors.] budget { max_tokens 8000, max_tool_calls 12, max_seconds 300 } expected_artifacts [log, report, receipt] scorer { kind exit_code } retry_policy { max_attempts 2, initial_backoff_seconds 5, max_backoff_seconds 30 } timeout_seconds 300这个示例展示了几个可在新规格中组合使用的字段细节worker.tool_profile如read-only与worker.capabilities如rust是对工具的进一步声明对照 crates/protocol/src/fleet.rs 中的任务规格类型定义可以确认worker、workspace、budget、expected_artifacts等字段均被建模为带 serde 默认值的强类型结构。budget支持max_tokens/max_tool_calls/max_seconds三路预算retry_policy支持max_attempts、initial_backoff_seconds、max_backoff_seconds。协议层FleetRetryPolicy的默认max_attempts为 3见 crates/protocol/src/fleet.rs手册示例将 reviewer 任务显式压到 1防止重复写盘。scorer除manual人工验证外还出现exit_code以退出码判定与code_whale_verifier_prompt给验证 prompt等确定性形态dogfood 中 protocol-review 任务即用code_whale_verifier_prompt要求至少包含一条 file:line 结论或明确说 all clear。不要在任务规格里放安全策略新写的 fleet task spec 不应包含security_policy或 worker 的trust_level。这些遗留字段仅在**旧账本回放legacy ledger replay**时保持可读新运行校验会拒绝它们。项目信任、文件系统/网络可达性、secrets、审批、沙箱与工具权威都属于Runtime 策略输入。协议层数据结构里仍保留security_policy等字段见 crates/protocol/src/fleet.rs正是为了向后兼容地读取旧回放记录而不是供新规格使用。Worker 到底怎么跑起来从源码结构看每个 worker 都会被翻译成一条无头codewhale exec --output-format stream-json …子进程命令由 host adapter本地进程或 SSH 适配器拉起并接管见 crates/tui/src/fleet/executor.rs 顶部说明与execargv 构造。同一份任务规格还可由仓库维护的自动 smoke 测试驱动——cargo test -p codewhale-tui --bins fleet::executor会通过真实 host adapter 并发运行多个 exec 风格 worker含一个注入的失败并断言终端 pass/fail 结果全程不需要外部服务与模型调用。3. 启动与监控 fleet启动运行codewhale fleet run tasks.json --max-workers 4命令会打印run id与worker ids。另开一个终端即可查看账本化的状态codewhale fleet status codewhale fleet inspect worker-id codewhale fleet logs worker-id codewhale fleet artifacts worker-id需要干预单个 worker 时使用类型化控制命令codewhale fleet interrupt worker-id codewhale fleet restart worker-id codewhale fleet resume run-id codewhale fleet stop --allfleet status、interrupt、resume、restart等在 CLI 与/fleet斜杠命令间共享同一份控制契约。仓库测试对这一点做了很严格的约束/fleet status必须读取持久账本而非当前会话的子 Agent 投影——当 workspace 还没有账本时它应如实返回带no_fleet_ledger的类型化不可用消息而不是假装一切正常且只读动词绝不能顺手创建.codewhale/fleet.jsonl见 crates/tui/src/commands/groups/core/fleet.rs 的测试。这套「同一操作 id如fleet.status贯穿 CLI、斜杠命令与运维面」的设计是承重命名边界的一部分。resume 的恢复语义resume专用于重启恢复manager 退出、笔记本休眠或租约过期stale lease之后。它会重放账本、对仍在 in-flight、心跳已停止的租约做对账在任务预算内重试否则按告警策略失败升级并打印恢复后的状态。它不会启动任何新工作且幂等因此适合在 manager 退出、休眠或 Runtime 重启后安全重复执行。这与 docs/FLEET.md 对codewhale fleet resume run-id的描述完全一致。关于并发上限的实现crates/tui/src/fleet/manager.rs 会把max_workers钳制在1..128之间--max-workers 4即是在这一包络内申请 4 个并发 worker 槽位。4. 编写 WorkflowWorkflow 的源码是声明式的 JavaScript 或 TypeScript会被 lowering 成类型化的 RustWorkflowSpec。它不是一个通用 JavaScript 运行时import、进程访问、文件系统读写、网络调用、eval、async、await都会被拒绝。这是刻意比 JavaScript 更严格的约束——Workflow 源码是熟悉的声明格式而不是第二个执行运行时。Workflow 脚本只扮演协调者本身没有文件系统与 shell真正的工作由脚本派生的子 Agent 完成详见 docs/WORKFLOW_AUTHORING.md。在仓库中建一个纳入版本库的文件例如workflows/docs_readiness.workflow.js。仓库同时也维护了一个生产示例 workflows/issue_audit.workflow.js并行 code / test / docs 三路审计再归约成发版风险评估。export default workflow({ id: docs-readiness, goal: Inspect fleet and Workflow docs, then synthesize a readiness note, nodes: [ { branch: { id: parallel-docs-audit, parallel: true, children: [ { agent: { id: fleet-docs, prompt: Inspect docs/FLEET.md for command and task-spec coverage., agent_type: review, mode: read_only, profile: reviewer, file_scope: [docs/FLEET.md] } }, { agent: { id: workflow-docs, prompt: Inspect docs/WORKFLOW_AUTHORING.md for Workflow authoring coverage., agent_type: review, mode: read_only, profile: reviewer, file_scope: [docs/WORKFLOW_AUTHORING.md] } } ] } }, { reduce: { id: readiness-summary, inputs: [fleet-docs, workflow-docs], prompt: Summarize the exact docs gaps and the safest next edit. } } ] });节点类型与 fleet 档案引用当前 Workflow 支持的节点包装器为agent、branch、sequence、reduce、teacher_review、loop_until、cond、expand。其中agent.profile指名一个 fleet 名册档案Agent 上的显式字段会覆盖档案默认值。这一点在 Rust 侧有对应的 lowering 逻辑branch/sequence/loop_until会递归归一化叶子节点的 profile见 crates/workflow/src/js_authoring.rs。档案名在编译期会被 trim 并转小写且必须是单一 token不含空白、引号或保存的名册在派发时刻解析。原始 JSON IRkind/spec也仍然合法。模型可见的 workflow 工具与--fleet旗标模型侧的workflow工具可以从内联源码或source_path启动、运行、检查或取消一个 workflow并支持三种兼容入口InputWhen to useplan结构化的 goal / phases / children首选 Agent 路径script由模型持有的短内联 JSsource_pathworkspace 内纳入版本库的.workflow.js/.workflow.ts此外docs/FLEET.md 记录了一个承重的连接面codewhale workflow run --fleet name旗标允许 workflow 运行选择一个命名 fleet。当 Codewhale 走这条路径、且 workflow 会启动多个 worker 或触碰文件时请先让它展示计划再放行。验证门禁这些约束保证 Workflow 不会变成第二个执行者Workflow 不会成为拥有自己 shell 或文件系统权威的第二个执行者。Workflow→Runtime 的启动校验在 lowering 到所选 worker 之前套用一套保守默认形状单个 Workflow run 最多1_000个 worker Agent 总量同时最多16个存活 Agent更大的群体在宿主机每 run 并发门禁上排队阻塞直到空出存活槽位Workflow IR 结构嵌套深度不超过5Runtime 子委托默认3层另有最大8层硬上限opt-in该执行预算独立于 Workflow IR 形状loop_until必须带max_iterations动态expand节点必须带max_children和模板。这些限制把总体规模与瞬时并发区分开一个合法的 1_000 Agent Workflow 也可以经由更小的 Runtime worker 池逐渐排空。模型选择逐成员进行——例如一个 DeepSeek preset 可以为编排者建议deepseek-v4-pro、为周边 worker 建议deepseek-v4-flash但任何槽位在需要时都可被用户或 Agent 覆盖。可以用仓库提供的验证命令确认 lowering 契约未回归cargo test -p codewhale-workflow --locked javascript见 docs/WORKFLOW_AUTHORING.md 的 Verification 一节。5. 自然语言入口先出规格再放行今天的理想 prompt 是Draft a fleet task spec for this goal, but do not run it yet. Show the proposed tasks, worker profiles, writable paths, expected artifacts, scorers, and security policy. Keep secrets disabled unless I explicitly grant them.审阅生成的规格后把它保存为tasks.json再运行上文第 3 节的 fleet 命令。对于 workflow则请 Codewhale 起草一份.workflow.js、先展示计划并且只有在批准之后才走 workflow 工具路径。这个审阅步骤是有意为之它确保在持久 worker 启动之前provider 路由、DeepSeek 或其他模型支持、可写路径、网络访问与 secret 使用都保持显式、可见、可确认。附一页式参考与延伸阅读常用命令面CLI ↔/fleet同契约codewhale fleet init/fleet run tasks.json --max-workers 4/fleet status/fleet inspect id/fleet logs id/fleet artifacts id/fleet interrupt id/fleet restart id/fleet resume run-id/fleet stop --allTUI 内/fleet setup打开档案向导/fleet list|status|interrupt|resume走持久账本控制面。想要一个不调模型、CI 安全的自动化验证运行cargo test -p codewhale-tui --bins fleet::executor想用真实codewhale execworker 跑端到端需 provider 凭证用codewhale fleet run docs/examples/fleet-dogfood.toml --max-workers 2 --once只排一次队并手动fleet status/inspect/logs检查。继续深入当前仓库概念与命名边界docs/FLEET.md、docs/WORKFLOW_AUTHORING.md、docs/AUTOMATIC_WORKFLOWS.md真实任务规格docs/examples/fleet-dogfood.toml真实 Workflow 示例workflows/issue_audit.workflow.js协议类型定义crates/protocol/src/fleet.rs执行器与适配器crates/tui/src/fleet/executor.rs、crates/tui/src/fleet/manager.rsJS lowering 与校验crates/workflow/src/js_authoring.rs、crates/workflow/src/elevation.rs控制面契约测试crates/tui/src/commands/groups/core/fleet.rs。当任务具备多阶段顺序 门禁 共享预算 确定性扇入时用 Workflow当工作独立、并行、隔离、长时时直接交给 fleet worker其余普通多 Agent 对话直接说即可——这正是 Codewhale 期望你在生产中保持的分寸。【免费下载链接】CodewhaleOpen-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考