explain-diff

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Explain Diff

Produce one teaching artifact: a long-page HTML file with Background, Intuition, Code, and Quiz. Not a PR description (

make-pr

) and not inline chat prose—the reader opens the file in a browser.

生成一份教学文档：一个包含「背景」「设计思路」「代码」「测验」模块的长页面HTML文件。它不是PR描述（

make-pr

）也不是即时聊天文本——用户需在浏览器中打开该文件查看。

Flags

参数说明

Flag	Effect
`--target <branch>`	Branch diff: `git diff <branch>...HEAD` . Default: `main` .
`--pr <n\|url>`	PR diff via `gh pr diff` (and PR title/body for context).
`--staged`	`git diff --cached` only.
`--unstaged`	`git diff` only.
`--output <path>`	Write path. Default: `/tmp/YYYY-MM-DD-explain-<slug>.html`

Diff source is mutually exclusive. Use the first detected among

--pr

--staged

--unstaged

; otherwise

--target

--pr

without a number when not on a PR branch: try

gh pr view

to resolve; if it returns no PR, stop and ask.

Slug: short kebab from the change topic (e.g.

rate-limit-api

参数	作用说明
`--target <branch>`	分支对比：执行 `git diff <branch>...HEAD` 。默认值： `main` 。
`--pr <编号\|链接>`	通过 `gh pr diff` 获取PR的diff内容（同时获取PR标题和正文作为上下文）。
`--staged`	仅执行 `git diff --cached` （查看已暂存的变更）。
`--unstaged`	仅执行 `git diff` （查看未暂存的变更）。
`--output <路径>`	指定输出文件路径。默认值： `/tmp/YYYY-MM-DD-explain-<slug>.html`

数据源为互斥模式。优先检测

--pr

、

--staged

、

--unstaged

参数，若均未检测到则使用

--target

。若未处于PR分支且

--pr

未指定编号，则尝试执行

gh pr view

来解析；如果未找到对应的PR，则终止操作并提示用户。

Slug：由变更主题生成的短横线分隔名称（例如

rate-limit-api

）。

Step 1: Gather the change set

步骤1：收集变更集

Collect diff text and identifiers (files, commits, PR number). If the diff is empty, stop: "No changes found to explain."

For

--target

, also run

git log <target>..HEAD --oneline

for narrative context.

收集diff文本及标识信息（文件、提交记录、PR编号）。如果diff为空，则终止操作并提示："未找到可解释的变更内容。"

若使用

--target

参数，还需执行

git log <target>..HEAD --oneline

以获取变更的上下文信息。

Step 2: Legwork

步骤2：前置准备

Read surrounding code beyond the diff hunk lines—callers, types, tests, config—so Background can stand alone for a beginner and still narrow to what this change touches. Done when you can name the system before/after without guessing.

阅读diff代码块之外的相关代码——包括调用方、类型定义、测试用例、配置文件等，确保「背景」模块既能让新手独立理解，又能精准聚焦本次变更涉及的内容。当你能准确描述变更前后的系统状态时，此步骤完成。

Step 3: Draft the four sections

步骤3：撰写四个模块内容

Follow section rubrics, prose tone, diagram families, and quiz rules in

./REFERENCE.md

. Order on the page: Background → Intuition → Code → Quiz.

遵循

./REFERENCE.md

中的模块规范、行文风格、图表样式及测验规则。页面内容顺序为：背景 → 设计思路 → 代码 → 测验。

Step 4: Write HTML

步骤4：生成HTML文件

Emit a single self-contained file: embedded CSS and JavaScript, table of contents, section headers, one scroll (no top-level tabs). Basic responsive layout. Apply the pre-save checklist in

./REFERENCE.md

(especially

pre

white-space

on code blocks).

Write only to

--output

or the default under

/tmp/

(or another path outside the repo). Never commit the HTML file.

生成单个独立文件：内嵌CSS和JavaScript、包含目录、模块标题，采用单滚动页面（无顶层标签页）。基础响应式布局。需遵循

./REFERENCE.md

中的预保存检查清单（尤其是代码块的

pre

标签及

white-space

样式设置）。

仅将文件写入

--output

指定路径或

/tmp

下的默认路径（或仓库外的其他路径）。禁止将HTML文件提交到仓库。

Step 5: Report

步骤5：输出结果

Give the absolute path and a one-line open hint (

open

on macOS,

xdg-open

on Linux,

start

on Windows). Do not paste the full HTML into chat.

输出文件的绝对路径及一行打开提示（macOS使用

open

命令，Linux使用

xdg-open

命令，Windows使用

start

命令）。禁止将完整HTML内容粘贴到聊天中。

Constraints

约束条件

Never use ASCII art diagrams; use simple HTML diagram patterns from
```
./REFERENCE.md
```
.
Never commit, push, or open a PR as part of this skill.
Quiz: five medium-difficulty multiple-choice questions with click feedback in the page—spec in
```
./REFERENCE.md
```
.

禁止使用ASCII艺术图；需采用
```
./REFERENCE.md
```
中的简易HTML图表样式。
禁止在使用该工具过程中提交、推送代码或创建PR。
测验模块：需包含5道中等难度的选择题，且在页面中提供点击反馈——具体规范见
```
./REFERENCE.md
```
。",