【免费下载链接】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点击查看免费下载Quick 模式Quick mode是 visual-explainer 技能内置的一种轻量渲染路径Agent 不再直接输出完整 HTML而是先产出一份紧凑的 JSON 规格spec由本地渲染器render.mjs负责校验并生成单一、自包含的 HTML 文档。本文以 plugins/visual-explainer/quick/README.md 为主干结合 schema.json、render.mjs、base.css 与 extension.ts 等源码完整讲解 Quick 模式的触发方式、Spec 数据结构、校验规则、渲染管线与失败回退策略。读完本文你将掌握如何为/generate-web-diagram、/diff-review、/plan-review、/project-recap四个命令的--quick变体编写合法 Spec并在 Pi、MCP 与纯 Node 三种运行环境下完成渲染。Quick 模式的定位与设计动机在完整模式full mode下Agent 需要把大量 HTML 与 CSS 直接写入响应再由渲染器落盘。Quick 模式把这段重复的 HTML/CSS 工作从 Agent 响应中剥离Agent 只输出一份紧凑的 JSON Specrender.mjs负责校验它并据此生成一份完整、自包含的 HTML 文档含内嵌 CSS、内联 favicon无需外部依赖。这种设计带来的直接收益是 token 与响应长度的显著下降同时把“页面长什么样”收敛为“数据是什么样”从而让视觉输出更可预期、更易校验。适用场景显式 opt-inQuick 模式是自愿开启的默认的 Agent 行为始终是全量 HTML 生成。它只允许出现在以下四个命令的--quick变体中四个命令定义见 commands/generate-web-diagram.md、commands/diff-review.md、commands/plan-review.md、commands/project-recap.md/generate-web-diagram --quick/diff-review --quick/plan-review --quick/project-recap --quick在 SKILL.md 的 Quick mode 一节中进一步明确了边界如果用户请求的设计无法用 Schema 表达、校验失败或渲染报错必须回退到完整 HTML 流程同时 Quick 模式不适用于幻灯片slides、fact-check、视觉计划visual plans、PPTX、主题themes以及更新类updates场景。也就是说Quick 模式是为“结构规整、内容可枚举”的页面评审、审计、架构说明、项目复盘设计的而不是为“自由视觉编排”设计的。快速上手两种运行方式Quick 模式的执行入口取决于运行环境。README 明确给出了两种路径Pi 环境调用既有工具其他 harness 直接运行本地脚本。方式一Pi 环境——调用visual_explainer工具在 Pi 中Agent 调用既有的visual_explainer工具action设为render_quick并传入filename与spec。README 给出的最小可运行示例是一个认证流程图{ 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 }] } } ] } }从 extension.ts 的源码可以看到render_quick的完整执行链路参数定义visualExplainerParametersL62-L116action枚举为prepare/render/render_quickspec的类型为 object描述为“遵循 quick/schema.json 的紧凑 JSON spec”open默认trueviewer枚举为browser/glimpse/auto默认browser。执行函数renderQuickVisualExplanationL380-L386校验spec必须存在随后调用renderQuickSpec(params.spec)得到完整 HTML再交由writeRenderedHtml落盘。writeRenderedHtmlL318-L364先通过outputFilenameL139-L148规范化文件名——只接受 basename不允许/、\、..、控制字符缺省补.html后缀随后校验 HTML 是完整文档assertHtmlDocument写入~/.agent/diagrams/目录L331并对目录与文件做符号链接防护L333-L337最后按open/viewer参数决定是否用浏览器或 Glimpse 打开。因此Pi 调用时只需关心三个参数action: render_quick、描述性filename无需带.html和符合 Schema 的spec。方式二其他 harness——直接运行render.mjs非 Pi 环境如 Claude Code 插件、Codex、opencode 等下先把 Spec 保存为 JSON 文件然后运行quick目录相对于已安装的 visual-explainer 技能目录即仓库中的 plugins/visual-explainer/quick/render.mjsnode ./quick/render.mjs spec.json ~/.agent/diagrams/auth-flow-quick.html命令行只有两个位置参数spec.json与output.html。从 render.mjs 的入口main()L194-L209可见其行为参数缺失时抛出Usage: node render.mjs spec.json output.html读取并JSON.parseSpec调用renderQuickSpec(spec)生成 HTMLmkdir递归创建输出目录L199写入文件L200并向 stdout 打印输出路径L201任何异常解析失败、校验失败、IO 错误都会写入 stderr 并以退出码 1 结束。渲染成功后用所在环境的浏览器命令打开结果即可。如果渲染器以错误退出请继续走正常的完整 HTML 工作流——这是 README 明确给出的回退策略。两种方式的差异小结维度Pirender_quick其他 harnessrender.mjsSpec 传递方式工具参数spec对象本地 JSON 文件输出位置~/.agent/diagrams/filename.html命令行指定的任意输出路径打开页面支持open/viewerbrowser/glimpse/auto需要自行调用浏览器命令失败处理抛错回退完整 HTML 流程stderr 报错、退出码 1回退完整 HTML 流程深入解析 Quick Spec Schemaquick/schema.json 是 Quick 模式的权威 JSON Schemadraft 2020-12。Spec 的结构如下顶层必须包含title非空字符串与sections至少 1 个 section 的数组可选顶层字段subtitle、summary顶层禁止出现其他任何属性additionalProperties: false。顶层字段字段类型必填说明titlestring是页面主标题minLength: 1会成为h1与titlesubtitlestring否副标题渲染为header中的装饰性小标题summarystring否摘要渲染为header中的导读段落sectionsarray是至少一项每项是一个 section 对象Section 的构成每个 section 必须含title非空可选subtitle、summary、tone并至少包含以下八种内容组件中的一种每种组件数组的minItems均为 1组件用途关键字段cards紧凑的发现项或概念卡片title必填、body、meta字符串数组渲染为 chip 标签、tonetable列与字符串行组成的表格columns至少 1 列、rows行内元素必须全为字符串且列数必须与 columns 相等、captionrisks带严重级别的风险项title、body、severity三者必填files文件路径、说明与变更状态path必填、detail、statussteps有序的工作或时间线条目title必填、body、statusflow节点与有向边的流程图nodes至少 1 个、edgescallouts注释、决策或警告body必填、title、toneevidence一条标签-值-来源的证据label、value必填、source可选枚举值一览Schema 中出现的全部受控枚举如下与 render.mjs L7-L10 中定义的 Set 完全一致字段合法值tonesection / card / flowNode / calloutneutral、accent、positive、warning、danger、inforisk.severitylow、medium、high、criticalfile.statusadded、modified、deleted、reviewed、plannedstep.statusdone、current、next、blocked各组件必填与可选字段明细card必填title可选bodystring、metastring 数组、tone。table必填columns非空 string 数组与rows元素为 string 数组的数组可选caption。校验规则是每一行元素的个数必须等于列数否则视为非法见 render.mjs L94。risk必填title、body、severity无其他可选字段。file必填path可选detail、status。step必填title可选body、status。flow必填nodes至少 1 个与edges可空数组。每个 node 必填id与label可选detail、tone每个 edge 必填from与to可选label。from/to必须引用已存在的节点id否则校验失败见 render.mjs L130-L131。callout必填body可选title、tone。evidence必填label与value可选source。一个覆盖多种组件的综合示例{ title: API 变更评审, subtitle: diff-review --quick, summary: 针对本次合并请求的关键风险、文件改动与实施步骤汇总。, sections: [ { title: 风险清单, risks: [ { title: 鉴权接口破坏性变更, body: 旧 token 格式不再被接受。, severity: high }, { title: 测试覆盖缺口, body: 新增限流分支缺少单测。, severity: medium } ] }, { title: 文件改动, files: [ { path: src/auth/token.go, detail: 重写 token 校验逻辑, status: modified }, { path: src/auth/middleware.go, detail: 新增限流中间件, status: added } ] }, { title: 实施步骤, steps: [ { title: 合并 token 校验重构, body: 先合入基础重构。, status: current }, { title: 补充限流测试, body: 覆盖阈值边界。, status: next } ] }, { title: 关键证据, evidence: [ { label: 变更文件数, value: 12, source: git diff --stat }, { label: 新增测试, value: 8, source: go test -cover } ] } ] }渲染器内部实现校验、转义与渲染管线render.mjs 是 Quick 模式的唯一渲染实现同时被 Pi 扩展extension.ts L6 导入与 MCP 服务mcp/server.mjs L11 导入复用因此它的行为就是所有环境的共同事实标准。校验阶段validateQuickSpecL55-L148校验完全在内存中完成不依赖ajv等外部校验库而是用一组手写的check*辅助函数逐字段检查。它收集的全部错误一次性返回便于 Agent 或调用方看到完整问题清单。主要规则包括顶层只允许title、subtitle、summary、sectionsL58 的checkKeys会为任何未知属性推送path is not supported错误title必须是非空字符串sections必须是非空数组L59-L65每个 section 同样做白名单键检查L73title非空L74tone必须是六选一枚举L77checkTonecards、risks、files、steps、callouts、evidence都必须是非空对象数组checkObjectArrayL38-L53且各自只允许 Schema 白名单内的键table.rows的每个元素必须是字符串数组且长度必须等于columns长度L94flow.nodes至少 1 个、flow.edges可以是空数组但每个 edge 的from/to必须命中 nodes 的id集合L121-L132。HTML 转义escapeHtmlL150-L152所有 Agent 文本在进入 HTML 之前统一经过escapeHtml→amp;、→lt;、→gt;、→quot;、→#39;。这意味着任何 Agent 写入的文本都不可能注入标签或脚本这是 Quick 模式的一个内置安全属性README 中“所有 Agent 文本都经过 HTML 转义”的描述即源于此处。渲染管线renderQuickSpecL186-L192渲染函数先调用validateQuickSpec若错误列表非空立即抛出Quick spec validation failed: ...L188。随后读取同目录 base.css 的全部内容L189作为内嵌style将每个 section 渲染为section classsection>赞分享【免费下载链接】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 Quick 模式详解JSON Schema 驱动的快速可视化渲染方案visual explainer Quick 模式详解JSON Schema 驱动的快速可视化渲染方案 visual explainer 是一个让 AI Agvisual-explainer 技能完全指南让 Agent 生成自包含 HTML 可视化页面、图表与幻灯片visual explainer 技能完全指南让 Agent 生成自包含 HTML 可视化页面、图表与幻灯片 本指南围绕 visual explainer Avisual-explainer /diff-review 视觉化 Diff 审查指南把 git 变更渲染成自包含 HTML 审查报告visual explainer /diff review 视觉化 Diff 审查指南把 git 变更渲染成自包含 HTML 审查报告 /diff revie上一篇Blender 插件与工具完整指南如何按工作流从资产到交付挑对每一环下一篇PCL2启动器装不上Forge手把手带你把报错一个个排掉创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考