用途
Visual Explainer 是一个用于生成自包含 HTML 页面的技能，主要用途是将技术信息以可视化方式呈现。它适用于以下场景：解释系统架构、展示代码变更、说明执行流程、呈现计划与路线图、展示数据表格与对比。当用户要求生成图表、架构图、流程图、时间线、仪表板或数据表格时，可使用此技能。技能明确要求：加载此技能后，输出必须包含至少一个承载真实信息的主要视觉产物，不得仅用装饰性样式包裹文字，也不得回退到 ASCII 艺术。
主要能力
该技能支持多种可视化类型，包括：架构图、流程图、执行流、序列图、状态机、ER 图、依赖图、时间线、路线图、仪表板、KPI 面板、语义化 HTML 表格、走查条带、步骤器、前后对比布局等。对于报告、评审、复盘、审计或计划分析类页面，要求至少包含两种视觉形式：一种结构性视觉（如图表、流程、架构图、时间线或依赖视图）和一种证据性视觉（如表格、KPI 仪表板、对比面板或紧凑的证据展示）。
技能还提倡主动表格渲染：当需要在终端中以 ASCII 表格呈现数据时（比较、审计、功能矩阵、状态报告等），若表格有 4 行以上或 3 列以上，应自动生成 HTML 页面并在浏览器中打开，同时告知用户文件路径。
使用方式
工作流程分为四步：思考、结构化、风格化、交付。
思考阶段：确定目标受众、图表类型和美学风格。美学风格包括单色终端、编辑风、蓝图、霓虹仪表板、纸墨、手绘/草图、IDE 风格、数据密集、渐变网格等，每次应变换选择。
结构化阶段：根据图表类型读取对应参考模板。流程图、序列图、ER、状态机、思维导图使用 Mermaid 模板；数据表格使用 data-table.html；交互式走查使用 walkthrough.html；仪表板使用 dashboard.html；时间线使用 timeline.html；文本密集型架构图使用 architecture.html。选择渲染方式时，执行流/代码流优先使用 Excalidraw 管道，其他 Mermaid 图表类型直接使用 Mermaid，架构图使用 CSS Grid 卡片加流程箭头，数据表格使用 HTML <table> 元素，走查使用原生 JS 步骤器，时间线使用 CSS，仪表板使用 CSS Grid 加内联 SVG。
风格化阶段：应用排版、配色、表面深度、链接样式、动画等原则。排版推荐 5 种字体配对：DM Sans + Fira Code、Instrument Serif + JetBrains Mono、IBM Plex Sans + IBM Plex Mono、Bricolage Grotesque + Fragment Mono、Plus Jakarta Sans + Azeret Mono。禁止使用 Roboto、Arial、Helvetica 作为通用主正文字体。配色使用 CSS 自定义属性，定义 --bg、--surface、--border、--text、--text-dim 和 3-5 个强调色，支持明暗两种主题。禁止使用特定颜色组合和效果，如 AI 紫色、青色、洋红色，以及卡片发光阴影、表情符号作为节标题、渐变文字标题等。文字质量方面，禁止使用特定词汇（delve、crucial、pivotal 等）、促销语言、填充短语和对比否定。
交付阶段：默认输出单个自包含 HTML 文件，写入 ~/.agent/diagrams/ 目录，使用描述性文件名。在浏览器中打开（macOS 使用 open 命令，Linux 使用 xdg-open 命令），并告知用户文件路径。在聊天回复中说明包含的视觉元素。
适用场景
该技能适用于开发者理解系统、产品经理查看全局、团队评审提案等场景。具体包括：架构与系统图、执行流与代码流、流程图、序列图、ER 图、状态机、思维导图、数据流图、数据表格与对比、审计、仪表板与 KPI 总结、时间线与路线图、走查与教程、报告与评审等。
限制
技能要求输出必须包含可视化元素，纯文字段落不满足要求。对于报告类页面，至少需要两种视觉形式。部分 Mermaid 图表类型（如 stateDiagram-v2）的标签解析有严格限制，特殊字符可能导致解析失败。AI 生成插图需依赖 surf-cli 工具，不可用时跳过。该技能未提供收费、价格、平台等商业信息。