visual-explainer

1. 基本信息

项目	内容
名称	visual-explainer
作者/维护者	nicobailon（GitHub）
来源链接	https://github.com/nicobailon/visual-explainer
许可证	MIT
GitHub Stars	9,293（GitHub API 实测，2026-07-21）
Forks	629（同上）
最新版本	v0.8.1（GitHub Release，发布于 2026-06-25）
安装方式	Claude Code 插件市场一键安装 / Codex CLI 手动复制 / Pi 包管理器 / OpenClaw AGENTS 指引

2. 功能介绍与亮点

visual-explainer 把原本要用终端 ASCII 框线图、错位表格呈现的内容——架构讲解、代码 diff 审查、实施计划审计——自动生成为自包含的静态 HTML 页面并在浏览器中打开。

场景化命令集：内置 /diff-review（可视化 diff 审查与代码评审）、/plan-review（计划与现有代码库的一致性审计）、/project-recap（项目复盘快照）、/fact-check（文档与代码的准确性核对）、/generate-web-diagram、/generate-visual-plan、/generate-slides 等 7 个命令
自动路由到合适的表现形式：流程图/时序图/ER图/C4架构图用可缩放拖拽的交互式 Mermaid 图，数据对比用响应式 HTML 表格，仪表盘类内容用 Chart.js，纯文字架构用 CSS 网格卡片
幻灯片模式：任意命令加 --slides 参数即可生成单屏切换的演示文稿，而非可滚动长页
自动触发机制：当终端即将输出 4 行以上或 3 列以上的复杂表格时，会自动改为生成 HTML 页面而非硬塞进终端
生成产物是无构建步骤的单文件 HTML（内嵌 CSS/JS），不依赖 Node/npm 运行时即可查看

3. 适用场景

所属分类：工程效率与代码质量。适合日常做代码 review 时希望可视化 diff 差异与风险点、启动一个较大改动前先审计实施计划与代码库的一致性、把架构或技术方案讲解/交接给团队成员及非工程背景相关方、把零散的项目状态整理成可分享的复盘页面。核心受益人群是使用 Claude Code / Codex 做日常开发、且经常需要向他人解释代码变更或技术方案的开发者与技术负责人。

4. 跨 Agent 兼容性

Claude Code：✅ 原生支持——README 给出插件市场安装命令，命令自动挂载为 /visual-explainer:command-name
Codex：✅ 支持（需手动安装）——README 给出 git clone 后复制到 ~/.codex/skills/ 的具体步骤，安装后作为原生 skill 路径调用
OpenClaw：⚠️ 需适配——README 明确说明仅提供轻量的 AGENTS.md 指引与技能目录引用，未包含原生 OpenClaw 插件适配器
Hermes Agent：❓ 未验证——README 与 SKILL.md 均未提及该生态

判断依据：均来自仓库 README 中逐一列出的安装矩阵（Harness / Support / Install path 三栏对照表）。

5. 推荐理由

把 diff、架构、实施计划一股脑塞进终端时，可读性会迅速崩溃——这正是这个技能要解决的问题。它把这几类最容易变得难读的输出，转成有排版、可缩放 Mermaid 图、深浅色主题的独立 HTML 页面，装一次之后 agent 会在合适场景自动触发，不需要每次手动喊。对经常要跟同事或非工程背景的人解释技术方案的开发者来说，这比截图终端或手写 wiki 页面省事。

6. 评分

维度	分数	说明
受欢迎程度	9	GitHub 9,293 stars、629 forks（GitHub API 实测，2026-07-21），由持续活跃的独立开发者维护，同类技能中排名靠前
可用性	9	提供 Claude Code 插件市场一键安装，另有 Codex、Pi、OpenClaw 的具体安装步骤；README 与 SKILL.md 文档详尽（含命令示例、目录结构、限制说明），最新版本发布于近一个月内
安全性	8	见下方安全检查清单

安全检查清单：

检查项	结果
① Shell 命令及权限范围	仅涉及本地文件复制，以及调用系统原生“用浏览器打开文件”命令（macOS `open` / Linux `xdg-open` / Windows `start`）；已读取扩展源码，输出文件名经过路径穿越与非法字符校验，无 sudo/root 操作
② 运行时是否联网外发数据	核心功能不发起任何网络请求；可选的第三方浏览器控制组件为独立可选依赖，非必需
③ API key/凭据存储方式	不需要任何密钥或凭据
④ 可疑指令/Prompt Injection 迹象	已通读 SKILL.md 全文、安装脚本与 Pi 扩展源码，未发现越权指令或隐藏的可疑内容
⑤ 作者/组织信誉	作者在 GitHub 上维护约 20 个相关工具仓库，仓库有 3 位贡献者；对用户在 Issue 中提出的诉求（如“缺少正式插件”）有后续版本响应
⑥ License	MIT，权责清晰
⑦ 最近维护时间	最新版本 v0.8.1 发布于 2026-06-25，changelog 记录详尽

综合评分（三项均值）：8.7

7. 跟同类 Skills 相比的优势

对比对象	定位	与 visual-explainer 的差异
effective-html（plannotator）	专注生成 HTML 计划/架构图页面的 agent skill	功能聚焦在计划与架构图渲染，未覆盖 diff 审查、幻灯片模式、Chart.js 仪表盘等场景，命令与模板体系也更单薄
project-artifact（anthropics 官方）	一键生成可分享的多工作流项目状态页，替代手写周报	面向“项目状态汇报”场景，产出是周报式状态页而非面向代码 diff/架构/计划的技术可视化，两者定位互补而非重叠

8. 用户评价

GitHub Issue #18（用户 Emasoft）反馈早期版本需要手动把命令复制进 ~/.claude/commands 目录、体验繁琐，并建议做成正式插件；该诉求后来体现为文档中的 Claude Code 插件市场一键安装方式。GitHub Issue #21（用户 ttttmr）反馈在 Pi 环境下，旧版手动安装脚本会与包管理器安装方式产生技能/提示词冲突。该技能目前在 Reddit、Hacker News 等平台尚无独立的具名用户评价。

9. 其他补充

仓库包含详尽的 CHANGELOG.md（记录逐版本变更），并接受外部贡献（当前 3 位贡献者）。README 明确致谢参考了 Anthropic 官方 frontend-design 技能与第三方 interface-design 项目的部分设计思路。

10. 安装使用方式

Claude Code（推荐）：

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

安装后命令以 /visual-explainer:command-name 形式出现，例如 /visual-explainer:diff-review。

Codex CLI：

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/  # 可选
rm -rf /tmp/visual-explainer

安装后直接让 Codex 使用 visual-explainer 技能，或调用 $visual-explainer。

OpenClaw： 使用仓库内 configs/openclaw/AGENTS.md 作为项目指引，并引用 plugins/visual-explainer/ 作为技能来源（非原生插件形式）。

Pi（额外支持的生态）： pi install git:github.com/nicobailon/visual-explainer，安装后需重启 Pi 生效。

安装后注意事项：所有生态下生成的 HTML 都会写入 ~/.agent/diagrams/ 并尝试用默认浏览器打开；若运行环境没有浏览器访问权限或处于沙箱中，需要手动打开生成的文件。

11. 注意事项

自动在浏览器打开生成文件依赖宿主环境是否允许访问浏览器，部分沙箱环境可能需要手动打开生成的 HTML 文件
OpenClaw 目前仅有轻量 AGENTS 指引、没有原生插件适配器；Hermes Agent 兼容性文档未提及，需自行验证
切换系统深浅色主题后，已生成页面里的 Mermaid 图需要刷新页面才能正确重渲染
生成内容的排版质量与信息提炼程度会随底层大模型能力不同而有差异
可选的 AI 生成配图功能依赖单独安装的 surf 组件，属于可选增强而非必需依赖