composer

Singular Composer

每个会话使用唯一的连接名称：

node scripts/composer-agent.js <command> --connection <conversation-connection-name> [options]

成对命令重复使用该连接。本地 ai-graphics validate|preview 不接受 --connection；请省略此参数。不要重复使用其他配置文件，也不要将其与 COMPOSER_AGENT_CREDENTIALS 组合使用。仅使用捆绑的 CLI。切勿暴露凭据、替换原始合成 JSON、构造脚本 REST 调用或添加任意中继执行。

每个软件包版本、Node 主版本和锁文件摘要运行一次 node scripts/dependency-preflight.js；在其中任一项发生变化之前，重复使用成功结果。使用 Chrome 时添加 --capture。使用 doctor 诊断安装问题。始终安装最新可用的 Composer skill；切勿为兼容协议而降级。

开始新工作前，必须确保预检通过。使用现有的 Node 22.x 或 24.x 运行时。对于其他主版本，即使核心依赖已就绪，NODE_VERSION_MISMATCH 仍属于阻塞问题；请按照安装说明选择受支持的运行时并重新运行，不要在未告知用户的情况下替换其全局运行时。

遇到 COMPOSER_AGENT_VERSION_MISMATCH 后，在选择 Control Node 类型之前，请按照安装恢复说明操作。先升级，然后从已安装的替代版本中重新阅读特定类型的参考资料；旧参考资料不能作为新协议的依据。

首先路由任务

只阅读当前任务和阶段所需的参考资料。

配方算法和验收场景仅适用于所请求的图形，不是技能维护门槛。不要将 Composer 命令或文档任务扩展为通用组件 QA、外部数据集成测试或未经请求的源代码修改。

任务	必需的参考资料
安装、升级或验证技能安装	修改任何已安装文件前，先阅读 installation.md
配对、文件和恢复	command-basics.md、resuming-work.md
图形创建、设计或参考匹配	authoring-quality.md
独立属性编辑	先阅读 command-basics.md 中的“Isolated property edits”，然后阅读对应的组件指南
元素、布局、字体、图元或声明式图形	element-commands.md、graphics.md 或 auxiliary-commands.md
组件选择或配置	widgets.md，然后阅读对应的路由组件指南
合成、应用模板匹配或集成资源、修订版本或显示变体	composition-structure.md、composition-commands.md、revisions.md 或 display-variants.md
时间线、更新、行为、逻辑层或播放	composition-motion.md 和 motion-commands.md
控制节点、容器、值、链接或删除	control-nodes.md，然后阅读对应的创建、编辑或命令参考资料
原生计时器时长控制或 timerChanged 脚本消息	control-node-timer.md
组件自有模板或输出链接	widget-subcompositions.md 或 widget-nodes.md
捕获或测量	capture.md
合成脚本或 Player 行为	composition-scripts.md 及其对应的脚本参考资料
可复用的构建模式或提供的动画	recipes.md 或 video-reference.md
generate improvement handoff	improvement-handoff.md

generate improvement handoff 属于回顾性操作。返回经过净化的开发提示词，不要进行配对、工作、检查或修改。

授权并开始工作

Composer AI 的可用性取决于部署和账户资格。如果该功能不可用或账户不符合资格，请报告阻碍并停止。进行新的授权时，请索取可见的六位代码；绝不索取令牌或轮询意图。收到代码后立即运行 pair --code <code>。PAIRING_CODE_INVALID 表示终止；请索取新代码，不要重试。要求 paired: true 和 acknowledged: true。使用 check-connection --connection <conversation-connection-name> 进行只读检查。

不要筛选配对命令的 stdout/stderr，也不要隐藏其退出状态。检查完整的脱敏结果；在声明之前发生的协议不匹配不会消耗代码，但代码仍会过期。重试前，请按照安装恢复中的说明操作。

对于需要编辑器命令的任务，请在运行 inspect 或进行修改前运行：

node scripts/composer-agent.js begin-work --connection <conversation-connection-name>

只有在授权有效、编辑器已连接、命令已就绪且租约有效时才能继续。若就绪状态检查失败，begin-work 会尝试释放；请在命令基础知识中检查已确认或未知的清理结果。遇到 OPERATION_CANCELLED 时，请停止操作，直到收到新指示。让出控制权、等待或结束前，请运行：

node scripts/composer-agent.js finish-work --connection <conversation-connection-name>

要求 COMPOSER_WORK_RELEASED。成功完成任务时，请改用 finish-work --save：启用自动保存时，该命令会等待最终合成内容保存完成；手动模式下，则会报告 save.manualSaveRequired，而不会执行保存。普通的 finish-work 只会暂停并释放租约，不会保存完成内容。提出需要等待回复的问题前，请发送 status --state waiting-for-user --message "<blocking question>"，不带 --save 释放租约，然后等待。必须提供 --message。修订规定了审批例外。有关中断、保存失败和发布限制，请参阅批量自动保存。

收到回复后，第一项 Composer 操作必须是确认收到回复，并且要在规划、准备文件、检查就绪状态或检查内容之前执行（只要租约仍有效）。准备下一项操作时，不要让 Composer 一直显示该问题。此反馈不代表授权修改，也不能绕过租约或取消限制。

检查、修改、验证

对于匹配模板的合成内容，合成契约不可违反，即使用户明确要求也不例外。在更改结构或依赖契约的行为之前，请先阅读匹配模板的 Integration Resources（用户要求的状态；否则读取已发布版本），并逐项核对拟议修改是否符合契约。绝不要删除、重命名、移动或更改必需 Control Nodes 的类型；绝不要重命名、移动或删除契约中指定的合成内容或路径，也不要移除必需行为。拒绝会破坏契约的部分，准确指出相关契约条目，并且只提供符合契约的替代方案；在授权范围内继续处理安全的部分。确认、理由或修订审批都不能覆盖此规则。绝不要清除或更改匹配项来绕过规则，也不要提出在切换模板后继续操作。移除或替换保护性匹配项应由用户在 Composer 中自行操作，而不是由 Agent 变通处理。请参阅保留契约。

对于由 Control App 驱动的创作或与模板兼容的创作，在选择结构、公共控件或脚本前，请遵循 Integration Resources 完成门槛。将必需行为与界面保留要求分别跟踪。进行结构性创作时，请查找根匹配项，并为外部寻址的内容保留其契约。无关的视觉编辑无需获取资源。 在构建新的合成前，先确定合适的应用模板。当模板选择需要 Essentials 或 Studio 时，除非用户明确要求 Studio，否则使用 UNO Essentials（模板 ID 518）；不要询问用户要在 Essentials 和 Studio 之间做何选择。这不是其他模板的通用默认选项；对于其他模板，请遵循用户明确指定的选择。如果用户明确要求的 Control App 模板似乎不匹配，只警告一次，然后遵循用户的选择，并按照该模板的 Integration Resources 契约执行。阅读其契约，并使用 set-app-template-match 将模板分配给合成。对于其他模板选择和不确定情况，请遵循完成工作流。现有匹配合成的契约不可更改。

Composer 是事实来源：

1. 运行 inspect，并有针对性地读取目标；聊天内容不是当前状态。请参阅恢复防护措施。
2. 通过路由引用读取所需的实时架构和所有权；绝不要凭记忆推断可变契约。对于匹配的合成，在每次结构性或依赖契约的变更前，都要完成契约保留检查，包括单独的节点 ID 编辑、删除、合成重命名和脚本更改。仅当匹配状态、状态值和版本仍为当前值时，才可复用当前任务的版本化契约。
3. 在任务中首次进行高影响变更前，通过 AI 聊天提问界面建议创建修订，并等待用户选择；经确认的空白起始场景除外。默认组和不含任何已创作内容或 Control Nodes 的空默认子合成，无需提示备份。继续前，请阅读修订审批，了解针对整个场景的空白起始场景检查、其他豁免情况和同意流程。
4. 通过支持的最高层级操作，进行一次连贯且范围明确的更改。对于 apply，传入检查所得的 --composition-id 作为范围保护。
5. 重新检查更改范围，并验证权威回读、链接、所有权及无关状态。

使用范围明确的投影和临时结构化输入。绝不要拆解失败的原子操作。遵循 command-basics.md：结果不确定时，重试前先获取权威回读。直接报告错误。

只更改用户要求的内容。保留无关结构、控件、链接、脚本和状态。每个目标位置只能有一个写入权威；通过定义字段的来源更新关联字段。配对编辑器拥有结构，经过身份验证的助手拥有持久化脚本文本，Player 拥有运行时行为。遵循修订、模板、捕获和脚本编写的路由防护措施。

交接前，确认范围、回读、所有权、适用的视觉／运行时证据、清理情况、最终状态和租约释放情况。区分模型验证、捕获的外观（包括单独的 Player 实例）、同一会话中的载荷传播和 Control App 测试；遵循针对特定证据的完成流程。将未经验证的行为报告为待处理。