Skip to content
Back to search

oil-diff

SkillWorks with Claude CodeGitHub

"将 Git 改动、提交范围或工作区修改生成直观易读的可视化 HTML 改动汇报页(含业务模块速览、前后对比图示、具体例子、单行改动文件树与右侧原文对照抽屉)。用户要求解释一轮代码或文档改了什么、把 git diff 做成汇报页或可视化演示页、向老板或团队展示仓库改动时使用。不用于执行代码修改、Git 提交、常规 Code Review 缺陷审计或制作通用幻灯片。"

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/oil-oil--oil-diff/badge.svg)](/listings/oil-oil--oil-diff)

HTML

<a href="/listings/oil-oil--oil-diff"><img src="/api/listings/oil-oil--oil-diff/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**方式一 · 命令行安装**

npx skills add oil-oil/oil-diff

**方式二 · 直接发给 Agent 安装**

请帮我安装这个 Skill:https://github.com/oil-oil/oil-diff

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 105 lines
  1. ---
  2. name: oil-diff
  3. description: "将 Git 改动、提交范围或工作区修改生成直观易读的可视化 HTML 改动汇报页(含业务模块速览、前后对比图示、具体例子、单行改动文件树与右侧原文对照抽屉)。用户要求解释一轮代码或文档改了什么、把 git diff 做成汇报页或可视化演示页、向老板或团队展示仓库改动时使用。不用于执行代码修改、Git 提交、常规 Code Review 缺陷审计或制作通用幻灯片。"
  4. license: MIT
  5. compatibility: "核心采集、渲染与校验脚本只依赖 Python 3.10+ 标准库和系统 git 命令;生成的 HTML 汇报页为零外部依赖的单文件页面,可在现代桌面与移动浏览器直接打开。已在 macOS 实机验证,Windows 与 Linux 完成跨平台静态检查。"
  6. metadata:
  7. version: "0.1.0"
  8. ---
  9. # oil-diff
  10. 把零散的 Git 改动转化为非代码作者(如项目负责人、产品伙伴、协作者)一眼能看懂的**可视化改动汇报页**。以“让未参与编码的读者 30 秒内看懂改了哪块业务、原来有什么痛点、现在怎么运作、改了哪些文件”为唯一交付标准。
  11. ## 仓库安全底线与 `.oil-diff/` 目录约定
  12. - 默认只在目标仓库下的未跟踪目录 `<repo>/.oil-diff/` 写入文件,第一步必须确认 `<repo>/.oil-diff/.gitignore` 内容精确为 `*` 加换行(自动让整个 `.oil-diff/` 对 Git 隐形,不修改目标项目根 `.gitignore`)。
  13. - `<repo>/.oil-diff/index.html` 只放最终交付的自包含单文件汇报页;中间数据(`diff-data.json`)、业务归因规格(`report-spec.json`)及核验截图统一放入 `<repo>/.oil-diff/assets/`。
  14. - 严禁执行 `git add`、`git commit`、`git checkout`、`git reset`、`git stash` 或修改任何已跟踪文件;交付前验证目标仓库的 `HEAD` 与 `git status --short` 和执行前完全一致。
  15. ## 先选择模式
  16. | 模式 | 适用情况 | 路径 | 默认停止点 |
  17. | --- | --- | --- | --- |
  18. | 生成汇报 | 给定仓库、分支、提交范围或未提交工作区,首次生成汇报页 | 采集数据 → 业务归因与文案 → 构建图示 → 渲染 HTML → 校验 | 产出 `.oil-diff/index.html` 并通过校验 |
  19. | 局部更新 | 已有 `.oil-diff/`,需调整章节划分、文案、图示或比较范围 | 读取现有配置 → 按需重跑采集或修改规格 → 重新渲染 → 校验 | 更新 `.oil-diff/index.html` 并通过校验 |
  20. | 质量核验 | 已有 `.oil-diff/index.html`,只检查文案、结构与仓库边界 | 运行 `scripts/lint_report.py` → 按需用浏览器工具静态截图检查 | 输出核验结论后停止 |
  21. 下文的 `<python>` 指版本不低于 3.10 的 Python 解释器:macOS 与 Linux 通常使用 `python3`,Windows 通常使用 `py -3`。
  22. ## 执行工作流
  23. > **默认委托独立子 Agent 执行(保护主对话上下文)**:
  24. > 若当前是主对话 Agent 且宿主支持启动子 Agent,**优先启动一个具备读写与命令执行能力的独立子 Agent** 跑完下方第 1~5 步闭环(避免大体积 `diff-data.json` 撑爆主对话上下文);若自身已是子 Agent 或宿主不支持子 Agent,则在当前上下文直接执行。
  25. > **主 Agent 启动子 Agent 时必须交接以下 3 项事实(防止子 Agent 脱离上下文盲猜)**:
  26. > 1. **入口与目标**:本 `SKILL.md` 的路径、目标仓库路径与比较范围(要求子 Agent 先完整阅读本 `SKILL.md`、[references/copywriting-and-structure.md](references/copywriting-and-structure.md) 与 [references/visual-and-interaction.md](references/visual-and-interaction.md));
  27. > 2. **本轮真实背景摘要**:用 3~5 句话概括本轮改动的目的、解决了什么问题(若主对话刚完成这轮修改,直接把真实意图告诉子 Agent);
  28. > 3. **实测截图白名单**:明确列出本轮是否有真实运行截出的图片路径;**若无真实实测截图,必须明确指令子 Agent:“本轮无实测截图,严禁从仓库 `_work/`、`research/` 等目录找图,全部使用内置矢量视觉积木”**。
  29. ### 1. 采集确定性 Git 改动数据
  30. 确定要汇报的仓库路径与比较范围(如未提交工作区、最近一轮提交,或 `base..head` 多段提交范围),运行 [scripts/collect_diff.py](scripts/collect_diff.py):
  31. ```text
  32. <python> scripts/collect_diff.py --repo <目标仓库路径> --output <目标仓库路径>/.oil-diff
  33. ```
  34. 需要指定多段比较范围时,传入一或多个 `--range <范围ID>:<显示名称>:<起点>..<终点>`(终点为工作区时写 `WT`)。脚本会自动创建 `.oil-diff/.gitignore`(写入 `*`)和 `.oil-diff/assets/`,并提取所有改动文件的路径、增删行数、行级修改块(hunks)及所在章节或函数上下文,保存为 `<output>/assets/diff-data.json`。
  35. ### 2. 按业务模块归因并撰写结构化文案
  36. 先完整读取 [文案与三层排版规范](references/copywriting-and-structure.md)。不要按文件列表逐个罗列改动,而是站在熟悉项目业务的汇报者视角,把全部改动文件归纳为 **3~7 件业务事项**,生成 `<output>/assets/report-spec.json`:
  37. 1. **业务模块与标题**:每件事必须标注简短的 `module`(业务模块胶囊,如 `工作区评审`、`鉴权中间件`),标题遵循「所属业务模块/工具 + 具体动作 + 机制变化」,禁止写成脱离项目语境的泛泛常识句。
  38. 2. **一两句话讲清痛点与改法(`overview`)**:用 1~2 句平实中文写好 `overview`,交代清楚原来有什么具体麻烦、现在改成怎么运作,把作者自造缩写翻译为具体动作。
  39. 3. **具体改法要点与核心文件归类**:每件事拆分为 2~4 个改法要点(`points`),将真正改动核心逻辑的文件挂在对应要点下(渲染为 `🎯 核心必看` 胶囊);其余顺手同步修改的外围文档只需列入章节 `fileIds`,渲染器会自动将其收进章节底部的 `📎 外围同步` 折叠条。
  40. ### 3. 配置实拍截图与微缩可视化舞台(配图零段落)
  41. 先读取 [视觉风格、可视化模式与交互规范](references/visual-and-interaction.md)。在 `.oil-diff/assets/report-spec.json` 的每个章节项中配置结构化 `"diagram"` 对象(遵循「配图是配图,文字是文字」,`<figure class="diagram">` 内严禁出现 `<p>` 段落长句):
  42. - **真实截图防伪铁律(`type: "screenshots"` 仅限真实运行产物,必须标注 `captureSource`)**:只有当本次改动确实由 Agent 实机运行并截出画面(`"captureSource": "live-capture"`)、用户明确提供了本次改动的实测截图(`"captureSource": "user-provided"`)、或图片本身就是本次 Git Diff 的跟踪文件(`"captureSource": "git-diff"`)时,才允许放入 `<output>/assets/shots/` 并使用截图字段。**严禁从仓库的临时目录(如 `_work/`、`research/`、调研素材、网上参考图)拷贝非本次实测的图片冒充修改前后截图**;`scripts/lint_report.py` 会通过 SHA-256 哈希比对自动拦截任何从仓库非改动区拷贝的图片。纯文档、规则或后端改动无真实运行截图时,一律使用下方的矢量微缩积木。
  43. - **无实拍图时选用 5 类纯视觉积木**:从 `"type": "routing" | "scenarios" | "flow" | "schema" | "diagnostics"`(或 `"comparison" | "alignment"`)中选择与章节主题 100% 对应的结构化模式,并根据项目实际业务填写自定义字段(如 `brand`、`goodHeading`、`badText`、`goodText`),避免直接沿用无关兜底词。
  44. - 如需自定义 `diagramHtml`,必须包含微缩视觉图元且只放 2~10 字的极简短标签,严禁塞入 `<p>` 段落句子。
  45. ### 4. 渲染自包含 HTML 汇报页(Bento 看板与分类必看漏斗)
  46. 运行 [scripts/render_report.py](scripts/render_report.py),将 `.oil-diff/assets/diff-data.json`、`.oil-diff/assets/report-spec.json` 与内置静态资源合成为单文件页面:
  47. ```text
  48. <python> scripts/render_report.py --report-dir <output>
  49. ```
  50. 渲染器会自动校验所有改动文件是否均已归入章节、核对摘录行号是否存在,并嵌入 [assets/report.css](assets/report.css) 与 [assets/report.js](assets/report.js),生成包含以下核心能力的 `index.html`:
  51. - **默认 Bento 看板布局(`#bento-deck`)**:首屏通过单行紧凑模块卡片(`1..N`)导航直达各章,不重复摘抄正文段落;主体采用双列 Bento 书页网格,高密度整合每章结论、实拍截图/架构图与改动要点,不输出底部冗余全量文件表(`#all-files`);
  52. - **按具体改动分类的「🎯 核心必看 / 📎 外围同步」漏斗**:在每个章节卡底部,将核心代码文件(`🎯 核心必看`)直接归类挂在 `1`、`2` 具体改法要点下方(`.point-pills`),将顺手同步的外围引用文件收进底部的 `📎 外围同步` 折叠条;
  53. - **可收起的窄栏改动文件树与右侧原文对照抽屉**:右侧文件树默认 `256px` 窄栏并支持一键「收起 ⇥ / ⇤ 文件树」释放全宽画布;点击任一核心文件胶囊、外围同步文件或右侧文件树,从右侧滑出 `720px` 代码对照抽屉。
  54. ### 5. 质量核验与双视口视觉检查
  55. 渲染完成后,运行 [scripts/lint_report.py](scripts/lint_report.py) 执行静态质量、防伪与安全边界检查:
  56. ```text
  57. <python> scripts/lint_report.py --repo <目标仓库路径> --report-dir <output>
  58. ```
  59. - 校验器会强制检查:
  60. 1. **截图真实性防伪(SHA-256 比对 + `captureSource` 核验)**:拦截未声明 `captureSource` 的截图,以及从仓库非 Diff 目录(如 `_work/`、历史素材)搬运冒充的图片;
  61. 2. **配图零段落与排版精简**:禁止 `<figure class="diagram">` 内出现 `<p>` 段落句子,确认启用 `#bento-deck`、按要点分类的 `.point-pills`、文件树折叠按钮 `[data-tree-toggle]`,且无冗余 `#all-files` 总表;
  62. 3. **文风与仓库零污染**:拦截空洞套话、检查 `.gitignore` 严格隔离及仓库 `git status` 未被污染。
  63. - 若当前宿主提供浏览器工具,必须在 **宽屏桌面(`1440px`)与小屏笔记本(`1100px`)双视口** 下打开 `<output>/index.html` 截图检查:确认小屏下双列卡片或三联图未发生文字挤压截断、文件树一键收起与展开正常、点击文件胶囊滑出右侧原文对照抽屉正常。只用静态截图与 DOM 检查,不录制视频。
  64. ## 资源导航
  65. - **参考规范**:
  66. - [references/copywriting-and-structure.md](references/copywriting-and-structure.md):撰写章节标题、速览句子与编写 `report-spec.json` 前必读。
  67. - [references/visual-and-interaction.md](references/visual-and-interaction.md):设计每章 HTML/CSS 可视化舞台与检查右侧抽屉交互前必读。
  68. - **脚本与静态资源**:
  69. - [scripts/collect_diff.py](scripts/collect_diff.py):步骤 1 采集 Git 改动并初始化 `.oil-diff/.gitignore`。
  70. - [scripts/render_report.py](scripts/render_report.py):步骤 4 内联 [assets/report.css](assets/report.css) 与 [assets/report.js](assets/report.js) 生成 `index.html`。
  71. - [scripts/lint_report.py](scripts/lint_report.py):步骤 5 校验文案、DOM 结构与 Git 零污染边界;修改脚本后运行 [tests/test_oil_diff.py](tests/test_oil_diff.py)。
  72. ## 输出与停止条件
  73. 当 `<output>/index.html` 生成完毕、`scripts/lint_report.py` 输出 `PASS`、且确认目标仓库的 Git 状态无任何新增修改时停止。向用户交付 `<output>/index.html` 的文件路径,并简要列出所归纳的业务事项标题与改动文件统计。
README.md · README · 101 lines
  1. <p align="center">
  2. <img src="./assets/readme/hero.svg" width="100%" alt="oil-diff:把零散的 Git 改动,变成人人看得懂的可视化汇报页。">
  3. </p>
  4. `oil-diff` 是一个 **Git 改动可视化汇报 Skill**。它把工作区修改、某次提交或分支之间的 Git Diff,按业务目的整理成 **3~7 件具体的事**,自动生成一份一屏看懂的 HTML 汇报页(`.oil-diff/index.html`)。
  5. 无论是向团队汇报一轮改动、合并代码前自己通览全局,还是想快速搞懂 AI 刚才改了什么,都不需要按字母顺序挨个翻几十个源码文件——打开网页,30 秒就能看清改了哪几块业务、为什么改、核心要看哪几个文件。
  6. <p align="center">
  7. <img src="./assets/readme/before-after.svg" width="100%" alt="对比直接翻看原始 Git Diff 与使用 oil-diff 阅读可视化汇报页的差异。">
  8. </p>
  9. ## 核心功能
  10. <p align="center">
  11. <img src="./assets/readme/section-features.svg" width="100%" alt="核心功能:按业务讲人话,配直观图示与代码抽屉">
  12. </p>
  13. ### 1. 一屏 Bento 看板,按业务讲人话
  14. 不再按文件列表罗列改动,而是把整批修改归纳成几张清晰的业务卡片:顶部先给出一行模块导航,每张卡片用平实的话讲清「原来有什么痛点、现在怎么解决」,拒绝空洞的技术黑话。
  15. <p align="center">
  16. <img src="./assets/readme/case-overview.png" width="100%" alt="oil-diff 首屏总览与右侧改动文件树。">
  17. </p>
  18. ### 2. 配图是配图,文字是文字
  19. 每一章都配有直观的前后对比图,不用大段文字凑数:
  20. - **有界面改动时**:支持放入修改前后的真实运行截图,直接拖动滑杆对比或点击放大;
  21. - **纯逻辑或规则改动时**:自动生成路由分流图、控件前后对比、流程变化或字段增删表,一眼看懂机制变化。
  22. <p align="center">
  23. <img src="./assets/readme/case-diagram-routing.png" width="100%" alt="章节配图示例:把复杂的规则拆分画成直观的分流结构。">
  24. </p>
  25. ### 3. 按具体改动分类「🎯 核心必看」与「📎 外围同步」
  26. 一次改动涉及几十个文件时,自动帮你分好轻重缓急:
  27. - **🎯 核心必看**:直接归类挂在每章的 `1`、`2` 具体改动点下方,标明增删行数,告诉你 Review 时最该看哪几个文件;
  28. - **📎 外围同步**:顺手同步修改的引用、配置或文档自动折叠收在卡片底部,不抢视线、也不漏文件。
  29. ### 4. 可收起文件树 + 右侧滑出代码抽屉
  30. 右侧配有紧凑的改动文件树(支持一键收起释放全宽画布)。想看某处具体改了哪几行代码时,点一下「核心必看」文件胶囊或右侧文件树,右侧立即滑出修改前后代码对照抽屉,主页面原地不动、不乱滚。
  31. <p align="center">
  32. <img src="./assets/readme/case-drawer.png" width="100%" alt="点击文件从右侧滑出修改前后代码对照抽屉。">
  33. </p>
  34. ## 安装与使用
  35. <p align="center">
  36. <img src="./assets/readme/section-use.svg" width="100%" alt="安装与使用:直接把仓库或分支交给你的 Agent">
  37. </p>
  38. ### 安装
  39. **方式一 · 命令行安装**
  40. ```bash
  41. npx skills add oil-oil/oil-diff
  42. ```
  43. **方式二 · 直接发给 Agent 安装**
  44. ```text
  45. 请帮我安装这个 Skill:https://github.com/oil-oil/oil-diff
  46. ```
  47. ### 日常使用
  48. 安装后,直接在对话里告诉 Agent 你想看哪部分改动即可:
  49. ```text
  50. 用 oil-diff 把当前分支最近的改动做成汇报页。
  51. ```
  52. ```text
  53. 用 oil-diff 整理目前还没提交的修改,生成一份 HTML 改动汇报。
  54. ```
  55. ```text
  56. 用 oil-diff 对比 main..HEAD 的改动,看看这轮到底改了哪几件事。
  57. ```
  58. ## 适用边界、数据与运行环境
  59. - **零污染仓库状态**:生成的网页与数据全部放在 `<repo>/.oil-diff/` 目录下,并自动对 Git 隐形,不修改项目原本的任何文件,也不影响 `git status`。
  60. - **单文件离线可用**:最终生成的 `.oil-diff/index.html` 是零外部依赖的单文件网页,双击就能在浏览器打开,也可以直接发给同事查看。
  61. - **配置与兼容性**:无需额外配置 API Key 或环境变量;仅依赖系统 `git` 与 Python 3.10+ 标准库,支持 macOS、Windows 与 Linux。
  62. 平时配合 Git 分支、Worktree 和 PR 管理改动的做法,也可以参考 Oil Book 里的[《从 0 到 1 学会使用 Git 与 GitHub》](https://book.oiloil.org/articles/git-from-scratch?utm_source=github&utm_medium=referral&utm_campaign=oil-diff-readme)。
  63. <p align="center">
  64. <a href="https://github.com/oil-oil/beautify-github-readme"><img src="./assets/readme/made-with-beautify.svg" width="300" alt="README made with beautify-github-readme"></a>
  65. </p>
  66. ## 许可证
  67. MIT License

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.