【免费下载链接】visual-explainerAgent skill that generates rich HTML pages or slide decks for diagrams, diff reviews, plan audits, data tables, and project recaps项目地址https://gitcode.com/gh_mirrors/vi/visual-explainer点击查看免费下载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 中的dependenciesmodelcontextprotocol/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 CodeMarketplace 插件保留 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 幻灯片转成.pptxHTML 仍是唯一事实来源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 CodeMarketplace 插件/plugin marketplace add nicobailon/visual-explainer /plugin install visual-explainervisual-explainer-marketplace注意Claude Code 插件会把命令按/visual-explainer:command-name命名空间化。Pipi 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提供三种actionaction: prepare在生成或评审完一个较大的计划、架构、diff 或实现后规划一次可视化解释。它不写文件只返回推荐的执行流程当preferSubagent默认 true且 subagent 工具可用时会建议先派一个 scout subagent 收集代码库上下文见prepareVisualExplanationextension.tsaction: render把完整的自包含 HTML 文档写入~/.agent/diagrams/。文件名必须是 basename拒绝路径、..与控制字符见outputFilenameextension.tsHTML 必须是完整文档assertHtmlDocument校验html//html包裹extension.tsaction: render_quick可选加入校验一份紧凑 JSON spec 并用本地渲染器 plugins/visual-explainer/quick/render.mjs 渲染。render在写盘前还会自动补全文档缺失的html lang、缺失的 viewport meta、自包含 favicon内联 SVG data URI以及对$$...$$数学块内裸/的转义见ensureDocumentMetadata、ensureFavicon、escapeDisplayMathextension.ts。输出目录固定为join(homedir(), .agent, diagrams)extension.ts并拒绝符号链接目录/文件目标以防写穿。渲染完成后可以选择用哪种方式打开页面对应viewer参数viewer: browser默认跨平台调用openmacOS/xdg-openLinux/cmd /c startWindowsopenInBrowserextension.tsviewer: glimpse仅当用户想要原生 Glimpse 窗口且已安装glimpseui时使用viewer: auto先尝试 Glimpse失败后回退到浏览器openRenderedPageextension.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 CLIAntigravity CLI 面向消费级 Gemini CLI 工作流从.agents/skills/工作区级或~/.gemini/antigravity-cli/skills/全局加载 Agent Skills。全局安装bashgit 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工作区安装bashgit 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 CLIgit 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/opencodegit 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 构建版本。CursorCursor 从~/.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 CopilotOpenClaw把 configs/openclaw/AGENTS.md 作为轻量项目指引并复制或引用plugins/visual-explainer/作为规范 skill 源不包含原生 OpenClaw 插件适配器。VS Code Copilot / Copilot CLI使用 configs/copilot/AGENTS.md 作为自定义指令或规则指引。VS Code 中可复制到受支持的工作区自定义指令文件如.github/copilot-instructions.mdCopilot CLI 通过其工作区指令或规则配置加入。两者都从plugins/visual-explainer/读取规范 skill本仓库不提供原生 Agent Skills 支持、Copilot 包或经过测试的 Copilot 插件适配器。Quick Mode用紧凑 JSON spec 代替重复 HTMLQuick 模式把重复的 HTML/CSS 移出 Agent 响应Agent 只产出一份紧凑 JSON specplugins/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 SchemaDraft 2020-12。spec 包含title必填、可选subtitle/summary以及一个或多个sectionsrequired: [title, sections]且additionalProperties: false严格禁止未知属性。每个 section 可包含以下组件组件含义关键字段与取值cards紧凑的发现或概念卡title必填、body、meta[]、tonetable列 字符串行columns≥1、rows每行字符串数组risks带严重级别的风险项title、body、severitylow/medium/high/criticalfiles路径、说明与变更状态path必填、detail、statusadded/modified/deleted/reviewed/plannedsteps有序工作或时间线项title必填、body、statusdone/current/next/blockedflow节点与有向边nodes[]idlabel可选detail/tone、edges[]from/to/可选labelcallouts备注、决策或警告body必填、可选title/toneevidence证据标签、值、可选来源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 classslide元素中提取幻灯片标题、短文本、项目符号、简单表格、代码块与 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 在渲染时把颜色烘焙进 SVGexplain 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.mdharness 无关的项目级配置 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-explainerAgent skill that generates rich HTML pages or slide decks for diagrams, diff reviews, plan audits, data tables, and project recaps项目地址https://gitcode.com/gh_mirrors/vi/visual-explainer点击查看免费下载相关推荐visual-explainer generate-slides 指南用 Agent 生成自包含 HTML 演示文稿与 PPTX 导出visual explainer generate slides 指南用 Agent 生成自包含 HTML 演示文稿与 PPTX 导出 核心导读 gene如何为 LocalAI 配置上下文压缩让长对话不超出模型上下文限制如何为 LocalAI 配置上下文压缩让长对话不超出模型上下文限制 在多轮聊天场景中对话历史会随着消息积累不断变长直到逼近模型配置的 context_svisual-explainer 自包含 HTML 图表 CSS 模式全解主题、布局、Mermaid 缩放与溢出防护实战指南visual explainer 自包含 HTML 图表 CSS 模式全解主题、布局、Mermaid 缩放与溢出防护实战指南 视觉解释页面的核心不在于画了多上一篇MLflow Mistral 集成指南用 mlflow.mistral.autolog() 自动追踪 Mistral AI 调用下一篇Composio TypeScript SDK AuthConfigs API 完全指南认证配置的查询、创建与全生命周期管理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考