【免费下载链接】visual-explainer
Agent skill that generates rich HTML pages or slide decks for diagrams, diff reviews, plan audits, data tables, and project recaps
visual-explainer 是一个面向 AI 编码 Agent 的技能包(agent skill):当 Agent 需要解释系统架构、评审 diff、对比计划与需求、汇总项目进度时,它不再输出难以阅读的 ASCII 字符画和管道符表格,而是生成一个自包含的 HTML 页面并在浏览器中打开。本文基于仓库根目录的 README.md 展开,结合 plugins/visual-explainer/SKILL.md、package.json 与各子模块源码,完整覆盖安装、命令、Quick 模式、幻灯片、主题系统、工作原理与限制,帮助你把它接入 Claude Code、Pi、MCP、Antigravity、Codex、OpenCode、Cursor 等任意主流 Agent 环境。
为什么需要它:ASCII 图表的天然局限
每个编码 Agent 在被要求画图时都会默认输出 ASCII art——盒式绘制字符、等宽对齐技巧、文本箭头。三五个节点的简单流程图勉强能看,但只要超过这个规模,输出就会变成难以阅读的乱码。
表格问题更严重。让 Agent 把 15 条需求与计划逐条对比,终端里就会出现一堵会折行、会断开的|与-组成的墙:数据都在,但读起来极其痛苦。
visual-explainer 要解决的就是这两个痛点:
- 真实排版:真正的字体层级、间距与配色,而不是等宽字符堆砌;
- 深浅双主题:支持深色/浅色配色方案;
- 交互式 Mermaid 图表:支持缩放(zoom)与平移(pan)的流程图、时序图、ER 图等。
它的设计哲学是零构建、零依赖:常规使用只需要一个浏览器;可选的 MCP 与 PPTX 工具才会用到少量 Node 依赖(见 package.json 中的dependencies:@modelcontextprotocol/server、pptxgenjs、zod、node-html-parser)。
典型调用方式:
> draw a diagram of our authentication flow > /diff-review > /plan-review ~/docs/refactor-plan.md核心命令一览
仓库在 plugins/visual-explainer/commands/ 下打包了 7 个斜杠命令模板,对应 README.md 的 Commands 表:
| 命令 | 作用 |
|---|---|
/generate-web-diagram | 为任意主题生成 HTML 图表 |
/generate-visual-plan | 为功能或扩展生成可视化实施计划 |
/generate-slides | 生成杂志级的幻灯片组 |
/diff-review | 可视化 diff 评审:架构对比 + 代码评审 |
/plan-review | 将计划与代码库对比并做风险评估 |
/project-recap | 生成心理模型快照,便于上下文切换后快速回到项目 |
/fact-check | 对照真实代码核验文档的准确性 |
此外,Agent 会在即将向终端倾倒复杂表格时自动介入(表格达到 4 行以上或 3 列以上),改为渲染 HTML 页面,只在聊天里给出简短摘要。这条规则写死在 plugins/visual-explainer/SKILL.md 的 "Trigger and delivery rules" 一节中。
安装:多 Harness 支持矩阵
visual-explainer 的安装形态随宿主环境而异。README 给出的支持矩阵如下:
| Harness | 支持形态 | 安装路径 / 行为 |
|---|---|---|
| Claude Code | Marketplace 插件 | 保留 marketplace 结构,源码位于plugins/visual-explainer/ |
| Pi | 包元数据 + 安装器 | package.json声明 skill、prompt 与原生visual_explainer工具(含prepare与render动作);install-pi.sh面向旧的纯手工安装 |
| MCP 主机 | 本地 stdio MCP 服务 | visual-explainer-mcp暴露渲染工具、提示模板与只读 skill 资源,不起 HTTP 服务 |
| PPTX 导出 | 尽力而为的静态工具 | visual-explainer-pptx将简单 HTML 幻灯片转成.pptx;HTML 仍是唯一事实来源 |
| Antigravity CLI | 原生 Agent Skills 路径 | 复制plugins/visual-explainer/到~/.gemini/antigravity-cli/skills/visual-explainer(全局)或.agents/skills/visual-explainer(单工作区) |
| Codex CLI | 原生 skill 路径 + 可选 prompts | 复制到~/.codex/skills/visual-explainer;可选 prompts 放入~/.codex/prompts/(若你的 Codex 构建支持) |
| OpenCode/opencode | 观测到的 skill/command 路径 | 复制到~/.config/opencode/skill/visual-explainer;可选命令放入~/.config/opencode/command/ |
| Cursor | 原生 Agent Skills 路径 | 复制plugins/visual-explainer/到~/.cursor/skills/visual-explainer(全局)或.cursor/skills/visual-explainer(工作区);可选旧式规则在configs/cursor/ |
| OpenClaw | 轻量 AGENTS/rules 指引 | 使用随附的 AGENTS 指引配合规范 skill 目录 |
| VS Code Copilot / Copilot CLI | 自定义指令或规则指引 | 把随附 AGENTS 指引加入工作区指令或规则配置 |
Claude Code(Marketplace 插件)
/plugin marketplace add nicobailon/visual-explainer /plugin install visual-explainer@visual-explainer-marketplace注意:Claude Code 插件会把命令按/visual-explainer:command-name命名空间化。
Pi
pi install git:github.com/nicobailon/visual-explainer或者从本地检出安装:
git clone --depth 1 https://github.com/nicobailon/visual-explainer.git pi install ./visual-explainer包清单在 package.json 中通过"pi"字段声明规范 skill、命令模板与 Pi 工具:
"pi": { "extensions": ["./plugins/visual-explainer/extension.ts"], "skills": ["./plugins/visual-explainer"], "prompts": ["./plugins/visual-explainer/commands"], "image": "./banner.png" }Pi 原生工具visual_explainer:由 plugins/visual-explainer/extension.ts 注册(pi.registerTool),提供三种action:
action: "prepare":在生成或评审完一个较大的计划、架构、diff 或实现后,规划一次可视化解释。它不写文件,只返回推荐的执行流程;当preferSubagent(默认 true)且 subagent 工具可用时,会建议先派一个 scout subagent 收集代码库上下文(见prepareVisualExplanation,extension.ts);action: "render":把完整的自包含 HTML 文档写入~/.agent/diagrams/。文件名必须是 basename(拒绝路径、..与控制字符,见outputFilename,extension.ts),HTML 必须是完整文档(assertHtmlDocument校验<html>/</html>包裹,extension.ts);action: "render_quick"(可选加入):校验一份紧凑 JSON spec 并用本地渲染器 plugins/visual-explainer/quick/render.mjs 渲染。
render在写盘前还会自动补全文档:缺失的html lang、缺失的 viewport meta、自包含 favicon(内联 SVG data URI),以及对$$...$$数学块内裸</>的转义(见ensureDocumentMetadata、ensureFavicon、escapeDisplayMath,extension.ts)。输出目录固定为join(homedir(), ".agent", "diagrams")(extension.ts),并拒绝符号链接目录/文件目标以防写穿。
渲染完成后可以选择用哪种方式打开页面,对应viewer参数:
viewer: "browser"(默认):跨平台调用open(macOS)/xdg-open(Linux)/cmd /c start(Windows)(openInBrowser,extension.ts);viewer: "glimpse":仅当用户想要原生 Glimpse 窗口且已安装glimpseui时使用;viewer: "auto":先尝试 Glimpse,失败后回退到浏览器(openRenderedPage,extension.ts)。
/generate-web-diagram仍是随附的提示模板命令。如果你以前用过旧版 curl/手工安装器,请先删除那些拷贝文件再执行pi install,否则用户级拷贝会遮蔽包资源,Pi 会报 skill 与 prompt 冲突:
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/s[h]are*.md旧版安装器依然可用(如果你更喜欢拷贝式安装而非包管理),但它不会安装原生 Pi 工具:
curl -fsSL https://raw.githubusercontent.com/nicobailon/visual-explainer/main/install-pi.sh | bashMCP 服务器
用visual-explainer-mcp(包安装)或先从检出运行npm install --no-package-lock,再把主机指向 plugins/visual-explainer/mcp/server.mjs。某些主机需要二进制的绝对路径。该服务器仅限本地 stdio:不调用 LLM、不启动 HTTP 监听、不处理凭据、也不会写到配置的输出目录(默认~/.agent/diagrams/)之外。
安全边界(README 与 plugins/visual-explainer/mcp/README.md 一致):
- 设置
VISUAL_EXPLAINER_OUTPUT_DIR可把"监狱"移到本机另一目录;不设置则保持默认路径字节级一致; - 配置的监狱必须能解析到自身,符号链接监狱路径会被拒绝;
- 渲染目标拒绝已存在的符号链接,并通过临时文件重命名完成写入;
- 请把监狱指向仅自己可写的目录,避免使用全局可写或组可写的共享目录,防止本机其他用户在"校验与写入之间"替换渲染目标;
- 文件名必须是 basename,路径穿越、控制字符与符号链接目标都会被拒绝。
包安装的 MCP 配置示例:
{ "mcpServers": { "visual-explainer": { "command": "visual-explainer-mcp" } } }检出安装的配置示例(注意使用绝对路径):
{ "mcpServers": { "visual-explainer": { "command": "node", "args": ["/absolute/path/to/visual-explainer/plugins/visual-explainer/mcp/server.mjs"] } } }服务器暴露三个工具:
visual_explainer_prepare:返回推荐的 visual-explainer 流程,不写文件;visual_explainer_render_html:校验完整 HTML 文档并写入输出目录;visual_explainer_render_quick:校验 quick 模式 JSON spec 并写入渲染后的 HTML。
渲染工具默认open: false;仅当你希望服务器请求打开浏览器或 Glimpse 窗口时才设open: true。
同时它还以 MCP prompt 的形式暴露全部 7 个命令模板(generate-web-diagram、generate-visual-plan、generate-slides、diff-review、plan-review、project-recap、fact-check,用request填充模板的$@参数),并以只读资源暴露规范SKILL.md、命令 markdown、quick README 与 quick schema。
Antigravity CLI
Antigravity CLI 面向消费级 Gemini CLI 工作流,从.agents/skills/(工作区级)或~/.gemini/antigravity-cli/skills/(全局)加载 Agent Skills。
全局安装(bash):
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工作区安装(bash):
git clone --depth 1 https://github.com/nicobailon/visual-explainer.git /tmp/visual-explainer mkdir -p .agents/skills cp -R /tmp/visual-explainer/plugins/visual-explainer .agents/skills/visual-explainer rm -rf /tmp/visual-explainerREADME 还提供了上述两种安装的 PowerShell 等价脚本(含事务化安装逻辑:暂存目录 + 备份 + 失败回滚 + EXIT 清理)。安装后在项目里启动agy,用/skills确认visual-explainer被发现,然后让 Antigravity 在图表、视觉评审、幻灯片与复杂表格场景使用该 skill。Antigravity SDK 项目可把同一份SKILL.md内容复用为 Agent Skill 资源,但本仓库不附带独立 SDK 包装;命令模板仍作为plugins/visual-explainer/commands/下的参考 markdown 存在。
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 # 可选,仅当你的 Codex 构建支持 prompt 模板时: cp /tmp/visual-explainer/plugins/visual-explainer/commands/*.md ~/.codex/prompts/ rm -rf /tmp/visual-explainer用$visual-explainer或直接让 Codex 使用该 skill 来调用;若 prompts 已安装且受支持,可用/prompts:diff-review、/prompts:plan-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让 OpenCode 使用visual-explainerskill 即可激活;命令模板行为取决于所装 OpenCode/opencode 构建版本。
Cursor
Cursor 从~/.cursor/skills/(全局)与.cursor/skills/(工作区)加载 Agent Skills,并按SKILL.md中的name:字段发现技能。README 提供了全局与工作区两套 bash 安装脚本(均带set -euo pipefail与事务化回滚:克隆到临时目录 → 暂存 → 校验SKILL.md存在 → 备份旧目标 → 原子移动),工作区版本目标为.cursor/skills/visual-explainer。安装后让 Cursor 在图表、视觉评审、幻灯片与复杂表格场景使用该 skill。
可选旧式规则:如果你更倾向基于 rules 的引导而非依赖 skill 发现,可以把 configs/cursor/visual-explainer.mdc 加入 Cursor rules。
OpenClaw 与 VS Code Copilot
- OpenClaw:把 configs/openclaw/AGENTS.md 作为轻量项目指引,并复制或引用
plugins/visual-explainer/作为规范 skill 源;不包含原生 OpenClaw 插件适配器。 - VS Code Copilot / Copilot CLI:使用 configs/copilot/AGENTS.md 作为自定义指令或规则指引。VS Code 中可复制到受支持的工作区自定义指令文件(如
.github/copilot-instructions.md);Copilot CLI 通过其工作区指令或规则配置加入。两者都从plugins/visual-explainer/读取规范 skill;本仓库不提供原生 Agent Skills 支持、Copilot 包或经过测试的 Copilot 插件适配器。
Quick Mode:用紧凑 JSON spec 代替重复 HTML
Quick 模式把重复的 HTML/CSS 移出 Agent 响应:Agent 只产出一份紧凑 JSON spec,plugins/visual-explainer/quick/render.mjs 负责校验并生成完整自包含 HTML 页面。
Quick 模式是显式加入(opt-in)的。只有命令里带字面量--quick才启用,且只支持四个命令:
/generate-web-diagram --quick authentication request flow /diff-review --quick main..HEAD(/plan-review --quick与/project-recap --quick同样支持。)不带--quick的命令保持完整的自定义 HTML 工作流;当内容不适合 quick schema、校验失败或渲染出错时,Agent 会回退到完整模式。quick 模式不适用于自定义视觉组合、幻灯片、Mermaid 密集拓扑,以及 schema 无法表达的内容;slides、fact-check、视觉计划、PPTX、主题与更新场景一律不用 quick 模式。
Pi 中的调用
{ "action": "render_quick", "filename": "auth-flow-quick", "spec": { "title": "Authentication flow", "sections": [ { "title": "Request path", "flow": { "nodes": [ { "id": "browser", "label": "Browser" }, { "id": "api", "label": "API", "tone": "positive" } ], "edges": [{ "from": "browser", "to": "api", "label": "token" }] } } ] } }其他 Harness 中的调用
node ./quick/render.mjs spec.json ~/.agent/diagrams/auth-flow-quick.html使用相对已安装 skill 目录的quick目录;渲染器出错时继续走正常完整 HTML 流程。
Schema 契约
plugins/visual-explainer/quick/schema.json 是权威 JSON Schema(Draft 2020-12)。spec 包含title(必填)、可选subtitle/summary,以及一个或多个sections(required: ["title", "sections"],且additionalProperties: false严格禁止未知属性)。每个 section 可包含以下组件:
| 组件 | 含义 | 关键字段与取值 |
|---|---|---|
cards | 紧凑的发现或概念卡 | title(必填)、body、meta[]、tone |
table | 列 + 字符串行 | columns(≥1)、rows(每行字符串数组) |
risks | 带严重级别的风险项 | title、body、severity:low/medium/high/critical |
files | 路径、说明与变更状态 | path(必填)、detail、status:added/modified/deleted/reviewed/planned |
steps | 有序工作或时间线项 | title(必填)、body、status:done/current/next/blocked |
flow | 节点与有向边 | nodes[](id+label+可选detail/tone)、edges[](from/to/可选label) |
callouts | 备注、决策或警告 | body(必填)、可选title/tone |
evidence | 证据:标签、值、可选来源 | label、value、source |
公共tone枚举为neutral/accent/positive/warning/danger/info。所有 Agent 文本都会被 HTML 转义;未知属性、非法枚举值、错误的 flow 引用(from/to必须对应存在的节点)以及列数不匹配的表格行都会导致校验失败。Pi 走既有visual_explainer工具(action: "render_quick"),其他 harness 可本地运行plugins/visual-explainer/quick/render.mjs。
Slide Deck Mode:从滚动页面到演示文稿
任何会产生可滚动页面的命令都支持--slides,改为生成幻灯片组(slide deck):
/diff-review --slides /project-recap --slides 2w需要可携带的演示文件时,给/generate-slides加--pptx,或在生成 HTML deck 后运行导出器:
visual-explainer-pptx ~/.agent/diagrams/my-deck.html ~/.agent/diagrams/my-deck.pptx从检出运行则用:
npm install --no-package-lock node plugins/visual-explainer/pptx/export.mjs ~/.agent/diagrams/my-deck.html ~/.agent/diagrams/my-deck.pptx省略输出路径时,导出器会在输入文件旁写入.pptx后缀文件(见 plugins/visual-explainer/pptx/README.md)。
PPTX 导出是"尽力而为、静态"的交接,实现位于 plugins/visual-explainer/pptx/export.mjs。它从<section class="slide">元素中提取:幻灯片标题、短文本、项目符号、简单表格、代码块与 Mermaid 源码占位符。它不保留:动画/过渡、阅读器导航(reader rail)、大纲、深链接与恢复状态、响应式布局、自定义 Web 字体,以及实时 Mermaid/Chart.js/SVG/canvas 渲染或 JavaScript 行为。最终保真请以 HTML deck 为准;.pptx仅作为需要演示文件时的可携带静态交接件。
slide 模式在 plugins/visual-explainer/references/slide-patterns.md 中定义了完整的工程规范,要点包括:
- 每张幻灯片只占一个
100dvh视口预算,无页面级滚动;默认overflow: hidden会静默裁剪,因此必须在交付前于目标视口与短横屏高度(开启prefers-reduced-motion: reduce)运行交付溢出检查(checkSlideOverflow),不能靠浏览器自己暴露问题; - 10 种幻灯片类型:Title、Section Divider、Content、Split、Diagram、Dashboard、Table、Code、Quote、Full-Bleed;
- 完整导航 chrome:进度条、可展开右侧阅读轨、带阅读百分比的计数器、键盘导航(方向键、
O大纲、?帮助)、#slide-N深链接(hash 优先于恢复状态)、基于 localStorage 的恢复; autoFit()运行时兜底:处理 Mermaid SVG 填满容器、KPI 长文本缩放、超长引文等比缩小——它只是安全网,被标记data-auto-fit的幻灯片仍需人工评审;- 写 HTML 前必须对源文档做"清点 → 映射到幻灯片"两步,保证不丢内容:一份 7 节的源文档通常产出 18–25 张幻灯片,而不是 10–13 张。
主题系统:11 套配色 + 运行时主题/字体选择器
用户要求可切换主题或点名某个配色(Dracula、Nord、Gruvbox、Catppuccin…)时,页面会带一个选择器——配色用彩色圆点、字体用Aa字条,两者都实时切换并重新渲染每一个 Mermaid 图(因为 Mermaid 在渲染时把颜色烘焙进 SVG):
"explain this pipeline, use Gruvbox" "diagram the auth flow, let me switch themes"随附 11 套调色板:深色 7 套(Dracula、Nord、One Dark、Catppuccin Mocha、Tokyo Night、Gruvbox Dark、Synthwave '84)+浅色 4 套(Solarized Light、GitHub Light、Catppuccin Latte、Gruvbox Light)。每套主题都定义与 plugins/visual-explainer/references/css-patterns.md 一致的 21 个 CSS 自定义属性(--bg、--surface、--surface-elevated、--border、--border-bright、--text、--text-dim、--accent、--accent-dim、--node-a/b/c、--green、--red、--orange及其 dim 变体),所以现有所有样式模式无需改动即可适配任意主题(完整变量定义见 plugins/visual-explainer/references/themes.md)。
字体选择器只提供 SKILL.md 已推荐的字体对:DM Sans + Fira Code、Instrument Serif + JetBrains Mono、IBM Plex Sans + IBM Plex Mono、Bricolage Grotesque + JetBrains Mono、Plus Jakarta Sans + Azeret Mono。页面必须通过var(--font-body)/var(--font-mono)读取字体,并在一个 stylesheet link 中按实际用到的字重加载全部字体族(不依赖 faux-bold)。
Mermaid 变量从调色板派生,而不是逐主题存储:18 个themeVariables全部由 6 个调色板值推导(--bg、--surface、--text、--text-dim、--accent等),这保证了图表永远与周围页面同步(mermaidVars(),见 themes.md)。选择器默认主题/字体可通过配置指定:
# visual-explainer.config.md(harness 无关的项目级配置) theme: gruvbox-dark font: bricolagetheme:/font:的值取自THEMES与FONT_PAIRS的 id,只用于播种DEFAULT_THEME/DEFAULT_FONT;未识别或缺失的值会回退到页面审美方向原本的选择。Claude Code 用户可把个人覆盖放在.claude/visual-explainer.local.md,共享项目默认值应放在 harness 无关的visual-explainer.config.md。这是 Agent 可读的生成契约,不是原生visual_explainer.render的参数。
选择器是 opt-in。未要求选择器的页面仍会得到一套按内容挑选的调色板与字体对。切主题时不要用@media (prefers-color-scheme)包裹主题值——显式选择不应被操作系统覆盖。另外,切换操作系统主题后 Mermaid SVG 需要刷新页面才能生效(Mermaid 尺寸在渲染时固定)。
工作原理:从目录结构到输出路径
README 的 How It Works 一节给出了仓库结构(skill 目录以plugins/visual-explainer/为规范源):
.claude-plugin/ ├── plugin.json ← marketplace identity └── marketplace.json ← plugin catalog plugins/ └── visual-explainer/ ├── .claude-plugin/ │ └── plugin.json ← plugin manifest ├── SKILL.md ← workflow + design principles ├── extension.ts ← Pi native tool ├── commands/ ← slash commands ├── quick/ ← JSON schema + deterministic local renderer ├── mcp/ ← local stdio MCP server ├── pptx/ ← best-effort static PPTX exporter ├── references/ ← agent reads before generating │ ├── css-patterns.md (layouts, animations, theming) │ ├── libraries.md (Mermaid, Chart.js, fonts) │ ├── responsive-nav.md (sticky TOC for multi-section pages) │ ├── slide-patterns.md (slide engine, transitions, presets) │ └── themes.md (11 palettes + runtime theme/font picker) └── templates/ ← reference templates with different palettes ├── architecture.html ├── mermaid-flowchart.html ├──>赞【免费下载链接】visual-explainer
Agent skill that generates rich HTML pages or slide decks for diagrams, diff reviews, plan audits, data tables, and project recaps
相关推荐
visual-explainer generate-slides 指南:用 Agent 生成自包含 HTML 演示文稿与 PPTX 导出
visual explainer generate slides 指南:用 Agent 生成自包含 HTML 演示文稿与 PPTX 导出 核心导读 : gene
如何为 LocalAI 配置上下文压缩,让长对话不超出模型上下文限制?
如何为 LocalAI 配置上下文压缩,让长对话不超出模型上下文限制? 在多轮聊天场景中,对话历史会随着消息积累不断变长,直到逼近模型配置的 context_s
visual-explainer 自包含 HTML 图表 CSS 模式全解:主题、布局、Mermaid 缩放与溢出防护实战指南
visual explainer 自包含 HTML 图表 CSS 模式全解:主题、布局、Mermaid 缩放与溢出防护实战指南 视觉解释页面的核心不在于"画了多