kakarot-visual-explainer

Kakarot Visual Explainer：把复杂解释做成一页可读的 HTML

这个 Skill 用于把复杂回答和技术文章选题整理成一页可读的视觉讲解页。模型负责事实、结构和文字，浏览器或 HTML 工具负责展示。页面服务于理解，不能替代事实核查、代码验证或用户确认。

它吸收了几个成熟视觉 Skill 的共同做法：首屏先给图和一句结论；默认生成离线单文件；交互必须回答一个具体问题；图形只保留承载核心关系的最少元素；渲染后必须在浏览器中检查实际页面。

什么时候生成页面

满足任一条件时生成页面：

• 有三个以上相互关联的概念，需要同时看到关系。
• 有流程、调用链、协议、状态迁移或多个参与者。
• 有三个以上维度的方案比较，或存在明确取舍。
• 有目录、模块、分类等层级结构，或有按时间展开的阶段。
• 用户明确说“画图”“可视化”“用 HTML 讲”“做成网页”或“我没看懂”。

以下情况直接用普通文字：

• 一两句话就能准确回答的问题。
• 用户只要命令、补丁、代码或纯文字。
• 没有可靠数据支撑的图表。此时先说明缺少数据，不能用模型臆造数字。

执行流程

1. 先读完用户给出的文章、代码、数据或差异，再写一句结论。没有读完来源时，不先设计页面。
2. 列出页面要回答的三至八个子问题。每个子问题只对应一个面板，删除不影响结论的元素。
3. 选择最能表达信息关系的结构：流程用 Mermaid flowchart，消息往来用 sequenceDiagram，层级用缩进树，历史用时间线，多维比较用 Markdown 表格，关键判断用醒目的结论卡片。
4. 先检查事实、来源和范围。把“已验证”“来自用户材料”“推断”分开写。没有证据的数字改成定性描述或删掉。
5. 生成单文件 HTML。页面至少包含标题、首屏结论、主要图形、证据或过程、限制条件和来源。优先使用内联 CSS、JavaScript 与 SVG，避免外部 CDN、远程字体、运行时 fetch 和必须启动的服务。
6. 只有在交互能回答明确问题时才加入交互。例如点击节点显示对应证据、切换前后状态、调整一个参数后立即更新结果。静态默认状态必须完整表达结论，读者不能依赖点击才能看懂核心内容。
7. 打开页面或用浏览器预览，检查窄屏宽度、图中文字、长标题、链接、键盘焦点、颜色对比度和暗色背景。发现文字溢出、连线遮挡或结构不清时，先删减元素或改稿，再改样式。
8. 回复时只给核心结论和页面绝对路径。用户要求文章时，再附可直接粘贴到正文的文字版；不要把整份 HTML 贴回对话。

页面结构

推荐使用下面的顺序：

1. 结论卡片：回答用户最关心的问题，限定结论适用范围。
2. 关系图或流程图：展示对象、动作和方向。每条连线写清动作，不只写名词。
3. 关键证据：放原始数据、代码入口、来源链接或用户提供的事实。
4. 比较与取舍：用表格展示维度、适用条件和代价；状态列只使用明确的“支持、受限、未知”。
5. 边界与下一步：写明未验证项、失败条件和读者可以执行的下一步。

页面可以使用 Mermaid，但必须同时保留关键关系的文字说明。Mermaid 无法渲染时，读者仍能从文字和表格理解结论。

图形先于装饰。结构图、时间线和关系图通常只保留五至七个关键元素；超过这个数量时先拆分或改成分步视图。每个节点都要有来源或作用，不能只为了填满画布增加节点。渲染工具无法目视检查时，至少用浏览器截图或可访问性树检查实际输出，不能只凭源代码判断页面正确。

页面模式按任务选择：

• 讲解页：默认模式，适合概念、机制和文章内容，使用首屏图形加滚动正文。
• 评审页：适合 PR、计划、架构或事故复盘，增加“当前状态、目标状态、差异和风险”四块内容。
• 数据页：只有输入包含真实数据时使用图表或指标卡，并标注时间、单位和数据源。
• 演示页：只有用户明确要演示或幻灯片时使用分页和大字号，不能把默认讲解页强行改成演示文稿。

文字和视觉规则

• 页面语言跟随用户语言；中文页面使用 lang="zh-CN"。
• 每个面板只回答一个问题。把长段落拆成短段落或列表。
• 同一对象全文使用同一个名称。首次出现的陌生术语用一句话解释。
• 用具体动词写清模型、程序、工具和用户各自做什么。
• 颜色只表达一种语义：绿色表示已确认，黄色表示受限或待核验，红色表示错误或阻断。
• 文字和背景保持足够对比度。移动端单列显示，图表允许横向滚动。
• 不使用动画掩盖信息，不加入与当前问题无关的装饰、统计数字或营销文案。
• 默认把生成文件写入当前任务的 outputs/ 或用户指定目录。不要自行上传、发布或创建公开链接。