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