算法演示台 · Algorithm Theater
把一个算法、数据结构或信息流程,变成一份可直接双击打开、逐步播放的交互图解 (单文件 HTML)。每一帧对应一次可见的状态变化,配有中文解说、伪代码高亮和 播放控制,适合讲课、汇报与自学演示。
产出的 HTML 不依赖任何外部 CDN 或构建工具,离线可开,双击即演示。
Triggers
Activate when
- “把 {算法} 做成可视化 / 图解 / 动画”
- “给 {数据结构/流程} 写一个逐步演示”
- “用可视化讲清楚 {KMP / 快速排序 / Dijkstra / 背包 / 爬楼梯 …}”
- “帮我画个演示稿(算法向)”
- “build a step-by-step visualization for {algorithm}”
- “make an interactive demo of {data structure / process}”
- “create an algorithm explainer animation”
Do not activate when
- 只需要静态示意图、架构图、关系图(无逐步逻辑)→ 交给
lov-bp-deck、lov-diagram或frontend-design。 - 需要品牌级长文/文章配图 → 交给
document-illustrator/baoyu-article-illustrator。 - 把可视化嵌入现有 React 应用并需要状态管理 → 本项目风格:直接按
TraceDefinition数据模型写 TS 模块,复用应用的播放器,不使用本 Skill 的 单文件 HTML 产物。
User Profile (cross-session)
Every generated Skill is connected to the shared user-profile/v1 contract in
skill.yaml. Read the shared user, brand, workspace, preferences, and this
Skill's skills.<skill_id> namespace at the start of every run. Keep the source
portable: resolved personal values belong in the shared profile, never here.
When the user directly states a durable preference or brand fact, persist it
through scripts/profile_store.py and report the saved profile path. Put
Skill-specific values under records.<field>; use brand.<field> or
user.<field> for shared values. Do not persist inferred secrets or credentials.
See references/user-profile.md for the complete contract.
Skill Group Composition
Read references/skill-composition.md before deciding whether to invoke or
extend any adjacent capability. The record distinguishes optional upstream and
downstream handoffs from embedded Kit modules. Do not silently depend on a
sibling Skill that is not shipped with this source.
Workflow (MANDATORY)
You MUST follow these steps in order.
Step 0: Resolve skill root, dependencies, and runtime context
- Use
SKILL_DIRif the environment provides it. - Otherwise infer the installed skill directory from the current skill context.
- Verify every required local module, reference, script, and asset before work:
scripts/validate_viz.py(帧模型校验)scripts/build_viz.py(模型 → HTML)assets/template.html(演示引擎模板)references/step-model.md(帧模型规范与示例)
- If a required resource is missing, name its expected relative path and stop before producing a partial result.
When running scripts manually:
export SKILL_DIR="/path/to/lov-algo-viz-creator"
Resolve context.profile on every invocation. The precedence is current request,
project context, Skill-specific profile records, shared preferences, shared
brand/user profile, then safe defaults. A direct user statement about a durable
preference or brand fact should be saved with scripts/profile_store.py record
using --confirm, followed by a concise saved-path report.
Step 1: Understand the requested outcome
- 确定要可视化的对象:是算法、数据结构、还是业务/信息流程?
- 确定示例数据与目标观众(自学 / 讲课 / 汇报)。
- 明确交付位置:默认写入
./output/(按输出规范),用户指定路径则尊重用户。 - 若算法存在多种实现(递归/迭代、不同的启发式),先确认用哪一种,不要自己拍板 造成返工;其余技术细节(布局、帧数、措辞)由你按本 Skill 原则自行决定。
Step 1.5: Analyze nearby Skills before implementation
- Inspect related local and installed Skills by routing contract and concrete input/output, not by filename alone.
- Record upstream, core, downstream, overlap, and not-composed decisions in
references/skill-composition.md. - Keep sibling Skills optional and artifact-based. When stages require hard coupling for one outcome, create a self-contained Kit instead.
Step 2: Model the algorithm as step frames
这是本 Skill 的核心。先把算法“翻译”成帧序列,再交给引擎渲染。
逐帧建模的六个原则(详见 references/step-model.md):
- 最小推进单元:每一帧 = 一次可见的状态变化(一次比较、一次交换、一次 访问、一次松弛、一次入栈…)。细粒度的机械操作合并成一帧,目标帧数 5–40。
- active vs settled:
active是当前正在操作的元素(每帧 1–3 个,聚焦);settled是已经确定/完成/访问过的元素(单调累积,不再变回)。观众靠这两组 颜色读进度。 - 动态值用
values:DP 表填的数值、最短距离、计数等“中间结果”放进values(node 布局是{节点id: 显示文本},bars 布局是数组快照)。 - 一句话叙事:每一帧的
note用一句中文讲清楚“这一步在做什么 + 为什么”, 引用具体数值/字符(“B 与 D 匹配,继续比较下一位”),不堆术语、不说空话。 - 伪代码对齐:
code写 4–8 行人类语言伪代码,codeLine指向当前逻辑行, 让观众知道“此刻对应哪一步”。 - 首末帧收尾:首帧解释输入与起点;末帧总结结果(“拓扑序列是 …”)。
选择布局:
sequence:数组/序列/字符串(KMP、二分、斐波那契、Z 数组)network:图/树/流程/依赖(BFS、Dijkstra、拓扑、Trie、架构流程)matrix:二维 DP 表 / 距离矩阵(背包、LCS、Floyd–Warshall)bars:数值排序/比较类(冒泡、快速、堆排序)
按以下顺序产出:
- 先写一份
model.json(完整 schema 与示例见references/step-model.md), 直接在算法上真实跑一遍,逐帧记录 active/settled/values,不要凭想象编帧。 - 用
scripts/validate_viz.py model.json校验(error 必须清零,warning 按--strict收敛)。 - 用
scripts/build_viz.py model.json -o output/xxx.html生成独立 HTML。 - 打开生成文件做一次“人肉走查”:叙事是否每一步都成立、帧序是否正确、 布局是否遮挡。
Step 3: Validate the deliverable
- 校验通过:
validate_viz.pyerror=0。 - HTML 生成成功:
build_viz.py有明确输出路径,双击可打开。 - 内容走查:note 每句准确、codeLine 对齐、无遮挡、无 emoji(用内联 SVG 图标)。
- 报告:给出输出文件路径、帧数、布局、演示方式(空格播放、←/→ 逐帧)。
Dependencies
python3(运行validate_viz.py/build_viz.py)。- 无需 npm、无构建步骤、无外部 CDN。
- 产物为自包含 HTML,浏览器(现代 Chrome/Safari/Edge/Firefox)即可打开。
