返回 CodeWhale
page.tsx
根目录 / web / app / [locale] / docs / subagents / page.tsx
1 import { buildPageMetadata } from "@/lib/page-meta";
2
3 export async function generateMetadata({ params }: { params: Promise<{ locale: string }> }) {
4 const { locale } = await params;
5 const isZh = locale === "zh";
6 return buildPageMetadata({
7 path: "/docs/subagents",
8 locale,
9 title: isZh ? "子 Agent · Codewhale 文档" : "Sub-Agents · Codewhale Docs",
10 description: isZh
11 ? "agent 工具、Fleet 角色、上下文分叉、worktree 隔离和并发上限。"
12 : "The agent tool, Fleet roles, context forking, worktree isolation, and concurrency caps.",
13 });
14 }
15
16 export default async function SubagentsPage({ params }: { params: Promise<{ locale: string }> }) {
17 const { locale } = await params;
18 const isZh = locale === "zh";
19 const bodyClass = isZh
20 ? "text-ink-soft leading-[1.9] tracking-wide"
21 : "text-ink-soft leading-relaxed";
22 const roles = isZh
23 ? [
24 { name: "worker", detail: "灵活执行父级交代的多步任务；可写、可用 shell。默认角色。" },
25 { name: "scout", detail: "只读，快速摸清相关代码——例如“找出 Foo 的所有调用点”。" },
26 { name: "planner", detail: "分析并产出策略，不执行——“设计迁移方案，不要动手”。" },
27 { name: "reviewer", detail: "只读审查并按严重度打分——“审一遍这个 PR 的 bug”。" },
28 { name: "builder", detail: "以最小改动落地一个明确的变更；可写、可用 shell。" },
29 { name: "verifier", detail: "运行测试和校验并汇报结果，不写代码。" },
30 { name: "consultant", detail: "只读的高推理力度顾问，用于判断类问题和设计评审。" },
31 { name: "custom", detail: "手工指定狭窄的工具白名单，用于锁定的派发。" },
32 ]
33 : [
34 { name: "worker", detail: "Flexible multi-step execution of the parent's brief; writes and shell allowed. The default role." },
35 { name: "scout", detail: "Read-only, maps the relevant code fast — “find every call site of Foo.”" },
36 { name: "planner", detail: "Analyse and produce a strategy without executing — “design the migration; don't run it.”" },
37 { name: "reviewer", detail: "Read-and-grade with severity scores — “audit this PR for bugs.”" },
38 { name: "builder", detail: "Land a specific change with minimal edits; writes and shell allowed." },
39 { name: "verifier", detail: "Run tests and validation gates and report the outcome; no code edits." },
40 { name: "consultant", detail: "Read-only high-reasoning counsel for judgement calls and design critique." },
41 { name: "custom", detail: "An explicit narrow tool allowlist for locked-down dispatch." },
42 ];
43
44 return (
45 <section className="space-y-10">
46 <section id="overview" className="scroll-mt-32">
47 <h2 className="font-display text-3xl mb-1">{isZh ? "子 Agent" : "Sub-Agents"}</h2>
48 <p className={`${bodyClass} mt-3`}>
49 {isZh
50 ? "父会话通过 agent 工具启动一个有明确职责的子 Agent，并立即拿回 agent_id、compact 收据和 transcript 句柄；子 Agent 在后台运行。子 Agent 默认继承父级的工具注册表，但它们是叶子 worker：不会再拿到 agent 或嵌套生命周期工具。agent 启动的是分离的后台工作——取消父回合会停止父级的等待路径，但不会杀死已经启动的子运行。"
51 : "A parent session launches one focused sub-agent through the agent tool and immediately gets back an agent_id, a compact receipt, and a transcript handle while the worker runs in the background. Sub-agents inherit the parent's tool registry by default, but they are leaf workers: they do not receive agent or nested lifecycle tools. agent launches detached background work — cancelling the parent turn stops the parent's wait path, but it does not kill already-opened child runs."}
52 </p>
53 <p className={`${bodyClass} mt-3`}>
54 {isZh
55 ? "对于必须跨进程重启、睡眠或远程执行存活的工作，优先选择 Fleet 或 Workflow 支撑的 Fleet 运行，而不是会话内的短寿命 agent 调用。"
56 : "For work that must survive process restarts, sleep, or remote execution, prefer Fleet or a Workflow-backed fleet run over a short in-session agent call."}
57 </p>
58 <div className="hairline-t mt-6">
59 {roles.map((row) => (
60 <section key={row.name} className="py-4 hairline-b">
61 <h3 className="font-display text-lg">{row.name}</h3>
62 <p className={`${bodyClass} mt-1 text-sm`}>{row.detail}</p>
63 </section>
64 ))}
65 </div>
66 </section>
67
68 <section id="fork" className="scroll-mt-32">
69 <h2 className="font-display text-2xl mb-1">{isZh ? "上下文分叉" : "Context forking"}</h2>
70 <p className={`${bodyClass} mt-3`}>
71 {isZh ? (
72 <>
73 <code className="inline">agent</code> 默认开启全新会话：子 Agent 只拿到角色提示词和你给的任务。当任务依赖父
74 transcript 里已有的决定、文件、待办或计划状态时，用{" "}
75 <code className="inline">fork_context: true</code>
76 ——运行时在可用时保持父级前缀逐字节一致（保留前缀缓存复用），追加一份结构化状态快照，再把子
77 Agent 的角色说明和任务放在末尾。独立探索用新会话，延续、审查、总结或压缩类工作用分叉会话。
78 </>
79 ) : (
80 <>
81 <code className="inline">agent</code> starts fresh by default: the child gets its role
82 prompt plus the task you pass. When the task depends on decisions, files, todos, or plan
83 state already in the parent transcript, use{" "}
84 <code className="inline">fork_context: true</code> — the runtime keeps the parent's
85 request prefix byte-identical where available (preserving prefix-cache reuse), appends a
86 structured state snapshot, then adds the sub-agent role instructions and task at the tail.
87 Use fresh sessions for independent exploration and forked sessions for continuation,
88 review, summarization, or compaction work.
89 </>
90 )}
91 </p>
92 </section>
93
94 <section id="worktree" className="scroll-mt-32">
95 <h2 className="font-display text-2xl mb-1">{isZh ? "Worktree 隔离" : "Worktree isolation"}</h2>
96 <p className={`${bodyClass} mt-3`}>
97 {isZh ? (
98 <>
99 并行编辑通道用 <code className="inline">worktree: true</code> 启动：Codewhale
100 为子 Agent 创建新的 git worktree 和分支（默认{" "}
101 <code className="inline">codex/agent-&lt;name&gt;-&lt;id&gt;</code>，检出在父仓库旁的{" "}
102 <code className="inline">.codewhale-worktrees/</code> 下），父检出保持干净。隔离不等于写权限：只带
103 prompt 的 worker 从只读开始；要写代码的子 Agent 还需声明{" "}
104 <code className="inline">write_authority</code> 和至少一个规范化的{" "}
105 <code className="inline">write_roots</code>、<code className="inline">exact_files</code>{" "}
106 或 <code className="inline">coordination_contracts</code>
107 值；重叠的共享写声明会在任何改动之前失败。
108 </>
109 ) : (
110 <>
111 Launch parallel edit lanes with <code className="inline">worktree: true</code>: Codewhale
112 creates a fresh git worktree and branch for the child (default{" "}
113 <code className="inline">codex/agent-&lt;name&gt;-&lt;id&gt;</code>, checked out beside the
114 parent repo under <code className="inline">.codewhale-worktrees/</code>) so the parent
115 checkout stays clean. Isolation is not write authority: a prompt-only worker starts
116 read-only, and a writer also declares{" "}
117 <code className="inline">write_authority</code> plus at least one normalized{" "}
118 <code className="inline">write_roots</code>, <code className="inline">exact_files</code>,
119 or <code className="inline">coordination_contracts</code> value. Overlapping shared write
120 claims fail before any mutation.
121 </>
122 )}
123 </p>
124 </section>
125
126 <section id="capacity" className="scroll-mt-32">
127 <h2 className="font-display text-2xl mb-1">{isZh ? "并发上限" : "Concurrency caps"}</h2>
128 <p className={`${bodyClass} mt-3`}>
129 {isZh
130 ? "子 Agent 容量的权威来源是 crates/tui/src/config/subagent_limits.rs：默认配置并发 64，最大配置并发 128，运行加排队的最大准入 1024。这些是容量上限，不是建议把每个槽位都派出去——管理者应使用最小的有效扇出，保持单一汇总负责人，并在汇报整体完成前验证 worker 收据。"
131 : "The sub-agent capacity source of truth is crates/tui/src/config/subagent_limits.rs: default configured concurrency is 64, maximum configured concurrency is 128, and maximum admitted running-plus-queued work is 1024. These are capacity ceilings, not advice to dispatch every slot — a manager should use the smallest useful fan-out, keep a single fan-in owner, and verify worker receipts before reporting combined completion."}
132 </p>
133 </section>
134
135 <section id="source" className="hairline-t pt-8">
136 <p className="text-sm text-ink-mute">
137 {isZh
138 ? "来源文档：docs/SUBAGENTS.md · 更新时请同步修改 docs-map.ts。"
139 : "Source document: docs/SUBAGENTS.md · Update docs-map.ts when changing."}
140 </p>
141 </section>
142 </section>
143 );
144 }
145
145 lines Plain Text