# Claude Algo Visualize

> 生成单文件的交互式数据结构/算法可视化 HTML 教学页面。适用场景：用户提供 PDF/教材要求生成知识点讲解、给出主题要求做动画演示（如"演示快排"、"做个队列动画"）、提供代码或算法要求可视化执行过程、要求对比两个概念或解释原理。即使用户没有明确说"HTML"或"可视化"，只要涉及"知识点总结"、"教学页面"、"动画演示"、"算法执行过程"、"PDF 讲解"、"SVG 图示"、"逐步执行"等场景也应触发。

- **Type:** Skill
- **Install:** `agentstack add skill-l0dyv-claude-algo-visualize-claude-algo-visualize`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [L0dyv](https://agentstack.voostack.com/s/l0dyv)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [L0dyv](https://github.com/L0dyv)
- **Source:** https://github.com/L0dyv/claude-algo-visualize
- **Website:** https://l0dyv.github.io/claude-algo-visualize/references/heap_overview.html

## Install

```sh
agentstack add skill-l0dyv-claude-algo-visualize-claude-algo-visualize
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

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

> **完整参考实现**：`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% 的内容用 `` 段落写**，不要用彩色框。定义、公式、性质全部放在 `` 中用 `` 加粗关键词：

```html
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**（留出标注文字空间）

```html

1

```

### 表格 — 克制使用

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

### 代码展示

用 `` 标签展示代码：

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

### 编号步骤

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

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

### 概念对比

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

```html

  
    方式 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` 容器末尾（`` 前）加入水印：

```html
Made with  claude-algo-visualize
```

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

---

## 完整页面结构

```html

  
  
  标题
  /* 读入 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](https://github.com/L0dyv)
- **Source:** [L0dyv/claude-algo-visualize](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-l0dyv-claude-algo-visualize-claude-algo-visualize
- Seller: https://agentstack.voostack.com/s/l0dyv
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.