Communitygithub.com

anim 创作工具

根据简短需求,创建一个单一的 YAML 模块,该模块可在浏览器中(使用 canvas2d、SVG、DOM 或 three.js)动画化歌曲的歌词和节拍。当被要求制作、移植、重新设计样式或修复一个 anim/歌词可视化/歌词动画模块时使用。此技能独立工作,无需示例库或目录。

anim 创作工具 是什么?

这个技能用于创建“anim”,一种单文件 YAML 模块,它能将歌曲歌词和节拍在浏览器中动态可视化,支持 canvas2d、SVG、DOM 或 three.js 四种后端。用户只需提供一个简短的需求描述,AI 就能根据一套详细的规则和设计原则生成完整的动画模块。该模块必须遵守“帧是播放时间的纯函数”这一核心原则,确保在快进、暂停、调整大小或切换主题时行为一致且画面正确。它严格分离纯逻辑(无 DOM)和浏览器渲染部分,并使用全局 `G` API 与宿主播放器交互。技能文档提供了从需求分析、代码实现到验证检查的完整工作流程,包括使用工具进行自动验证、检查(生成 PNG 截图)和预览,以及无需 shell 的纯聊天模式。文档还包含了避免常见陷阱的指导、详细的文档路由表和 20 条质量标准,以确保生成的动画既正确又美观,同时兼顾可读性(支持 CJK、RTL 等)和无障碍性。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/prjctg/animr-skill/tree/HEAD/skill

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

创作一个 anim

anim 是一个文件,<kebab-name>@<major>.<minor>.yaml,包含四个键:t(字面量 c)、j(一个 ES 模块)、s(CSS)、h(HTML/SVG)。宿主播放器通过全局 G API 运行它,该 API 提供歌曲的音节、单词、行、段落和节拍。你的任务:根据一个简短的需求,创建一个在快进/暂停/调整大小/主题切换下正确、清晰易读且美观的文件。以下路径相对于此 skill/ 目录。

最重要的规则

  1. 帧是播放时间的纯函数。 render(t) 必须画出相同的画面,无论播放到达 t 还是用户拖动到 t。不允许使用 Math.random、Date.now、累积积分或“上一帧发生了什么”这种状态(会被快进跳过)。所有内容都源自歌曲数据、种子和 t。
  2. 两段式结构。 一个导出的、无 DOM 的纯函数部分(buildPlan、frameAt、辅助函数;可单元测试)位于一个横幅注释之上,然后是一个精简的浏览器部分(export default function (G, shadowRoot, config)),仅负责连接和绘制。参见 guides/architecture.md。
  3. 在 default 中注册,在 INIT 中读取歌曲数据。 G.on / G.off / G.onFrame 仅在 default 内部使用。G.map / forEach / lookup / iterator / relayout 仅在 INIT 触发后(在 INIT 处理函数中,或在之后的回调如 render 中)使用,绝不在 default 本身中使用。订阅 G.on(G.TYPE.TICK, render) 用于播放;G.onFrame({ render, reset }) 涵盖 SEEK/PLAY/PAUSE/RESIZE 和 UNINIT。
  4. 使用 G.dispose / G.listen 进行清理。 从 default 返回的函数会被忽略。释放 WebGL(使用 forceContextLoss)、监听器、定时器、相机。
  5. 颜色存在于 CSS 中,而非 c.v 中。 在 :host 上设置浅色值,在 [data-bs-theme=dark] { } 中设置深色覆盖;canvas 使用 g-lib 的 cssColors 读取这些值。两种主题都必须看起来经过精心设计。
  6. 绝不重复造 g-lib 已有的轮子(clamp、lerp、缓动、种子随机数生成器、canvas 适配、弹簧、文本布局、对象池等)。从精确标签的 pinned 版本导入;在编写任何辅助函数之前,先查看 pitfalls/dont-hand-roll.md 和 spec/g-lib.md。
  7. 可读性优先于特效。 活跃的音节在浅色和深色主题下、在手机和笔记本电脑上、对于长行、中文(CJK)、从右到左(RTL)文本和缅甸语都应该是清晰可读的。大的闪烁应保持在 3 Hz 以下(guides/accessibility.md)。
  8. 少量可配置选项。 c 和 cSchema 是简单的字面量;每个选项都应该产生可见的效果。

工作流程(使用仓库工具)

  1. 需求。 根据 guides/design-brief.md 编写设计需求:一个强烈的、具象的画面;机制;哪些事件驱动什么(同步映射);结构(主歌/副歌/节拍);可读性方案;选项;陷阱。根据其选择表选择后端。拒绝那些无法保持可读性的想法。
  2. 脚手架。 运行 npm run new -- <name> --backend canvas2d|svg|dom|three(或手动复制 templates/<backend>.yaml 并替换 __NAME__)。
  3. 阅读一次: spec/module-format.md、pitfalls/general.md、你对应后端在 pitfalls/backends.md 中的章节、pitfalls/dont-hand-roll.md。仅通过下面的路由表打开其他文档。
  4. 实现 纯函数部分(时间到状态),然后是精简的浏览器部分。
  5. 验证。 运行 npm run validate -- anims/<file>.yaml。修复每个错误;在文档块中证明每个警告的合理性,或者修复它。
  6. 检查。 运行 npm run check -- anims/<file>.yaml,它会无头挂载 13 首边缘案例歌曲,对合规性表进行评分,并将 PNG 写入 out/<name>/ 目录。打开这些 PNG(手机/笔记本电脑,浅色/深色主题)。一个在丑陋或不可读帧上的绿色表格是失败的。在一行寻址纯度测试上出现 WARN 意味着画面依赖于历史记录:修复它,或者在文档块中证明其合理性(一个有意的模拟)。
  7. 预览(可选)。运行 npm run preview -- anims/<file>.yaml 进行播放、拖动、切换主题和调整选项。
  8. 审查 对照 guides/quality-rubric.md(20 个问题),然后交付这一个 YAML 文件和一份简短报告(文件名,最终检查表,需求中未明确决定的决策,你刻意没有做什么)。不要提交 out/ 目录或测试框架。

无工具模式(聊天模型,无 shell)

跳过步骤 2、5-7。从匹配的模板文本开始,在你的推理中编写设计需求,然后在回答之前,逐行对照你自己的代码检查 pitfalls/general.md、对应后端章节和 20 个问题的质量标准。仅在单个代码块中输出 YAML 文件,并提及哪些质量标准项目你无法在运行的情况下验证(寻址纯度、主题切换、尺寸调整)。

路由表:仅在相关触发条件适用时打开文档

当你即将……时阅读
决定构建什么;选择后端guides/design-brief.md
布局文件;命名阶段;编写文档块guides/architecture.md
使用任何 G.* 调用、事件选项或 id 范围spec/events.md, spec/event-shapes.md, spec/g.d.ts
添加选项、颜色、主题spec/config.md
使用时间工具、文本测量、canvas 辅助函数、生命周期spec/utilities.md
将行拆分为显示行、文本换行spec/relayout.md, guides/patterns-text.md
在音节/行/节拍上触发事件;预生成;暂停;弹簧guides/patterns-timing.md
适配、高亮或样式化文本;非拉丁脚本guides/patterns-text.md
编写渲染代码(DOM、SVG、canvas、three、模拟、层)guides/patterns-render.md, pitfalls/backends.md
相机、地形、群组、打包、程序化 3Dguides/techniques.md, pitfalls/techniques.md
使用照片或相机spec/image-input.md
构建游戏(autoPlay 为 false,得分,状态)guides/games.md
使用任何 g-lib 辅助函数spec/g-lib.md
对闪烁、运动、对比度感到不确定guides/accessibility.md
完成guides/quality-rubric.md

最小结构(不要提交这个;从一个模板开始)

"t": |-
  c
"j": |
  import { hash01 } from 'https://cdn.jsdelivr.net/gh/prjctg/[email protected]/index.js';
  /* [email protected]: <一行说明>
   * 1. <编号的设计声明:机制及其拒绝的常见错误答案> */
  export function frameAt(plan, t) { /* 纯函数 */ }
  /* 浏览器部分。此线之上的所有内容刻意保持无 DOM。 */
  export default function (G, shadowRoot, config) {
    const cfg = G.cfg(config, { channel: G.cfg.int(0) });
    let ready = false;
    const render = (t) => { if (!ready) return; /* 绘制 frameAt(plan, t) */ };
    G.on(G.TYPE.INIT, () => { ready = true; /* 此处 G.map(...) 有效 */ });
    G.on(G.TYPE.TICK, render);
    G.onFrame({ render, reset() { ready = false; } });
  }
  export const c = { v: { fadeMs: 150 }, m: [{ s: 'fadeMs', t: 'fadeMs' }] };
  export const cSchema = [{ i: 'fadeMs', n: 'Fade (ms)', t: 'int', mn: 0, mx: 2000 }];
"s": |
  :host { display: block; --ink: var(--inkColor, #111); }
  [data-bs-theme=dark] { --ink: var(--inkColor, #eee); }
"h": |
  <canvas id="c"></canvas>

j、s、h 包含原始文本(绝不包裹在反引号或引号中)。t 使用 |-。文件名携带版本号;绝不要原地编辑已发布的版本。

相关技能