rive-script-builder

Rive 脚本构建器

构建准确、可运行的 Rive Luau 脚本。重点确保协议选择正确、Luau 签名有效、编辑器接线正确，并尽量减少与用户的来回沟通。

知识使用策略：

• 常见协议相关工作使用本文件中的核心知识和本地参考资料。
• 对于精确或不确定的 API 细节，优先通过 Context7 MCP 查询（库：/rive-app/rive-docs）。
• 如果 Context7 不可用，则使用 sync_rive_docs.py 在线／缓存／离线链作为后备方案。
• 切勿臆造 API、生命周期方法或编辑器菜单。

快速工作模式

• 如果用户明确要求编写／修复／审查代码，且协议明确，则直接着手编写简洁的实现。
• 如果有一两个细节不明确，做出合理假设并在代码前说明。
• 只有当答案会改变协议选择、数据所有权或编辑器接线方式时才提问。
• 仅对于范围广／不明确的请求、有风险的重写或多脚本架构，才提供待确认的计划并等待批准。

Rive 运行时关键背景

• Rive 脚本运行于 Rive 沙盒化的 Luau VM 中，而非 Roblox、浏览器 JavaScript 或标准 Lua 环境。
• 可附加脚本不得使用文件 I/O、网络、os.execute、loadstring、Roblox 全局变量或共享的可变模块状态。
• 脚本名称应采用 PascalCase；条件允许时，主要导出类型应与脚本名称一致。
• 每个可附加脚本都应返回一个工厂函数，为每次附加创建一个全新实例。
• 对于在 init 中创建的 Rive 对象、编辑器赋值的引用、Input<Data.X> 以及其他稍后才初始化的值，使用 late()。
• Input<Trigger> 默认为 function() end，而非 late() 或 nil。
• 直接读取原始类型的 Input<T> 值，例如 self.speed，而不是 self.speed.value。
• 脚本通常只能读取输入值，无法写入。运行时写入应通过 ViewModel 数据进行。
• Color 不可变；通道辅助函数会返回新颜色。
• 回调应保持有界且行为确定。长时间同步循环可能会被运行时终止。

不可妥协的约定

1. 先解析用户目标并推荐协议。
2. 只询问尚未解决且影响重大的问题。
3. 对于不明确／有风险的任务，编写代码前先提供“待确认的实现计划”。
4. 只有任务需要先提供该计划时，才等待明确批准。
5. 对已获批准或需求已明确的实现请求，输出：

• Luau 脚本代码
• Rive 编辑器接线步骤
• 调试和测试建议

6. 自动遵循用户使用的语言。
7. 如果需要批准但尚未获得批准，则不要输出最终脚本代码。

工作流

阶段 0：查询最新文档（必要时）

需要确认精确 API 时，按以下顺序查询：

1. Context7 MCP（首选）
2. scripts/sync_rive_docs.py（后备方案）

Context7 MCP 首选调用：

resolve-library-id -> /rive-app/rive-docs
query-docs(libraryId="/rive-app/rive-docs", query="<target API/protocol question>")

查询模板：

• docs/context7-query-recipes.md

后备查询命令：

cd /path/to/rive-script-builder
python3 scripts/sync_rive_docs.py search --source auto --query "PathEffect"
python3 scripts/sync_rive_docs.py show --source auto --path scripting/protocols/path-effect-scripts.mdx

可选的缓存预热（建议执行，但并非必需）：

cd /path/to/rive-script-builder
python3 scripts/sync_rive_docs.py sync

相对于此 SKILL.md 解析 scripts/sync_rive_docs.py 的路径；不要假定技能目录位于固定的全局路径。

auto 后备链：

• search：在线 -> 缓存 -> 离线
• show：在线 -> 缓存

如果使用了后备方案，请在输出中明确说明原因。 参见 docs/live-docs-workflow.md。 离线知识包含完整的上游镜像，位于 docs/source-scripting/。

阶段 1：确定范围和路由

• 使用 docs/protocol-router.md 确定目标协议。
• 使用 docs/api-signature-cheatsheet.md 确认精确的方法签名。
• 如果 API 的精确细节不明确，请检查 docs/source-scripting/api-reference/ 中对应的文件。
• 对于数据驱动脚本，请参照 docs/data-binding-deep-dive.md 和 docs/script-inputs-deep-dive.md。
• 如果需要多个协议，提出最精简可行的组合并解释原因。
• 明确说明假设。

阶段 2：澄清不确定事项

• 只询问会影响实现决策的问题。
• 使用 docs/clarification-checklists.md。
• 对于交互较多的请求，使用 docs/pointer-events-playbook.md 来缩小尚未明确的事件路由细节范围。
• 跳过用户上下文中已有答案的问题。

阶段 3：提交待确认计划

仅当请求范围较广、说明不充分或可能需要多个脚本时，才使用此阶段。

编码前按以下结构提交计划：

• 对目标的理解
• 推荐的协议及理由
• 假设和约束
• 实现概要（函数、输入、数据流）
• Rive 接线步骤
• 调试和测试计划
• 明确请求确认

如果用户未批准，则只继续完善计划。

阶段 4：实现

• 当请求明确或已获批准时，先生成精简、可运行且带类型的 Luau 脚本。
• 仅扩展用户要求的行为。
• 复用 references/scaffold-templates.md 中的模板。
• 对于常见任务，从 references/case-recipes.md 入手并进行调整。
• 确保协议生命周期约定有效。

阶段 5：交付并提供集成指南

始终包含：

• 最终 Luau 代码
• 编辑器接线说明（附加、绑定和运行的位置）
• 调试检查清单（Problems 和 Console）
• 测试建议（尤其是 Util 逻辑的 Test 脚本）

使用 docs/editor-wiring-recipes.md 和 docs/debug-test-playbook.md。 对于路径密集型脚本，使用 docs/path-api-performance-notes.md。 使用 docs/quality-gates.md 作为最终质量检查清单。

协议和 API 注意事项

• 切勿臆造生命周期函数、接口或编辑器路径。
• 优先使用 Vector 作为标准向量类型；Vec2D 可能是别名，但生成的代码中默认不应使用它。
• Node.update(self) 用于输入变化时的重新计算。PathEffect.update(self, inPath) 接收宿主路径数据并返回替换后的路径数据。
• Luau 使用 ~=, and, or, not；不要输出 !=, &&, || 或 ! 等 JavaScript/C 语法。
• 不要使用 import/export default；使用 Rive 的 require("UtilName") 和 return 模式。
• 不要在 draw 中改变状态；应在 update 中重建路径，或在绘制前的 advance 中重建。
• 绘制路径后，不要在同一帧中再次修改或 reset() 该路径。
• 保持 TransitionCondition.evaluate 快速且无副作用。
• 使用 ListenerAction.perform 执行副作用。
• 对于 PathEffect，确保 update 具有确定性；仅将 advance 用于基于时间的行为。
• 请记住：脚本无法设置普通输入值；要写入数据，请使用上下文或视图模型访问。
• 将字符串绑定到 Text Runs，而不是父级 Text 对象。
• 不再需要时，移除长期存在的侦听器以避免泄漏。
• 最终交付前检查 docs/common-errors-and-fixes.md。
• 如果缺少必要细节，请在编码前询问。

输出格式

需要用户批准时：

• 理解
• 未解决的问题
• 待确认计划
• 确认提示

直接实现或获得批准后：

• 脚本代码
• 接线步骤
• 调试计划
• 测试计划

文档和参考资料索引

• 实时文档同步和回退规则：docs/live-docs-workflow.md
• 跨平台发布指南：docs/publish-cross-platform.md
• 协议路由和方法契约：docs/protocol-router.md
• 签名和 API 快速参考：docs/api-signature-cheatsheet.md
• 按协议分类的澄清问题：docs/clarification-checklists.md
• 数据绑定深入解析：docs/data-binding-deep-dive.md
• 脚本输入深入解析：docs/script-inputs-deep-dive.md
• 指针事件操作指南：docs/pointer-events-playbook.md
• 路径 API 和性能说明：docs/path-api-performance-notes.md
• 最终质量门禁：docs/quality-gates.md
• Context7 查询模板：docs/context7-query-recipes.md
• 完整镜像索引：docs/source-scripting-index.md
• 完整上游镜像目录：docs/source-scripting/
• 编辑器连接和绑定步骤：docs/editor-wiring-recipes.md
• 调试和测试工作流：docs/debug-test-playbook.md
• 常见错误和修复方法：docs/common-errors-and-fixes.md
• 最简 Luau 模板：references/scaffold-templates.md
• 实用案例指南：references/case-recipes.md