用途
explain-changes 是一个 AI 工具技能,当用户要求解释改动(代码改动或其他任何改动)时使用。它生成一份统一的审查页面,直接展示具体改了什么,而不是让模型凭记忆复述。页面顶部的一段简短描述和针对文件、改动的注释由使用者提供,页面会标明哪些部分出自使用者。
该技能与 explain-visually 不同:后者用故事形式解释决策或设计,而本技能快速展示改动本身,以 diff 为核心。
主要能力
- 从 git 构建:diff 从与基础分支(默认 origin/HEAD)的合并基点延伸到工作区,同时展示已提交、未提交和未跟踪的改动,并附带提交、推送状态和 GitHub 比较链接。
- 支持多仓库同时审查。
- 支持仓库外的文件:在改动前用
--files开始会话,文本文件最大 1 MB,移动通过内容识别,跳过 .git、node_modules 和构建目录。 - 支持仅能通过命令读取的状态(cron、任务计划程序、服务、API 配置):用
--capture NAME=COMMAND在改动前捕获,之后对输出做 diff;捕获命令应只读且对同一状态输出一致。 - 支持记录有副作用的一次性命令:通过
review.py run记录命令、退出码和输出。 - 支持 MCP 工具调用(Notion、TickTick、邮件等):用
review.py note记录,原始结果经--evidence保存为文件,页面显示为 agent 报告。
使用方式
需要 Python 3.10+ 和 git。<skill> 为该技能文件夹(~/.agents/skills/explain-changes)。
仅仓库,在结束时:
python <skill>/assets/review.py render --git . --out <scratchpad>/review/review.html
python <skill>/assets/review.py render --git C:/git/a --git C:/git/b=origin/develop --description why.md --out review.html
其他情况,在 scratchpad 中开始一个会话,需在第一次改动前启动:
R="python <skill>/assets/review.py"
$R begin <scratchpad>/review --title "Move backups to D:" \
--files "C:/Users/me/scripts" --capture "tasks=schtasks /query /fo csv" --git C:/git/my-app
# ... your work ...
$R run <scratchpad>/review "schtasks /change /tn Backup /st 03:00"
$R note <scratchpad>/review --title "Set Status to Pågår on the task" --evidence <scratchpad>/notion-result.json
$R render --session <scratchpad>/review --description <scratchpad>/review/why.md --out <scratchpad>/review/review.html
--files 接受文件或文件夹(可重复)。--description 为 Markdown,显示在标题下,分三段:为何做此改动;如读者需要可加简短背景(Background: ...);以及修复或改了什么(Fixed: ... 或 Changed: ...),用平实语言写结果而非代码。段落开头的标签会单独占一行。
为每个文件和改动添加注释:在 render 前用相同 --git/--session 选项运行 outline,它会列出每个变更文件和改动并写出 JSON 模板。
$R outline --git . --template <scratchpad>/review/notes.json
# 写入 why.md,并填写 notes.json 中每个文件的 "summary" 和每个改动的 "text",然后:
$R render --git . --description <scratchpad>/review/why.md --annotations <scratchpad>/review/notes.json --out <scratchpad>/review/review.html --artifact
每条注释一句话,说明是什么和为什么。每个改动以第一个变更行(+N 新文件,-N 旧文件)为键;更多编辑后再次运行 outline,已填写的注释会保留,新改动会被加入;不再匹配的注释会在页面上显示为警告。
链接前先检查页面:render 打印的文件和 +/− 应与 git diff --shortstat $(git merge-base <base> HEAD) 一致(加上 git 之外的内容);页面没有关于注释的 "!" 警告;在浏览器中注释位于正确的改动上方。
用 Artifact 工具(私有)发布并链接,渲染时加 --artifact 以省略该工具自行添加的文档骨架。若没有该工具,可用 T3 的 html_render 展示,或给出文件路径。超过 16 MB 的页面无法发布。不要把页面读入上下文(可达数百 kB),按路径发布并在浏览器检查。
页面内容
页面依次包含:描述;包含总计(文件、行数、多个仓库和文件夹、已检查状态、已运行命令、agent 报告的操作)和生成时间的统计框;角落的内容列表列出每个变更文件。
之后每个来源一个部分:仓库(分支 vs 基础、提交、推送状态、GitHub 链接)或文件夹;带状态、+/− 和 agent 文件摘要的文件列表;以及带行号的 diff。大文件、生成文件(锁文件)和删除文件默认折叠。状态差异和记录的操作在后。
提供两种 diff 视图,可在工具栏切换并在浏览器中记忆:Inline(默认)将修改行显示一次,删除的词红色删除线、添加的词绿色,仅一列行号;Old + new 先显示删除行再显示添加行,高亮变更词并显示两列行号。差异过大无法配对的行走显示为普通删除和添加行。自动换行默认开启并记忆。手机宽度下只有一列行号。
适用场景与限制
适用于检查自己所做的改动:仓库、仓库外文件、定时任务、集成;也适用于 GitHub 仓库、本地或未推送工作、仓库外文件、命令可读状态、有副作用命令和 MCP 调用。GitHub 自带 PR 视图和 AI 工具的 diff 视图更适合行内评论;本页面覆盖它们不涉及的部分:仓库外改动、多仓库、状态与操作、跨工具一览。
限制:需要 Python 3.10+ 和 git;不要在被监视文件或捕获输出中放入密钥,页面会展示它们,避开 .env* 文件;捕获命令应只读且输出对同一状态一致;超过 16 MB 的页面无法发布;修改 review.py 时需在同一提交中更新其描述,并运行 python examples/build_examples.py <scratchpad>/examples --check,三个示例页面均须显示 ok。