@pippit-dev/cli 1.0.11 → 1.0.13

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` 查询并下载视频。 |
 
 小云雀平台能力覆盖：
 
@@ -213,6 +222,37 @@ pippit-tool-cli download-result --output-path ./thread_123/results/result.mp4 --
 
 短剧命令的错误日志会追加写入本地每日日志文件：`~/.pippit_tool_cli/logs/yyyy-mm-dd.log`。日志路径会基于当前用户主目录和系统路径分隔符生成，因此可在 macOS、Linux 和 Windows 上使用。
 
+## 生图 CLI
+
+`generate-image` 会上传本地参考图片，然后向综合 Nest Agent 提交生图请求：
+
+```bash
+pippit-tool-cli generate-image \
+  --prompt "生成一张小猫海报" \
+  --image "~/images/cat.png" \
+  --model "seedream_4.5" \
+  --ratio 6 \
+  --generate-image-count 2
+```
+
+命令输出 `thread_id`、`run_id` 和 `web_thread_link`。提交 HTTP 请求时，`agent_name` 固定为 `pippit_nest_agent`，参考图会使用上传接口返回的 `pippit_asset_id` 写入顶层 `asset_ids`，生图模型写入 `general_agent_settings.image_model`，比例写入 `general_agent_settings.ratio`，生图数量写入 `general_agent_settings.generate_image_count`。`--model` 为必填参数，CLI 只做非空校验，具体模型值是否可用由服务端决定。
+
+`--ratio` 可选，填写服务端 `Ratio` 枚举值。CLI 只做整数格式解析，不检查枚举值是否在下表范围内；具体值是否可用由服务端决定。常用枚举值含义如下：
+
+| ratio 参数 | IDL 枚举 | 含义 |
+| ---: | --- | --- |
+| `0` | `CanvasRatioOriginal` | 原始比例（自动） |
+| `2` | `CanvasRatio16To9` | 16:9（横屏） |
+| `13` | `CanvasRatio21To9` | 21:9（电影） |
+| `3` | `CanvasRatio9To16` | 9:16（竖屏） |
+| `4` | `CanvasRatio4To3` | 4:3 |
+| `5` | `CanvasRatio3To4` | 3:4 |
+| `6` | `CanvasRatio1To1` | 1:1 |
+
+`--generate-image-count` 可选，填写生图数量，对应 IDL 字段 `GeneralSettingsPart.GenerateImageCount` / JSON 字段 `generate_image_count`。CLI 只校验不能为负数；具体数量范围由服务端决定。
+
+图片支持 `.jpg`、`.jpeg`、`.png`、`.gif`、`.bmp`、`.webp`、`.svg`。CLI 会在提交前校验 prompt、model 必填、ratio 整数格式、generate-image-count 非负和文件后缀。
+
 ## 生视频 CLI
 
 `generate-video` 会上传本地参考图片、视频和音频，然后向视频片段 Agent 提交生视频请求：
@@ -233,7 +273,7 @@ pippit-tool-cli generate-video \
 
 命令输出 `thread_id`、`run_id` 和 `web_thread_link`。提交生视频 HTTP 请求时，参考图、参考视频和参考音频会使用上传接口返回的 `pippit_asset_id`，并分别写入 `video_part_tool_param.images`、`video_part_tool_param.videos` 和 `video_part_tool_param.audios`。图片最多 9 张，支持 `.jpg`、`.jpeg`、`.png`、`.gif`、`.bmp`、`.webp`、`.svg`；视频最多 3 个，支持 `.mp4`、`.avi`、`.mov`、`.wmv`、`.flv`、`.webm`、`.mkv`、`.m4v`；音频最多 3 个，仅支持 `.mp3`、`.wav`。普通用户支持模型 `Seedance_2.0_mini_lite`；`seedance2.0_vision`、`seedance2.0_fast_vision` 和 `Seedance_2.0_mini` 为 VIP 专属模型。CLI 会在提交前校验 prompt、素材数量和文件后缀；模型、比例、分辨率等语义校验由服务端处理。
 
-查询并下载生视频结果：
+查询并下载生图/生视频结果：
 
 ```bash
 pippit-tool-cli query-result \
@@ -242,7 +282,7 @@ pippit-tool-cli query-result \
   --download-dir "./output"
 ```
 
-`query-result` 会查询指定 Run 并输出 JSON。Run 成功完成后下载视频产物，`completed=true`，`videos` 中只包含 `download_url` 和 `output_path`；Run 失败也视为终态，`completed=true` 且填充 `error_message`；Run 未到终态时 `completed=false`。
+`query-result` 会查询指定 Run 并输出 JSON。Run 成功完成后下载视频和图片产物，`completed=true`，`videos` 和 `images` 中各包含 `download_url` 和 `output_path`；图片扩展名取自产物 `metadata.format`，缺省时兜底 `.png`。Run 失败也视为终态，`completed=true` 且填充 `error_message`；Run 未到终态时 `completed=false`。
 
 ## HTTP 客户端
 

package/checksums.txt

@@ -1,6 +1,6 @@
-c85941f7ca83a0c948dfe59ee139ab6255eda8f7e10c3dcd4a1e2e244c239229  pippit-tool-cli-1.0.11-darwin-amd64.tar.gz
-ed9a1bde1cf391d5a7347214cf73315ecff11186d8ebf563954faf8b0ebc0c83  pippit-tool-cli-1.0.11-darwin-arm64.tar.gz
-7bd0507fa68ac3ca07537f669469b5495485344c6bf305bd5254570516e6e6e9  pippit-tool-cli-1.0.11-linux-amd64.tar.gz
-eac223202657b5e086ef7f79283d2724d9bc539646e5bdd0f37e0ee9c1daeb14  pippit-tool-cli-1.0.11-linux-arm64.tar.gz
-809e06799e7e712af87d45f825ca3e1d84fe9ba6d8885b56727e84f9ee76749d  pippit-tool-cli-1.0.11-windows-amd64.zip
-09a2703e7de552b5d2a319ac99c144eca690aa43bfb1368c458d23db56440574  pippit-tool-cli-1.0.11-windows-arm64.zip
+10344df2fea39ac74dc362fce1dbf60e0dd8a73afa45402bdc3f3f3fee2aab03  pippit-tool-cli-1.0.13-darwin-amd64.tar.gz
+8bf05a6e9acea5eb4057102eda3c58d0ec17843bd800a8b0aa820688477f903b  pippit-tool-cli-1.0.13-darwin-arm64.tar.gz
+7f444b3b6089d9c1d6006c1888dad75717f259a3af3b511b2fc26aaff21f1ff4  pippit-tool-cli-1.0.13-linux-amd64.tar.gz
+f25ade56bd1b3b99b9fe4858fe1fc766878a79ef650961e7042f5de0d2bdda98  pippit-tool-cli-1.0.13-linux-arm64.tar.gz
+665bfaad8505fea2669dc8cbd8a4577f0179f8fe6c8a20c84b3882343b336d2d  pippit-tool-cli-1.0.13-windows-amd64.zip
+b4833e6dce0f7bc2981648bfe7fa029438f6ab7e58636c50134b2100302379cd  pippit-tool-cli-1.0.13-windows-arm64.zip

package/cmd/generate_image/generate_image.go

@@ -0,0 +1,59 @@
+package generate_image
+
+import (
+	"io"
+	"strconv"
+	"strings"
+
+	"github.com/Pippit-dev/pippit-cli/internal/common"
+	internalgen "github.com/Pippit-dev/pippit-cli/internal/generate_image"
+	"github.com/spf13/cobra"
+)
+
+// NewCommand builds the generate-image command.
+func NewCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
+	opts := &internalgen.Options{}
+	var generateImageCount int
+
+	cmd := &cobra.Command{
+		Use:   "generate-image",
+		Short: "Generate an image with the nest agent",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if cmd.Flags().Changed("generate-image-count") {
+				opts.GenerateImageCount = &generateImageCount
+			} else {
+				opts.GenerateImageCount = nil
+			}
+
+			result, err := internalgen.Run(cmd.Context(), opts, runner)
+			if err != nil {
+				_ = common.AppendDailyErrorLog("generate-image", err, map[string]string{
+					"prompt":               strings.TrimSpace(opts.Prompt),
+					"image":                strings.Join(opts.ImagePaths, ","),
+					"model":                strings.TrimSpace(opts.Model),
+					"ratio":                strings.TrimSpace(opts.Ratio),
+					"generate_image_count": optionalIntString(opts.GenerateImageCount),
+				})
+				return err
+			}
+			return common.WriteJSON(stdout, result)
+		},
+	}
+	cmd.SetOut(stdout)
+	cmd.SetErr(stderr)
+	flags := cmd.Flags()
+	flags.StringVar(&opts.Prompt, "prompt", "", "image generation prompt")
+	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.IntVar(&generateImageCount, "generate-image-count", 0, "generated image count")
+	return cmd
+}
+
+func optionalIntString(value *int) string {
+	if value == nil {
+		return ""
+	}
+	return strconv.Itoa(*value)
+}

package/cmd/generate_image_test.go

@@ -0,0 +1,135 @@
+package cmd
+
+import (
+	"bytes"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/bytedance/sonic"
+)
+
+func TestGenerateImage(t *testing.T) {
+	var uploaded 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/upload_file":
+			if r.Method != http.MethodPost {
+				t.Fatalf("upload method = %s, want POST", r.Method)
+			}
+			if err := r.ParseMultipartForm(1 << 20); err != nil {
+				t.Fatalf("ParseMultipartForm(): %v", err)
+			}
+			files := r.MultipartForm.File["file"]
+			if len(files) != 1 {
+				t.Fatalf("file parts = %d, want 1", len(files))
+			}
+			if files[0].Filename != "cat.png" {
+				t.Fatalf("filename = %q, want cat.png", files[0].Filename)
+			}
+			uploaded = true
+			_, _ = w.Write([]byte(`{"ret":"0","errmsg":"","data":{"pippit_asset_id":"image_asset_1"}}`))
+		case "/api/biz/v1/skill/submit_run":
+			if !uploaded {
+				t.Fatal("submit called before upload")
+			}
+			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["agent_name"] != "pippit_nest_agent" {
+				t.Fatalf("agent_name = %v, want nest agent", body["agent_name"])
+			}
+			if body["message"] != "生成小猫海报" {
+				t.Fatalf("message = %v, want prompt", body["message"])
+			}
+			if _, ok := body["video_part_tool_param"]; ok {
+				t.Fatalf("video_part_tool_param should be omitted: %#v", body)
+			}
+			assetIDs, ok := body["asset_ids"].([]any)
+			if !ok || len(assetIDs) != 1 || assetIDs[0] != "image_asset_1" {
+				t.Fatalf("asset_ids = %#v, want uploaded asset", body["asset_ids"])
+			}
+			settings, ok := body["general_agent_settings"].(map[string]any)
+			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["ratio"] != float64(6) {
+				t.Fatalf("ratio = %v, want 6", settings["ratio"])
+			}
+			if settings["generate_image_count"] != float64(2) {
+				t.Fatalf("generate_image_count = %v, want 2", settings["generate_image_count"])
+			}
+			if _, ok := settings["video_model"]; ok {
+				t.Fatalf("video_model should be omitted: %#v", settings)
+			}
+			_, _ = w.Write([]byte(`{"ret":"0","errmsg":"","data":{"run":{"thread_id":"thread_123","run_id":"run_456"},"web_thread_link":"https://xyq.example/thread_123"}}`))
+		default:
+			t.Fatalf("unexpected path %s", r.URL.Path)
+		}
+	}))
+	defer server.Close()
+
+	cwd := chdirTemp(t)
+	image := filepath.Join(cwd, "cat.png")
+	if err := os.WriteFile(image, []byte("image-data"), 0o644); err != nil {
+		t.Fatalf("WriteFile(%s): %v", image, err)
+	}
+
+	var stdout, stderr bytes.Buffer
+	root := newTestRootCommand(t, &stdout, &stderr, server.URL)
+	root.SetArgs([]string{
+		"generate-image",
+		"--prompt", "生成小猫海报",
+		"--image", image,
+		"--model", "seedream_4.5",
+		"--ratio", "6",
+		"--generate-image-count", "2",
+	})
+
+	if err := root.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v, stderr = %s", err, stderr.String())
+	}
+
+	got := decodeJSON(t, stdout.Bytes())
+	if got["thread_id"] != "thread_123" || got["run_id"] != "run_456" {
+		t.Fatalf("output = %#v, want thread and run IDs", got)
+	}
+}
+
+func TestGenerateImageRequiresModel(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatal("server should not receive request without model")
+	}))
+	defer server.Close()
+
+	var stdout, stderr bytes.Buffer
+	root := newTestRootCommand(t, &stdout, &stderr, server.URL)
+	root.SetArgs([]string{
+		"generate-image",
+		"--prompt", "x",
+	})
+
+	err := root.Execute()
+	if err == nil {
+		t.Fatal("Execute() error = nil, want model validation")
+	}
+	if !strings.Contains(err.Error(), "缺少必填参数 --model") {
+		t.Fatalf("error = %q, want model validation", err)
+	}
+}

package/cmd/generate_video/query_result.go

@@ -16,7 +16,7 @@ func NewQueryResultCommand(stdout, stderr io.Writer, runner *common.Runner) *cob
 
 	cmd := &cobra.Command{
 		Use:   "query-result",
-		Short: "Query a generate-video run result and download completed videos",
+		Short: "Query a run result and download completed videos or images",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			result, err := internalgen.QueryResult(cmd.Context(), opts, runner)
@@ -37,7 +37,7 @@ func NewQueryResultCommand(stdout, stderr io.Writer, runner *common.Runner) *cob
 	cmd.SetErr(stderr)
 	cmd.Flags().StringVar(&opts.ThreadID, "thread-id", "", "thread_id from generate-video output")
 	cmd.Flags().StringVar(&opts.RunID, "run-id", "", "run_id from generate-video output")
-	cmd.Flags().StringVar(&opts.DownloadDir, "download-dir", "", "directory to download completed videos into")
+	cmd.Flags().StringVar(&opts.DownloadDir, "download-dir", "", "directory to download completed videos or images into")
 	return cmd
 }
 
@@ -45,6 +45,7 @@ func queryResultFromError(err error, opts *internalgen.QueryResultOptions) *inte
 	result := &internalgen.QueryResultResult{
 		ErrorMessage: err.Error(),
 		Videos:       []internalgen.QueryResultVideo{},
+		Images:       []internalgen.QueryResultImage{},
 	}
 	if opts != nil {
 		result.ThreadID = strings.TrimSpace(opts.ThreadID)

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/cmd/root.go

@@ -7,6 +7,7 @@ import (
 	"strings"
 
 	// authcmd "github.com/Pippit-dev/pippit-cli/cmd/auth"
+	"github.com/Pippit-dev/pippit-cli/cmd/generate_image"
 	"github.com/Pippit-dev/pippit-cli/cmd/generate_video"
 	"github.com/Pippit-dev/pippit-cli/cmd/short_drama"
 	updatecmd "github.com/Pippit-dev/pippit-cli/cmd/update"
@@ -32,7 +33,7 @@ func newRootCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Comm
 	root := &cobra.Command{
 		Use:           "pippit-tool-cli",
 		Short:         "Pippit CLI",
-		Long:          "Pippit CLI generates videos, submits short-drama workflows, downloads generated assets, and updates the installed CLI package.",
+		Long:          "Pippit CLI generates videos and images, submits short-drama workflows, downloads generated assets, and updates the installed CLI package.",
 		Version:       version.Current(),
 		SilenceUsage:  true,
 		SilenceErrors: true,
@@ -45,6 +46,7 @@ func newRootCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Comm
 	root.AddCommand(newDownloadResultCommand(stdout, stderr, runner))
 	root.AddCommand(newGetThreadCommand(stdout, stderr, runner))
 	root.AddCommand(newListThreadFileCommand(stdout, stderr, runner))
+	root.AddCommand(generate_image.NewCommand(stdout, stderr, runner))
 	root.AddCommand(generate_video.NewCommand(stdout, stderr, runner))
 	root.AddCommand(generate_video.NewQueryResultCommand(stdout, stderr, runner))
 	root.AddCommand(short_drama.NewCommand(stdout, stderr, runner))

package/internal/common/path.go

@@ -0,0 +1,24 @@
+package common
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// ExpandPath expands a leading "~" to the current user's home directory.
+func ExpandPath(path string) (string, error) {
+	path = strings.TrimSpace(path)
+	if path == "~" {
+		return os.UserHomeDir()
+	}
+	if strings.HasPrefix(path, "~/") || strings.HasPrefix(path, `~\`) {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return "", fmt.Errorf("解析用户主目录失败: %w", err)
+		}
+		return filepath.Join(home, path[2:]), nil
+	}
+	return path, nil
+}

package/internal/common/set.go

@@ -0,0 +1,10 @@
+package common
+
+// StringSet builds a membership set from a string list.
+func StringSet(list []string) map[string]struct{} {
+	set := make(map[string]struct{}, len(list))
+	for _, value := range list {
+		set[value] = struct{}{}
+	}
+	return set
+}

package/internal/generate_image/generate_image.go

@@ -0,0 +1,164 @@
+package generate_image
+
+import (
+	"context"
+	"fmt"
+	"path/filepath"
+	"strconv"
+	"strings"
+
+	"github.com/Pippit-dev/pippit-cli/internal/common"
+)
+
+const (
+	agentNameNest = "pippit_nest_agent"
+)
+
+var (
+	allowedImageExtensionList = []string{".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp", ".svg"}
+	allowedImageExtensions    = common.StringSet(allowedImageExtensionList)
+)
+
+const ratioUsage = "enum values: 0=原始比例/自动, 2=16:9(横屏), 13=21:9(电影), 3=9:16(竖屏), 4=4:3, 5=3:4, 6=1:1"
+
+// Options is the stable command-facing request shape for generate-image.
+type Options struct {
+	Prompt             string
+	ImagePaths         []string
+	Model              string
+	Ratio              string
+	GenerateImageCount *int
+}
+
+type generalAgentSettings struct {
+	ImageModel         string `json:"image_model"`
+	Ratio              *int   `json:"ratio,omitempty"`
+	GenerateImageCount *int   `json:"generate_image_count,omitempty"`
+}
+
+// Result is the JSON envelope printed by `pippit-tool-cli generate-image`.
+type Result struct {
+	ThreadID      string `json:"thread_id"`
+	RunID         string `json:"run_id"`
+	WebThreadLink string `json:"web_thread_link"`
+}
+
+func Run(ctx context.Context, opts *Options, runner *common.Runner) (*Result, error) {
+	if runner == nil || runner.Client == nil {
+		return nil, fmt.Errorf("generate-image 运行器客户端缺失")
+	}
+	if err := ValidateOptions(opts); err != nil {
+		return nil, err
+	}
+
+	imageAssetIDs, err := uploadImageList(ctx, opts.ImagePaths, runner)
+	if err != nil {
+		return nil, fmt.Errorf("上传图片失败: %w", err)
+	}
+
+	body := buildSubmitRunBody(opts, imageAssetIDs)
+
+	var resp common.SubmitRunResponse
+	if err := runner.Client.SendRequest(ctx, common.SubmitRunPath(runner), body, &resp); err != nil {
+		return nil, fmt.Errorf("提交 generate-image 请求失败: %w", err)
+	}
+	if resp.Ret != "0" {
+		if resp.Errmsg == "" {
+			resp.Errmsg = "未知错误"
+		}
+		return nil, common.NewLogIDError(fmt.Sprintf("generate-image 请求返回失败: ret=%s errmsg=%s", resp.Ret, resp.Errmsg), resp.LogID)
+	}
+	if resp.Data.Run.ThreadID == "" {
+		return nil, fmt.Errorf("generate-image 响应缺少 data.run.thread_id")
+	}
+	if resp.Data.Run.RunID == "" {
+		return nil, fmt.Errorf("generate-image 响应缺少 data.run.run_id")
+	}
+
+	return &Result{
+		ThreadID:      resp.Data.Run.ThreadID,
+		RunID:         resp.Data.Run.RunID,
+		WebThreadLink: resp.Data.WebThreadLink,
+	}, nil
+}
+
+func ValidateOptions(opts *Options) error {
+	if opts == nil {
+		return fmt.Errorf("缺少必填参数 --prompt")
+	}
+	if strings.TrimSpace(opts.Prompt) == "" {
+		return fmt.Errorf("缺少必填参数 --prompt")
+	}
+	if strings.TrimSpace(opts.Model) == "" {
+		return fmt.Errorf("缺少必填参数 --model")
+	}
+	if _, err := parseRatio(opts.Ratio); err != nil {
+		return err
+	}
+	if opts.GenerateImageCount != nil && *opts.GenerateImageCount < 0 {
+		return fmt.Errorf("--generate-image-count 不能为负数")
+	}
+	if err := validateImageExtensions(opts.ImagePaths); err != nil {
+		return err
+	}
+	return nil
+}
+
+func validateImageExtensions(paths []string) error {
+	for _, path := range paths {
+		ext := strings.ToLower(filepath.Ext(strings.TrimSpace(path)))
+		if _, ok := allowedImageExtensions[ext]; !ok {
+			return fmt.Errorf("不支持的图片文件后缀 %q，文件：%q；支持的后缀：%s", ext, path, strings.Join(allowedImageExtensionList, ", "))
+		}
+	}
+	return nil
+}
+
+func SupportedRatioUsage() string {
+	return ratioUsage
+}
+
+func uploadImageList(ctx context.Context, paths []string, runner *common.Runner) ([]string, error) {
+	assetIDs := make([]string, 0, len(paths))
+	for _, path := range paths {
+		expanded, err := common.ExpandPath(path)
+		if err != nil {
+			return nil, err
+		}
+		result, err := common.UploadFile(ctx, common.UploadFileOptions{Path: expanded}, runner)
+		if err != nil {
+			return nil, err
+		}
+		assetIDs = append(assetIDs, result.AssetID)
+	}
+	return assetIDs, nil
+}
+
+func buildSubmitRunBody(opts *Options, imageAssetIDs []string) map[string]any {
+	ratio, _ := parseRatio(opts.Ratio)
+	body := map[string]any{
+		"agent_name": agentNameNest,
+		"message":    strings.TrimSpace(opts.Prompt),
+		"general_agent_settings": generalAgentSettings{
+			ImageModel:         strings.TrimSpace(opts.Model),
+			Ratio:              ratio,
+			GenerateImageCount: opts.GenerateImageCount,
+		},
+	}
+	if len(imageAssetIDs) > 0 {
+		body["asset_ids"] = imageAssetIDs
+	}
+	return body
+}
+
+func parseRatio(raw string) (*int, error) {
+	ratio := strings.TrimSpace(raw)
+	if ratio == "" {
+		return nil, nil
+	}
+	value, err := strconv.Atoi(ratio)
+	if err != nil {
+		return nil, fmt.Errorf("ratio %q 必须是整数枚举值；可参考：%s", ratio, ratioUsage)
+	}
+	return &value, nil
+}

package/internal/generate_image/generate_image_test.go

@@ -0,0 +1,148 @@
+package generate_image
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestValidateOptionsRequiresModel(t *testing.T) {
+	opts := &Options{
+		Prompt: "x",
+	}
+
+	err := ValidateOptions(opts)
+	if err == nil {
+		t.Fatal("ValidateOptions() error = nil, want model validation")
+	}
+	if !strings.Contains(err.Error(), "缺少必填参数 --model") {
+		t.Fatalf("error = %q, want model validation", err)
+	}
+}
+
+func TestValidateOptionsAllowsServerDecidedModel(t *testing.T) {
+	opts := &Options{
+		Prompt: "x",
+		Model:  "seedream_3.0",
+	}
+
+	if err := ValidateOptions(opts); err != nil {
+		t.Fatalf("ValidateOptions() error = %v, want nil", err)
+	}
+}
+
+func TestValidateOptionsAllowsServerDecidedRatio(t *testing.T) {
+	opts := &Options{
+		Prompt: "x",
+		Model:  "seedream_4.5",
+		Ratio:  "99",
+	}
+
+	if err := ValidateOptions(opts); err != nil {
+		t.Fatalf("ValidateOptions() error = %v, want nil", err)
+	}
+}
+
+func TestValidateOptionsRejectsNegativeGenerateImageCount(t *testing.T) {
+	count := -1
+	opts := &Options{
+		Prompt:             "x",
+		Model:              "seedream_4.5",
+		GenerateImageCount: &count,
+	}
+
+	err := ValidateOptions(opts)
+	if err == nil {
+		t.Fatal("ValidateOptions() error = nil, want generate-image-count validation")
+	}
+	if !strings.Contains(err.Error(), "--generate-image-count 不能为负数") {
+		t.Fatalf("error = %q, want generate-image-count validation", err)
+	}
+}
+
+func TestParseRatioSupportsVisibleEnumValues(t *testing.T) {
+	cases := []struct {
+		ratio string
+		want  int
+	}{
+		{ratio: "0", want: 0},
+		{ratio: "2", want: 2},
+		{ratio: "13", want: 13},
+		{ratio: "3", want: 3},
+		{ratio: "4", want: 4},
+		{ratio: "5", want: 5},
+		{ratio: "6", want: 6},
+	}
+
+	for _, tt := range cases {
+		t.Run(tt.ratio, func(t *testing.T) {
+			got, err := parseRatio(tt.ratio)
+			if err != nil {
+				t.Fatalf("parseRatio(%q) error = %v", tt.ratio, err)
+			}
+			if got == nil || *got != tt.want {
+				t.Fatalf("parseRatio(%q) = %#v, want %d", tt.ratio, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestParseRatioRejectsNonInteger(t *testing.T) {
+	_, err := parseRatio("1:1")
+	if err == nil {
+		t.Fatal("parseRatio() error = nil, want integer validation")
+	}
+	if !strings.Contains(err.Error(), `ratio "1:1" 必须是整数枚举值`) {
+		t.Fatalf("error = %q, want integer validation", err)
+	}
+}
+
+func TestValidateOptionsRejectsUnsupportedImageExtension(t *testing.T) {
+	opts := &Options{
+		Prompt:     "x",
+		Model:      "seedream_4.5",
+		ImagePaths: []string{"ref.tiff"},
+	}
+
+	err := ValidateOptions(opts)
+	if err == nil {
+		t.Fatal("ValidateOptions() error = nil, want image extension validation")
+	}
+	if !strings.Contains(err.Error(), `不支持的图片文件后缀 ".tiff"`) {
+		t.Fatalf("error = %q, want image extension validation", err)
+	}
+}
+
+func TestBuildSubmitRunBodyWithGeneralAgentSettings(t *testing.T) {
+	count := 2
+	opts := &Options{
+		Prompt:             "  生成小猫海报  ",
+		Model:              " seedream_4.5 ",
+		Ratio:              "6",
+		GenerateImageCount: &count,
+	}
+
+	body := buildSubmitRunBody(opts, []string{"asset_1"})
+	if body["agent_name"] != agentNameNest {
+		t.Fatalf("agent_name = %v, want nest agent", body["agent_name"])
+	}
+	if body["message"] != "生成小猫海报" {
+		t.Fatalf("message = %v, want trimmed prompt", body["message"])
+	}
+	settings, ok := body["general_agent_settings"].(generalAgentSettings)
+	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.Ratio == nil || *settings.Ratio != 6 {
+		t.Fatalf("ratio = %#v, want 6", settings.Ratio)
+	}
+	if settings.GenerateImageCount == nil || *settings.GenerateImageCount != 2 {
+		t.Fatalf("generate_image_count = %#v, want 2", settings.GenerateImageCount)
+	}
+	assetIDs, ok := body["asset_ids"].([]string)
+	if !ok || len(assetIDs) != 1 || assetIDs[0] != "asset_1" {
+		t.Fatalf("asset_ids = %#v, want asset_1", body["asset_ids"])
+	}
+}

package/internal/generate_video/query_result.go

@@ -32,6 +32,7 @@ type QueryResultResult struct {
 	RunID        string             `json:"run_id"`
 	ErrorMessage string             `json:"error_message"`
 	Videos       []QueryResultVideo `json:"videos"`
+	Images       []QueryResultImage `json:"images"`
 }
 
 // QueryResultVideo describes a downloaded video from query-result.
@@ -40,6 +41,12 @@ type QueryResultVideo struct {
 	OutputPath  string `json:"output_path"`
 }
 
+// QueryResultImage describes a downloaded image from query-result.
+type QueryResultImage struct {
+	DownloadURL string `json:"download_url"`
+	OutputPath  string `json:"output_path"`
+}
+
 type queryThread struct {
 	ThreadID string     `json:"thread_id"`
 	RunList  []queryRun `json:"run_list"`
@@ -69,6 +76,7 @@ type queryContent struct {
 
 type queryContentData struct {
 	Video        *queryVideo     `json:"video"`
+	Image        *queryImage     `json:"image"`
 	ErrorMessage string          `json:"error_message"`
 	ErrorCode    json.RawMessage `json:"error_code"`
 }
@@ -80,6 +88,16 @@ type queryVideo struct {
 	AssetID     string `json:"asset_id"`
 }
 
+type queryImage struct {
+	DownloadURL string         `json:"url"`
+	AssetID     string         `json:"asset_id"`
+	Metadata    queryImageMeta `json:"metadata"`
+}
+
+type queryImageMeta struct {
+	Format string `json:"format"`
+}
+
 func QueryResult(ctx context.Context, opts *QueryResultOptions, runner *common.Runner) (*QueryResultResult, error) {
 	if err := validateQueryResultOptions(opts); err != nil {
 		return nil, err
@@ -111,6 +129,7 @@ func QueryResult(ctx context.Context, opts *QueryResultOptions, runner *common.R
 			ThreadID:  firstNonEmpty(thread.ThreadID, opts.ThreadID),
 			RunID:     opts.RunID,
 			Videos:    []QueryResultVideo{},
+			Images:    []QueryResultImage{},
 		}
 		if run.State == failedRunState {
 			result.ErrorMessage = firstNonEmpty(extractQueryErrorMessage(run), "Run 失败")
@@ -119,17 +138,19 @@ func QueryResult(ctx context.Context, opts *QueryResultOptions, runner *common.R
 	}
 
 	videos := extractQueryVideos(run)
-	if len(videos) == 0 {
-		return nil, fmt.Errorf("下载失败：未找到可下载的视频产物")
+	images := extractQueryImages(run)
+	if len(videos) == 0 && len(images) == 0 {
+		return nil, fmt.Errorf("下载失败：未找到可下载的产物")
 	}
 
-	downloadDir, err := expandPath(opts.DownloadDir)
+	downloadDir, err := common.ExpandPath(opts.DownloadDir)
 	if err != nil {
 		return nil, fmt.Errorf("下载失败：解析下载目录失败：%w", err)
 	}
 
+	usedNames := make(map[string]int, len(videos)+len(images))
+
 	resultVideos := make([]QueryResultVideo, 0, len(videos))
-	usedNames := make(map[string]int, len(videos))
 	for i, video := range videos {
 		if strings.TrimSpace(video.DownloadURL) == "" {
 			return nil, fmt.Errorf("下载失败：第 %d 个视频产物 download_url 为空", i+1)
@@ -155,11 +176,38 @@ 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)
+		}
+		outputPath := filepath.Join(downloadDir, uniqueQueryResultFileName(imageFileName(image, i+1), usedNames))
+		download, err := common.DownloadResult(ctx, common.DownloadResultOptions{
+			URL:        image.DownloadURL,
+			OutputPath: outputPath,
+			Workers:    5,
+		}, runner)
+		if err != nil {
+			return nil, fmt.Errorf("下载失败：%w", err)
+		}
+		actualOutputPath := outputPath
+		if len(download.Downloaded) > 0 {
+			actualOutputPath = download.Downloaded[0]
+		} else if len(download.AlreadyExist) > 0 {
+			actualOutputPath = download.AlreadyExist[0]
+		}
+		resultImages = append(resultImages, QueryResultImage{
+			DownloadURL: image.DownloadURL,
+			OutputPath:  actualOutputPath,
+		})
+	}
+
 	return &QueryResultResult{
 		Completed: true,
 		ThreadID:  firstNonEmpty(thread.ThreadID, opts.ThreadID),
 		RunID:     opts.RunID,
 		Videos:    resultVideos,
+		Images:    resultImages,
 	}, nil
 }
 
@@ -181,6 +229,7 @@ func queryResultFromGetThreadBusinessError(err error, opts *QueryResultOptions)
 		RunID:        opts.RunID,
 		ErrorMessage: message,
 		Videos:       []QueryResultVideo{},
+		Images:       []QueryResultImage{},
 	}, true
 }
 
@@ -288,6 +337,23 @@ func extractQueryVideos(run queryRun) []queryVideo {
 	return videos
 }
 
+func extractQueryImages(run queryRun) []queryImage {
+	images := make([]queryImage, 0)
+	for _, entry := range run.EntryList {
+		artifact := entry.Artifact
+		for _, content := range artifact.Content {
+			if content.SubType != "biz/x_data_image" {
+				continue
+			}
+			data := content.Data
+			if data.Image != nil {
+				images = append(images, *data.Image)
+			}
+		}
+	}
+	return images
+}
+
 func extractQueryErrorMessage(run queryRun) string {
 	if message := firstNonEmpty(run.ErrorMessage, run.ErrorMsg, run.Errmsg); message != "" {
 		return message
@@ -342,6 +408,42 @@ func hasVideoExtension(name string) bool {
 	}
 }
 
+func imageFileName(image queryImage, index int) string {
+	name := image.AssetID
+	if name == "" {
+		name = "result_" + strconv.Itoa(index)
+	}
+	name = sanitizeFileName(name)
+	if !hasImageExtension(name) {
+		name += "." + normalizeImageFormatExt(image.Metadata.Format)
+	}
+	return name
+}
+
+// normalizeImageFormatExt maps the server-provided metadata.format to a safe
+// file extension. Only a known allowlist is accepted; anything else (including
+// "image/jpeg", ".jpeg", or empty values) falls back to "png".
+func normalizeImageFormatExt(format string) string {
+	format = strings.ToLower(strings.TrimSpace(format))
+	format = strings.TrimPrefix(format, "image/")
+	format = strings.TrimPrefix(format, ".")
+	switch format {
+	case "jpg", "jpeg", "png", "gif", "bmp", "webp", "svg":
+		return format
+	default:
+		return "png"
+	}
+}
+
+func hasImageExtension(name string) bool {
+	switch strings.ToLower(strings.TrimSpace(filepath.Ext(name))) {
+	case ".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp", ".svg":
+		return true
+	default:
+		return false
+	}
+}
+
 func firstNonEmpty(values ...string) string {
 	for _, value := range values {
 		value = strings.TrimSpace(value)
@@ -355,7 +457,7 @@ func firstNonEmpty(values ...string) string {
 func sanitizeFileName(name string) string {
 	name = strings.TrimSpace(name)
 	if name == "" {
-		return "result.mp4"
+		return "result"
 	}
 	return strings.Map(func(r rune) rune {
 		if unicode.IsControl(r) || r == '/' || r == '\\' || strings.ContainsRune(`<>:"|?*`, r) {

package/internal/generate_video/query_result_test.go

@@ -29,3 +29,98 @@ func TestVideoFileNameKeepsVideoExtension(t *testing.T) {
 		t.Fatalf("videoFileName() = %q, want cat_video.mp4", got)
 	}
 }
+
+func TestImageFileNameUsesAssetID(t *testing.T) {
+	got := imageFileName(queryImage{
+		AssetID:  "7659311708893512254",
+		Metadata: queryImageMeta{Format: "jpeg"},
+	}, 1)
+	want := "7659311708893512254.jpeg"
+	if got != want {
+		t.Fatalf("imageFileName() = %q, want %q", got, want)
+	}
+}
+
+func TestImageFileNameAddsExtensionFromFormat(t *testing.T) {
+	got := imageFileName(queryImage{
+		AssetID:  "pic1",
+		Metadata: queryImageMeta{Format: "png"},
+	}, 1)
+	if got != "pic1.png" {
+		t.Fatalf("imageFileName() = %q, want pic1.png", got)
+	}
+}
+
+func TestImageFileNameFallsBackToPngWhenFormatEmpty(t *testing.T) {
+	got := imageFileName(queryImage{
+		AssetID:  "pic1",
+		Metadata: queryImageMeta{Format: ""},
+	}, 1)
+	if got != "pic1.png" {
+		t.Fatalf("imageFileName() = %q, want pic1.png", got)
+	}
+}
+
+func TestImageFileNameNormalizesMimeTypeFormat(t *testing.T) {
+	cases := []struct {
+		format string
+		want   string
+	}{
+		{format: "image/jpeg", want: "pic1.jpeg"},
+		{format: ".jpeg", want: "pic1.jpeg"},
+		{format: "JPEG", want: "pic1.jpeg"},
+		{format: "image/png", want: "pic1.png"},
+		{format: "image/webp", want: "pic1.webp"},
+		{format: "image/svg+xml", want: "pic1.png"}, // unsupported, falls back
+		{format: "application/octet-stream", want: "pic1.png"},
+	}
+	for _, tt := range cases {
+		t.Run(tt.format, func(t *testing.T) {
+			got := imageFileName(queryImage{AssetID: "pic1", Metadata: queryImageMeta{Format: tt.format}}, 1)
+			if got != tt.want {
+				t.Fatalf("imageFileName(format=%q) = %q, want %q", tt.format, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestImageFileNameUsesResultIndexWhenNoID(t *testing.T) {
+	got := imageFileName(queryImage{
+		Metadata: queryImageMeta{Format: "jpeg"},
+	}, 2)
+	if got != "result_2.jpeg" {
+		t.Fatalf("imageFileName() = %q, want result_2.jpeg", got)
+	}
+}
+
+func TestImageFileNameKeepsExistingImageExtension(t *testing.T) {
+	got := imageFileName(queryImage{
+		AssetID:  "cat_poster.png",
+		Metadata: queryImageMeta{Format: "jpeg"},
+	}, 1)
+	if got != "cat_poster.png" {
+		t.Fatalf("imageFileName() = %q, want cat_poster.png", got)
+	}
+}
+
+func TestExtractQueryImagesFiltersBySubType(t *testing.T) {
+	run := queryRun{
+		EntryList: []queryEntry{
+			{Artifact: queryArtifact{Content: []queryContent{
+				{SubType: "biz/x_data_image", Data: queryContentData{Image: &queryImage{DownloadURL: "https://x/a.jpeg", AssetID: "p1"}}},
+				{SubType: "biz/x_data_video", Data: queryContentData{Video: &queryVideo{DownloadURL: "https://x/v.mp4", VID: "v1"}}},
+			}}},
+			{Artifact: queryArtifact{Content: []queryContent{
+				{SubType: "biz/x_data_image", Data: queryContentData{Image: &queryImage{DownloadURL: "https://x/b.png", AssetID: "p2"}}},
+				{SubType: "text/plain", Data: queryContentData{}},
+			}}},
+		},
+	}
+	got := extractQueryImages(run)
+	if len(got) != 2 {
+		t.Fatalf("extractQueryImages() = %d images, want 2", len(got))
+	}
+	if got[0].AssetID != "p1" || got[1].AssetID != "p2" {
+		t.Fatalf("extractQueryImages() = %q,%q, want p1,p2", got[0].AssetID, got[1].AssetID)
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pippit-dev/cli",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "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-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,60 @@ metadata:
 **平台核心能力：**
 - **生成**：文生图、文生视频、图生视频、视频续写
 - **编辑**：局部修改、元素替换、镜头调整、风格迁移
-- **复杂创作**：一句话生成完整短剧（剧本→分镜→成片）、复刻已有视频风格做 TVC/宣传片、用音乐生成 MV、产品展示片制作
+- **复杂创作**：复刻已有视频风格做 TVC/宣传片、用音乐生成 MV、产品展示片制作
 
-用户的所有创作和编辑需求都通过发送自然语言消息来完成，Agent 会自主编排工作流。复杂任务（短剧、MV）耗时较长，需耐心轮询。
+除“视频模型直出”外，创作和编辑需求通过发送自然语言消息来完成，后端 Agent 会自主编排工作流。复杂任务耗时较长，需耐心轮询。
+
+## 执行路由（必须先判断）
+
+### 路由 A：视频模型直出
+
+满足任一条件时，必须直接使用 `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 次。
+
+### 路由 B：小云雀后端 Agent 编排
+
+需要意图确认、脚本/分镜拆解、MV、TVC、局部编辑、复杂参考素材编排，或者用户未明确要求模型直出时，继续使用本技能内置的 `submit_run.py` / `get_thread.py` 会话工作流。
+
+### 路由 C：短剧工作流
+
+用户要求短剧生成、续写、改写、剧情扩展、人物设定、分集草稿或短剧会话文件处理时，停止本技能流程并转交 `xyq-short-drama-skill`，不要用 `submit_run.py` 或 `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 +87,7 @@ metadata:
 2. **查询会话进展** - 根据 `thread_id` 、 `run_id`、`after_seq` 增量拉取该会话的消息列表，用于轮询创作过程的消息和最终产物结果
 3. **上传文件** - 支持上传`单张图片`、`单个视频文件`或`单个mp3/wav音频文件`到小云雀资产库，得到文件对应的 `asset_id`（编辑或参考已有图片/视频/音频时需要先上传）
 4. **下载结果** - 将会话中生成的图片/视频批量下载到本地，支持指定输出目录和文件名前缀。
+5. **视频模型直出** - 使用 `pippit-tool-cli generate-video` 直接调用视频模型，使用 `query-result` 查询并下载结果。
 
 
 ## 前置要求
@@ -46,7 +98,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 +150,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 +161,7 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
     - 将过程创作信息展示给用户，继续轮询
   - 当任务完成（run 结束）：
     - 如果涉及意图确认/流程中断（如"请回答以下问题"）：
-      → 向用户展示问题，等待用户回复
+      → 优先调用当前宿主的结构化用户提问工具展示问题，等待用户回复
       → 使用 `thread_id` 重新提交任务（保持同一会话，产生新的 run_id）
       → 回到步骤 2 继续轮询（可能多轮，直到不再意图确认）
     - 如果 content 中包含产物 URL：
@@ -211,16 +263,16 @@ 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`
+2. **提交任务**：先按“执行路由”判断；模型直出调用 `pippit-tool-cli generate-video`，其余任务把用户的原始描述 + asset_id 原封不动发给 `submit_run.py`
 3. **传话**：根据 `get_thread.py` 返回的消息列表，展示过程中的意图询问、创作信息等
 4. **取件**：`get_thread.py` 轮询结果 → 检查结果 → 下载产物 → 结果展示给用户
 
@@ -258,3 +310,4 @@ python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir
 - 查询会话时可用 --after-seq 做增量拉取，便于轮询新消息（含 assistant 回复与生图/生视频结果）
 - 上传文件仅支持图片（image/*）、视频（video/*）和 `.mp3/.wav` 音频文件，其他类型会被拒绝，文件大小须在 200MB 以下
 - 生成过程中将过程中的创作信息展示给用户；任务完成后给出**产物结果（图片/视频）URL链接**和下载的**本地文件列表**。
+- 模型直出任务必须保留 `generate-video` 返回的 `thread_id` / `run_id`，并用 `query-result` 取回最终视频。