pi-file-diff

每轮发生文件改动的 Pi 任务稳定结束后，pi-file-diff 都会自动追加一份可复核的改动回执；无需输入命令或手动查看。它会说明改了哪些文件、各有多少增删行；需要细看时，还能在终端内逐文件查看完整 diff。它既可用于 Git 仓库，也可用于普通目录。

pi install npm:pi-file-diff

目录

• 它是什么
• 为什么创建它
• 演示
• 与现有 Pi 插件的定位对比
• 安装
• 命令
• 配置
• 追踪原理
• 开发

它是什么

Pi agent 可以通过 write、edit 修改文件，也可以通过 shell 间接修改。pi-file-diff 会在一次对话中记录这些变化，并以两个层次呈现：

1. 自动任务回执：每一轮发生文件改动的用户可见任务真正稳定结束后，pi-file-diff 都会自动追加一份简洁的文件清单与总 +/- 行数；无需输入命令或额外提示。重试、压缩后的重跑、排队 follow-up 会合并为同一份回执，不会产生重叠的多次汇总。
2. 交互式查看面板：可浏览全部改动文件，并在不离开终端的情况下查看完整补丁。面板提供独立的 diff 标记栏、行号和分页，便于审阅多文件任务。

摘要以 TUI 条目形式追加，不会重新进入模型上下文，也不会因为展示回执而额外唤醒 agent。/file-diff 仅用于你按需回看当前对话累计的改动，并不是触发自动回执的前提。

每份自动回执只统计本轮任务（一次 agent_start → agent_settled 之间）实际改动的文件；之前任务的文件不会混入。整个会话的累计改动仍保留在扩展内部，可随时用 /file-diff 或 ctrl+q 面板回看。

为什么创建它

“agent 到底改了什么？”这一问题的答案往往分散在工具调用、shell 输出和 Git 状态里。在下面的场景中尤其不方便：

• 工作区并不是 Git 仓库；
• agent 改了仓库外文件，例如临时配置；
• 一次任务包含多次工具调用、重试或 follow-up；
• 你想先快速确认改了什么，只有在需要时才进入 diff 细看。

pi-file-diff 去掉了“记得去查看”的步骤：每轮发生文件改动的任务稳定结束后，它会自动追加回执；你无需输入 /file-diff、查看 Git 状态，也无需执行任何其他命令。它默认低打扰地给出任务结束回执，只有在你选择时才深入查看某个文件的差异。

演示

从任务结束时自动追加的回执，到逐文件完整补丁，整个审阅流程都在 Pi 的终端界面内完成。

1. 任务结束回执

每轮发生文件改动的用户可见任务稳定结束后，pi-file-diff 都会自动追加这份简洁回执；无需输入命令。

2. 文件浏览面板

在回执中按 Ctrl+Q 打开交互式文件列表，可审阅全部改动文件；Git 已跟踪与未跟踪路径会分别汇总展示。

3. 单文件 Diff

选择一个文件即可查看补丁。增删标记位于独立 gutter，且每行旁会显示对应的旧文件或新文件行号。

与现有 Pi 插件的定位对比

这些插件解决的是相邻而不相同的问题。请按工作流选择；它们也可以组合使用。

| 需求 | pi-file-diff | @slix/pi-file-tracker | @geminixiang/pi-diff | @kkskcs/pi-diff-inline | | --- | --- | --- | --- | --- | | 主要呈现位置 | 任务结束回执 + 终端 Diff 面板 | 输入框上方持续显示的实时组件 | 浏览器中的 Git Diff 面板 | 对话流内嵌 Diff 渲染 | | 初次如何出现 | 自动追加：每轮有文件改动的稳定任务结束后显示，无需输入命令 | 持续可见的实时组件 | 手动执行 /diff 打开面板 | 渲染传入的一段 diff 或两份文本比较 | | 主要工作单位 | 一段稳定任务；需要时可回看整场对话累计改动 | 当前会话里实时触及的文件 | 工作区、暂存区和提交历史的 Git Diff | 传入的一段 diff 或两份文本比较 | | 是否要求 Git 仓库 | 否。Git 信息仅用于可选分组。 | 否 | 是，其 /diff 基于 Git diff | 否 | | 审阅交互 | 终端内分页的逐文件 Diff 面板 | 实时状态和文件统计 | 浏览器审阅与评论工作流 | 内嵌 unified / split 渲染 | | 最适合的场景 | “任务完成后，给我一份可靠的变更回执。” | “始终显示当前文件活动。” | “在浏览器中审阅 Git 变更。” | “直接在对话中渲染一段 diff。” |

上表依据各插件在 Pi Package Catalog 的公开文档整理；各项目会独立演进。

安装

从 npm 安装 — 推荐

pi install npm:pi-file-diff

如果 Pi 已在运行，执行 /reload；否则重启 Pi。卸载：

pi remove npm:pi-file-diff

从本地仓库安装 — 开发用途

在已有的本地 checkout 中执行：

cd /path/to/pi-file-diff
npm install
pi install "$(pwd)"

日常使用请优先通过 npm 安装。

命令

扩展只提供四个主动命令，且职责明确：一个回答“改了什么”，一个控制“如何发现 shell 改动”，一个控制“哪些路径不值得进入审阅”，一个调节“何时把目录折叠成一条”。

/file-diff — 查看当前对话累计的变更集

/file-diff

当你想手动重新查看当前对话累计的文件改动时使用它。常见场景包括：自动回执已经滚出屏幕；你连续发了多个 follow-up，想获得一份合并后的总览；准备审阅、测试、提交或把工作交接给别人之前，想确认最终涉及哪些文件。

它与自动任务回执的区别在于：此命令不只看最后一次稳定任务，而会从扩展至今记录的全部变化重新构建当前对话的文件清单，并给出文件状态以及总增删行数。它是纯查看操作：不会重置已追踪的变更、不会修改任何文件，也不会把信息重新发送给模型。

/file-diff-mode — 有意识地选择 shell 改动追踪方式

/file-diff-mode [status|auto|on|off]

通过 Pi 原生 write、edit 产生的改动始终会被追踪。这个命令控制额外的文件系统扫描：它用于发现 shell 间接造成的改动，例如脚本生成文件、重定向写入、sed、cp、rm 等。

| 模式 | 何时使用 | 行为 | | --- | --- | --- | | status 或不带参数 | 不确定为什么某个 shell 改动出现或没有出现。 | 显示当前保存的模式、工作区文件数阈值和检测到的工作区大小。 | | auto | 大小不一的项目，适合默认使用。 | 工作区文件数低于 bashThreshold 时开启 shell 追踪；超过阈值时自动跳过开销更高的扫描。 | | on | 工作区规模可控，而且必须审阅 shell 生成或修改的文件。 | 即使超过自动阈值也强制开启 shell 追踪；任务结束时的扫描可能更慢。 | | off | 工作区很大、shell 输出不重要，或希望追踪开销最低。 | 只追踪 Pi 原生 write、edit；仅由 shell 造成的变化不会出现在回执中。 |

例如：

/file-diff-mode status
/file-diff-mode on
/file-diff-mode auto

选择会保存到 ~/.pi/agent/file-diff.json，并从下一次 agent 任务开始生效。切换项目或调整配置后，建议先运行 status，确认当前工作区与模式选择相匹配。

/file-diff-exclude — 把已知噪声移出审阅范围

/file-diff-exclude [<路径>|remove <路径>|clear]

当某些路径的变化不应干扰 agent 工作审阅时，使用排除规则。例如会话日志、缓存、每次运行都会变化的构建产物、vendor 目录或应用运行数据。排除规则只影响 pi-file-diff 的追踪与展示；它绝不会删除、移动或修改目标文件。

路径可以相对于当前工作区，也可以是绝对路径，或以 ~ 开头。既能排除整个目录，也能只排除单个文件；目录排除会覆盖其下所有内容。

| 目的 | 命令 | 何时使用 | | --- | --- | --- | | 添加排除路径 | /file-diff-exclude .pi-dock/sessions | 某个噪声目录反复出现在回执中。 | | 查看现有规则 | /file-diff-exclude | 想排查某个路径为何没有显示。 | | 恢复单一路径 | /file-diff-exclude remove .pi-dock/sessions | 该路径重新变得值得审阅。 | | 恢复全部路径 | /file-diff-exclude clear | 切换项目，或希望回到默认行为。 |

排除列表会保存到 ~/.pi/agent/file-diff.json。尽量在对话较早阶段添加规则，然后运行 /file-diff，确认剩下的回执只保留真正需要审阅的文件。

/file-diff-threshold — 目录聚合阈值

/file-diff-threshold [<数量>|status]

当一个目录下改动了大量文件时，回执与 ctrl+q 面板会把它们折叠成一条目录条目，末尾括号列出子树构成（零项省略），如 M src/ +40 -12 (修改 10 个文件，新增 3 个文件)。目录状态描述目录自身：全新目录 → +；已删除目录 → -；已存在目录即使只是新增了文件也是 M（修改）。

折叠只发生在当前工作区的子目录上，工作区根目录本身永不折叠；文件数少于阈值的目录仍逐个展示文件。在面板中选中目录条目后按 Enter/ctrl+q 进入目录，Esc/← 返回上一级。

阈值默认 5，最小 2，改动即时生效；也可以写入配置文件或环境变量（见 配置）。

配置

创建或编辑 ~/.pi/agent/file-diff.json，再执行 /reload 或重启 Pi：

{
  "lang": "en",
  "bashTracking": "auto",
  "bashThreshold": 200000,
  "dirThreshold": 5,
  "ignore": ["my_vendor"],
  "exclude": [".pi-dock/sessions"]
}

| 配置项 | 可选值 | 默认值 | 含义 | | --- | --- | --- | --- | | lang | en、zh | en | 界面语言。 | | bashTracking | auto、on、off | auto | 是否扫描 shell 引起的改动。auto 会在工作区超过阈值时关闭扫描。 | | bashThreshold | 正整数 | 200000 | auto 模式使用的工作区文件数阈值。 | | dirThreshold | 整数 ≥ 2 | 5 | 目录聚合阈值：cwd 子目录下改动文件数达到该值即折叠成一条目录条目。 | | ignore | 字符串数组 | [] | 额外忽略的目录名，不区分大小写。 | | exclude | 字符串数组 | [] | 不追踪、不展示的文件或目录路径。 |

环境变量 PI_FILE_DIFF_LANG、PI_FILE_DIFF_BASH_TRACKING 和 PI_FILE_DIFF_DIR_THRESHOLD 的优先级高于配置文件。

追踪原理

| 改动来源 | 检测方式 | 审阅结果 | | --- | --- | --- | | Pi edit 工具 | Pi 返回的 unified patch | 精确补丁和行数统计。 | | Pi write 工具 | 路径与写入内容 | 新文件内容或已追踪写入结果，以及统计信息。 | | shell / bash 工具 | 有界的工作区内容快照 + 任务结束扫描 | 基线可用时展示文本 Diff；否则只展示 shell 改动路径。 |

为了保持响应速度，扩展有以下边界：

• shell 扫描只覆盖工作区，并跳过常见的依赖、构建产物、VCS、缓存、IDE 目录，以及 AI 工具运行时目录（.codex、.claude、.cursor、.gemini、.pi 等——这些目录会被其他并发的 agent/工具会话持续写入，默认忽略）；
• 由 write/edit 追踪、但不在该扫描范围内的文件（位于会话工作区之外的项目，或位于被忽略目录中）仍会按工具结果列出；shell 扫描既不会把它们标为 shell 修改，也不会把它们误判为已删除。
• 文本快照有单文件大小与总内容量上限。大型、二进制、无法读取或超出范围的文件，可能只显示路径而不显示文本 Diff（如 *.sqlite-wal）；
• mtime 扫描只能判断「文件在任务窗口内被写过」，无法区分是 agent 还是其他进程写的。如果你并行编辑文件、或同一工作区内有其他 agent/工具正在运行（SQLite WAL/SHM、缓存、日志会持续变动），这些改动可能被归因到 shell。此时可以用 /file-diff-exclude 屏蔽对应目录，或在配置文件 ignore 中追加目录名；更好的做法是让 agent 在项目目录而非 HOME 这类包含运行时状态的目录中工作。

开发

要求：Node.js >= 22.18.0 与 npm。

npm install
npm run typecheck
npm test

贡献

欢迎提交问题和聚焦的 Pull Request。涉及界面的改动请附终端截图或能体现行为的测试。提交 PR 前请执行：

npm run typecheck && npm test

许可证

MIT © 2026 pi-file-diff contributors。