企业官网建设流程全解析

CodeWhale子代理教程：用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

CodeWhale 是一款用 Rust 编写的开源终端编码智能体（coding agent）。它的子代理（Sub-agent）机制允许主代理通过内置的agent工具，把探索、审查、验证等后台任务委托给多个"小鲸鱼"并行处理——你只需说一句自然语言，就能让多个子代理同时开工，父代理负责最终决策与汇总。本教程面向新手，带你从零看懂并上手 CodeWhale 子代理。

🐋 什么是 CodeWhale 子代理？

可以把它想象成一个"主编程师带团队干活"的模式：

• 父代理（Parent）：理解你的真实需求，做架构、安全与验收决策，最后向用户汇报；
• 子代理（Sub-agent）：领到一份聚焦的任务简报，在后台独立运行自己的模型回合、调用工具、产出证据，完成后把结果交回父代理。

关键特性一览：

完整的机制说明见官方文档：docs/SUBAGENTS.md（英文版）和 docs/zh_hans/SUBAGENTS.md（简体中文版）。

🚀 30 秒上手：一句话委托后台任务

你不需要记任何命令。在 CodeWhale 会话里直接用自然语言提出委托需求即可，例如：

"派一个 explore 子代理，只读地帮我找出Foo的每个调用点，给我文件:行号证据。"

父代理会自动调用agent工具、选择合适的角色、启动后台 worker，并在你继续对话时并行等待其完成。想手动查看各角色的实际路由配置，可以在会话里输入/config subagents status。

💡 小贴士：一次可以委托多个相互独立的子代理（比如同时开 2-3 个 explore 去摸不同模块），它们会并行执行。

🧭 8 个内置角色：按需挑选"岗位"

agent工具的type字段决定子代理的工作姿态。每个角色不只是标签，而是对"写不写文件、能不能跑 shell"的明确约定：

何时选哪个？简单口诀：

• 任务是"把整件事做完" →general
• 需要证据再决策 →explore（便宜、快，适合并行）
• 已有变更要打分 →reviewer
• 变更已定稿只需落地 →implement
• 要权威的通过/失败结论 →test

各角色的完整系统提示词在 crates/tui/src/tools/subagent/mod.rs 中（搜索*_AGENT_INTRO），旧的拼写如scout、builder、review仍可作为别名被解析。

📋 写好一份委派简报（Delegation Brief）

子代理干得好不好，很大程度取决于父代理交给它的简报。官方推荐的结构化简报包含：问题（QUESTION）、范围（SCOPE）、已知事实（ALREADY_KNOWN）、投入档位（EFFORT: quick/medium/thorough）、停止条件（STOP_CONDITION）和输出格式（OUTPUT）。

官方内置的delegate技能对"什么该自己做、什么该委托"给出了黄金法则（见 crates/tui/assets/skills/delegate/SKILL.md）：

• 保留在父代理：理解用户真实需求、架构/安全/发布风险决策、跨模块集成、最终验收；
• 委托给子代理：有界的只读探索、边界清晰的机械改动、聚焦的测试/lint 运行、样板代码生成；
• 不要委托：一两步就完的小事、模糊的产品决策、没有验收标准的危险操作、最终验证。

弱提示 vs 强提示的对比：

⚡ 并发、深度与预算：后台任务有多"猛"？

子代理默认火力很足，但全部有界可控：

常用调节项都写在~/.codewhale/config.toml的[subagents]段里（并发、token_budget、max_steps、wall_time_secs等），常量定义在 crates/tui/src/config/subagent_limits.rs。

进阶玩法还包括：

• Worktree 隔离：给子代理加worktree: true，CodeWhale 会为它创建独立的 git worktree 和分支（默认codex/agent-<name>-<id>，位于.codewhale-worktrees/），多个子代理并行改代码互不干扰，父仓库保持干净；
• 上下文分叉：fork_context: true让子代理继承父代理当前的对话前缀与 To-do 快照，适合"接着上文继续做"的任务；独立探索则建议用全新会话；
• 按角色配模型：[subagents.roles.<role>]可为不同角色固定不同的 provider/模型，比如让reviewer用大模型、explore用便宜快速的模型。

🔍 怎么检查进度、结果和失败？

子代理的生命周期是：Pending → Running → Completed / Failed / Cancelled / Interrupted / BudgetExhausted。

• 查看名单：agent(action="status")返回当前会话所有子代理的状态页（深度、耗时、token 用量、最近活动）；
• 追问/续跑：followup可唤醒运行中的子代理，或从可继续的检查点恢复被中断的任务；
• 交付文件：在委托时声明deliverables，完成后会自动核对文件是否存在、非空、在作用域内，给出present / missing / empty / out_of_scope等判定；
• 输出契约：非 explore 子代理的汇报固定以五个小节收尾——SUMMARY（做了什么）、EVIDENCE（文件:行号证据）、CHANGES（改了哪些文件）、RISKS（风险）、BLOCKERS（卡点）；explore 角色只交SUMMARY+EVIDENCE。

⚠️ 注意：子代理的汇报本质是"自报"。父代理（或你）在依赖其结论前，应复核关键EVIDENCE引用和verification.status，必要时本地再跑一次测试。

❓ 新手常见问题

Q1：子代理会拿到比父代理更多的权限吗？不会。权限是"求交集"的：子代理的有效写/网/ shell 权限永远是父代理当前姿态的上限之内，拒绝列表还会向上合并，角色名或标志都变不出新权限。

Q2：父代理回完一句话，后台子代理会被杀掉吗？不会。健康的子代理在父代理正常响应后继续运行，完成通知通过同一个 Engine 收件箱返回，还可以唤醒父代理进入下一回合；显式中断/取消始终有效。

Q3：任务必须扛过进程重启、休眠或远程执行，怎么办？会话内委托的agent适合短期工作；需要持久化的长跑任务，优先使用 Fleet 或 Workflow 支撑的 fleet 运行（见 docs/FLEET.md 与 docs/WORKFLOW_AUTHORING.md）。

Q4：子代理的记忆是隔离的吗？子代理保留各自的私有 To-do 列表，互不可读；当记忆功能开启时（[memory] enabled = true），它们可以通过remember工具向父代理共享的记忆存储追加持久备注。

📚 延伸阅读

• 官方子代理文档（英文）：docs/SUBAGENTS.md
• 官方子代理文档（简体中文）：docs/zh_hans/SUBAGENTS.md
• 内置 delegate 委托技能：crates/tui/assets/skills/delegate/SKILL.md
• 子代理运行时源码：crates/tui/src/tools/subagent/mod.rs
• 并发/准入限制配置：crates/tui/src/config/subagent_limits.rs

一句话总结：在 CodeWhale 中，把"要证据的活儿"交给子代理，把"做决策的活儿"留在父代理。用一句话委托、用角色定姿态、用简报划边界，你就能在终端里跑起一支并行工作的 AI 工程小队。🐋

【免费下载链接】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