@pippit-dev/cli 1.0.48 → 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/internal/generate_video/query_result.go

@@ -14,10 +14,54 @@ import (
 )
 
 const (
-	successRunState = 3
-	failedRunState  = 4
+	successRunState  = 3
+	failedRunState   = 4
+	canceledRunState = 5
 )
 
+// Query-result status values. "completed" stays a terminal flag; "status"
+// carries the machine-readable result so integrators need not parse text.
+const (
+	statusRunning   = "running"
+	statusSucceeded = "succeeded"
+	statusFailed    = "failed"
+	statusCanceled  = "canceled"
+	statusUnknown   = "unknown"
+)
+
+// runStateStatus maps the server-side run state (0-9) to the user-facing
+// status. Any unmapped value falls back to unknown instead of being guessed.
+var runStateStatus = map[int]string{
+	0: statusUnknown, // Unspecified
+	1: statusRunning, // Submitted
+	2: statusRunning, // Working
+	3: statusSucceeded,
+	4: statusFailed,
+	5: statusCanceled,
+	6: statusUnknown, // InputRequired
+	7: statusRunning, // Generating
+	8: statusRunning, // Interrupt
+	9: statusUnknown, // HITL_Interrupt
+}
+
+var terminalRunStates = map[int]struct{}{
+	successRunState:  {},
+	failedRunState:   {},
+	canceledRunState: {},
+}
+
+func statusForRunState(state int) string {
+	if s, ok := runStateStatus[state]; ok {
+		return s
+	}
+	return statusUnknown
+}
+
+func isTerminalRunState(state int) bool {
+	_, ok := terminalRunStates[state]
+	return ok
+}
+
 // QueryResultOptions is the command-facing request shape for query-result.
 type QueryResultOptions struct {
 	ThreadID    string
@@ -27,6 +71,7 @@ type QueryResultOptions struct {
 
 // QueryResultResult describes the user-facing query-result outcome.
 type QueryResultResult struct {
+	Status       string             `json:"status,omitempty"`
 	Completed    bool               `json:"completed"`
 	ThreadID     string             `json:"thread_id"`
 	RunID        string             `json:"run_id"`
@@ -112,10 +157,7 @@ func QueryResult(ctx context.Context, opts *QueryResultOptions, runner *common.R
 		RunID:    opts.RunID,
 	}, runner)
 	if err != nil {
-		if result, ok := queryResultFromGetThreadBusinessError(err, opts); ok {
-			return result, nil
-		}
-		return nil, fmt.Errorf("查询失败：%w", err)
+		return nil, queryResultQueryError(err)
 	}
 
 	thread, err := parseQueryThread(threadResult)
@@ -129,7 +171,8 @@ func QueryResult(ctx context.Context, opts *QueryResultOptions, runner *common.R
 	}
 	if run.State != successRunState {
 		result := &QueryResultResult{
-			Completed: run.State == failedRunState,
+			Status:    statusForRunState(run.State),
+			Completed: isTerminalRunState(run.State),
 			ThreadID:  firstNonEmpty(thread.ThreadID, opts.ThreadID),
 			RunID:     opts.RunID,
 			Videos:    []QueryResultVideo{},
@@ -209,6 +252,7 @@ func QueryResult(ctx context.Context, opts *QueryResultOptions, runner *common.R
 	}
 
 	return &QueryResultResult{
+		Status:    statusSucceeded,
 		Completed: true,
 		ThreadID:  firstNonEmpty(thread.ThreadID, opts.ThreadID),
 		RunID:     opts.RunID,
@@ -217,26 +261,39 @@ func QueryResult(ctx context.Context, opts *QueryResultOptions, runner *common.R
 	}, nil
 }
 
-func queryResultFromGetThreadBusinessError(err error, opts *QueryResultOptions) (*QueryResultResult, bool) {
+// queryResultQueryError converts a get_thread failure into a Go error while
+// keeping a clean, customer-facing message. The command layer maps it to
+// status=unknown; the technical envelope stays in the local error log.
+func queryResultQueryError(err error) error {
 	var logErr *common.LogIDError
-	if !errors.As(err, &logErr) {
-		return nil, false
-	}
-	message := getThreadBusinessErrorMessage(logErr.Message)
-	if message == "" {
-		message = "查询失败"
-	}
-	if logID := logErr.LogID(); logID != "" {
-		message = fmt.Sprintf("%s log_id=%s", message, logID)
+	if errors.As(err, &logErr) {
+		message := getThreadBusinessErrorMessage(logErr.Message)
+		if message == "" {
+			message = "查询失败"
+		}
+		if logID := logErr.LogID(); logID != "" {
+			return fmt.Errorf("%s log_id=%s", message, logID)
+		}
+		return fmt.Errorf("%s", message)
 	}
-	return &QueryResultResult{
-		Completed:    true,
-		ThreadID:     opts.ThreadID,
-		RunID:        opts.RunID,
-		ErrorMessage: message,
+	return fmt.Errorf("查询失败：%w", err)
+}
+
+// NewQueryResultError builds the user-facing result for a failed query. A
+// failed call never produces a run status, so it reports unknown rather than
+// guessing; the concrete cause stays in error_message.
+func NewQueryResultError(err error, opts *QueryResultOptions) *QueryResultResult {
+	result := &QueryResultResult{
+		Status:       statusUnknown,
+		ErrorMessage: err.Error(),
 		Videos:       []QueryResultVideo{},
 		Images:       []QueryResultImage{},
-	}, true
+	}
+	if opts != nil {
+		result.ThreadID = strings.TrimSpace(opts.ThreadID)
+		result.RunID = strings.TrimSpace(opts.RunID)
+	}
+	return result
 }
 
 func getThreadBusinessErrorMessage(message string) string {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pippit-dev/cli",
-  "version": "1.0.48",
+  "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));
 }