Kimi Code Tower 协议解析:TowerReview 分支审查判定与提交机制实战指南
Kimi Code Tower 协议解析:TowerReview 分支审查判定与提交机制实战指南
Tower 是 agent-core-v2 中实现的多智能体协作协议:一个主控(tower)通过 TowerSpawn 派生出 worker 与 reviewer 子代理,各自在独立的 git worktree 分支上工作,所有协作流量(收件箱、finding、review、mission 更新)只经 Tower* 系列工具流转,落盘到 .tower/ 协议目录。本文聚焦其中负责"审查质量关卡"的 TowerReview 工具:它让被指派的 reviewer 对分支提交正式判定(clean / p1-Nitems / p2-Nitems),把判定写入审查文件并路由下一步动作。读完本文,你将掌握 TowerReview 的完整参数契约、判定语义、权限与轮次规则、分支 tip 盖章机制,以及它与 TowerMerge 合并门禁的联动原理,并能在自己的 Tower 工作区中正确提交审查、处理返工与复审流程。
一、TowerReview 在 Tower 协议中的定位
1.1 审查角色的由来
在 Tower 协议中,一个 build mission 的工作流是:TowerPlan 规划 → TowerSpawn 派出 worker 写代码 → 分支完成后由 reviewer 审查 → 判定通过后由 TowerMerge 合入 base 分支。其中 reviewer 也是通过 TowerSpawn 以 review_target 参数派生的:
- worker:传
mission_id,工具创建 mission worktree 并把完整 mission 文本作为简报; - reviewer:传
review_target,当该分支属于某个 mission 时,简报携带完整 mission 文本(标题、任务、用户原文 context)以及作者在档的 review-request,让审查"对照 mission 意图"而非只看代码健康度;审查者必须通过 TowerReview 提交判定。
从 types.ts 可以看到,花名册(roster)条目用 kind: 'worker' | 'reviewer' 区分角色,reviewer 额外记录 reviewTarget 与 reviewMissionId,这正是权限校验的数据基础。
1.2 工具契约总览
review.md 给出了 TowerReview 的核心语义,可概括为三句话:
- 为被指派审查的分支提交一份审查判定;
- 判定会盖章当前分支 tip——分支随后若发生移动,tower 必须先要求复审才能合并;只有被指派到该目标的 reviewer(或 tower 本身)才能提交,轮次号由系统自动分配;
- 提交结果决定下一步路由:非 clean 判定点名 roster 中的 worker 携审查文件恢复工作以便修复并复审;clean 判定则报告分支已达到合并就绪状态,交给 TowerMerge。
二、TowerReview 参数契约详解
工具的参数定义在 review.ts,由 zod 严格模式(.strict(),不接受未知字段)定义:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
target |
string | 是 | 被指派审查的分支名 |
status |
string | 是 | 判定结果,必须匹配 clean / p1-Nitems / p2-Nitems 正则 |
merge |
enum | 是 | 合并建议:merge / fix-then-merge / hold |
findings |
string | 是 | 完整 finding 正文(Markdown);clean 时写 none |
checks |
string[] | 否 | 已核验的检查清单项(如 "tests pass"、"no secrets") |
decision |
string | 是 | 判定背后的推理过程 |
对应的 JSON Schema 形态(由 toInputJsonSchema 生成)形如:
{
"type": "object",
"properties": {
"target": { "type": "string" },
"status": { "type": "string", "pattern": "^(clean|p[12]-\\d+items)$" },
"merge": { "enum": ["merge", "fix-then-merge", "hold"] },
"findings": { "type": "string" },
"checks": { "type": "array", "items": { "type": "string" } },
"decision": { "type": "string" }
},
"required": ["target", "status", "merge", "findings", "decision"],
"additionalProperties": false
}
工具在 reviewTool.ts 中实现:resolveExecution 声明 description: Submitting tower review for ${args.target}: ${args.status},执行时经 runTowerTool 包装(support.ts 会把 TowerProtocolError/GitError 转成 isError: true 的输出,避免把协议错误当正常结果),并调用 store 的 submitReview 完成落盘。
2.1 status:判定结果的三值语义
status 的正则 /^(clean|p[12]-\d+items)$/ 决定了三种合法判定:
clean:分支可合并。审查文件正文的 Findings 部分写none;p1-Nitems:存在N条 P1(最高优先级)finding,必须修复;p2-Nitems:存在N条 P2 优先级 finding。
对应类型定义在 types.ts:TowerReviewStatus = 'clean' | \p1-{number}items\` | \`p2-{number}items`。校验失败时 store 会抛出明确错误:review status must be clean | p1-Nitems | p2-Nitems, got "..."`。
2.2 merge:合并建议的三档选项
merge:直接合并(通常配合clean);fix-then-merge:先修复再合并(通常配合非 clean 判定);hold:暂缓合并(可能存在外部阻塞或待决策事项)。
merge 与 status 是相互独立校验的两个维度,非法值都会在 store 层被拒绝(见 store.ts)。
三、提交权限与轮次机制
3.1 谁能提交
store.ts 中的 submitReview 首先校验调用者身份:
- 调用者为 tower(主控)时直接放行;
- 否则必须满足
callerEntry.kind === 'reviewer' && callerEntry.reviewTarget === input.target,即该花名册条目必须是针对此目标分支指派的 reviewer。
不符合者会收到 agent "..." is not an assigned reviewer for "..."。测试 store.test.ts 专门验证了这一约束:worker w1、未注册的 ghost、以及把 target 改成其他分支的 reviewer 都会被拒绝。
3.2 轮次号自动分配与 5 轮上限
轮次号(round)不是参数,而是系统自动计算:store 统计该 reviewer 在目标分支上已提交的审查数 myRounds,本次轮次为 round = myRounds + 1(store.ts)。
同时存在硬性上限 MAX_REVIEW_ROUNDS = 5(store.ts):同一 reviewer 对同一分支超过 5 轮后会被拒绝,错误信息会给出"重定向"建议——重新指派不同的 worker 或全新 reviewer、把 mission 拆小、或用 TowerMission status=abandoned 降级范围。测试 store.test.ts 验证了"同一 reviewer 第 6 轮被拒、新 reviewer 从 round 1 重新开始"的行为。
3.3 审查文件命名与全局序号
每份审查落盘到 .tower/comms/reviews/ 目录,文件名由 paths.ts 的 reviewFileName 生成:
review-{targetSlug}-{reviewerSlug}-r{round}.md
targetSlug 会把 # 前缀转换为 pr、把 / 转换为 -(兼容 PR 模式目标)。此外每个审查还会获得一个单调递增的全局序号 seq(nextReviewSeq,见 store.ts),用于审查的稳定排序——测试 store.test.ts 验证了"按 seq 而非文件系统 mtime 排序"与序号递增行为。
四、分支 tip 盖章:复审的根基
submitReview 的核心动作之一是给审查盖章当前分支 tip:
const reviewedCommit = await branchTip(this.repoRoot, input.target);
该 commit 哈希写入审查文件 frontmatter 的 reviewed_commit 字段(store.ts)。这一设计直接服务于合并门禁:如果审查盖章的 commit 不是分支当前 tip,则合并被拒绝。TowerMerge 的 merge() 中:
if (review.reviewedCommit !== tip) {
throw await block('tip-moved', `merge blocked: ${branch} moved since the clean review ...`);
}
也就是说,"clean 判定"是一次性的、与具体 commit 绑定的。任何修复提交都会让分支移动,此时必须先由 tower 重新指派复审(TowerReview 会以新的 tip 盖章),旧判定自动失效。测试 store.test.ts 完整走了一遍"无审查 → p2 判定 → clean → tip 移动被拒 → clean 复审 → 合并成功"的门禁链路。
五、审查文件的落盘格式
每份审查是带 YAML frontmatter 的 Markdown 文件(解析/渲染实现在 frontmatter.ts):
---
date: 2026-09-28
reviewer: rev
target: feat/b010100-xxx
round: 2
seq: 7
status: p1-2items
merge: fix-then-merge
reviewed_commit: 3f2a91c4d1e...
mission: M3
tokens: 12345
---
## Findings
- [P1] 登录接口缺少鉴权,见 `src/auth/login.ts`
- [P1] 错误处理吞掉异常,见 `src/handlers/err.ts`
## Checks
- [x] tests pass
- [x] no secrets
## Decision
分支功能基本完整,但存在两处 P1 级别问题,修复后需复审。
各字段含义:
round:该 reviewer 在此分支上的第几轮审查(自动分配);seq:全局提交序号(自动分配);reviewed_commit:审查盖章的分支 tip;mission:审查归属的 mission id(由 reviewer 花名册的reviewMissionId或按分支解析得出);tokens:提交审查时 reviewer 累计消耗的 token 数(来自会话用量统计,无记录时为-1,见 support.ts)。
checks 参数会被渲染为 - [x] item 的 checkbox 列表;若 reviewer 未提供,文件内会写入 - [x] (reviewer reported no formal checks) 占位。所有审查写入走 writeUnique(wx 原子创建,冲突时自动加 -2、-3 后缀),并把 review.write 事件(target、round、verdict、7 位 commit、tokens)追加到活动日志。
六、提交结果的路由:下一步怎么走
这是 TowerReview 与其他 Tower 工具衔接的关键。提交成功后,工具输出按判定分叉(reviewTool.ts):
6.1 clean:进入合并就绪
输出 review submitted: {rel},随后追加:
next: {target} is merge-ready — the tower can TowerMerge it in Dependency Flow order.
即告诉主控:分支可以按依赖顺序交给 TowerMerge 合入。TowerMerge 的门禁会在此基础上再校验依赖已合并、改动在 mission scope 内、主 checkout 状态干净等条件(见 merge.md 与 store.ts)。
6.2 非 clean:点名 worker 恢复返工
非 clean 判定时,store 会做两件事:
- 翻转 mission 状态:如果该分支所属 mission 处于
completed(在 Tower 协议里completed仅表示"待审查",并非最终态),会自动翻回active并记录mission.rework日志(store.ts)。这一点在 mission.md 中有明确定义:"只有merged才是最终态,completed表示等待审查,分支仍可能被打回返工"。 - 输出恢复指令:通过
resolveMissionByBranch找到分支所属 mission 的 owner,输出:
next: resume {owner} with this review file ({rel}): Agent(resume="{worker.agentId}", run_in_background=true, prompt="...") — never foreground: its output flows back through the tower protocol files. The branch must be fixed and re-reviewed before it can merge.
若该分支没有在档的 worker(比如没有 mission 记录或 owner 缺失),则输出:
next: no worker on record owns {target} — route this review file ({rel}) through the tower so it can reassign the fixes.
无论哪种情况,工具都会追加一句:Also notify the branch author (or the tower) with TowerSend so the verdict is seen.——即用 TowerSend 通知作者或主控,保证判定可见。
注意"never foreground"这条铁律:恢复 worker 必须用 run_in_background=true 后台执行,因为返工产出是通过 tower 协议文件流回主控的,而不是子代理的返回值。
6.3 返工循环与重定向
结合 TowerSpawn 的简报机制(spawn.md):worker 重新被 spawn 到已被审查过的分支时,简报会携带最新一轮审查(判定、findings、decision)与前一个 worker 的 review-request,让返工从判定结论出发而非冷启动;reviewer 重新 spawn 时会拿到该分支之前的审查轮次,从而对当前 tip 复核旧 finding,而不是重复报告。当同一 reviewer 的返工循环超过 5 轮仍不收敛时,store 会拒绝并强制走"重定向"(换人、拆 mission 或降级范围),防止无限打转。
七、TowerReview 的完整实战示例
以下是一个 reviewer 在分支 feat/b010100-xxx 上提交 clean 判定的完整调用与预期输出:
TowerReview(
target="feat/b010100-xxx",
status="clean",
merge="merge",
findings="none",
checks=["tests pass", "no secrets", "docs updated"],
decision="所有任务已完成,改动均在 mission M3 声明的 scope 内,测试通过,未发现密钥泄漏。"
)
预期输出:
review submitted: .tower/comms/reviews/review-feat-b010100-xxx-rev-r2.md
next: feat/b010100-xxx is merge-ready — the tower can TowerMerge it in Dependency Flow order.
Also notify the branch author (or the tower) with TowerSend so the verdict is seen.
而一次发现 2 条 P1 问题的提交则输出:
review submitted: .tower/comms/reviews/review-feat-b010100-xxx-rev-r1.md
next: resume bob with this review file (.tower/comms/reviews/review-feat-b010100-xxx-rev-r1.md): Agent(resume="agent-bob-01", run_in_background=true, prompt="...") — never foreground: its output flows back through the tower protocol files. The branch must be fixed and re-reviewed before it can merge.
Also notify the branch author (or the tower) with TowerSend so the verdict is seen.
主控随后会以该审查文件为上下文后台恢复 worker bob 修复问题,再重新 spawn reviewer 复审,直到出现盖章于最新 tip 的 clean 判定,才轮到 TowerMerge。
八、使用要点与边界约束
- 协议文件只读:按 tower-worker-overlay.md 的要求,任何代理都不得手写/修改
.tower/下的文件,review 文件只能由 TowerReview 写入,手工改动会破坏合并门禁; - Tower 模式前提:Tower 编排工具仅主控 agent 可用(
TOWER_MAIN_AGENT_ONLY),且需要用户先以/tower on开启 tower 模式(见 support.ts); - 判定与 commit 强绑定:clean 只对盖章时的 tip 有效,分支移动即失效,必须复审;
- mission 状态语义:
completed ≠ 完成,它是"待审查";非 clean 判定会自动把它翻回active,只有merged才是终点; - 轮次上限:同一 reviewer 单分支最多 5 轮,超出后必须换人或重新规划。
TowerReview 是 Tower 协议中"质量门禁"的落点:它把审查结论固化成可审计的协议文件、把判定与具体 commit 绑定、并在每次提交后自动路由下一步,从而让多代理协作的合并流程始终建立在"对照 mission 意图、经审查确认、盖章最新 tip"的可验证基础之上。
参考实现与验证
- 工具定义与 schema:review.ts
- 工具执行与输出路由:reviewTool.ts
- 协议核心(提交审查、轮次上限、合并门禁):store.ts
- 类型契约:types.ts
- 审查文件命名与目录:paths.ts
- 门禁流程测试(无审查→p2→clean→tip 移动→复审→合并):store.test.ts
- 权限校验测试与轮次上限测试:store.test.ts、store.test.ts