@pippit-dev/cli 1.0.10 → 1.0.12

package/README.md

@@ -213,6 +213,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 +264,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 +273,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 @@
-44e0b20d9ce770e4a1bfc8ae474aaec8b6fc7e17beb7e9c00468024caa3888dd  pippit-tool-cli-1.0.10-darwin-amd64.tar.gz
-0d77c0aae453c3a64c61699823b775367816f7300aca04f0d47aec1151038092  pippit-tool-cli-1.0.10-darwin-arm64.tar.gz
-7ee3fd6064406864ce4f3bbb8886421dc1cde462cb678e3faac66d81c6e64cbb  pippit-tool-cli-1.0.10-linux-amd64.tar.gz
-95c1b80c2e743eafce3ab91c94f86df727d236c859d8f9d581eb7a7d5b055125  pippit-tool-cli-1.0.10-linux-arm64.tar.gz
-cd9997499e4a217c456b18b021e0215705bf5fba64325bc3461380fed315cf10  pippit-tool-cli-1.0.10-windows-amd64.zip
-b82a6022de7f4cdd9ffbcc6e00c8390fcf5ae323630c202a72861eee411c1c52  pippit-tool-cli-1.0.10-windows-arm64.zip
+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

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/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.10",
+  "version": "1.0.12",
   "description": "Pippit CLI",
   "bin": {
     "pippit-tool-cli": "scripts/run.js"

package/skills/short-drama/SKILL.md

@@ -59,6 +59,17 @@ metadata:
 - 不替用户决定创意内容，例如风格、剧情方向、角色设定、镜头方案。只能清洗流程选项，不能代替用户选择创作偏好。
 - 如果服务端问题混入跨度过大的多个流程选项，重新组织成当前阶段可回答的问题，并说明已按主流程剔除不合理或跳跃选项。
 
+## 宿主提问工具优先
+
+当后端 Agent 通过 `readable_text` 要求用户补充信息、选择选项、确认流程或确认创意内容时，优先使用当前宿主提供的 ask-question / confirmation / form 类工具向用户提问，而不是只在普通聊天里输出问题。
+
+使用宿主提问工具前，先按“表单与问卷选项处理原则”清洗问题和选项：
+
+- 只把当前阶段合理、必要、可执行的选项放进提问工具。
+- 不把已剔除的跳跃流程、倒退流程或不合理选项放进提问工具。
+- 对普通开放问题，用单个清晰问题询问用户；对明确互斥选项，用宿主支持的选择控件。
+- 如果当前宿主没有暴露可调用的 ask-question / confirmation / form 工具，才退回普通聊天提问，并说明需要用户回复后才能继续。
+
 ## 前置要求
 
 需要已安装 `pippit-tool-cli`：
@@ -75,6 +86,40 @@ Access Key 创建地址：https://xyq.jianying.com/home?tab_name=home
 export XYQ_ACCESS_KEY="<access-key>"
 ```
 
+## 小云雀界面打开契约
+
+`+submit-run` 返回 `web_thread_link` 后，用户侧 Agent 必须优先把小云雀短剧 WebUI 打开给用户，而不是只展示链接。
+
+按当前宿主适配打开方式：
+
+**Codex Desktop**
+
+1. 如果 `browser:control-in-app-browser` skill 可用，先读取并按该 skill 连接 Codex in-app browser。
+2. 使用 in-app browser 打开 `web_thread_link`，并让浏览器可见。
+3. 继续执行 `get-thread`、`list-thread-file` 和 `download-result`；打开 WebUI 不替代 CLI 轮询和产物下载。
+
+**WorkBuddy**
+
+1. 如果当前 WorkBuddy 会话暴露内置浏览器或页面打开能力，使用宿主提供的能力打开 `web_thread_link`。
+2. 不要套用 Codex Desktop 的 `browser:control-in-app-browser`、`node_repl` 或 `agent.browsers.get("iab")` 实现。
+3. 如果 WorkBuddy 当前没有暴露可调用浏览器工具，说明无法自动打开，并把 `web_thread_link` 交给用户在 WorkBuddy 内置浏览器或普通浏览器中打开。
+
+**TRAE Work**
+
+1. 如果当前 TRAE Work 会话暴露内置浏览器或页面打开能力，使用宿主提供的能力打开 `web_thread_link`。
+2. 不要套用 Codex Desktop 的 in-app browser 实现。
+3. 如果 TRAE Work 当前没有暴露可调用浏览器工具，说明无法自动打开，并把 `web_thread_link` 交给用户手动打开。
+
+**其他宿主或未知环境**
+
+如果没有明确的宿主浏览器能力、工具不可用或连接失败：
+
+- 明确说明未能自动打开小云雀界面的具体原因。
+- 仍然把 `web_thread_link` 展示给用户，作为手动打开入口。
+- 不要因此跳过后续进展查询和文件下载。
+
+打开界面的目的只是让用户能进入小云雀编辑/确认界面做视觉 review、流程确认或手动调整；短剧任务提交、状态查询和重要资产落盘仍以 `pippit-tool-cli` 为准。
+
 ## 使用方法
 
 ### 1. 提交短剧任务
@@ -152,7 +197,7 @@ pippit-tool-cli download-result --url DOWNLOAD_URL --output-path FILE_PATH --upd
 ```
 1. pippit-tool-cli short-drama +submit-run --message "用户的原始短剧需求"
    → 拿到 thread_id、run_id 和 web_thread_link
-2. 立即将 web_thread_link 展示给用户
+2. 立即展示 web_thread_link，并按“小云雀界面打开契约”优先用 in-app browser 打开该链接
 3. 并行发起，二者同等重要：
    a. pippit-tool-cli get-thread --thread-id THREAD_ID --run-id RUN_ID
    b. pippit-tool-cli list-thread-file --thread-id THREAD_ID --page-num PAGE_NUM --page-size 200
@@ -183,8 +228,9 @@ pippit-tool-cli download-result --url DOWNLOAD_URL --output-path FILE_PATH --upd
    → 拿到 asset_id
 3. pippit-tool-cli short-drama +submit-run --message "用户的原始短剧需求" --asset-ids asset_id
    → 拿到 thread_id、run_id 和 web_thread_link
-4. 记录该 thread_id 已绑定这个剧本文件；后续同一 thread_id 的续写或修改只传 --thread-id，不再传新的剧本 asset_id
-5. 后续同场景 1 的并行查询、重要资产发现和文件下载流程
+4. 立即展示 web_thread_link，并按“小云雀界面打开契约”优先用 in-app browser 打开该链接
+5. 记录该 thread_id 已绑定这个剧本文件；后续同一 thread_id 的续写或修改只传 --thread-id，不再传新的剧本 asset_id
+6. 后续同场景 1 的并行查询、重要资产发现和文件下载流程
 ```
 
 ### 场景 3：在已有短剧会话中续写或修改
@@ -192,8 +238,9 @@ pippit-tool-cli download-result --url DOWNLOAD_URL --output-path FILE_PATH --upd
 ```
 1. pippit-tool-cli short-drama +submit-run --message "用户的新需求" --thread-id THREAD_ID
    → 拿到新的 run_id 和 web_thread_link
-2. 如果该 THREAD_ID 已经绑定过剧本文件，不要再上传或通过 --asset-ids 追加第二个剧本文件
-3. 继续按场景 1 展示进展、处理用户补充问题、获取新增会话文件列表，并及时下载新增重要资产
+2. 立即展示 web_thread_link，并按“小云雀界面打开契约”优先用 in-app browser 打开该链接
+3. 如果该 THREAD_ID 已经绑定过剧本文件，不要再上传或通过 --asset-ids 追加第二个剧本文件
+4. 继续按场景 1 展示进展、处理用户补充问题、获取新增会话文件列表，并及时下载新增重要资产
 ```
 
 ## 轮询策略
@@ -205,7 +252,7 @@ pippit-tool-cli download-result --url DOWNLOAD_URL --output-path FILE_PATH --upd
 - **重要资产识别**：每轮都检查 `list-thread-file` 返回的文件。剧本设计、场景设计、场景图、人物角色设计、人物图、分集草稿、故事板、最终视频产物都是重要资产。
 - **文件下载**：解析 `list-thread-file` 的结果后，对带 `download_url` 的重要资产立即调用 `download-result` 下载资源；不要在 `list-thread-file` 阶段检查文件是否已存在，存在性检查由下载工具内部处理。
 - **下载完成标准**：不要把文件元信息展示当成下载完成；必须拿到本地 `file_path`，或明确记录该文件在重试后仍下载失败。
-- **用户确认**：如果消息中出现需要用户确认、补充设定或回答问题的内容，先判断是否包含表单、问卷、选项或按钮；包含时按“短剧主流程顺序”和“表单与问卷选项处理原则”清洗选项，再展示给用户并等待回复。
+- **用户确认**：如果消息中出现需要用户确认、补充设定或回答问题的内容，先判断是否包含表单、问卷、选项或按钮；包含时按“短剧主流程顺序”和“表单与问卷选项处理原则”清洗选项，再按“宿主提问工具优先”向用户提问并等待回复。
 - **超时**：如果长时间无结果，告知用户任务仍在生成中，可稍后通过 `web_thread_link` 查看。
 - **错误处理**：`get-thread`、`list-thread-file` 或 `download-result` 任一调用失败时，记录失败原因和参数，在后续轮询中主动重试；重试期间继续处理其他成功返回的消息和文件。连续多轮失败后再向用户说明仍未完成的查询或下载项。
 
@@ -214,10 +261,11 @@ pippit-tool-cli download-result --url DOWNLOAD_URL --output-path FILE_PATH --upd
 一次短剧任务不能只以 `get-thread` 返回的 `readable_text` 作为结束条件。完成前必须同时检查：
 
 1. 已处理 `get-thread` 返回的最新 `readable_text`、用户确认问题和最终消息。
-2. 已用 `--page-size 200` 调用 `list-thread-file` 获取会话文件列表；如果本轮 `total` 达到 200，已在后续轮询中递增 `page-num` 查询新一页。
-3. 对所有带 `download_url` 的重要资产，已调用 `download-result` 下载到本地 `file_path`。
-4. 已按短剧主流程顺序检查服务端表单、问卷和选项，没有把跳过必要阶段的选项直接呈现给用户；如果跳过 `剧本标准化`，已明确这是可选阶段。
-5. 对查询失败或下载失败的资产，已在后续轮询中主动重试，并在最终回复中列出仍失败的文件或命令。
+2. 已展示 `web_thread_link`，并按当前宿主尝试打开小云雀 WebUI：Codex Desktop 用 in-app browser；WorkBuddy / TRAE Work 用各自宿主提供的内置浏览器或页面打开能力；如果不能自动打开，已说明原因并提供手动链接。
+3. 已用 `--page-size 200` 调用 `list-thread-file` 获取会话文件列表；如果本轮 `total` 达到 200，已在后续轮询中递增 `page-num` 查询新一页。
+4. 对所有带 `download_url` 的重要资产，已调用 `download-result` 下载到本地 `file_path`。
+5. 已按短剧主流程顺序检查服务端表单、问卷和选项，没有把跳过必要阶段的选项直接呈现给用户；如果跳过 `剧本标准化`，已明确这是可选阶段。
+6. 对查询失败或下载失败的资产，已在后续轮询中主动重试，并在最终回复中列出仍失败的文件或命令。
 
 ## 输出格式
 
@@ -310,8 +358,9 @@ Thread: thread_...
 ## 向用户展示内容
 
 - 任务提交后：立即展示 `web_thread_link`。
+- 在支持内置浏览器或页面打开能力的宿主中：任务提交后按“小云雀界面打开契约”优先打开 `web_thread_link`，让用户能进入小云雀 WebUI 查看和调整；不同宿主只使用各自提供的浏览器能力，不复用 Codex Desktop 的实现细节。
 - 任务进行中：展示后端 Agent 返回的过程消息。
-- 需要用户补充信息时：如果是普通问题，展示后端 Agent 的问题并等待用户回复；如果包含表单、问卷、选项或按钮，先按短剧主流程清洗不合理或跳跃的流程选项，再展示给用户。
+- 需要用户补充信息时：如果是普通问题，按“宿主提问工具优先”提问并等待用户回复；如果包含表单、问卷、选项或按钮，先按短剧主流程清洗不合理或跳跃的流程选项，再用宿主提问工具呈现；没有可用提问工具时才退回普通聊天。
 - 任务完成后：展示短剧内容、分集草稿、设定说明或其他结果信息，同时检查是否有未下载的重要资产。
 - 获取会话文件后：展示或记录文件元信息，不把它当成已下载结果。
 - 文件资源下载后：展示已落盘的本地文件路径；已存在而跳过下载的文件也要标明。