Codex 如何可视化代码审查？visual-explainer 工作流教程

想知道 Codex 怎么做可视化代码审查？装完 visual-explainer 可别只拿它来「美化 git diff」哦。正确的打开方式是先核对清楚变更事实，再把涉及的文件范围、架构影响、前后行为和风险结论，都整理进可追溯的 HTML 里。官方的 diff-review 命令支持传入分支、提交、范围、PR 或者 HEAD；要是不传参数，就会把工作区和 main 或 master 做对比。

运行前要准备什么？

首先得确认 Skill 放在 ~/.codex/skills/visual-explainer 路径下，核心功能不需要额外的 API Key。如果你的 Codex 支持提示词模板，可以安装 commands 文件，直接调用 /prompts:diff-review 就行；要是不支持，直接让 $visual-explainer 执行 diff review 也可以。输出文件默认存放在 ~/.agent/diagrams/ 目录里。

它先收集哪些证据？

• diff 统计、文件状态、增删行数，还有完整的变更文件。
• 公开 API、类型、函数、依赖、配置以及文档的变化。
• 提交信息、相关调用路径，还有测试覆盖情况。
• 每个结论对应的文件路径、命令输出或行号证据。

HTML 审查页应该出现哪些部分？

1. 执行摘要和完整文件地图。
2. 架构影响，以及关键行为的前后对比。
3. 正确性、测试、兼容性、安全、性能与维护方面的风险。
4. 依赖耦合、迁移发布事项，还有明确的合并建议。

页面里的颜色也有固定含义：红色表示删除内容或旧行为，绿色表示新增内容或新行为，琥珀色提示修改和风险，蓝色用来放中性上下文。如果主要章节超过四个，还会有响应式的章节导航。

怎样判断第一次试跑成功？

我一般会挑一个小提交跑一遍审查，然后确认三件事：HTML 文件真的存在；页面里的函数名和文件名都能在仓库里找到；风险结论都带着证据，不是瞎猜动机。要是浏览器没自动打开，手动打开输出文件就行。

常见问题

• 页面只有 diff 摘要：说明 Codex 没读取关联文件和调用路径，得补充审查范围。
• 架构图过密：把大图改成小型概览加模块卡片就行。
• 结论没有行号：让它重新绑定文件、命令输出或代码位置。
• 准备合并却没看到测试影响：说明审查还没达到官方命令的要求。

完成检查清单

1. 变更范围、行为差异和风险都有来源。
2. 审查页能独立打开，没有横向溢出。
3. Mermaid 关系可以缩放、拖动和展开。
4. 合并建议区分阻断项和后续事项。