用途:针对一次代码改动生成一份丰富的交互式 HTML 讲解文档,面向两类读者——第一次接触该代码库的队友,以及想检验自己理解的改动作者。
定位改动:写文档前先确定要讲什么。给定 PR 编号或 URL 时用 gh pr diff <number> 取差异、gh pr view <number> 取标题描述与讨论;给定分支时用 git diff <base>...<branch> 对比仓库默认分支;给定提交时用 git show <sha>;未指定时看工作区(git diff HEAD),若工作区干净则用当前分支对比默认分支。之后还要超出 diff 本身:完整阅读被改文件、其调用方以及所属子系统,因为背景章节依赖对周边系统的理解。
四个章节按顺序排列:背景(分层讲解改动嵌入的既有系统,初学者深度背景可标注为熟悉者可跳过,再给与改动直接相关的窄背景);直觉(讲清核心思想、原有问题、改动体现的洞察与取舍,聚焦本质,用玩具数据和图表示例);代码(高层次走读,按概念或数据流分组排序,而非按 diff 的文件顺序);测验(五道交互式选择题,中等难度,点击后给出对错与简短解释)。
输出格式:单个自包含 HTML 文件,CSS 与 JavaScript 全部内联,不请求外部资源(CDN、字体、图片),需离线可用;单页长文,带章节标题和目录;基本响应式以适应手机;保存在仓库之外以免进入版本控制,文件名以当天日期开头以便按时间排序,形如 /tmp/YYYY-MM-DD-explanation-<slug>.html。完成后在浏览器打开(macOS 上执行 open <path>)并告知用户路径。
写作风格:清晰流畅、衔接自然,用提示框标注关键概念、定义和重要边界情况。图表:选用少数几类图表族并反复复用(如简化 UI、带示例数据的系统数据流图),用简单 HTML/CSS 构建,列表用 HTML 列表,绝不用 ASCII 艺术;代码块用 <pre> 标签,若改用自定义样式 div,其 CSS 必须包含 white-space: pre 或 pre-wrap,保存前逐块检查空白处理。
限制:资料未提供安装命令、收费方式与具体平台要求等信息,暂未提供。