diffity

代码 review 还能这样玩：Diffity 把 GitHub 的 Diff 体验搬到你本地

场景切入：你刚写完一个 feature 分支，习惯性地在终端里敲 git diff，面对着一屏幕红绿混杂的 patch 文本，眉头一皱——增行、删行、改行混在一起，光靠肉眼很难快速定位真正的问题。传统做法是把改动推到 GitHub，在网页上打开 PR 才能看到语义化的行级别评论功能。但如果你还没 push，或者不想在远端留下痕迹呢？

Diffity（nilbuild/diffity）就是来解决这个问题的：它在你本地启动一个浏览器端的 Diff 工具，界面风格完全对标 GitHub PR Review——代码高亮、分屏对比、行级评论——但完全不依赖 GitHub。你可以在任何 git 仓库里直接运行 diffity，浏览器秒开，体验和 GitHub 如出一辙。

项目背景与作者

Diffity 由 Kamran Ahmed（@kamrify）开发维护，他在开发者社区以「Every Programmer Should Know」等工程教育内容闻名。项目采用 npm monorepo 架构，在 nilbuild 组织下维护，采用 PolyForm Shield 1.0.0 许可证（对商业闭源使用有保护）。

目前版本 v0.9.5，主分支托管于 GitHub，拥有 693 颗星（增长趋势 Score: 54.37），是近期增长较快的开发者工具项目。

给谁用、解决什么问题

简单来说，Diffity 是一款本地化的 GitHub PR Review 工具。它让你在提交代码前，就能像在 GitHub 网页上那样逐行评论、讨论、标注问题。

传统方式的痛点：

• git diff 输出的是原始 patch，没有语法高亮，没有语义上下文
• 想让 AI agent review 代码？Agent 只能看原始 diff，缺少交互界面
• 在团队工作流中，review 需要 push 到远端才能开始，流程笨重

Diffity 的解决思路： 在本地用一行命令启动一个带 Web UI 的 Diff 查看器，像 GitHub PR 一样支持行级评论、AI review、代码导览。Agent 可以直接读取评论并修复代码，实现「评论→AI 自动修复」的闭环。

核心功能详解

1. 浏览器 Diff 查看器

在任意 git 仓库运行 diffity，浏览器自动打开一个分屏对比的 Diff 视图：

diffity                      # 查看所有未提交改动
diffity HEAD~1               # 查看上一次提交
diffity main..feature        # 对比 main 和 feature 分支
diffity v1.0.0 v2.0.0        # 对比两个版本标签

支持统一视图（unified）和分屏视图（split），内置暗色模式，支持通过 --dark 参数切换。

2. AI 代码评审（Code Review）

配合 Claude Code、Cursor、Codex 等 AI 编程工具，Diffity 提供了完整的 Agent Skills：

命令	作用
/diffity-review	让 AI 在 Diff 上留下评论，标注 [must-fix]、[suggestion]、[nit]、[question] 四级严重性
/diffity-resolve	读取所有开放评论，让 AI 自动修复对应代码
/diffity-diff	打开 Diff 查看器，可传 refs、branch、commit range
/diffity-tour	引导式代码导览，AI 分析代码库后生成逐步解说

典型工作流：/diffity-review → 浏览器查看评论 → /diffity-resolve → AI 自动修复。

3. 引导式代码导览（Code Tours）

让 AI 深入研究代码库后，生成逐步导览。导览包含代码高亮区域和详细解说，支持按概念（"how does auth work?"）、按流程（"walk me through this PR"）、按技术点（"closures"、"generics"）等多种提问方式。每个导览步骤可包含子高亮（sub-highlights），点击可聚焦到函数内的特定逻辑片段。

4. 项目驱动学习（Learn Mode）

用 /diffity-learn 开启交互式学习之旅，指定一门语言或框架，AI agent 会：

1. 创建教学项目（learn-<topic>/ 目录）
2. 以导览形式打开，边做边讲
3. 给出练习题让你写代码
4. 用 Diffity 评论反馈你的代码
5. 根据进度动态调整后续内容

进度保存在 learn.json，随时可以接着学。

5. GitHub PR 集成

传入 GitHub PR URL 直接在本地打开该 PR 的 Diff（需安装 gh CLI 并认证），可以在本地评论并推送到 GitHub 成为正式的 PR review 评论，也可以拉取现有 GitHub 评论到本地查看。打通本地工作流和 GitHub 远端评论系统。

6. 多项目并行

Diffity 支持同时在多个仓库运行，每个实例自动分配不同端口（从 5391 开始），不会冲突。diffity list 查看所有运行中的实例，diffity --new 强制重启。

7. 文件树浏览器

diffity tree 打开全仓库文件树，可浏览、阅读（语法高亮）、评论任意文件，配合 /diffity-resolve-tree 让 AI 修复文件级评论。

技术架构解析

Monorepo 结构

Diffity 采用 npm workspaces 构建 monorepo，主 package.json 声明了 5 个子包：

packages/
  cli/        — npm 全局 CLI 入口（diffity 命令）
  git/        — git 操作封装（diff、commit、tree 等）
  github/     — GitHub PR API 集成（评论推送/拉取）
  parser/     — Git diff 文本解析
  ui/         — React Web UI（浏览器端）
  skills/     — Claude Code / Cursor agent skills

cli 包（packages/cli）：

• 入口：src/index.ts，使用 commander 解析 CLI 参数
• 核心：src/server.ts，Node.js 原生 HTTP 服务器（非 Express），直接处理路由
• 数据库：better-sqlite3，用于持久化评论线程和会话信息
• 浏览器打开：open 库自动调用系统默认浏览器

git 包（@diffity/git）：

• getDiff()、getDiffStatForRef()、resolveDiffArgs() 等核心函数
• getTree()、getTreeEntries()、getWorkingTreeFileContent() 等文件浏览
• 支持 revert hunk 和 revert file 操作（revertHunk、revertFile）
• 测试：vitest 完整测试套件

parser 包（@diffity/parser）：

• 解析原始 git diff 输出为结构化 ParsedDiff 对象
• 输出给 server.ts 中的 parseDiff() 函数使用

ui 包（@diffity/ui）：

• 框架：React 19 + React Router v7
• 构建工具：Vite + Tailwind CSS v4
• 语法高亮：Shiki v4（VS Code 同款高精度语法高亮）
• Markdown 渲染：react-markdown + remark-gfm（GitHub Flavored Markdown）
• 图表：mermaid（流程图、时序图支持）
• 虚拟列表：@tanstack/react-virtual，处理大文件列表
• HTTP 客户端：@tanstack/react-query

github 包（@diffity/github）：

• pushComments()、pullComments() 打通 GitHub PR Review API
• checkoutPr() 自动拉取 PR 到本地
• 认证检测：isAuthenticated() 检查 gh CLI 状态

部署方式

• 开发调试：npm install && npm run dev，自动启动 5 个 watcher 进程（parser、git、cli、ui、skills）
• 生产使用：npm install -g diffity，全局安装后即可在任意 git 仓库使用
• 依赖：Node.js >= 18，无任何外部服务依赖，纯本地运行
• 无 Docker 支持：没有 Dockerfile 或 docker-compose，不支持容器化部署

局限与注意事项

1. 没有 Docker 支持：无法一键容器化部署，必须在宿主机安装 Node.js >= 18，对 Docker-first 团队不太友好。
2. 单用户本地工具：虽然支持多项目并行，但设计目标是单开发者本地使用，不是团队协作平台。
3. 依赖 gh CLI 做 GitHub PR：完整的 PR 功能需要 gh auth login，在没有认证的机器上 PR 功能不可用。
4. 评论持久化在 SQLite：数据存在本地 ~/.diffity.db，不适合跨设备同步。
5. Agent 生态锁定：AI review 功能需要 Claude Code / Cursor / Codex 等特定 Agent，不是通用接口。

行业意义与趋势

Diffity 体现了 AI 编程时代的一个明确趋势：从「AI 输出代码 → 人类 review」转向「AI 在代码上下文中评论 → AI 自动修复」的闭环。传统 Code Review 依赖人在 GitHub 网页上逐行写评论，效率低且容易遗漏；Diffity 把评论能力赋予 AI Agent，让 review 和 fix 变成一个连续的自动化流程。

结合 Claude Code 等 Agent 工具，Diffity 正在构建「本地先行 review → push 后 GitHub 同步」的新工作流。对个人开发者和小型团队尤其有价值，因为它不需要任何基础设施，只要装好 Node.js 就能用。