AI Agent技能visual-explainer：将技术信息自动转化为可视化HTML页面

1. 项目概述：一个为AI Agent设计的视觉化解释器技能

如果你和我一样，经常需要向同事、客户或者自己解释一个复杂的系统架构、代码变更计划，或者梳理一份冗长的数据对比表，你肯定知道那种感觉：在终端里用ASCII字符画图，或者用Markdown表格，不仅费时费力，而且信息密度和可读性都差强人意。接收方往往需要花费额外的精力去“解码”你的图表，沟通效率大打折扣。

最近我在为我的AI助手（Agent）寻找一种能“所见即所得”地生成技术图表和文档的方法时，遇到了一个名为visual-explainer的OpenClaw AI Agent技能。它彻底改变了我的工作流。简单来说，这是一个专为AI Agent设计的技能，其核心功能是：将任何需要视觉化解释的技术概念——无论是系统架构、代码差异、实施计划还是数据表格——自动生成为一个美观、独立、可直接在浏览器中打开的HTML页面。

想象一下，当你向你的AI助手描述一个微服务架构，或者让它分析一次Git提交的代码差异时，它不再给你一堆难以阅读的纯文本或简陋的ASCII图，而是直接生成一个包含精美图表、清晰布局、完整交互（如缩放、导航）的网页。这个网页是自包含的（所有CSS、JavaScript都内联其中），你可以直接保存、分享，甚至一键部署到公网。这正是visual-explainer所做的事情。它本质上是一个高度结构化、设计驱动的HTML生成引擎，封装成了AI Agent可以调用的“技能”。

这个技能特别适合开发者、技术负责人、项目经理以及任何需要频繁进行技术沟通和文档化的人。它解决的痛点非常明确：将结构化的技术信息，从枯燥的文本形态，转化为具有视觉层次和叙事逻辑的“可读物”，从而极大地提升理解效率和沟通体验。接下来，我将深入拆解它的设计哲学、核心工作流、实现细节，并分享我在实际使用中积累的经验和避坑指南。

2. 核心设计哲学与工作流拆解

visual-explainer不是一个简单的模板填充工具。它的背后有一套非常清晰且强硬的设计哲学，旨在对抗AI生成内容中常见的“敷衍感”和“同质化”。理解这套哲学，是高效使用它的关键。

2.1 主动式渲染与“零ASCII”原则

技能的第一条核心原则是“主动式渲染”。传统上，AI Agent在遇到表格或结构化数据时，默认会输出终端友好的ASCII表格。visual-explainer改变了这一默认行为：任何超过4行或3列的表格数据，都应被自动渲染为HTML页面，而不是ASCII艺术。你不需要额外请求，Agent会主动执行这个转换。

这背后的逻辑是，浏览器是一个远比终端强大的渲染引擎。HTML表格支持粘性表头、行悬停高亮、响应式滚动、单元格内代码高亮等特性，这些都是ASCII表格无法提供的。当数据量稍大时，一个HTML页面的信息呈现效率和美观度是碾压性的。因此，技能要求开发者“永远不要回退到ASCII艺术”，将生成可视化页面作为首选和默认的输出方式。

2.2 设计驱动，而非样式堆砌

第二个核心原则是“设计意图先行”。技能文档中反复强调要避免“AI敷衍式设计”，即那种千篇一律的“深色主题+蓝色高光+Inter字体”的组合。它要求每一次生成都必须有明确的美学方向和内容类型适配。

在动笔写一行HTML之前，你必须思考并决定：

1. 受众是谁？是深入细节的开发者，还是关注大局的产品经理？这决定了信息密度和视觉复杂度。
2. 内容类型是什么？是架构图、流程图、序列图、数据表，还是演示文稿？每种类型都有其最合适的渲染引擎（Mermaid.js, CSS Grid, 原生<table>等）。
3. 美学风格是什么？技能提供了一系列预设的、有约束的美学方向，如：
   • 蓝图风格：技术绘图感，深石板蓝/蓝色调，单色标签，精确边框。适合严谨的技术文档。
   • 编辑风格：衬线字体标题，大量留白，大地色或深海军蓝+金色点缀。适合报告、文章。
   • 纸墨风格：暖米色背景，陶土/鼠尾草绿点缀，非正式感。适合头脑风暴、计划草案。
   • 单色终端风格：绿/琥珀色于近黑色背景，复古CRT光晕可选。怀旧或极简风格。

选择一种风格并贯彻到底，是保证输出独特性和专业感的关键。技能禁止使用那些缺乏设计思考的“网红”配色，比如千篇一律的蓝紫色渐变、霓虹灯式的青粉色组合，这些被其称为“AI敷衍信号”。

2.3 标准化工作流：思考、结构、样式、交付

技能将生成过程规范化为一个四步工作流，确保输出质量的一致性。

第一步：思考（5秒钟）这不是让你长时间纠结，而是快速做出上文提到的三个关键决策（受众、类型、风格）。查阅参考文档（如./templates/和./references/下的文件）来获取灵感，但不要死记硬背。每次生成前重新阅读相关模板，有助于吸收其中的设计模式。

第二步：结构根据内容类型选择正确的渲染方法。这是技术实现的核心决策点。visual-explainer强烈推荐使用Mermaid.js来处理大多数图表类型（流程图、序列图、类图、思维导图等），因为它能自动处理节点布局和连线路由，这是纯CSS难以完美实现的。对于文本内容丰富的架构概述，则使用CSS Grid + 卡片布局，以便容纳更丰富的描述和代码片段。对于纯粹的数据表格，则使用语义化的HTML<table>元素。

这里有一个非常重要的避坑经验：对于复杂的架构图（超过15个元素），不要试图把所有东西塞进一个Mermaid图里，否则会变得极小且难以阅读。应该采用“混合模式”：用一个简化的Mermaid图展示顶层模块关系，然后用详细的CSS卡片网格来展开每个模块的内部细节。这样既保留了拓扑可视性，又保证了内容的可读性。

第三步：样式这是将设计意图落地的环节。包括：

• 字体配对：禁止使用默认的Inter/Roboto/Arial。必须从预设的优秀配对中选择，如 DM Sans + Fira Code（技术感）、Instrument Serif + JetBrains Mono（编辑感）。
• 色彩体系：使用CSS自定义属性定义完整的调色板，至少包括背景、表面、边框、文本及3-5个强调色。强调色应有完整和暗淡两个变体。色彩要有语义命名（如--pipeline-step），而非--blue-3。
• 视觉层次：通过表面深度（阴影、背景色微差）、动画（渐入、悬停反馈）来引导视线和标示重要性。动画必须克制且有目的，禁止无意义的发光、脉冲效果。

第四步：交付生成的HTML文件默认保存在~/.agent/diagrams/目录下，并使用描述性文件名。技能会自动在默认浏览器中打开该文件，并告知用户文件路径，方便后续查找和分享。

3. 关键技术实现与深度解析

理解了设计哲学后，我们深入到具体的技术实现层面。visual-explainer的成功，很大程度上依赖于对几个关键技术的精妙运用和严格规范。

3.1 Mermaid.js的进阶使用与深度定制

Mermaid是生成各种图表的核心引擎，但技能对其的使用远不止于调用API那么简单。

3.1.1 主题与样式覆盖技能禁止使用Mermaid的默认主题。必须使用theme: 'base'并配合自定义的themeVariables，使图表的颜色与整个页面的调色板完美融合。例如，你需要定义节点边框色、背景色、连线颜色等，使其与你的“蓝图”或“编辑”风格一致。

mermaid.initialize({ startOnLoad: true, theme: 'base', themeVariables: { primaryColor: '#1e3a5f', // 深蓝 primaryBorderColor: '#2d4a7a', primaryTextColor: '#f8fafc', lineColor: '#94a3b8', fontFamily: '"Fira Code", monospace' } });

更重要的是，技能要求通过CSS覆盖Mermaid内部的SVG类名，以实现像素级的控制。例如，你可以精确调整特定类型节点的样式。

3.1.2 容器与交互封装这是最容易出错的地方。技能严禁直接使用裸露的<pre class="mermaid">标签。虽然它能渲染，但缺乏必要的交互控件。必须使用从templates/mermaid-flowchart.html中复制的完整diagram-shell模式。

这个模式包含一个完整的HTML结构套件和约200行的JavaScript模块，提供以下关键功能：

• 缩放控件：固定的 +、-、重置、全屏按钮。
• 鼠标交互：Ctrl/Cmd+滚轮缩放，拖拽画布平移。
• 点击展开：点击图表区域（或全屏按钮）会在新标签页中打开一个放大的视图。

这个封装确保了无论图表多复杂，用户都能舒适地浏览。忽略这一步，生成的图表将难以使用。

3.1.3 布局方向与标签处理对于复杂图表，优先使用flowchart TD（自上而下）而非flowchart LR（从左到右）。因为LR布局在节点较多时会水平铺开，导致标签变得难以阅读。LR仅适用于简单的3-4个节点的线性流程。

在流程图的节点标签中换行，必须使用HTML的<br/>标签，绝不能使用\n。因为Mermaid会将\n原样输出为文本。

3.1.4 CSS类名冲突规避一个极其重要的细节：永远不要在页面级定义.node这个CSS类。Mermaid.js 在内部使用.node类来定位SVG中的<g>元素（用于变换定位）。如果你在页面CSS中定义了.node的样式（比如加了hover效果或box-shadow），这些样式会泄漏到图表中，严重破坏布局。正确的做法是使用命名空间化的类名，如.ve-card来定义你的卡片组件。要修改Mermaid节点的样式，必须将样式规则限定在.mermaid选择器下，例如.mermaid .node rect { ... }。

3.2 响应式布局与溢出保护

生成的HTML页面需要在各种尺寸的屏幕上都能良好显示。技能对此有严格的质量检查。

3.2.1 通用布局策略

• CSS Grid：用于卡片的宏观布局，非常灵活。
• Flexbox：用于组件内的微观对齐。
• 表格：使用原生<table>并配合overflow-x: auto的包装器，以处理超宽表格。

3.2.2 关键的溢出保护规则技能文档中专门有一个“溢出保护”章节，指出了几个常见陷阱：

• min-width: 0：对于Grid和Flex容器内的子项，必须设置min-width: 0或overflow: hidden，以防止内容（如长单词、URL）撑破容器。
• overflow-wrap: break-word：对于并排面板中的文本，需要此属性确保长字符串能断行。
• 列表项布局：绝对不要对<li>使用display: flex来对齐标记字符和内容。这会创建匿名的Flex项目，导致包含多个行内<code>标签的行发生溢出。正确的做法是使用绝对定位来放置标记点。

3.3 动态内容与可选增强

3.3.1 AI生成插图（可选）如果系统安装了surf-cli（一个通过Gemini等模型生成图像的命令行工具），技能可以动态生成配图。这适用于那些Mermaid难以表达的抽象概念、物理基础设施或需要艺术化渲染的教育性图表。

工作流程是：用surf生成图片到临时文件，用base64编码，然后以数据URI的形式嵌入HTML。这样保证了页面的自包含性。生成时，提示词需要与页面的整体美学风格（配色、类型）相匹配。

3.3.2 图表与动画对于仪表盘中的图表，推荐使用Chart.js（通过CDN引入）。对于复杂的多元素交互动画，可以使用anime.js。但动画必须遵循“减少运动偏好”（prefers-reduced-motion）的设置，并且只用于有意义的场景：页面加载时的错落渐入、悬停反馈、用户触发的交互。

4. 不同内容类型的实现策略与模板应用

visual-explainer针对不同的内容类型，提供了高度优化的实现策略和参考模板。生搬硬套会导致输出效果不佳。

4.1 架构图与系统图：三种复杂度，三种策略

1. 简单拓扑（<10个元素）：直接使用Mermaid的graph TD。自动布局足够清晰。
2. 文本密集型概述（<15个元素）：使用CSS Grid + 卡片。参考./templates/architecture.html。每个模块或组件是一个卡片，包含描述、代码片段、工具列表等丰富内容。卡片之间用垂直的箭头SVG连接。这种方式在信息承载量上远超Mermaid节点。
3. 复杂架构（15+元素）：使用混合模式。顶部是一个简化的Mermaid图（5-8个节点），展示核心模块及其关系。下方为每个模块展开一个详细的CSS Grid卡片区域，列出函数、接口等细节。这是平衡全局视野与局部细节的最佳实践。

4.2 数据表格：超越ASCII的艺术

当需要呈现审计结果、功能对比、状态报告时，必须使用原生<table>。

• 粘性表头：通过position: sticky实现，滚动时标题栏始终可见。
• 斑马纹：使用tr:nth-child(even)添加轻微的背景色差异，提高长表格的可读性。
• 状态指示器：使用带颜色的圆点或徽章（<span>），绝对不要用表情符号，以保证专业性。
• 单元格内容：长文本自然换行；技术引用用<code>包裹；次要说明用<small>并调低颜色对比度；数字列右对齐并使用等宽字体（tabular-nums）。

4.3 幻灯片模式：一种不同的叙事媒介

当用户通过/generate-slides命令或--slides标志明确请求时，技能会进入幻灯片模式。这不是简单地将滚动页面切分成几屏，而是一种完全不同的内容组织和叙事方式。

核心区别：

• 每屏即一页：每张幻灯片高度严格为100dvh，禁止内部滚动。
• 字体更大：字号是普通页面的2-3倍，追求在投影仪上的清晰度。
• 叙事弧线：内容需要被重新组织成“冲击力→背景→深入探讨→解决方案”的演讲逻辑。
• 视觉优先：更多地使用全出血图片、背景渐变、装饰性SVG元素和小型Mermaid图。
• 构图变化：连续幻灯片必须采用不同的空间构图（居中、左重、右重、分割等），避免单调。

在生成幻灯片前，必须完整阅读./references/slide-patterns.md，并遵循其中的“从源文档规划幻灯片”流程，确保不遗漏任何重要内容。幻灯片数量多不是问题，内容缺失才是失败。

5. 实操心得、常见问题与避坑指南

经过一段时间的深度使用，我积累了一些宝贵的实操经验和常见问题的解决方案。

5.1 字体与色彩：摆脱“AI味”的关键

• 心得：字体配对是确立风格最快的方式。尝试使用一些不那么“系统默认”的字体，比如Bricolage Grotesque或Plus Jakarta Sans，能立刻让页面显得与众不同。色彩上，放弃那些Hex颜色代码看起来就很“Tailwind默认”的紫色 (#8b5cf6)、紫红色 (#d946ef)。尝试一些有故事感的组合，如陶土红(#c2410c)配鼠尾草绿(#65a30d)，或深蓝(#1e3a5f)配金色(#d4a73a)，质感马上提升。
• 问题：在深色/浅色模式切换时，颜色看起来不协调或对比度不足。
• 解决：定义色彩变量时，一定要在:root和@media (prefers-color-scheme: ...)中分别定义完整的两套值。对于以深色为主的主题，在:root定义深色值，在媒体查询中覆盖为浅色值。务必在两个模式下都进行测试。

5.2 Mermaid图表：大小与交互的平衡

• 心得：对于10-12个节点的图表，可以通过增加themeVariables中的fontSize(如18-20px) 和设置初始缩放(INITIAL_ZOOM为1.5-1.6)来改善可读性。但超过15个节点，请果断采用“混合模式”。
• 问题：Mermaid图表无法点击拖拽或缩放。
• 解决：百分之百确认你使用了完整的diagram-shell模式，而不是裸的<pre class="mermaid">。检查生成的HTML中是否包含了.zoom-controls容器和相应的JavaScript函数（如zoomIn(),panStart()等）。
• 问题：使用stateDiagram-v2时，包含冒号、括号的转换标签导致解析失败。
• 解决：stateDiagram-v2的标签语法非常严格。如果标签需要复杂内容，改用flowchart TD来模拟状态机，用带引号的边标签（如A -->|"cancel()"| B）和<br/>来处理复杂文本。

5.3 内容组织与信息过载

• 心得：不要试图在一个页面上塞进所有东西。对于辅助性或参考性内容（如完整的文件列表、详细的决策日志），使用<details>和<summary>标签将其折叠起来。这保持了主流程的整洁，同时让有需要的读者可以展开查看。
• 问题：生成的页面在手机上看布局错乱，内容溢出屏幕。
• 解决：这是“质量检查”中“无溢出”规则的体现。务必为所有Flex/Grid容器的子项设置min-width: 0。使用浏览器开发者工具的设备模拟器进行测试，并确保所有容器都有overflow: hidden或overflow-x: auto作为安全阀。

5.4 部署与分享

• 心得：/share命令（背后调用share.sh脚本）极其方便。它利用vercel-deploy技能，无需任何认证即可将HTML文件瞬间部署到一个可公开访问的临时URL，非常适合快速分享评审。
• 注意：这些部署是公开的，且默认保留30天。如果涉及敏感信息，请勿使用此功能。对于内部或敏感图表，更适合通过文件分享或内网部署。

5.5 最后的检查清单

在交付最终成果前，我养成了执行以下检查的习惯：

1. 眯眼测试：眯起眼睛看页面。是否还能分辨出主要的视觉层次和区块？如果一片模糊，说明对比度和层次感不足。
2. 替换测试：想象把页面的字体和颜色换成一套最普通的深色主题。这个页面还会显得独特吗？如果变得平庸，说明当前的设计风格没有起到决定性作用。
3. 双主题测试：在操作系统中切换明暗模式，确保两种模式下页面都美观且可用。
4. 信息完整性：这个图表是否真正回答了用户最初的问题？有没有遗漏关键部分？美观但不完整是失败。
5. 控制台检查：在浏览器中打开生成的HTML文件，打开开发者工具控制台，确保没有JavaScript错误或资源加载失败。

visual-explainer技能将一个好的技术沟通者应有的思考过程——理解受众、选择形式、注重设计、确保可用——固化成了AI Agent可执行的指令。它不仅仅是一个工具，更是一套关于如何有效进行技术可视化的最佳实践框架。掌握它，意味着你的AI助手能产出堪比资深技术写作者和设计师协作完成的作品，这将极大地提升你技术文档的输出质量和沟通效率。