Claude Algo Visualize

交互式可视化页面生成技能

当用户要求生成网页、可视化、动画演示、知识点总结、教学页面、代码执行动画时，加载此技能。

> 完整参考实现：references/heap_overview.html（428 行的"堆"全景讲解页面）。它是对照本 skill 所有约定（CSS 骨架、叙事密度、大小顶堆并排 SVG、Push/Pop/建堆/堆排序双面板联动动画）写出的完整样板。遇到"PDF → 讲解页面"类型任务时，建议先用 Read 工具浏览这个参考文件作为对齐基准；其他类型也可以参考它的叙事节奏和 SVG 写法。

定位

生成完整的交互式 HTML 页面（单文件）。页面风格是"说人话的教学梳理"——有逻辑流、有叙事感、有图示、有交互。

适用场景包括但不限于：

• 用户提供 PDF/教材，要求生成知识点讲解页面
• 用户提供一个主题（如"队列的操作"），要求生成教学 + 动画页面
• 用户提供代码/算法，要求生成逐步执行动画
• 用户要求对比两个概念、演示某个过程、解释某个原理

---

铁律（违反任何一条 = 质量不合格）

铁律一：正文为主，彩色框为辅

页面内容的 80%+ 应该是 ` 段落和 / 标题。彩色 callout 框（.info、.warn、.good、.def、.formula`）只是偶尔穿插的旁白，整页加起来不超过 3-4 个。

参考 references/heap_overview.html（428 行，7 个章节）：0 个 .def，0 个 .formula，总共只有 5 个 .info + 2 个 .good + 4 个 .warn。定义、公式、性质全部用 ` + ` 写在正文里。

反面教材：连续出现 3 个以上 .def 框，或者把公式放进 .formula 框——这些会让页面变成一堆彩色方块的堆砌，不像教学页面。

铁律二：SVG 节点绝对不能重叠 + viewBox 必须留够空间

写 SVG 时（无论静态图还是 JS 动画），必须确保：

• 每个圆形节点的半径（通常 r=22~24）加上文字不会和相邻节点重叠
• 手算坐标时，相邻节点圆心距 ≥ 56px（2 × 半径 + 间隙）
• 父子节点之间的 y 轴间距 ≥ 60px（给连线和文字留空间）
• 如果空间不够，宁可增大 viewBox 的高度，也不能压缩节点间距
• 写完坐标后，在脑中画图验证：每个 (cx, cy) 周围 24px 半径内不能有其他圆心

viewBox 安全边距：viewBox 的宽高必须比所有内容的边界多出至少 20px。具体检查方法：

• 找出所有节点中最大的 (y + r) 值，再加上所有节点下方标注文字的高度（约 20px），viewBox 高度必须 ≥ 此值 + 10px
• 如果节点下方有 `` 标注（如编码、层号），viewBox 底部还要再留 10px
• 经验公式：viewBox 高度 = max(节点 y + r) + 40

铁律三：动画必须与代码联动

当页面涉及代码执行过程时，交互动画必须与代码展示联动。不能出现"动画是动画，代码是代码"的割裂情况。

具体要求：

• 动画的每个 step 必须标注当前正在执行代码的第几行
• 代码展示区用 .code-panel 容器包裹，每行代码用 ` 包裹，当前执行行加 .cl.on` 高亮
• 代码面板放在动画可视化区域的上方或左侧，形成"代码 + 可视化"的双面板布局
• 说明文字（.cap）应同时解释代码在做什么和数据结构如何变化
• 如果代码太长（超过 12 行），只展示与当前动画相关的核心片段，其余用 // ... 省略

铁律四：每个概念/步骤必须配 SVG 图示

页面中讲到任何可视化概念时，必须有对应的 SVG 图：

• 数据结构（树、图、队列、栈等）→ 画结构图
• 操作过程（插入、删除、排序步骤等）→ 画状态图或做动画
• 对比/比较 → 并排 SVG
• 算法执行 → 步骤动画

具体要求：

• 概念讲完 → 紧跟 SVG 图示 → 再接文字说明，这个节奏不能断
• 静态 SVG 用内联 HTML 写（不需要 JS），颜色用 CSS 变量
• 交互式动画只用来演示"多步骤过程"（如算法执行、构造过程），静态图用来展示"单个状态/概念"
• 整页的静态 SVG 数量应该 ≥ 交互式动画的数量

反面教材：一个概念讲解章节只有文字没有图——读者看着纯文字根本无法理解。

铁律五：有来源时跟着来源的教学脉络走，顺着来源的页面顺序梳理章节——它先讲什么就先写什么章节，它用什么例子就用什么例子。不要从结论倒推，不要"提炼要点后重新组织"。

如果没有提供来源（纯主题/算法请求），则按自然教学顺序组织：

1. 先讲"这是什么"（定义/背景）
2. 再讲"怎么工作"（原理/步骤，配图）
3. 然后讲"实际例子"（手动模拟，配动画）
4. 最后总结（核心要点、易错点）

---

输入类型与工作流

类型 A：PDF / 教材 → 知识点讲解页面

1. 读入 PDF，顺着 PDF 的页面顺序梳理章节
2. PDF 从哪个概念开始讲 → 第一个章节；接着讲什么 → 第二个章节
3. 有哪些图/例子 → 对应嵌入到相关章节
4. 最后有"知识回顾"/"考点" → 最后的总结章节
5. 章节编号用 `，页面开头用 .toc` 列出目录

类型 B：主题描述 → 教学 + 可视化页面

用户说"给我做个队列的动画"或"解释一下快排"之类。

1. 根据主题规划章节（按自然教学顺序）
2. 对于适合的主题，可以采用总-分-总结构：先给出概览（宏观把握），再逐个讲解局部细节（局部击破），最后汇总回顾（合并理解）
3. 每个关键概念配静态 SVG
4. 核心操作配交互式动画（如：入队/出队、分区过程）
5. 如果涉及代码，用 `` 展示，配合逐步执行动画
6. 不要吝啬动画：如果多一个动画能让读者更清晰、更循序渐进地理解，就应该加；但不要为了多而多导致冗余

类型 C：代码 / 算法 → 逐步执行动画

用户给了一段代码或指定一个算法，要求可视化执行过程。

1. 先用 `` 展示完整代码
2. 设计 steps 数组，每一步反映数据的完整状态
3. 每步只做一件事（比较/交换/移动）
4. 配文字说明当前行在做什么
5. 用数组视图（.aw/.ar/.ac）或树视图（SVG）展示

类型 D：概念对比 / 原理解释

用户要求对比两个概念或解释某个原理。

1. 用 .compare 并排展示
2. 每个概念配 SVG 图示
3. 共同点和差异用 ` + ` 说明
4. 如有流程差异，配动画对比

---

套用模板（assets/）

assets/ 目录下有三个必用文件，它们是页面的"骨骼"。生成页面时用 Read 工具把对应文件读出来后原样嵌入，不要 paraphrase 重写——paraphrase 会丢失 CSS 变量名、类名和模板字符串结构，导致样式和动画出问题。

assets/base.css — CSS 骨架

包含颜色变量（含深色模式）、基础排版、所有 callout / compare / 动画容器 / 数组单元格 / 代码面板样式。三个字体变量：--sans（正文）、--mono（代码）、--serif（标题 h1/h2/h3，使用宋体系衬线字体）。

用法：读入后原样放入 `` 标签，不做修改。如果需要调整字号或间距，在骨架后追加覆盖规则，不要改骨架本身——骨架改动会影响参考实现的视觉一致性。

assets/boilerplate.js — JavaScript 工具 + 渲染模板

内含六块内容，按需选取：

| 块 | 何时嵌入 | |---|---| | 工具函数（treePos / mkDots / D） | 所有动画场景必嵌 | | hlLines 代码高亮助手 | 当动画联动代码时嵌入（铁律三） | | 模板 A：数组 + 完全二叉树 | 堆、堆排序——任何"数组 + 完全二叉树双视角"的演示 | | 模板 B：自定义坐标树 | 哈夫曼森林合并、BST、图等需要手算坐标的场景（务必遵守铁律二） | | 模板 C：纯数组 | 简单排序、队列、栈——没有树形结构时 | | 键盘导航 | 所有动画页面都应加 | | VizExpand：动画容器展开/收起 | 所有动画页面都应加 |

只摘取对应模板块嵌入 `（按文件里的注释分割线取一段），**不要把整文件复制进去**——模板 A 和 C 都声明了顶层 var steps / function render / function go，两块一起嵌入会重复声明报错。正确的嵌入顺序：**工具函数块 → 选定的渲染模板块 →（如需）hlLines 块 → 键盘导航块 → 你自己的 steps` 数据**。

使用模板 A 之前注意看文件里的注释：必须自行定义 clsFn(i)（决定数组单元格的高亮类），否则会抛错。模板 B 只提供 renderStep() 纯函数，需要自己写一小段 cur + go(d) + 初始化的驱动层（文件里有示例）。

assets/animation-html.html — 三种动画 HTML 骨架

| 骨架 | 对应场景 | 配套 JS | |---|---|---| | 结构 1：代码面板 + SVG 树 + 数组 | 涉及代码时必须使用（铁律三） | 模板 A + hlLines | | 结构 2：SVG 树 + 数组 | 纯数据结构演示 | 模板 A 或 B | | 结构 3：只有数组 | 简单排序 / 队列 / 栈 | 模板 C |

按场景选一个复制到对应章节，把所有 xx-* id 替换为你的实际前缀（如 heap-push-svg、heap-push-arr 等），避免同页多个动画互相冲突。

---

正文写法

`` 为主

**90% 的内容用 ` 段落写**，不要用彩色框。定义、公式、性质全部放在 中用 ` 加粗关键词：

1. 带权路径长度
先搞清楚三个层层递进的概念。
结点的权：有某种现实含义的数值（如：表示结点的重要性、字符出现的频次等）。
结点的带权路径长度：从树的根到该结点的路径长度（经过的边数）与该结点上权值的乘积。

注意：

• 没有 .def 框，没有 .formula 框，全是 `` 段落
• 公式直接写在 `` 里，不用特殊容器
• 关键术语用 `` 加粗

彩色 callout 框 — 极其克制地使用

callout 框只在以下情况出现，整页总共不超过 3-4 个：

• .info：讲完一个概念后，补充一个容易忽略的要点
• .warn：一个极其容易犯的错
• .good：一个章节讲完后的核心结论

不要用 callout 框来写定义、公式、性质——这些是正文内容，用 `` 写。

静态 SVG 图示

概念讲完后紧跟 SVG 图示。SVG 坐标规划规则：

• viewBox 宽度通常 0 0 700 200（宽 700），高度按需调整
• 圆形节点半径 r=22，相邻节点圆心距 ≥ 56px
• 父子层 y 间距 ≥ 60px
• 颜色用 CSS 变量（var(--gnb) 等），支持深色模式
• viewBox 高度 = max(节点 y + r) + 40（留出标注文字空间）

1

表格 — 克制使用

整页最多 1-2 个表格，只在确实适合并列对比时使用。不要用表格来罗列步骤——步骤用 ` 或编号步骤（.sb`）写。

代码展示

用 `` 标签展示代码：

void HeadAdjust(int A[], int k, int len) {
    A[0] = A[k];
    for (int i = 2*k; i <= len; i *= 2) {
        ...
    }
}

编号步骤

用 .sb + .sn 展示带编号的步骤：

1找到变量名：a
2往右看：[3] → a 是一个长度为 3 的数组

概念对比

用 .compare 并排展示两个概念：

  
    方式 A
    说明...
  
  
    方式 B
    说明...
  

总结章节

每个页面最后有一个总结章节，用 ` 回顾核心脉络，最多加一个 .good` 做最终结论。

---

交互式动画（设计原则）

> 动画的 JS 模板和 HTML 骨架在 assets/ 里，本节只讲设计层面的约定——颜色语义、每个 step 里放什么数据、怎么选模板。

颜色约定

| CSS 类 | 语义 | 何时使用 | |---|---|---| | hl / 蓝 | 当前关注 | 正在操作的节点 | | sw / 橙 | 交换中 | 两个元素正在交换 | | nw / 绿 | 新元素/成功 | 新插入、比较通过 | | pp / 红 | 问题/删除 | 需要调整、违规 | | ok / 绿 | 已完成 | 已确认满足条件 | | lk / 绿 | 已锁定 | 已排好的末尾 | | dim | 不参与 | 被忽略的元素 |

steps 数据设计

每个动画场景的 steps 是一个数组。每个 step 包含当前完整状态：

数组/堆类动画（完全二叉树 + 数组双视角，搭配模板 A）：

{
  vals: [...],      // 当前数组状态
  cap: "...",       // 说明文字（支持  ）
  focus: number,    // 当前关注下标（-1=无）
  swap: [a, b],     // 交换对（null=无）
  lk: [...],        // 已锁定的下标
  hn: number,       // 堆大小（当数组比堆大时）
  line: number,     // 当前高亮代码行号（从 0 开始，-1=无）
}

通用树/图动画（自定义坐标，搭配模板 B）：

{
  cap: "...",
  nodes: [{v:"值", x, y, cf, cs, ct}],   // 节点列表 + 颜色
  edges: [{x1, y1, x2, y2, l?"0/1"}],    // 边列表（可选标签）
  arr: [...],         // 可选：关联数组状态
  ch: [...],          // 可选：变化的数组下标
  line: number,       // 当前高亮代码行号（从 0 开始，-1=无）
}

原则：每步只做一件事（比较 or 交换）；状态反映操作后的结果。当涉及代码时，每个 step 必须指定 line 字段，render 函数末尾调用 hlLines('codeId', s.line)。

栈（Stack）可视化

画栈时，栈底位置固定，新元素从栈顶入栈/出栈。不要反过来固定栈顶而让栈底浮动——这与栈的实际语义不符，也让读者难以直观观察栈的增长和收缩。

模板选择速查

• 有完全二叉树 + 数组双视角 → 模板 A（treePos 自动算坐标）
• 树结构不规则（合并、删除导致形状变化）→ 模板 B（手算坐标，务必遵守铁律二）
• 只有数组 → 模板 C

VizExpand — 动画容器展开/收起

为每个 .w 容器右上角自动添加展开按钮（hover 时显示），点击在 正常 ↔ 页面全屏 之间切换。页面全屏状态下，卡片撑满视口并带半透明遮罩，支持三种方式收起：点击右上角关闭按钮、按 ESC、点击遮罩区域。嵌入 VizExpand 代码段即可，页面加载后自动初始化，无需手动调用。

水印

每个页面默认在 .c 容器末尾（`` 前）加入水印：

Made with  claude-algo-visualize

样式已在 base.css 中定义（居中、淡色小字、分隔线），无需额外 CSS。

---

完整页面结构

  
  
  标题
  /* 读入 assets/base.css 原样嵌入 */

  标题
  一句话概括
  ...

  
  1. ...
  正文段落为主...
  图示...

  2. ...
  正文...
  交互动画（从 assets/animation-html.html 选一个骨架）

  N. 总结
  回顾...
  Made with  claude-algo-visualize

/* 读入 assets/boilerplate.js 里的工具 + 选定模板 + 自己的 steps */

---

常见陷阱

1. 缺少图示：讲到可视化概念必须有 SVG 图，概念讲解后紧跟图示，不能只有纯文字
2. SVG 节点重叠：相邻圆心距 ≥ 56px，父子 y 间距 ≥ 60px，不够就加大 viewBox
3. viewBox 裁切：viewBox 高度 = max(节点 y + r) + 40，务必验证所有 step
4. 彩色框泛滥：不要用 .def/.formula 框写定义和公式，用 ` + `。callout 框整页 ≤ 4 个
5. 表格泛滥：整页 ≤ 2 个表格，不要用表格罗列步骤
6. 脱离来源脉络：有 PDF 时跟着 PDF 的教学顺序走，不要自己重新组织
7. SVG 颜色硬编码：SVG 中必须用 CSS 变量
8. 公式显示：不引入 LaTeX，用 Unicode 字符（Σ、×、≥、≤、⌊⌋）
9. 只有动画没有静态图：静态 SVG 用来解释概念，交互动画用来演示过程，两者都要有
10. 动画与代码割裂：涉及代码执行的动画必须用 .code-panel + .cl.on 高亮当前执行行，steps 里必须包含 line 字段。不能出现动画区域和代码区域互不关联的情况
11. paraphrase 骨架文件：assets/base.css 和 assets/boilerplate.js 里的代码不要手改或重写，读出来原样嵌入；需要定制在后面追加覆盖规则
12. 忘替换 id 前缀：assets/animation-html.html 里所有 xx-* id 必须全部替换为实际前缀，同页多个动画用不同前缀隔离

---

写入策略

由于单个 HTML 文件通常很大（300-600 行），一次性写入容易因网络断流导致全部丢失。必须分阶段写入：

1. 先告知用户整体计划：列出页面将包含哪些章节、几个动画、预计总行数，让用户确认方向正确
2. 分块写入：先写 HTML 骨架 + CSS（从 assets/base.css 读入）+ 前几个章节的静态内容，确认写入成功后，再用 Edit 追加后续章节和 JS
3. 每完成一个阶段，告知用户进度（如"CSS + 前 3 节静态内容已写入，接下来写第 4 节动画和 JS"）

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: L0dyv
• Source: L0dyv/claude-algo-visualize
• License: MIT
• Homepage: https://l0dyv.github.io/claude-algo-visualize/references/heap_overview.html

Install and usage instructions live in the source repository linked above.