@pippit-dev/cli 1.0.51 → 1.0.53

package/README.md

@@ -77,6 +77,20 @@ pippit-tool-cli get-credit-balance --team-id 0      # 仅本次使用个人
 
 `space list/use TEAM_ID` 依赖 API 部署 `/api/biz/v1/skill/get_lite_team_list` 的 AK 适配入口，业务团队使用还依赖对应 API 团队权限实现；不直连 commerce Web 接口。宿主 Agent 的选择、任务恢复与不回退规则已写入三个 Skill 的 `Space Selection` 章节。
 
+## 账号 AIGC 水印设置
+
+```bash
+pippit-tool-cli watermark       # 查询当前账号的 AIGC 水印开关
+pippit-tool-cli watermark off   # 保存内容时去除 AIGC 水印
+pippit-tool-cli watermark on    # 恢复保留 AIGC 水印
+```
+
+查询和修改均输出 `{"enabled":true}` 或 `{"enabled":false}`，`true` 表示保留 AIGC 水印。无参数只查询，只有显式 `on` / `off` 才修改；修改接口在服务端回读后返回当前状态。
+
+这是当前认证账号的持久设置，与 Web「保存内容去除 AIGC 水印」同步；不依赖默认个人/团队空间，也不会变成团队开关。品牌水印与最终下载权益仍由服务端决定，关闭 AIGC 开关不代表所有视频均无任何水印。修改失败或结果不明时先用无参数命令查询，不自动重复写入。
+
+依赖 API 部署 `/api/biz/v1/skill/mget_user_setting` 和 `/api/biz/v1/skill/update_user_setting` 的 AK 接口。前者接收 `{}`，后者接收 `{"enabled":true}` 或 `{"enabled":false}`；接口仅读写 AK 所属账号的 AIGC 设置。
+
 ## 小云雀营销成片技能
 
 入口：[skills/xyq-marketing-skill/SKILL.md](skills/xyq-marketing-skill/SKILL.md)。使用 [官网](https://xyq.jianying.com/cli?tab=api) 已开放的营销 API，支持素材上传、营销视频提交、结果查询与下载、积分查询。安装器会从 `skills/` 自动安装该 Skill，也可以单独安装：
@@ -452,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 @@
-95c1a5b68a1df337ef3869de5cd00172b766c9324975f2a7358631d92b843137  pippit-tool-cli-1.0.51-darwin-amd64.tar.gz
-05a617b10aa6768f1a0d51c82d5f1bbf7a3ed6196db17247dfaad7cd1f46f957  pippit-tool-cli-1.0.51-darwin-arm64.tar.gz
-fb1edb92514aa2941b8c83ca1b806f76cdd1a0e19610b6ac9af38e415b9e060e  pippit-tool-cli-1.0.51-linux-amd64.tar.gz
-45b57561a0f190d32e4f05cc2aef6e9d2421263f7cec4cacd1e0151d5b1898aa  pippit-tool-cli-1.0.51-linux-arm64.tar.gz
-0f727048f4e3915a3f58e7c3b0b4df6d3fcd4214a17881cdb37f2958c417d86a  pippit-tool-cli-1.0.51-windows-amd64.zip
-1b05ef17e005e405997cf78622afbdc6d161f20c855347fabc5a0a46cf00399d  pippit-tool-cli-1.0.51-windows-arm64.zip
+08e0f157a05bdcbbb4c7a53eeeee3374d5be4bf86ec31139c5d42328c8cc781e  pippit-tool-cli-1.0.53-darwin-amd64.tar.gz
+fa1b79ed862a997d7ec8117895158f1914d2fcaa30792b303fd924d2856a834f  pippit-tool-cli-1.0.53-darwin-arm64.tar.gz
+e0d30c4edf201108587da2bd1ce97f9e7a30721e41700c50e7ddb57cc4c2474a  pippit-tool-cli-1.0.53-linux-amd64.tar.gz
+b60c817d9b58659838baf9954e5cc110ddc92ed2736e5512047dc2b20a9dfde8  pippit-tool-cli-1.0.53-linux-arm64.tar.gz
+b890470552424b37fbd98d8a0e202d66526f7f575233cfb860599dadbc802be2  pippit-tool-cli-1.0.53-windows-amd64.zip
+cf549f5b6e7d929d7b8b48b0a1a3df467ad921c23b4a93361799d7723b023bde  pippit-tool-cli-1.0.53-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/root.go

@@ -119,6 +119,7 @@ func newRootCommandWithAdapter(stdout, stderr io.Writer, runner *common.Runner,
 	root.AddCommand(canvascmd.NewCommand(stdout, stderr, runner))
 	root.AddCommand(newDownloadResultCommand(stdout, stderr, runner))
 	root.AddCommand(newGetCreditBalanceCommand(stdout, stderr, runner))
+	root.AddCommand(newWatermarkCommand(stdout, stderr, runner))
 	root.AddCommand(newModelCommand(stdout, stderr, runner))
 	root.AddCommand(newMarketingCommand(stdout, stderr, runner, policy))
 	root.AddCommand(newGetThreadCommand(stdout, stderr, runner))

package/cmd/space.go

@@ -30,7 +30,7 @@ func prepareCommandSpace(cmd *cobra.Command, runner *common.Runner, stderr io.Wr
 		top = top.Parent()
 	}
 	switch top.Name() {
-	case commandnames.Space, commandnames.Login, commandnames.Logout, commandnames.Status, commandnames.Update, commandnames.Completion, commandnames.Help, commandnames.DownloadResult:
+	case commandnames.Space, commandnames.Login, commandnames.Logout, commandnames.Status, commandnames.Update, commandnames.Completion, commandnames.Help, commandnames.DownloadResult, commandnames.Watermark:
 		return nil
 	}
 	raw, _ := cmd.Flags().GetString("space-context")

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

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