Guided Review

在 coding agent 中执行只读源码的对话式代码审查。先帮助第一次接触代码的读者理解变更，再引导读者判断实现是否可靠。本 Skill 统一管理审查范围、证据、变更讲解、因果章节、渐进式交互和最终呈现。可用的专业审查能力可以提供审查视角，但不能重新捕获范围，也不能替换本 Skill 的交互约定。

收集上下文前，先读 references/evidence-policy.md。首次向用户展示审查结果前，先读 references/interaction-contract.md。

分类文件前，读取 references/review-preferences.md 和内置的 references/review-preferences.json。当前对话中的明确偏好优先于仓库根目录的 .guided-review.json，仓库配置优先于内置默认值。内置默认值已覆盖常见技术栈的测试、快照、lockfile、构建产物和生成声明，仓库通常不需要额外配置。

确定审查维度前，读取 references/stack-lenses.md，按变更中生产文件的实际构成应用对应技术栈维度。技术栈维度是基础完整审查的展开，始终可用，不占用专业视角名额。

变更达到引导式审查门槛时，在选择可选专业视角前读取 references/review-orchestration.md。

首次响应前，根据当前对话判断输出语言。用户明确指定的语言优先；否则使用用户有效消息中的主要语言，忽略粘贴的代码、引用文档、URL 和工具输出。仓库语言和 agent 默认提示不能覆盖用户语言。标题、证据标签、审查发现、导航文本和适配器控件必须使用同一种语言。

默认使用通用 Markdown 交互约定。仅当运行环境是 Codex 且具备相应 UI 能力时，读取 references/codex-ui.md。仅当运行环境明确说明当前回复会发送到飞书/Lark，或用户明确要求生成、预览或发送飞书版本且当前环境明确提供飞书消息或卡片渲染能力时，读取 references/lark-ui.md。一次响应只使用一个平台适配器；没有明确适配器时不得猜测平台能力。已知当前 agent 的原生文件链接格式时使用该格式，否则只显示仓库相对路径，不臆造深层链接。

一次审查 run 内，每个实际需要的 reference 最多读取一次。首次读取后把会影响后续判断的约束压缩记录到私有草稿的 _referenceNotes，后续阶段复用这些笔记，不重新打开原 reference。互斥的平台适配器只读取已确定的一份；不要为了满足单次读取而预加载无关 reference。

收集上下文时，如果 Skill 目录中存在 references/history-provider.local.md，读取并应用它。该文件是可选的本地增强层，不属于公开核心；缺失时直接使用 Git 历史和其他现有证据，不提示用户安装。

边界

• 不修改源码，不暂存、不提交、不推送，也不发布审查评论。
• 不宣称普通 Skill 输出会变成原生行内审查评论。
• 不用文字说明替代确定性的测试、lint 或策略检查。
• 不编造审查发现；没有问题的章节可以没有发现。
• 每个变更文件都必须被归入一个章节或配套变更组。
• 范围捕获器可以在 Git 私有目录下保存一份临时 Diff、清单、草稿和已校验审查状态。它们不得修改工作树、索引、ref 或远端，并且必须清理。

判断是否进入流程

用户显式调用 $guided-review 时直接进入本流程。隐式触发只适用于用户明确要求审查、audit、检查合并就绪度或查找缺陷的场景。仅仅因为变更很大，不能把实现、排障或讲解任务改成代码审查。

隐式选择发生时通常还没有精确规模。先捕获用户要求的范围，再按下文门槛判断。小变更直接返回精简审查，不解释为什么没有使用引导式地图。

选择范围

用户已经指定分支、基线、范围、commit 或 working tree 时，直接使用。否则只问一个问题，给出三个选项：

1. 当前分支相对其基线，推荐
2. 已暂存、未暂存和未跟踪的 working tree 变更
3. 自定义 <from>..<to> 范围

使用内置脚本捕获范围：

运行脚本需要 Git 和 Python 3.10 或更高版本，只使用 Python 标准库。

python3 <skill-dir>/scripts/capture_scope.py --scope branch
python3 <skill-dir>/scripts/capture_scope.py --scope worktree
python3 <skill-dir>/scripts/capture_scope.py --scope range --range <from>..<to>

用户给出基线时传入 --base <ref>。脚本输出 JSON 清单，并在 Git 私有目录下写入精确 unified Diff 和 manifest.json。Diff 为空时停止。保留 manifestPath 供状态复用，保留 diffPath 供清理。

changes.diff 是不可变范围的完整权威副本。manifest.json 的每个 files[] 同时提供独立 diffPath、在完整 Diff 中的半开字节区间 byteRange、hunkCount、addedLines 和 deletedLines。规模统计和文件归类直接使用清单字段；分析代码时每个生产文件的分片最多读取一次，不整读或分段反复读取 changes.diff。只有分片缺失、完整性校验失败或工具无法读取分片时，才回退完整 Diff，并记录原因。

收集上下文

从清单和变更路径出发，只收集与这些路径有关的证据：

1. 当前对话中的目标、约束和修正。
2. 当前代码与 Diff，它们是“实际改了什么”的权威来源。
3. 仓库根目录及离变更文件最近的适用 AGENTS.md。
4. 邻近规范、OpenSpec、ADR、API schema 和迁移文档。
5. 变更测试、构建配置，以及已有测试或 CI 结果。
6. commit message、blame、issue 和可用的历史决策记录。

遵循证据策略中的验证投入规则。完整审查必须说明核对过什么，但不要求审查 agent 重新执行所有测试。优先复用与当前范围匹配的 CI 或测试记录，只运行能解决关键不确定性的最小检查，同一项验证不得为每个章节重复执行。

历史记录只能证明当时记录的意图，不能证明当前代码符合意图。只列出实际使用的来源；可选历史来源缺失时，仅在它导致重要结论无法确认的情况下记录为未解决的不确定性。

选择审查深度

应用审查偏好后，只统计生产文件及其变更行数。生产文件包括运行时代码、有效运行时配置、schema 和迁移；测试、fixture、snapshot、生成物、lockfile、文档和其他配套文件不计入门槛。行数按捕获 Diff 的新增加删除计算，不按文件总长度或清单总大小计算。

同时满足以下条件才算小变更：

• 生产文件变更少于 200 行；
• 生产文件少于 5 个。

达到任一边界值，即 200 行或 5 个文件，使用正常的引导式地图。小变更跳过地图，直接使用交互约定中的精简完整审查；不要告诉用户这个 Skill 没必要。

小变更不要求用户选择审查视角，除非用户已经点名。正常引导式审查按照审查编排参考选择专业视角；只有多个兼容视角会实质改变审查问题或结论时，才询问一次。技术栈维度按变更文件构成自动应用，不询问用户。

只做一次完整分析

正常引导式审查必须先完成全量分析，再展示地图。逐个读取每个生产文件的 Diff 分片，追踪判断所需的调用方与契约，执行审查编排参考中的基础完整审查，应用一次已选专业视角，确定章节归属，评估发现，并记录验证和不确定性。这里要求完整分析覆盖，不代表可以运行完整测试套件。遵守证据策略的软性探证预算；清单或分片已经确认的事实不得换用 git show、搜索或另一条命令重复求证。

读取 references/review-state.md。分析过程中按小块写入私有草稿：先合并顶层摘要和笔记，再逐章追加；不要在一个 turn 里生成整份大 JSON。

python3 <skill-dir>/scripts/review_state.py draft \
  --manifest <manifestPath> --merge <partial-json-file>
python3 <skill-dir>/scripts/review_state.py draft \
  --manifest <manifestPath> --append-chapter <chapter-json-file>

所有章节、配套分组和最终判断齐全后，把 analysisStatus 合并为 complete，再校验并保存最终状态：

python3 <skill-dir>/scripts/review_state.py save \
  --manifest <manifestPath> --draft

增量草稿不是可展示状态。analysisStatus 不是 complete，或仍有清单路径未分配时，最终保存会失败，也不得展示地图。已校验的 review-state.json 是地图、章节、只看风险、完整审查和最终视图共同的数据源。展示任一视图前先加载：

python3 <skill-dir>/scripts/review_state.py load --manifest <manifestPath>

用户改变范围或要求审查更新后的 working tree 时，先清理再重新捕获。新问题需要状态外证据时，只补读该证据，更新完整草稿并再次保存。

组织审查地图

用最少的因果章节让新审查者理解变更。优先按问题、契约、实现、集成、验证组织，不按文件名排序讲述。

标题和范围之后，先单独给出基于证据的初步风险 Low、Medium、High 或 Unknown，下一段用一句话说明原因。风险结论必须先于变更说明、审查方式、意图、契约和章节地图，便于用户第一眼定位；初步风险用于定位，不是最终结论。

随后用结构化变更说明回答四个问题。可见标签依次为“问题背景”“解决方法”“行为变化”“适用边界”：

• 问题背景：原有行为为什么不能满足目标；
• 解决方法：这次通过什么机制解决；
• 行为变化：主要调用链、数据流或用户行为发生了什么变化；
• 适用边界：哪些情况没有覆盖，或哪些结论因证据不足仍无法确认。

不得根据经验补写问题背景或边界。证据不足时直接说明无法确认。变更说明之后显示“审查方式”，包括基础完整审查和实际选用的专业视角。

• 能共同证明一个行为的源码、测试和装配放在同一章节。
• 生成文件、lockfile、机械重命名等放入一个或多个配套变更组。
• 偏好规则只决定文件位置和审查深度。命中的文件如果属于有效契约、治理指令、运行时配置、schema 或迁移，必须提升到对应因果章节。
• 每个清单路径只能归入一个章节或配套变更组。
• 一个候选章节包含多个可独立审查的行为时先拆分；否则保持因果边界，按作用分组，不按目录或字母排序。
• 通用或降级 Markdown 地图中，每章最多直接链接五个关键文件。优先展示入口、契约、信任边界和核心实现；其余文件按作用和数量概括，进入章节后再展示完整清单。
• 配套变更只显示类别、数量和证据用途，不显示路径、不创建章节入口，也不逐文件审查。它们可以用于判断意图或验证；若要产生发现，必须先因其控制行为而提升到正式章节。
• 通用 Markdown 地图始终是默认和失败回退。平台适配器可以用等价交互总览替换本次可见地图，但不能重复展示，也不能隐藏底层审查状态。
• 每个章节及其文件只展示一次。首次响应只展示地图，不一次性展开所有章节。

展示地图后，等待用户进入章节、跳转章节、只看风险或要求一次性完整审查。这些操作只是读取同一状态的不同视图，不会启动新的审查。

如果建议用户优先查看某一章或某个视图，必须同时给出一句基于已保存证据的理由，例如该章包含最高严重级别发现、是理解后续章节的前置机制，或最贴近用户当前目标。不得只说“建议先看第 4 章”而不解释原因；没有实质理由时不做推荐，只列出可选入口。

审查章节

用户选择章节后，加载已保存状态并展示已有分析。不能因为用户进入章节就重新读取 Diff、重新追踪调用、再次运行专业审查或验证。只有新问题或已记录的不确定性确实需要时才补读源码，并同步更新完整状态。

章节应包含：

1. 本章存在的原因、改变的行为和实际工作机制。
2. 足以支撑判断的最小证据集和准确来源标签。
3. 按因果作用分组的完整变更文件列表、可点击链接及文件作用。
4. 具体审查重点。
5. 按严重级别排序的审查发现，如有。
6. 已记录的验证和剩余不确定性。
7. 返回地图、进入相邻章节或切换只看风险的文本导航。平台适配器可以增加控件，但不能移除通用文本选项。

审查发现必须对应具体的正确性、安全、权限、并发、数据丢失、错误处理、边界、性能或契约问题，锚定到变更后的准确行，并说明问题、触发场景、证据与发生机制、实际影响和可执行修复建议。触发场景必须来自可复核的输入条件、系统状态、角色权限或调用顺序；无法证明的场景放在“审查重点”或“未解决”，不能写成确定发现。

分别判断意图和实现：

• 意图：用户要求或记录的契约是否自洽、安全。
• 实现：Diff 是否正确实现契约且没有引入缺陷。

完成审查

完成用户要求的章节后，总结：

• 已覆盖章节和跳过的配套变更组；
• 意图与实现结论；
• 按严重级别排列、带文件链接的发现；
• 未解决的证据冲突或未知项；
• 有记录支撑的验证，不把只读过的测试代码说成执行结果。

当前适配器有说明时，可以提供 agent 原生的独立审查入口。不得暗示 Guided Review 能替代人工批准、CI 或分支保护。

最后删除私有捕获内容；提前停止或发生已处理异常时也要清理：

python3 <skill-dir>/scripts/capture_scope.py --repo <repo-root> --cleanup <diffPath>