difit-review

Difit Review

何时使用此技能

difit 会打开外部浏览器界面并启动一个长期运行的本地服务，因此必须由用户明确选择后才能启动：

• 只有当用户明确提到 difit、要求在 difit 查看器中打开、显示或批注评审内容，或按名称调用此技能时，才使用此技能。
• 请勿将其用于普通评审请求，例如“评审这些更改”“使用 reviewer Agent”“找出此差异中的问题”或“评审此 PR/提交/分支”。应照常进行评审，并在回复中报告发现。
• 请求含糊时，优先采用非 difit 评审方式。

概述

此技能会在便于人类阅读的查看器中打开用户要求的 git diff。同时，Agent 可以通过 --comment 选项添加任意批注。 此批注机制非常适合记录代码评审发现和代码说明。 运行命令前，请根据以下规则选择 <difit-command>：

• 如果 command -v difit 执行成功，则使用 difit。
• 否则，使用 npx difit。
• 如果在无网络权限的沙盒环境中，使用 npx difit 需要访问网络，则应先请求提升权限并征得用户同意，再运行命令。

步骤

最终命令通常如下所示：

<difit-command> <target> [compare-with] \
  --comment '{"type":"thread","filePath":"src/foobar.ts","position":{"side":"old","line":102},"body":"line 1\nline 2"}' \
  --comment '{"type":"thread","filePath":"src/example.ts","position":{"side":"new","line":{"start":36,"end":39}},"body":"Range comment for L36-L39"}'

详细步骤如下。

1. 确定目标差异并评审其内容。

• 检查用户指定的差异。它可以是本地 git 修订、GitHub URL、补丁文件或类似内容。
• 正常理解差异，必要时检查相关代码，并考虑如何回应用户的请求，无论用户需要的是评审发现、说明还是其他内容。
• 对于 PR 评审，应在本地检查 PR，并将评审结果限制为 difit 输出。请勿向远程 GitHub 发布评论。

2. 添加准备好的批注并启动 difit，或复用正在运行的服务。

• 启动前先检查是否可复用
  • 每个 Git 根目录和评审目标最多保留一个运行中的 difit 服务。如果你之前为同一目标启动的 difit 服务仍在运行，请勿再次启动服务或重新打开其 URL；使用 <difit-command> comment add --port <port> '<json>'（JSON 格式与 --comment 相同）将新发现添加到该服务，让已打开的页面显示这些内容。
  • 如果预计会进行多轮评审，请使用 --keep-alive 或 --background 启动（分离运行的 keep-alive 服务会打印 JSON 连接信息，例如 {"port":4966,"url":"http://localhost:4966","pid":123}，但不会自动打开浏览器），然后在后续轮次使用 comment add / comment get --port <port>。
• difit 启动选项
  • 使用 <difit-command> <target> [compare-with] 指定目标差异。
  • 对于未提交的更改，使用 <difit-command> .；对于工作树更改，使用 <difit-command> working；对于已暂存的更改，使用 <difit-command> staged。
  • 对于标准输入内容，可使用类似 diff -u file1.txt file2.txt | <difit-command> 的形式。
• 批注参数
  • 每条批注都使用 type: "thread"。
  • 批注正文使用用户正在使用的语言。
  • 对于目标侧存在的行，使用 position.side: "new"。
  • 对于仅存在于已删除一侧的行，使用 position.side: "old"。
  • 对于涉及多行的问题，使用范围批注。
  • 切勿将差异中的机密、令牌、密码、API 密钥、私钥或其他类似凭证的内容复制到 --comment 正文或任何命令行参数中。
• 尚未添加到 git 的文件的附加参数
  • 对于未提交的更改，如果决定也在差异中显示尚未添加到 git 的文件，请添加 --include-untracked。

3. 分享 difit URL 并完成回复。
   • 如果没有可添加的批注，请明确说明。
   • 无需手动验证已启动的 difit 页面。