add-effect

用途：当需要向 @remotion/effects 包新增一个特效时使用此技能。整个流程涵盖实现、包入口注册、文档、演示、预览图、Remotion 技能同步、格式化与构建。\n\n主要能力与步骤：\n\n1. 选择特效形态：新特效优先使用 WebGL2 后端，仅当 WebGL 无法表达时才用 2D。简单特效使用单文件 packages/effects/src/<effect-name>.ts；需要多个着色器、运行时辅助或多个文件时，使用 packages/effects/src/<effect-name>/ 文件夹加顶层再导出文件。遵循既有命名：文件/子路径 kebab-case（如 chromatic-aberration），函数 camelCase（如 chromaticAberration），类型 PascalCase params（如 ChromaticAberrationParams），特效类型字符串 remotion/<kebab-case-name>。\n\n2. 实现特效：在特效文件中从 remotion 导入 SequenceSchema 和 Internals，使用 const {createEffect, createWebGL2ContextError} = Internals;。用 const 定义默认值；用 satisfies SequenceSchema 定义 schema（字段会出现在 Studio 可视化编辑中）；导出 params 类型；在 resolve() 辅助函数中解析默认值；使用 packages/effects/src/validate-effect-param.ts 与 packages/effects/src/color-utils.ts 中的辅助函数校验参数；无法获取 WebGL2 时抛出 createWebGL2ContextError('<effect name> effect')；将 documentationLink 设为 https://www.remotion.dev/docs/effects/<slug>；calculateKey() 需包含所有解析后的参数。资料给出 WebGL2 特效的通用代码结构，包含 schema、params 类型、resolve、validate、state 类型、顶点/片元着色器，以及 createEffect 的 type、label、documentationLink、backend、calculateKey、setup、apply、cleanup、schema、validateParams 等字段。新增辅助前应参考既有 WebGL2 特效，如 halftone.ts、blur/blur-runtime.ts、chromatic-aberration/chromatic-aberration-runtime.ts、wave/wave-runtime.ts。\n\n3. 注册包入口：更新 packages/effects/bundle.ts 添加新的 src/<effect-name>.ts 入口；在 packages/effects/package.json 中添加 exports["./<effect-name>"] 与 typesVersions 条目；若使用文件夹实现，添加顶层再导出文件。\n\n4. 构建验证：进入 packages/effects，运行 bun test src/test 与 bunx turbo make --filter="@remotion/effects"。\n\n5. 添加文档：创建 packages/docs/docs/effects/<effect-name>.mdx，遵循既有特效页面格式，包括 frontmatter（slug、title、sidebar_label、crumb: '@remotion/effects'）、image（需先运行 bun render-cards.ts）、H1、包归属说明、简短描述、<EffectsDemo type="effects-<effect-name>" />、带 title="MyComp.tsx" 的 twoslash 示例、每个选项的 ### 标题（可选参数用 ?）、disabled? 小节与 See also 小节。同时更新 packages/docs/sidebars.ts、packages/docs/docs/effects/table-of-contents.tsx，并通过卡片生成器更新 packages/docs/src/data/articles.ts。\n\n6. 添加交互式文档演示：创建 packages/docs/components/effects/effects-<effect-name>-preview.tsx，资料给出预览组件示例代码，docs 特效预览需使用 fit="cover"。在 packages/docs/components/effects-demos/registry.ts 注册演示，导入预览组件与真实特效 schema（或从 effect().definition.schema 读取），添加 id: 'effects-<effect-name>' 条目，仅为 schema 默认为 undefined 的必填字段添加 initialValues。\n\n7. 添加并渲染目录预览合成：TOC 卡片必须来自 packages/docs 中真实 Remotion 合成，预览资源始终渲染为 PNG。在 packages/docs/src/remotion/Root.tsx 的 effect-previews 文件夹下添加 Still，使用与预览组件 CanvasImage 相同的宽高。随后从 packages/docs 运行给定 remotion still 命令，并提交合成入口与渲染图像。\n\n8. 生成文档卡片：进入 packages/docs 运行 bun render-cards.ts，提交生成的 PNG 与新增的 image: frontmatter 行；若生成器顺带产生无关卡片，应移除无关文件。\n\n9. 更新 Remotion 技能：仅当新特效改变通用使用机制、导入约定、安装指引或自定义特效建议时，更新 packages/skills/skills/remotion-markup/effects.md；不要在那里重复完整特效列表，以文档目录为准。\n\n10. 格式化、构建与验证：进入 packages/effects 运行 bunx oxfmt src --write，回到根目录运行 bun run build 与 bun run formatting（若改动涉及 docs 源码，formatting 覆盖 packages/docs/src；仅 MDX 编辑不要对文档页运行格式化）。提交前检查 git diff --check 与 git status --short。\n\n常见陷阱：不要忘记 package.json 的 exports 与 typesVersions（子路径导入如 @remotion/effects/my-effect 依赖它们）；不要忘记 bundle.ts，否则 ESM 子路径不会被构建；不要在 packages/docs/src/remotion 留下临时渲染入口；不要用手写 SVG 作为特效 TOC 预览；除非特效有意改变 alpha，否则保留 alpha；像素运算时注意画布存储的是预乘 alpha；WebGL 颜色运算常需在亮度或阈值计算前对采样 RGB 做反预乘，再对输出 RGB 重新预乘。\n\n适用场景：向 @remotion/effects 新增特效并同步其实现、文档、演示与预览资源的完整开发流程。限制与价格等资料暂未提供。