nicobailon/visual-explainer · 上手攻略

  • 仓库：nicobailon/visual-explainer
  • 链接：https://github.com/nicobailon/visual-explainer
  • 分类：agent-skill（多 harness 兼容）
  • 作者：spark
  • 更新：2026-08-07

是什么

一个 Agent Skill 集合，把"在终端里讲不清的复杂图表/表格/对比"从 ASCII art / monospace 字符画升级为自包含 HTML 页面或幻灯片，直接在浏览器中打开阅读。支持架构图、Mermaid 流程图、数据表、幻灯片、diff 评审、plan 对比、project recap 等多种形态。

与单一 harness 锁定不同，它同时提供 6 种安装形态：Claude Code（marketplace 插件）、Pi（包管理 + 原生 visual_explainer 工具）、Codex CLI、OpenCode/opencode、Cursor（rules-based）、OpenClaw（AGENTS rules + skill 源拷贝）。

输出统一写到 ~/.agent/diagrams/filename.html，需要浏览器打开。

解决什么问题

三个真实痛点：

  1. 终端里的图超过 3 个节点就乱：box-drawing 字符、ASCII art 在分支多、层级深时立刻不可读。
  2. 表格超过 3 列就折行：终端宽度有限，15 列需求对照表被截断、对不齐。
  3. plan / diff 评审只能看干文本：架构图、风险表、变更对比用纯文字表达不清，团队 review 效率低。

Visual-explainer 把这些场景显式封装为命令：/diff-review、/plan-review、/generate-web-diagram、/generate-visual-plan、/generate-slides、/project-recap、/fact-check；并在 agent 准备"在终端里输出 4 行以上、3 列以上表格"时自动路由到 HTML 输出。

快速安装

按你的 harness 选一个：

# Claude Code（marketplace 插件）
/plugin marketplace add nicobailon/visual-explainer
/plugin install visual-explainer@visual-explainer-marketplace
# 注：命令 namespace 为 /visual-explainer:command-name

# Pi（包管理 + 原生工具）
pi install git:github.com/nicobailon/visual-explainer
# 或本地 clone 后安装
git clone --depth 1 https://github.com/nicobailon/visual-explainer.git
pi install ./visual-explainer
# Pi 注册了原生工具 visual_explainer，action: prepare / render

# 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
# 调用：$visual-explainer 或 /prompts:diff-review 等

# OpenCode/opencode
git clone --depth 1 https://github.com/nicobailon/visual-explainer.git /tmp/visual-explainer
mkdir -p ~/.config/opencode/skill ~/.config/opencode/command
cp -R /tmp/visual-explainer/plugins/visual-explainer ~/.config/opencode/skill/visual-explainer
cp /tmp/visual-explainer/plugins/visual-explainer/commands/*.md ~/.config/opencode/command/
rm -rf /tmp/visual-explainer

# Cursor（rules-based，非原生 skill）
# 把 configs/cursor/visual-explainer.mdc 加入 Cursor rules

# OpenClaw（AGENTS rules + 拷贝 skill 源）
# 使用 configs/openclaw/AGENTS.md，并把 plugins/visual-explainer/ 拷贝为 canonical skill 源

Pi 用户从旧的 curl 安装切换到包管理时，必须先清理旧文件避免冲突：

rm -rf ~/.pi/agent/skills/visual-explainer
rm -f ~/.pi/agent/prompts/{diff-review,fact-check,generate-slides,generate-visual-plan,generate-web-diagram,plan-review,project-recap}.md
rm -f ~/.pi/agent/prompts/share*.md

最小硬件：现代浏览器（任何能渲染 SVG + CSS Grid 的都行）。

核心用法

7 个内置命令：

命令 用途
/generate-web-diagram 给任意主题生成 HTML 示意图
/generate-visual-plan 把一个特性/扩展的实现方案可视化为计划图
/generate-slides 生成"杂志质感"的幻灯片
/diff-review diff 评审 + 架构对比 + 代码 review
/plan-review 拿现有 plan 跟 codebase 比对，做风险评估
/project-recap 给"刚回到这个项目"的人生成上下文快照（接受时间参数，如 2w）
/fact-check 把文档跟实际代码核对，验证准确性

任何可滚动 HTML 命令都支持 --slides 改输出为幻灯片：

/diff-review --slides
/project-recap --slides 2w

自动触发场景：agent 准备在终端输出 4 行以上、3 列以上表格时，会自动渲染为 HTML 而非纯文本。

Pi 原生工具的 workflow：

1) action: "prepare"  → 生成视觉解释的方案（plan / architecture / diff / implementation 后调用）
2) action: "render"   → 把完整 HTML 写到 ~/.agent/diagrams/ 并打开

底层路由规则（agent 内部使用）： - 流程图 → Mermaid（带 zoom/pan） - 架构概览 → CSS Grid - 数据对照 → HTML 表格 - 仪表盘 → Chart.js - 幻灯片 → 自带 slide engine

仓库结构：

.claude-plugin/
├── plugin.json         ← marketplace identity
└── marketplace.json    ← plugin catalog
plugins/
└── visual-explainer/
    ├── SKILL.md              ← workflow + 设计原则
    ├── extension.ts          ← Pi 原生工具
    ├── commands/             ← 斜杠命令
    ├── references/           ← agent 生成时读的参考
    │   ├── css-patterns.md   ← 布局、动画、主题
    │   ├── libraries.md      ← Mermaid / Chart.js / 字体
    │   ├── responsive-nav.md ← 多节页 sticky TOC
    │   └── slide-patterns.md ← 幻灯片引擎、转场、preset
    └── templates/            ← 不同色板的参考模板
        ├── architecture.html
        ├── mermaid-flowchart.html
        ├── data-table.html
        └── slide-deck.html

典型适用场景

  • 架构评审：让 agent 把现有 codebase 的模块依赖画出来，浏览器里点开看，比读 200 行 README 直观。
  • Diff 评审：/diff-review 同时输出"改了哪些文件 + 改动前后的架构对比 + 风险评估"三栏，比 git diff 高效。
  • Plan 对比：写好 refactor 方案后 /plan-review ~/docs/refactor-plan.md，agent 拿 plan 跟 codebase 对比标红。
  • 新人 onboarding：/project-recap 生成项目"心智模型快照"，包含目录结构 + 关键决策 + 上周活跃区。
  • 会议/分享：/generate-slides 或任何命令加 --slides，输出可投屏的幻灯片。
  • 文档 fact-check：写完设计文档后 /fact-check，让 agent 跟代码核对一致性。

坑与注意

  1. 生成质量依赖模型能力：仓库自承"Results vary by model capability"——强模型（Claude Sonnet/Opus 级别）才能稳定产出可读 HTML，弱模型可能给出行列错乱或主题不一致的页面。
  2. 浏览器自动打开依赖 harness：HTML 是写到 ~/.agent/diagrams/ 的自包含文件，但"自动在浏览器打开"取决于 harness 自身 + 沙箱规则。在 sandbox 里执行可能写完不弹窗。
  3. 主题切换要刷新：Mermaid 生成的 SVG 在切换 OS 主题（dark/light）时不会自动重新着色，需要手动 F5。
  4. OpenClaw 集成是轻量级：仅提供 AGENTS.md rules + 拷贝 skill 源，没有原生 plugin adapter；自动触发和命令 namespace 都不完整，效果最弱。
  5. Cursor 集成也是 rules-based：不是原生 skill，需要 Cursor 自己识别 AGENTS.md / .mdc 才能触发。
  6. 路径约定：~/.agent/diagrams/ 是默认输出目录，如果项目协作里别人用不同路径，review 时要确认对方发的也是这个目录还是用了别名。
  7. Pi 用户混用旧新装法会冲突：从 curl | bash 切到 pi install 时必须先 rm 旧文件，否则 user-level copies 会 shadow package resources。
  8. 依赖 Mermaid/Chart.js 的 CDN：自包含 HTML 里通过 CDN 引用库，离线环境需要替换为本地拷贝。
  9. 大仓库 project-recap 慢：/project-recap 会读大量文件，配 --slides 2w 时间窗更精确，避免全量扫描。

与同类对比

工具 形态 优势 劣势
visual-explainer（本仓库） 多 harness skill + 原生工具 6 种 harness 安装路径；命令覆盖 7 个真实场景；自包含 HTML 输出质量看模型；OpenClaw/Cursor 集成是 rules 级
Mermaid Live Editor 网页编辑器 交互式、所见即所得 不能从对话自动产出
diagrams.net (draw.io) 桌面/Web 应用 拖拽自由度高 完全人工，不接 agent
Excalidraw Web/桌面 手绘风格 同样不接 agent
Claude 原生 ASCII 渲染 agent 默认 零安装 复杂场景必然乱
Anthropic 官方 frontend-design skill Claude skill 设计感强 偏重前端设计而非架构图/review

差异化卖点：唯一同时给 6 种 harness 提供安装路径 + 把 7 个常见评审/汇报场景做成命令 + 自包含 HTML 离线可读。

一句话推荐结论

只要你的 agent 能跑、你的项目复杂度超过 3 个模块，就装上；最常用的 /diff-review 和 /plan-review 能把 review 时间砍一半以上。OpenClaw/Cursor 用户收益略低，但仍可作为 AGENTS rules 入门。

最小可跑命令

# 1. 选你的 harness（示例用 Claude Code）
/plugin marketplace add nicobailon/visual-explainer
/plugin install visual-explainer@visual-explainer-marketplace

# 2. 重启 Claude Code 激活

# 3. 任选一个命令触发
> /generate-web-diagram
   主题：当前项目的认证流程

> /diff-review
   （agent 自动取最近一次未提交 diff）

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

> /project-recap --slides 2w

# 4. 打开输出
xdg-open ~/.agent/diagrams/$(ls -t ~/.agent/diagrams/ | head -1)   # Linux
open ~/.agent/diagrams/$(ls -t ~/.agent/diagrams/ | head -1)       # macOS

来源与可信度

  • 仓库 README（GitHub，2026-08-07 抓取）：https://github.com/nicobailon/visual-explainer
  • 6 种 harness 安装路径均来自 README；其中 Claude Code marketplace、Pi 包管理、Codex CLI、OpenCode 安装步骤均可直接复制。
  • 引用：Borrow ideas from Anthropic's frontend-design skill and interface-design——README 自述灵感来源。
  • commits/main（2026-08-07 抓取）：存在持续提交记录，更新活跃。
  • 原始 commit/PR/issue 链接：仓库主分支头部 commit nicobailon/visual-explainer@main（具体 SHA 须 git ls-remote https://github.com/nicobailon/visual-explainer.git refs/heads/main 实时取）。
  • 不确定处：OpenClaw 集成的"非原生 plugin adapter"细节未在 README 展开，按 configs/openclaw/AGENTS.md 推断需自行组合；自动触发表格阈值（4 行 × 3 列）来自 README 表述但实际触发稳定性未做端到端 benchmark。