difit

Difit

何时使用此技能

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

• 仅当用户明确提到 difit、要求在查看器中打开或显示差异，或有长期指示（例如项目文档或 Agent 配置中要求在代码更改后通过 difit 请求审查）时，才使用此技能。
• 不要将其用于常规审查请求，例如“审查这些更改”“使用审查 Agent”“找出此差异中的问题”或“审查此 PR/提交/分支”。请通过正常回复渠道回答这些请求。
• 如果请求含糊不清，优先选择不使用 difit 的方式。

概述

此技能会使用 difit 请求用户进行代码审查。 运行命令前，请根据以下规则选择 <difit-command>：

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

如果用户留下审查评论，所选 difit 命令退出时会将评论打印到标准输出。 收到审查评论后，继续工作并处理这些评论。 如果服务关闭时没有评论，则视为“未提供审查评论”。无需重启服务。 也无需手动确认页面是否已成功启动。

命令

• 提交前审查未提交的更改：<difit-command> .
• 审查 HEAD 提交：<difit-command>
• 审查暂存区更改：<difit-command> staged
• 仅审查未暂存的更改：<difit-command> working

基本用法：

<difit-command> <target>                    # View single commit diff. ex: difit 6f4a9b7
<difit-command> <target> [compare-with]     # Compare two commits/branches. ex: difit feature main

可选的启动评论

如果有内容想在 difit 打开时告知用户，可以使用 --comment 将其作为启动评论附加。 这适用于审查发现、说明，以及用户应直接在差异中看到的任何背景信息。

<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"}'

• 每条评论都使用 type: "thread"。
• 使用用户正在使用的语言撰写评论正文。
• 对于目标侧差异中存在的行，使用 position.side: "new"。
• 对于仅存在于已删除侧的行，使用 position.side: "old"。
• 对于涉及多行的问题，使用范围评论。
• 切勿将差异中的机密、令牌、密码、API 密钥、私钥或其他类似凭据的内容复制到 --comment 正文或任何命令行参数中。

包含未跟踪文件

对于未提交的更改，如果还应在差异中显示尚未添加到 git 的文件，请添加 --include-untracked。

<difit-command> . --include-untracked

复用正在运行的服务

每个 Git 根目录和审查目标最多保留一个运行中的 difit 服务。启动审查后再次编辑时，请复用正在运行的服务，而不要再启动一个——重复启动会产生重复的端口和浏览器标签页。

• 启动 difit 前，检查你之前启动的 difit 服务是否仍在同一个 Git 根目录下运行（例如，你启动的后台进程是否仍在运行）。
• 如果同一目标已有服务在运行，请勿再启动一个，也不要重新打开其 URL。对于工作树目标（.、working、staged 和默认的 HEAD），difit 会监视仓库；差异发生变化时，打开的页面会提示用户重新加载。
• 如果预计会进行多轮审查，请使用 --keep-alive 启动服务（浏览器断开连接后服务仍会运行），或使用 --background（分离运行的 keep-alive 服务；会打印类似 {"port":4966,"url":"http://localhost:4966","pid":123} 的 JSON，且不会自动打开浏览器，因此只需向用户分享一次 URL）。
• 只要服务仍在运行，就无需重启即可交换反馈：
  • <difit-command> comment get --port <port> — 读取用户的审查评论（使用 --format json 可获取结构化输出）。
  • <difit-command> comment add --port <port> '<json>' — 向正在运行的服务添加新评论（JSON 结构与 --comment 相同）。
  • <difit-command> comment resolve <threadId...> --port <port> — 解决你已处理的评论串。
• 如果审查目标发生变化（例如，提交范围不同），请停止现有服务并启动新服务，而不要让同一仓库同时运行两个服务。

限制

只能在由 Git 管理的目录中使用。