visualization

name	visualization
description	可视化生成技能。用户描述一个主题或提供数据，将其转换为交互式可视化网页，自动启动本地服务器并打开浏览器展示。触发场景：(1) 用户要求将人物关系、历史事件、数据报表、物理原理、地图路线、知识概念等内容可视化；(2) 用户说"帮我做一个可视化"、"用图表展示"、"生成可视化页面"；(3) 用户提供数据文件并希望生成图表看板。

可视化生成技能

子 Agent 架构（必须遵守）

可视化任务复杂度高、上下文占用大。主 agent 只负责协调，禁止自己执行具体实现任务，所有实质性工作由子 agent 承担：

主 agent
├── 理解需求、确认场景、设计方案（自己执行）
├── 数据准备 sub-agent    ← 负责搜索采集、整理、输出 data.json
└── 可视化实现 sub-agent  ← 负责编写代码、创建文件、启动服务器

触发时机：

• 用户确认场景设计方案后，立即同时启动两个子 agent（如数据已确定可先启动数据 agent）
• 主 agent 等待两个子 agent 完成后汇总结果告知用户

传递给子 agent 的上下文必须包含：

• 工作目录绝对路径
• 场景类型 + 子类型（如：人物关系 / 力导图）
• 场景文件路径（SCENE.md 的绝对路径，让子 agent 自行读取）
• 数据 agent 的 data.json 输出路径（传递给实现 agent）
• 布局与配色设计方案

---

SOP

第一步：理解需求（→ 与用户确认）

深入理解用户想可视化的内容：

• 核心主题是什么？
• 是否有现成数据？（没有则由数据 agent 自动搜索采集）
• 目标受众和使用场景？

输出：用 1-3 句话复述需求理解，请用户确认后再继续。

第二步：判断可视化场景（→ 与用户确认）

根据需求自动匹配最合适的场景。优先自动识别，仅当无法确定时才列出候选场景让用户选择。

场景路由表：

场景	关键词	场景文件路径
人物关系可视化	人物、关系、图谱、家族、力导图、树图	scenes/character-relationship/SCENE.md
图表数据可视化	数据、报表、Excel、图表、大屏、看板	scenes/chart-dashboard/SCENE.md
事件时间线可视化	历史、时间线、事件、年份、朝代	scenes/event-timeline/SCENE.md
物理模拟可视化	原理、模拟、发动机、3D、物理	scenes/physics-simulation/SCENE.md
地图演进可视化	地图、路线、路径、地理、行军	scenes/map-evolution/SCENE.md
知识点教学可视化	概念、教学、演示、原理、动画	scenes/knowledge-teaching/SCENE.md
化学分子可视化	合成路线、分子结构、反应机理、晶体结构、蛋白质、SMILES、PDB、有机合成、化合物	scenes/chemistry/SCENE.md

确认场景后，立即读取对应的 SCENE.md，获取场景专属的技术栈、数据格式和实现策略。

输出：说明判断为哪个场景及理由，请用户确认。

第三步：组件设计与内容编排

结合 SCENE.md 中的场景规范进行设计（此步骤主 agent 自行完成）：

• 确定子类型（如力导图 vs 折叠树）
• 规划布局：标题区、主视图区、说明区、交互控件
• 确定配色方案和交互方式
• 确定工作目录路径（格式见下方约定）

方案确定后，启动子 agents 并行执行第四步。

第四步：并行启动子 Agents

数据准备 Agent

职责：采集数据 → 按规范整理 → 输出 data.json

任务要求：

1. 读取场景 SCENE.md，了解该场景的数据格式规范
2. 如用户未提供数据，使用 WebSearch 工具或 agent-browser skill 搜索采集原始数据
3. 将采集到的数据按 SCENE.md 中定义的 JSON 格式整理
4. 将整理好的数据写入工作目录下的 data.json

数据采集策略（按优先级）：

• 优先使用内置 WebSearch 工具快速搜索
• 内容较多或需要抓取页面结构时，改用 agent-browser skill
• 如搜索结果不完整，基于已有知识补充，并在数据中标注 "_note": "部分数据基于常识推断"

化学合成路线场景专项检查： 整理完 compounds 后，必须遍历所有 reactions 的 from/to 字段，确认每一个引用的 id 都已在 compounds 中有对应条目且包含 smiles 字段。缺失的中间体需主动搜索补全，不能留空。

数据完整性自检（写入前必做）： 完成数据整理后，在写入 data.json 之前，按以下清单自检：

• JSON 格式合法（用 python3 -c "import json; json.load(open('data.json'))" 验证）
• 所有必填字段已填写（无意外的 null 或空字符串）
• 节点/条目间的 id 引用完整（如 reactions 引用的 compounds id 均存在）
• 数据量合理（节点数、事件数等与需求描述一致，无明显遗漏）
• 推断/估算的数据已标注 "_note" 字段说明来源

可视化实现 Agent

职责：等待 data.json 就绪 → 编写 HTML + JS → 启动服务器 → 冒烟测试

任务要求：

1. 读取场景 SCENE.md，了解技术栈和实现要点（优先阅读「⚠️ 已知坑点」部分，避免重复踩坑）
2. 等待并读取 data.json（数据 agent 产出）
3. 从零设计并编写 index.html（不直接使用模板，模板仅供参考格式）
4. 启动开发服务器
5. 冒烟测试：用 agent-browser skill 打开页面截图，检查以下内容并修复发现的问题：
   • 页面是否正常加载（无白屏、无崩溃）
   • 浏览器控制台是否有报错（重点看 TypeError、CDN 加载失败）
   • 核心可视化元素是否渲染成功（节点/图表/3D模型）
   • 如有问题，直接在本 agent 内修复后重新截图确认，直到通过为止

---

工作目录约定

在用户当前工作目录下创建子目录：

{当前目录}/{主题简称}-visualization/
├── index.html      # 主页面（通过 fetch 加载数据）
├── data.json       # 可视化数据（由数据 agent 产出，不内联到 HTML）
└── ...             # 其他资源（如有）

目录名使用英文或拼音，简短清晰（如 buniannian-relationship/、sales-dashboard/）。

代码规范

• 数据与视图分离：数据存放在独立 data.json，页面通过 fetch('./data.json') 异步加载，禁止将大量数据内联到 HTML
• 库加载：通过 CDN 引入，优先使用 jsDelivr 或 unpkg
• 中文注释：代码注释使用中文
• 自适应布局：页面适配常见屏幕宽度

启动服务器

可视化实现 agent 完成代码后，使用 skill 内置的 Node.js 开发服务器：

node ~/.claude/skills/visualization/shared/server.js 3000 {工作目录绝对路径}

服务器启动后自动打开浏览器。

SCENE.md 维护原则

当某个场景出现以下情况时，必须立即更新对应的 SCENE.md，将经验永久沉淀：

情况	更新内容
发现某个库的 API 用法与 SCENE.md 中的示例不符	修正代码示例，在「⚠️ 已知坑点」表格中记录
某个 CDN 地址失效或版本有问题	更新为可用地址/版本
数据格式需要新增字段	在数据格式规范中补充
发现更优的实现方案	更新实现要点章节

原则：踩过的坑必须记录，让规范比代码更可靠。