重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
diffity-review by kamranahmedse/diffity
npx skills add https://github.com/kamranahmedse/diffity --skill diffity-review你正在使用 diffity agent CLI 审查代码差异并留下行内评论。
ref (可选): 要审查的 Git 引用 (例如 main..feature, HEAD~3)。默认为工作区更改。当同时提供 ref 和 focus 时,两者都使用 (例如 /diffity-review main..feature security)。focus (可选): 将审查重点放在特定领域。可选值: security, , , , , 。如果省略,则审查所有内容。广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
performancenamingerrorstypeslogicdiffity agent list [--status open|resolved|dismissed] [--json]
diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new|old] --body "<text>"
diffity agent general-comment --body "<text>"
diffity agent resolve <id> [--summary "<text>"]
diffity agent dismiss <id> [--reason "<text>"]
diffity agent reply <id> --body "<text>"
comment 命令需要 --file, --line, --body--end-line 默认为 --line (单行评论)--side 默认为 newgeneral-comment 创建与任何文件或行无关的差异级别评论<id> 接受完整 UUID 或 8 字符前缀diffity 是否可用: 运行 which diffity。如果未找到,请使用 npm install -g diffity 安装。审查需要一个运行中的会话,其引用与请求的引用匹配。引用不匹配会导致添加评论时出现"文件不在当前差异中"的错误。
diffity list --json 获取所有正在运行的实例。解析 JSON 输出,并找到其 repoRoot 与当前仓库匹配的条目。ref 字段与请求的引用进行比较:
"work",为命名引用存储用户提供的引用字符串 (例如 "main", "HEAD~3)。diffity <ref> --no-open --new (如果没有 ref,则运行 diffity --no-open --new)。--new 标志会终止旧会话并启动一个新会话。使用带有 run_in_background: true 的 Bash 工具。等待 2 秒,然后使用 diffity list --json 验证并记下端口。"work" → 使用 diffity --no-open --new 重新启动 (正在运行的会话是针对命名引用的,但我们需要工作区)。diffity <ref> --no-open (如果没有 ref,则使用 diffity --no-open)run_in_background: true 的 Bash 工具diffity list --json 验证并记下端口。从 diffity 的 API 获取解析后的差异参数,然后自己运行 git diff — 不要手动构造差异引用,因为 diffity 使用合并基准解析:
curl -s 'http://localhost:<port>/api/diff/ref?ref=<ref>'
如果未提供 ref,请省略 ref 查询参数。响应是带有 args 字段 (例如 "abc123def") 的 JSON。运行 git diff <args> 获取统一差异。行号在 @@ 块头中。
查找并阅读所有相关的 CLAUDE.md 文件 — 根目录的 CLAUDE.md 以及包含修改文件的任何目录中的 CLAUDE.md 文件。这些文件定义了差异必须遵循的特定于项目的规则。
首先总结变更。 在寻找问题之前,构建一个关于差异的心智模型:
git log --oneline <args>) 以及任何链接的问题或 PR 描述以获取上下文。理解意图有助于你区分有意行为和真正的错误。
对于每个更改的文件,阅读整个文件 (不仅仅是差异块) 以理解完整上下文。
交叉引用调用者和依赖项。 对于任何更改的函数签名、重命名的导出、修改的返回类型或更改的行为: 在整个代码库中 grep 查找使用情况。一个孤立看起来正确的函数可能会破坏每个调用者。检查:
使用以下技术分析代码更改。如果提供了 focus 参数,请集中在该领域。否则,应用所有分析流程和信号阈值。
差异告诉你什么改变了;周围的代码告诉你这个改变是否正确。应用这些分析流程:
数据流分析 — 跟踪更改代码中的值。每个变量从哪里来?它去哪里?检查:
if (x))?状态和生命周期分析 — 对于有状态的代码 (React 状态、数据库事务、流、事件监听器):
契约分析 — 根据必须满足的契约检查更改后的代码:
边界分析 — 对于系统边界处的代码 (用户输入、网络、文件 I/O、IPC):
边界情况分析 — 仅针对实际中会发生的情况,而非理论上的情况:
标记会影响正确性、安全性或可靠性的真正问题:
跳过风格问题、linter 可捕获的问题以及未更改代码中预先存在的问题。专注于差异,而不是整个文件。
对于每个发现,在发布前验证它是真实的:
如果跨文件出现重复模式,请评论第一次出现,并在总体摘要中提及该模式,而不是重复评论。
在评论正文中使用严重性前缀对每个发现进行分类:
[must-fix] — 错误、安全问题、数据丢失风险。将导致中断或产生错误结果的代码。[suggestion] — 具有明确理由的具体改进。不是风格偏好 — 真正的改进。[question] — 需要作者澄清的不明确之处。对于每个发现,使用以下命令留下行内评论:
diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new] --body "<comment>"
--side new (默认)--side old--end-line留下所有行内评论后,决定是否需要一般评论:
没有发现 → 留下一般评论: "未发现问题。已检查错误和 CLAUDE.md 合规性。"
1-2 个发现 → 跳过一般评论,除非存在行内评论未涵盖的跨领域问题。
3+ 个发现 → 留下一般评论 总结主题。
不要在一般评论中使用严重性前缀 — 前缀仅用于行内发现。
以结论开头,直接且简洁 — 不要恭维,不要填充,不要叙述代码的作用。
diffity agent general-comment --body "<overall review summary>"
现在评论已准备就绪,打开浏览器:
diffity open <ref>
如果提供了 ref 参数,请传递它 (例如 diffity open HEAD~3)。省略它以打开默认视图。
告诉用户审查已完成,他们可以检查浏览器。示例:
审查完成 — 请检查您的浏览器。
发现: 2 个必须修复, 1 个建议
准备就绪后,运行 /diffity-resolve 来修复它们。
每周安装量
75
仓库
GitHub Stars
280
首次出现
8 天前
安全审计
安装于
gemini-cli74
kimi-cli74
codex74
amp74
cline74
github-copilot74
You are reviewing a diff and leaving inline comments using the diffity agent CLI.
ref (optional): Git ref to review (e.g. main..feature, HEAD~3). Defaults to working tree changes. When both ref and focus are provided, use both (e.g. /diffity-review main..feature security).focus (optional): Focus the review on a specific area. One of: security, performance, naming, errors, types, logic. If omitted, review everything.diffity agent list [--status open|resolved|dismissed] [--json]
diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new|old] --body "<text>"
diffity agent general-comment --body "<text>"
diffity agent resolve <id> [--summary "<text>"]
diffity agent dismiss <id> [--reason "<text>"]
diffity agent reply <id> --body "<text>"
--file, --line, --body are required for comment--end-line defaults to --line (single-line comment)--side defaults to newgeneral-comment creates a diff-level comment not tied to any file or line<id> accepts full UUID or 8-char prefixdiffity is available: run which diffity. If not found, install it with npm install -g diffity.The review needs a running session whose ref matches the requested ref. A ref mismatch causes "file not in current diff" errors when adding comments.
diffity list --json to get all running instances. Parse the JSON output and find the entry whose repoRoot matches the current repo.ref field against the requested ref:
"work" for working-tree sessions and the user-provided ref string (e.g. "main", "HEAD~3") for named refs.diffity <ref> --no-open --new (or diffity --no-open --new if no ref). The --new flag kills the old session and starts a fresh one. Use Bash tool with . Wait 2 seconds, then verify with and note the port.Get the resolved diff args from diffity's API , then run git diff yourself — do NOT construct the diff ref manually, as diffity uses merge-base resolution:
curl -s 'http://localhost:<port>/api/diff/ref?ref=<ref>'
If no ref was provided, omit the ref query parameter. The response is JSON with an args field (e.g. "abc123def"). Run git diff <args> to get the unified diff. Line numbers are in the @@ hunk headers.
2. Find and read all relevant CLAUDE.md files — the root CLAUDE.md and any CLAUDE.md files in directories containing modified files. These define project-specific rules that the diff must follow.
Summarize the change first. Before looking for problems, build a mental model of the diff:
git log --oneline <args>) and any linked issues or PR descriptions for context.Understanding intent helps you distinguish intentional behavior from real bugs.
For each changed file, read the entire file (not just the diff hunks) to understand the full context.
Cross-reference callers and dependents. For any changed function signature, renamed export, modified return type, or altered behavior: grep for usages across the codebase. A function that looks correct in isolation can break every caller. Check:
Analyze the code changes using the techniques below. If a focus argument was provided, concentrate on that area. Otherwise, apply all analysis passes and the signal threshold.
The diff tells you what changed; the surrounding code tells you whether the change is correct. Apply these analysis passes:
Data flow analysis — Trace values through the changed code. Where does each variable come from? Where does it go? Check:
if (x)) that the diff accidentally moved outside of?State and lifecycle analysis — For stateful code (React state, database transactions, streams, event listeners):
Contract analysis — Check the changed code against the contracts it must satisfy:
Boundary analysis — For code at system boundaries (user input, network, file I/O, IPC):
Edge case analysis — Only for cases that will happen in practice, not theoretical ones:
Flag real problems that would affect correctness, security, or reliability:
Skip style concerns, linter-catchable issues, and pre-existing problems in unchanged code. Focus on the diff, not the whole file.
For each finding, verify it's real before posting:
If a repeated pattern appears across files, comment on the first occurrence and mention the pattern in the general summary instead of duplicating comments.
Categorize each finding with a severity prefix in the comment body:
[must-fix] — Bugs, security issues, data loss risks. Code that will break or produce wrong results.[suggestion] — Concrete improvements with a clear reason. Not style preferences — real improvements.[question] — Something unclear that needs clarification from the author.For each finding, leave an inline comment using:
diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new] --body "<comment>"
--side new (default) for comments on added/modified code--side old for comments on removed code--end-line when the issue spans multiple linesOpen the browser now that comments are ready:
diffity open <ref>
Pass the ref argument if one was provided (e.g. diffity open HEAD~3). Omit it to open the default view.
Review complete — check your browser.
Found: 2 must-fix, 1 suggestion
When you're ready, run /diffity-resolve to fix them.
Weekly Installs
75
Repository
GitHub Stars
280
First Seen
8 days ago
Security Audits
Gen Agent Trust HubPassSocketWarnSnykPass
Installed on
gemini-cli74
kimi-cli74
codex74
amp74
cline74
github-copilot74
通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南
48,700 周安装
run_in_background: truediffity list --json"work" → restart with diffity --no-open --new (the running session is for a named ref, but we need working-tree).diffity <ref> --no-open (or diffity --no-open if no ref)run_in_background: truediffity list --json and note the port.After leaving all inline comments, decide whether a general comment is needed:
No findings → leave a general comment: "No issues found. Checked for bugs and CLAUDE.md compliance."
1-2 findings → skip the general comment unless there's a cross-cutting concern the inline comments don't cover.
3+ findings → leave a general comment summarizing the themes.
Do not use severity prefixes in the general comment — prefixes are only for inline findings.
Lead with the verdict, be direct and concise — no compliments, no filler, no narrating what the code does.
diffity agent general-comment --body "<overall review summary>"