visual-explainer 怎么安装？Claude Code/Codex 可视化教程

想装 visual-explainer？先搞清楚你用的是 Claude Code 还是 Codex——Claude Code 走官方插件市场安装，Codex 得把仓库里的标准 Skill 目录复制到 ~/.codex/skills/visual-explainer 路径下。这俩的安装命令千万别混着用哈。

Claude Code 怎么从插件市场安装？

我一般会先确认仓库地址就是 nicobailon/visual-explainer，再在 Claude Code 里依次输入这两条命令：

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

插件命令是带命名空间的，装完之后可以用 /visual-explainer:diff-review、/visual-explainer:generate-slides 这种格式调用。要是你还照着旧版“直接用仓库 URL 安装插件”的教程来，很容易碰到加载失败——现在这个仓库已经按 marketplace 结构发布了。

Codex 怎么放到正确目录？

Codex 官方仓库的说明是用 HTTPS 克隆仓库，再复制标准目录。我建议你完整跑下面这组命令，别只复制个 SKILL.md 就完事，不然容易漏了模板和参考文件：

git clone --depth 1 https://github.com/nicobailon/visual-explainer.git /tmp/visual-explainer
mkdir -p ~/.codex/skills ~/.codex/prompts
cp -R /tmp/visual-explainer/plugins/visual-explainer ~/.codex/skills/visual-explainer
cp /tmp/visual-explainer/plugins/visual-explainer/commands/*.md ~/.codex/prompts/

复制到 ~/.codex/prompts/ 这一步是可选的，只适用于支持提示词模板的 Codex 版本，Skill 本身不依赖它。装完之后你直接说“使用 visual-explainer Skill 画出认证架构”，或者显式调用 $visual-explainer 就行。如果提示词被识别到了，命令形式通常是 /prompts:diff-review。

第一次怎么试跑？

我一般会选个很小但确实需要梳理关系的需求来测，比如“用 visual-explainer 生成当前项目认证流程的 HTML 图解”。成功的标志不是终端里蹦出一段 Mermaid 文本，而是 ~/.agent/diagrams/ 路径下多出能打开的 HTML 文件，用浏览器打开能正常显示。

需要额外配 API Key 或者装别的依赖吗？

• 核心的 HTML、CSS、Mermaid 图和表格输出功能，不用单独配置 API Key。
• 查看生成结果得有浏览器；能不能自动打开，还会受 Agent 环境和沙箱权限影响。
• surf-cli 只用于可选的图片生成能力，需不需要密钥得按该工具自己的官方配置来处理。

装失败了先查什么？

• Codex 的路径对不对：得正好是 ~/.codex/skills/visual-explainer/SKILL.md，别多套了一层仓库目录。
• Claude Code 是不是先完成了 marketplace add，再执行的 plugin install。
• 有没有把 Claude Code 的命名空间命令，误写成 Codex 的 prompts 命令。
• 浏览器没自动打开的话，先手动打开生成的 HTML 看看，别把显示权限问题误判成生成失败。

安装成功自查清单

1. Agent 能识别出 visual-explainer 这个名称。
2. 小测试生成了完整的 HTML，不是纯 ASCII 图。
3. 文件在 ~/.agent/diagrams/ 或者你指定的路径下。
4. Mermaid 图具备缩放、拖动和展开的控件。