AGENT SKILL

motion-figure

制作会运动或响应读者的图表:课程内的 SMIL 动画与滑块组件、展示真实系统部件并计算结论的交互机制图, 以及课程配色的有序抖色条带。触发短语:“动画图”“添加滑块”“交互图”“展示系统如何工作” “让图动起来”“抖色页头”“机制图”“figure 围栏”。

License 许可
MIT
最近更新
2026-11-12
Stars
★ 1.3k
Forks
195

01 前言 Front Matter

name
motion-figure
tags
[ "figures", "svg", "smil", "animation", "interactive", "dither" ]
version
1.1.0
description
制作会运动或响应读者的图表:课程内的 SMIL 动画与滑块组件、展示真实系统部件并计算结论的交互机制图, 以及课程配色的有序抖色条带。触发短语:“动画图”“添加滑块”“交互图”“展示系统如何工作” “让图动起来”“抖色页头”“机制图”“figure 围栏”。

02 资源文件 7

03 SKILL.md 正文

动态图表

制作会运动或响应输入的图表。支持 Claude、Cursor、Codex、OpenClaw、Hermes 和所有读取 SKILL.md 的 agent。

层级 产物 使用位置
1. 课程图 声明式 SMIL 动画,或重绘 SVG 的滑块组件,均通过 figure 围栏挂载 课程内
2. 机制图 展示真实系统部件的 HTML 面板,读者操作一个控件并阅读计算结论 独立页面、README、文章、课程外站点页面
3. 抖色场 使用纸张、强调色和墨色的 WebGL 有序抖点条带,支持四种固定种子运动 页头和节间分隔

课程运行时限制严格,所以第 1 层规则最多。第 2、3 层有独立参考文件。

适用情况

  • 课程解释随时间变化的过程,例如 token 经过阶段、队列填充、循环重复。
  • 一个输入改变公式输出,例如学习率、温度、分块大小、批大小。
  • 作者要求图表动画、滑块或交互。
  • 页面需要读者改变一个条件,观察缓存、队列、上下文窗口或路由器的行为:用第 2 层。
  • 页面需要课程配色的缓慢动态页头:用第 3 层。

使用其他技能的情况

  • 固定结构,无时间轴与输入:使用 blueprint-figure 静态图。
  • 有独立状态模型与机器几何的完整讲解页:使用 isometric-explainer。
  • 只需配色、字体或写作规则:使用 course-style。本技能把必要部分复制到 references/tokens.md。

方法

  1. 用一句话说明图中唯一的变化。需要两句话时拆成两张图。

  2. 选层级。课程内用第 1 层。第 2 层读取 references/mechanism-figures.md,从 templates/mechanism.html 开始。第 3 层读取 references/dither-fields.md,复制 templates/dither.js。以下步骤针对第 1 层:时间是变量时用动画,数值是变量时用滑块。

  3. 使用 kebab-case 名称,例如 request-path、context-budget。先查注册表,同名后注册模块会替换先前图表。

  4. 代码放进 figures-<topic>.js,用 IIFE 包裹,读取 window.LF,不存在则立即返回。

  5. 图函数签名为 function (host, cfg),向 host 添加一个 .lf 卡片,可返回清理函数。

  6. 卡片包含 .lf-head(大写 .lf-label 和短提示)、.lf-body、.lf-cap 图注。

  7. SVG 使用 viewBox="0 0 520 H",通常 H 为 200 至 250,单条形可更矮。

  8. 添加 title 和 desc,ID 只创建一次,放在渲染函数外。

  9. 动画先入场,再进入一个慢循环,逐项遵守 references/smil-rules.md。

  10. 滑块先定义 state._render,再调用 LF.slider 或 LF.select,最后调用一次 state._render()。

  11. 模块末尾用 LF.register({ 'your-name': fn }) 注册。

  12. 课程 Markdown 加围栏,首行为名称,后面可带 JSON:

    ```figure
    context-budget {"windowK": 32}
    ```
    
  13. 完成检查清单,在浅色、深色、375px 宽度和减少动态效果设置下查看。

页面如何挂载图表

  • Markdown 解析器把围栏转为 <div class="lesson-figure" data-figure="name {json}">。
  • 构建器扫描课程中的图名,找到含该带引号名称的模块并写清单。找不到提供者则停止构建。
  • 页面按固定顺序只加载该课需要的模块。新文件排在已列文件后,按字母序加载。
  • 挂载函数将第一个词作为名称,剩余内容解析为 JSON,失败则 cfg 为空对象。
  • 图函数抛错时,运行时清空宿主并记录 warning,课程其他部分继续渲染。
  • 挂载后补充缺少的 title、desc、role=img 和控件标签。有 SMIL 时添加暂停按钮,有一次性动画时添加重播按钮。
  • 离开视口、标签页隐藏或读者点击暂停时停止动画。减少动态效果或打印时显示静态帧。

全部运行时函数与两个完整示例见 references/toolkit.md。

规则

动画图:

  1. 只用 animate、animateTransform、animateMotion,不在图中使用 setInterval 或 requestAnimationFrame。
  2. 每图最多 55 个 SVG 元素。
  3. 入场从 opacity 0、scale 0.95 到 opacity 1、scale 1,不从 scale 0 开始。
  4. 入场使用 calcMode=spline、keySplines="0.23 1 0.32 1",时长 0.5 至 0.6 秒。
  5. 入场错开 0.05 至 0.4 秒,退出比入场短。
  6. 循环 2.5 至 6 秒,repeatCount=indefinite。循环不设 fill=freeze,否则运行时改为播放一次。
  7. keyTimes 与 values 项数相同,从 0 到 1,单调不减。
  8. keySplines 比 keyTimes 少一项,只能与 calcMode=spline 共用。
  9. animateMotion 使用 keyPoints 时,calcMode=linear,keyPoints 与 keyTimes 项数相同,不带 values。
  10. 动画 fill 或 stroke 值不用 var()。叠加目标颜色元素,改变其透明度。
  11. 循环只改变 opacity、transform、stroke-dashoffset 或路径运动。x、y、x1、y1、x2、y2、width、height、r、cx、cy、rx、ry 动画会被运行时改为一次性。
  12. 宿主 data-static-time 指定的帧必须完整可读,默认 1.5 秒。完整状态较晚才出现时显式设置。该帧中运动元素不压在标签上,同一标签的两种状态不同时可见。
  13. 元素绕中心缩放:组内内容围绕 (0,0) 绘制,用 translate 移动组,缩放用 additive=sum。

滑块组件:

  1. 只写 ES5,使用 var、函数表达式、字符串拼接,不用箭头、let、const、模板字符串。
  2. 第一次 LF.slider 或 LF.select 前定义 state._render,因为控件创建时会包裹它。
  3. state._render 中移除全部 SVG 子元素再重建,不原地编辑节点。
  4. ID 在渲染外只创建一次。新节点缺少的属性会被运行时删除,包括 ID。
  5. 条形通过长度或路径 stroke-dasharray 增长,不用 scale,因为协调后的节点绕中心缩放。
  6. 标签短小,英文小写,括号内写单位,例如 chunk size (tokens)。中文页面对应翻译。

两种图共用:

  1. 颜色来自 CSS 变量,以浅色值作默认,例如 var(--blueprint,#3553ff)。无变量可用时才用字面十六进制值。
  2. 主体最多一个强调色 blueprint,第二状态可用 warn,其他部分用 ink 和 rule token。
  3. SVG 字至少 12 单位,字体 var(--font-mono)。必须更小时,给 SVG 至少 500px 宽并允许图内横向滚动。用 LF.textWidth 按文字确定框宽,长标签用 LF.wrapText 换行。矩阵单元格分别按宽和高计算,取较小值。线条和框边不穿过标签,标签不宽于其背后的框。
  4. 在手机上测量实际字号。375px 屏幕中 520 单位图可能只宽 279px,12 单位标签实际约 6.4px。
  5. 图注清楚说明每种颜色。英文每句最多 25 词,中文用短句。
  6. lf-label 英文大写、两至四词,中文对应翻译。

机制图,第 2 层:

  1. 展示真实文件名、键名、token 数等名称和数值,不用 item 1 或无名灰条。
  2. 提供一个主控件:单步、滑块、开关、播放或停止部件。
  3. 最后以文字输出从图中数值计算的结论,不写死结果。
  4. 35% 可见时播放一次,提供重播按钮,不循环。
  5. 只动画 transform 和 opacity,缓动 cubic-bezier(0.23, 1, 0.32, 1)。按压 120 至 160ms,显现 200 至 300ms,折叠 380 至 500ms。
  6. 列表每项错开 30 至 70ms,只错开前八项。
  7. 每帧标签完整,不省略、不重叠、不压点阵。文字至少 11px,结论至少 12.5px。
  8. 320px 时面板单列,控件触摸目标 40px。
  9. 使用站内其他页面未用过的机制,并登记机制表。

抖色场,第 3 层:

  1. 读取 bg、blueprint、ink,data-theme 改变时重绘。
  2. 最多每秒 30 帧,只在可见时绘制。
  3. 减少动态效果时绘制静态帧。无 WebGL 时显示静态斜线填充。
  4. 条带 aria-hidden=true。除标签小片外,点阵上不放文字。

完成前检查

  • [ ] 围栏名称与注册名完全一致,没有其他模块同名。
  • [ ] 模块没有箭头、let、const、模板字符串。
  • [ ] 课程图没有 setInterval 或 requestAnimationFrame。
  • [ ] smil-rules.md 的校验器对已挂载宿主返回空数组。
  • [ ] 每个动画图最多 55 个 SVG 元素。
  • [ ] 循环时长均在 2.5 至 6 秒。
  • [ ] 循环不改变第 11 条的几何属性。
  • [ ] 减少动态效果时图完整,没有丢失元素。
  • [ ] 深色下所有线和标签可见。
  • [ ] 375px 宽时标签可读,图表外页面不横向滚动。
  • [ ] 在课程仓库内运行 node scripts/audit_lesson_figures.js --only <name>,输出 TOTAL 0。它在 Chrome 中按桌面和手机宽度挂载图表,检查静态帧和两个动画时刻。以下情况会失败:标签重叠;标签或闭合图形超出 viewBox;文字小于 9px;桌面宽度下需要横向滚动;标签被图形遮挡或被线条穿过;标签宽于其框;带边框的框互相重叠。文字检查允许 0.5px 舍入误差。用 --shots <dir> 查看失败截图,重新排布出错区域,不要逐个挪标签凑数。viewBox 中的最小字号决定最后两项:图宽 728px 时,文字至少需要 9 × viewBox 宽 / 728 单位。
  • [ ] 滑块到最小、最大均无 NaN、负宽度、控制台错误。
  • [ ] SVG 有一个 title 和 desc,滑动后 ID 保持不变。
  • [ ] 图注解释每种颜色。
  • [ ] 第 2 层通过 mechanism-figures.md 的全部检查。
  • [ ] 第 3 层通过 dither-fields.md 的全部检查。

文件

  • references/smil-rules.md:十二条 SMIL 规则、原因与浏览器校验器。
  • references/toolkit.md:LF 函数、挂载顺序、完整滑块和 SMIL 模块、站外预览页。
  • references/tokens.md:明暗配色、字体、动态时长。
  • references/mechanism-figures.md:第 2 层的真实名称、反例、机制、结构、结论、动态预算与检查。
  • references/dither-fields.md:第 3 层的着色器、四种运动、标记、规则、抖色条和检查。
  • templates/mechanism.html:可在浏览器直接打开的 LRU 缓存机制图,含容量控件。
  • templates/dither.js:完整抖色脚本,加载后添加 <div class="dither" data-seed="...">。

仓库内另见 site/lesson-figures.js 运行时与 site/figures-*.js 更多图表。

04 同仓库更多 Skills

fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

write-manual

为一个固定版本的技术主题编写长篇手册,从用途讲到每个请求与响应。 每个示例来自离线运行记录,每个断言追溯到按权威排序的来源,审计必须达到 TOTAL 0。 用于“编写手册”“为某主题写入门手册”“manual.json”“增加手册章节” “构建运行记录工具”“审计手册”“固定规范版本并文档化”。

★ 1.3k
fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

start-learning

AI Engineering from Scratch 课程的一次性入门流程(523 节课、20 个阶段)。访谈学习者、 运行分级测验,并写入由 learn skill 驱动的持久学习计划 LEARNING.md。触发短语: “开始学习”、“设置课程”、“开始课程”、“带我入门”、“创建学习计划”,或 "start learning", "set up the course", "begin the curriculum", "onboard me", "create my learning plan"

★ 1.3k
fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

mcpa-certification

AI Engineering from Scratch 中文版中的 MCPA(Model Context Protocol Associate)AI 原生导师与入门流程。学习者需要备考 MCPA、继续认证路线、 交互式学习下一课、运行并验证实践实验、参加诊断或全真模拟、根据薄弱领域 补弱时使用。适用于 Claude Code、Codex、ChatGPT、Cursor 或其他 agent。

★ 1.3k
fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

lesson-screen

课程导师在终端教学时,在旁边打开浏览器学习屏幕。展示课程已注册的图表、带真实数值的 代码执行过程和可点击的预测题。也可结合课程与宿主已安装的图表技能,为当前课程制作 蓝图、机制图、等距机器或 3D 模型。点击以事件形式返回导师。 触发短语:“打开学习屏幕”、“用图展示”、“用 3D 展示”、“画出架构”、“为这节课制作图表”, 或 "open the lesson screen", "show me this visually", "show this in 3D", "draw the architecture", "visualize this lesson", "build a figure for this lesson", "lesson screen"。

★ 1.3k
fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

learn

AI Engineering from Scratch 课程的交互式课程 tutor。读取 LEARNING.md,获取下一课, 在终端按章节教学,结尾测验并记录进度。可在克隆仓库中或完全通过 raw.githubusercontent.com 工作—— 无需设置。触发短语:“下一课”、“教我”、“继续课程”、“我们来学习”、“继续学习”,或 "next lesson", "teach me", "continue the course", "let's learn", "resume learning"

★ 1.3k
fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

learn-reverse-engineering

从零开始学 AI 工程中逆向工程专项路径的交互导师。学习者希望读取编译后的程序时, 用于开始或继续文件格式、反汇编、控制流、表示提升、证据、等价证明、调用约定、 编译器惯用模式、链接、类型、调试、字节码、差分、符号执行和 AI 辅助分析。 每次调用讲授一课,并将证据记录到 REVERSE-ENGINEERING-LEARNING.md。

★ 1.3k