@pippit-dev/cli 1.0.52 → 1.0.54

package/README.md

@@ -466,7 +466,11 @@ pippit-tool-cli query-result \
   --download-dir "./output"
 ```
 
-`query-result` 会查询指定 Run 并输出 JSON。Run 成功完成后下载视频和图片产物，`completed=true`、`status="succeeded"`，`videos` 和 `images` 中各包含 `download_url` 和 `output_path`；图片扩展名取自产物 `metadata.format`，缺省时兜底 `.png`。`status` 是机读状态，共 5 种取值：`running`（运行中，对应服务端已提交、处理中、生成中、程序中断等继续轮询的状态）、`succeeded`（成功）、`failed`（失败并填充 `error_message`）、`canceled`（已取消）、`unknown`（未指定、等待补充输入、人工交互中断等无法自动判定的状态）。`completed` 只表示是否到终态（成功、失败、已取消时为 true），判断成功失败请使用 `status`；查询或下载本身失败时 `status="unknown"`、`completed=false`，具体原因见 `error_message`。
+`query-result` 查询指定 Run 并输出 JSON，成功后下载视频和图片。`status` 支持 `running`、`succeeded`、`failed`、`canceled`、`input_required`、`interrupted`、`unknown`。`completed` 仅表示终态：成功、失败、取消和人工交互中断结束（state=9）为 true；等待补充输入（state=6）为 `input_required`、false，需要停止自动轮询并等待交互。程序中断／等待工具回调（state=8）仍为 `running`。
+
+判断优先级：无论查询接口 `ret` 为多少，只要能解析指定 Run，就使用其 `state`；失败原因优先读取 `fail_reason.message/code`。没有目标 Run 时，仅按此接口已核实的返回识别终态：`ret=5` 且 `errmsg` 为 `创作失败` 或以 `创作失败：` 开头，返回 `failed`、true；`ret=5` 且 `errmsg` 为 `创作已取消`，返回 `canceled`、true。其他查询错误（包括 `ret=5` 的 `获取会话信息失败`、`ret=1/2`、鉴权／团队权限、网络及解析错误）返回 `unknown`、false 并保留错误与可用的 LogID，不推断任务失败。当前接口的 `ret=2` 是参数错误，不代表安审失败。未指定或未知 Run 状态保持 `unknown`。已解析 Run 的非零接口返回也记录到本地错误日志。
+
+Run 已成功但产物缺失或下载失败时，保留 `succeeded`、true，在 `error_message` 中报告错误，并保留此前已成功下载的 `videos` / `images`。媒体项包含 `download_url` 和 `output_path`；图片扩展名取自 `metadata.format`，缺省为 `.png`。完整交付仍须检查错误及所有目标文件，不能只看 `completed=true`。
 
 ## Adapter 接入边界
 

package/checksums.txt

@@ -1,6 +1,6 @@
-edd2d8640d4a34b156d8c614ef5186ce91a6ea8778aee7b208d41296a840ef3f  pippit-tool-cli-1.0.52-darwin-amd64.tar.gz
-7b4b992088057f012851cd5c396d05239ad5fd6782bf93c3a7f9f5ae494b81fd  pippit-tool-cli-1.0.52-darwin-arm64.tar.gz
-aab287cc80ccab5f78f0f73df95d15b61d7e9e67205fb8b5e6386c22a35dc732  pippit-tool-cli-1.0.52-linux-amd64.tar.gz
-a9c86c8323d9f2a4859a0280095a7cac85cdf0e7fc59aa3bc758f99332bd387e  pippit-tool-cli-1.0.52-linux-arm64.tar.gz
-a0846db0ff0f2c61337c85f50f3b746ad9a6bd1ed2862df16399ba6dcc4257e7  pippit-tool-cli-1.0.52-windows-amd64.zip
-54dd5852b9597b3ad9405be0c63ebfa670b713c169f69649647b3afe5ed89fe1  pippit-tool-cli-1.0.52-windows-arm64.zip
+3027db71d4e1b89ccaaa50f4660fb41a90e578bf7c08f0ea1c28367a597371a1  pippit-tool-cli-1.0.54-darwin-amd64.tar.gz
+b6a932ae33085d565e88c21a39b446dcb21cf148b6fb66d5a5baa040896d98ae  pippit-tool-cli-1.0.54-darwin-arm64.tar.gz
+aabce0e36f96a1dcc29c24a277e85859e938f6eddc4ed74a0536df3e4e4bce23  pippit-tool-cli-1.0.54-linux-amd64.tar.gz
+beb74396a2d82e05f7199b05cdd7850b148748b18483f9ccf24c4ec09d573968  pippit-tool-cli-1.0.54-linux-arm64.tar.gz
+c84ccf75b7c3474f2623f0563c4bf1193a2c84b6f8d0d6ee853ac9c00913ee9c  pippit-tool-cli-1.0.54-windows-amd64.zip
+8bd9e6abcde7060fb8b1fac9cb4ea9729cc88b73b27dc9d775581306738a56ba  pippit-tool-cli-1.0.54-windows-arm64.zip

package/cmd/generate_video/query_result.go

@@ -26,7 +26,11 @@ func NewQueryResultCommand(stdout, stderr io.Writer, runner *common.Runner) *cob
 					"run_id":       strings.TrimSpace(opts.RunID),
 					"download_dir": strings.TrimSpace(opts.DownloadDir),
 				})
-				result = internalgen.NewQueryResultError(err, opts)
+				if result == nil {
+					result = internalgen.NewQueryResultError(err, opts)
+				} else if result.ErrorMessage == "" {
+					result.ErrorMessage = err.Error()
+				}
 			}
 			encoder := json.NewEncoder(stdout)
 			encoder.SetIndent("", "  ")

package/cmd/generate_video_test.go

@@ -434,98 +434,103 @@ func TestGenerateVideoErrorLogIncludesLogID(t *testing.T) {
 }
 
 func TestQueryResultDownloadsCompletedVideo(t *testing.T) {
-	var requestedDownload bool
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.Header.Get("Authorization") != "Bearer test-token" {
-			t.Fatalf("Authorization = %q, want test bearer token", r.Header.Get("Authorization"))
-		}
-		switch r.URL.Path {
-		case "/api/biz/v1/skill/get_thread":
-			if r.Method != http.MethodPost {
-				t.Fatalf("get_thread method = %s, want POST", r.Method)
+	for _, ret := range []string{"0", "1", "2", "5", "1015", "16019", "987654"} {
+		t.Run("ret="+ret, func(t *testing.T) {
+			var requestedDownload bool
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				if r.Header.Get("Authorization") != "Bearer test-token" {
+					t.Fatalf("Authorization = %q, want test bearer token", r.Header.Get("Authorization"))
+				}
+				switch r.URL.Path {
+				case "/api/biz/v1/skill/get_thread":
+					if r.Method != http.MethodPost {
+						t.Fatalf("get_thread method = %s, want POST", r.Method)
+					}
+					data, err := io.ReadAll(r.Body)
+					if err != nil {
+						t.Fatalf("read body: %v", err)
+					}
+					var body map[string]any
+					if err := sonic.Unmarshal(data, &body); err != nil {
+						t.Fatalf("decode body: %v", err)
+					}
+					if body["thread_id"] != "thread_123" {
+						t.Fatalf("thread_id = %v, want thread_123", body["thread_id"])
+					}
+					if body["run_id"] != "run_456" {
+						t.Fatalf("run_id = %v, want run_456", body["run_id"])
+					}
+					if _, ok := body["version"]; ok {
+						t.Fatalf("version = %v, want omitted", body["version"])
+					}
+					_, _ = w.Write([]byte(`{"ret":"` + ret + `","errmsg":"","data":{"thread":{"thread_id":"thread_123","run_list":[{"run_id":"run_456","state":3,"entry_list":[{"artifact":{"content":[{"sub_type":"biz/x_data_prompt_text","data":"做个小猫视频"},{"sub_type":"biz/x_data_video","data":"{\"video\":{\"download_url\":\"` + serverURL(r) + `/video.mp4\",\"title\":\"cat_video\",\"vid\":\"cat_vid\"}}"}]}}]}]}}}`))
+				case "/video.mp4":
+					requestedDownload = true
+					if r.Method != http.MethodGet {
+						t.Fatalf("download method = %s, want GET", r.Method)
+					}
+					_, _ = w.Write([]byte("video-data"))
+				default:
+					t.Fatalf("unexpected path %s", r.URL.Path)
+				}
+			}))
+			defer server.Close()
+
+			downloadDir := filepath.Join(t.TempDir(), "downloads")
+			var stdout, stderr bytes.Buffer
+			root := newTestRootCommand(t, &stdout, &stderr, server.URL)
+			root.SetArgs([]string{
+				"query-result",
+				"--thread-id", "thread_123",
+				"--run-id", "run_456",
+				"--download-dir", downloadDir,
+			})
+
+			if err := root.Execute(); err != nil {
+				t.Fatalf("Execute() error = %v, stderr = %s", err, stderr.String())
 			}
-			data, err := io.ReadAll(r.Body)
-			if err != nil {
-				t.Fatalf("read body: %v", err)
+
+			outputPath := filepath.Join(downloadDir, "cat_vid.mp4")
+			downloadURL := server.URL + "/video.mp4"
+			if !requestedDownload {
+				t.Fatal("download endpoint was not requested")
 			}
-			var body map[string]any
-			if err := sonic.Unmarshal(data, &body); err != nil {
-				t.Fatalf("decode body: %v", err)
+			got := decodeJSON(t, stdout.Bytes())
+			if got["completed"] != true {
+				t.Fatalf("completed = %v, want true", got["completed"])
 			}
-			if body["thread_id"] != "thread_123" {
-				t.Fatalf("thread_id = %v, want thread_123", body["thread_id"])
+			if got["status"] != "succeeded" {
+				t.Fatalf("status = %v, want succeeded", got["status"])
 			}
-			if body["run_id"] != "run_456" {
-				t.Fatalf("run_id = %v, want run_456", body["run_id"])
+			if got["thread_id"] != "thread_123" || got["run_id"] != "run_456" {
+				t.Fatalf("ids = (%v, %v), want thread/run ids", got["thread_id"], got["run_id"])
 			}
-			if _, ok := body["version"]; ok {
-				t.Fatalf("version = %v, want omitted", body["version"])
+			if _, ok := got["state"]; ok {
+				t.Fatalf("state should not be returned: %#v", got)
 			}
-			_, _ = w.Write([]byte(`{"ret":"0","errmsg":"","data":{"thread":{"thread_id":"thread_123","run_list":[{"run_id":"run_456","state":3,"entry_list":[{"artifact":{"content":[{"sub_type":"biz/x_data_prompt_text","data":"做个小猫视频"},{"sub_type":"biz/x_data_video","data":"{\"video\":{\"download_url\":\"` + serverURL(r) + `/video.mp4\",\"title\":\"cat_video\",\"vid\":\"cat_vid\"}}"}]}}]}]}}}`))
-		case "/video.mp4":
-			requestedDownload = true
-			if r.Method != http.MethodGet {
-				t.Fatalf("download method = %s, want GET", r.Method)
+			if got["error_message"] != "" {
+				t.Fatalf("error_message = %v, want empty", got["error_message"])
 			}
-			_, _ = w.Write([]byte("video-data"))
-		default:
-			t.Fatalf("unexpected path %s", r.URL.Path)
-		}
-	}))
-	defer server.Close()
-
-	downloadDir := filepath.Join(t.TempDir(), "downloads")
-	var stdout, stderr bytes.Buffer
-	root := newTestRootCommand(t, &stdout, &stderr, server.URL)
-	root.SetArgs([]string{
-		"query-result",
-		"--thread-id", "thread_123",
-		"--run-id", "run_456",
-		"--download-dir", downloadDir,
-	})
-
-	if err := root.Execute(); err != nil {
-		t.Fatalf("Execute() error = %v, stderr = %s", err, stderr.String())
-	}
+			videos, ok := got["videos"].([]any)
+			if !ok || len(videos) != 1 {
+				t.Fatalf("videos = %#v, want one video", got["videos"])
+			}
+			video, ok := videos[0].(map[string]any)
+			if !ok {
+				t.Fatalf("video = %#v, want object", videos[0])
+			}
+			if video["download_url"] != downloadURL || video["output_path"] != outputPath {
+				t.Fatalf("video = %#v, want download_url/output_path", video)
+			}
+			for _, unwanted := range []string{"vid", "asset_id", "title", "draft", "draft_task_id"} {
+				if _, ok := video[unwanted]; ok {
+					t.Fatalf("video = %#v, should not contain %s", video, unwanted)
+				}
+			}
+			assertFileContent(t, outputPath, "video-data")
 
-	outputPath := filepath.Join(downloadDir, "cat_vid.mp4")
-	downloadURL := server.URL + "/video.mp4"
-	if !requestedDownload {
-		t.Fatal("download endpoint was not requested")
-	}
-	got := decodeJSON(t, stdout.Bytes())
-	if got["completed"] != true {
-		t.Fatalf("completed = %v, want true", got["completed"])
-	}
-	if got["status"] != "succeeded" {
-		t.Fatalf("status = %v, want succeeded", got["status"])
-	}
-	if got["thread_id"] != "thread_123" || got["run_id"] != "run_456" {
-		t.Fatalf("ids = (%v, %v), want thread/run ids", got["thread_id"], got["run_id"])
-	}
-	if _, ok := got["state"]; ok {
-		t.Fatalf("state should not be returned: %#v", got)
-	}
-	if got["error_message"] != "" {
-		t.Fatalf("error_message = %v, want empty", got["error_message"])
-	}
-	videos, ok := got["videos"].([]any)
-	if !ok || len(videos) != 1 {
-		t.Fatalf("videos = %#v, want one video", got["videos"])
-	}
-	video, ok := videos[0].(map[string]any)
-	if !ok {
-		t.Fatalf("video = %#v, want object", videos[0])
-	}
-	if video["download_url"] != downloadURL || video["output_path"] != outputPath {
-		t.Fatalf("video = %#v, want download_url/output_path", video)
-	}
-	for _, unwanted := range []string{"vid", "asset_id", "title", "draft", "draft_task_id"} {
-		if _, ok := video[unwanted]; ok {
-			t.Fatalf("video = %#v, should not contain %s", video, unwanted)
-		}
+		})
 	}
-	assertFileContent(t, outputPath, "video-data")
 }
 
 func TestQueryResultPreservesDraftMetadata(t *testing.T) {
@@ -601,11 +606,11 @@ func TestQueryResultIgnoresVideoDataWithoutVideoSubType(t *testing.T) {
 		t.Fatalf("Execute() error = %v, stderr = %s", err, stderr.String())
 	}
 	got := decodeJSON(t, stdout.Bytes())
-	if got["completed"] != false {
-		t.Fatalf("completed = %v, want false", got["completed"])
+	if got["completed"] != true {
+		t.Fatalf("completed = %v, want true for a succeeded Run", got["completed"])
 	}
-	if got["status"] != "unknown" {
-		t.Fatalf("status = %v, want unknown", got["status"])
+	if got["status"] != "succeeded" {
+		t.Fatalf("status = %v, want succeeded despite missing downloadable artifacts", got["status"])
 	}
 	if got["thread_id"] != "thread_123" || got["run_id"] != "run_456" {
 		t.Fatalf("ids = (%v, %v), want thread/run ids", got["thread_id"], got["run_id"])
@@ -674,14 +679,14 @@ func TestQueryResultGetThreadBusinessErrorReturnsErrorMessage(t *testing.T) {
 		t.Fatalf("Execute() error = %v, stderr = %s", err, stderr.String())
 	}
 	got := decodeJSON(t, stdout.Bytes())
-	if got["completed"] != false {
-		t.Fatalf("completed = %v, want false", got["completed"])
+	if got["completed"] != true {
+		t.Fatalf("completed = %v, want true", got["completed"])
 	}
 	if got["thread_id"] != "thread_123" || got["run_id"] != "run_456" {
 		t.Fatalf("ids = (%v, %v), want thread/run ids", got["thread_id"], got["run_id"])
 	}
-	if got["status"] != "unknown" {
-		t.Fatalf("status = %v, want unknown", got["status"])
+	if got["status"] != "failed" {
+		t.Fatalf("status = %v, want failed", got["status"])
 	}
 	if got["error_message"] != "创作失败：暂时无法生成 log_id=log_456" {
 		t.Fatalf("error_message = %v, want get_thread business error", got["error_message"])
@@ -692,6 +697,46 @@ func TestQueryResultGetThreadBusinessErrorReturnsErrorMessage(t *testing.T) {
 	}
 }
 
+func TestQueryResultUsesRunDespiteBusinessError(t *testing.T) {
+	for _, tt := range []struct {
+		name, data, status, message string
+		completed                   bool
+	}{
+		{"structured failure", `{"thread":{"thread_id":"thread_123","run_list":[{"run_id":"run_456","state":4,"error_message":"Run 失败"}]}}`, "failed", "Run 失败", true},
+		{"envelope fallback", `{"thread":{"thread_id":"thread_123","run_list":[{"run_id":"run_456","state":4}]}}`, "failed", "模拟接口错误 log_id=fixture-log", true},
+		{"succeeded without artifacts", `{"thread":{"thread_id":"thread_123","run_list":[{"run_id":"run_456","state":3}]}}`, "succeeded", "下载失败：未找到可下载的产物", true},
+		{"canceled", `{"thread":{"thread_id":"thread_123","run_list":[{"run_id":"run_456","state":5}]}}`, "canceled", "", true},
+		{"running", `{"thread":{"thread_id":"thread_123","run_list":[{"run_id":"run_456","state":2}]}}`, "running", "", false},
+		{"different run", `{"thread":{"thread_id":"thread_123","run_list":[{"run_id":"other","state":4}]}}`, "unknown", "模拟接口错误 log_id=fixture-log", false},
+		{"missing thread", `{}`, "unknown", "模拟接口错误 log_id=fixture-log", false},
+		{"null data", `null`, "unknown", "模拟接口错误 log_id=fixture-log", false},
+		{"malformed run", `{"thread":{"run_list":"invalid"}}`, "unknown", "模拟接口错误 log_id=fixture-log", false},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				if r.URL.Path != "/api/biz/v1/skill/get_thread" {
+					t.Fatalf("unexpected path %s", r.URL.Path)
+				}
+				fmt.Fprintf(w, `{"ret":"2","errmsg":"模拟接口错误","log_id":"fixture-log","data":%s}`, tt.data)
+			}))
+			defer server.Close()
+			var stdout, stderr bytes.Buffer
+			root := newTestRootCommand(t, &stdout, &stderr, server.URL)
+			root.SetArgs([]string{"query-result", "--thread-id", "thread_123", "--run-id", "run_456", "--download-dir", t.TempDir()})
+			if err := root.Execute(); err != nil {
+				t.Fatalf("Execute() error = %v, stderr = %s", err, stderr.String())
+			}
+			got := decodeJSON(t, stdout.Bytes())
+			if got["status"] != tt.status || got["completed"] != tt.completed || got["error_message"] != tt.message {
+				t.Fatalf("output = %#v, want status=%s completed=%v error_message=%q", got, tt.status, tt.completed, tt.message)
+			}
+			if got["thread_id"] != "thread_123" || got["run_id"] != "run_456" {
+				t.Fatalf("output = %#v, want requested thread/run IDs", got)
+			}
+		})
+	}
+}
+
 func TestQueryResultFailedReturnsErrorMessage(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		switch r.URL.Path {
@@ -789,10 +834,10 @@ func TestQueryResultRunStateMapping(t *testing.T) {
 		{2, "running", false},
 		{4, "failed", true},
 		{5, "canceled", true},
-		{6, "unknown", false},
+		{6, "input_required", false},
 		{7, "running", false},
 		{8, "running", false},
-		{9, "unknown", false},
+		{9, "interrupted", true},
 		{99, "unknown", false},
 	}
 	for _, tt := range tests {

package/cmd/query_result_branches_test.go

@@ -0,0 +1,265 @@
+package cmd
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// This matrix follows the legacy skill query endpoint, including its middleware.
+// Business error envelopes deliberately omit Run, as the real handler does.
+func TestQueryResultResponseBranches(t *testing.T) {
+	tests := []struct {
+		name, ret, message, status string
+		httpStatus                 int
+	}{
+		{"empty thread id", "2", "thread id不能为空", "unknown", 200},
+		{"invalid version", "2", "version参数无效", "unknown", 200},
+		{"empty run id", "2", "run id不能为空", "unknown", 200},
+		{"invalid AK owner info", "2", "无法根据此Ak找到有效用户信息", "unknown", 200},
+		{"invalid OAuth user info", "2", "无法获取有效用户信息", "unknown", 200},
+		{"RPC or DB error", "5", "获取会话信息失败", "unknown", 200},
+		{"no runs", "1", "会话中缺少有效的Run", "unknown", 200},
+		{"run not found", "2", "会话中未找到RunID为run_456的Run", "unknown", 200},
+		{"run copy failed", "1", "解析Run信息失败", "unknown", 200},
+		{"failed without reason", "5", "创作失败", "failed", 200},
+		{"failed with reason", "5", "创作失败：视频可能不合规，请修改后重试", "failed", 200},
+		{"failed with empty reason", "5", "创作失败：", "failed", 200},
+		{"canceled", "5", "创作已取消", "canceled", 200},
+		{"bad bearer or AK", "1015", "invalid access key", "unknown", 401},
+		{"bad owner", "1015", "invalid access key owner", "unknown", 401},
+		{"bad team id", "1015", "invalid team id", "unknown", 401},
+		{"team login missing", "1015", "login required for team access", "unknown", 401},
+		{"permission RPC failure", "1015", "team permission check failed", "unknown", 401},
+		{"permission RPC rejection", "1015", "team permission denied", "unknown", 401},
+		{"team denied", "16019", "team permission denied", "unknown", 200},
+		{"member inactive", "16020", "team member is inactive", "unknown", 200},
+		{"role denied", "16021", "team role is not allowed", "unknown", 200},
+		{"team missing", "16022", "team not found", "unknown", 200},
+		{"team unavailable", "16023", "team is unavailable", "unknown", 200},
+		{"subscription inactive", "16024", "team subscription is inactive", "unknown", 200},
+		{"member limit", "16025", "team member limit exceeded", "unknown", 200},
+		{"product identity invalid", "2", "missing or unsupported business app id", "unknown", 400},
+		{"product identity unavailable", "5", "business app identity unavailable", "unknown", 503},
+		{"request binding error", "-3", "bad request", "unknown", 200},
+		{"panic", "-2", "system panic", "unknown", 500},
+		{"unknown future ret", "987654", "new server error", "unknown", 200},
+		{"wrong ret with failure phrase", "2", "创作失败：原因", "unknown", 200},
+		{"wrong ret with cancellation phrase", "1", "创作已取消", "unknown", 200},
+		{"unrecognized ret with failure phrase", "987654", "创作失败", "unknown", 200},
+		{"zero ret without run", "0", "创作失败", "unknown", 200},
+		{"contains failure word", "5", "查询创作失败记录失败", "unknown", 200},
+		{"only moderation wording", "5", "视频可能不合规", "unknown", 200},
+		{"wrong failure delimiter", "5", "创作失败: reason", "unknown", 200},
+		{"cancellation suffix", "5", "创作已取消查询失败", "unknown", 200},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			body, err := json.Marshal(map[string]any{"ret": tt.ret, "errmsg": tt.message, "log_id": "branch-log", "data": nil})
+			if err != nil {
+				t.Fatal(err)
+			}
+			got := executeQueryResponse(t, tt.httpStatus, string(body))
+			completed := tt.status == "failed" || tt.status == "canceled"
+			if got["status"] != tt.status || got["completed"] != completed {
+				t.Fatalf("got %#v, want %s completed=%t", got, tt.status, completed)
+			}
+			message, _ := got["error_message"].(string)
+			if tt.ret != "0" && (!strings.Contains(message, tt.message) || !strings.Contains(message, "branch-log")) {
+				t.Fatalf("original error/LogID lost: %q", message)
+			}
+			if message == "" {
+				t.Fatalf("missing error: %#v", got)
+			}
+		})
+	}
+}
+
+func executeQueryResponse(t *testing.T, status int, body string) map[string]any {
+	t.Helper()
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/biz/v1/skill/get_thread" {
+			t.Errorf("unexpected download/request: %s", r.URL.Path)
+		}
+		w.WriteHeader(status)
+		_, _ = w.Write([]byte(body))
+	}))
+	defer server.Close()
+	return executeQueryURL(t, server.URL, t.TempDir())
+}
+
+func executeQueryURL(t *testing.T, url, dir string) map[string]any {
+	t.Helper()
+	var stdout, stderr bytes.Buffer
+	root := newTestRootCommand(t, &stdout, &stderr, url)
+	root.SetArgs([]string{"query-result", "--thread-id", "thread_123", "--run-id", "run_456", "--download-dir", dir})
+	if err := root.Execute(); err != nil {
+		t.Fatalf("Execute: %v, stderr=%s", err, stderr.String())
+	}
+	got := decodeJSON(t, stdout.Bytes())
+	if got["thread_id"] != "thread_123" || got["run_id"] != "run_456" {
+		t.Fatalf("requested IDs lost: %#v", got)
+	}
+	for _, key := range []string{"videos", "images"} {
+		if _, ok := got[key].([]any); !ok {
+			t.Fatalf("%s is not an array: %#v", key, got)
+		}
+	}
+	return got
+}
+
+func TestQueryResultRecordedFailureResponse(t *testing.T) {
+	// Recorded production response; only diagnostic identifiers are sanitized.
+	data, err := os.ReadFile("testdata/query-result/recorded-failure.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := executeQueryResponse(t, 200, string(data))
+	if got["status"] != "failed" || got["completed"] != true || got["error_message"] != "创作失败：视频可能不合规，请修改后重试 log_id=recorded-failure-log" {
+		t.Fatalf("recorded failure was not recognized: %#v", got)
+	}
+}
+
+func TestQueryResultRunPrecedesEveryBusinessError(t *testing.T) {
+	states := []struct {
+		state     int
+		status    string
+		completed bool
+	}{
+		{0, "unknown", false}, {1, "running", false}, {2, "running", false},
+		{3, "succeeded", true}, {4, "failed", true}, {5, "canceled", true},
+		{6, "input_required", false}, {7, "running", false}, {8, "running", false},
+		{9, "interrupted", true}, {99, "unknown", false},
+	}
+	// These are compatibility envelopes, not assertions that the server currently
+	// returns a structured Run for every error. The recorded fixture covers that.
+	for _, ret := range []string{"0", "1", "2", "5", "1015", "16019", "16020", "16021", "16022", "16023", "16024", "16025", "-2", "-3", "987654"} {
+		for _, state := range states {
+			t.Run(fmt.Sprintf("ret=%s/state=%d", ret, state.state), func(t *testing.T) {
+				clearDailyErrorLog(t)
+				got := executeQueryResponse(t, 200, fmt.Sprintf(`{"ret":%q,"errmsg":"创作失败：envelope reason","log_id":"matrix-log","data":{"thread":{"run_list":[{"run_id":"other","state":4},{"run_id":"run_456","state":%d,"fail_reason":{"message":"Run reason","code":12023}}]}}}`, ret, state.state))
+				if got["status"] != state.status || got["completed"] != state.completed {
+					t.Fatalf("got %#v, want %#v", got, state)
+				}
+				if state.state == 4 && got["error_message"] != "Run reason (error_code=12023)" {
+					t.Fatalf("lost run reason: %#v", got)
+				}
+				if state.state != 3 && state.state != 4 && got["error_message"] != "" {
+					t.Fatalf("envelope overwrote Run: %#v", got)
+				}
+				if ret != "0" {
+					logs, err := json.Marshal(readDailyErrorLog(t))
+					if err != nil {
+						t.Fatal(err)
+					}
+					if !strings.Contains(string(logs), "ret="+ret) || !strings.Contains(string(logs), "matrix-log") {
+						t.Fatalf("missing diagnostics: %s", logs)
+					}
+				}
+			})
+		}
+	}
+}
+
+func TestQueryResultUnusableResponses(t *testing.T) {
+	for _, body := range []string{
+		``, `<html>gateway error</html>`, `{"ret":`,
+		`{}`, `{"ret":"0"}`, `{"ret":"0","data":null}`,
+		`{"ret":"0","data":{}}`, `{"ret":"0","data":{"readable_text":"失败"}}`,
+		`{"ret":"0","data":{"thread":null}}`,
+		`{"ret":"0","data":{"thread":{"run_list":[]}}}`,
+		`{"ret":"0","data":{"thread":{"run_list":"invalid"}}}`,
+		`{"ret":"0","data":{"thread":{"run_list":[{"run_id":"other","state":4}]}}}`,
+		`{"ret":"0","data":{"thread":{"run_list":[{"run_id":"run_456","state":"bad"}]}}}`,
+		`{"ret":"","errmsg":"创作失败","data":null}`,
+		`{"ret":"5","errmsg":"","data":null}`,
+	} {
+		t.Run(body, func(t *testing.T) {
+			got := executeQueryResponse(t, 200, body)
+			if got["status"] != "unknown" || got["completed"] != false || got["error_message"] == "" {
+				t.Fatalf("got %#v", got)
+			}
+		})
+	}
+	for _, code := range []int{400, 401, 403, 429, 500, 502, 503, 504} {
+		t.Run(fmt.Sprint(code), func(t *testing.T) {
+			got := executeQueryResponse(t, code, "gateway error")
+			if got["status"] != "unknown" || got["completed"] != false || !strings.Contains(got["error_message"].(string), fmt.Sprint(code)) {
+				t.Fatalf("got %#v", got)
+			}
+		})
+	}
+	t.Run("connection refused", func(t *testing.T) {
+		server := httptest.NewServer(http.NotFoundHandler())
+		server.Close()
+		got := executeQueryURL(t, server.URL, t.TempDir())
+		if got["status"] != "unknown" || got["completed"] != false || got["error_message"] == "" {
+			t.Fatalf("got %#v", got)
+		}
+	})
+}
+
+func TestQueryResultRetainsPartialDownloads(t *testing.T) {
+	for _, mode := range []string{"second video fails", "first image fails", "second image fails", "cached video then image fails"} {
+		t.Run(mode, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				if r.URL.Path == "/api/biz/v1/skill/get_thread" {
+					content := []any{map[string]any{"sub_type": "biz/x_data_video", "data": map[string]any{"video": map[string]any{"download_url": serverURL(r) + "/video", "vid": "first"}}}}
+					badVideo := map[string]any{"sub_type": "biz/x_data_video", "data": map[string]any{"video": map[string]any{"download_url": "invalid-scheme://broken"}}}
+					badImage := map[string]any{"sub_type": "biz/x_data_image", "data": map[string]any{"image": map[string]any{"url": "invalid-scheme://broken"}}}
+					if mode == "second video fails" {
+						content = append(content, badVideo)
+					} else {
+						if mode == "second image fails" {
+							content = append(content, map[string]any{"sub_type": "biz/x_data_image", "data": map[string]any{"image": map[string]any{"url": serverURL(r) + "/image", "asset_id": "first-image"}}})
+						}
+						content = append(content, badImage)
+					}
+					_ = json.NewEncoder(w).Encode(map[string]any{"ret": "0", "data": map[string]any{"thread": map[string]any{"run_list": []any{map[string]any{"run_id": "run_456", "state": 3, "entry_list": []any{map[string]any{"artifact": map[string]any{"content": content}}}}}}}})
+					return
+				}
+				_, _ = w.Write([]byte("media-data"))
+			}))
+			defer server.Close()
+			dir := t.TempDir()
+			if mode == "cached video then image fails" {
+				if err := os.WriteFile(filepath.Join(dir, "first.mp4"), []byte("media-data"), 0600); err != nil {
+					t.Fatal(err)
+				}
+			}
+			got := executeQueryURL(t, server.URL, dir)
+			if got["status"] != "succeeded" || got["completed"] != true || !strings.Contains(got["error_message"].(string), "下载失败") {
+				t.Fatalf("got %#v", got)
+			}
+			videos := got["videos"].([]any)
+			images := got["images"].([]any)
+			wantImages := 0
+			if mode == "second image fails" {
+				wantImages = 1
+			}
+			if len(videos) != 1 || len(images) != wantImages {
+				t.Fatalf("partial files lost: %#v", got)
+			}
+			for _, file := range append(videos, images...) {
+				assertFileContent(t, file.(map[string]any)["output_path"].(string), "media-data")
+			}
+		})
+	}
+}
+
+func TestQueryResultTerminalEnvelopeWithoutUsableRun(t *testing.T) {
+	for _, data := range []string{`null`, `{}`, `{"thread":null}`, `{"thread":{"run_list":[]}}`, `{"thread":{"run_list":[{"run_id":"other","state":3}]}}`, `{"thread":{"run_list":"bad"}}`} {
+		t.Run(data, func(t *testing.T) {
+			got := executeQueryResponse(t, 200, `{"ret":"5","errmsg":"创作失败：reason","data":`+data+`}`)
+			if got["status"] != "failed" || got["completed"] != true || got["error_message"] != "创作失败：reason" {
+				t.Fatalf("got %#v", got)
+			}
+		})
+	}
+}

package/cmd/testdata/query-result/recorded-failure.json

@@ -0,0 +1,6 @@
+{
+  "ret": "5",
+  "errmsg": "创作失败：视频可能不合规，请修改后重试",
+  "log_id": "recorded-failure-log",
+  "data": null
+}

package/dist/checksums.txt

@@ -1,6 +1,6 @@
-edd2d8640d4a34b156d8c614ef5186ce91a6ea8778aee7b208d41296a840ef3f  pippit-tool-cli-1.0.52-darwin-amd64.tar.gz
-7b4b992088057f012851cd5c396d05239ad5fd6782bf93c3a7f9f5ae494b81fd  pippit-tool-cli-1.0.52-darwin-arm64.tar.gz
-aab287cc80ccab5f78f0f73df95d15b61d7e9e67205fb8b5e6386c22a35dc732  pippit-tool-cli-1.0.52-linux-amd64.tar.gz
-a9c86c8323d9f2a4859a0280095a7cac85cdf0e7fc59aa3bc758f99332bd387e  pippit-tool-cli-1.0.52-linux-arm64.tar.gz
-a0846db0ff0f2c61337c85f50f3b746ad9a6bd1ed2862df16399ba6dcc4257e7  pippit-tool-cli-1.0.52-windows-amd64.zip
-54dd5852b9597b3ad9405be0c63ebfa670b713c169f69649647b3afe5ed89fe1  pippit-tool-cli-1.0.52-windows-arm64.zip
+3027db71d4e1b89ccaaa50f4660fb41a90e578bf7c08f0ea1c28367a597371a1  pippit-tool-cli-1.0.54-darwin-amd64.tar.gz
+b6a932ae33085d565e88c21a39b446dcb21cf148b6fb66d5a5baa040896d98ae  pippit-tool-cli-1.0.54-darwin-arm64.tar.gz
+aabce0e36f96a1dcc29c24a277e85859e938f6eddc4ed74a0536df3e4e4bce23  pippit-tool-cli-1.0.54-linux-amd64.tar.gz
+beb74396a2d82e05f7199b05cdd7850b148748b18483f9ccf24c4ec09d573968  pippit-tool-cli-1.0.54-linux-arm64.tar.gz
+c84ccf75b7c3474f2623f0563c4bf1193a2c84b6f8d0d6ee853ac9c00913ee9c  pippit-tool-cli-1.0.54-windows-amd64.zip
+8bd9e6abcde7060fb8b1fac9cb4ea9729cc88b73b27dc9d775581306738a56ba  pippit-tool-cli-1.0.54-windows-arm64.zip

package/internal/common/get_thread.go

@@ -18,8 +18,13 @@ type GetThreadOptions struct {
 }
 
 // GetThreadResult is the parsed get_thread response used by `pippit-tool-cli get-thread`.
+// A business error may return both a result and an error so structured callers
+// can still inspect the returned Run. Callers must continue to handle the error.
 type GetThreadResult struct {
 	ReadableText string `json:"readable_text"`
+	Ret          string `json:"-"`
+	Errmsg       string `json:"-"`
+	LogID        string `json:"-"`
 	RawData      []byte `json:"-"`
 }
 
@@ -49,11 +54,12 @@ func GetThread(ctx context.Context, opts *GetThreadOptions, runner *Runner) (*Ge
 	if err := runner.Client.SendRequest(ctx, getThreadPath(runner), body, &resp); err != nil {
 		return nil, fmt.Errorf("获取线程请求失败: %w", err)
 	}
+	result := &GetThreadResult{Ret: resp.Ret, Errmsg: resp.Errmsg, LogID: resp.LogID, RawData: resp.Data}
 	if resp.Ret != "0" {
 		if resp.Errmsg == "" {
 			resp.Errmsg = "未知错误"
 		}
-		return nil, NewLogIDError(fmt.Sprintf("获取线程请求返回失败: ret=%s errmsg=%s", resp.Ret, resp.Errmsg), resp.LogID)
+		return result, NewLogIDError(fmt.Sprintf("获取线程请求返回失败: ret=%s errmsg=%s", resp.Ret, resp.Errmsg), resp.LogID)
 	}
 	if len(resp.Data) == 0 {
 		return nil, fmt.Errorf("get_thread 响应缺少 data")
@@ -68,10 +74,8 @@ func GetThread(ctx context.Context, opts *GetThreadOptions, runner *Runner) (*Ge
 		}
 	}
 
-	return &GetThreadResult{
-		ReadableText: readable.ReadableText,
-		RawData:      resp.Data,
-	}, nil
+	result.ReadableText = readable.ReadableText
+	return result, nil
 }
 
 func getThreadPath(runner *Runner) string {

package/internal/common/get_thread_test.go

@@ -57,6 +57,21 @@ func TestGetThreadRequiresRetZero(t *testing.T) {
 	}
 }
 
+func TestGetThreadPreservesDataOnBusinessError(t *testing.T) {
+	result, err := GetThread(context.Background(), &GetThreadOptions{
+		ThreadID: "thread_123",
+		RunID:    "run_456",
+	}, &Runner{
+		Client: getThreadFakeClient{response: `{"ret":"2","errmsg":"模拟接口错误","log_id":"fixture-log","data":{"thread":{"thread_id":"thread_123","run_list":[{"run_id":"run_456","state":4}]}}}`},
+	})
+	if err == nil || !strings.Contains(err.Error(), "ret=2") || !strings.Contains(err.Error(), "fixture-log") {
+		t.Fatalf("error = %v, want business error with log ID", err)
+	}
+	if result == nil || !strings.Contains(string(result.RawData), `"run_456"`) {
+		t.Fatalf("result = %#v, want response data alongside business error", result)
+	}
+}
+
 func TestGetThreadV2RequiresReadableText(t *testing.T) {
 	_, err := GetThread(context.Background(), &GetThreadOptions{
 		ThreadID: "thread_123",
@@ -72,3 +87,24 @@ func TestGetThreadV2RequiresReadableText(t *testing.T) {
 		t.Fatalf("error = %q, want readable_text validation", err)
 	}
 }
+
+func TestGetThreadPreservesEnvelope(t *testing.T) {
+	for _, ret := range []string{"0", "1", "2", "5", "1015", "16019", "987654"} {
+		t.Run(ret, func(t *testing.T) {
+			result, err := GetThread(context.Background(), &GetThreadOptions{ThreadID: "thread", RunID: "run"}, &Runner{Client: getThreadFakeClient{response: `{"ret":"` + ret + `","errmsg":"server message","log_id":"server-log","data":null}`}})
+			if (err != nil) != (ret != "0") {
+				t.Fatalf("err=%v ret=%s", err, ret)
+			}
+			if result == nil || result.Ret != ret || result.Errmsg != "server message" || result.LogID != "server-log" || string(result.RawData) != "null" {
+				t.Fatalf("envelope lost: %#v", result)
+			}
+			raw, marshalErr := sonic.Marshal(result)
+			if marshalErr != nil {
+				t.Fatal(marshalErr)
+			}
+			if strings.Contains(string(raw), "server-log") || strings.Contains(string(raw), "server message") {
+				t.Fatalf("internal envelope leaked: %s", raw)
+			}
+		})
+	}
+}

package/internal/generate_video/query_result.go

@@ -14,19 +14,22 @@ import (
 )
 
 const (
-	successRunState  = 3
-	failedRunState   = 4
-	canceledRunState = 5
+	successRunState     = 3
+	failedRunState      = 4
+	canceledRunState    = 5
+	interruptedRunState = 9
 )
 
 // 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"
+	statusRunning       = "running"
+	statusSucceeded     = "succeeded"
+	statusFailed        = "failed"
+	statusCanceled      = "canceled"
+	statusUnknown       = "unknown"
+	statusInputRequired = "input_required"
+	statusInterrupted   = "interrupted"
 )
 
 // runStateStatus maps the server-side run state (0-9) to the user-facing
@@ -38,16 +41,17 @@ var runStateStatus = map[int]string{
 	3: statusSucceeded,
 	4: statusFailed,
 	5: statusCanceled,
-	6: statusUnknown, // InputRequired
-	7: statusRunning, // Generating
-	8: statusRunning, // Interrupt
-	9: statusUnknown, // HITL_Interrupt
+	6: statusInputRequired,
+	7: statusRunning,     // Generating
+	8: statusRunning,     // Interrupt
+	9: statusInterrupted, // HITL_Interrupt is terminal, unlike Interrupt (8).
 }
 
 var terminalRunStates = map[int]struct{}{
-	successRunState:  {},
-	failedRunState:   {},
-	canceledRunState: {},
+	successRunState:     {},
+	failedRunState:      {},
+	canceledRunState:    {},
+	interruptedRunState: {},
 }
 
 func statusForRunState(state int) string {
@@ -100,12 +104,18 @@ type queryThread struct {
 }
 
 type queryRun struct {
-	RunID        string       `json:"run_id"`
-	State        int          `json:"state"`
-	ErrorMessage string       `json:"error_message"`
-	ErrorMsg     string       `json:"error_msg"`
-	Errmsg       string       `json:"errmsg"`
-	EntryList    []queryEntry `json:"entry_list"`
+	RunID        string           `json:"run_id"`
+	State        int              `json:"state"`
+	ErrorMessage string           `json:"error_message"`
+	ErrorMsg     string           `json:"error_msg"`
+	Errmsg       string           `json:"errmsg"`
+	FailReason   *queryFailReason `json:"fail_reason"`
+	EntryList    []queryEntry     `json:"entry_list"`
+}
+
+type queryFailReason struct {
+	Message string          `json:"message"`
+	Code    json.RawMessage `json:"code"`
 }
 
 type queryEntry struct {
@@ -152,34 +162,41 @@ func QueryResult(ctx context.Context, opts *QueryResultOptions, runner *common.R
 		return nil, err
 	}
 
-	threadResult, err := common.GetThread(ctx, &common.GetThreadOptions{
+	threadResult, queryErr := common.GetThread(ctx, &common.GetThreadOptions{
 		ThreadID: opts.ThreadID,
 		RunID:    opts.RunID,
 	}, runner)
-	if err != nil {
-		return nil, queryResultQueryError(err)
-	}
-
 	thread, err := parseQueryThread(threadResult)
 	if err != nil {
+		if queryErr != nil {
+			return queryResultWithoutRun(threadResult, queryErr, opts)
+		}
 		return nil, fmt.Errorf("查询失败：%w", err)
 	}
 
 	run, ok := findQueryRun(thread, opts.RunID)
 	if !ok {
+		if queryErr != nil {
+			return queryResultWithoutRun(threadResult, queryErr, opts)
+		}
 		return nil, fmt.Errorf("查询失败：未找到 run_id=%s 对应的 Run", opts.RunID)
 	}
+	logResolvedQueryError(queryErr, opts)
+	result := &QueryResultResult{
+		Status:    statusForRunState(run.State),
+		Completed: isTerminalRunState(run.State),
+		ThreadID:  firstNonEmpty(thread.ThreadID, opts.ThreadID),
+		RunID:     opts.RunID,
+		Videos:    []QueryResultVideo{},
+		Images:    []QueryResultImage{},
+	}
 	if run.State != successRunState {
-		result := &QueryResultResult{
-			Status:    statusForRunState(run.State),
-			Completed: isTerminalRunState(run.State),
-			ThreadID:  firstNonEmpty(thread.ThreadID, opts.ThreadID),
-			RunID:     opts.RunID,
-			Videos:    []QueryResultVideo{},
-			Images:    []QueryResultImage{},
-		}
 		if run.State == failedRunState {
-			result.ErrorMessage = firstNonEmpty(extractQueryErrorMessage(run), "Run 失败")
+			message := extractQueryErrorMessage(run)
+			if message == "" && queryErr != nil {
+				message = queryResultQueryError(queryErr).Error()
+			}
+			result.ErrorMessage = firstNonEmpty(message, "Run 失败")
 		}
 		return result, nil
 	}
@@ -187,20 +204,19 @@ func QueryResult(ctx context.Context, opts *QueryResultOptions, runner *common.R
 	videos := extractQueryVideos(run)
 	images := extractQueryImages(run)
 	if len(videos) == 0 && len(images) == 0 {
-		return nil, fmt.Errorf("下载失败：未找到可下载的产物")
+		return result, fmt.Errorf("下载失败：未找到可下载的产物")
 	}
 
 	downloadDir, err := common.ExpandPath(opts.DownloadDir)
 	if err != nil {
-		return nil, fmt.Errorf("下载失败：解析下载目录失败：%w", err)
+		return result, fmt.Errorf("下载失败：解析下载目录失败：%w", err)
 	}
 
 	usedNames := make(map[string]int, len(videos)+len(images))
 
-	resultVideos := make([]QueryResultVideo, 0, len(videos))
 	for i, video := range videos {
 		if strings.TrimSpace(video.DownloadURL) == "" {
-			return nil, fmt.Errorf("下载失败：第 %d 个视频产物 download_url 为空", i+1)
+			return result, fmt.Errorf("下载失败：第 %d 个视频产物 download_url 为空", i+1)
 		}
 		outputPath := filepath.Join(downloadDir, uniqueQueryResultFileName(videoFileName(video, i+1), usedNames))
 		download, err := common.DownloadResult(ctx, common.DownloadResultOptions{
@@ -209,7 +225,7 @@ func QueryResult(ctx context.Context, opts *QueryResultOptions, runner *common.R
 			Workers:    5,
 		}, runner)
 		if err != nil {
-			return nil, fmt.Errorf("下载失败：%w", err)
+			return result, fmt.Errorf("下载失败：%w", err)
 		}
 		actualOutputPath := outputPath
 		if len(download.Downloaded) > 0 {
@@ -217,7 +233,7 @@ func QueryResult(ctx context.Context, opts *QueryResultOptions, runner *common.R
 		} else if len(download.AlreadyExist) > 0 {
 			actualOutputPath = download.AlreadyExist[0]
 		}
-		resultVideos = append(resultVideos, QueryResultVideo{
+		result.Videos = append(result.Videos, QueryResultVideo{
 			DownloadURL: video.DownloadURL,
 			OutputPath:  actualOutputPath,
 			Draft:       video.Draft,
@@ -225,10 +241,9 @@ func QueryResult(ctx context.Context, opts *QueryResultOptions, runner *common.R
 		})
 	}
 
-	resultImages := make([]QueryResultImage, 0, len(images))
 	for i, image := range images {
 		if strings.TrimSpace(image.DownloadURL) == "" {
-			return nil, fmt.Errorf("下载失败：第 %d 个图片产物 download_url 为空", i+1)
+			return result, fmt.Errorf("下载失败：第 %d 个图片产物 download_url 为空", i+1)
 		}
 		outputPath := filepath.Join(downloadDir, uniqueQueryResultFileName(imageFileName(image, i+1), usedNames))
 		download, err := common.DownloadResult(ctx, common.DownloadResultOptions{
@@ -237,7 +252,7 @@ func QueryResult(ctx context.Context, opts *QueryResultOptions, runner *common.R
 			Workers:    5,
 		}, runner)
 		if err != nil {
-			return nil, fmt.Errorf("下载失败：%w", err)
+			return result, fmt.Errorf("下载失败：%w", err)
 		}
 		actualOutputPath := outputPath
 		if len(download.Downloaded) > 0 {
@@ -245,25 +260,52 @@ func QueryResult(ctx context.Context, opts *QueryResultOptions, runner *common.R
 		} else if len(download.AlreadyExist) > 0 {
 			actualOutputPath = download.AlreadyExist[0]
 		}
-		resultImages = append(resultImages, QueryResultImage{
+		result.Images = append(result.Images, QueryResultImage{
 			DownloadURL: image.DownloadURL,
 			OutputPath:  actualOutputPath,
 		})
 	}
 
-	return &QueryResultResult{
-		Status:    statusSucceeded,
-		Completed: true,
-		ThreadID:  firstNonEmpty(thread.ThreadID, opts.ThreadID),
-		RunID:     opts.RunID,
-		Videos:    resultVideos,
-		Images:    resultImages,
-	}, nil
+	return result, nil
 }
 
-// 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.
+// The legacy endpoint omits data for Failed/Canceled. Only these exact
+// endpoint-specific responses prove a terminal Run; other errors (including
+// ret=5 "获取会话信息失败") describe a failed query, not a failed Run.
+func queryResultWithoutRun(threadResult *common.GetThreadResult, queryErr error, opts *QueryResultOptions) (*QueryResultResult, error) {
+	status := statusUnknown
+	if threadResult != nil && threadResult.Ret == "5" {
+		message := strings.TrimSpace(threadResult.Errmsg)
+		switch {
+		case message == "创作失败" || strings.HasPrefix(message, "创作失败："):
+			status = statusFailed
+		case message == "创作已取消":
+			status = statusCanceled
+		}
+	}
+	if status == statusUnknown {
+		return nil, queryResultQueryError(queryErr)
+	}
+	logResolvedQueryError(queryErr, opts)
+	result := NewQueryResultError(queryResultQueryError(queryErr), opts)
+	result.Status = status
+	result.Completed = true
+	return result, nil
+}
+
+// The command logs returned errors. Errors consumed by a resolved Run must
+// also retain their original ret/errmsg/log_id for diagnosis.
+func logResolvedQueryError(err error, opts *QueryResultOptions) {
+	if err != nil {
+		_ = common.AppendDailyErrorLog("query-result", err, map[string]string{
+			"thread_id": opts.ThreadID,
+			"run_id":    opts.RunID,
+		})
+	}
+}
+
+// queryResultQueryError extracts a customer-facing get_thread error. It is used
+// when no target Run can be resolved, or as the failed Run's fallback reason.
 func queryResultQueryError(err error) error {
 	var logErr *common.LogIDError
 	if errors.As(err, &logErr) {
@@ -279,9 +321,8 @@ func queryResultQueryError(err error) error {
 	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.
+// NewQueryResultError builds the user-facing result when no Run could be
+// resolved. The concrete cause stays in error_message.
 func NewQueryResultError(err error, opts *QueryResultOptions) *QueryResultResult {
 	result := &QueryResultResult{
 		Status:       statusUnknown,
@@ -418,6 +459,16 @@ func extractQueryImages(run queryRun) []queryImage {
 }
 
 func extractQueryErrorMessage(run queryRun) string {
+	if run.FailReason != nil {
+		message := strings.TrimSpace(run.FailReason.Message)
+		code := rawMessageString(run.FailReason.Code)
+		if message != "" {
+			if code != "" && code != "0" {
+				return fmt.Sprintf("%s (error_code=%s)", message, code)
+			}
+			return message
+		}
+	}
 	if message := firstNonEmpty(run.ErrorMessage, run.ErrorMsg, run.Errmsg); message != "" {
 		return message
 	}
@@ -435,6 +486,11 @@ func extractQueryErrorMessage(run queryRun) string {
 			}
 		}
 	}
+	if run.FailReason != nil {
+		if code := rawMessageString(run.FailReason.Code); code != "" && code != "0" {
+			return "error_code=" + code
+		}
+	}
 	return ""
 }
 

package/internal/generate_video/query_result_branches_test.go

@@ -0,0 +1,63 @@
+package generate_video
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"testing"
+
+	"github.com/Pippit-dev/pippit-cli/internal/common"
+)
+
+func TestQueryFailureReasons(t *testing.T) {
+	for _, tt := range []struct{ name, run, want string }{
+		{"real fail reason", `{"fail_reason":{"message":"视频可能不合规，请修改后重试","code":12023}}`, "视频可能不合规，请修改后重试 (error_code=12023)"},
+		{"message only", `{"fail_reason":{"message":"reason"}}`, "reason"},
+		{"zero code", `{"fail_reason":{"message":"reason","code":0}}`, "reason"},
+		{"code only", `{"fail_reason":{"code":12023}}`, "error_code=12023"},
+		{"empty reason", `{"fail_reason":{"message":" ","code":0}}`, ""},
+		{"null reason", `{"fail_reason":null}`, ""},
+		{"structured reason wins", `{"fail_reason":{"message":"real reason","code":12023},"error_message":"legacy"}`, "real reason (error_code=12023)"},
+		{"legacy message fallback", `{"fail_reason":{"code":12023},"error_message":"legacy"}`, "legacy"},
+		{"error_msg fallback", `{"error_msg":"legacy"}`, "legacy"},
+		{"errmsg fallback", `{"errmsg":"legacy"}`, "legacy"},
+		{"artifact reason", `{"entry_list":[{"artifact":{"content":[{"data":{"error_message":"artifact reason","error_code":99}}]}}]}`, "artifact reason (error_code=99)"},
+		{"artifact code only", `{"entry_list":[{"artifact":{"content":[{"data":{"error_code":"99"}}]}}]}`, "error_code=99"},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			var run queryRun
+			if err := json.Unmarshal([]byte(tt.run), &run); err != nil {
+				t.Fatal(err)
+			}
+			if got := extractQueryErrorMessage(run); got != tt.want {
+				t.Fatalf("got %q want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+type queryErrorClient struct{ err error }
+
+func (c queryErrorClient) SendRequest(context.Context, string, any, any) error { return c.err }
+func (c queryErrorClient) SendRequestWithHeaders(context.Context, string, any, map[string]string, any) error {
+	return c.err
+}
+func (c queryErrorClient) SendMultipartRequest(context.Context, string, map[string]string, common.MultipartFile, any) error {
+	return c.err
+}
+
+func TestQueryResultTransportFailure(t *testing.T) {
+	for _, cause := range []error{context.DeadlineExceeded, context.Canceled, errors.New("connection reset")} {
+		t.Run(cause.Error(), func(t *testing.T) {
+			opts := &QueryResultOptions{ThreadID: "thread", RunID: "run", DownloadDir: t.TempDir()}
+			result, err := QueryResult(context.Background(), opts, &common.Runner{Client: queryErrorClient{cause}})
+			if result != nil || !errors.Is(err, cause) {
+				t.Fatalf("result=%#v err=%v", result, err)
+			}
+			result = NewQueryResultError(err, opts)
+			if result.Status != "unknown" || result.Completed || result.ErrorMessage == "" {
+				t.Fatalf("result=%#v", result)
+			}
+		})
+	}
+}

package/package.json

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

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

@@ -33,6 +33,22 @@ URL 导入前检查实际入口的 `--help` 含 `--url`；旧版缺少时按 [
 
 媒体节点优先通过语义 `create_biz_node` 创建，`initialData` 只传 `pippitAssetId`：CLI 查询素材并填写真实云媒体 `assetId`。用 `update_asset.contentPatch` 或 `update_node_data.patch` 替换素材时也可只传新的 `pippitAssetId`。显式填写的 `assetId` 必须与素材查询结果匹配，否则返回 `INVALID_MEDIA_IDENTITY` 并拒绝写入。
 
+普通 `biz/image` 的素材绑定在同层 `content.pippitAssetId` 与 `content.assetId`。`content.appearanceInfo`、`content.sourceInfos` 属于角色/场景结构，不能套用于普通图片；角色/场景继续按各自领域命令及 schema 操作。
+
+以下仅用于核对保存后的节点结构，ID 占位符须替换为同空间真实查询结果，不作为完整写入请求直接执行：
+
+```json
+{"type":"biz/image","content":{"pippitAssetId":"PIPPIT_MATERIAL_ID","assetId":"CLOUD_IMAGE_ASSET_ID"}}
+```
+
+错误反例：同层绑定缺失，即使保存 ACK，也不是可用参考图：
+
+```json
+{"type":"biz/image","content":{"appearanceInfo":{"pippitAssetId":"PIPPIT_MATERIAL_ID","assetId":"CLOUD_IMAGE_ASSET_ID"}}}
+```
+
+可先创建不含绑定的图片空草稿；不能用 `generation`、`sourceInfos` 或手改“已上传”状态把空草稿视为素材已就绪。已有错绑数据先回读、核对真实素材，再在用户授权的编辑范围内修正，不自动迁移用户画布。
+
 `canvas upload` 顶层旧字段 `asset_id` 是保留兼容的 workspace/source ID，不能当节点媒体 ID；它与 `upload-file.asset_id` 的含义不同。`media_asset_id` 来自查询结果对应的 `Image/Video/Audio.asset_id`；缺失时不能用 `source_id`、`pippit_asset_id` 或画布节点 ID 补位。`node_asset_refs[].pippit_asset_id` 使用画布节点资产 ID。
 
 批量 `apply_mutations` 默认非原子执行：必须检查 `data.results` 中每一项的 `committed` / `aborted` 状态，保留已成功项，不重跑整批。需要任一失败时整批回滚，可显式传 `atomic: true`。

package/skills/xyq-nest-skill/commands/query-result.md

@@ -20,6 +20,7 @@ stdout 是 JSON；命令可能将错误编码进 JSON 并以退出码 0 返回
 
 | 字段 | 含义 |
 | --- | --- |
+| `status` | 目标 Run 状态：`running`、`succeeded`、`failed`、`canceled`、`input_required`、`interrupted`、`unknown`；不直接由查询接口 `ret` 决定 |
 | `completed` | 是否结束；失败时也可能为 `true`，不等于成功 |
 | `error_message` | 非空即错误，不能因为 `completed=false` 而忽略 |
 | `thread_id` / `run_id` | 对应的查询任务 |
@@ -31,6 +32,7 @@ stdout 是 JSON；命令可能将错误编码进 JSON 并以退出码 0 返回
 
 ```json
 {
+  "status": "succeeded",
   "completed": true,
   "thread_id": "THREAD_ID",
   "run_id": "RUN_ID",
@@ -40,7 +42,15 @@ stdout 是 JSON；命令可能将错误编码进 JSON 并以退出码 0 返回
 }
 ```
 
-任务尚未完成时通常返回 `completed=false`、空错误、空媒体数组。命令不提供完整会话消息、用户反问或可区分的所有状态；不能仅凭这个响应断言具体进度、取消状态或等待用户输入。轮询停止条件见 [共用流程](../workflows/async-delivery.md)。
+`status` 和 `completed` 优先按返回的目标 Run 判定，适用于任意 `ret`。失败原因优先读取 Run 的 `fail_reason.message/code`，再读取兼容错误字段和接口错误；非零接口返回仍保留本地诊断日志。
+
+没有目标 Run 时，只有已核实的接口返回可确定终态：`ret=5` 且 `errmsg` 为 `创作失败` 或以 `创作失败：` 开头时返回 `failed`、`completed=true`；`ret=5` 且 `errmsg` 为 `创作已取消` 时返回 `canceled`、`completed=true`。不要泛匹配“失败”或“不合规”。其余查询错误保持 `unknown`、`completed=false`，通过 `error_message` 报告原因及可用的 LogID。`ret=2` 是参数错误，不代表安审失败；`ret=5` 也可能只是查询会话失败。未指定或未知 Run 状态保持 `unknown`。
+
+`input_required` 表示等待补充输入，`completed=false`；`interrupted` 表示人工交互中断结束，`completed=true`。两者均停止自动轮询并报告交互需求或中断状态。`canceled` 也直接停止，不因空产物误报下载失败。程序中断／等待工具回调仍为 `running`。
+
+Run 已成功但产物缺失或下载失败时，保留 `succeeded`、`completed=true`，错误写入 `error_message`。此前已成功下载的文件仍保留在媒体数组中。核对这些文件后可交付已完成部分，但不能宣称全部下载或交付成功。
+
+只有 `running` 且无错误时继续轮询；未知状态不能自动当作运行中。命令不提供完整会话消息或用户反问，不编造具体进度。轮询停止条件见 [共用流程](../workflows/async-delivery.md)。
 
 ## 样片结果
 
@@ -54,4 +64,4 @@ stdout 是 JSON；命令可能将错误编码进 JSON 并以退出码 0 返回
 
 文件名由 CLI 根据产物信息生成，以 `output_path` 为准，不自行拼接编号或推测扩展名。同目录已有同名文件可能被复用；复用不证明内容相同，也不代表本次新下载。发现同名文件属于其他产物时，选择用户认可范围内的未冲突目录再查询，不删除已有文件。
 
-找不到产物、链接缺失或下载失败时会返回错误。当前任一文件下载失败可能使整次查询只返回错误，无法据此认定其他文件都没下载或已完整交付。复查本次结果，不把输出目录里的任意旧文件当作本次产物。
+找不到产物、链接缺失或下载失败时会返回错误。下载中途失败时，媒体数组保留此前已成功下载或复用的文件；逐项核对 `output_path` 后可交付可用部分，并说明未完成项。不把输出目录里的任意旧文件当作本次产物，也不宣称已完整交付。

package/skills/xyq-nest-skill/scripts/ensure-cli.js

@@ -12,6 +12,18 @@ const REQUIRED_COMMANDS = [
   "generate-image", "generate-video", "video-super-resolution",
   "erase-video-subtitle", "get-credit-balance", "model list", "model describe",
 ];
+// v1.0.50 first ships ordinary-image binding guards in both Canvas entries.
+const MIN_CANVAS_VERSION = [1, 0, 50];
+
+function supportsCanvasBindings(version) {
+  const match = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z.-]+)?$/.exec(version);
+  if (!match) return false;
+  const parts = match.slice(1, 4).map(Number);
+  for (let i = 0; i < MIN_CANVAS_VERSION.length; i++) {
+    if (parts[i] !== MIN_CANVAS_VERSION[i]) return parts[i] > MIN_CANVAS_VERSION[i];
+  }
+  return true;
+}
 
 function npmCommand() {
   if (process.platform !== "win32") return ["npm", []];
@@ -80,6 +92,11 @@ function ensureCLI({ canvas = false } = {}) {
     if (expectedVersion && version !== expectedVersion) {
       throw new Error(`CLI 版本 ${version} 与 npm 包版本 ${expectedVersion} 不一致。`);
     }
+    if (canvas && !supportsCanvasBindings(version)) {
+      const failure = new Error(`Canvas 需要 CLI >=${MIN_CANVAS_VERSION.join(".")} 正式版以校验图片绑定，当前版本：${version}。`);
+      failure.missingCommand = "Canvas 图片绑定校验（CLI >=1.0.50 正式版）";
+      throw failure;
+    }
     const commands = REQUIRED_COMMANDS.map((command) => command.split(" "));
     if (canvas) {
       for (const command of ["create", "get", "allocate", "upload", "apply"]) commands.push(["canvas", command]);
@@ -165,7 +182,7 @@ function ensureCLI({ canvas = false } = {}) {
 
 if (require.main === module) {
   if (process.argv.length === 3 && process.argv[2] === "--help") {
-    console.log("Usage: node ensure-cli.js [--canvas]\n优先复用 PATH 或缓存中命令齐全的 CLI，不存在或缺少必需命令时安装 npm latest，成功输出 {cli_path, version} JSON。--canvas 额外验证画布原生命令和 npm 运行时，并返回 canvas_entry。");
+    console.log("Usage: node ensure-cli.js [--canvas]\n优先复用 PATH 或缓存中命令齐全的 CLI，不存在或缺少必需命令时安装 npm latest，成功输出 {cli_path, version} JSON。--canvas 要求 CLI >=1.0.50 正式版，额外验证画布原生命令和 npm 运行时，并返回 canvas_entry。");
   } else if (process.argv.length !== 2 && !(process.argv.length === 3 && process.argv[2] === "--canvas")) {
     console.error("不支持的参数。用法：node ensure-cli.js [--canvas]");
     process.exitCode = 1;

package/skills/xyq-nest-skill/scripts/install.md

@@ -16,7 +16,7 @@ node "{baseDir}/scripts/ensure-cli.js"
 
 可选参数按实际任务检查帮助：URL 导入前核对所选入口 `upload-file --help` 或 `canvas upload --help` 含 `--url`，缺少时先更新到支持版本。安装脚本只检查必需命令，不因未使用的 URL 参数自动升级，也不证明服务端已部署 URL 导入能力。
 
-命令齐全则直接复用，不检查最新版本；不存在或缺少必需命令时，获取 `@pippit-dev/cli@latest`。PATH 旧版本缺少命令但缓存完整时复用缓存，避免每次升级。版本命令不能运行或检查超时则报告运行错误。
+命令齐全则直接复用，不检查最新版本；Canvas 另有下述最低版本要求。不存在、缺少必需命令或不满足 Canvas 最低版本时，获取 `@pippit-dev/cli@latest`。PATH 旧版本不兼容但缓存完整时复用缓存，避免每次升级。版本命令不能运行或检查超时则报告运行错误。
 
 需要安装时，脚本跳过 npm 生命周期脚本获取包，调用包内 `scripts/install-cli.js` 只安装 CLI。成功后缓存到 `~/.cache/pippit-tool-cli/xyq-skill/<平台>-<架构>/current`。不要求全局 npm 写入权限，也不安装或清理全局 Skill。
 
@@ -36,7 +36,9 @@ node "{baseDir}/scripts/ensure-cli.js"
 
 ## Canvas 运行时检查
 
-画布任务改用 `node "{baseDir}/scripts/ensure-cli.js" --canvas`。除原有检查外，再验证五个原生资产子命令的帮助，并通过同一个 npm 包的 Node 入口真实执行离线 `canvas command list`，确认运行时可加载且含基本查询与节点创建能力。该检查不登录、不访问画布、不写入远端。
+画布任务改用 `node "{baseDir}/scripts/ensure-cli.js" --canvas`。要求 CLI 至少为 `1.0.50` 正式版，该版本起原生 `canvas apply` 和 npm 语义运行时均包含普通图片绑定校验；仅有同名命令不能证明旧版包含该修复。旧版、预发布版或无法识别的版本按不兼容处理，先查缓存，再至多安装一次；最新包仍不兼容则报错。普通媒体任务不受此最低版本限制。
+
+除原有检查外，再验证五个原生资产子命令的帮助，并通过同一个 npm 包的 Node 入口真实执行离线 `canvas command list`，确认运行时可加载且含基本查询与节点创建能力。该检查不登录、不访问画布、不写入远端。保留当前 Skill 的实际路径及返回的 `version`、`cli_path`、`canvas_entry`，便于故障定位；`Pippit-CLI/1.0` 是 User-Agent，不能作为 CLI 发行版本。
 
 成功额外返回 `canvas_entry`，供 `node "CANVAS_ENTRY" canvas command ...` 使用；`cli_path` 仍用于原生命令。语义操作的实际支持范围以当前目录为准，检查通过不代表所有业务操作或服务端权限都可用。
 

package/skills/xyq-nest-skill/workflows/async-delivery.md

@@ -7,15 +7,15 @@
 1. 提交成功后保存 `thread_id`、`run_id` 和 `web_thread_link`，立即向用户展示任务链接。已有任务直接使用其标识进入查询，不再次生成。
 2. 使用同一 `cli_path` 和同一对任务 ID 调用查询命令，明确 `--download-dir`。每隔 10 秒查询一次，不在轮询中重新安装 CLI。
 3. 先检查命令是否可执行、输出是否为有效 JSON，再读取非空 `error_message`；有错误就进入下面的失败处理。
-4. 无错误且 `completed=false` 时继续轮询，只说明尚未取得最终结果，不编造创作消息或完成百分比。
-5. 无错误且 `completed=true` 时，要求媒体数组中有待交付产物，逐项核对 `output_path` 后进入交付。空结果或缺少必要字段时报告异常，不空轮询。
+4. `status=input_required` 时停止自动轮询，提示需要补充输入；`status=interrupted` 或 `canceled` 时停止并报告对应终态。只有无错误且 `status=running` 时继续轮询，不编造创作消息或完成百分比。`unknown` 不等于运行中，报告无法确定任务状态。
+5. 无错误且 `status=succeeded`、`completed=true` 时，要求媒体数组中有待交付产物，逐项核对 `output_path` 后进入交付。空结果或缺少必要字段时报告异常，不空轮询。
 
 ## 停止与恢复
 
 - 明确的任务失败、鉴权失败、参数错误或产物缺失：停止并报告错误及可用的任务 ID、链接、LogID，不重新提交生成。
 - 可识别的暂时网络错误或下载错误：间隔 10 秒后仅重试同一次查询一次；仍失败则报告阻塞。无法判别错误类别时停止，避免盲目重试。
 - 用户要求停止时停止本地轮询；这不等于已取消服务端任务。持续未完成时遵守用户或宿主的等待时限，最迟在连续 48 小时后停止等待，保留 ID 供后续恢复查询。宿主无法持续执行时如实说明，不承诺后台监控。
-- 当前查询输出无法区分所有非成功状态；若长时间未完成或任务页面显示需要交互，报告当前查询能力的限制，不代答或新建任务。
+- 等待输入或人工交互中断时，查询输出不含完整反问内容；引导查看任务页面，不代答或新建任务。
 - 恢复时继续查询原任务，复用该任务已确定的输出目录，对已交付产物去重。
 
 ## 媒体交付完成标准

package/skills/xyq-nest-skill/workflows/canvas-edit.md

@@ -7,7 +7,7 @@
 3. **发现与查询**：`list → describe/schema` 定位操作。用 `get_snapshot` 查节点，用 `get_asset` 查具体资产；3D/多轨再查询其独立文档。`run` 是统一执行入口，其中 query/get 类操作是读取，不等于所有 run 都是写入。
 4. **准备输入**：使用查询所得的节点、子对象和资产 ID。外链素材通过 `canvas upload --url` 导入并保存 `pippit_asset_id`、`state` 与可能的 `warning`；也可复用 `upload-file --url` 返回的稳定 `asset_id`，再按 [URL 导入与资产复用](../commands/canvas-assets.md#url-import) 创建所需节点；已有资产直接复用，不重复导入。多轨 `expectedRevision` 来自最新查询。复杂输入写入 JSON 文件后传 `--file`；不要同时传 `--file` 和 `--input`。只操作用户指定范围。
 5. **预演与写入**：当前 schema 支持 `dryRun` 时可先预演，再在已有授权范围内执行真实修改。不能给所有命令强加此字段：领域命令的 dryRun 验证具体编辑，通用 `apply_mutations.dryRun` 不能替代领域预演。删除、恢复等操作仅按用户明确要求执行。
-6. **验证结果**：检查退出码与 JSON 的 `ok`、错误信息，`ok=false` 即失败。`dryRun=true` 成功不代表落盘；实际写入成功后，用对应查询回读目标字段及关联关系，确认没有误改其他对象。
+6. **验证结果**：检查退出码与 JSON 的 `ok`、错误信息，`ok=false` 即失败。`dryRun=true` 成功不代表落盘；实际写入成功后，用对应查询回读目标字段及关联关系，确认没有误改其他对象。素材绑定还须按[图片绑定契约](../commands/canvas-assets.md#低层事务的使用边界)核对节点类型、字段位置和素材身份：普通 `biz/image` 的 `content.pippitAssetId` 必须是所选图片素材，`content.assetId` 必须匹配该素材查询的 `Image.asset_id`。保存 ACK 只证明事务被接受，不证明参考素材可用。
 7. **反馈交付**：说明已验证的画布变化，保留已有/返回的画布链接及目标 ID。只完成文档编辑时不要声称图片/视频已生成；确有媒体文件待交付时遵循 [媒体交付标准](async-delivery.md)。
 
 语义执行骨架（占位符替换为当前目录中的命令、真实 ID 和已准备的输入文件）：
@@ -17,3 +17,5 @@ node "CANVAS_ENTRY" canvas command run COMMAND_NAME --canvas-id CANVAS_ASSET_ID
 ```
 
 写请求失败或返回“未确认事务已隔离”时保留错误上下文，先回读状态，不自动重跑、不删除本地恢复记录。多轨版本冲突需重新查询并基于新状态准备操作；检查点恢复会改变画布，不能作为所有失败的自动回滚方式。
+
+后续任务要把节点用于生视频参考时，先在原空间回读并完成上述核对。绑定缺失、错层或素材未就绪时停止提交，明确指出节点和缺失字段；保留原始错误与 LogID，不反复重试或手改上传状态。`node asset resource not ready` 表示素材预处理未就绪；即使外层显示“服务器繁忙”，也不能据此把重复生成当作恢复方式。