visual-explainer

在 AI 辅助编程的日常中，你是否经历过这样的绝望时刻：

让 AI 画一个系统架构图，它吐出一堆由 +, -, | 组成的 ASCII 艺术图，稍微复杂一点就错位乱码；

让 AI 对比 15 条需求与代码实现，它生成了一堵由竖线构成的“表格墙”，在终端里自动换行后支离破碎，根本没法读。

visual-explainer 是一个专为 AI 代理（如 Pi, Claude Code 等）设计的技能包。它能智能识别你的可视化需求，不再生成枯燥的文本图形，而是直接创建一个自包含的、交互式的 HTML 页面，并在浏览器中打开。无论是复杂的系统架构、代码差异审查，还是项目计划核对，现在都能以杂志级的排版和可缩放平移的图表呈现。

为什么你需要 visual-explainer？

1. 拒绝“瞎眼”的 ASCII 图

传统的终端图表在超过 3 个节点后就会变得难以辨认。visual-explainer 强制 AI 使用 Mermaid.js 渲染真正的流程图、时序图和状态机。

• 交互性：支持缩放、平移，清晰展示每一个连接关系。
• 美观度：自动应用精心设计的配色方案，告别黑白文本。

2. 拯救破碎的数据表格

当数据量较大时，终端表格简直是灾难。visual-explainer 会自动将宽表转换为 HTML 数据表格。

• 响应式布局：自动适应屏幕宽度，不再乱换行。
• 视觉增强：内置 KPI 仪表盘、状态徽章和条件格式，让数据一目了然。

3. 零依赖，开箱即用

生成的每个文件都是单一的 .html，内联了所有 CSS 和 JS。

• 无需构建：不需要 npm install，不需要 Webpack。
• 跨平台：只要有浏览器就能看，完美支持明暗主题切换。

安装指南

该技能支持 Pi 和 Claude Code 等主流代理框架。

方式一：一键安装 (Pi 用户)

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

方式二：手动安装 (通用)

克隆仓库并将提示模板复制到对应目录，以注册斜杠命令。

对于 Claude Code:

# 克隆技能
git clone https://github.com/nicobailon/visual-explainer.git ~/.claude/skills/visual-explainer

# 注册斜杠命令
mkdir -p ~/.claude/commands
cp ~/.claude/skills/visual-explainer/prompts/*.md ~/.claude/commands/

💡 彩蛋：如果你安装了 surf-cli，该技能还能自动调用 Gemini 生成插图并嵌入页面，让文档图文并茂。

六大核心命令与工作流

visual-explainer 包含六个精心设计的提示模板，覆盖开发全生命周期：

实战示例

1. 智能差异审查 (/diff-review)

不再需要肉眼比对 Git Diff。运行以下命令：

/diff-review          # 默认对比当前分支与 main
/diff-review abc123   # 对比特定提交
/diff-review #42      # 对比第 42 号 PR

输出结果：一个完整的 HTML 报告，包含：

• 架构演变图：Before vs After 的系统架构对比。
• KPI 仪表盘：代码行数、复杂度、测试覆盖率的变化趋势。
• 结构化审查：分门别类的代码优缺点分析。
• 决策日志：记录本次变更背后的思考与权衡。

2. 计划与现实核对 (/plan-review)

确保代码没有偏离设计初衷：

/plan-review ~/docs/refactor-plan.md

AI 会逐条核实计划中的声明，生成一份“计划 vs 现实”的差异报告，并高亮潜在的风险区域。

3. 幻灯片模式 (--slides)

任何生成长页面的命令都支持 --slides 参数，瞬间变身演示文稿：

/diff-review --slides         # 用于站会汇报的差异审查幻灯片
/project-recap --slides 2w    # 过去两周的项目回顾演示

工作原理：美学与逻辑的结合

visual-explainer 不仅仅是一个转换器，它是一套设计系统。

1. 智能路由：代理会根据内容类型自动选择最佳渲染方案（Mermaid 用于关系图，CSS Grid 用于架构概览，Chart.js 用于数据可视化）。
2. 参考库驱动：技能内置了 css-patterns.md, libraries.md, slide-patterns.md 等参考文件。每次生成前，AI 都会阅读这些设计原则，确保输出符合现代审美。
3. 多样化模板：提供四种截然不同的调色板模板（如陶土色架构卡、鸭青色流程图、玫瑰红数据表、午夜风幻灯片），避免千篇一律。
4. 自动触发：当你要求画图，或 AI 准备输出超过 4 行 3 列的表格时，技能会自动拦截并转为 HTML 生成流程。

输出文件默认保存至 ~/.agent/diagrams/，并自动调用默认浏览器打开。

⚠️ 局限性说明

• 依赖浏览器：无法在终端内联预览，必须跳转浏览器查看。
• 主题同步：切换系统明暗模式时，Mermaid SVG 部分可能需要刷新页面才能生效（原生 CSS 元素可即时响应）。
• 模型依赖：最终效果取决于底层 AI 模型的理解能力。本技能提供设计指导和模板，但无法保证像素级的完美控制。