@pippit-dev/cli 1.0.12 → 1.0.14

package/README.md

@@ -9,11 +9,19 @@
 | 技能 | 说明 | 路径 |
 |-------|-------------|------|
 | `xyq-short-drama-skill` | 短剧工作流技能，支持提交创作任务、上传参考文件、查询进度、列出会话文件和下载产物。 | `skills/short-drama/` |
-| `xyq-skill` | 通用 NestAgent 技能，支持图片/视频生成、编辑、图片/视频/mp3或wav音频文件上传、进度查询和结果下载。 | `skills/xyq-nest-skill/` |
+| `xyq-skill` | 通用创作技能，支持 NestAgent 图片/视频生成与编辑，并在视频模型直出时调用 `pippit-tool-cli generate-video`。 | `skills/xyq-nest-skill/` |
+
+### 技能路由
+
+- 通用图片/视频生成、编辑和复杂参考素材编排使用 `xyq-skill`。
+- 用户明确要求视频模型直出、指定视频模型或直接调用 CLI 时，由 `xyq-skill` 调用 `pippit-tool-cli generate-video`，再用 `query-result` 查询和下载结果。
+- 短剧生成、续写、改写、人物设定、分集创作和短剧会话文件处理使用 `xyq-short-drama-skill`，不要与通用创作流程混用。
+
+两份技能需要用户补充、选择或确认时，优先调用宿主的结构化提问工具：Codex 使用 `request_user_input`，WorkBuddy 使用 `ask_user_question`，Trae 和其他宿主使用实际暴露的同类工具；没有同类工具时退回普通聊天提问。
 
 ## 通用 NestAgent 技能
 
-`xyq-skill` 通过接入小云雀 NestAgent 的综合创作能力，实现 AI 图片/视频生成、编辑、风格转换、图片/视频/mp3或wav音频文件上传、进度查询和结果下载。
+`xyq-skill` 通过接入小云雀 NestAgent 的综合创作能力，实现 AI 图片/视频生成、编辑、风格转换、图片/视频/mp3或wav音频文件上传、进度查询和结果下载；视频模型直出请求直接使用 `pippit-tool-cli generate-video`。
 
 ### 功能特性
 
@@ -23,6 +31,7 @@
 | 查询会话进展 | 增量拉取会话消息，轮询创作进度和产物结果。 |
 | 上传文件 | 上传图片/视频/mp3或wav音频到小云雀资产库，获取 `asset_id` 用于编辑和参考。 |
 | 下载结果 | 批量下载生成的图片/视频到本地，支持并行下载。 |
+| 视频模型直出 | 调用 `generate-video` 提交请求，展示 `web_thread_link`，再用 `query-result` 查询并下载视频。 |
 
 小云雀平台能力覆盖：
 

package/checksums.txt

@@ -1,6 +1,6 @@
-127a8f5d5f5c655e671fcd9dee1ce5007ce85f5cd3fbb8bd96310bbfb9c36233  pippit-tool-cli-1.0.12-darwin-amd64.tar.gz
-2f51e8957dae53550f07b63aedb38aafa39c42b07a5d7bf2bc9591cceea933e4  pippit-tool-cli-1.0.12-darwin-arm64.tar.gz
-d25be6ff1afc4ca2f16028993f7340d210bd20e10a98e81dcd29122f156934ba  pippit-tool-cli-1.0.12-linux-amd64.tar.gz
-85f5edd2da2a143f7b41145a3e090d84dce2aaf877189c95b04769bde081bda2  pippit-tool-cli-1.0.12-linux-arm64.tar.gz
-205e82c8982ce275a87884b056304e595815dafc62c9be186299b5b684066aba  pippit-tool-cli-1.0.12-windows-amd64.zip
-4264f068bf7bbdc6bada501eec7867d83b2c494543a53c0b82cdecf55205188f  pippit-tool-cli-1.0.12-windows-arm64.zip
+7e8b88e21ebfd05357f0183c408bfbacaf6c583398e9ab8f3edd24063be911b1  pippit-tool-cli-1.0.14-darwin-amd64.tar.gz
+e514b59bb83b59130deb9cec6cb0f114fd11fe47921d7a65e2f697ad5d528e07  pippit-tool-cli-1.0.14-darwin-arm64.tar.gz
+436efcab90026d8e0d3e593943d8cbd473a5219017685c1099f09992a7034d4b  pippit-tool-cli-1.0.14-linux-amd64.tar.gz
+d4a7916d18a16b7b179db6251931796440e236a6d8d841e385bf02e4de9bca29  pippit-tool-cli-1.0.14-linux-arm64.tar.gz
+9688067ffd270653e81570ff2cd395e51d92f82248573c3682a3d7c3fd6cbb89  pippit-tool-cli-1.0.14-windows-amd64.zip
+98d211cd42c0d1a7b526f9a0cca7456d0e9acbf56a0f4da4c7dc1b2d25d457ff  pippit-tool-cli-1.0.14-windows-arm64.zip

package/cmd/generate_image/generate_image.go

@@ -33,6 +33,7 @@ func NewCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command
 					"image":                strings.Join(opts.ImagePaths, ","),
 					"model":                strings.TrimSpace(opts.Model),
 					"ratio":                strings.TrimSpace(opts.Ratio),
+					"resolution":           strings.ToUpper(strings.TrimSpace(opts.Resolution)),
 					"generate_image_count": optionalIntString(opts.GenerateImageCount),
 				})
 				return err
@@ -47,6 +48,7 @@ func NewCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command
 	flags.StringArrayVar(&opts.ImagePaths, "image", nil, "local reference image path; repeat for multiple images")
 	flags.StringVar(&opts.Model, "model", "", "image model; supported: seedream_5.0_pro, seedream_5.0, seedream_4.3, nova2, seedream_4.5, seedream_4.1, seedream_4")
 	flags.StringVar(&opts.Ratio, "ratio", "", "image ratio; "+internalgen.SupportedRatioUsage())
+	flags.StringVar(&opts.Resolution, "resolution", "", "image resolution; only seedream_5.0_pro supports these options: 1K, 2K, 4K")
 	flags.IntVar(&generateImageCount, "generate-image-count", 0, "generated image count")
 	return cmd
 }

package/cmd/generate_image_test.go

@@ -66,12 +66,15 @@ func TestGenerateImage(t *testing.T) {
 			if !ok {
 				t.Fatalf("general_agent_settings = %#v, want object", body["general_agent_settings"])
 			}
-			if settings["image_model"] != "seedream_4.5" {
-				t.Fatalf("image_model = %v, want seedream_4.5", settings["image_model"])
+			if settings["image_model"] != "seedream_5.0_pro" {
+				t.Fatalf("image_model = %v, want seedream_5.0_pro", settings["image_model"])
 			}
 			if settings["ratio"] != float64(6) {
 				t.Fatalf("ratio = %v, want 6", settings["ratio"])
 			}
+			if settings["resolution"] != "4K" {
+				t.Fatalf("resolution = %v, want 4K", settings["resolution"])
+			}
 			if settings["generate_image_count"] != float64(2) {
 				t.Fatalf("generate_image_count = %v, want 2", settings["generate_image_count"])
 			}
@@ -97,8 +100,9 @@ func TestGenerateImage(t *testing.T) {
 		"generate-image",
 		"--prompt", "生成小猫海报",
 		"--image", image,
-		"--model", "seedream_4.5",
+		"--model", "seedream_5.0_pro",
 		"--ratio", "6",
+		"--resolution", "4K",
 		"--generate-image-count", "2",
 	})
 

package/cmd/generate_video_test.go

@@ -446,7 +446,7 @@ func TestQueryResultIgnoresVideoDataWithoutVideoSubType(t *testing.T) {
 	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["error_message"] != "下载失败：未找到可下载的视频产物" {
+	if got["error_message"] != "下载失败：未找到可下载的产物" {
 		t.Fatalf("error_message = %v, want no downloadable video error", got["error_message"])
 	}
 	videos, ok := got["videos"].([]any)

package/internal/generate_image/generate_image.go

@@ -27,12 +27,14 @@ type Options struct {
 	ImagePaths         []string
 	Model              string
 	Ratio              string
+	Resolution         string
 	GenerateImageCount *int
 }
 
 type generalAgentSettings struct {
 	ImageModel         string `json:"image_model"`
 	Ratio              *int   `json:"ratio,omitempty"`
+	Resolution         string `json:"resolution,omitempty"`
 	GenerateImageCount *int   `json:"generate_image_count,omitempty"`
 }
 
@@ -142,6 +144,7 @@ func buildSubmitRunBody(opts *Options, imageAssetIDs []string) map[string]any {
 		"general_agent_settings": generalAgentSettings{
 			ImageModel:         strings.TrimSpace(opts.Model),
 			Ratio:              ratio,
+			Resolution:         strings.ToUpper(strings.TrimSpace(opts.Resolution)),
 			GenerateImageCount: opts.GenerateImageCount,
 		},
 	}

package/internal/generate_image/generate_image_test.go

@@ -42,6 +42,18 @@ func TestValidateOptionsAllowsServerDecidedRatio(t *testing.T) {
 	}
 }
 
+func TestValidateOptionsAllowsServerDecidedResolution(t *testing.T) {
+	opts := &Options{
+		Prompt:     "x",
+		Model:      "seedream_4.5",
+		Resolution: "8K",
+	}
+
+	if err := ValidateOptions(opts); err != nil {
+		t.Fatalf("ValidateOptions() error = %v, want nil", err)
+	}
+}
+
 func TestValidateOptionsRejectsNegativeGenerateImageCount(t *testing.T) {
 	count := -1
 	opts := &Options{
@@ -116,8 +128,9 @@ func TestBuildSubmitRunBodyWithGeneralAgentSettings(t *testing.T) {
 	count := 2
 	opts := &Options{
 		Prompt:             "  生成小猫海报  ",
-		Model:              " seedream_4.5 ",
+		Model:              " seedream_5.0_pro ",
 		Ratio:              "6",
+		Resolution:         " 4k ",
 		GenerateImageCount: &count,
 	}
 
@@ -132,12 +145,15 @@ func TestBuildSubmitRunBodyWithGeneralAgentSettings(t *testing.T) {
 	if !ok {
 		t.Fatalf("general_agent_settings = %#v, want object", body["general_agent_settings"])
 	}
-	if settings.ImageModel != "seedream_4.5" {
-		t.Fatalf("image_model = %q, want seedream_4.5", settings.ImageModel)
+	if settings.ImageModel != "seedream_5.0_pro" {
+		t.Fatalf("image_model = %q, want seedream_5.0_pro", settings.ImageModel)
 	}
 	if settings.Ratio == nil || *settings.Ratio != 6 {
 		t.Fatalf("ratio = %#v, want 6", settings.Ratio)
 	}
+	if settings.Resolution != "4K" {
+		t.Fatalf("resolution = %q, want 4K", settings.Resolution)
+	}
 	if settings.GenerateImageCount == nil || *settings.GenerateImageCount != 2 {
 		t.Fatalf("generate_image_count = %#v, want 2", settings.GenerateImageCount)
 	}

package/package.json

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

package/skills/short-drama/SKILL.md

@@ -63,6 +63,12 @@ metadata:
 
 当后端 Agent 通过 `readable_text` 要求用户补充信息、选择选项、确认流程或确认创意内容时，优先使用当前宿主提供的 ask-question / confirmation / form 类工具向用户提问，而不是只在普通聊天里输出问题。
 
+按宿主选择准确工具：
+
+- **Codex**：优先调用 `request_user_input`。仅在工具已暴露且当前模式允许时调用；不可用时退回普通聊天提问。不要在 Codex 中调用 `ask_user_question`。
+- **WorkBuddy**：优先调用 `ask_user_question`（Ask User Question）；工具未暴露时才退回普通聊天提问。
+- **Trae 及其他宿主**：先查看当前宿主实际暴露的工具，再使用同类结构化提问、确认或表单工具；不要臆造具体工具名。没有同类工具时退回普通聊天提问。
+
 使用宿主提问工具前，先按“表单与问卷选项处理原则”清洗问题和选项：
 
 - 只把当前阶段合理、必要、可执行的选项放进提问工具。
@@ -70,6 +76,8 @@ metadata:
 - 对普通开放问题，用单个清晰问题询问用户；对明确互斥选项，用宿主支持的选择控件。
 - 如果当前宿主没有暴露可调用的 ask-question / confirmation / form 工具，才退回普通聊天提问，并说明需要用户回复后才能继续。
 
+真实提交将进入消耗 credits 的图片生成、视频生成或编辑阶段时，如果用户本轮尚未明确确认执行，必须使用上述工具征得明确确认。不要设置默认同意、自动选择或超时后继续；纯文本规划和查询进展不需要额外确认。
+
 ## 前置要求
 
 需要已安装 `pippit-tool-cli`：

package/skills/xyq-nest-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: xyq-skill
-description: 通过小云雀的 AI 能力进行综合创作，支持生成和编辑图片/视频。覆盖场景包括：生成（文生图、文生视频、图生视频、做动画、画一个xxx、来段xxx）、编辑修改（把xxx换成yyy、去掉xxx、加上xxx、改成xxx、调整xxx、局部修改、改镜头）、风格转换（风格迁移、转绘、换风格）、视频续写延长、复刻视频/TVC/宣传片、短剧/短漫剧生成、音乐MV生成、产品广告/展示片制作、分镜/故事板设计、教育视频/短视频制作。当用户提到小云雀、xyq、上传参考图/视频/mp3或wav音频、查看生成进度时也应触发。关键判断：只要用户的请求涉及 AI 视频的创作、生成、编辑、修改，无论措辞如何（如"画只猫"、"做个海报"、"做个视频"、"这个视频帮我改一下"、"帮我复刻这段视频"、"用这首歌做个MV"、"一句话生成短剧"），都必须触发此技能。
+description: 通过小云雀的 AI 能力进行综合创作，支持生成和编辑图片/视频，并在用户明确要求图片或视频模型直出、指定图片或视频模型或直接调用 CLI 时使用 pippit-tool-cli generate-image / generate-video。覆盖文生图、文生视频、图生视频、视频编辑、风格转换、视频续写、视频复刻、TVC、宣传片、音乐 MV、产品广告、分镜和教育短视频等场景。当用户提到小云雀、xyq、上传参考图/视频/mp3或wav音频、查看生成进度时也应触发。短剧生成、续写、改写、人物设定和分集创作应使用 xyq-short-drama-skill，不在本技能中执行。
 user-invocable: true
 metadata:
   {
@@ -17,7 +17,7 @@ metadata:
   }
 ---
 
-# 小云雀会话（生视频）
+# 小云雀创作与图片/视频模型直出
 
 通过 小云雀的API 创建会话、发送消息（生图、生视频、编辑视频等）、上传图片/视频/mp3或wav音频文件，并查询会话消息进展。
 
@@ -26,9 +26,93 @@ metadata:
 **平台核心能力：**
 - **生成**：文生图、文生视频、图生视频、视频续写
 - **编辑**：局部修改、元素替换、镜头调整、风格迁移
-- **复杂创作**：一句话生成完整短剧（剧本→分镜→成片）、复刻已有视频风格做 TVC/宣传片、用音乐生成 MV、产品展示片制作
+- **复杂创作**：复刻已有视频风格做 TVC/宣传片、用音乐生成 MV、产品展示片制作
 
-用户的所有创作和编辑需求都通过发送自然语言消息来完成，Agent 会自主编排工作流。复杂任务（短剧、MV）耗时较长，需耐心轮询。
+除“图片/视频模型直出”外，创作和编辑需求通过发送自然语言消息来完成，后端 Agent 会自主编排工作流。复杂任务耗时较长，需耐心轮询。
+
+## 执行路由（必须先判断）
+
+### 路由 A：图片模型直出
+
+满足任一条件时，必须直接使用 `pippit-tool-cli generate-image`，不要改走 `submit_run.py`：
+
+- 用户明确说“图片模型直出”、“直接调图片模型”或明确要求用 CLI 生图。
+- 用户指定了具体图片模型（如 `seedream_5.0_pro`），并希望单次直接生成图片。
+- 上游流程已明确将任务标记为图片 direct-model / 模型直出。
+
+执行原则：
+
+1. 执行前用 `command -v pippit-tool-cli` 确认 CLI 可用；不可用时报告阻塞，不要悄悄降级到会话 API。
+2. 真实提交会消耗 credits；如果用户本轮尚未明确确认生成，按“用户确认与反问”规则征得明确确认后再运行。
+3. 保留用户原始 prompt，不要自行扩写、润色、翻译或增加风格词。
+4. `--model` 必填；用户未提供图片模型时，先询问使用哪个模型。只添加用户已经给出的 `--ratio`、`--resolution`、`--generate-image-count`、`--image` 参数，不补默认值。
+5. `--resolution` 的使用说明是：仅 `seedream_5.0_pro` 支持 `1K`、`2K`、`4K`。不要在 skill 侧维护额外 allowlist 或自行改写用户值，实际合法性由服务端决定。
+6. `generate-image` 返回后，保存 `thread_id`、`run_id`，并立即向用户展示 `web_thread_link`。
+7. 每隔 10 秒调用 `query-result`，直到 `completed=true`。出现 `error_message` 时停止并报告；成功时展示并下载 `images[].output_path`。
+
+```bash
+pippit-tool-cli generate-image \
+  --prompt "用户原始描述" \
+  --model IMAGE_MODEL
+  --ratio RATIO
+  --resolution RESOLUTION
+  --generate-image-count COUNT
+  --image 参考图路径
+
+pippit-tool-cli query-result \
+  --thread-id THREAD_ID \
+  --run-id RUN_ID \
+  --download-dir OUTPUT_DIR
+```
+
+### 路由 B：视频模型直出
+
+满足任一条件时，必须直接使用 `pippit-tool-cli generate-video`，不要改走 `submit_run.py`：
+
+- 用户明确说“视频模型直出”、“直接调模型”或“直接调用 CLI”。
+- 用户指定了具体视频模型（如 Seedance），并希望单次直接生成视频。
+- 上游流程已明确将任务标记为 direct-model / 模型直出。
+
+执行原则：
+
+1. 执行前用 `command -v pippit-tool-cli` 确认 CLI 可用；不可用时报告阻塞，不要悄悄降级到会话 API。
+2. 真实提交会消耗 credits；如果用户本轮尚未明确确认生成，按“用户确认与反问”规则征得明确确认后再运行。
+3. 保留用户原始 prompt，不要自行扩写、润色、翻译或增加风格词。
+4. 只添加用户已经给出的 `--model`、`--duration`、`--ratio`、`--resolution`、`--image`、`--video`、`--audio` 参数；未给参数交给 CLI 默认值。
+5. `generate-video` 返回后，保存 `thread_id`、`run_id`，并立即向用户展示 `web_thread_link`。
+6. 每隔 10 秒调用 `query-result`，直到 `completed=true`。出现 `error_message` 时停止并报告；成功时展示并下载 `videos[].output_path`。
+
+```bash
+pippit-tool-cli generate-video --prompt "用户原始描述"
+
+pippit-tool-cli query-result \
+  --thread-id THREAD_ID \
+  --run-id RUN_ID \
+  --download-dir OUTPUT_DIR
+```
+
+`--image` 最多重复 9 次，`--video` 和 `--audio` 最多各重复 3 次。
+
+### 路由 C：小云雀后端 Agent 编排
+
+需要意图确认、脚本/分镜拆解、MV、TVC、局部编辑、复杂参考素材编排，或者用户未明确要求模型直出时，继续使用本技能内置的 `submit_run.py` / `get_thread.py` 会话工作流。
+
+### 路由 D：短剧工作流
+
+用户要求短剧生成、续写、改写、剧情扩展、人物设定、分集草稿或短剧会话文件处理时，停止本技能流程并转交 `xyq-short-drama-skill`，不要用 `submit_run.py`、`generate-image` 或 `generate-video` 假装执行完整短剧流程。
+
+## 用户确认与反问
+
+后端返回意图确认问题、真实提交前需要 credits 确认，或缺少无法安全推断的必需信息时，暂停执行并向用户提问。
+
+1. 优先使用当前 Agent 宿主提供的结构化用户提问或确认工具。
+   - **Codex**：准确工具名是 `request_user_input`。仅在工具已暴露且当前模式允许时调用；不可用时退回普通聊天提问。不要在 Codex 中调用 `ask_user_question`。
+   - **WorkBuddy**：准确工具名是 `ask_user_question`（Ask User Question）。需要用户补充、选择或确认时优先调用；工具未暴露时才退回普通聊天提问。
+   - **Trae 及其他宿主**：先查看当前宿主实际暴露的工具，再使用同类结构化提问、确认或表单工具；不要臆造具体工具名。没有同类工具时退回普通聊天提问。
+2. 涉及 credits、真实生成、外部提交或不可逆操作时，必须等待用户明确答复；不要默认同意或超时后继续。
+3. 后端已经给出问题或选项时，保持原意传给用户，不要代替用户回答。
+4. 当前宿主没有结构化提问工具，或当前模式不允许调用时，使用一条简洁的普通聊天问题并暂停。
+5. 收到回复后，把用户答案原样发回同一 `thread_id`，获取新的 `run_id`，再继续轮询；不要新开会话。
 
 ## 功能
 
@@ -36,6 +120,8 @@ metadata:
 2. **查询会话进展** - 根据 `thread_id` 、 `run_id`、`after_seq` 增量拉取该会话的消息列表，用于轮询创作过程的消息和最终产物结果
 3. **上传文件** - 支持上传`单张图片`、`单个视频文件`或`单个mp3/wav音频文件`到小云雀资产库，得到文件对应的 `asset_id`（编辑或参考已有图片/视频/音频时需要先上传）
 4. **下载结果** - 将会话中生成的图片/视频批量下载到本地，支持指定输出目录和文件名前缀。
+5. **图片模型直出** - 使用 `pippit-tool-cli generate-image` 直接调用图片模型，使用 `query-result` 查询并下载图片结果。
+6. **视频模型直出** - 使用 `pippit-tool-cli generate-video` 直接调用视频模型，使用 `query-result` 查询并下载视频结果。
 
 
 ## 前置要求
@@ -46,7 +132,7 @@ export XYQ_ACCESS_KEY="your-access-key"
 
 可选：`XYQ_OPENAPI_BASE` 或 `XYQ_BASE_URL`，默认 `https://xyq.jianying.com`。
 
-无需安装额外依赖，仅使用 Python 标准库。
+会话 API 路由无需安装额外依赖，仅使用 Python 标准库。图片/视频模型直出路由额外要求 `pippit-tool-cli` 在 `PATH` 中可用。
 
 ## 使用方法
 
@@ -98,7 +184,7 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
 
 理解这些工作流，才能正确组合上面的脚本完成用户需求。
 
-### 场景 1：用户要求生成图片或视频（最常见）
+### 场景 1：用户要求生成图片或视频（非模型直出）
 
 ```
 1. submit_run.py --message "用户的描述"  →  拿到 thread_id、run_id 和 web_thread_link
@@ -109,7 +195,7 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
     - 将过程创作信息展示给用户，继续轮询
   - 当任务完成（run 结束）：
     - 如果涉及意图确认/流程中断（如"请回答以下问题"）：
-      → 向用户展示问题，等待用户回复
+      → 优先调用当前宿主的结构化用户提问工具展示问题，等待用户回复
       → 使用 `thread_id` 重新提交任务（保持同一会话，产生新的 run_id）
       → 回到步骤 2 继续轮询（可能多轮，直到不再意图确认）
     - 如果 content 中包含产物 URL：
@@ -118,7 +204,18 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
 6. 向用户展示：过程中的创作信息，以及下载后的本地文件列表
 ```
 
-### 场景 2：用户提供图片/视频/音频要求编辑修改或作为参考（如"参考这个视频做一个新的"、"用这首歌做MV"）
+### 场景 2：用户明确要求图片模型直出
+
+```
+1. command -v pippit-tool-cli  →  确认 CLI 可用
+2. 检查图片模型：用户未提供时先询问，不要自行选择
+3. pippit-tool-cli generate-image --prompt "用户原始描述" --model IMAGE_MODEL [仅添加用户已给出的其他参数]
+4. 拿到 thread_id、run_id 和 web_thread_link，立即展示 web_thread_link
+5. 每隔 10 秒调用 query-result --thread-id THREAD_ID --run-id RUN_ID --download-dir OUTPUT_DIR
+6. completed=true 后展示并下载 images[].output_path；出现 error_message 时停止并报告
+```
+
+### 场景 3：用户提供图片/视频/音频要求编辑修改或作为参考（如"参考这个视频做一个新的"、"用这首歌做MV"）
 
 ```
 1. upload_file.py /path/to/video.mp4  →  拿到 asset_id1
@@ -129,7 +226,7 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
 
 用户给了文件路径 + 编辑指令 = 先上传文件，再把编辑指令和 所有asset_id 一起发送。
 
-### 场景 3：用户提供参考图/视频/音频要求生成新内容
+### 场景 4：用户提供参考图/视频/音频要求生成新内容
 
 ```
 1. upload_file.py /path/to/ref1.png  →  拿到 asset_id1
@@ -140,7 +237,7 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
 6. 后续同场景 1 的步骤 2-6
 ```
 
-### 场景 4：在已有会话中追加新需求
+### 场景 5：在已有会话中追加新需求
 
 ```
 1. submit_run.py --message "新的描述" --thread-id THREAD_ID  →  拿到 thread_id、run_id、web_thread_link
@@ -211,18 +308,18 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
 - 任务在创作中：
   - 展示过程中的创作信息等，继续轮询
 - 任务完成（run 结束）：
-  - 若涉及意图确认/流程中断（如"请回答以下问题"）→ 展示问题 → 等待用户回复 → 使用同一 `thread_id` 重新提交任务 → 继续轮询（可能多轮）
+  - 若涉及意图确认/流程中断（如"请回答以下问题"）→ 按“用户确认与反问”规则优先调用结构化提问工具 → 等待用户回复 → 使用同一 `thread_id` 重新提交任务 → 继续轮询（可能多轮）
   - 若 content 中包含产物 URL：
   - 结果地址：来自 `get_thread` 返回的 `messages` 中，任务创作完成会包含产物 URL，将产物链接、下载的本地文件等信息告知用户。
 
 ## 核心原则：用户侧不做创作，只做传话
 
-你（用户侧 Agent）的职责是**搬运工**，不是创作者。后端有专门的 Agent 负责理解需求、拆解分镜、编排工作流、选模型、写 prompt。你要做的只有三件事：
+你（用户侧 Agent）的职责是**搬运工**，不是创作者。会话 API 路由由后端 Agent 负责理解需求、拆解分镜、编排工作流、选模型、写 prompt；图片/视频模型直出路由把用户原始参数传给 CLI。你要做的是：
 
-1. **上传**：如果用户给了本地文件 → `upload_file.py` 拿到 asset_id
-2. **提交任务**：把用户的原始描述 + asset_id 原封不动发给 `submit_run.py`
+1. **准备素材**：会话 API 路由用 `upload_file.py` 把本地文件转为 asset_id；图片/视频模型直出路由把本地路径直接交给 CLI 的 `--image` / `--video` / `--audio` 参数
+2. **提交任务**：先按“执行路由”判断；图片模型直出调用 `pippit-tool-cli generate-image`，视频模型直出调用 `pippit-tool-cli generate-video`，其余任务把用户的原始描述 + asset_id 原封不动发给 `submit_run.py`
 3. **传话**：根据 `get_thread.py` 返回的消息列表，展示过程中的意图询问、创作信息等
-4. **取件**：`get_thread.py` 轮询结果 → 检查结果 → 下载产物 → 结果展示给用户
+4. **取件**：会话 API 路由用 `get_thread.py` 轮询，图片/视频模型直出路由用 `query-result` 轮询 → 检查结果 → 下载产物 → 结果展示给用户
 
 **绝对不要做的事：**
 - 不要替用户扩写、润色、翻译 prompt（用户说"帮我推演分镜"，就直接传"帮我推演分镜"，不要自己先写个分镜表再逐条发）
@@ -258,3 +355,4 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
 - 查询会话时可用 --after-seq 做增量拉取，便于轮询新消息（含 assistant 回复与生图/生视频结果）
 - 上传文件仅支持图片（image/*）、视频（video/*）和 `.mp3/.wav` 音频文件，其他类型会被拒绝，文件大小须在 200MB 以下
 - 生成过程中将过程中的创作信息展示给用户；任务完成后给出**产物结果（图片/视频）URL链接**和下载的**本地文件列表**。
+- 图片/视频模型直出任务必须保留 `generate-image` / `generate-video` 返回的 `thread_id` / `run_id`，并用 `query-result` 取回最终图片或视频。