@pippit-dev/cli 0.0.5 → 0.0.7

package/README.md

@@ -13,7 +13,7 @@ export XYQ_ACCESS_KEY="<access-key>"
 pippit-cli short-drama +submit-run --message "写一个赛博朋克短剧开头"
 pippit-cli short-drama +upload-file --path ./story.md
 pippit-cli short-drama +get-thread --thread-id thread_123 --run-id run_456 --after-seq 0
-pippit-cli short-drama +download-result --output-dir ./thread_123/results/result.mp4 --url URL
+pippit-cli short-drama +download-result --output-path ./thread_123/results/result.mp4 --url URL
 ```
 
 NPM package names must be lowercase, so the publishable package name is
@@ -26,7 +26,7 @@ export XYQ_ACCESS_KEY="<access-key>"
 go run . short-drama +submit-run --message "写一个赛博朋克短剧开头"
 go run . short-drama +upload-file --path ./story.md
 go run . short-drama +get-thread --thread-id thread_123 --run-id run_456 --after-seq 0
-go run . short-drama +download-result --output-dir ./thread_123/results/result.mp4 --url URL
+go run . short-drama +download-result --output-path ./thread_123/results/result.mp4 --url URL
 ```
 
 `+submit-run` calls `/api/biz/v1/skill/submit_run` and prints `thread_id`,
@@ -34,7 +34,7 @@ go run . short-drama +download-result --output-dir ./thread_123/results/result.m
 `+get-thread` calls
 `/api/biz/v1/skill/get_thread` and prints extracted `messages`.
 `+download-result` downloads the result URL to
-the `--output-dir` file path. `+upload-file` is still mocked while
+the `--output-path` file path. `+upload-file` is still mocked while
 its real service contract is wired.
 
 ## HTTP Client

package/checksums.txt

@@ -1,6 +1,6 @@
-8afee21204eb10b435b6ae93762af02e7a7d8c2fb2e4a7f0b613dc7b56d23d99  pippit-cli-0.0.5-darwin-amd64.tar.gz
-dfe02e27e30eaffe5ef7be9f3b914684a87ca72b809e635ff8c3c9f599f0aaa7  pippit-cli-0.0.5-darwin-arm64.tar.gz
-0b73c06d98bf696cc3bae73381c50185c0c63a9db707a4f81adba4088452cbef  pippit-cli-0.0.5-linux-amd64.tar.gz
-de2f89ef9124b64b5cee3bfa88cb7c0f110faefeed04517922861ccd42d641b2  pippit-cli-0.0.5-linux-arm64.tar.gz
-ab4a79448c29be1f129abc8f82007fb25dd636e6b9f25d13f7085826f86f48ef  pippit-cli-0.0.5-windows-amd64.zip
-8599eb109ad4b5a1e844e5475e02fc2ddd4d91057cf94f164570ac632cbaa43a  pippit-cli-0.0.5-windows-arm64.zip
+b2cba39200b8114a21e496bca83d677fe2b478b23e374666a0a8cab2ad2e457e  pippit-cli-0.0.7-darwin-amd64.tar.gz
+44be0c9cb8dc98edec7519a704290c06dcfa966360c48bcad709f1e53d5a80d0  pippit-cli-0.0.7-darwin-arm64.tar.gz
+175816681f3affd9eb20900c6e0cfbc035ec1f24eaf06dc6c41686b6cdea5ec7  pippit-cli-0.0.7-linux-amd64.tar.gz
+ebf0c0e9b4b2bbed872acce3f9cf07dd0b21c52ab7c11c62d6778f820c0479fa  pippit-cli-0.0.7-linux-arm64.tar.gz
+573c22cdbd208e9a9a541ae4f67cd922e63129995716d7b92e665d828cec8f49  pippit-cli-0.0.7-windows-amd64.zip
+996d18e5ca27083ee8e9b200f39571c53ff8829f7fdc85c8ba7631778e7f3178  pippit-cli-0.0.7-windows-arm64.zip

package/cmd/short_drama/short_drama.go

@@ -96,9 +96,9 @@ func newShortDramaDownloadResultCommand(stdout, stderr io.Writer, runner *common
 		Short: "Download a generated result URL",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
-			opts.OutputDir = strings.TrimSpace(opts.OutputDir)
-			if opts.OutputDir == "" {
-				return fmt.Errorf("--output-dir is required")
+			opts.OutputPath = strings.TrimSpace(opts.OutputPath)
+			if opts.OutputPath == "" {
+				return fmt.Errorf("--output-path is required")
 			}
 			opts.URL = strings.TrimSpace(opts.URL)
 			if opts.URL == "" {
@@ -118,7 +118,7 @@ func newShortDramaDownloadResultCommand(stdout, stderr io.Writer, runner *common
 	cmd.SetOut(stdout)
 	cmd.SetErr(stderr)
 	cmd.Flags().StringVar(&opts.URL, "url", "", "URL to download")
-	cmd.Flags().StringVar(&opts.OutputDir, "output-dir", "", "output file path")
+	cmd.Flags().StringVar(&opts.OutputPath, "output-path", "", "local output file path")
 	cmd.Flags().IntVar(&opts.Workers, "workers", 5, "parallel download workers")
 	return cmd
 }
@@ -164,8 +164,8 @@ func newShortDramaListThreadFileCommand(stdout, stderr io.Writer, runner *common
 			if opts.ThreadID == "" {
 				return fmt.Errorf("--thread-id is required")
 			}
-			if opts.PageSize <= 0 || opts.PageSize > 100 {
-				return fmt.Errorf("--page-size must be between 1 and 100")
+			if opts.PageSize <= 0 || opts.PageSize > 1000 {
+				return fmt.Errorf("--page-size must be between 1 and 1000")
 			}
 			if opts.PageNum <= 0 {
 				return fmt.Errorf("--page-num must be greater than 0")
@@ -182,7 +182,7 @@ func newShortDramaListThreadFileCommand(stdout, stderr io.Writer, runner *common
 	cmd.SetErr(stderr)
 	cmd.Flags().StringVar(&opts.ThreadID, "thread-id", "", "thread ID to list files for")
 	cmd.Flags().IntVar(&opts.PageNum, "page-num", 1, "page number (1-based)")
-	cmd.Flags().IntVar(&opts.PageSize, "page-size", 100, "number of files per page (between 1 and 100)")
+	cmd.Flags().IntVar(&opts.PageSize, "page-size", 1000, "number of files per page (between 1 and 1000)")
 	return cmd
 }
 

package/cmd/short_drama_test.go

@@ -181,7 +181,7 @@ func TestShortDramaDownloadResult(t *testing.T) {
 	outputPath := filepath.Join("results", "cover.jpeg")
 	root.SetArgs([]string{
 		"short-drama", "+download-result",
-		"--output-dir", outputPath,
+		"--output-path", outputPath,
 		"--workers", "2",
 		"--url", server.URL + "/image?filename=ignored.jpeg",
 	})
@@ -191,11 +191,11 @@ func TestShortDramaDownloadResult(t *testing.T) {
 	}
 
 	got := decodeJSON(t, stdout.Bytes())
-	if got["output_dir"] != outputPath {
-		t.Fatalf("output_dir = %v, want %s", got["output_dir"], outputPath)
+	if got["output_path"] != outputPath {
+		t.Fatalf("output_path = %v, want %s", got["output_path"], outputPath)
 	}
-	if got["total"] != float64(1) {
-		t.Fatalf("total = %v, want 1", got["total"])
+	if _, ok := got["total"]; ok {
+		t.Fatalf("total should not be returned: %#v", got)
 	}
 	downloaded, ok := got["downloaded"].([]any)
 	if !ok || len(downloaded) != 1 {
@@ -233,7 +233,7 @@ func TestShortDramaDownloadResultSkipsExistingFile(t *testing.T) {
 	root := NewRootCommand(&stdout, &stderr)
 	root.SetArgs([]string{
 		"short-drama", "+download-result",
-		"--output-dir", outputPath,
+		"--output-path", outputPath,
 		"--url", server.URL + "/image",
 	})
 
@@ -245,11 +245,11 @@ func TestShortDramaDownloadResultSkipsExistingFile(t *testing.T) {
 	}
 
 	got := decodeJSON(t, stdout.Bytes())
-	if got["output_dir"] != outputPath {
-		t.Fatalf("output_dir = %v, want %s", got["output_dir"], outputPath)
+	if got["output_path"] != outputPath {
+		t.Fatalf("output_path = %v, want %s", got["output_path"], outputPath)
 	}
-	if got["total"] != float64(0) {
-		t.Fatalf("total = %v, want 0", got["total"])
+	if _, ok := got["total"]; ok {
+		t.Fatalf("total should not be returned: %#v", got)
 	}
 	alreadyExist, ok := got["already_exist"].([]any)
 	if !ok || len(alreadyExist) != 1 || alreadyExist[0] != outputPath {
@@ -258,7 +258,49 @@ func TestShortDramaDownloadResultSkipsExistingFile(t *testing.T) {
 	assertFileContent(t, outputPath, "existing-data")
 }
 
-func TestShortDramaDownloadResultRequiresOutputDir(t *testing.T) {
+func TestShortDramaDownloadResultSkipsMetaJSON(t *testing.T) {
+	serverCalled := false
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		serverCalled = true
+		t.Fatal("server should not receive request for meta.json")
+	}))
+	defer server.Close()
+
+	chdirTemp(t)
+	outputPath := filepath.Join("results", "meta.json")
+
+	var stdout, stderr bytes.Buffer
+	root := NewRootCommand(&stdout, &stderr)
+	root.SetArgs([]string{
+		"short-drama", "+download-result",
+		"--output-path", outputPath,
+		"--url", server.URL + "/meta.json",
+	})
+
+	if err := root.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v, stderr = %s", err, stderr.String())
+	}
+	if serverCalled {
+		t.Fatal("server was called, want meta.json to skip download")
+	}
+	if _, err := os.Stat(outputPath); !os.IsNotExist(err) {
+		t.Fatalf("meta.json stat err = %v, want file to be absent", err)
+	}
+
+	got := decodeJSON(t, stdout.Bytes())
+	if got["output_path"] != outputPath {
+		t.Fatalf("output_path = %v, want %s", got["output_path"], outputPath)
+	}
+	if _, ok := got["total"]; ok {
+		t.Fatalf("total should not be returned: %#v", got)
+	}
+	skipped, ok := got["skipped"].([]any)
+	if !ok || len(skipped) != 1 || skipped[0] != outputPath {
+		t.Fatalf("skipped = %#v, want meta.json output path", got["skipped"])
+	}
+}
+
+func TestShortDramaDownloadResultRequiresOutputPath(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
 	root.SetArgs([]string{"short-drama", "+download-result", "--url", "https://example.com/image.png"})
@@ -267,15 +309,33 @@ func TestShortDramaDownloadResultRequiresOutputDir(t *testing.T) {
 	if err == nil {
 		t.Fatal("Execute() error = nil, want validation error")
 	}
-	if !strings.Contains(err.Error(), "--output-dir is required") {
-		t.Fatalf("error = %q, want output-dir validation", err)
+	if !strings.Contains(err.Error(), "--output-path is required") {
+		t.Fatalf("error = %q, want output-path validation", err)
+	}
+}
+
+func TestShortDramaDownloadResultRejectsOutputDirFlag(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	root := NewRootCommand(&stdout, &stderr)
+	root.SetArgs([]string{
+		"short-drama", "+download-result",
+		"--output-dir", filepath.Join("results", "image.png"),
+		"--url", "https://example.com/image.png",
+	})
+
+	err := root.Execute()
+	if err == nil {
+		t.Fatal("Execute() error = nil, want unknown flag error")
+	}
+	if !strings.Contains(err.Error(), "unknown flag: --output-dir") {
+		t.Fatalf("error = %q, want output-dir rejection", err)
 	}
 }
 
 func TestShortDramaDownloadResultRequiresURL(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
-	root.SetArgs([]string{"short-drama", "+download-result", "--output-dir", filepath.Join("results", "image.png")})
+	root.SetArgs([]string{"short-drama", "+download-result", "--output-path", filepath.Join("results", "image.png")})
 
 	err := root.Execute()
 	if err == nil {
@@ -289,7 +349,7 @@ func TestShortDramaDownloadResultRequiresURL(t *testing.T) {
 func TestShortDramaDownloadResultRejectsInvalidScheme(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
-	root.SetArgs([]string{"short-drama", "+download-result", "--output-dir", filepath.Join("results", "image.png"), "--url", "file:///etc/passwd"})
+	root.SetArgs([]string{"short-drama", "+download-result", "--output-path", filepath.Join("results", "image.png"), "--url", "file:///etc/passwd"})
 
 	err := root.Execute()
 	if err == nil {
@@ -311,7 +371,7 @@ func TestShortDramaDownloadResultAllFailed(t *testing.T) {
 	root := NewRootCommand(&stdout, &stderr)
 	root.SetArgs([]string{
 		"short-drama", "+download-result",
-		"--output-dir", filepath.Join("results", "missing.png"),
+		"--output-path", filepath.Join("results", "missing.png"),
 		"--url", server.URL + "/notfound",
 	})
 
@@ -337,7 +397,7 @@ func TestShortDramaDownloadResultOutputPath(t *testing.T) {
 	outputPath := filepath.Join("custom", "nested", "cover.png")
 	root.SetArgs([]string{
 		"short-drama", "+download-result",
-		"--output-dir", outputPath,
+		"--output-path", outputPath,
 		"--url", server.URL + "/image.png",
 	})
 
@@ -346,8 +406,8 @@ func TestShortDramaDownloadResultOutputPath(t *testing.T) {
 	}
 
 	got := decodeJSON(t, stdout.Bytes())
-	if got["output_dir"] != outputPath {
-		t.Fatalf("output_dir = %v, want %s", got["output_dir"], outputPath)
+	if got["output_path"] != outputPath {
+		t.Fatalf("output_path = %v, want %s", got["output_path"], outputPath)
 	}
 	assertFileContent(t, outputPath, "image-data")
 }
@@ -497,6 +557,10 @@ func TestShortDramaListThreadFile(t *testing.T) {
 	if got["total"] != float64(1) {
 		t.Fatalf("total = %v, want 1", got["total"])
 	}
+	wantMessage := "<system-remind>\n- total is below 1000; continue querying with current --page-num 2\n</system-remind>"
+	if got["message"] != wantMessage {
+		t.Fatalf("message = %v, want current page hint", got["message"])
+	}
 	files, ok := got["files"].([]any)
 	if !ok || len(files) != 1 {
 		t.Fatalf("files = %#v, want one file", got["files"])
@@ -517,6 +581,35 @@ func TestShortDramaListThreadFile(t *testing.T) {
 	}
 }
 
+func TestShortDramaListThreadFileMessageWhenPageFull(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !strings.Contains(r.URL.Path, "list_thread_file") {
+			t.Fatalf("path = %s, want list_thread_file path", r.URL.Path)
+		}
+		_, _ = w.Write([]byte(`{"ret":"0","errmsg":"","data":{"total":1000,"files":[]}}`))
+	}))
+	defer server.Close()
+
+	var stdout, stderr bytes.Buffer
+	root := newTestRootCommand(t, &stdout, &stderr, server.URL)
+	root.SetArgs([]string{
+		"short-drama", "+list-thread-file",
+		"--thread-id", "thread_123",
+		"--page-num", "2",
+		"--page-size", "1000",
+	})
+
+	if err := root.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v, stderr = %s", err, stderr.String())
+	}
+
+	got := decodeJSON(t, stdout.Bytes())
+	wantMessage := "<system-remind>\n- total reached 1000; query the next page with --page-num 3\n</system-remind>"
+	if got["message"] != wantMessage {
+		t.Fatalf("message = %v, want next page hint", got["message"])
+	}
+}
+
 func TestShortDramaListThreadFileRequiresThreadID(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)

package/internal/common/download_results.go

@@ -21,9 +21,9 @@ import (
 
 // DownloadResultOptions is the command-facing shape for downloading one result URL.
 type DownloadResultOptions struct {
-	URL       string `json:"url"`
-	OutputDir string `json:"output_dir"`
-	Workers   int    `json:"workers"`
+	URL        string `json:"url"`
+	OutputPath string `json:"output_path"`
+	Workers    int    `json:"workers"`
 }
 
 type DownloadResultError struct {
@@ -33,10 +33,10 @@ type DownloadResultError struct {
 
 // DownloadResultResponse is the JSON envelope printed by `pippit-cli short-drama +download-result`.
 type DownloadResultResponse struct {
-	OutputDir    string                 `json:"output_dir"`
+	OutputPath   string                 `json:"output_path"`
 	Downloaded   []string               `json:"downloaded"`
 	AlreadyExist []string               `json:"already_exist,omitempty"`
-	Total        int                    `json:"total"`
+	Skipped      []string               `json:"skipped,omitempty"`
 	Errors       []*DownloadResultError `json:"errors,omitempty"`
 }
 
@@ -64,9 +64,15 @@ func DownloadResult(ctx context.Context, opts DownloadResultOptions, runner *Run
 		return nil, fmt.Errorf("download url is required")
 	}
 
-	outputPath := strings.TrimSpace(opts.OutputDir)
+	outputPath := strings.TrimSpace(opts.OutputPath)
 	if outputPath == "" {
-		return nil, fmt.Errorf("output_dir is required")
+		return nil, fmt.Errorf("output_path is required")
+	}
+	if shouldSkipDownload(outputPath) {
+		return &DownloadResultResponse{
+			OutputPath: outputPath,
+			Skipped:    []string{outputPath},
+		}, nil
 	}
 	// check if the output path exists and is a file
 	if info, err := os.Stat(outputPath); err == nil {
@@ -74,9 +80,8 @@ func DownloadResult(ctx context.Context, opts DownloadResultOptions, runner *Run
 			return nil, fmt.Errorf("output path %q is a directory", outputPath)
 		}
 		return &DownloadResultResponse{
-			OutputDir:    outputPath,
+			OutputPath:   outputPath,
 			AlreadyExist: []string{outputPath},
-			Total:        0,
 		}, nil
 	} else if !os.IsNotExist(err) {
 		return nil, fmt.Errorf("stat output path: %w", err)
@@ -159,9 +164,8 @@ func DownloadResult(ctx context.Context, opts DownloadResultOptions, runner *Run
 	})
 
 	result := &DownloadResultResponse{
-		OutputDir:  outputPath,
+		OutputPath: outputPath,
 		Downloaded: downloaded,
-		Total:      len(downloaded),
 		Errors:     errorList,
 	}
 	if len(downloaded) == 0 && len(errorList) > 0 {
@@ -170,6 +174,10 @@ func DownloadResult(ctx context.Context, opts DownloadResultOptions, runner *Run
 	return result, nil
 }
 
+func shouldSkipDownload(outputPath string) bool {
+	return filepath.Base(outputPath) == "meta.json"
+}
+
 func downloadFileWithRetry(ctx context.Context, client Client, rawURL string, targetPath string) error {
 	var lastErr error
 	for attempt := 0; attempt <= maxDownloadRetries; attempt++ {

package/internal/common/list_thread_file.go

@@ -24,8 +24,9 @@ type ThreadFile struct {
 
 // ListThreadFileResult is the JSON envelope printed by `pippit-cli short-drama +list-thread-file`.
 type ListThreadFileResult struct {
-	Files []*ThreadFile `json:"files"`
-	Total int64         `json:"total"`
+	Files   []*ThreadFile `json:"files"`
+	Total   int64         `json:"total"`
+	Message string        `json:"message"`
 }
 
 type listThreadFileResponse struct {
@@ -82,11 +83,24 @@ func ListThreadFile(ctx context.Context, opts *ListThreadFileOptions, runner *Ru
 	}
 
 	return &ListThreadFileResult{
-		Files: files,
-		Total: resp.Data.Total,
+		Files:   files,
+		Total:   resp.Data.Total,
+		Message: listThreadFileMessage(resp.Data.Total, opts.PageNum),
 	}, nil
 }
 
+func listThreadFileMessage(total int64, pageNum int) string {
+	start, end := "<system-remind>", "</system-remind>"
+	if pageNum <= 0 {
+		pageNum = 1
+	}
+	var message string
+	if total >= 1000 {
+		message = fmt.Sprintf("total reached 1000; query the next page with --page-num %d", pageNum+1)
+	}
+	return fmt.Sprintf("%s\n- %s\n%s", start, message, end)
+}
+
 func threadFilePath(threadID string, filePath string) string {
 	parts := []string{strings.TrimSpace(threadID)}
 	trimmedFilePath := strings.Trim(strings.TrimSpace(filePath), `/\`)

package/package.json

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

package/skills/short-drama/SKILL.md

@@ -17,17 +17,19 @@ metadata:
 
 # 小云雀短剧创作
 
-通过 `pippit-cli short-drama` 命令提交短剧创作任务、上传参考文件，并查询任务进展，获取会话产物文件。
+通过 `pippit-cli short-drama` 命令提交短剧创作任务、上传参考文件，并行查询任务进展和会话产物文件，及时把重要资产下载到用户本地。
 
-短剧场景面向剧情、人物、分集与画面化叙事创作，用户的原始需求通过 `--message` 发送给后端 Agent。后端 Agent 负责理解任务、编排流程和生成内容；用户侧 Agent 只负责提交任务、查询进展和展示结果。
+短剧场景面向剧情、人物、分集与画面化叙事创作，用户的原始需求通过 `--message` 发送给后端 Agent。后端 Agent 负责理解任务、编排流程和生成内容；用户侧 Agent 负责提交任务、并行查询进展与产物、主动下载重要资产并展示结果。
 
 ## 功能
 
 1. **提交短剧 Run 任务** - 创建新会话或向已有会话发送短剧创作需求。
 2. **查询会话进展** - 根据 `thread_id`、`run_id`、`after_seq` 拉取短剧任务消息列表。
 3. **上传文件** - 上传短剧相关参考文件，得到文件 ID，供后续任务引用。
-4. **获取会话文件** - 根据 `thread_id` 拉取会话文件列表，得到 `file_path`、`file_name`、`download_url`。
-5. **下载文件资源** - 使用文件列表中的 `download_url` 下载资源，并按 `file_path` 写入用户本地目录。
+4. **获取会话文件** - 根据 `thread_id` 拉取会话文件列表，得到 `file_path`、`download_url`。这和查询会话进展同等重要。
+5. **下载重要资产** - 使用文件列表中的 `download_url` 下载资源，并按 `file_path` 写入用户本地目标文件路径。
+
+重要资产包括但不限于：剧本设计、场景设计、场景图、人物角色设计、人物图、分集草稿、故事板、最终视频产物。只要 `+list-thread-file` 返回了这些资产的 `download_url`，就要及时调用下载工具落盘，不要只展示文件元信息。
 
 ## 前置要求
 
@@ -73,7 +75,7 @@ pippit-cli short-drama +upload-file --path /path/to/outline.md
 
 ```bash
 # 获取会话文件列表
-pippit-cli short-drama +list-thread-file --thread-id THREAD_ID --page-num 1 --page-size 100
+pippit-cli short-drama +list-thread-file --thread-id THREAD_ID --page-num 1 --page-size 1000
 ```
 
 `+list-thread-file` 返回的每个文件对象包含：
@@ -85,16 +87,16 @@ pippit-cli short-drama +list-thread-file --thread-id THREAD_ID --page-num 1 --pa
 }
 ```
 
-`+list-thread-file` 只负责获取会话文件列表，不负责下载文件。
+`+list-thread-file` 只负责获取会话文件列表，不负责下载文件，也不需要判断本地文件是否已存在。
 
 ### 5. 下载文件资源
 
 ```bash
-# 下载文件资源到指定目录
-pippit-cli short-drama +download-result --url DOWNLOAD_URL --output-dir FILE_PATH 
+# 下载文件资源到指定文件路径
+pippit-cli short-drama +download-result --url DOWNLOAD_URL --output-path FILE_PATH
 ```
 
-`+download-result` 负责把会话产生的文件，通过URL下载到 `file_path`目录中，如果目标文件已存在，跳过下载。
+`FILE_PATH` 必须直接使用 `+list-thread-file` 返回的完整 `file_path`，包含文件名，不要取父目录。`+download-result` 负责把会话产生的文件通过 URL 下载到该目标文件路径；如果目标文件已存在，跳过下载。
 
 ## 典型工作流
 
@@ -104,20 +106,25 @@ pippit-cli short-drama +download-result --url DOWNLOAD_URL --output-dir FILE_PAT
 1. pippit-cli short-drama +submit-run --message "用户的原始短剧需求"
    → 拿到 thread_id、run_id 和 web_thread_link
 2. 立即将 web_thread_link 展示给用户
-3. 并行发起：
+3. 并行发起，二者同等重要：
    a. pippit-cli short-drama +get-thread --thread-id THREAD_ID --run-id RUN_ID --after-seq SEQUENCE
-   b. pippit-cli short-drama +list-thread-file --thread-id THREAD_ID --page-num 1 --page-size 100
+   b. pippit-cli short-drama +list-thread-file --thread-id THREAD_ID --page-num PAGE_NUM --page-size 1000
 4. 检查 `get-thread` 返回的 messages：
    - 如果任务仍在进行中：展示过程消息，继续查询
    - 如果后端 Agent 提出问题：展示问题，等待用户回复
-5. 解析 `list-thread-file` 返回的 files，只获取文件元信息：
-   - 对每个文件取 file_path、file_name、download_url
-   - 按 file_path 在用户本地环境构建目录
-   - 如果在工作目录中 file_name 已存在：跳过下载
-6. 对缺失的本地文件，调用 +download-result 并行下载资源：
+5. 检查 `list-thread-file` 返回的 files：
+   - 对每个文件取 file_path、download_url
+   - 将 file_path 作为本地目标文件路径，包含文件名
+   - 有 download_url 的重要资产：加入本轮下载队列
+   - 不判断 file_path 在本地是否已存在，是否跳过由 +download-result 内部处理
+   - 如果本轮 total 达到 1000：下一轮将 PAGE_NUM 加 1，继续查询新一页文件
+6. 对重要资产，立即调用 +download-result 并行下载资源：
    - 使用第 5 步获取的 download_url 作为 --url
-   - 使用第 5 步获取的 file_path 作为 --output-dir
-7. 如用户继续追加需求，使用同一 thread_id 再次 submit-run
+   - 使用第 5 步获取的完整 file_path 作为 --output-path
+   - 剧本设计、场景设计、场景图、人物角色设计、人物图、最终视频产物都属于重要资产
+7. 查询或下载失败时，不要直接放弃；记录失败项，并在后续轮询中主动重试
+8. 只有会话进展已处理，且已发现的重要资产均已下载或明确重试失败后，才向用户汇总最终结果
+9. 如用户继续追加需求，使用同一 thread_id 再次 submit-run
 ```
 
 ### 场景 2：用户提供参考文件要求创作
@@ -127,7 +134,7 @@ pippit-cli short-drama +download-result --url DOWNLOAD_URL --output-dir FILE_PAT
    → 拿到 file_id
 2. pippit-cli short-drama +submit-run --message "用户的原始短剧需求" --asset-ids file_id
    → 拿到 thread_id、run_id 和 web_thread_link
-3. 后续同场景 1 的并行查询和文件下载流程
+3. 后续同场景 1 的并行查询、重要资产发现和文件下载流程
 ```
 
 ### 场景 3：在已有短剧会话中续写或修改
@@ -135,18 +142,30 @@ pippit-cli short-drama +download-result --url DOWNLOAD_URL --output-dir FILE_PAT
 ```
 1. pippit-cli short-drama +submit-run --message "用户的新需求" --thread-id THREAD_ID
    → 拿到新的 run_id 和 web_thread_link
-2. 继续按场景 1 展示进展、处理用户补充问题、获取新增会话文件列表，并按需下载新增文件资源
+2. 继续按场景 1 展示进展、处理用户补充问题、获取新增会话文件列表，并及时下载新增重要资产
 ```
 
 ## 轮询策略
 
 - **间隔**：每 10 秒查询一次。
 - **增量拉取**：首次使用 `--after-seq 0`，后续根据已读消息进度调整 `after-seq`。
-- **并行查询**：每次 `+submit-run` 返回 `thread_id` 后，同时发起 `+get-thread` 和 `+list-thread-file`；会话信息展示流程保持不变，`+list-thread-file` 只用于获取文件元信息。
-- **文件下载**：解析 `+list-thread-file` 的结果后，只有目标本地文件不存在时才调用 `+download-result` 下载资源。
+- **并行查询**：每次 `+submit-run` 返回 `thread_id` 后，同时发起 `+get-thread` 和 `+list-thread-file`；二者同等重要，不能只查询会话进展而忽略会话文件。
+- **文件分页**：`+list-thread-file` 使用 `--page-size 1000`。如果本轮返回的 `total` 达到 1000，下一轮使用 `--page-num` 加 1 查询新一页结果；如果未达到 1000，保持当前页继续轮询新增产物。
+- **重要资产识别**：每轮都检查 `+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` 任一调用失败时，记录失败原因和参数，在后续轮询中主动重试；重试期间继续处理其他成功返回的消息和文件。连续多轮失败后再向用户说明仍未完成的查询或下载项。
+
+## 完成标准
+
+一次短剧任务不能只以 `+get-thread` 返回完成消息作为结束条件。完成前必须同时检查：
+
+1. 已处理 `+get-thread` 返回的最新会话进展、用户确认问题和最终消息。
+2. 已用 `--page-size 1000` 调用 `+list-thread-file` 获取会话文件列表；如果本轮 `total` 达到 1000，已在后续轮询中递增 `page-num` 查询新一页。
+3. 对所有带 `download_url` 的重要资产，已调用 `+download-result` 下载到本地 `file_path`。
+4. 对查询失败或下载失败的资产，已在后续轮询中主动重试，并在最终回复中列出仍失败的文件或命令。
 
 ## 输出格式
 
@@ -204,51 +223,59 @@ pippit-cli short-drama +download-result --url DOWNLOAD_URL --output-dir FILE_PAT
       "download_url": "https://..."
     }
   ],
-  "total": 1
+  "total": 1,
+  "message": "<system-remind>\n- total reached 1000; query the next page with --page-num {page-num} + 1\n</system-remind>"
 }
 ```
 
+当 `total` 达到 1000 时，`message` 会用 `<system-remind>` 提示下一轮将 `page-num` 加 1 查询新一页。
+
 **+download-result** 返回：
 
 ```json
 {
-  "output_dir": "/path/to/output-dir",
-  "downloaded": ["/path/to/output-dir/01.md"],
-  "total": 1
+  "output_path": "./{thread-id}/{file_path}/{file_name}",
+  "downloaded": ["./{thread-id}/{file_path}/{file_name}"]
 }
 ```
 
 ## 会话文件与资源下载
 
-先用 `+list-thread-file` 获取会话文件列表，再按需用 `+download-result` 并行下载文件资源。
+先用 `+list-thread-file` 获取会话文件列表，再用 `+download-result` 并行下载重要资产。获取文件元信息不是最终目标，重要资产落盘才是核心目标。文件是否已存在由下载工具内部检查，`+list-thread-file` 阶段不要做本地存在性判断。
 
 ### 获取会话文件
 
-从 `+list-thread-file` 的 `files` 中逐个读取文件元信息：`file_path`、`download_url`。
+从 `+list-thread-file` 的 `files` 中逐个读取文件元信息：`file_path`、`file_name`、`download_url`。重点识别剧本设计、场景设计、场景图、人物角色设计、人物图、分集草稿、故事板、最终视频产物等重要资产。
 
 ```
-1. file_path在本地已存在
-   → 跳过
-2. file_path在本地不存在
+1. 有download_url的重要资产
    → 记录该file_path和URL
-   → 多个待下载的文件 → 使用 +download-result 工具并行下载文件到本地
+   → 使用 +download-result 将URL资源下载到该file_path
+2. 本轮total达到1000
+   → 下一轮page-num加1，继续查询新一页结果
+3. 本轮total未达到1000
+   → 后续轮询保持当前页，继续发现新增产物
+4. list-thread-file或download-result失败
+   → 记录失败参数和错误
+   → 后续轮询主动重试，不要直接结束任务
 ```
 
 ### 并行下载文件资源
 
-只对目标路径不存在的文件调用下载工具，可并行：
+对带 `download_url` 的重要资产调用下载工具，可并行。重要资产必须主动下载，不要等用户再次要求，也不要在调用下载工具前先检查本地文件是否存在。
 
-1. 调用 `pippit-cli short-drama +download-result --url DOWNLOAD_URL --output-dir FILE_PATH`。
-2. 下载完成后，向用户展示本地文件路径；如果某个文件下载失败，只报告该文件错误，不阻塞已成功落盘的文件展示。
+1. 调用 `pippit-cli short-drama +download-result --url DOWNLOAD_URL --output-path FILE_PATH`。
+2. 下载完成后，向用户展示本地文件路径；如果某个文件下载失败，记录失败项并在后续轮询中重试，不阻塞已成功落盘的文件展示。
 
 ## 向用户展示内容
 
 - 任务提交后：立即展示 `web_thread_link`。
 - 任务进行中：展示后端 Agent 返回的过程消息。
 - 需要用户补充信息时：原样展示后端 Agent 的问题，等待用户回复。
-- 任务完成后：展示短剧内容、分集草稿、设定说明或其他结果信息。
+- 任务完成后：展示短剧内容、分集草稿、设定说明或其他结果信息，同时检查是否有未下载的重要资产。
 - 获取会话文件后：展示或记录文件元信息，不把它当成已下载结果。
 - 文件资源下载后：展示已落盘的本地文件路径；已存在而跳过下载的文件也要标明。
+- 如果仍有重要资产下载失败：说明失败文件、失败命令和已进行的重试，不要把它描述为已完成下载。
 
 ## 核心原则：用户侧不做创作，只做传话
 
@@ -275,6 +302,6 @@ pippit-cli short-drama +download-result --url DOWNLOAD_URL --output-dir FILE_PAT
 - 查询进展时优先使用 `+submit-run` 返回的 `thread_id` 和 `run_id`。
 - `--after-seq` 用于增量拉取消息，首次查询可设置为 `0`。
 - `+upload-file` 当前用于短剧场景文件上传链路，上传后将返回可传给 `+submit-run` 的文件 ID。
-- `+list-thread-file` 只需要 `thread_id`；分页参数默认 `--page-num 1 --page-size 100`。
-- `+list-thread-file` 和 `+download-result` 是两个不同的 CLI 指令：前者获取会话文件元信息，后者下载 URL 资源并写入到本地目录。
-- `+download-result` 接收 `--url`、`--output-dir`、`--workers`。
+- `+list-thread-file` 只需要 `thread_id`；分页参数使用 `--page-num 1 --page-size 1000` 起步，`total` 达到 1000 时下一轮递增 `page-num`。
+- `+list-thread-file` 和 `+download-result` 是两个不同的 CLI 指令：前者获取会话文件元信息，后者下载 URL 资源并写入到本地目标文件路径。
+- `+download-result` 接收 `--url`、`--output-path`、`--workers`；`--output-path` 必须是包含文件名的目标文件路径。