创作一个 anim
anim 是一个文件,<kebab-name>@<major>.<minor>.yaml,包含四个键:t(字面量 c)、j(一个 ES 模块)、s(CSS)、h(HTML/SVG)。宿主播放器通过全局 G API 运行它,该 API 提供歌曲的音节、单词、行、段落和节拍。你的任务:根据一个简短的需求,创建一个在快进/暂停/调整大小/主题切换下正确、清晰易读且美观的文件。以下路径相对于此 skill/ 目录。
最重要的规则
- 帧是播放时间的纯函数。
render(t)必须画出相同的画面,无论播放到达t还是用户拖动到t。不允许使用Math.random、Date.now、累积积分或“上一帧发生了什么”这种状态(会被快进跳过)。所有内容都源自歌曲数据、种子和t。 - 两段式结构。 一个导出的、无 DOM 的纯函数部分(
buildPlan、frameAt、辅助函数;可单元测试)位于一个横幅注释之上,然后是一个精简的浏览器部分(export default function (G, shadowRoot, config)),仅负责连接和绘制。参见guides/architecture.md。 - 在
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。 - 使用
G.dispose/G.listen进行清理。 从default返回的函数会被忽略。释放 WebGL(使用forceContextLoss)、监听器、定时器、相机。 - 颜色存在于 CSS 中,而非
c.v中。 在:host上设置浅色值,在[data-bs-theme=dark] { }中设置深色覆盖;canvas 使用 g-lib 的cssColors读取这些值。两种主题都必须看起来经过精心设计。 - 绝不重复造 g-lib 已有的轮子(clamp、lerp、缓动、种子随机数生成器、canvas 适配、弹簧、文本布局、对象池等)。从精确标签的 pinned 版本导入;在编写任何辅助函数之前,先查看
pitfalls/dont-hand-roll.md和spec/g-lib.md。 - 可读性优先于特效。 活跃的音节在浅色和深色主题下、在手机和笔记本电脑上、对于长行、中文(CJK)、从右到左(RTL)文本和缅甸语都应该是清晰可读的。大的闪烁应保持在 3 Hz 以下(
guides/accessibility.md)。 - 少量可配置选项。
c和cSchema是简单的字面量;每个选项都应该产生可见的效果。
工作流程(使用仓库工具)
- 需求。 根据
guides/design-brief.md编写设计需求:一个强烈的、具象的画面;机制;哪些事件驱动什么(同步映射);结构(主歌/副歌/节拍);可读性方案;选项;陷阱。根据其选择表选择后端。拒绝那些无法保持可读性的想法。 - 脚手架。 运行
npm run new -- <name> --backend canvas2d|svg|dom|three(或手动复制templates/<backend>.yaml并替换__NAME__)。 - 阅读一次:
spec/module-format.md、pitfalls/general.md、你对应后端在pitfalls/backends.md中的章节、pitfalls/dont-hand-roll.md。仅通过下面的路由表打开其他文档。 - 实现 纯函数部分(时间到状态),然后是精简的浏览器部分。
- 验证。 运行
npm run validate -- anims/<file>.yaml。修复每个错误;在文档块中证明每个警告的合理性,或者修复它。 - 检查。 运行
npm run check -- anims/<file>.yaml,它会无头挂载 13 首边缘案例歌曲,对合规性表进行评分,并将 PNG 写入out/<name>/目录。打开这些 PNG(手机/笔记本电脑,浅色/深色主题)。一个在丑陋或不可读帧上的绿色表格是失败的。在一行寻址纯度测试上出现 WARN 意味着画面依赖于历史记录:修复它,或者在文档块中证明其合理性(一个有意的模拟)。 - 预览(可选)。运行
npm run preview -- anims/<file>.yaml进行播放、拖动、切换主题和调整选项。 - 审查 对照
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 |
| 相机、地形、群组、打包、程序化 3D | guides/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 使用 |-。文件名携带版本号;绝不要原地编辑已发布的版本。