oil-diff

---
name: oil-diff
description: "将 Git 改动、提交范围或工作区修改生成直观易读的可视化 HTML 改动汇报页（含业务模块速览、前后对比图示、具体例子、单行改动文件树与右侧原文对照抽屉）。用户要求解释一轮代码或文档改了什么、把 git diff 做成汇报页或可视化演示页、向老板或团队展示仓库改动时使用。不用于执行代码修改、Git 提交、常规 Code Review 缺陷审计或制作通用幻灯片。"
license: MIT
compatibility: "核心采集、渲染与校验脚本只依赖 Python 3.10+ 标准库和系统 git 命令；生成的 HTML 汇报页为零外部依赖的单文件页面，可在现代桌面与移动浏览器直接打开。已在 macOS 实机验证，Windows 与 Linux 完成跨平台静态检查。"
metadata:
  version: "1.1.0"
---

# oil-diff

把零散的 Git 改动转化为非代码作者（如项目负责人、产品伙伴、协作者）一眼能看懂的**可视化改动汇报页**。以“让未参与编码的读者 30 秒内看懂改了哪块业务、原来有什么痛点、现在怎么运作、改了哪些文件”为唯一交付标准。

## 仓库安全底线与 `.oil-diff/` 目录约定

- 默认只在目标仓库下的未跟踪目录 `<repo>/.oil-diff/` 写入文件，第一步必须确认 `<repo>/.oil-diff/.gitignore` 内容精确为 `*` 加换行（自动让整个 `.oil-diff/` 对 Git 隐形，不修改目标项目根 `.gitignore`）。
- **默认写入版本化结构**：每次汇报落在自己的 `versions/v<NNN>_<时间>_<分支>_<起点>-<终点>/` 下，含 `meta.json`（版本证书）、`index.html`、`report-spec.json`、`diff-data.json` 与 `shots/`；根部 `index.html` 只是 1 KB 跳转页，`INDEX.md` 是自动生成的版本清单。**完整规范见 [references/layout-and-versioning.md](references/layout-and-versioning.md)，动手前必读**。
- **旧的平铺结构（根部 `index.html` + `assets/`）继续可读可更新**，不因升级而报错；想迁进版本目录用 `scripts/oildiff_versions.py migrate`。
- 严禁执行 `git add`、`git commit`、`git checkout`、`git reset`、`git stash`、`git clean` 或修改任何已跟踪文件；交付前验证目标仓库的 `HEAD` 与 `git status --short` 和执行前完全一致。

## 先选择模式

| 模式 | 适用情况 | 路径 | 默认停止点 |
| --- | --- | --- | --- |
| 生成汇报 | 给定仓库、分支、提交范围或未提交工作区，首次生成汇报页 | 采集数据 → 业务归因与文案 → 构建图示 → 渲染 HTML → 校验 | 新版本目录产出 `index.html` 并通过校验 |
| 局部更新 | 同一比较范围，只调整章节划分、文案或图示 | 复用原版本目录 → 改 `report-spec.json` → 重新渲染 → 校验 | 该版本 `index.html` 更新并通过校验（不新建版本） |
| 换范围重做 | 比较范围或 HEAD 变了 | 同上「生成汇报」，分配下一个 vNNN，**禁止覆盖旧版本** | 新版本目录产出 `index.html` |
| 版本维护 | 整理版本清单、清理旧版、重建被删的页面 | `oildiff_versions.py rebuild-index` / `prune` / `rerender` / `migrate` | 输出维护结果摘要 |
| 质量核验 | 已有汇报页，只检查文案、结构与仓库边界 | 运行 `scripts/lint_report.py` → 按需用浏览器工具静态截图检查 | 输出核验结论后停止 |

下文的 `<python>` 指版本不低于 3.10 的 Python 解释器：macOS 与 Linux 通常使用 `python3`，Windows 通常使用 `py -3`。

## 执行工作流

> **默认委托独立子 Agent 执行（保护主对话上下文）**：
> 若当前是主对话 Agent 且宿主支持启动子 Agent，**优先启动一个具备读写与命令执行能力的独立子 Agent** 跑完下方第 1～6 步闭环（避免大体积 `diff-data.json` 撑爆主对话上下文）；若自身已是子 Agent 或宿主不支持子 Agent，则在当前上下文直接执行。
> **主 Agent 启动子 Agent 时必须交接以下 3 项事实（防止子 Agent 脱离上下文盲猜）**：
> 1. **入口与目标**：本 `SKILL.md` 的路径、目标仓库路径与比较范围（要求子 Agent 先完整阅读本 `SKILL.md`、[references/layout-and-versioning.md](references/layout-and-versioning.md)、[references/copywriting-and-structure.md](references/copywriting-and-structure.md) 与 [references/visual-and-interaction.md](references/visual-and-interaction.md)）；
> 2. **本轮真实背景摘要**：用 3～5 句话概括本轮改动的目的、解决了什么问题（若主对话刚完成这轮修改，直接把真实意图告诉子 Agent）；
> 3. **实测截图白名单**：明确列出本轮是否有真实运行截出的图片路径；**若无真实实测截图，必须明确指令子 Agent：“本轮无实测截图，严禁从仓库 `_work/`、`research/` 等目录找图，全部使用内置矢量视觉积木”**。

### 1. 采集确定性 Git 改动数据

确定要汇报的仓库路径与比较范围（如未提交工作区、最近一轮提交，或 `base..head` 多段提交范围），运行 [scripts/collect_diff.py](scripts/collect_diff.py)：

```text
<python> scripts/collect_diff.py --repo <目标仓库路径> --output <目标仓库路径>/.oil-diff --versioned [--base merge-base]
```

- **`--versioned` 必带**（输出目录下已有 `versions/` 时自动走版本化，平铺仅用于兼容旧项目）。脚本会分配下一个 `vNNN`、建版本目录、写 `draft` 状态的 `meta.json`，并创建 `.oil-diff/.gitignore`（写入 `*`）。
- **stdout 是一段 JSON**，含 `versionDir`、`versionId`、`mode`、`comparison`、`counts`。后续步骤的路径一律取自 `versionDir`，不要自己拼。
- 需要指定多段比较范围时，传入一或多个 `--range <范围ID>:<显示名称>:<起点>..<终点>`（终点为工作区时写 `WT`）。
- **比较口径必须选对**（详见 [references/layout-and-versioning.md](references/layout-and-versioning.md) 第 6 节）：默认 `--base tip`（两点差异，回答「这条线和主分支现在差多少」）；若读者关心「本分支自己净加了什么」，用 `--base merge-base`，因为主分支 cherry-pick 过同类修复时两点口径会重复计算。
- 产物：`<versionDir>/diff-data.json`，含所有改动文件的路径、增删行数、行级修改块（hunks）及所在章节或函数上下文。

### 2. 按业务模块归因并撰写结构化文案

先完整读取 [文案与三层排版规范](references/copywriting-and-structure.md)。不要按文件列表逐个罗列改动，而是站在熟悉项目业务的汇报者视角，把全部改动文件归纳为 **3～7 件业务事项**，生成 `<versionDir>/report-spec.json`：

1. **业务模块与标题**：每件事必须标注简短的 `module`（业务模块胶囊，如 `工作区评审`、`鉴权中间件`），标题遵循「所属业务模块/工具 + 具体动作 + 机制变化」，禁止写成脱离项目语境的泛泛常识句。
2. **一两句话讲清痛点与改法（`overview`）**：用 1～2 句平实中文写好 `overview`，交代清楚原来有什么具体麻烦、现在改成怎么运作，把作者自造缩写翻译为具体动作。
3. **具体改法要点与核心文件归类**：每件事拆分为 2～4 个改法要点（`points`），将真正改动核心逻辑的文件挂在对应要点下（渲染为 `🎯 核心必看` 胶囊）；其余顺手同步修改的外围文档只需列入章节 `fileIds`，渲染器会自动将其收进章节底部的 `📎 外围同步` 折叠条。

### 3. 配置实拍截图与微缩可视化舞台（配图零段落）

先读取 [视觉风格、可视化模式与交互规范](references/visual-and-interaction.md)。在 `<versionDir>/report-spec.json` 的每个章节项中配置结构化 `"diagram"` 对象（遵循「配图是配图，文字是文字」，`<figure class="diagram">` 内严禁出现 `<p>` 段落长句）：

- **真实截图防伪铁律（`type: "screenshots"` 仅限真实运行产物，必须标注 `captureSource`）**：只有当本次改动确实由 Agent 实机运行并截出画面（`"captureSource": "live-capture"`）、用户明确提供了本次改动的实测截图（`"captureSource": "user-provided"`）、或图片本身就是本次 Git Diff 的跟踪文件（`"captureSource": "git-diff"`）时，才允许放入 `<versionDir>/shots/` 并使用截图字段。截图命名走 `shot-<两位序号>-<ASCII短标签>.png`，**每版自带 `shots/` 不共用**（共用会让旧版的图被新版误引用，也让「这张图属于哪一版」失去答案）。**严禁从仓库的临时目录（如 `_work/`、`research/`、调研素材、网上参考图）拷贝非本次实测的图片冒充修改前后截图**；`scripts/lint_report.py` 会通过 SHA-256 哈希比对自动拦截任何从仓库非改动区拷贝的图片。纯文档、规则或后端改动无真实运行截图时，一律使用下方的矢量微缩积木。
- **无实拍图时选用 5 类纯视觉积木**：从 `"type": "routing" | "scenarios" | "flow" | "schema" | "diagnostics"`（或 `"comparison" | "alignment"`）中选择与章节主题 100% 对应的结构化模式，并根据项目实际业务填写自定义字段（如 `brand`、`goodHeading`、`badText`、`goodText`），避免直接沿用无关兜底词。
- 如需自定义 `diagramHtml`，必须包含微缩视觉图元且只放 2～10 字的极简短标签，严禁塞入 `<p>` 段落句子。

### 4. 渲染自包含 HTML 汇报页（Bento 看板与分类必看漏斗）

运行 [scripts/render_report.py](scripts/render_report.py)，将 `<versionDir>/diff-data.json`、`<versionDir>/report-spec.json` 与内置静态资源合成为单文件页面：

```text
<python> scripts/render_report.py --report-dir <versionDir>
```

渲染器会自动校验所有改动文件是否均已归入章节、核对摘录行号是否存在，并嵌入 [assets/report.css](assets/report.css) 与 [assets/report.js](assets/report.js)，生成包含以下核心能力的 `index.html`：
- **默认 Bento 看板布局（`#bento-deck`）**：首屏通过单行紧凑模块卡片（`1..N`）导航直达各章，不重复摘抄正文段落；主体采用双列 Bento 书页网格，高密度整合每章结论、实拍截图/架构图与改动要点，不输出底部冗余全量文件表（`#all-files`）；
- **按具体改动分类的「🎯 核心必看 / 📎 外围同步」漏斗**：在每个章节卡底部，将核心代码文件（`🎯 核心必看`）直接归类挂在 `1`、`2` 具体改法要点下方（`.point-pills`），将顺手同步的外围引用文件收进底部的 `📎 外围同步` 折叠条；
- **可收起的窄栏改动文件树与右侧原文对照抽屉**：右侧文件树默认 `256px` 窄栏并支持一键「收起 ⇥ / ⇤ 文件树」释放全宽画布；点击任一核心文件胶囊、外围同步文件或右侧文件树，从右侧滑出 `720px` 代码对照抽屉；
- **页头版本戳**：`.report-meta` 里输出 `v003 · 生成于 … · 分支 · main 5816ed1 → 7c60e6f · 48 个提交`，同一条信息写进 `<title>` 与 `<meta name="description">`。汇报页会被截图、转发、存成 PDF，**脱离文件夹之后页面自己必须能证明自己是谁**。

渲染完成后渲染器会**回填 `meta.json`**：写入 `artifacts`（三个产物的字节数与 sha256）、`chapters`、`counts.core/peripheral`，并把 `status` 从 `draft` 置为 `final`。因此**必须先写 `report-spec.json` 再渲染**，顺序颠倒会得到一份缺章节信息的证书。

### 5. 质量核验与双视口视觉检查

渲染完成后，运行 [scripts/lint_report.py](scripts/lint_report.py) 执行静态质量、防伪与安全边界检查：

```text
<python> scripts/lint_report.py --repo <目标仓库路径> --report-dir <目标仓库路径>/.oil-diff
```

`--report-dir` 传**报告根目录**（`.oil-diff`）或**单个版本目录**都接受：传根目录时逐个版本校验并汇总，传版本目录只校验那一版。

- 校验器会强制检查：
  1. **截图真实性防伪（SHA-256 比对 + `captureSource` 核验）**：拦截未声明 `captureSource` 的截图，以及从仓库非 Diff 目录（如 `_work/`、历史素材）搬运冒充的图片；
  2. **配图零段落与排版精简**：禁止 `<figure class="diagram">` 内出现 `<p>` 段落句子，确认启用 `#bento-deck`、按要点分类的 `.point-pills`、文件树折叠按钮 `[data-tree-toggle]`，且无冗余 `#all-files` 总表；
  3. **版本证书完整性**：`meta.json` 必填键齐全、`versionId` 格式合法、`status`/`mode` 取值在枚举内、目录名与 `meta.folder` 一致、`artifacts.indexHtml.sha256` 与磁盘文件相符（不符通常是 `write_text` 把 `\n` 转成了 `\r\n`）、页头版本戳的 `data-*` 属性与 `meta` 一致；
  4. **文风与仓库零污染**：拦截空洞套话、检查 `.gitignore` 严格隔离及仓库 `git status` 未被污染。
- 若当前宿主提供浏览器工具，必须在 **宽屏桌面（`1440px`）与小屏笔记本（`1100px`）双视口** 下打开版本目录里的 `index.html` 截图检查：确认小屏下双列卡片或三联图未发生文字挤压截断、文件树一键收起与展开正常、点击文件胶囊滑出右侧原文对照抽屉正常。只用静态截图与 DOM 检查，不录制视频。

### 6. 交付后维护版本目录

增量出过几版之后，用 [scripts/oildiff_versions.py](scripts/oildiff_versions.py) 维护（详细口径见 [references/layout-and-versioning.md](references/layout-and-versioning.md) 第 7 节）：

```text
<python> scripts/oildiff_versions.py --root <out> rebuild-index     # 重写 INDEX.md 与根部跳转页
<python> scripts/oildiff_versions.py --root <out> prune --dry-run   # 先看会删什么（默认留 10 版 / 200MB）
<python> scripts/oildiff_versions.py --root <out> rerender --version v003   # index.html 丢了可重建
<python> scripts/oildiff_versions.py --root <out> migrate --repo <repo>    # 旧平铺结构一次性迁入
```

原则：**清理只删 `versions/<folder>/` 内部**（脚本内 `assert_inside_versions()` 断言路径前缀，防拼错）；`diff-data.json` 只留最近 3 版；`pinned: true` 的版本永不自动删；`INDEX.md` 里 `missing` 行不隐藏，否则「曾经有过这一版」这段事实就丢了。

## 资源导航

- **参考规范**：
  - [references/layout-and-versioning.md](references/layout-and-versioning.md)：**动手前必读**。`.oil-diff/` 目录布局、版本目录命名、`meta.json` 字段、`INDEX.md` 列口径、比较模式选择、保留清理策略与 15 条边界情况。
  - [references/copywriting-and-structure.md](references/copywriting-and-structure.md)：撰写章节标题、速览句子与编写 `report-spec.json` 前必读。
  - [references/visual-and-interaction.md](references/visual-and-interaction.md)：设计每章 HTML/CSS 可视化舞台与检查右侧抽屉交互前必读。

- **脚本与静态资源**：
  - [scripts/collect_diff.py](scripts/collect_diff.py)：步骤 1 采集 Git 改动、分配版本号、写 `draft` 状态的 `meta.json` 并初始化 `.oil-diff/.gitignore`。
  - [scripts/render_report.py](scripts/render_report.py)：步骤 4 内联 [assets/report.css](assets/report.css) 与 [assets/report.js](assets/report.js) 生成 `index.html`，并回填 `meta.artifacts` / `status: final`。
  - [scripts/lint_report.py](scripts/lint_report.py)：步骤 5 校验文案、DOM 结构、版本证书一致性与 Git 零污染边界。
  - [scripts/oildiff_versions.py](scripts/oildiff_versions.py)：步骤 6 版本维护（`rebuild-index` / `prune` / `rerender` / `migrate` / `new`）。
  - [scripts/oildiff_paths.py](scripts/oildiff_paths.py)：共享布局模块（`detect_layout` / `artifact_paths` / 命名与原子写），四个脚本都依赖它，改动需同步。
  - 修改脚本后运行 [tests/test_oil_diff.py](tests/test_oil_diff.py)（unittest）。

## 输出与停止条件

当版本目录里的 `index.html` 生成完毕、`scripts/lint_report.py` 输出 `PASS`、且确认目标仓库的 Git 状态无任何新增修改时停止。向用户交付 `<versionDir>/index.html` 的文件路径（并说明打开 `.oil-diff/index.html` 会自动跳到最新一版），简要列出所归纳的业务事项标题与改动文件统计。

• .gitignore 1 KB
• LICENSE 1 KB
• README.md 6 KB
• SKILL.md 16 KB