@pippit-dev/cli 1.0.49 → 1.0.50

package/dist/xyq-canvas-command-runtime.cjs.LEGAL.txt

@@ -1,7 +1,7 @@
 XYQ Canvas Command Runtime - Bundled Software Notices
 
 Generated from the exact esbuild input graph. No build paths or timestamps are included.
-12 Pippit first-party modules are bundled and are not listed by internal package name.
+14 Pippit first-party modules are bundled and are not listed by internal package name.
 
 ===== @babel/runtime@7.29.7 =====
 License metadata: MIT
@@ -546,32 +546,6 @@ maintained libraries used by this software which have their own
 licenses; we recommend you read them, as their terms may differ from the
 terms above.
 
-===== three@0.184.0 =====
-License metadata: MIT
-
---- LICENSE ---
-The MIT License
-
-Copyright © 2010-2026 three.js authors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
-
 ===== tslib@2.6.2 =====
 License metadata: 0BSD
 

package/dist/xyq-canvas-command-runtime.cjs.sha256

@@ -1,2 +1,2 @@
-8e14b9a2c496491c2ee44da3ed950ac8301b67981dfaba3ab1e042cf8b937298  xyq-canvas-command-runtime.cjs
-3b97217c41dfb3c298185c80b1e70c2b469f552450e53d00fc1dcf7098740ffb  xyq-canvas-command-runtime.cjs.LEGAL.txt
+1c53a5f869ee7c148e9f993e318d4ea5b34c5e93e2ac0749dd3f47ecff946e4f  xyq-canvas-command-runtime.cjs
+c547c923eaf2e8c155f84aed934f42ad02855d669e8c0a890e38d049bc1ef8e7  xyq-canvas-command-runtime.cjs.LEGAL.txt

package/internal/canvas/image_binding.go

@@ -0,0 +1,152 @@
+package canvas
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"reflect"
+	"strconv"
+	"strings"
+)
+
+var imageSubjectFields = []string{"appearanceinfo", "sourceinfos"}
+
+func isImageSubjectField(field string) bool {
+	name := strings.ToLower(field)
+	return name == imageSubjectFields[0] || name == imageSubjectFields[1]
+}
+
+func nodeBindingContent(node map[string]json.RawMessage) map[string]json.RawMessage {
+	raw, _ := identityField(node, "content")
+	var content map[string]json.RawMessage
+	_ = json.Unmarshal(raw, &content)
+	return content
+}
+
+func decodeBindingValue(raw json.RawMessage) any {
+	decoder := json.NewDecoder(bytes.NewReader(raw))
+	decoder.UseNumber()
+	var value any
+	_ = decoder.Decode(&value)
+	return value
+}
+
+func hasSubjectBinding(value any) bool {
+	switch value := value.(type) {
+	case nil:
+		return false
+	case string:
+		return strings.TrimSpace(value) != ""
+	case []any:
+		return len(value) > 0
+	case map[string]any:
+		return len(value) > 0
+	default:
+		return true
+	}
+}
+
+func replacesImageSubjectBinding(patch PatchEntry) bool {
+	if patch.Path != "" || patch.Op != "replace" {
+		return false
+	}
+	var node map[string]json.RawMessage
+	if json.Unmarshal(patch.Value, &node) != nil {
+		return false
+	}
+	kind, _ := identityString(node, "type")
+	if kind != "biz/image" {
+		return false
+	}
+	for field, raw := range nodeBindingContent(node) {
+		if isImageSubjectField(field) && hasSubjectBinding(decodeBindingValue(raw)) {
+			return true
+		}
+	}
+	return false
+}
+
+// Legacy fields may be retained or cleared, but new image bindings use the
+// image protocol. Do not infer a role/scene conversion from arbitrary content.
+func validateImageSubjectBinding(nodeID string, node, previous map[string]json.RawMessage) error {
+	content := nodeBindingContent(node)
+	oldContent := nodeBindingContent(previous)
+	oldType, _ := identityString(previous, "type")
+	for field, raw := range content {
+		if !isImageSubjectField(field) {
+			continue
+		}
+		value := decodeBindingValue(raw)
+		if !hasSubjectBinding(value) {
+			continue
+		}
+		if oldType == "biz/image" && reflect.DeepEqual(value, decodeBindingValue(oldContent[field])) {
+			continue
+		}
+		return mediaIdentityError(nodeID, "/content/"+field,
+			"biz/image cannot bind role/scene content; use content.pippitAssetId for an image or a biz/role or biz/scene node")
+	}
+	return nil
+}
+
+// Project only the selected identity subtree, including nested subject fields.
+// RFC 6902 array operations must not collapse a child patch into its parent.
+func projectMediaIdentityValue(raw json.RawMessage, parts []string, patch PatchEntry) (json.RawMessage, error) {
+	if len(parts) == 0 {
+		return patch.Value, nil
+	}
+	value := bytes.TrimSpace(raw)
+	if len(value) == 0 {
+		return nil, fmt.Errorf("cannot validate a media identity without its content base")
+	}
+	key := parts[0]
+	if value[0] == '{' {
+		var object map[string]json.RawMessage
+		if err := json.Unmarshal(value, &object); err != nil {
+			return nil, err
+		}
+		if len(parts) == 1 && patch.Op == "remove" {
+			delete(object, key)
+		} else {
+			next, err := projectMediaIdentityValue(object[key], parts[1:], patch)
+			if err != nil {
+				return nil, err
+			}
+			object[key] = next
+		}
+		return json.Marshal(object)
+	}
+	if value[0] != '[' {
+		return nil, fmt.Errorf("cannot validate a nested identity patch on a scalar")
+	}
+	var array []json.RawMessage
+	if err := json.Unmarshal(value, &array); err != nil {
+		return nil, err
+	}
+	index, err := strconv.Atoi(key)
+	if key == "-" && len(parts) == 1 && patch.Op == "add" {
+		index, err = len(array), nil
+	}
+	if err != nil || index < 0 || index > len(array) || (len(key) > 1 && key[0] == '0') {
+		return nil, fmt.Errorf("invalid media identity array index %q", key)
+	}
+	if len(parts) == 1 && patch.Op == "add" {
+		array = append(array, nil)
+		copy(array[index+1:], array[index:])
+		array[index] = patch.Value
+	} else {
+		if index == len(array) {
+			return nil, fmt.Errorf("media identity array index %q does not exist", key)
+		}
+		if len(parts) == 1 && patch.Op == "remove" {
+			array = append(array[:index], array[index+1:]...)
+		} else {
+			next, err := projectMediaIdentityValue(array[index], parts[1:], patch)
+			if err != nil {
+				return nil, err
+			}
+			array[index] = next
+		}
+	}
+	return json.Marshal(array)
+}

package/internal/canvas/image_binding_test.go

@@ -0,0 +1,137 @@
+package canvas
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/Pippit-dev/pippit-cli/internal/common"
+)
+
+func imageBindingFixture(node string, patches []PatchEntry) (ApplyOptions, *common.Runner, *int) {
+	opts, _, writes := applyIdentityFixture(patches, imageMaterial())
+	client := &fakeClient{send: func(_ context.Context, path string, body, out any) error {
+		switch path {
+		case QueryPath:
+			request := body.(queryRequest)
+			var assets []json.RawMessage
+			for _, id := range request.PippitAssetIDs {
+				if id == testNodeID {
+					content, _ := json.Marshal(node)
+					assets = append(assets, json.RawMessage(fmt.Sprintf(`{"PippitAssetID":"%s","TextInfo":{"content":%s},"version":5}`, id, content)))
+				} else if id == testPippitID {
+					assets = append(assets, json.RawMessage(imageMaterial()))
+				}
+			}
+			payload, _ := json.Marshal(map[string]any{"ret": "0", "data": map[string]any{"Assets": assets}})
+			return decodeInto(out, string(payload))
+		case ApplyPath:
+			*writes++
+			return decodeInto(out, fmt.Sprintf(`{"ret":"0","data":{"results":[{"transaction_id":"tx","status":"ack","asset_versions":{"%s":6}}]}}`, testNodeID))
+		default:
+			return fmt.Errorf("unexpected request %s", path)
+		}
+	}}
+	return opts, runnerWithClient(client), writes
+}
+
+func bindingPatch(op, path, value string) PatchEntry {
+	return PatchEntry{AssetID: testNodeID, Op: op, Path: path, Value: json.RawMessage(value)}
+}
+
+func TestApplyMediaIdentityRejectsRoleFieldsOnImageBeforeWrite(t *testing.T) {
+	blank := `{"type":"biz/image","content":{"caption":"draft","generation":{}}}`
+	for _, test := range []struct {
+		name, node string
+		patches    []PatchEntry
+	}{
+		{"original-upload", blank, []PatchEntry{
+			bindingPatch("add", "/content/appearanceInfo", `{"pippitAssetId":"image-material"}`),
+			bindingPatch("add", "/content/generation", `{"source":"uploaded"}`),
+			bindingPatch("add", "/content/sourceInfos", `{"image-material":{"source":"uploaded"}}`),
+		}},
+		{"source-map", blank, []PatchEntry{bindingPatch("add", "/content/sourceInfos", `{"image-material":{}}`)}},
+		{"source-array", blank, []PatchEntry{bindingPatch("add", "/content/sourceInfos", `[{"pippitAssetId":"image-material"}]`)}},
+		{"root-create", "", []PatchEntry{bindingPatch("add", "", `{"type":"biz/image","content":{"appearanceInfo":{"pippitAssetId":"image-material"}}}`)}},
+		{"root-replace", blank, []PatchEntry{bindingPatch("replace", "", `{"type":"biz/image","content":{"sourceInfos":{"image-material":{}}}}`)}},
+		{"content-replace", blank, []PatchEntry{bindingPatch("replace", "/content", `{"appearanceInfo":{"candidateId":"candidate"}}`)}},
+		{"nested-appearance", `{"type":"biz/image","content":{"appearanceInfo":{}}}`, []PatchEntry{bindingPatch("add", "/content/appearanceInfo/pippitAssetId", `"image-material"`)}},
+		{"nested-source-map", `{"type":"biz/image","content":{"sourceInfos":{}}}`, []PatchEntry{bindingPatch("add", "/content/sourceInfos/material", `{"pippitAssetId":"image-material"}`)}},
+		{"nested-source-array", `{"type":"biz/image","content":{"sourceInfos":[]}}`, []PatchEntry{bindingPatch("add", "/content/sourceInfos/-", `{"pippitAssetId":"image-material"}`)}},
+		{"changed-legacy-field", `{"type":"biz/image","content":{"appearanceInfo":{"pippitAssetId":"old"}}}`, []PatchEntry{bindingPatch("replace", "/content/appearanceInfo/pippitAssetId", `"new"`)}},
+		{"remove-one-legacy-source", `{"type":"biz/image","content":{"sourceInfos":{"first":{},"second":{}}}}`, []PatchEntry{bindingPatch("remove", "/content/sourceInfos/first", "")}},
+		{"unchanged-direct-identities", string(imageNode(testMediaID)), []PatchEntry{bindingPatch("add", "/content/sourceInfos", `{"material":{}}`)}},
+		{"type-change", `{"type":"biz/role","content":{"appearanceInfo":{"pippitAssetId":"material"}}}`, []PatchEntry{bindingPatch("replace", "/type", `"biz/image"`)}},
+		{"case-alias", blank, []PatchEntry{bindingPatch("add", "/content/AppearanceInfo", `{"pippitAssetId":"material"}`)}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			opts, runner, writes := imageBindingFixture(test.node, test.patches)
+			_, err := Apply(context.Background(), opts, runner)
+			if err == nil || !strings.Contains(err.Error(), "INVALID_MEDIA_IDENTITY") || !strings.Contains(err.Error(), "/content/") || !strings.Contains(err.Error(), "content.pippitAssetId") {
+				t.Fatalf("expected corrective image binding error, got %v", err)
+			}
+			if *writes != 0 {
+				t.Fatalf("invalid image binding was sent %d times", *writes)
+			}
+		})
+	}
+}
+
+func TestApplyMediaIdentityPreservesImageDraftAndLegacyEdits(t *testing.T) {
+	legacy := `{"type":"biz/image","content":{"caption":"old","appearanceInfo":{"pippitAssetId":"material","candidateId":"candidate"},"sourceInfos":{"material":{}}}}`
+	for _, test := range []struct {
+		name, node string
+		patches    []PatchEntry
+	}{
+		{"blank-create", "", []PatchEntry{bindingPatch("add", "", `{"type":"biz/image","content":{"caption":"draft"}}`)}},
+		{"legacy-caption", legacy, []PatchEntry{bindingPatch("replace", "/content/caption", `"edited"`)}},
+		{"unchanged-content", legacy, []PatchEntry{bindingPatch("replace", "/content", `{"sourceInfos":{"material":{}},"appearanceInfo":{"candidateId":"candidate","pippitAssetId":"material"},"caption":"edited"}`)}},
+		{"unchanged-root", legacy, []PatchEntry{bindingPatch("replace", "", `{"type":"biz/image","content":{"sourceInfos":{"material":{}},"appearanceInfo":{"candidateId":"candidate","pippitAssetId":"material"},"caption":"edited"}}`)}},
+		{"unchanged-nested-field", legacy, []PatchEntry{bindingPatch("replace", "/content/appearanceInfo/pippitAssetId", `"material"`)}},
+		{"remove-field", legacy, []PatchEntry{bindingPatch("remove", "/content/appearanceInfo", "")}},
+		{"clear-object", legacy, []PatchEntry{bindingPatch("replace", "/content/appearanceInfo", `{}`)}},
+		{"clear-array", legacy, []PatchEntry{bindingPatch("replace", "/content/sourceInfos", `[]`)}},
+		{"clear-null", legacy, []PatchEntry{bindingPatch("replace", "/content/sourceInfos", `null`)}},
+		{"clear-blank", legacy, []PatchEntry{bindingPatch("replace", "/content/appearanceInfo", `" "`)}},
+		{"clear-last-object-key", `{"type":"biz/image","content":{"sourceInfos":{"a/b~c":{}}}}`, []PatchEntry{bindingPatch("remove", "/content/sourceInfos/a~1b~0c", "")}},
+		{"clear-last-array-item", `{"type":"biz/image","content":{"sourceInfos":[{"pippitAssetId":"material"}]}}`, []PatchEntry{bindingPatch("remove", "/content/sourceInfos/0", "")}},
+		{"final-role-type", `{"type":"biz/image","content":{}}`, []PatchEntry{
+			bindingPatch("add", "/content/appearanceInfo", `{"pippitAssetId":"material"}`),
+			bindingPatch("replace", "/type", `"biz/role"`),
+		}},
+		{"final-empty-binding", `{"type":"biz/image","content":{}}`, []PatchEntry{
+			bindingPatch("add", "/content/appearanceInfo", `{"pippitAssetId":"material"}`),
+			bindingPatch("remove", "/content/appearanceInfo", ""),
+		}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			opts, runner, writes := imageBindingFixture(test.node, test.patches)
+			if _, err := Apply(context.Background(), opts, runner); err != nil {
+				t.Fatal(err)
+			}
+			if *writes != 1 {
+				t.Fatalf("writes = %d", *writes)
+			}
+		})
+	}
+}
+
+func TestApplyMediaIdentityLeavesOtherNodeBindingsUnchanged(t *testing.T) {
+	for _, kind := range []string{"role", "scene", "audio", "video"} {
+		t.Run(kind, func(t *testing.T) {
+			node := fmt.Sprintf(`{"type":"biz/%s","content":{"appearanceInfo":{},"sourceInfos":[]}}`, kind)
+			opts, runner, writes := imageBindingFixture(node, []PatchEntry{
+				bindingPatch("add", "/content/appearanceInfo/pippitAssetId", `"material"`),
+				bindingPatch("add", "/content/sourceInfos/-", `{"pippitAssetId":"material"}`),
+			})
+			if _, err := Apply(context.Background(), opts, runner); err != nil {
+				t.Fatal(err)
+			}
+			if *writes != 1 {
+				t.Fatalf("writes = %d", *writes)
+			}
+		})
+	}
+}

package/internal/canvas/media_identity.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"maps"
 	"strings"
 
 	"github.com/Pippit-dev/pippit-cli/internal/common"
@@ -91,10 +92,17 @@ func cloudMediaID(raw json.RawMessage, kind string) (string, error) {
 }
 
 func touchesMediaIdentity(path string) bool {
-	switch strings.ToLower(path) {
+	normalized := strings.ToLower(path)
+	switch normalized {
 	case "", "/type", "/content", "/content/assetid", "/content/pippitassetid":
 		return true
 	}
+	for _, field := range imageSubjectFields {
+		prefix := "/content/" + field
+		if normalized == prefix || strings.HasPrefix(normalized, prefix+"/") {
+			return true
+		}
+	}
 	return false
 }
 
@@ -143,6 +151,9 @@ func projectIdentityPatch(node map[string]json.RawMessage, patch PatchEntry) (ma
 		return nil, fmt.Errorf("cannot validate a patch without its node base")
 	}
 	parts := strings.Split(strings.TrimPrefix(patch.Path, "/"), "/")
+	for index, part := range parts {
+		parts[index] = strings.NewReplacer("~1", "/", "~0", "~").Replace(part)
+	}
 	key := parts[0]
 	if len(parts) == 1 {
 		if patch.Op == "remove" {
@@ -152,16 +163,7 @@ func projectIdentityPatch(node map[string]json.RawMessage, patch PatchEntry) (ma
 		}
 		return node, nil
 	}
-	var content map[string]json.RawMessage
-	if err := json.Unmarshal(node[key], &content); err != nil || content == nil {
-		return nil, fmt.Errorf("cannot validate a media identity without its content base")
-	}
-	if patch.Op == "remove" {
-		delete(content, parts[1])
-	} else {
-		content[parts[1]] = patch.Value
-	}
-	value, err := json.Marshal(content)
+	value, err := projectMediaIdentityValue(node[key], parts[1:], patch)
 	if err != nil {
 		return nil, err
 	}
@@ -210,12 +212,13 @@ func validateApplyMediaIdentities(ctx context.Context, request ApplyRequest, run
 		if touchesMediaIdentity(patch.Path) && !affected[patch.AssetID] {
 			affected[patch.AssetID] = true
 			ordered = append(ordered, patch.AssetID)
-			if patch.Path != "" {
+			if patch.Path != "" || replacesImageSubjectBinding(patch) {
 				toQuery = append(toQuery, patch.AssetID)
 			}
 		}
 	}
 	nodes := make(map[string]map[string]json.RawMessage)
+	previousNodes := make(map[string]map[string]json.RawMessage)
 	type identity struct{ nodeID, kind, pippitID, mediaID string }
 	previous := make(map[string]identity)
 	if len(toQuery) > 0 {
@@ -230,6 +233,7 @@ func validateApplyMediaIdentities(ctx context.Context, request ApplyRequest, run
 				return mediaIdentityError(id, "/content", err.Error())
 			}
 			nodes[id] = node
+			previousNodes[id] = maps.Clone(node)
 			kind, pippitID, mediaID, readErr := readNodeIdentity(node)
 			if readErr == nil {
 				previous[id] = identity{id, kind, pippitID, mediaID}
@@ -254,6 +258,11 @@ func validateApplyMediaIdentities(ctx context.Context, request ApplyRequest, run
 		if err != nil {
 			return mediaIdentityError(nodeID, "/content", err.Error())
 		}
+		if kind == "image" {
+			if err := validateImageSubjectBinding(nodeID, nodes[nodeID], previousNodes[nodeID]); err != nil {
+				return err
+			}
+		}
 		if kind == "" || (pippitID == "" && mediaID == "") {
 			continue
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pippit-dev/cli",
-  "version": "1.0.49",
+  "version": "1.0.50",
   "description": "Pippit CLI",
   "bin": {
     "pippit-tool-cli": "scripts/run.js"

package/scripts/canvas-command-guides.js

@@ -76,13 +76,13 @@ const GUIDES = [
       "多轨 TimelineDraft 的时间字段使用整数微秒：1 秒 = 1000000 µs。输出 width/height 使用像素。草稿 duration 由片段推导；frameRate 当前只读，没有设置帧率 command。expectedRevision 是草稿版本号，不是时间。",
       "3D 关键帧与动作片段 startFrame/durationFrames 使用帧，timeline.fps 定义帧时长；move_keyframes.deltaFrames 是整数帧偏移。动作片段 trimStart/trimEnd 使用源动画秒数，可带小数，不是帧。",
       "通用 generate-video --duration 使用整数秒，由该视频入口处理；它不会在本地把故事板 duration-ms 标签自动转换成该参数。其模型/时长能力不能替代故事板当前模型约束。",
-      "ID 从所属查询取得：Timeline 的轨道/片段/来源 ID 由 xyq.timeline.query 返回；3D 对象/动画 ID 由 xyq.scene3d.query 返回。外层 nodeId 始终从当前 Canvas 节点查询取得。",
+      "ID 从所属查询取得：Timeline 的轨道/片段/来源 ID 由 xyq.timeline.query 返回；当前 CLI 未提供 3D V2 内部对象编辑入口。外层 nodeId 始终从当前 Canvas 节点查询取得。",
     ].join("\n\n"),
     next_commands: [
       "pippit-tool-cli canvas command guide storyboard",
       "pippit-tool-cli canvas command guide timeline",
       "pippit-tool-cli canvas command guide scene3d",
-      "pippit-tool-cli canvas command describe xyq.scene3d.apply --operation move_keyframes",
+      "pippit-tool-cli canvas command list",
     ],
     examples: [
       {
@@ -125,31 +125,21 @@ const GUIDES = [
   },
   {
     name: "scene3d",
-    summary: "3D 导演文档、对象 ID、空间与动画单位及编辑边界。",
+    summary: "3D V2 文档的能力边界、空间与动画单位。",
     content: [
-      "3D 导演台由外层 Canvas 节点和独立导演文档组成。create_biz_node 使用 nodeKind: scene3d；先 list 确认当前安装版本支持的命令，再 describe --node-kind 查看工厂参数。",
-      "xyq.scene3d.query 的 nodeId 是外层 Canvas 节点 ID；返回的对象、摄像机、关键帧等 ID 属于导演文档，不能与 Canvas 节点 ID 混用。先查询文档与可动画属性通道，再引用已有 ID。创建新对象时选文档内未占用的 ID。",
-      "xyq.scene3d.apply.operations 是 {command,args} 数组，command 使用现有 Scene3D SDK 命令名。describe --operation 查看一种操作及其 args，schema 可导出完整输入。dryRun:true 预演编辑，不改变原文档。",
-      "transform.position 使用米，rotation 为 XYZ Euler 角度，scale 为无单位 XYZ 倍率；camera FOV 使用角度。几何体 theta/phi/arc 等参数使用弧度，以对应 kind 的 schema 为准。",
-      "关键帧与 startFrame/durationFrames 使用帧，帧时长取决于 timeline.fps；动作片段 trimStart/trimEnd 使用源动画秒数，可为小数。不要把微秒、毫秒或旋转弧度填入帧或角度字段。",
-      "这套命令编辑导演文档；截图、渲染导出、上传与生成需要相应运行环境和现有入口。资源/动作引用应来自已查询到的真实资源，不用临时 URL 或虚构 ID 代替。",
+      "当前 SDK 主干的 3D 导演文档已迁移到 V2，旧 xyq.scene3d.apply/query 入口已移除。本版本不提供内部对象编辑命令，也不能通过通用资产补丁绕过该边界。内部编辑请使用 Web 3D 导演台。",
+      "外层节点仍可通过 create_biz_node 的 nodeKind: scene3d 创建；参数以 describe --node-kind 和当前 schema 为准。",
+      "transform.position 使用米，rotation 为 XYZ Euler 角度，scale 为无单位 XYZ 倍率；camera FOV 使用角度。几何体 theta/phi/arc 等参数使用弧度。",
+      "关键帧使用帧，帧时长取决于 timeline.fps；动作片段 trimStart/trimEnd 使用源动画秒数。此处仅说明单位，不代表 CLI 已提供编辑能力。",
     ].join("\n\n"),
     next_commands: [
+      "pippit-tool-cli canvas command list",
       "pippit-tool-cli canvas command describe create_biz_node --node-kind scene3d",
-      'pippit-tool-cli canvas command run xyq.scene3d.query --canvas-id CANVAS_ID --input \'{"nodeId":"DIRECTOR_NODE_ID"}\'',
-      "pippit-tool-cli canvas command describe xyq.scene3d.apply --operation create_node",
-      "pippit-tool-cli canvas command schema xyq.scene3d.apply",
     ],
     examples: [
       {
-        description: "填入真实外层 nodeId，并确保 camera-new 在导演文档内未占用，再预演创建摄像机。",
-        command:
-          "pippit-tool-cli canvas command run xyq.scene3d.apply --canvas-id CANVAS_ID --file ./scene3d-input.json",
-        input: {
-          nodeId: "DIRECTOR_NODE_ID",
-          operations: [{ command: "create_node", args: { kind: "camera", id: "camera-new", name: "Close-up" } }],
-          dryRun: true,
-        },
+        description: "只查询外层 3D 节点的创建 schema，不提交文档编辑。",
+        command: "pippit-tool-cli canvas command describe create_biz_node --node-kind scene3d",
       },
     ],
     related: ["time", "timeline"],
@@ -163,7 +153,9 @@ function listGuides() {
 function getGuide(name) {
   const guide = GUIDES.find((item) => item.name === name);
   if (!guide) {
-    throw new Error(`未知的画布指南：${String(name)}。运行 pippit-tool-cli canvas command guide 查看主题。`);
+    throw new Error(
+      `未知的画布指南：${String(name)}。运行 pippit-tool-cli canvas command guide 查看主题。`,
+    );
   }
   return JSON.parse(JSON.stringify(guide));
 }

package/scripts/canvas-command.js

@@ -674,6 +674,17 @@ function createDefinitions(sdk, runtime, allocateNodeId, queryMediaAsset) {
 }
 
 function ensureNodeRuntimeGlobals() {
+  if (typeof globalThis.DOMException !== "function") {
+    // Node 16 exposes its native DOMException through AbortSignal.reason,
+    // while newer Node versions also expose the constructor as a global.
+    const controller = new AbortController();
+    controller.abort();
+    Object.defineProperty(globalThis, "DOMException", {
+      configurable: true,
+      value: controller.signal.reason.constructor,
+      writable: true,
+    });
+  }
   if (typeof globalThis.structuredClone !== "function") {
     const { deserialize, serialize } = require("v8");
     Object.defineProperty(globalThis, "structuredClone", {

package/skills/xyq-nest-skill/commands/canvas.md

@@ -27,7 +27,8 @@
 | 读取画布和资产 | `get_snapshot`、`get_asset`、`get_permissions` | 取得真实节点/资产 ID，不用名称猜 ID |
 | 创建业务节点 | `create_biz_node` | 支持类型和初始字段用 `--node-kind` 查看；不要手拼业务节点结构 |
 | 节点位置、大小、样式、布局、分组 | `move_nodes`、`resize_node`、`set_node_style`、`align_nodes`、`arrange_nodes`、`group_nodes` 等 | 先查询目标和归属；删除与重排仅限用户请求范围 |
-| 连线和画布配置 | `create_edge`、`reconnect_edge`、`delete_edges`、`set_title`、`set_cover` 等 | 连线两端来自当前画布查询 |
+| 节点引用 | `create_biz_node`、`update_node_data` | 创建时用 `references: ["source-node-id"]`；更新时在 `generation.references` 声明 `{ "sourceNodeId": "source-node-id" }`，SDK 自动同步连线 |
+| 画布配置 | `set_title`、`set_cover` 等 | 参数以当前命令 schema 为准 |
 | 角色与场景资料 | `xyq.role.updateDescription/updateAppearance/updateSourceInfos`、`xyq.scene.updateDescription` | 用完整命令名分别 describe，遵守具体字段 |
 | 图片/视频节点提示词和已有引用 | `xyq.generation.update_prompt` | 先读 `guide prompt-references`；保留其他生成参数，不触发生成 |
 | 3D 导演台对象、摄像机、关键帧、动作 | `xyq.scene3d.query` / `xyq.scene3d.apply` | 先读 `guide scene3d` 和 `guide time` |
@@ -51,3 +52,7 @@ node "CANVAS_ENTRY" canvas command guide
 - 目前没有公开的故事板镜头增删排序、脚本保存、指定镜头生成领域命令；`guide storyboard` 是说明，不是执行能力。底层补丁不能替代这些业务流程。
 - 3D 和多轨命令编辑文档，不提供截图、渲染或最终视频导出。多轨时间为整数微秒，3D 动画时间区分帧和源动画秒；先查字段 schema。
 - 编辑后按 [画布查询、编辑与验证](../workflows/canvas-edit.md) 回读确认；无需使用媒体异步查询来判断画布写入成功。只有实际取得图片/视频文件时才进入媒体交付标准。
+
+图片和视频空节点会按 `initialData.generation.ratio` 预留尺寸，再参与排版。先创建节点、设置生成比例和引用，再布局，避免产物回填后挤占间距。已有媒体优先使用真实尺寸。
+
+替换 `generation` 时必须同时携带完整的 `references` 列表；空数组表示清空引用。仅修改提示词可用 `xyq.generation.update_prompt`。不再使用独立的创建、重连或删除连线命令；批量创建时让引用源节点排在目标节点之前。