Blender Harness 调用规范

本技能定义驱动 Blender 的唯一执行通道（WorkBuddy 团队与单插件用户通用）。它是平台无关的：启动器 + JSON 命令行客户端 + 运行在 Blender 内的结构化命令注册表。所有命令契约、回执 schema 与验收阈值以本插件随附的 blender-production 技能参考文档为准。

1. 定位插件目录

本技能位于 <插件根>/skills/blender-harness/SKILL.md。插件根目录（含 scripts/、schemas/、config/）即执行入口所在：

<插件根>/scripts/launch_harness.py     # 启动托管会话
<插件根>/scripts/harness_cli.py        # 向会话派发命令

在 shell 中用 pwd/ls 确认实际路径后再执行；不要凭记忆猜路径。

2. 启动会话（每个生产任务一次）

mkdir -p <输出根目录>            # 所有产物必须落在该授权目录内
python3 <插件根>/scripts/launch_harness.py \
    --session-id <唯一会话ID> \
    --output-root <输出根目录的绝对路径> \
    --execution-mode auto_with_budget

• Blender 可执行文件自动发现（PATH 或 /Applications/Blender.app/Contents/MacOS/Blender）；装在别处时传 --blender <路径>。
• 启动成功后打印 descriptor（含 address、token、descriptorPath）。记下 descriptorPath——后续所有命令都要用它。
• 会话结束后按 descriptor 里的说明关闭；不要留孤儿 Blender 进程。

3. 派发命令

把请求写成 JSON 文件再发送（闭合契约，多余字段直接报 INVALID_REQUEST）：

{
  "protocolVersion": "codex-blender/v1",
  "sessionId": "<与会话一致>",
  "requestId": "<本次请求唯一ID>",
  "transactionId": "<事务ID>",
  "command": "mesh.inspect",
  "arguments": {}
}

python3 <插件根>/scripts/harness_cli.py \
    --descriptor <descriptorPath> --request <请求.json>

修改类命令必须走事务（读命令不需要）

凭空编造 transactionId 会得到 TRANSACTION_NOT_FOUND。正确序列：

1. transaction.begin（arguments 必须为空对象）→ 返回 snapshotId 与当前 sceneRevision。
2. 修改命令（如 object.create_mesh）：带同一 transactionId，并带 expectedSceneRevision = begin 返回的 revision；每次成功修改后 revision 递增，下一条命令要跟上。
3. transaction.commit（arguments 为空对象）→ 提交事务，快照进入已批准状态。
4. export.file：arguments.snapshotId 必须逐字等于 commit 批准的 snapshotId，否则报 MILESTONE_NOT_APPROVED。

规则：

• requestId 每次唯一；读命令（*.inspect、capability.*、查询类）不需要事务，也不需要 revision。
• 响应是 JSON：status 为 succeeded 时核对 result 与 changedObjects；failed 时读 error.code 与 error.message。

4. 常用错误码

5. 能力目录与成熟度

开工前先查，不要假设：

{"command": "capability.list", "arguments": {"domain": "mesh"}}
{"command": "capability.describe", "arguments": {"id": "export.file"}}

成熟度分层：L1 可查询（产物不可交付）、L3 可生产（有 runtime/visual/delivery 证据）、L4 可恢复生产。交付任务只允许 L3+ 命令产出。

6. 后台任务（长渲染/烘焙）

{"command": "job.submit", "arguments": {"jobId": "render_001", "kind": "RENDER_ANIMATION_FRAMES", "parameters": {...}}}
{"command": "job.status",  "arguments": {"jobId": "render_001"}}
{"command": "job.list",    "arguments": {"state": "running"}}

最大并发 2；第三个任务 FIFO 排队；磁盘保留 max(卷容量20%, 20GB)，超限时不落快照、不启进程。取消用 job.cancel。

7. 纪律

1. 回执是唯一事实——"应该成功了"不算数。
2. 每个验收断言都要能失败；测量值（计数/误差/哈希/探测）必须进汇报。
3. 门禁（gated/foreground）被拒就如实上报，不重试绕过。
4. 产物路径永远在授权输出根内；导出走 export.* 命令而不是直接写 Blender 设置。