Codewhale 文档

查找准确的使用说明。

从安装和首次运行开始,或者直接查找模式、权限、工具、提供商、Fleet、MCP 与运行时 API。这些页面就是正式的产品文档;每页都链接仓库中的源文档,方便查阅完整细节。

Fleet 与 Workflow

Fleet 是面向持久多 worker 运行的本地优先控制平面。它不是独立的执行引擎:一个 Fleet worker 就是一次由 Fleet 启动并持久跟踪的 codewhale exec 无头运行。当工作需要重试、睡眠/重启后存活、远程执行、收据或可审计的台账时,使用 Fleet 而不是短寿命的 agent 扇出。

Fleet

谁来做工作:配置好的 worker、角色、模型、主机和信任边界。

Workflow

工作按什么顺序进行:阶段、门禁、预算、回放和汇总。

Lane

一个正在运行的 Workflow 实例及其实时进度。

Runtime

Lane 在哪里、如何执行:本地或远程进程、提供商路由、沙箱和 API 边界。

运行一次 Fleet

Fleet 状态存放在工作区的 .codewhale/fleet.jsonl 台账中,worker 日志在 .codewhale/fleet/ 下。codewhale fleet resume <run-id> 是重启恢复命令:它重放台账、调和停止心跳的在途租约,且幂等——在管理进程退出、笔记本睡眠或运行时重启后都可以安全运行。

codewhale fleet init
codewhale fleet run tasks.json --max-workers 4
codewhale fleet status
codewhale fleet inspect <worker-id>
codewhale fleet logs <worker-id>
codewhale fleet interrupt <worker-id>
codewhale fleet resume <run-id>
codewhale fleet stop --all

注意两个同名状态面:TUI 里的 /fleet status(或 /subagents)只显示当前交互会话的子 Agent;shell 里的 codewhale fleet status 才读取持久 Fleet 台账。

角色与 /fleet setup

/fleet setup 打开一个渐进式向导,编写可复用的 agent 团队档案:一次只做一个选择——角色,然后是模型(可继承,或任何已配置提供商的具体模型),再是思考档位(inherit、off、low、medium、high、max 或 auto)——最后在审查页确认完整姿态(路由、思考、权限、工具、范围与审查策略)。档案可以写在项目级(.codewhale/agents/<role>.toml,随仓库走)或个人级($CODEWHALE_HOME/agents/<role>.toml,本机所有仓库可用);同名项目档案优先。档案的存储范围不会扩大运行操作的权限。

Workflow 编排

普通多 Agent 工作不需要 Workflow:在 Operate 里直接发消息,需要并行、隔离或长时间工作时让 Codewhale 优先委派后台 worker 即可。只有当工作需要有序阶段、门禁、共享预算、回放或确定性汇总时才用 Workflow。Workflow 脚本是纯协调者:没有自己的文件系统和 shell,真正的工作由它启动的子 Agent 完成。脚本以编译专用的声明式 JS 子集编写,降低到类型化的 WorkflowSpec 后由 Rust 校验与执行;import、fetch、process、eval、async/await 等会产生副作用的写法会被编译器拒绝。

默认校验边界:每次 Workflow 运行最多 100 个 worker Agent、最多 5 层递归 Fleet 环、循环必须声明 max_iterations、动态 expand 节点必须声明 max_children 和模板。这些是数量上限而非并发要求——一个合法的 100 Agent Workflow 仍会按配置好的 Fleet worker 池排水执行。Workflow JS 沙箱内单 run 最多 16 个并发存活 Agent、整个 VM 生命周期最多 1,000 次启动。

来源文档:docs/FLEET.md, docs/WORKFLOW_AUTHORING.md · 更新时请同步修改 docs-map.ts。