【免费下载链接】visual-explainerAgent skill that generates rich HTML pages or slide decks for diagrams, diff reviews, plan audits, data tables, and project recaps项目地址https://gitcode.com/gh_mirrors/vi/visual-explainer点击查看免费下载/diff-review是 visual-explainer 技能中专门负责代码变更可视化审查的命令模板它把一次 diff、一次 PR 或某个提交范围转换为一份自带样式、可离线打开、适合浏览器阅读的自包含 HTML 审查报告。本文完整讲解该命令的输入范围判定、数据收集与源码验证流程、七段式页面结构、diff 配色语言与 Quick 快速模式并结合 diff-review.md、schema.json、render.mjs、extension.ts 等源码佐证底层实现读完即可在自己所在的 Agent 环境中跑出规范、可复用的视觉化代码审查。命令定位什么时候该用 /diff-review在 visual-explainer 的命令体系中/diff-review与/generate-web-diagram、/generate-visual-plan、/plan-review、/project-recap、/fact-check并列是面向变更审查场景的专用命令commands 目录。它处理的是终端里最难以阅读的两类输出diff 文本git diff的/-行堆叠难以建立改了什么、为什么改、影响多大的整体认知代码审查结论一串文件路径和行号缺少架构级、风险级的组织。命令模板本身只有两句话的指令——加载 visual-explainer 技能生成一份自包含的 HTML diff 审查报告见 diff-review.md 头部但紧接着就规定了完整的工作流程范围检测 → 数据收集 → 源码验证 → 七段式页面 → 配色与交互约束 → 交付到~/.agent/diagrams/并在浏览器打开。这也是它在 MCP server 中被暴露为 prompt 模板visual-explainer://commands/*.md的原因——同一份指令既可以在交互式 Agent 中执行也可以通过 MCP 宿主以request参数填充$触发。输入范围检测Scope detection命令模板要求对$参数做一次宽输入解释而不是只认某一种 git 对象Scope detection 一节可以是分支如main..HEAD可以是单个提交可以是提交区间range可以是PR可以是HEAD如果不给任何参数则默认把工作区working tree与main/master对比。这个设计意味着同一个命令入口可以覆盖我还没提交和我想审一下合并请求两类典型诉求。从仓库 README 的示例也能看到它的惯用法/diff-review直接比较工作区与主干/diff-review main..HEAD显式指定区间README 的 Quick Mode 一节。另外README 还提到/diff-review --slides可以把审查页面渲染成幻灯片形式——任何生成可滚动页面的命令都支持--slides。写 HTML 之前的数据收集命令模板明确规定动手写 HTML 之前必须先完成 git 层面的数据收集Data gathering 一节。需要运行的 git 命令覆盖以下维度数据维度内容diff 统计diff stats、name-status重命名/复制/状态文件层面变更文件清单、行数变化增删行、新增/删除的文件接口层面公共 API / 类型 / 函数签名变化文档层面文档docs与 CHANGELOG 的变更测试层面被触碰的测试文件依赖层面依赖与配置文件变更除此之外还有两条阅读要求完整阅读变更文件并连带阅读理解其行为所需的周边代码路径surrounding code paths而不是只看 diff 片段如果审查的是已提交的工作读取 commit message 作为变更理由如果是本次会话自己产生的改动使用可用的进度/计划笔记progress/plan notes作为设计意图来源。源码验证禁止编造依据这是命令模板中最强调事实纪律的一节Source verification 一节。在生成报告之前Agent 必须做到知道并引用以下四件事精确的变更文件清单与行数范围exact changed files and line-count scope被引用的每个函数 / 类型 / 模块的名字重要变更的before/after 行为可能的耦合与测试影响likely coupling and test impact。并且明确要求使用文件路径、命令输出或file:line证据。不要发明理由或代码路径。Use file paths, command outputs, or file:line evidence. Do not invent rationale or code paths.这为整份报告设定了可验证性底线——页面里的每个结论都能回溯到仓库中的具体位置。这一纪律与项目的fact-check命令commands/fact-check.md一脉相承visual-explainer 的定位始终是以事实为基础的视觉呈现审查页面的说服力来自证据链而不是排版。七段式页面结构Required page sections命令模板把审查报告固定为七个必备段落Required page sections 一节执行摘要Executive summary给出直觉判断intuition、解决的问题problem solved、事实范围factual scope文件地图File map完整的文件树按 新增/修改/删除 三态配色长列表要紧凑并用details折叠架构影响Architecture impact当模块间关系有意义时使用 Mermaid 或混合hybrid图前后行为对比Before/after behavior并排side-by-side的可视化对比风险审查Risk review正确性、测试、API 兼容性、安全/隐私、性能、可维护性六个维度耦合地图Coupling map依赖关系、隐藏耦合、迁移/发布顾虑审查结论Review recommendation是否可以合并merge/readiness、阻塞项blockers、后续跟进follow-ups。这七段正好对应 diff 审查的完整认知链条结论先行 → 改动全景 → 架构视角 → 行为视角 → 风险视角 → 耦合视角 → 决策。文件地图使用details折叠长列表与 SKILL.md 的布局规范语义化 HTML、details折叠、可访问性保持一致。一致的 diff 配色语言与交互规范命令模板对颜色给出了明确、可复用的语义diff-review.md 配色要求红色 删除 / before绿色 新增 / after琥珀色 修改 / 风险蓝色 中性上下文。并且规定4 个以上章节必须使用响应式章节导航responsive section navigation同时遵守 SKILL.md 的 Mermaid 与溢出overflow规则。响应式导航的实现依据在 references/responsive-nav.md4 章节 → responsive-nav这一路由规则见 SKILL.md 的 Reference routing 表。值得注意Quick 快速模式把同一套语义落地到了 CSS 变量层。查看 quick/base.css 可以看到 light/dark 两套色板light 下--positive: #35745c、--warning: #a36d14、--danger: #a33c3c、--info: #356c8cdark 下对应#76b99a、#e3ad55、#e37a75、#72acd0并通过prefers-color-scheme媒体查询整体切换。这与 SKILL.md 的双配色方案约束token 定义在:root媒体查询只重定义 token组件全部经由 token 取色完全一致。Mermaid 的使用还需遵循 SKILL.md 的 Mermaid 不变量使用theme: base配合自定义themeVariables匹配页面配色、复杂图用 ELK 布局、采用templates/mermaid-flowchart.html中的diagram-shell结构.diagram-shell.mermaid-wrap.zoom-controls.mermaid-viewport.mermaid-canvas每个图都要带缩放/重置/展开控件、Ctrl/Cmd滚轮缩放、拖拽平移与点击展开。对于架构影响这类关系型段落15 个以上元素时不要塞进一张 Mermaid 图改用小 Mermaid 总览 CSS 详情卡片的混合模式。审查报告的排版基调要求diff review 属于 SKILL.md 明确定义的功能性内容类型polished-utilitarian真实的信息层级、克制的间距、不搞花哨的 hero 区SKILL.md 设计判断一节。同时配色选择遵循优先级用户原话 项目既有设计系统主题/token 文件 技能自身默认做 diff/plan 审查前应先检查仓库 token 再定调色板。在可访问性与排版层面SKILL.md 的布局不变量同样约束审查页面正文近 65ch、标题text-wrap: balance、普通文本 ≥14px、标签 ≥11px、代码 ≥12px、用 flex/gridgap分隔而非 collapse margin、防止溢出用min-width: 0与overflow-wrap: break-word。这些看似细节的要求直接决定了审查报告读得下去的程度。Quick 快速模式把审查浓缩成 JSON spec当$中包含字面量--quick时命令进入快速模式diff-review.md 的 Quick mode 一节。流程要点先移除--quick标志再做范围检测证据收集与验证流程与完整模式完全相同——快速模式不豁免事实收集读取./quick/README.md和./quick/schema.json把审查结果表达为紧凑的 JSON spec在 Pi 中调用visual_explainer工具的action: render_quick在其他 harness 中保存 JSON 后运行本地./quick/render.mjs如果内容不适合 schema、校验失败或渲染出错回退到完整 HTML 流程不带--quick则始终保持完整 HTML 行为。也就是说--quick不是偷懒模式而是换一种输出形态——Agent 不再手写 HTML/CSS而是输出结构化数据由确定性的渲染器生成页面。快速模式的 JSON Schema 契约quick/schema.json 是权威的 JSON Schemadraft 2020-12。顶层 spec 需要title必填非空与sections必填至少 1 项可选subtitle、summaryadditionalProperties: false意味着未知属性直接校验失败。每个 section 至少要有title可组合以下内容块可同时出现多个但同一类型块内至少 1 项块类型字段说明cardstitle(必填)、body、meta[]、tone紧凑的发现或概念卡片tablecolumns[](≥1)、rows[][]、caption列数与每行 cell 数必须一致riskstitle、body、severity(均必填)严重度枚举low/medium/high/criticalfilespath(必填)、detail、status状态枚举added/modified/deleted/reviewed/plannedstepstitle(必填)、body、status状态枚举done/current/next/blockedflownodes[](≥1)、edges[]edge 的from/to必须引用已声明节点calloutsbody(必填)、title、tone注意事项、决策或警告evidencelabel、value(均必填)、source审查证据条目所有tone字段共享枚举neutral/accent/positive/warning/danger/info。所有 Agent 文本都会被 HTML 转义未知属性、非法枚举值、坏的 flow 引用、列数不匹配的表格行都会导致校验失败——这是 quick/README.md 与 render.mjs 双重确认的行为。render.mjs确定性渲染器quick/render.mjs 是快速模式的本地渲染实现核心函数validateQuickSpecL55-L148逐字段执行上面的校验随后renderQuickSpecL186-L192把 spec 渲染成完整 HTML读取同目录 base.css 内联进style所有文本经escapeHtmlL150-L152转义 注入内置 SVG faviconstandardFavicon输出!doctype htmlhtml langen viewport meta 的完整文档章节按01/02/03kicker 编号section 级tone映射到data-tone的 CSS 变量渲染函数族覆盖renderCards、renderTable、renderListsrisks/files/steps、renderFlow、renderCalloutsAndEvidenceL158-L184与 schema 的 8 种内容块一一对应。CLI 用法Usage: node render.mjs spec.json output.htmlL194-L202node plugins/visual-explainer/quick/render.mjs spec.json ~/.agent/diagrams/diff-review-quick.html校验失败或渲染出错时进程以非零码退出并输出错误到 stderrAgent 据此回退到完整 HTML 流程。渲染交付输出路径、打开行为与多 harness 支持命令模板的收尾动作是固定的写入~/.agent/diagrams/并在浏览器打开diff-review.md 末行。不同宿主环境的落点由 extension.ts 与 mcp/README.md 分别承载Pi原生工具visual_explainer工具支持prepare/render/render_quick三种 actionextension.ts L8-L20。render_quick接收filename与spec输出目录固定为~/.agent/diagrams/filename必须是 basename拒绝/、\、..、控制字符自动补.html见 outputFilename L139-L148并对输出目录与目标文件做symlink 防护拒绝 symlink 目标L331-L337viewer支持browser默认/glimpse/auto先试 glimpseui 再回退浏览器。MCP 宿主本地 stdio server 暴露visual_explainer_render_quick工具校验 spec 并写入输出目录默认~/.agent/diagrams/可用VISUAL_EXPLAINER_OUTPUT_DIR迁移render 工具默认open: false只有显式open: true才请求浏览器/Glimpse 窗口diff-review同时作为 prompt 模板暴露用request填充$mcp/README.md。其他 harness保存 spec 后运行本地node ./quick/render.mjs spec.json output.html再用宿主自带的浏览器命令打开quick/README.md 的 Other harnesses 一节。从 extension.ts 的 render 流程可以看到完整交付链校验完整 HTML 文档必须!doctype html/html开头、/html结尾→ 补lang、viewport、favicon 与 display-math 转义 → 写入~/.agent/diagrams/→ 按 viewer 发起打开请求并报告 dispatched/failed/unsupported 状态。SKILL.md 的 Final checklistL128-L148进一步要求在交付前核对无控制台错误、桌面宽度无水平溢出、字体带 fallback、表格不丢行列、Mermaid 图带 zoom/pan/expand 等。与相邻命令的分工/diff-review只做变更的视觉化与其余命令形成互补/plan-review把一份计划文档与真实代码库对比输出风险与差距评估commands/plan-review.md/fact-check验证文档内容与真实代码是否一致commands/fact-check.md/project-recap为切换上下文的人生成项目心智模型快照/generate-web-diagram任意主题的 HTML 图解/generate-slides把内容组织成幻灯片配合--slides。四者的共同前提是同一个证据先行、视觉后置。/diff-review的独特价值在于它把 git 语义diff/commit/range/PR直接翻译成七段式审查报告而配色、折叠、导航与 Mermaid 交互等全部复用 visual-explainer 的既有设计系统最终交付物是零依赖、可归档、可分享的单个 HTML 文件。赞分享【免费下载链接】visual-explainerAgent skill that generates rich HTML pages or slide decks for diagrams, diff reviews, plan audits, data tables, and project recaps项目地址https://gitcode.com/gh_mirrors/vi/visual-explainer点击查看免费下载相关推荐CANN Runtime 本地代码审查指南基于 runtime-code-review skill 的 Diff 审查工作流CANN Runtime 本地代码审查指南基于 runtime code review skill 的 Diff 审查工作流 导读 本指南以 CANN RunCANNAscend人工智能性能剖析系统编程visual-explainer 的 plan-review 命令基于源码证据的 HTML 实施计划审查指南visual explainer 的 plan review 命令基于源码证据的 HTML 实施计划审查指南 导读 plan review 是 visualTig diff视图深度解析如何像IDE一样逐行审查Git代码变更Tig diff视图深度解析如何像IDE一样逐行审查Git代码变更 Tig src/main.c https://link.gitcode.com/i/e上一篇构建游戏智能体的技术革命Behaviac多范式AI框架全解析下一篇如何让黑苹果配置不再难OpCore Simplify带来的自动化革命创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考