visual-explainer - 将复杂输出转化为精美HTML可视化

这是什么

visual-explainer 是一个面向 AI 编程 Agent 的技能包，由 nicobailon 开发，采用 MIT 许可证开源。它的核心价值在于：当你让 Agent 解释系统架构、审查代码差异、比对计划或总结项目时，它不再输出难看的 ASCII 艺术图和符号表格，而是生成一个自包含的 HTML 页面，用真正的排版、深色/浅色主题、手绘风格的动画图表呈现信息，并自动在浏览器中打开供阅读。

这个仓库自发布以来已获得 10387 个 Star、674 个 Fork，仅有 1 个开放 Issue，最新版本为 v0.12.0。它被设计为无构建步骤，普通使用只需一个浏览器，符合“零依赖”的轻量理念。

适合谁

开发者与技术团队：需要快速把复杂的 diff、架构图、计划审查结果变成直观网页，方便阅读和分享。
项目经理 / 技术文档作者：需要把计划对比、需求审计、项目总结转化为美观的幻灯片或数据表格页面。
自媒体创作者 / 内容运营：可借助 Agent 将技术内容转化为富有视觉表现的 HTML 页面，用于博客、教程或演示。
使用 AI 编程助手的效率爱好者：希望让 Agent 的输出不再局限于终端，而是更加人性化、可读。

能做什么

绘制图表：支持手绘风格、可交互的系统架构图、流程图，取代 ASCII 示意图。
Diff 审查：通过 /diff-review 命令，将代码差异渲染为清晰的对比页面。
计划审查：通过 /plan-review 检查文档中的计划，以可视化的方式标出问题或不一致。
数据表格展示：将复杂的数据对比（如 15 条需求与计划的匹配）转换为排版优秀的 HTML 表格。
幻灯片生成：生成 HTML 幻灯片，并可通过附带工具导出为 PPTX 或 MP4 视频（视频导出需额外配置）。
项目总结：自动生成项目回顾页面，便于归档或向团队展示。

使用前准备

基本使用只需一个支持 Agent Skills 的编程环境（如 Claude Code、Codex、Cursor、Antigravity CLI 等）以及一个现代浏览器。无需 API 密钥，也无需额外搭建本地服务。

若需要使用视频导出功能，需自行安装 ffmpeg、Chrome 和 playwright-core；若需 PPTX 导出，则依赖少量 Node 包（pptxgenjs 等）。这些都属于可选功能，不影响核心的 HTML 生成。

安装方法

支持多种安装路径，以下列出常见方式。以 Pi（一个 AI 编程 Agent）为例，可直接运行：

pi install git:github.com/nicobailon/visual-explainer

对于 Claude Code（Marketplace 插件），在对话中执行：

/plugin marketplace add nicobailon/visual-explainer
/plugin install visual-explainer@visual-explainer-marketplace

对于 Antigravity CLI（全局安装）：

git clone --depth 1 https://github.com/nicobailon/visual-explainer.git /tmp/visual-explainer
mkdir -p ~/.gemini/antigravity-cli/skills
cp -R /tmp/visual-explainer/plugins/visual-explainer ~/.gemini/antigravity-cli/skills/visual-explainer
rm -rf /tmp/visual-explainer

对于 Codex CLI，复制到 ~/.codex/skills/visual-explainer；对于 Cursor，复制到 ~/.cursor/skills/visual-explainer 或项目目录 .cursor/skills/；对于通用 MCP 主机，可使用 visual-explainer-mcp 命令，或从源码运行 plugins/visual-explainer/mcp/server.mjs。

完整安装矩阵请参考项目 README，其中包含 Windows PowerShell 脚本和每种环境的详细说明。

使用示例

安装后，你可以向你的 Agent 发出如下指令：

draw a diagram of our authentication flow
/diff-review
/plan-review ~/docs/refactor-plan.md

Agent 会生成一个自包含的 HTML 文件，并自动在浏览器中打开（或根据配置使用 Glimpse 预览）。渲染结果采用响应式设计，支持深色/浅色主题，图表带有动画效果，阅读体验远超终端文本。

风险与注意事项

项目采用 MIT 许可证，来源公开，风险极低。但仍建议在使用 MCP 服务器时，将输出目录（~/.agent/diagrams/）设置为仅当前用户可写，避免其他本地用户恶意替换渲染结果。
部分功能（视频导出）依赖外部组件（ffmpeg、Chrome、playwright-core），需额外安装并注意版本兼容性。
如果使用旧版 curl/manual 安装方式，升级到 Pi 包管理前需清理旧文件，否则可能产生技能和提示冲突。
MCP 服务器是本地 stdio 模式，不监听 HTTP、不调用 LLM、不处理凭据，安全性较高，但请勿将输出目录指向公共可写目录。