@pippit-dev/cli 1.0.26 → 1.0.27

package/internal/models/models.go

@@ -0,0 +1,220 @@
+package models
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/Pippit-dev/pippit-cli/internal/common"
+	"github.com/Pippit-dev/pippit-cli/internal/config"
+	"github.com/Pippit-dev/pippit-cli/internal/version"
+)
+
+const (
+	Scene    = "web_turbo_video_generator"
+	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.
+type Catalog struct {
+	Scene     string `json:"scene"`
+	ConfigKey string `json:"config_key"`
+	Config    *struct {
+		Models []json.RawMessage `json:"models"`
+	} `json:"config"`
+}
+
+type Summary struct {
+	Key       string `json:"key"`
+	Name      string `json:"name"`
+	Kind      string `json:"kind"`
+	IsDefault bool   `json:"is_default"`
+}
+
+type Result struct {
+	Catalog   *Catalog
+	Cached    bool
+	FetchedAt time.Time
+	Warning   string
+}
+
+type cacheEntry struct {
+	FetchedAt time.Time `json:"fetched_at"`
+	Catalog   *Catalog  `json:"catalog"`
+}
+
+type Service struct {
+	runner   *common.Runner
+	cacheDir string
+	now      func() time.Time
+}
+
+func NewService(runner *common.Runner) *Service {
+	dir, err := os.UserCacheDir()
+	if err == nil {
+		dir = filepath.Join(dir, "pippit-cli", "models")
+	}
+	return &Service{runner: runner, cacheDir: dir, now: time.Now}
+}
+
+func (s *Service) Get(ctx context.Context, refresh bool) (*Result, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	if s.runner == nil || s.runner.Config == nil || s.runner.Client == nil || s.runner.Auth == nil {
+		return nil, fmt.Errorf("模型查询运行器未初始化")
+	}
+	// Resolve credentials before reading cache: logout/expiry must not expose a
+	// previous account's model list. Only a hash is used in the cache filename.
+	accessKey, err := s.runner.Auth.ResolveAccessKey(ctx)
+	if err != nil || strings.TrimSpace(accessKey) == "" {
+		return nil, fmt.Errorf("模型查询需要有效登录，请执行 pippit-tool-cli login 或检查 XYQ_ACCESS_KEY 后重试")
+	}
+	path := config.GetAvailableModelListPath
+	if s.runner.Config.Paths != nil && s.runner.Config.Paths.GetAvailableModelList != "" {
+		path = s.runner.Config.Paths.GetAvailableModelList
+	}
+	cachePath := s.cachePath(accessKey, path)
+	if !refresh && cachePath != "" {
+		if entry := s.readCache(cachePath); entry != nil {
+			return &Result{Catalog: entry.Catalog, Cached: true, FetchedAt: entry.FetchedAt}, nil
+		}
+	}
+	// A failed refresh must not make the next retry reuse an older fresh entry.
+	if cachePath != "" {
+		_ = os.Remove(cachePath)
+	}
+	queryCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+	var resp struct {
+		Ret    string   `json:"ret"`
+		Errmsg string   `json:"errmsg"`
+		LogID  string   `json:"log_id"`
+		Data   *Catalog `json:"data"`
+	}
+	err = s.runner.Client.SendRequest(queryCtx, path, struct {
+		Scene          string `json:"scene"`
+		SourceModelKey string `json:"source_model_key"`
+	}{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 {
+		return nil, common.NewLogIDError("模型配置无效，请稍后重试（可加 --refresh）: "+err.Error(), resp.LogID)
+	}
+	currentKey, err := s.runner.Auth.ResolveAccessKey(ctx)
+	if err != nil || currentKey != accessKey {
+		return nil, fmt.Errorf("查询期间登录凭证已变化，请重试模型查询")
+	}
+	result := &Result{Catalog: resp.Data, FetchedAt: s.now().UTC()}
+	if cachePath == "" || s.writeCache(cachePath, result) != nil {
+		result.Warning = "模型查询成功，但本地缓存写入失败；下次查询将重新请求服务端"
+	}
+	return result, nil
+}
+
+func (s *Service) cachePath(accessKey, path string) string {
+	if s.cacheDir == "" {
+		return ""
+	}
+	scope, _ := json.Marshal([]string{
+		"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 {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil
+	}
+	var entry cacheEntry
+	if json.Unmarshal(raw, &entry) != nil || validateCatalog(entry.Catalog) != nil {
+		return nil
+	}
+	age := s.now().Sub(entry.FetchedAt)
+	if age < 0 || age >= CacheTTL {
+		return nil
+	}
+	return &entry
+}
+
+func (s *Service) writeCache(path string, result *Result) error {
+	raw, err := json.Marshal(cacheEntry{FetchedAt: result.FetchedAt, Catalog: result.Catalog})
+	if err != nil {
+		return err
+	}
+	if err := os.MkdirAll(s.cacheDir, 0700); err != nil {
+		return err
+	}
+	f, err := os.CreateTemp(s.cacheDir, ".models-*.tmp")
+	if err != nil {
+		return err
+	}
+	defer os.Remove(f.Name())
+	_, writeErr := f.Write(raw)
+	closeErr := f.Close()
+	if writeErr != nil {
+		return writeErr
+	}
+	if closeErr != nil {
+		return closeErr
+	}
+	return os.Rename(f.Name(), path)
+}
+
+func validateCatalog(catalog *Catalog) error {
+	if catalog == nil || catalog.Config == nil || catalog.Scene != Scene || catalog.ConfigKey == "" {
+		return fmt.Errorf("缺少配置或场景不匹配")
+	}
+	seen := 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" {
+			return fmt.Errorf("模型条目缺少有效 key 或 kind")
+		}
+		if seen[model.Key] {
+			return fmt.Errorf("模型 key 重复: %s", model.Key)
+		}
+		seen[model.Key] = true
+	}
+	return nil
+}
+
+func (c *Catalog) Search(query string) []Summary {
+	query = strings.TrimSpace(query)
+	matches := make([]Summary, 0)
+	for _, raw := range c.Config.Models {
+		var model Summary
+		_ = json.Unmarshal(raw, &model) // validated at the network/cache boundary
+		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)) {
+			matches = append(matches, model)
+		}
+	}
+	return matches
+}
+
+func (c *Catalog) Describe(key string) (json.RawMessage, error) {
+	key = strings.TrimSpace(key)
+	for _, raw := range c.Config.Models {
+		var model Summary
+		_ = json.Unmarshal(raw, &model)
+		if model.Key == key {
+			return describeModel(raw)
+		}
+	}
+	return nil, fmt.Errorf("未找到可用模型 %q；请执行 model list --refresh 查看当前模型", key)
+}

package/internal/models/models_test.go

@@ -0,0 +1,200 @@
+package models
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/Pippit-dev/pippit-cli/internal/auth"
+	"github.com/Pippit-dev/pippit-cli/internal/common"
+	"github.com/Pippit-dev/pippit-cli/internal/config"
+)
+
+const validResponse = `{"ret":"0","data":{"scene":"web_turbo_video_generator","config_key":"key1","config":{"models":[{"key":"new-model","kind":"video","name":"新模型","is_default":true,"supported_ratio_list":[0,1],"audio_total_limit":0,"future_field":9007199254740993}]}}}`
+
+func newTestService(t *testing.T, handler http.HandlerFunc) *Service {
+	t.Helper()
+	server := httptest.NewServer(handler)
+	t.Cleanup(server.Close)
+	cfg := config.Load()
+	cfg.BaseURL, cfg.AccessKey = server.URL, "private-test-key"
+	runner := common.NewRunner(cfg, nil)
+	runner.Auth = auth.NewManager(cfg)
+	runner.Client = common.NewHTTPClient(server.URL, time.Second, common.NewAccessKeyContextProviderAuthorizer(runner.Auth.ResolveAccessKey))
+	s := NewService(runner)
+	s.cacheDir = t.TempDir()
+	return s
+}
+
+type unavailableAuth struct{ common.AuthManager }
+
+func (unavailableAuth) ResolveAccessKey(context.Context) (string, error) {
+	return "", errors.New("expired credential")
+}
+
+func TestMissingCredentialsCannotReadFreshCache(t *testing.T) {
+	requests := 0
+	s := newTestService(t, func(w http.ResponseWriter, _ *http.Request) {
+		requests++
+		_, _ = w.Write([]byte(validResponse))
+	})
+	if _, err := s.Get(context.Background(), false); err != nil {
+		t.Fatal(err)
+	}
+	s.runner.Auth = unavailableAuth{}
+	result, err := s.Get(context.Background(), 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)
+	}
+}
+
+func TestCacheTTLRefreshAndIsolation(t *testing.T) {
+	requests := 0
+	s := newTestService(t, func(w http.ResponseWriter, r *http.Request) {
+		requests++
+		if r.Method != "POST" || r.URL.Path != config.GetAvailableModelListPath || !strings.HasPrefix(r.Header.Get("Authorization"), "Bearer ") {
+			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"] != "" {
+			t.Errorf("unexpected body: %v, err=%v", body, err)
+		}
+		_, _ = w.Write([]byte(validResponse))
+	})
+	now := time.Date(2026, 9, 20, 12, 0, 0, 0, time.UTC)
+	s.now = func() time.Time { return now }
+	check := func(refresh, cached bool, count int) *Result {
+		t.Helper()
+		result, err := s.Get(context.Background(), 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)
+		}
+		return result
+	}
+	first := check(false, false, 1)
+	now = now.Add(CacheTTL - time.Second)
+	cached := check(false, true, 1)
+	if !cached.FetchedAt.Equal(first.FetchedAt) {
+		t.Fatal("cache hit must not renew TTL")
+	}
+	now = now.Add(time.Second)
+	check(false, false, 2) // expires exactly at five minutes
+	check(true, false, 3)
+	s.runner.Config.AccessKey = "second-account"
+	check(false, false, 4)
+	oldPath := s.cachePath("second-account", config.GetAvailableModelListPath)
+	s.runner.Config.BaseURL += "/other-api"
+	if s.cachePath("second-account", config.GetAvailableModelListPath) == oldPath {
+		t.Fatal("API base URLs must not share cache")
+	}
+	files, _ := os.ReadDir(s.cacheDir)
+	for _, file := range files {
+		raw, _ := os.ReadFile(filepath.Join(s.cacheDir, file.Name()))
+		if strings.Contains(string(raw)+file.Name(), "private-test-key") || strings.Contains(string(raw)+file.Name(), "second-account") {
+			t.Fatal("cache must not persist raw credentials")
+		}
+	}
+}
+
+func TestFailedQueryDoesNotUseOrCacheStaleData(t *testing.T) {
+	response := validResponse
+	requests := 0
+	s := newTestService(t, func(w http.ResponseWriter, _ *http.Request) {
+		requests++
+		_, _ = w.Write([]byte(response))
+	})
+	if _, err := s.Get(context.Background(), false); err != nil {
+		t.Fatal(err)
+	}
+	for _, invalid := range []string{
+		`{"ret":"1001","errmsg":"unavailable","log_id":"log_123"}`,
+		`{"ret":"0","data":null}`,
+		`{"ret":"0","data":{"scene":"other","config_key":"key","config":{}}}`,
+		`not-json`,
+	} {
+		response = invalid
+		if result, err := s.Get(context.Background(), 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 {
+			t.Fatal("retry must query the server, not reuse cached success or failure")
+		}
+	}
+	response = validResponse
+	if _, err := s.Get(context.Background(), false); err != nil {
+		t.Fatal(err)
+	}
+	cachePath := s.cachePath(s.runner.Config.AccessKey, config.GetAvailableModelListPath)
+	if err := os.WriteFile(cachePath, []byte("broken"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	result, err := s.Get(context.Background(), 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 {
+		t.Fatal("future-dated cache must be ignored")
+	}
+}
+
+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)
+		if err != nil {
+			t.Fatal(err)
+		}
+		raw, err := result.Catalog.Describe("new-model")
+		if err != nil || !strings.Contains(string(raw), "9007199254740993") || !strings.Contains(string(raw), `"audio_total_limit":0`) {
+			t.Fatalf("configuration lost values: %s %v", raw, err)
+		}
+		if len(result.Catalog.Search("新模")) != 1 || len(result.Catalog.Search("missing")) != 0 {
+			t.Fatal("unexpected search result")
+		}
+		if _, err := result.Catalog.Describe("missing"); err == nil {
+			t.Fatal("missing model must not invent a config")
+		}
+	}
+}
+
+func TestCacheWriteFailureStillReturnsServerResult(t *testing.T) {
+	s := newTestService(t, func(w http.ResponseWriter, _ *http.Request) { _, _ = w.Write([]byte(validResponse)) })
+	file := filepath.Join(t.TempDir(), "not-a-directory")
+	if err := os.WriteFile(file, []byte("x"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	s.cacheDir = file
+	result, err := s.Get(context.Background(), false)
+	if err != nil || result.Cached || result.Warning == "" {
+		t.Fatalf("result=%+v err=%v", result, err)
+	}
+}
+
+func TestEmptyAndDuplicateModels(t *testing.T) {
+	for _, tc := range []struct {
+		data  string
+		valid bool
+	}{
+		{`{"scene":"web_turbo_video_generator","config_key":"empty","config":{}}`, true},
+		{`{"scene":"web_turbo_video_generator","config_key":"dup","config":{"models":[{"key":"x","kind":"video"},{"key":"x","kind":"video"}]}}`, false},
+		{`{"scene":"web_turbo_video_generator","config_key":"null","config":{"models":[null]}}`, false},
+	} {
+		var catalog Catalog
+		if err := json.Unmarshal([]byte(tc.data), &catalog); err != nil {
+			t.Fatal(err)
+		}
+		if err := validateCatalog(&catalog); (err == nil) != tc.valid {
+			t.Fatalf("validateCatalog = %v", err)
+		}
+	}
+}

package/internal/short_drama/submit_run.go

@@ -9,6 +9,7 @@ import (
 
 // SubmitRunOptions is the stable command-facing request shape for short drama run submission.
 type SubmitRunOptions struct {
+	Source   string   `json:"platform,omitempty"`
 	Message  string   `json:"message"`
 	ThreadID string   `json:"thread_id,omitempty"`
 	AssetIDs []string `json:"asset_ids,omitempty"`
@@ -36,6 +37,7 @@ func SubmitRun(ctx context.Context, opts *SubmitRunOptions, runner *common.Runne
 		body["asset_ids"] = opts.AssetIDs
 	}
 	body["agent_name"] = "pippit_nest_novel_agent"
+	body = common.WithSubmitRunSource(body, opts.Source)
 
 	var resp common.SubmitRunResponse
 	if err := runner.Client.SendRequest(ctx, common.SubmitRunPath(runner), body, &resp); err != nil {

package/internal/video_tool/video_tool.go

@@ -17,6 +17,7 @@ const (
 
 // SuperResolutionOptions is the command-facing request shape for video-super-resolution.
 type SuperResolutionOptions struct {
+	Source           string
 	VideoPath        string
 	ToolVersion      string
 	OutputResolution string
@@ -24,6 +25,7 @@ type SuperResolutionOptions struct {
 
 // EraseSubtitleOptions is the command-facing request shape for erase-video-subtitle.
 type EraseSubtitleOptions struct {
+	Source    string
 	VideoPath string
 }
 
@@ -43,7 +45,7 @@ func RunSuperResolution(ctx context.Context, opts *SuperResolutionOptions, runne
 	if err != nil {
 		return nil, err
 	}
-	return common.SubmitRun(ctx, "video-super-resolution", buildSuperResolutionSubmitRunBody(opts, assetID), runner)
+	return common.SubmitRun(ctx, "video-super-resolution", common.WithSubmitRunSource(buildSuperResolutionSubmitRunBody(opts, assetID), opts.Source), runner)
 }
 
 // RunEraseSubtitle uploads one video and submits a subtitle-erasing run.
@@ -59,7 +61,7 @@ func RunEraseSubtitle(ctx context.Context, opts *EraseSubtitleOptions, runner *c
 	if err != nil {
 		return nil, err
 	}
-	return common.SubmitRun(ctx, "erase-video-subtitle", buildEraseSubtitleSubmitRunBody(assetID), runner)
+	return common.SubmitRun(ctx, "erase-video-subtitle", common.WithSubmitRunSource(buildEraseSubtitleSubmitRunBody(assetID), opts.Source), runner)
 }
 
 // ValidateSuperResolutionOptions validates only command shape; semantic enums remain service-owned.

package/package.json

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

package/skills/short-drama/SKILL.md

@@ -21,6 +21,10 @@ metadata:
 
 短剧场景面向剧情、人物、分集与画面化叙事创作，用户的原始需求通过 `--message` 发送给后端 Agent。后端 Agent 负责理解任务、编排流程和生成内容；用户侧 Agent 负责提交任务、并行查询进展与产物、主动下载重要资产并展示结果。
 
+## 宿主来源统计
+
+调用 `short-drama +submit-run` 时，宿主 Agent 根据可信的实际运行环境静默附加可选 `--source`：豆包办公为 `doubao_office`，WorkBuddy 为 `workbuddy`，Codex 为 `codex`；其它已知宿主使用真实、稳定的产品标识。不附带版本、会话 ID、用户信息或 prompt，不从用户创作内容猜测来源，不向用户询问或增加确认。来源不明时省略；仅用于统计，不影响实际工具效果，不改写 `--message`。上传、查询和下载命令不附加此参数。旧版 CLI 以 `--help` 为准，不支持时省略，不因统计字段阻塞任务或重复提交。
+
 ## 功能
 
 1. **提交短剧 Run 任务** - 创建新会话或向已有会话发送短剧创作需求。

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

@@ -27,6 +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) |
 | 生成视频，使用图/视频/音频参考，首尾帧生视频 | `generate-video` | [生视频](commands/generate-video.md) |
 | 提升已有视频分辨率、视频超分 | `video-super-resolution` | [超分](commands/video-super-resolution.md) |
 | 去除已有视频字幕 | `erase-video-subtitle` | [擦字幕](commands/erase-video-subtitle.md) |
@@ -48,6 +49,15 @@ metadata:
 - 提交成功后立即展示真实 `web_thread_link`；未返回链接时如实说明，保留任务 ID。后续查询和下载失败不能触发重复生成。
 - 每个最终图片/视频都通过宿主文件交付或媒体渲染能力展示为真实附件或可预览媒体。URL、路径列表仅作补充；详细完成标准见共用交付流程。
 
+## 宿主来源统计
+
+调用 `generate-image`、`generate-video`、`video-super-resolution`、`erase-video-subtitle` 时，由宿主 Agent 根据实际运行环境静默附加可选 `--source`，仅用于来源统计，不影响创作参数或工具效果。
+
+- 使用稳定的宿主标识：豆包办公填 `doubao_office`，WorkBuddy 填 `workbuddy`，Codex 填 `codex`；其它已知宿主使用其真实、稳定的产品标识，不附带版本、会话 ID、用户信息或 prompt。
+- 从宿主提供的可信环境信息判断；不能因用户在创作内容中提到某个平台就认定它是来源，也不要把后端 Agent 名当作宿主来源。
+- 不向用户询问、不增加确认步骤，不为此改写 prompt。无法确认来源时直接省略；不传或空值均不阻塞提交。
+- 来源只随本次提交发送，不加入上传、查询、下载或 Canvas 命令。使用已有旧版 CLI 时先按 `--help` 确认是否支持；不支持则省略，不因统计字段中断任务或在未知提交结果时重提。
+
 ## 按需参考的完整场景
 
 命令文档含最小调用示例；需要了解从需求到交付的组合过程时，再读对应场景：

package/skills/xyq-nest-skill/commands/erase-video-subtitle.md

@@ -11,3 +11,5 @@ pippit-tool-cli erase-video-subtitle --video "/path/to/source.mp4"
 成功返回 `thread_id`、`run_id`、`web_thread_link`，继续 [异步结果与媒体交付](../workflows/async-delivery.md)。失败时报告原因，不把其他生成命令当作字幕处理的自动降级方案。
 
 用户还明确要求超分时，参考 [擦字幕后超分](../examples/video-process-chain.md)，用第一步下载得到的实际视频路径衔接第二步。
+
+`--source` 是可选来源统计参数，由宿主 Agent 根据真实环境静默填写（如 `doubao_office`、`workbuddy`、`codex`）；来源不明时省略，不询问用户，不改变 prompt 或创作参数。详见 [宿主来源统计](../SKILL.md#宿主来源统计)。

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

@@ -30,3 +30,5 @@ pippit-tool-cli generate-image --prompt "用户原始描述" --model IMAGE_MODEL
 ## 返回与处理
 
 成功返回 JSON 中的 `thread_id`、`run_id`、`web_thread_link`；随后执行 [异步结果与媒体交付](../workflows/async-delivery.md)。参数错误、上传失败或服务端拒绝时停止并说明原因，不切换模型或重新提交。仅在已明确失败、问题已修正且原授权仍适用时重试；提交结果不确定时避免重复收费。
+
+`--source` 是可选来源统计参数，由宿主 Agent 根据真实环境静默填写（如 `doubao_office`、`workbuddy`、`codex`）；来源不明时省略，不询问用户，不改变 prompt 或创作参数。详见 [宿主来源统计](../SKILL.md#宿主来源统计)。

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

@@ -7,27 +7,51 @@
 | 参数 | 必填 | 规则 |
 | --- | --- | --- |
 | `--prompt` | 是 | 用户原始描述，不能全为空白 |
-| `--model` | 否 | 用户指定的模型；未提供时省略，由服务端处理默认配置 |
+| `--model` | 是 | 用户指定的准确模型枚举；未明确模型时先确认，不猜测 |
 | `--image` | 否 | 本地图片路径，重复参数 |
 | `--video` | 否 | 本地参考视频路径，重复参数 |
 | `--audio` | 否 | 本地 `.mp3/.wav` 音频路径，重复参数 |
-| `--duration` | 否 | 整数秒；用户只给时长范围时先确认具体秒数 |
-| `--ratio` | 否 | 比例字符串，如 `9:16`、`16:9`、`3:4`、`4:3`；不转换为生图枚举 |
-| `--resolution` | 否 | 用户指定值，如 `720p`、`1080p` |
+| `--duration` | 按模型 | 整数秒；MiniMax、Wan、HappyHorse 可省略由服务端补齐默认值，其他模型需明确提供；用户只给时长范围时先确认具体秒数 |
+| `--ratio` | 按模式 | 比例字符串，不转换为生图枚举；MiniMax、Wan、HappyHorse 可省略使用服务端配置默认值；其他模型需明确提供 |
+| `--resolution` | 按模型 | `Seedance_2.0_mini`、`Seedance_2.0_mini_lite` 可省略，服务端默认 `720p`；MiniMax、Wan、HappyHorse 可省略使用服务端配置默认值；其他模型需明确提供 |
 | `--generate-type` | 否 | 首尾帧任务传 `1`；其他显式值交服务端处理 |
 
-普通用户模型为 `Seedance_2.0_mini_lite`；VIP 模型包括 `seedance2.0_vision`、`seedance2.0_fast_vision`、`Seedance_2.0_mini`、`Seedance_2.5`。该列表仅用于选择提示，以当前帮助和服务端为准，不自行新增模型或分辨率组合校验。
+当前支持的模型以 `pippit-tool-cli model list` 为准，完整参数配置用 `pippit-tool-cli model describe MODEL_KEY` 查询；缓存有效期为 5 分钟，需要最新结果时加 `--refresh`。详情见 [模型发现](model.md)。CLI 不自行维护模型白名单或分辨率组合校验。
 
 本地图片支持 `.jpg/.jpeg/.png/.gif/.bmp/.webp/.svg`；视频支持 `.mp4/.avi/.mov/.wmv/.flv/.webm/.mkv/.m4v`。CLI 内部上传参考素材。
 
+## 模型与模式
+
+先从模型列表取得准确 key，再查看配置中的分辨率、时长、比例和创作模式。配置会随服务端调整，本页示例不作为可用模型或参数范围清单。
+
+MiniMax、Wan、HappyHorse 可省略分辨率、时长、比例，由服务端配置补默认值。MiniMax 的兼容输入 `720p` 会映射到 `768p`，Wan/HappyHorse 的 `720p` 保持不变。Max 首尾帧模式会按素材采用自适应比例。素材可用组合以当前配置和服务端校验为准，CLI 不限制素材数量。
+
+```bash
+pippit-tool-cli model list
+pippit-tool-cli model describe MiniMax-H3
+pippit-tool-cli generate-video --prompt "用户原始描述" --model MiniMax-H3 --ratio 16:9
+```
+
+模型查询失败时提示重试，不从本文示例推定模型仍然可用，不自行替换用户指定的模型。Wan 同样必须有提示词；文件和网页链接输入不在本命令范围内。
+
 ## 最小调用
 
+`Seedance_2.0_mini` 和 `Seedance_2.0_mini_lite` 可以省略分辨率，CLI 不补值，交由服务端默认使用 `720p`：
+
+```bash
+pippit-tool-cli generate-video --prompt "用户原始描述" --model Seedance_2.0_mini --duration 5 --ratio 16:9
+```
+
+`seedance2.0_vision` 仍需指定分辨率：
+
 ```bash
-pippit-tool-cli generate-video --prompt "用户原始描述"
+pippit-tool-cli generate-video --prompt "用户原始描述" --model seedance2.0_vision --duration 5 --ratio 16:9 --resolution 720p
 ```
 
-首尾帧场景：明确两张图片的角色，按首帧、尾帧顺序传两次 `--image`，固定传 `--generate-type 1`。缺少图片、角色不清或无法确定原始描述时先询问。完整示例见 [首尾帧生视频](../examples/first-last-frame.md)。
+首尾帧场景：明确两张图片的角色，按首帧、尾帧顺序传两次 `--image`，固定传 `--generate-type 1`。MiniMax 只给首帧时也可传一张图片，仍需 `--generate-type 1`。缺少图片、角色不清或无法确定原始描述时先询问。完整示例见 [首尾帧生视频](../examples/first-last-frame.md)。
 
 ## 返回与处理
 
 成功返回 `thread_id`、`run_id`、`web_thread_link`，继续 [异步结果与媒体交付](../workflows/async-delivery.md)。素材、权限或参数失败时说明原因，不自动降低用户指定的模型、分辨率或删减素材。无法确认提交是否成功时，不重复生成。
+
+`--source` 是可选来源统计参数，由宿主 Agent 根据真实环境静默填写（如 `doubao_office`、`workbuddy`、`codex`）；来源不明时省略，不询问用户，不改变 prompt 或创作参数。详见 [宿主来源统计](../SKILL.md#宿主来源统计)。

package/skills/xyq-nest-skill/commands/model.md

@@ -0,0 +1,59 @@
+# model：发现可用视频模型
+
+需要有效登录或 `XYQ_ACCESS_KEY`。生成前可查询当前账号可用的模型及参数配置；目前只支持视频模型。
+
+```bash
+# 全部可见视频模型
+pippit-tool-cli model list
+
+# 按 key 或展示名检索；search 是 list 的别名
+pippit-tool-cli model search MiniMax --type video
+
+# 按准确 key 查看参数详情；两种写法等价
+pippit-tool-cli model describe MiniMax-H3
+pippit-tool-cli model MiniMax-H3
+
+# 强制重新查询服务端
+pippit-tool-cli model list --refresh
+pippit-tool-cli model describe MiniMax-H3 --refresh
+```
+
+`list` 输出 `models`，每项包含 `key`、`name`、`kind`、`is_default`。关键词与 key 完全一致时优先返回该项，否则按 key / name 不区分大小写检索。`describe` 只接受准确 key，输出整理后的 `model` 参数详情；不知道 key 时先查列表，不用展示名猜枚举。
+
+两种输出均包含 `scene`、`cached`、`fetched_at`、`expires_at`。合法空列表输出 `models: []`，表示当前没有可见模型。
+
+## 缓存与失败处理
+
+成功结果在系统用户缓存目录的 `pippit-cli/models/` 下保留 5 分钟，命中不会延长有效期；按凭证指纹、API 地址、接口、场景及 CLI 版本隔离。缓存不保存 AK 原文。切换凭证或退出登录后，不读取先前凭证的缓存。
+
+`--refresh` 跳过缓存重新查询。缓存过期、损坏或时间戳异常时重新请求；服务端查询失败返回非零退出状态并提示重试，不返回过期缓存或静态模型列表，也不缓存失败响应。可稍后重试原命令或加 `--refresh`；若是登录错误，先恢复登录。单次查询最长 30 秒，不自动重复请求。
+
+缓存写入失败不丢弃本次服务端成功结果，stderr 会提示；stdout 仍为 JSON。
+
+## 参数配置的使用
+
+`describe` 将配置整理成可直接选择生成参数的结构。以下为示例片段，实际值以查询为准：
+
+```json
+{
+  "key": "MiniMax-H3",
+  "ratio": {
+    "options": ["adaptive", "16:9", "21:9", "9:16", "4:3", "3:4", "1:1"],
+    "default": "9:16"
+  },
+  "resolution": {"options": ["768p", "2k"], "default": "768p"},
+  "duration": {"min": 4, "max": 15, "step": 1, "default": 10, "unit": "seconds"}
+}
+```
+
+- `ratio.options/default` 按 IDL 转为字符串，可直接用于 `--ratio`。支持全部有对应生成参数的已有比例枚举；`0` 为 `adaptive`。自定义比例 `1` 没有对应的 CLI 尺寸参数，和未知枚举一样跳过；未知默认值不输出，不猜测替代值。
+- `resolution.options` 去除 disabled 选项，默认值必须在有效选项内。
+- `Seedance_2.0_mini`、`Seedance_2.0_mini_lite` 的生成请求可以省略 `--resolution`，服务端默认 `720p`。查询未返回分辨率维度时，不因此要求用户补填，也不在查询结果中伪造选项。
+- `duration` 来自参数维度：范围输出 `min/max/step`，选项输出数字 `options`，均以秒为单位，不把选项枚举号当秒数。若只下发旧 `supported_duration_list`，暂保留该原始字段并明确提示不能直接用于 `--duration`。
+- `material_limits` 保留数量字段；大小字段使用 `max_image_size_bytes`，视频时长字段使用 `min_video_duration_ms/max_video_duration_ms/max_total_video_duration_ms`。字段未返回与值为 `0` 保持区别。
+- `creation_modes` 保留 `enabled`、素材校验等服务端策略，并为文本/参考/首尾帧模式标注对应 `generate_type`。`smart` 比例策略显示 `adaptive`；其他可识别模式继承模型比例。MiniMax 的文本模式排除 `adaptive`，纯文生视频使用固定比例。原始模式 key 不是生成参数，未标注 `generate_type` 的模式不代表 CLI 已接入。
+- 条件维度的 `active_when_any`、参数组合约束及其他未转换字段保留；模型级选项不保证任意组合都可用。配置不一致时通过 `warnings` 提示刷新，未知比例枚举直接跳过。
+
+内部 `config_key` 不输出。缓存仍保存服务端原始配置，列表/详情展示时转换，不修改生成请求、不新增本地模型准入限制。生成参数格式见 [生视频命令](generate-video.md)。
+
+查询结果反映当前账号的服务端可见配置及 Skill 模型白名单；最终提交仍由服务端判断权限、参数、余额等条件。缓存最多滞后 5 分钟，需要最新值时使用 `--refresh`。生成命令不会自动请求模型列表或凭缓存拦截生成。

package/skills/xyq-nest-skill/commands/video-super-resolution.md

@@ -15,3 +15,5 @@ pippit-tool-cli video-super-resolution --video "/path/to/source.mp4" --output-re
 ```
 
 示例以用户要求 1080p 为前提。成功返回 `thread_id`、`run_id`、`web_thread_link`，按 [异步结果与媒体交付](../workflows/async-delivery.md) 查询、下载并交付。输入失败或服务端拒绝时停止，不擅自切换版本或分辨率。
+
+`--source` 是可选来源统计参数，由宿主 Agent 根据真实环境静默填写（如 `doubao_office`、`workbuddy`、`codex`）；来源不明时省略，不询问用户，不改变 prompt 或创作参数。详见 [宿主来源统计](../SKILL.md#宿主来源统计)。