explain-diff

解释差异

标志

标志	默认值	作用
--target <branch>	main	解释 <branch>...HEAD
--pr <n|url>	关闭	解释一个 PR 差异及其元数据
--staged	关闭	解释暂存区
--unstaged	关闭	解释工作区变更
--output <path>	/tmp/YYYY-MM-DD-explain-<slug>.html	设置 HTML 路径

四种来源选项互斥；冲突或未提供值的标志均为 BLOCKED；裸 --pr 是唯一无值例外，并可解析当前分支对应的 PR。未指定来源标志时，使用等效于 --target main 的选项。若无法获取 PR 差异，则阻止操作。缺少可选 PR 元数据时，仍可生成仅包含差异的页面，但不得声称变更动机。

1. 锁定来源和输出

记录来源标识、head SHA、精确差异、已排序路径和差异的 SHA-256 哈希。差异为空时为 NO_CHANGES。根据经过清理的分支名称、PR 编号或 change-<head8> 生成 slug，长度上限为 40 个字符。

将输出解析为仓库外的绝对路径；明确指定的仓库内路径为 BLOCKED，不得重新定位。创建不存在的父目录。覆盖用户指定的现有文件前先阻止操作。默认输出只能替换包含本技能生成器标记的先前产物。

记录： source/hash | theme(name/paths/path-hash/gate) | evidence | output | gate | verification | terminal。 Gate 为 lock、research、build 或 verify。每次完成一个 gate 和主题后，将记录保存到输出旁的 <output>.ledger。仅当输出和来源哈希匹配时，才可恢复活动记录；否则为 BLOCKED。成功后删除记录。

完成条件：来源和安全输出均不可变。

2. 分组和调研

阅读周边代码前，先将每个变更路径分配到一个功能主题。路径超过 50 个时，通过代表性代码块解释主题，并完整列出所有已排序路径，不得截断。重命名表示为 old → new；将生成文件或二进制文件列在对应主题下，且不得在没有文本代码块的情况下声称其行为变化。仅含路径的清单行使用 data-hunk="<path>:inventory"。最多使用 12 个主题、每个主题查看 3 个周边文件，总计最多查看 30 个周边文件。仅当计划中的论断需要时，才阅读直接定义、调用方、契约、测试和配置。

完成条件：每个路径都有对应主题，且每项计划中的论断都有代码块或已读文件指针。

3. 构建教学页面

加载 ./REFERENCE.md。按以下顺序编写一个 HTML 文件：背景、直觉、代码、测验。包含目录、内联 CSS 和 JavaScript、响应式布局，且图示仅使用 HTML 或内联 SVG。代码部分按主题分组；对于大型差异，须包含完整清单。

关于变更的每个事实性句子都必须能追溯到代码块。每项系统相关论断都必须能追溯到周边文件。删除缺乏依据的意图、动机或 PR 论断。

完成条件：文件已存在，且包含全部四个非空章节和五道有依据的测验题。

4. 验证并报告

应用参考检查清单。验证不存在外部资源 URL，并检查所有锚点、生成器标记、代码空白、证据指针和测验答案反馈。 如果存在浏览器工具，则加载文件，并为每个问题测试一个正确答案和一个错误答案；否则解析 JavaScript 和 HTML，并注明 verification: static-only。浏览器运行应报告 verification: browser。 在 SUCCESS 之前重新计算实时源指纹；如果发生偏移，则状态为 BLOCKED，确保页面不会混用不同快照。

中断后，对比源哈希和台账。如果主题已变更，则重新开始；否则从第一个未完成的关卡继续。

报告绝对路径、源、主题和文件数量、测验数量以及验证级别。不要粘贴 HTML。终态值为 SUCCESS、NO_CHANGES 和 BLOCKED。绝不提交、推送或修改 PR。