Kimi Code Tower 协议解析:TowerReview 分支审查判定与提交机制实战指南

原创2026-09-28 11:06:532,307 阅读
文章标签:人工智能大模型AI Agent代码智能体CLIAI 技能MCP Clients开发工具

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 的核心语义,可概括为三句话:

  1. 为被指派审查的分支提交一份审查判定;
  2. 判定会盖章当前分支 tip——分支随后若发生移动,tower 必须先要求复审才能合并;只有被指派到该目标的 reviewer(或 tower 本身)才能提交,轮次号由系统自动分配;
  3. 提交结果决定下一步路由:非 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 会做两件事:

  1. 翻转 mission 状态:如果该分支所属 mission 处于 completed(在 Tower 协议里 completed 仅表示"待审查",并非最终态),会自动翻回 active 并记录 mission.rework 日志(store.ts)。这一点在 mission.md 中有明确定义:"只有 merged 才是最终态,completed 表示等待审查,分支仍可能被打回返工"。
  2. 输出恢复指令:通过 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"的可验证基础之上。

参考实现与验证

登录后查看全文
kimi-code