Codewhale fleet-manager 技能实战用类型化控制面为 Fleet 多 Worker 运行做状态分诊与安全升级【免费下载链接】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当 Codewhale 以“多 Worker 耐久运行fleet run”方式并行执行任务时谁在后台负责看护这些 Worker答案在仓库内置的一等公民系统技能fleet-manager中它把codewhale fleetCLI、/fleet命令与 Runtime API 抽象为一套类型化typed、可记账ledgered的控制面指导 manager 角色按固定循环对 Worker 状态分类、选择“最窄且安全”的动作、留下可追溯的回执或起草升级信息。读完本文你将掌握如何遵守技能划定的权限边界、如何执行六步分诊循环、四类失败状态如何区分、何时允许restart何时必须escalate以及标准升级草稿与回执的书写形状——并能从源码层级理解这套规则背后的 ledger 与调度实现。一、技能定位manager 角色内置的操作手册在 Codewhale 的术语体系中Fleet不是执行层而是“本地优先、可持久化”的多 Worker 运行的名单roster与成员选择层它决定谁参与、谁是操作者真正的执行与授权由被委托的协调器delegated coordinator与 Runtime 完成参见 docs/FLEET.md。fleet-manager正是为“扮演 fleet run 的 manager 角色”而设计的系统技能。其技能描述frontmatter写明了触发场景Use when managing, triaging, restarting, escalating, or summarizing Codewhale fleet runs and workers.当需要管理、分诊、重启、升级或汇总 Codewhale fleet 运行与 Worker 时使用。技能正文crates/tui/assets/skills/fleet-manager/SKILL.md则直截了当地给出了 manager 的全部职责你的工作是对 Worker 状态进行分类、选择最窄的安全类型化动作并留下一份已记账的回执ledgered receipt或一份安全的升级草稿escalation draft。也就是说manager 永远只做三件事——分类classify→ 最小干预act→ 留痕receipt / draft绝不越权执行。1.1 它是一等公民系统技能该技能不是零散文本而是被 Codewhale TUI 的“系统技能安装器”静态打包进二进制中的在 crates/tui/src/skills/system.rs 第 25 行FLEET_MANAGER_BODY通过include_str!(../../assets/skills/fleet-manager/SKILL.md)直接嵌入第 102–106 行的BUNDLED_SKILLS数组登记了它introduced_in: 4即自第 4 代捆绑技能起随系统技能一起自动安装官方 fleet 文档在 docs/FLEET.md 的 “Manager-Agent Runbook” 一节明确指出“The bundledfleet-managerskill mirrors this runbook for manager agents. It is a first-party system skill and should be discoverable through the normal skill registry after system skills are installed or refreshed.”因此当系统技能安装或刷新后任意 manager 上下文都可以通过普通技能注册表发现它。二、权限边界Authority Boundary先立规矩再谈操作技能把“哪些表面可以动、哪些绝对不许碰”写成了铁律。这是整个技能安全性的地基核心原则是能用类型化表面就不要去翻底层文件。边界条款具体要求优先使用类型化表面优先codewhale fleet status、inspect、logs、artifacts、interrupt、restart、stop以及 Runtime API 端点而不是在 shell 里手动翻找禁止直接读底层除非类型化命令或 API 缺少必要证据否则不得直接读取.codewhale/fleet.jsonl、宿主机日志或远程文件禁止主动外发消息除非用户或运行配置显式授权发送否则不得发送 Slack、webhook、PagerDuty、Email 或聊天消息只能起草摘要脱敏任何汇总或升级信息中永远不得包含 secrets、token、webhook URL、routing key、完整 prompt 或超大日志。2.1 为什么这些文件不能直接读源码给出了答案禁止直读.codewhale/fleet.jsonl并非洁癖而是因为该 ledger 是整个 fleet 的事实来源source of truth。从 crates/tui/src/fleet/manager.rs 可以看到FleetManager::open第 228 行起通过FleetLedger::open(workspace)打开工作区 ledger所有调度、心跳、租约、产物、回执都以追加事件的方式写入 ledger并由rebuild_state()重建投影状态快照FleetStatusSnapshot第 145–161 行一次性汇总queued / running / completed / partial / failed / restarted / escalated / transport_failed / task_failed / verifier_failed / cancelled / stale等计数器——这些正是codewhale fleet status输出的数据来源。换句话说ledger 是写路径命令执行时追加而 status/inspect 等命令是读路径按类型重建。直接去 grep 一个还在被并发追加的 JSONL 文件得到的可能是撕裂状态或未经协调器归约的中间记录这正是技能禁止 manager 直读它的工程理由。类似地logs只输出**有界bounded**日志产物内容、artifacts只列出产物引用而不内嵌大载荷。2.2 类型化表面在哪里定义fleet 是双重表面共享同一个控制面契约CLIcodewhale fleet …实现位于 crates/tui/src/commands/groups/core/fleet.rs经 crates/tui/src/fleet/control.rs 的execute_fleet_control派发Slash 命令/fleet …Runtime API/v1/fleet/...端点与 CLI 共用 manager 控制逻辑动作同样写入 fleet ledger端点清单见 docs/FLEET.md 的 “Status Surfaces” 一节并有 crates/tui/src/runtime_api/tests.rs 等测试覆盖。三、Triage Loop六步分诊循环技能的正文操作核心是一段固定的分诊循环。任何一次 manager 介入都应完整走完这六步而不是“看到报错就重启”1. 定位 run 与 worker —— 从用户请求、run 回执或 fleet status 输出中确定对象 若用户未点名 worker先执行 codewhale fleet status。 2. 检查 worker —— 使用 codewhale fleet inspect worker-id 或对应的 Runtime API worker 端点。 3. 查看有界证据 —— codewhale fleet logs worker-id 与 codewhale fleet artifacts worker-id 汇总时只概括 artifact 引用refs不贴完整载荷。 4. 先分类后行动见下方四类状态。 5. 选择一个类型化动作restart / interrupt / stop / escalate / no-op。 6. 在响应中记录结果分类、已采取或已起草的动作、 证据命令、artifact 引用与下一个 owner。第 4 步的“先分类、后行动”是整个循环的灵魂动作必须由分类推导分类必须先于动作完成。这一工程语义也体现在源码中——FleetStatusSnapshot里把transport_failed、task_failed、verifier_failed分开计数让分类可以被精确检验codewhale fleet status会把这三类失败来源分别呈现。四、四类状态分类判断“到底坏在哪一层”技能将 Worker 状态归入四类判定依据不是情绪而是证据分类判定特征原文定义典型示例transient failure瞬时失败transport 错误、超时、心跳过期、宿主机不可用或可重试的 provider/网络故障Worker 心跳停滞、SSH 连接中断、上游 API 抖动task failure任务失败Worker完成了任务但结果错误、缺少必需产物、或上报领域错误交付了错误补丁、报告文件缺失verifier failure验证器失败scorer/验证器失败或与 Worker 结果意见不一致打分器超时、正则与产出不匹配needs-human需要人工权限缺失、涉密边界不安全、破坏性动作、重启次数耗尽、产品决策有歧义或产物与验证器互相冲突Worker 索要 secret、需要对主干做破坏性变更在 docs/FLEET.md 的 “Manager-Agent Runbook” 中可以看到与技能完全一致的分类清单二者互为印证transient failure是“不改变任务也大概率能自愈”的情形task failure是“任务本身的产出不对”verifier failure是“结果存在但验证层不认账”needs-human则是 manager 从类型化证据无法自行消解的交叉口。五、选择动作分类到动作的决策映射分类完成之后第 5 步要求只选一个类型化动作。技能给出的映射如下瞬时失败 还有重试预算→codewhale fleet restart worker-id瞬时失败但重试不安全→ 起草升级信息并标记needs-human任务失败→ 保留产物、汇总失败原因默认不重启——除非任务规格说明“重试可产生新证据”验证器失败→ 先检查 scorer 输入与产物若无法通过类型化动作修正验证器则升级needs-human→ 不自动重启起草一份简洁升级信息。动作集合与源码的 manager 控制严格对应interrupt/restart/stop/resume都由 crates/tui/src/fleet/manager.rs 中围绕 ledger 的实现驱动其中resume_run第 661 行起是重启恢复专用动作它回放 ledger、通过共享调度器恢复语义调和“心跳已停但租约仍在”的孤儿 in-flight lease预算内重试否则失败并升级不启动任何新工作、可安全重复执行——对应 CLI 的codewhale fleet resume run-id。5.1 常用命令速查供 manager 引用codewhale fleet status # 汇总统计排队/运行/完成/部分/失败/重启/升级/取消/stale 及失败来源 codewhale fleet inspect worker-id # 单 Worker 状态目标、role、host、心跳、最新事件、产物引用、告警状态 codewhale fleet logs worker-id # 打印有界日志产物内容 codewhale fleet artifacts worker-id # 列出产物引用不内嵌大载荷 codewhale fleet interrupt worker-id # 中断当前任务不安全继续 / 用户显式要求取消时 codewhale fleet restart worker-id # 仅 CLI 支持重新租约该任务并驱动 manager 循环到结束 codewhale fleet stop --all # 停止整个 run codewhale fleet resume run-id # 重启恢复回放 ledger、调和 stale lease不新建 run一个值得注意的细节codewhale fleet restart是CLI-only——/fleet restart不会静默地做一个“更小的事”而是返回surface_not_supported并指名 CLI 命令见 docs/FLEET.md。六、Restart vs Escalate重启还是升级的完整判据技能给出了两套“全真 / 任一为真”的判定清单manager 应逐条核对而非凭感觉。只有以下条件全部为真才允许 restart失败很可能是瞬时transient的任务是幂等的或运行策略允许重试重试预算还有剩余不涉及 secret、权限或破坏性动作边界上一次尝试产出了足够的回执数据可以解释这次重启。只要命中以下任一情形就必须 escalate重启预算已耗尽Worker 索取 secrets 或新的权限产物显示数据丢失、损坏或破坏性副作用验证器与任务结果冲突且你无法从类型化证据自行消解重启后同一失败再次出现需要人类做出产品/发布决策。这套规则与 docs/FLEET.md 的 runbook 完全同源也与源码调度语义一致manager 的默认 stale 判定窗口为 300 秒DEFAULT_STALE_AFTER_SECONDS: u64 300见 crates/tui/src/fleet/manager.rs 第 38 行重试与升级的边界最终由调度器按 heartbeat timeout 与 retry budget 统一裁决——预算内重试预算外 fail escalate。七、Safe Escalation Draft标准升级草稿模板当需要把问题交给 Slack 或 PagerDuty 上的人类时技能要求使用固定的草稿形状。日志最多保留三行短摘录或一个 artifact 引用全文不得含 secretCodewhale fleet needs attention Run: run-id Worker: worker-id Task: task-id or unknown Classification: transient failure | task failure | verifier failure | needs-human Reason: one sentence, no secrets Latest typed evidence: codewhale fleet inspect worker-id; codewhale fleet artifacts worker-id Safe log excerpt: 3 lines max or see artifact ref Requested decision: restart approval | verifier review | task owner review | permission decision注意模板里的两个关键设计Latest typed evidence给出的是“可复现的检查命令”而不是截图或整段日志——接手的任何 manager 或人都能用同样命令拿到一致证据Requested decision是显式的决策请求把“你需要人类拍板什么”压缩成一个枚举值降低人工处理成本。fleet 的告警层也贯彻了同一原则事件路由按类型化事件类stale、restart_exhausted、needs_human、budget_exceeded、verifier_failed、run_completed而非日志字符串匹配告警适配器配置只存环境变量名不存 secret 值ledger 只记录slack/webhook/pagerduty之类的审计标签任务规格在入账时会脱敏 webhook URL 与 routing key详见 docs/FLEET.md 的 “Alerts” 一节。八、Post-Run Receipt每条响应都必须以回执收尾技能要求 manager 的每一条Fleet Manager 响应都以一段紧凑回执结束。这保证任何一次人工介入都可在 ledgable 层面被追溯Fleet receipt Run: run-id Workers checked: count/list Classification: state Action: restart/interrupt/stop/escalation draft/no-op Ledger expectation: typed action should be recorded | draft only, no send Artifacts reviewed: refs Follow-up owner: manager | task owner | human其中两行尤其值得注意Ledger expectation区分“该类型化动作应被记录进 ledger”与“仅草稿未发送”——把 manager 的意图与系统的持久化事实对齐防止“以为发了其实只是草稿”Follow-up owner明确了下一个负责方闭环到人/角色。这个回执形态与 docs/FLEET.md “Manager-Agent Runbook” 对 post-run 汇总的要求一致应包含 run id、检查过的 workers、分类、采取或起草的类型化动作、预期 ledger 效果、审阅过的 artifact 引用与下一个 owner并“链接 artifact 引用而不是整段复制日志或记录”。九、落地建议如何把技能接进真实运行流程要把这套技能从“文档规则”变成可执行工作流建议配合以下仓库资源一起使用理解完整架构再分诊先读 docs/FLEET.md弄清Fleet成员名单/选择、Workflow编排顺序、Runtime执行与授权三层分工以及“身份解析先于权限评估、权限只能收窄不能换人换路由”的负载承载原则。用真实任务规格练习参照 docs/FLEET_WORKFLOW_TUTORIAL.md 的第 2 步书写tasks.jsonJSON/TOML 均可仓库还提供了可直接审阅的示例 docs/examples/fleet-dogfood.toml执行codewhale fleet run tasks.json --max-workers 4再开第二个终端跑 status/inspect/logs/artifacts 体验“有界证据”与类型化动作。把 manager 规则写成场景技能正文中的分类清单、restart 五判据、escalate 六判据可以直接改写成操作 checklistsneeds-human与告警事件类一一对应适合接入真实告警路由。注意控制面契约跨双表面的命令语义、read-vs-write 权限、receipt 格式与类型化未知值在 docs/COMMAND_CONTROL_PLANE.md 中有更完整的契约说明。十、小结三层防线下的最小干预原则回看整份技能fleet-manager真正的价值不在于“重启一个 Worker”这个动作本身而在于它为 manager 角色搭起了三层防线表面防线只用类型化命令与 API不直读 ledger、日志与远程文件决策防线先分类后行动restart 需五项全真、escalate 只需一项命中留痕防线升级信息走固定脱敏模板每条响应都以Fleet receipt收尾并声明 ledger 预期。这套规则与 crates/tui/src/fleet/manager.rs 的 ledger-first 实现身份冻结、租约心跳、预算内重试、预算外升级一脉相承manager 是被规则约束的看护者而不是拥有 shell 权限的急救员。当你下一次看到 fleet run 里出现 stale worker 或 verifier 冲突时按技能给出的顺序行动即可——先 inspect再分类然后要么给一次有充分回执依据的 restart要么起草一封不携带任何 secret 的升级信息。文中所有命令与行为均以当前仓库内技能与文档为准适用前提是已完成codewhale fleet init且系统技能已安装/刷新。【免费下载链接】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），仅供参考