steve-swanson/review-work

审查工作

此技能审查代码，在本地网页上显示发现结果，并且只修复用户批准的内容。所有批准的修复都合并到一个分支上，并通过一个拉取请求（PR）提交。

主代理（运行此技能的聊天）负责全局。它设定范围，为每个辅助代理选择模型，保存所有记录，并检查所有结果。辅助代理执行分配的任务并报告结果。

此技能与 plan-work 和 execute-work 配合使用。它不会调用或修改它们。

此处使用的术语

• 审查分支：正在接受审查的分支。PR 会合并回此分支。它不总是 develop。
• 审查提交：被审查的确切提交 SHA。每个发现结果都指向它。
• 发现结果：审查中的一个问题或疑问，带有类似 R001 的 ID。
• 页面：用户在此本地网页上为每个发现结果选择 修复、不修复 或 澄清。
• 批次：一次点击提交所发送的选择集合。
• 工作树：同一仓库在其自身文件夹中的额外签出。
• 协调分支：收集所有修复的单个分支（及其自己的工作树）。它将成为 PR。采用常规分支风格命名，<类型>/<简短描述>，小写并用连字符分隔。审查修复通常是 fix/，例如 fix/session-recovery；如果所有修复更适合，则使用 refactor/、perf/、docs/、test/ 或 chore/。如果用户或仓库指定了不同的约定（例如在 AGENTS.md 中），则遵循该约定。切勿在名称中包含 integration。
• 任务分支：一个短命的分支和工作树，用于一个辅助代理进行一项修复。
• 快进合并：仅向前移动分支且不添加合并提交的合并（git merge --ff-only）。
• 运行自有：由此审查运行创建。清理仅影响运行自有的分支和工作树。匹配的名称不能证明所有权。

用户已允许的操作

• 启动此技能允许审查记录和本地页面服务。
• 选择在另一台链接的机器上显示页面，允许在那台机器上运行一个页面托管线程，位于名为 Review-work pages 的 T3 项目中（如果缺失则创建）。该项目仅运行 review-work CLI。它永远不会触及那里的代码。审查完成后，允许结算该线程并删除 Review-work pages 项目（这将删除其聊天），如 remote-page.md 所述。切勿删除任何其他项目。此审查聊天永远不会在那个项目中：它保留在原处，并接收最终报告。
• 提交修复（在页面上，或在聊天中明确说“修复它”）允许任务工作树、提交、合并到协调分支、安全清理、推送以及一个准备就绪待审查的 PR。它还允许监视该 PR 直到其合并，然后在审查机器上删除此运行未更改的、已合并的协调工作树和本地分支。
• 如果用户说“仅本地”或“不要创建 PR”，则遵循该指示。
• 切勿合并 PR、启用自动合并或进行部署。

步骤 1：确定审查范围

1. 阅读仓库的说明、需求、状态、分支和工作树。不要干涉未提交的编辑和其他运行。
2. 记录仓库路径、共享 Git 文件夹、分支、基础分支、被审查的提交 SHA、主机（机器名称）和聊天 ID。
3. 仅审查已提交的代码，使用 git show、差异或干净的托管签出。未提交的文件不属于审查范围。
4. 选择范围：
   • 功能分支： 审查其与基础分支的差异。从用户、项目规则或 PR 元数据中获取基础分支。如果仍然不清楚，请询问。
   • develop： 审查整个当前代码。不要凭空捏造开始日期或开始提交。
5. 询问 “内联还是子代理扇出？”，除非用户已经说明。
   • 内联： 主代理自行审查。修复仍然使用辅助代理。
   • 扇出： 辅助代理并行审查。询问一次最多允许的辅助代理数量，并根据有用的独立区域建议一个数字。提供 自动：在容量允许的情况下使用尽可能多的有用辅助代理。如果容量未知，则说明限制为 4。其余排队等候。
6. 在创建任何工作树之前，保存当前工作树、本地分支和托管附件的快照。保留此运行创建的每个工作树的列表：审查者、修复者、辅助代理、重试以及它们的子项，也包括未更改或已放弃的工作树。参见 cleanup.md。

步骤 2：启动审查记录

• 使用此技能中的 Node 24+ 和 scripts/review.mjs。命令参见 runtime.md。
• 运行 init 一次，使用一个保存在项目外部的 JSON 输入文件。保存返回的审查文件夹路径并重复使用。在恢复时，切勿创建新的运行。
• 记录存储在 <home>/.agents/state/review-work/ 中。运行时会在该处创建任何其他文件之前先创建其 .gitignore，因此 Git 永远不会拾取它们。
• 仓库的身份是其清理后的远程 URL 加上其真实的共享 Git 文件夹。同一个克隆的链接工作树共享一个身份；不同的克隆则不共享。每个运行也有自己的 ID，因此同时运行的审查不会混淆。
• 只有主代理及其页面服务写入记录。切勿将数据库、服务或状态复制到工作树或 .worktreeinclude 中。辅助代理返回结果，主代理保存它们。辅助代理将大文件放在自己的临时文件夹中；主代理导入它们。

步骤 3：选择模型，然后审查

首先阅读 routing.md。

• 主代理为每个审查和修复任务选择确切的模型 和 努力程度。它检查主机是否提供它们，然后在开始任务前记录选择。辅助代理从不调用 Jev 或选择路由（模型、努力程度或选项）。除非主代理给它们一个精确、固定的分配，否则它们永远不会启动自己的辅助代理。
• 保持在聊天的模型系列内：GPT 聊天中使用 GPT 模型；Claude 聊天中使用 Claude Opus、Sonnet 或 Haiku。
• 始终使用最新版本。 模型按层级名称（Astra、Sol、Terra、Opus、Sonnet、Haiku）选择。对于每个层级，运行时在主机模型列表中仅保留最新版本并拒绝旧版本。切勿凭记忆选择版本。相信主机模型列表胜于猜测。切勿发明模型 ID 或静默切换提供商。如果系列未知或所需的模型缺失，请询问。
• Jev 可以首先选择模型，然后选择该模型支持的努力程度。它需要一个密钥。使用运行时的凭据发现功能找到它，永远不要自己打开文件。发现首先检查 <home>/.config/jev/credentials.env（建议的名称为 TYPESAFE_API_KEY）。如果不存在可用的home密钥，检查项目实际的环境加载顺序及其配置的适配器，然后传递这些环境文件路径。切勿打印、保存或 source 密钥文件或密钥值。完整的查找顺序在 routing.md 中。
• 配置好的 Jev MCP 适配器可以做出相同的两个选择。首先读取其真实的工具模式；不要假设存在 jev_route 工具。如果没有适配器，则使用运行时内置的直接传输。
• 努力程度上限，适用于每个模型： 审查和规划最高到超高，绝不能到最高或极致。修复最高到高。运行时拒绝任何超过上限的路由，无论是来自 Jev 还是主代理。
• 如果 Jev 缺失或给出不可用的答案，主代理将使用相同的规则自行决定。没有固定的回退表。
  • 只读列表工作：低程度即可。
  • 算法或困难推理：高或超高。
  • 不确定：高。
  • 安全审查和规划（登录、权限、密钥、密码学、租户隔离、信任边界）：最新的 GPT Astra 或最新的 Claude Opus，使用超高程度。如果该模型没有超高程度，则使用同一模型在其上限以下（至少为高）的最高级别。不要切换到旧版本。如果辅助代理发现新的安全范围，则停止该部分并向主代理报告。 计划的实施使用下面的修复路由，包括安全修复。
  • 内联审查，当其中一部分需要更高的路由时： 不要要求用户更改此聊天的模型或努力程度。此聊天无法确认或设置其自身的努力程度。将该部分（例如，安全检查）交给一个审查辅助代理，并在启动时设置辅助代理的确切模型和努力程度（在 Claude Code 中，使用 Agent 工具的 model 和 effort；在 T3 中，使用 delegate_task 选项）。首先记录路由。辅助代理返回发现结果；主代理保存它们。仅当主机无法在所需的模型和努力程度下启动辅助代理时才询问用户：然后解释差距并提供保持此聊天的模型。为此审查记录一次该选择，不再询问。这永远不会降低扇出辅助代理的规则。
• 按行为和文件划分审查。跨文件追踪流程。寻找代码可能出错的方式：错误结果、违反规则、数据丢失、缺少检查以及兼容性破坏。对照需求和实际运行的代码检查每个关注点。合并重复项。
• 记录覆盖率：你 检查 了什么、跳过 了什么以及 未能完成 了什么，包括路径、SHA、原因和证据。“未发现结果”并不意味着每个文件都已检查。若有重要的覆盖率未得到说明（未记录为已检查、已跳过或未完成），不得认为审查已完成。

步骤 4：编写人们能理解的发现结果

用户仅凭发现结果的文本来做决定，因此文本必须简短、准确且平实。阅读 writing-findings.md。向每个审查辅助代理提供其路径，并告知其遵循该指南。

使用 Conventional Comments 标签，例如 issue、question、suggestion 和 nitpick。将每个发现结果标记为 blocking 或 non-blocking。每个发现结果包含四个部分：

• 标题： 问题是什么，用 80 个字符或更少的平实句子表述。例如“重试付款可能创建两张发票”，而不是“非幂等的发票创建路径”。
• 为何重要（discussion）：谁或什么会受到影响，何时以及多久一次。
• 证据（evidence，以及可选的代码 excerpt）：path:line、代码路径或步骤，以及你是如何知道的。
• 修复思路（suggestion）：以小型修复、中型修复或大型修复开头，然后说明要更改什么。

如果不确定，写一个 question。切勿将猜测作为已确认的 issue 呈现。为每个发现结果分配一个稳定的 ID、路径和行号，以及被审查的 SHA。

在加载发现结果之前，对每个结果运行 writing-findings.md 中的清晰度检查。重写任何未通过检查的发现结果，并保留每个事实。

步骤 5：显示页面并收集决策

1. 加载发现结果和覆盖率，然后启动页面。一个页面服务于整个审查，包括后续轮次。

2. 对于每个发现结果，用户选择 修复、不修复 或 澄清，并可以为任何选择添加注释。选择会保存为草稿。切换选择会保留注释。

3. 只有 提交 会发送一个批次。部分批次也可以；未决定的发现结果保持打开状态。已提交的选择在页面上是锁定的。更改在聊天中进行。

4. 首先检查运行时环境。 当此聊天的 shell 设置了 T3CODE_THREAD_ID 或 T3CODE_CLI_PATH，或者 T3 工具（例如 t3_environment_links）可用时，它在 T3 Code 中运行。如果不是：

   • 在此机器上显示页面，使用 deliveryMode: "terminal"。
   • 跳过下面的页面主机选择，并且不提供另一台机器。不要阅读 remote-page.md。
   • 在第 5 项中使用纯终端文本。

   在 T3 中，根据聊天的起源选择在哪里显示页面。 将此与内联/扇出选择分开。

   • 遵守此聊天中已显式做出的页面主机选择。恢复时，重用该选择；仅当用户更改它或该主机不可用时才再次询问。
   • 如果聊天是在审查机器上本地启动的，则在该机器上显示页面，无需询问。根据用户声明或主机提供的客户端来源元数据来确定被发起设备。代理的主机名、工作目录、执行环境或 creationSource（web、mobile 或 mcp）本身不能证明用户从哪里启动了聊天。
   • 如果聊天是远程启动的，或者其来源不确定，则询问一次在哪里显示页面。直接询问页面主机，而不是单独询问用户是否本地。调用 t3_environment_links 并提供此机器以及 每个具有完全访问权限的可达链接机器，使用它们的实际标签。不要因为操作系统原因而遗漏任何机器。解释已知的能力/访问障碍，而不是静默隐藏主机。如果提问工具无法容纳每个选择，则在问题中列出所有合格的主机并接受主机名。
   • 当用户机器已知且符合条件时，推荐使用它。仅在影响选择时解释屏幕锁定限制：T3 的流式浏览器会在审查机器的屏幕锁定时停止。在审查记录中保存所选主机和来源证据（或 unknown）。
   • 在另一台机器上： 遵循 remote-page.md。页面在用户自己的浏览器中打开，提交将选择发送回此聊天。它需要完全访问的 T3 链接。在此机器锁定时也能工作。

5. 始终给出主机和页面链接。

   • 在 T3 中，在此机器上： T3 浏览器可以打开页面。说 “提交会自动恢复此对话。” 页面使用本地的 t3 thread send 命令。无需公共 webhook 或隧道。
   • 在 T3 中，在另一台机器上： 说明哪台机器显示页面，以及 “提交会将你的选择发送回此聊天。”
   • 在纯终端中， 说：
     1. 打开审查页面。
     2. 为每个发现结果选择一个选项，如果需要可添加注释，然后点击提交。
     3. 回到此聊天并等待摘要。

6. 禁用页面上的交互。删除此项目中的本地和远程运行自有分支和工作树。按照 cleanup.md 进行清理：不要删除未创建的内容。

步骤 9：报告给用户

撰写一份最终摘要，包括实际检查的内容、发现和修复了哪些问题（带有清晰的标题目录以供参考）、已确认的安全范围、覆盖率差距、非阻塞问题，以及与原始范围相比的任何说明。对于与 execute-work 一起运行的 AGENTS.md 任务，以与其它技能一致的方式结束。

参考

• runtime.md
• routing.md
• writing-findings.md
• cleanup.md
• remote-page.md