@pippit-dev/cli 1.0.32 → 1.0.33

package/internal/models/models.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"sort"
 	"strings"
 	"time"
 
@@ -16,12 +17,14 @@ import (
 )
 
 const (
-	Scene    = "web_turbo_video_generator"
-	CacheTTL = 5 * time.Minute
+	VideoScene = "web_turbo_video_generator"
+	ImageScene = "web_image_agent"
+	CacheTTL   = 5 * time.Minute
 )
 
 // Catalog preserves the server's model configuration, including unknown fields
-// and integer enums. It is never used as a local generation allowlist.
+// and integer enums. Image names are resolved here before submission; admission
+// and parameter validation remain the server's responsibility.
 type Catalog struct {
 	Scene     string `json:"scene"`
 	ConfigKey string `json:"config_key"`
@@ -31,7 +34,7 @@ type Catalog struct {
 }
 
 type Summary struct {
-	Key  string `json:"key"`
+	Key  string `json:"key,omitempty"`
 	Name string `json:"name"`
 	Kind string `json:"kind"`
 }
@@ -62,7 +65,22 @@ func NewService(runner *common.Runner) *Service {
 	return &Service{runner: runner, cacheDir: dir, now: time.Now}
 }
 
-func (s *Service) Get(ctx context.Context, refresh bool) (*Result, error) {
+func sceneForType(modelType string) (string, error) {
+	switch modelType {
+	case "video":
+		return VideoScene, nil
+	case "image":
+		return ImageScene, nil
+	default:
+		return "", fmt.Errorf("不支持的模型类型 %q；--type 可选 video 或 image", modelType)
+	}
+}
+
+func (s *Service) Get(ctx context.Context, modelType string, refresh bool) (*Result, error) {
+	scene, err := sceneForType(modelType)
+	if err != nil {
+		return nil, err
+	}
 	if err := ctx.Err(); err != nil {
 		return nil, err
 	}
@@ -79,9 +97,9 @@ func (s *Service) Get(ctx context.Context, refresh bool) (*Result, error) {
 	if s.runner.Config.Paths != nil && s.runner.Config.Paths.GetAvailableModelList != "" {
 		path = s.runner.Config.Paths.GetAvailableModelList
 	}
-	cachePath := s.cachePath(accessKey, path)
+	cachePath := s.cachePath(accessKey, path, scene)
 	if !refresh && cachePath != "" {
-		if entry := s.readCache(cachePath); entry != nil {
+		if entry := s.readCache(cachePath, scene); entry != nil {
 			return &Result{Catalog: entry.Catalog, Cached: true, FetchedAt: entry.FetchedAt}, nil
 		}
 	}
@@ -100,14 +118,14 @@ func (s *Service) Get(ctx context.Context, refresh bool) (*Result, error) {
 	err = s.runner.Client.SendRequest(queryCtx, path, struct {
 		Scene          string `json:"scene"`
 		SourceModelKey string `json:"source_model_key"`
-	}{Scene: Scene}, &resp)
+	}{Scene: scene}, &resp)
 	if err != nil {
 		return nil, fmt.Errorf("模型查询失败，请稍后重试（可加 --refresh）: %w", err)
 	}
 	if resp.Ret != "0" {
 		return nil, common.NewLogIDError(fmt.Sprintf("模型查询失败，请稍后重试（可加 --refresh）: ret=%s errmsg=%s", resp.Ret, resp.Errmsg), resp.LogID)
 	}
-	if err := validateCatalog(resp.Data); err != nil {
+	if err := validateCatalog(resp.Data, scene); err != nil {
 		return nil, common.NewLogIDError("模型配置无效，请稍后重试（可加 --refresh）: "+err.Error(), resp.LogID)
 	}
 	currentKey, err := s.runner.Auth.ResolveAccessKey(ctx)
@@ -121,24 +139,24 @@ func (s *Service) Get(ctx context.Context, refresh bool) (*Result, error) {
 	return result, nil
 }
 
-func (s *Service) cachePath(accessKey, path string) string {
+func (s *Service) cachePath(accessKey, path, scene string) string {
 	if s.cacheDir == "" {
 		return ""
 	}
 	scope, _ := json.Marshal([]string{
-		"v1", strings.TrimRight(s.runner.Config.BaseURL, "/"), path, Scene,
+		"v1", strings.TrimRight(s.runner.Config.BaseURL, "/"), path, scene,
 		version.Current(), accessKey,
 	})
 	return filepath.Join(s.cacheDir, fmt.Sprintf("%x.json", sha256.Sum256(scope)))
 }
 
-func (s *Service) readCache(path string) *cacheEntry {
+func (s *Service) readCache(path, scene string) *cacheEntry {
 	raw, err := os.ReadFile(path)
 	if err != nil {
 		return nil
 	}
 	var entry cacheEntry
-	if json.Unmarshal(raw, &entry) != nil || validateCatalog(entry.Catalog) != nil {
+	if json.Unmarshal(raw, &entry) != nil || validateCatalog(entry.Catalog, scene) != nil {
 		return nil
 	}
 	age := s.now().Sub(entry.FetchedAt)
@@ -172,20 +190,37 @@ func (s *Service) writeCache(path string, result *Result) error {
 	return os.Rename(f.Name(), path)
 }
 
-func validateCatalog(catalog *Catalog) error {
-	if catalog == nil || catalog.Config == nil || catalog.Scene != Scene || catalog.ConfigKey == "" {
+func validateCatalog(catalog *Catalog, scene string) error {
+	kind := "video"
+	if scene == ImageScene {
+		kind = "image"
+	} else if scene != VideoScene {
+		return fmt.Errorf("不支持的模型场景 %q", scene)
+	}
+	if catalog == nil || catalog.Config == nil || catalog.Scene != scene || catalog.ConfigKey == "" {
 		return fmt.Errorf("缺少配置或场景不匹配")
 	}
 	seen := make(map[string]bool)
+	seenNames := make(map[string]bool)
 	for _, raw := range catalog.Config.Models {
 		var model Summary
-		if json.Unmarshal(raw, &model) != nil || strings.TrimSpace(model.Key) == "" || model.Kind != "video" {
+		if json.Unmarshal(raw, &model) != nil || strings.TrimSpace(model.Key) == "" || model.Kind != kind {
 			return fmt.Errorf("模型条目缺少有效 key 或 kind")
 		}
 		if seen[model.Key] {
+			if kind == "image" {
+				return fmt.Errorf("图片模型配置包含重复条目")
+			}
 			return fmt.Errorf("模型 key 重复: %s", model.Key)
 		}
 		seen[model.Key] = true
+		if kind == "image" {
+			name := strings.TrimSpace(model.Name)
+			if name == "" || strings.EqualFold(name, strings.TrimSpace(model.Key)) || seenNames[name] {
+				return fmt.Errorf("图片模型展示名称缺失、与模型标识相同或重复，请刷新模型列表")
+			}
+			seenNames[name] = true
+		}
 	}
 	return nil
 }
@@ -196,7 +231,10 @@ func (c *Catalog) Search(query string) []Summary {
 	for _, raw := range c.Config.Models {
 		var model Summary
 		_ = json.Unmarshal(raw, &model) // validated at the network/cache boundary
-		if model.Key == query {
+		if c.Scene == ImageScene {
+			model.Key = "" // Wire identifiers stay in the raw catalog only.
+			model.Name = strings.TrimSpace(model.Name)
+		} else if model.Key == query {
 			return []Summary{model}
 		}
 		if query == "" || strings.Contains(strings.ToLower(model.Name), strings.ToLower(query)) || strings.Contains(strings.ToLower(model.Key), strings.ToLower(query)) {
@@ -206,14 +244,78 @@ func (c *Catalog) Search(query string) []Summary {
 	return matches
 }
 
-func (c *Catalog) Describe(key string) (json.RawMessage, error) {
-	key = strings.TrimSpace(key)
+func (c *Catalog) findModel(selector string) (json.RawMessage, error) {
+	selector = strings.TrimSpace(selector)
+	var found json.RawMessage
 	for _, raw := range c.Config.Models {
 		var model Summary
 		_ = json.Unmarshal(raw, &model)
-		if model.Key == key {
-			return describeModel(raw)
+		value := model.Key
+		if c.Scene == ImageScene {
+			value = strings.TrimSpace(model.Name)
 		}
+		if value != "" && value == selector {
+			if found != nil {
+				return nil, fmt.Errorf("模型名称重复，请执行 model list --type image --refresh 刷新后重试")
+			}
+			found = raw
+		}
+	}
+	if found != nil {
+		return found, nil
+	}
+	if c.Scene == ImageScene {
+		return nil, fmt.Errorf("未找到该图片模型名称；请执行 model list --type image --refresh，并使用列表中的完整名称")
+	}
+	return nil, fmt.Errorf("未找到可用模型 %q；请执行 model list --type video --refresh 查看当前模型", selector)
+}
+
+func (c *Catalog) Describe(selector string) (json.RawMessage, error) {
+	raw, err := c.findModel(selector)
+	if err != nil {
+		return nil, err
+	}
+	return describeModel(raw)
+}
+
+// ImageModelKey translates the user's exact display name into a wire value.
+// Never guess keys from names or send an unresolved name to the server.
+func (c *Catalog) ImageModelKey(name string) (string, error) {
+	if c.Scene != ImageScene {
+		return "", fmt.Errorf("图片生成需要图片模型配置")
+	}
+	raw, err := c.findModel(name)
+	if err != nil {
+		return "", err
+	}
+	var model Summary
+	_ = json.Unmarshal(raw, &model)
+	return model.Key, nil
+}
+
+// ImageDisplayMessage keeps known wire identifiers out of server error messages.
+func (c *Catalog) ImageDisplayMessage(message string) string {
+	var models []Summary
+	for _, raw := range c.Config.Models {
+		var model struct {
+			Summary
+			ReportName string `json:"report_name"`
+		}
+		_ = json.Unmarshal(raw, &model)
+		name := strings.TrimSpace(model.Name)
+		if model.Kind == "image" && name != "" {
+			for _, value := range []string{model.Key, model.ReportName} {
+				if value != "" && value != name {
+					models = append(models, Summary{Key: value, Name: name})
+				}
+			}
+		}
+	}
+	// A key can be a prefix of another key. Replace the longer one first.
+	sort.Slice(models, func(i, j int) bool { return len(models[i].Key) > len(models[j].Key) })
+	pairs := make([]string, 0, len(models)*2)
+	for _, model := range models {
+		pairs = append(pairs, model.Key, strings.TrimSpace(model.Name))
 	}
-	return nil, fmt.Errorf("未找到可用模型 %q；请执行 model list --refresh 查看当前模型", key)
+	return strings.NewReplacer(pairs...).Replace(message)
 }

package/internal/models/models_test.go

@@ -45,11 +45,11 @@ func TestMissingCredentialsCannotReadFreshCache(t *testing.T) {
 		requests++
 		_, _ = w.Write([]byte(validResponse))
 	})
-	if _, err := s.Get(context.Background(), false); err != nil {
+	if _, err := s.Get(context.Background(), "video", false); err != nil {
 		t.Fatal(err)
 	}
 	s.runner.Auth = unavailableAuth{}
-	result, err := s.Get(context.Background(), false)
+	result, err := s.Get(context.Background(), "video", false)
 	if err == nil || result != nil || requests != 1 || !strings.Contains(err.Error(), "login") {
 		t.Fatalf("must require login before cache: result=%+v err=%v requests=%d", result, err, requests)
 	}
@@ -63,7 +63,7 @@ func TestCacheTTLRefreshAndIsolation(t *testing.T) {
 			t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)
 		}
 		var body map[string]string
-		if err := json.NewDecoder(r.Body).Decode(&body); err != nil || body["scene"] != Scene || body["source_model_key"] != "" {
+		if err := json.NewDecoder(r.Body).Decode(&body); err != nil || body["scene"] != VideoScene || body["source_model_key"] != "" {
 			t.Errorf("unexpected body: %v, err=%v", body, err)
 		}
 		_, _ = w.Write([]byte(validResponse))
@@ -72,7 +72,7 @@ func TestCacheTTLRefreshAndIsolation(t *testing.T) {
 	s.now = func() time.Time { return now }
 	check := func(refresh, cached bool, count int) *Result {
 		t.Helper()
-		result, err := s.Get(context.Background(), refresh)
+		result, err := s.Get(context.Background(), "video", refresh)
 		if err != nil || result.Cached != cached || requests != count {
 			t.Fatalf("Get: result=%+v err=%v requests=%d, want cached=%v requests=%d", result, err, requests, cached, count)
 		}
@@ -89,9 +89,9 @@ func TestCacheTTLRefreshAndIsolation(t *testing.T) {
 	check(true, false, 3)
 	s.runner.Config.AccessKey = "second-account"
 	check(false, false, 4)
-	oldPath := s.cachePath("second-account", config.GetAvailableModelListPath)
+	oldPath := s.cachePath("second-account", config.GetAvailableModelListPath, VideoScene)
 	s.runner.Config.BaseURL += "/other-api"
-	if s.cachePath("second-account", config.GetAvailableModelListPath) == oldPath {
+	if s.cachePath("second-account", config.GetAvailableModelListPath, VideoScene) == oldPath {
 		t.Fatal("API base URLs must not share cache")
 	}
 	files, _ := os.ReadDir(s.cacheDir)
@@ -110,7 +110,7 @@ func TestFailedQueryDoesNotUseOrCacheStaleData(t *testing.T) {
 		requests++
 		_, _ = w.Write([]byte(response))
 	})
-	if _, err := s.Get(context.Background(), false); err != nil {
+	if _, err := s.Get(context.Background(), "video", false); err != nil {
 		t.Fatal(err)
 	}
 	for _, invalid := range []string{
@@ -120,29 +120,29 @@ func TestFailedQueryDoesNotUseOrCacheStaleData(t *testing.T) {
 		`not-json`,
 	} {
 		response = invalid
-		if result, err := s.Get(context.Background(), true); err == nil || result != nil || !strings.Contains(err.Error(), "重试") {
+		if result, err := s.Get(context.Background(), "video", true); err == nil || result != nil || !strings.Contains(err.Error(), "重试") {
 			t.Fatalf("failed query must suggest retry: result=%+v err=%v", result, err)
 		}
 		before := requests
-		if _, err := s.Get(context.Background(), false); err == nil || requests != before+1 {
+		if _, err := s.Get(context.Background(), "video", false); err == nil || requests != before+1 {
 			t.Fatal("retry must query the server, not reuse cached success or failure")
 		}
 	}
 	response = validResponse
-	if _, err := s.Get(context.Background(), false); err != nil {
+	if _, err := s.Get(context.Background(), "video", false); err != nil {
 		t.Fatal(err)
 	}
-	cachePath := s.cachePath(s.runner.Config.AccessKey, config.GetAvailableModelListPath)
+	cachePath := s.cachePath(s.runner.Config.AccessKey, config.GetAvailableModelListPath, VideoScene)
 	if err := os.WriteFile(cachePath, []byte("broken"), 0600); err != nil {
 		t.Fatal(err)
 	}
-	result, err := s.Get(context.Background(), false)
+	result, err := s.Get(context.Background(), "video", false)
 	if err != nil || result.Cached {
 		t.Fatalf("corrupt cache should refresh: %+v %v", result, err)
 	}
 	// A timestamp in the future must not extend visibility indefinitely.
 	s.now = func() time.Time { return result.FetchedAt.Add(-time.Second) }
-	if s.readCache(cachePath) != nil {
+	if s.readCache(cachePath, VideoScene) != nil {
 		t.Fatal("future-dated cache must be ignored")
 	}
 }
@@ -150,7 +150,7 @@ func TestFailedQueryDoesNotUseOrCacheStaleData(t *testing.T) {
 func TestModelConfigurationPreservedAcrossCache(t *testing.T) {
 	s := newTestService(t, func(w http.ResponseWriter, _ *http.Request) { _, _ = w.Write([]byte(validResponse)) })
 	for i := 0; i < 2; i++ {
-		result, err := s.Get(context.Background(), false)
+		result, err := s.Get(context.Background(), "video", false)
 		if err != nil {
 			t.Fatal(err)
 		}
@@ -188,7 +188,7 @@ func TestCacheWriteFailureStillReturnsServerResult(t *testing.T) {
 		t.Fatal(err)
 	}
 	s.cacheDir = file
-	result, err := s.Get(context.Background(), false)
+	result, err := s.Get(context.Background(), "video", false)
 	if err != nil || result.Cached || result.Warning == "" {
 		t.Fatalf("result=%+v err=%v", result, err)
 	}
@@ -207,8 +207,150 @@ func TestEmptyAndDuplicateModels(t *testing.T) {
 		if err := json.Unmarshal([]byte(tc.data), &catalog); err != nil {
 			t.Fatal(err)
 		}
-		if err := validateCatalog(&catalog); (err == nil) != tc.valid {
+		if err := validateCatalog(&catalog, VideoScene); (err == nil) != tc.valid {
 			t.Fatalf("validateCatalog = %v", err)
 		}
 	}
 }
+
+func TestImageAndVideoCacheIsolation(t *testing.T) {
+	requests := map[string]int{}
+	failImage := false
+	s := newTestService(t, func(w http.ResponseWriter, r *http.Request) {
+		var body map[string]string
+		if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+			t.Error(err)
+			return
+		}
+		scene := body["scene"]
+		requests[scene]++
+		if body["source_model_key"] != "" || len(body) != 2 {
+			t.Errorf("unexpected identity or selector fields: %v", body)
+		}
+		response := validResponse
+		switch scene {
+		case ImageScene:
+			response = strings.ReplaceAll(strings.ReplaceAll(validResponse, VideoScene, ImageScene), `"kind":"video"`, `"kind":"image"`)
+			if failImage {
+				response = `{"ret":"1001","errmsg":"scene not supported"}`
+			}
+		case VideoScene:
+		default:
+			t.Errorf("unexpected scene %q", scene)
+		}
+		_, _ = w.Write([]byte(response))
+	})
+	for _, kind := range []string{"image", "video"} {
+		for i := 0; i < 2; i++ {
+			result, err := s.Get(context.Background(), kind, false)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if result.Cached != (i == 1) || result.Catalog.Search("")[0].Kind != kind {
+				t.Fatalf("cache crossed model type: %+v", result)
+			}
+		}
+	}
+	if requests[ImageScene] != 1 || requests[VideoScene] != 1 {
+		t.Fatalf("requests=%v", requests)
+	}
+	// Even a syntactically valid video cache at the image path must be ignored.
+	videoPath := s.cachePath(s.runner.Config.AccessKey, config.GetAvailableModelListPath, VideoScene)
+	imagePath := s.cachePath(s.runner.Config.AccessKey, config.GetAvailableModelListPath, ImageScene)
+	raw, err := os.ReadFile(videoPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(imagePath, raw, 0600); err != nil {
+		t.Fatal(err)
+	}
+	result, err := s.Get(context.Background(), "image", false)
+	if err != nil || result.Cached || requests[ImageScene] != 2 {
+		t.Fatalf("mismatched cache not refreshed: result=%+v err=%v requests=%v", result, err, requests)
+	}
+	failImage = true
+	for _, refresh := range []bool{true, false} {
+		if result, err := s.Get(context.Background(), "image", refresh); err == nil || result != nil {
+			t.Fatalf("image failure reused a catalog: result=%+v err=%v", result, err)
+		}
+	}
+	result, err = s.Get(context.Background(), "video", false)
+	if err != nil || !result.Cached || requests[ImageScene] != 4 || requests[VideoScene] != 1 {
+		t.Fatalf("image refresh invalidated video: result=%+v err=%v requests=%v", result, err, requests)
+	}
+}
+
+func TestImageCatalogValidation(t *testing.T) {
+	for _, tc := range []struct {
+		name, scene, models string
+		valid               bool
+	}{
+		{"empty", ImageScene, `[]`, true},
+		{"image", ImageScene, `[{"key":"dynamic-image","name":"图片测试模型","kind":"image"}]`, true},
+		{"missing name", ImageScene, `[{"key":"x","kind":"image"}]`, false},
+		{"blank name", ImageScene, `[{"key":"x","kind":"image","name":" "}]`, false},
+		{"unknown enum is not a display name", ImageScene, `[{"key":"future_code","name":"future_code","kind":"image"}]`, false},
+		{"duplicate name", ImageScene, `[{"key":"x","kind":"image","name":"名称"},{"key":"y","kind":"image","name":" 名称 "}]`, false},
+		{"wrong scene", VideoScene, `[{"key":"x","kind":"image"}]`, false},
+		{"wrong kind", ImageScene, `[{"key":"x","kind":"video"}]`, false},
+		{"duplicate", ImageScene, `[{"key":"x","kind":"image"},{"key":"x","kind":"image"}]`, false},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			s := newTestService(t, func(w http.ResponseWriter, _ *http.Request) {
+				_, _ = w.Write([]byte(`{"ret":"0","data":{"scene":"` + tc.scene + `","config_key":"key","config":{"models":` + tc.models + `}}}`))
+			})
+			result, err := s.Get(context.Background(), "image", false)
+			if (err == nil) != tc.valid {
+				t.Fatalf("result=%+v err=%v valid=%v", result, err, tc.valid)
+			}
+		})
+	}
+}
+
+func TestImageNamesKeepWireKeysInternalAcrossCache(t *testing.T) {
+	const response = `{"ret":"0","data":{"scene":"web_image_agent","config_key":"image-config","config":{"models":[{"key":"wire-image","name":"智能图片V2","kind":"image"},{"key":"wire-image-fast","report_name":"wire-image-fast","name":"智能图片V2.5 Fast","kind":"image","is_default":true,"supported_ratio_list":[3,6]}]}}}`
+	s := newTestService(t, func(w http.ResponseWriter, _ *http.Request) { _, _ = w.Write([]byte(response)) })
+	for i := 0; i < 2; i++ {
+		result, err := s.Get(context.Background(), "image", false)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if result.Cached != (i == 1) {
+			t.Fatalf("cached=%v", result.Cached)
+		}
+		catalog := result.Catalog
+		list := catalog.Search("智能图片")
+		if len(list) != 2 || list[1].Name != "智能图片V2.5 Fast" {
+			t.Fatalf("unexpected image names: %+v", list)
+		}
+		if len(catalog.Search("wire-image")) != 0 || len(catalog.Search("fast")) != 1 {
+			t.Fatal("image search must use display names only")
+		}
+		raw, err := json.Marshal(list)
+		if err != nil || strings.Contains(string(raw), `"key"`) || strings.Contains(string(raw), "wire-image") {
+			t.Fatalf("list leaked identifiers: %s, %v", raw, err)
+		}
+		detail, err := catalog.Describe(list[1].Name)
+		if err != nil || strings.Contains(string(detail), "wire-image") || !strings.Contains(string(detail), "智能图片V2.5 Fast") {
+			t.Fatalf("detail leaked identifiers or lost name: %s, %v", detail, err)
+		}
+		key, err := catalog.ImageModelKey(" 智能图片V2.5 Fast ")
+		if err != nil || key != "wire-image-fast" {
+			t.Fatalf("name resolution: key=%q, err=%v", key, err)
+		}
+		for _, invalid := range []string{"", "智能图片", "wire-image-fast", "不存在"} {
+			if _, err := catalog.ImageModelKey(invalid); err == nil || strings.Contains(err.Error(), "wire-image") {
+				t.Fatalf("unresolved input accepted or leaked: %q, %v", invalid, err)
+			}
+			if _, err := catalog.Describe(invalid); err == nil || strings.Contains(err.Error(), "wire-image") {
+				t.Fatalf("detail accepted unresolved input: %q, %v", invalid, err)
+			}
+		}
+		if !strings.Contains(string(catalog.Config.Models[1]), "wire-image-fast") {
+			t.Fatal("presentation mutated the cached request identifier")
+		}
+		if got := catalog.ImageDisplayMessage("wire-image-fast / wire-image"); got != "智能图片V2.5 Fast / 智能图片V2" {
+			t.Fatalf("error must use names: %s", got)
+		}
+	}
+}

package/package.json

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

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

@@ -10,8 +10,6 @@ metadata:
 
 通过 CLI 完成生成、处理、结果下载与媒体交付。支持下表中的操作；不提供多轮会话续写或自动拆分剧本、分镜并编排成片的能力。复杂需求先确认能由所列命令完成的具体操作，不承诺未覆盖的流程。
 
-商品图文营销一键成片（剧情广告、品牌大片、达人带货）由独立的 `xyq-marketing-skill` 提供，不用普通生视频代替营销编排；未安装该 Skill 时先说明当前能力边界。
-
 ## 开始执行
 
 1. 画布任务运行 `node "{baseDir}/scripts/ensure-cli.js" --canvas`，其他任务运行 `node "{baseDir}/scripts/ensure-cli.js"`。保存返回的 `cli_path`；Canvas 还需保存 `canvas_entry`。文档中的 `pippit-tool-cli` 替换为带引号的 `cli_path`；画布语义命令按模块说明通过 Node 入口执行。同一任务复用，安装细节见 [安装说明](scripts/install.md)。
@@ -29,7 +27,7 @@ metadata:
 | 查看登录状态、登录、退出或切换账号 | `status` / `login` / `logout` | [授权](commands/auth.md) |
 | 创建或查询小云雀个人画布，编辑节点、布局、连线、角色/场景、提示词、3D 或多轨草稿 | `canvas` | [Canvas 能力与命令发现](commands/canvas.md) |
 | 生成图片，或基于参考图修改图片 | `generate-image` | [生图与图片编辑](commands/generate-image.md) |
-| 查询当前可用的视频模型、参数配置 | `model list` / `model describe` | [模型发现](commands/model.md) |
+| 查询当前可用的图片/视频模型、比例、分辨率及推理强度等参数配置 | `model list` / `model describe` | [模型发现](commands/model.md) |
 | 生成视频，使用图/视频/音频参考，首尾帧生视频 | `generate-video` | [生视频](commands/generate-video.md) |
 | 提升已有视频分辨率、视频超分 | `video-super-resolution` | [超分](commands/video-super-resolution.md) |
 | 去除已有视频字幕 | `erase-video-subtitle` | [擦字幕](commands/erase-video-subtitle.md) |
@@ -45,6 +43,7 @@ metadata:
 ## 执行总则
 
 - 保留用户原始 prompt，不擅自扩写、润色、翻译或增加风格词；参数转换按对应命令文档执行。生成和视频处理只传用户给定的可选创作参数，缺少必填项先询问。画布输入还需使用实际查询的 ID、版本和当前 schema。模型和参数最终合法性由服务端判断。
+- 图片模型对用户只展示服务端返回的名称；列表、选择、详情与生成命令均使用完整名称，不解释或展示对应底层枚举。名称到提交标识由 CLI 解析，详见 [模型发现](commands/model.md)。
 - 用户明确要求生成或处理，即可在该范围内执行；仅咨询用法、费用或方案时不提交。范围、必填信息或消耗 credits 的授权不明确时，先确认，不重复索要已给出的授权。
 - 提问优先使用宿主实际提供且当前模式允许的工具：Codex 的 `request_user_input` 或 `request_user_input_async`，WorkBuddy 的 `ask_user_question`；不可用时用普通聊天。需要答案时等待答复。
 - 素材参数接收本地文件路径，CLI 内部上传。远程链接不能冒充本地路径；缺少可访问文件时先解决素材获取。单文件必须小于 500 MB（500000000 字节）。

package/skills/xyq-nest-skill/commands/generate-image.md

@@ -7,25 +7,30 @@
 | 参数 | 必填 | 规则 |
 | --- | --- | --- |
 | `--prompt` | 是 | 用户原始描述，不能全为空白 |
-| `--model` | 是 | 用户选择的图片模型；缺少时先询问 |
+| `--model` | 是 | 用户选择的图片模型完整名称；包含空格时加引号，缺少时先询问 |
 | `--image` | 否 | 本地参考图路径，多张图重复此参数，保留用户指定的角色与顺序 |
-| `--ratio` | 否 | 整数枚举，按下表转换明确的比例要求 |
-| `--resolution` | 否 | 仅 `seedream_5.0_pro` 支持 `1K`、`2K`、`4K` 选项 |
+| `--ratio` | 否 | 查询返回的数字枚举（如 `3` 表示 `9:16`）；比例含义见 `option_labels` |
+| `--resolution` | 否 | 对应模型查询返回的分辨率；提交时转为大写 |
+| `--effort` | 否 | 对应模型查询返回的推理强度；提交为 `general_agent_settings.image_effort`，转为小写 |
 | `--generate-image-count` | 否 | 用户指定的生成数量 |
 
-比例映射：`0=原始比例/自动`、`2=16:9`、`13=21:9`、`3=9:16`、`4=4:3`、`5=3:4`、`6=1:1`。此命令接收整数，不传 `--ratio "16:9"`。用户未给比例时省略；不明确的比例先确认，不猜枚举。
+先用 `pippit-tool-cli model list --type image` 查询模型，再用 `pippit-tool-cli model describe "模型名称" --type image` 查询比例、分辨率和可选推理强度。对用户只展示名称，不提供底层模型枚举。生成命令用 `--model "完整名称"`，CLI 负责从当前配置中解析提交标识；名称不存在或重复时停止。查询失败时按错误处理，不回退静态模型目录；细节见 [模型发现](model.md)。
 
-当前 CLI 帮助列出的模型包括 `seedream_5.0_pro`、`seedream_5.0`、`seedream_4.3`、`nova2`、`seedream_4.5`、`seedream_4.1`、`seedream_4`。用于提示选择，实际支持情况以当前帮助和服务端为准，不在 Skill 中增加模型白名单校验。
+图片比例只传数字，例如用户指定 `9:16` 时使用 `--ratio 3`。从模型查询的 `option_labels` 确认含义，再将对应的数字 `options` 传入；`0` 表示自动比例。CLI 校验整数格式，模型是否支持该枚举由服务端决定。
+
+推理强度只有部分模型包含；未下发 `effort` 维度时不主动提供档位选择。用户未指定的比例、分辨率、推理强度均省略，不从查询默认值自动补齐。条件维度和参数组合以服务端下发为准，不将每个维度的选项任意组合；不在 Skill 或 CLI 维护模型白名单。
+
+使用旧版 CLI 时先检查 `generate-image --help`；若 `--model` 仍要求 key，或缺少用户指定的 `--effort`，先升级，不能把底层枚举交给用户或静默丢弃推理强度。
 
 本地图片后缀支持 `.jpg/.jpeg/.png/.gif/.bmp/.webp/.svg`。参考图由命令内部上传，不需要自行获取资产 ID。
 
 ## 最小调用
 
 ```bash
-pippit-tool-cli generate-image --prompt "用户原始描述" --model IMAGE_MODEL
+pippit-tool-cli generate-image --prompt "用户原始描述" --model "智能图片V2.5 Fast"
 ```
 
-只追加用户已提供的可选参数。多图编辑见 [参考图编辑示例](../examples/image-edit.md)。
+上例名称须存在于实际查询结果，不能当作静态可用列表。CLI 在上传前复用当前凭证下的有效缓存或查询模型列表，提交时才使用底层枚举，不让用户填写枚举。只追加用户已提供的可选参数。多图编辑见 [参考图编辑示例](../examples/image-edit.md)。
 
 ## 返回与处理