@playcraft/cli 0.1.67 → 0.1.68

package/project-template-v2/.playcraft/skills.lock.json

@@ -108,8 +108,8 @@
     },
     {
       "skillRef": "remix/playcraft-audio-generation",
-      "version": "1.3.0",
-      "artifactHash": "39e9a331a1f5b4ebe96a663fa845b41f2471be239610b12f9fca86c494e82665",
+      "version": "1.4.0",
+      "artifactHash": "d8ad3620ad8b8e383421b9a19bd7eeeea154dd8b1d2b1688687bcf31f6fde3c2",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-audio-generation"
     },

package/project-templates/phaser/.claude/skills/playcraft-audio-generation/SKILL.md

@@ -3,7 +3,7 @@ name: playcraft-audio-generation
 description: Use when generating or replacing playable audio, reusing library audio, managing durable audio tasks, or locally compressing, trimming, looping, normalizing, and mixing sound.
 triggers: 生成音效,生成bgm,生成背景音乐,generate sfx,generate bgm,generate audio,音频,音效,背景音乐,sfx,bgm,loop音频,音频压缩,音频处理,audio,compress audio,fade,normalize,音频后处理,音频管线
 compatibility: agent,opencode
-version: 1.3.0
+version: 1.4.0
 surfaces:
   - sandbox-agent
 ---
@@ -16,7 +16,7 @@ AI (Artificial Intelligence, 人工智能) 音频包含 SFX (Sound Effects, 音
 
 ### 云工作区的可编辑短音效
 
-仅在当前锁定技能版本与工作区能力支持时使用本段流程。先运行 `playcraft audio source capabilities`，检查 `enabled`、`writable`、对应 `operations`；生成与渲染还须 `renderer.ready`。能力缺失或关闭时保留源及已有试听，报告不可用，不替换工程技能锁，不移除声音上下文后继续执行。`synth-sfx` 保持短音效流程；仅在 `audioScoreVersion:1` 与 `audioScoreContextVersion:1` 均声明时使用下述乐谱／多轨流程。外部采样和动态混合仍不支持。
+仅在当前锁定技能版本与工作区能力支持时使用本段流程。先运行 `playcraft audio source capabilities`，检查 `enabled`、`writable`、对应 `operations`；生成与渲染还须 `renderer.ready`。能力缺失或关闭时保留源及已有试听，报告不可用，不替换工程技能锁，不移除声音上下文后继续执行。`synth-sfx` 保持短音效流程；仅在 `audioScoreVersion:1` 与 `audioScoreContextVersion:1` 均声明时使用下述乐谱／多轨流程。动态混合使用独立高级程序入口，不写入既有音效或乐谱源。
 
 默认从描述、试听、采用开始，只展示适用的时长、音量、音高、明亮度简单控件；用户要求细节后再展开精确参数。工程源在 `source/audio/` 等 `dist/` 外目录，最终表示包位于 `dist/audio/`。未采用候选保持私有，不因续改而强制写入工程。
 
@@ -84,6 +84,24 @@ playcraft audio source adopt --task <taskId> --candidate <candidateId> \
 
 音乐完整包成员为 `sound.pcscore.json / audition.wav / runtime.mjs / sound.mjs / manifest.json`，只使用回执中的固定模块。`createSound().prepare()` 不默认展开整段音乐采样；`play()` 按乐谱和循环段调度，返回的 `stop()` 或播放器 `stop()/dispose()` 会结束循环并释放资源。场景退出、页面隐藏或切换试听时应调用停止，禁止遗留循环。单次播放可传 `play({loop:false})`；指定段落或轨道试听通过受支持的 `selection` 参数。试听渲染文件本身是完整单次表示，循环起止需随乐谱一起使用。
 
+### 高级：游戏状态与短采样混合
+
+用户明确要求按游戏状态改变声音，或组合短采样与合成音时，先检查 `playcraft audio program --help` 是否存在。旧工作区不支持该命令时保留现有源和技能锁并报告。不要为普通生成和简单调整主动创建音频程序。
+
+```bash
+# --asset 必须是采用回执中的完整不可变声音包成员；可选 --sample 是 dist/audio 中有摘要目录的短采样。
+playcraft audio program init --asset <sound.pcscore.json或sound.pcaudio.json固定路径> --output source/audio/states.pcaudioprogram.json
+playcraft audio program validate --path source/audio/states.pcaudioprogram.json
+playcraft audio program compile --path source/audio/states.pcaudioprogram.json
+playcraft audio program inspect --manifest <编译回执manifestPath>
+```
+
+程序是独立的 `playcraft.audio-program@1`，最多 8 项资产、16 个离散状态、每状态 4 层及 60 秒。状态明确指定增益、半音、低通与乐谱拍段；切换采用停止并重启语义，不承诺无缝交叉淡化。短采样只接受单声道 44100 Hz、PCM（Pulse Code Modulation，脉冲编码调制）16 位标准波形文件，每个最多 2 秒、最多 4 个；不接受外部地址或任意脚本。依赖必须带精确路径、内容摘要和大小。编译会校验完整声音包及平台引擎，渲染所有状态并拒绝超峰值；不静默截断或归一化。全部状态波形总量限 16 MiB，输入依赖限 2 MiB。
+
+从编译回执的 `runtimeModulePath` 导入 `createSound`，在明确交互中 `await player.play('idle')`；状态变化时 `await player.setState('action')`。切换场景或页面隐藏时停止，销毁时 `dispose()`。`prerenderModulePath` 使用同一接口，已把音高、滤波和混合烘焙到各状态波形，播放不重复处理；两种方案仍要求浏览器支持音频上下文。模块与共享引擎均不可变，修改程序后重新编译，保留旧模块用于回退。只修改 `dist/audio` 包内文件会触发校验失败。
+
+渠道选型必须按完整实际构建产物字节数比较，包括运行时、嵌入依赖和波形；源 JSON（JavaScript Object Notation，JavaScript 对象表示法）大小不能代表最终压缩收益。未知渠道能力采用保守回退，渠道不支持音频上下文时不能宣称预渲染模块可用。完整渠道包通过平台交付页生成与下载，不保存到工作区 `dist/`。
+
 ### 复用素材与持久化音频任务
 
 ```bash

package/project-templates/threejs/.claude/skills/playcraft-audio-generation/SKILL.md

@@ -3,7 +3,7 @@ name: playcraft-audio-generation
 description: Use when generating or replacing playable audio, reusing library audio, managing durable audio tasks, or locally compressing, trimming, looping, normalizing, and mixing sound.
 triggers: 生成音效,生成bgm,生成背景音乐,generate sfx,generate bgm,generate audio,音频,音效,背景音乐,sfx,bgm,loop音频,音频压缩,音频处理,audio,compress audio,fade,normalize,音频后处理,音频管线
 compatibility: agent,opencode
-version: 1.3.0
+version: 1.4.0
 surfaces:
   - sandbox-agent
 ---
@@ -16,7 +16,7 @@ AI (Artificial Intelligence, 人工智能) 音频包含 SFX (Sound Effects, 音
 
 ### 云工作区的可编辑短音效
 
-仅在当前锁定技能版本与工作区能力支持时使用本段流程。先运行 `playcraft audio source capabilities`，检查 `enabled`、`writable`、对应 `operations`；生成与渲染还须 `renderer.ready`。能力缺失或关闭时保留源及已有试听，报告不可用，不替换工程技能锁，不移除声音上下文后继续执行。`synth-sfx` 保持短音效流程；仅在 `audioScoreVersion:1` 与 `audioScoreContextVersion:1` 均声明时使用下述乐谱／多轨流程。外部采样和动态混合仍不支持。
+仅在当前锁定技能版本与工作区能力支持时使用本段流程。先运行 `playcraft audio source capabilities`，检查 `enabled`、`writable`、对应 `operations`；生成与渲染还须 `renderer.ready`。能力缺失或关闭时保留源及已有试听，报告不可用，不替换工程技能锁，不移除声音上下文后继续执行。`synth-sfx` 保持短音效流程；仅在 `audioScoreVersion:1` 与 `audioScoreContextVersion:1` 均声明时使用下述乐谱／多轨流程。动态混合使用独立高级程序入口，不写入既有音效或乐谱源。
 
 默认从描述、试听、采用开始，只展示适用的时长、音量、音高、明亮度简单控件；用户要求细节后再展开精确参数。工程源在 `source/audio/` 等 `dist/` 外目录，最终表示包位于 `dist/audio/`。未采用候选保持私有，不因续改而强制写入工程。
 
@@ -84,6 +84,24 @@ playcraft audio source adopt --task <taskId> --candidate <candidateId> \
 
 音乐完整包成员为 `sound.pcscore.json / audition.wav / runtime.mjs / sound.mjs / manifest.json`，只使用回执中的固定模块。`createSound().prepare()` 不默认展开整段音乐采样；`play()` 按乐谱和循环段调度，返回的 `stop()` 或播放器 `stop()/dispose()` 会结束循环并释放资源。场景退出、页面隐藏或切换试听时应调用停止，禁止遗留循环。单次播放可传 `play({loop:false})`；指定段落或轨道试听通过受支持的 `selection` 参数。试听渲染文件本身是完整单次表示，循环起止需随乐谱一起使用。
 
+### 高级：游戏状态与短采样混合
+
+用户明确要求按游戏状态改变声音，或组合短采样与合成音时，先检查 `playcraft audio program --help` 是否存在。旧工作区不支持该命令时保留现有源和技能锁并报告。不要为普通生成和简单调整主动创建音频程序。
+
+```bash
+# --asset 必须是采用回执中的完整不可变声音包成员；可选 --sample 是 dist/audio 中有摘要目录的短采样。
+playcraft audio program init --asset <sound.pcscore.json或sound.pcaudio.json固定路径> --output source/audio/states.pcaudioprogram.json
+playcraft audio program validate --path source/audio/states.pcaudioprogram.json
+playcraft audio program compile --path source/audio/states.pcaudioprogram.json
+playcraft audio program inspect --manifest <编译回执manifestPath>
+```
+
+程序是独立的 `playcraft.audio-program@1`，最多 8 项资产、16 个离散状态、每状态 4 层及 60 秒。状态明确指定增益、半音、低通与乐谱拍段；切换采用停止并重启语义，不承诺无缝交叉淡化。短采样只接受单声道 44100 Hz、PCM（Pulse Code Modulation，脉冲编码调制）16 位标准波形文件，每个最多 2 秒、最多 4 个；不接受外部地址或任意脚本。依赖必须带精确路径、内容摘要和大小。编译会校验完整声音包及平台引擎，渲染所有状态并拒绝超峰值；不静默截断或归一化。全部状态波形总量限 16 MiB，输入依赖限 2 MiB。
+
+从编译回执的 `runtimeModulePath` 导入 `createSound`，在明确交互中 `await player.play('idle')`；状态变化时 `await player.setState('action')`。切换场景或页面隐藏时停止，销毁时 `dispose()`。`prerenderModulePath` 使用同一接口，已把音高、滤波和混合烘焙到各状态波形，播放不重复处理；两种方案仍要求浏览器支持音频上下文。模块与共享引擎均不可变，修改程序后重新编译，保留旧模块用于回退。只修改 `dist/audio` 包内文件会触发校验失败。
+
+渠道选型必须按完整实际构建产物字节数比较，包括运行时、嵌入依赖和波形；源 JSON（JavaScript Object Notation，JavaScript 对象表示法）大小不能代表最终压缩收益。未知渠道能力采用保守回退，渠道不支持音频上下文时不能宣称预渲染模块可用。完整渠道包通过平台交付页生成与下载，不保存到工作区 `dist/`。
+
 ### 复用素材与持久化音频任务
 
 ```bash