@playcraft/cli 0.1.67 → 0.1.69

package/project-template/.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-template/.claude/skills/playcraft-workspace-assets/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: playcraft-workspace-assets
-description: Use when finding or downloading shared library assets, or creating and managing durable image, audio, sprite, animation, model, or video generation tasks in a PlayCraft cloud workspace.
+description: Use when selecting 3D asset kits, finding or downloading shared library assets, or managing durable media generation tasks in a PlayCraft cloud workspace.
 compatibility: agent,opencode
-version: 1.0.0
+version: 1.1.0
 surfaces:
   - sandbox-agent
 ---
@@ -13,6 +13,17 @@ surfaces:
 
 ## 查找并复用素材
 
+一组三维物件的检索入口为素材包；包内覆盖结果给出逐项可用模型及缺口：
+
+```bash
+playcraft library kits --search "家具" --json
+playcraft library kit kenney-furniture-kit --needs "椅子,桌子,打印机" --json
+```
+
+素材包是主题与风格的逻辑集合，区别于一起下载的文件集合及版权来源归档。`coverageScope: partial` 表示仅部分收录；`members` 才是当前可用模型及确切版本，`needCoverage` 返回同包每项需求的候选或缺口。`inventoryRevision` 只标识当前库存，不是持久保存的历史整包版本。`styleGuidance` 提供设计参照，`compatibility` 未验证的单位、朝向和连接规则不能用于兼容性承诺；生成供应商不会自动匹配该风格。
+
+包内模型和独立素材都使用以下单素材入口。模型下载加 `--revision-id <revisionId>`，保留命令生成的 `.playcraft/asset-provenance.json`、许可和来源说明；工程文件路径、模型版本与来源记录共同标识实际使用实例。
+
 ```bash
 playcraft library search "角色" --type texture --tags character --limit 20 --json
 playcraft library facets --json
@@ -21,9 +32,9 @@ playcraft library files <assetId> --json
 playcraft library download <assetId> --output ./assets/character
 ```
 
-检索字段是名称、素材库路径和标签；还可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。不要把下载预览图当作完整素材包。
+检索字段是名称、素材库路径和标签，已审核模型还支持别名、用途、许可及能力筛选；也可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。预览图不能代替模型或其依赖。
 
-`--output` 对单文件表示文件路径，对素材包表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。素材包包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
+`--output` 对单文件表示文件路径，对文件集合表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。文件集合包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
 
 ## 创建持久化生成任务
 

package/project-template-v2/.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-template-v2/.claude/skills/playcraft-workspace-assets/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: playcraft-workspace-assets
-description: Use when finding or downloading shared library assets, or creating and managing durable image, audio, sprite, animation, model, or video generation tasks in a PlayCraft cloud workspace.
+description: Use when selecting 3D asset kits, finding or downloading shared library assets, or managing durable media generation tasks in a PlayCraft cloud workspace.
 compatibility: agent,opencode
-version: 1.0.0
+version: 1.1.0
 surfaces:
   - sandbox-agent
 ---
@@ -13,6 +13,17 @@ surfaces:
 
 ## 查找并复用素材
 
+一组三维物件的检索入口为素材包；包内覆盖结果给出逐项可用模型及缺口：
+
+```bash
+playcraft library kits --search "家具" --json
+playcraft library kit kenney-furniture-kit --needs "椅子,桌子,打印机" --json
+```
+
+素材包是主题与风格的逻辑集合，区别于一起下载的文件集合及版权来源归档。`coverageScope: partial` 表示仅部分收录；`members` 才是当前可用模型及确切版本，`needCoverage` 返回同包每项需求的候选或缺口。`inventoryRevision` 只标识当前库存，不是持久保存的历史整包版本。`styleGuidance` 提供设计参照，`compatibility` 未验证的单位、朝向和连接规则不能用于兼容性承诺；生成供应商不会自动匹配该风格。
+
+包内模型和独立素材都使用以下单素材入口。模型下载加 `--revision-id <revisionId>`，保留命令生成的 `.playcraft/asset-provenance.json`、许可和来源说明；工程文件路径、模型版本与来源记录共同标识实际使用实例。
+
 ```bash
 playcraft library search "角色" --type texture --tags character --limit 20 --json
 playcraft library facets --json
@@ -21,9 +32,9 @@ playcraft library files <assetId> --json
 playcraft library download <assetId> --output ./assets/character
 ```
 
-检索字段是名称、素材库路径和标签；还可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。不要把下载预览图当作完整素材包。
+检索字段是名称、素材库路径和标签，已审核模型还支持别名、用途、许可及能力筛选；也可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。预览图不能代替模型或其依赖。
 
-`--output` 对单文件表示文件路径，对素材包表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。素材包包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
+`--output` 对单文件表示文件路径，对文件集合表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。文件集合包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
 
 ## 创建持久化生成任务
 

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"
     },
@@ -171,8 +171,8 @@
     },
     {
       "skillRef": "remix/playcraft-workspace-assets",
-      "version": "1.0.0",
-      "artifactHash": "f098949b043a229e561d92a34c3a65b44ffbd83d1758ef30ac09d2d0d5ea2570",
+      "version": "1.1.0",
+      "artifactHash": "bb8d3c17953e85e006f5de75bd267d29ea9cef329298d169ba57e11f59f4f21e",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-workspace-assets"
     }

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/phaser/.claude/skills/playcraft-workspace-assets/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: playcraft-workspace-assets
-description: Use when finding or downloading shared library assets, or creating and managing durable image, audio, sprite, animation, model, or video generation tasks in a PlayCraft cloud workspace.
+description: Use when selecting 3D asset kits, finding or downloading shared library assets, or managing durable media generation tasks in a PlayCraft cloud workspace.
 compatibility: agent,opencode
-version: 1.0.0
+version: 1.1.0
 surfaces:
   - sandbox-agent
 ---
@@ -13,6 +13,17 @@ surfaces:
 
 ## 查找并复用素材
 
+一组三维物件的检索入口为素材包；包内覆盖结果给出逐项可用模型及缺口：
+
+```bash
+playcraft library kits --search "家具" --json
+playcraft library kit kenney-furniture-kit --needs "椅子,桌子,打印机" --json
+```
+
+素材包是主题与风格的逻辑集合，区别于一起下载的文件集合及版权来源归档。`coverageScope: partial` 表示仅部分收录；`members` 才是当前可用模型及确切版本，`needCoverage` 返回同包每项需求的候选或缺口。`inventoryRevision` 只标识当前库存，不是持久保存的历史整包版本。`styleGuidance` 提供设计参照，`compatibility` 未验证的单位、朝向和连接规则不能用于兼容性承诺；生成供应商不会自动匹配该风格。
+
+包内模型和独立素材都使用以下单素材入口。模型下载加 `--revision-id <revisionId>`，保留命令生成的 `.playcraft/asset-provenance.json`、许可和来源说明；工程文件路径、模型版本与来源记录共同标识实际使用实例。
+
 ```bash
 playcraft library search "角色" --type texture --tags character --limit 20 --json
 playcraft library facets --json
@@ -21,9 +32,9 @@ playcraft library files <assetId> --json
 playcraft library download <assetId> --output ./assets/character
 ```
 
-检索字段是名称、素材库路径和标签；还可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。不要把下载预览图当作完整素材包。
+检索字段是名称、素材库路径和标签，已审核模型还支持别名、用途、许可及能力筛选；也可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。预览图不能代替模型或其依赖。
 
-`--output` 对单文件表示文件路径，对素材包表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。素材包包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
+`--output` 对单文件表示文件路径，对文件集合表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。文件集合包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
 
 ## 创建持久化生成任务
 

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

package/project-templates/threejs/.claude/skills/playcraft-workspace-assets/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: playcraft-workspace-assets
-description: Use when finding or downloading shared library assets, or creating and managing durable image, audio, sprite, animation, model, or video generation tasks in a PlayCraft cloud workspace.
+description: Use when selecting 3D asset kits, finding or downloading shared library assets, or managing durable media generation tasks in a PlayCraft cloud workspace.
 compatibility: agent,opencode
-version: 1.0.0
+version: 1.1.0
 surfaces:
   - sandbox-agent
 ---
@@ -13,6 +13,17 @@ surfaces:
 
 ## 查找并复用素材
 
+一组三维物件的检索入口为素材包；包内覆盖结果给出逐项可用模型及缺口：
+
+```bash
+playcraft library kits --search "家具" --json
+playcraft library kit kenney-furniture-kit --needs "椅子,桌子,打印机" --json
+```
+
+素材包是主题与风格的逻辑集合，区别于一起下载的文件集合及版权来源归档。`coverageScope: partial` 表示仅部分收录；`members` 才是当前可用模型及确切版本，`needCoverage` 返回同包每项需求的候选或缺口。`inventoryRevision` 只标识当前库存，不是持久保存的历史整包版本。`styleGuidance` 提供设计参照，`compatibility` 未验证的单位、朝向和连接规则不能用于兼容性承诺；生成供应商不会自动匹配该风格。
+
+包内模型和独立素材都使用以下单素材入口。模型下载加 `--revision-id <revisionId>`，保留命令生成的 `.playcraft/asset-provenance.json`、许可和来源说明；工程文件路径、模型版本与来源记录共同标识实际使用实例。
+
 ```bash
 playcraft library search "角色" --type texture --tags character --limit 20 --json
 playcraft library facets --json
@@ -21,9 +32,9 @@ playcraft library files <assetId> --json
 playcraft library download <assetId> --output ./assets/character
 ```
 
-检索字段是名称、素材库路径和标签；还可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。不要把下载预览图当作完整素材包。
+检索字段是名称、素材库路径和标签，已审核模型还支持别名、用途、许可及能力筛选；也可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。预览图不能代替模型或其依赖。
 
-`--output` 对单文件表示文件路径，对素材包表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。素材包包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
+`--output` 对单文件表示文件路径，对文件集合表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。文件集合包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
 
 ## 创建持久化生成任务