@pippit-dev/cli 0.0.21 → 0.0.23

package/README.md

@@ -198,13 +198,13 @@ pippit-tool-cli --version
 pippit-tool-cli short-drama +submit-run --message "写一个赛博朋克短剧开头"
 pippit-tool-cli short-drama +upload-file --path ./reference.doc
 pippit-tool-cli short-drama +get-thread --thread-id thread_123 --run-id run_456
-pippit-tool-cli short-drama +download-result --output-path ./thread_123/results/result.mp4 --url URL
+pippit-tool-cli short-drama +download-result --output-path ./thread_123/results/result.mp4 --url URL --updated-at 1779716734
 ```
 
 `+submit-run`: 输出 `thread_id`、`run_id` 和 `web_thread_link`；其中 `--message` 为必填参数。
 `+get-thread`: 请求中带 `version=v2`，并输出 `readable_text`。
 `+upload-file`: 输出返回的 `asset_id`。 当前仅支持 `.doc`、`.docx` 和 `.txt` 文件。
-`+download-result`: 会把结果 URL 下载到 `--output-path` 指定的文件路径。
+`+download-result`: 会把结果 URL 下载到 `--output-path` 指定的文件路径；传入 `--updated-at` 后，如果本地文件早于该时间戳会覆盖更新，否则跳过。
 
 短剧命令的错误日志会追加写入本地每日日志文件：`~/.pippit_tool_cli/logs/yyyy-mm-dd.log`。日志路径会基于当前用户主目录和系统路径分隔符生成，因此可在 macOS、Linux 和 Windows 上使用。
 

package/checksums.txt

@@ -1,6 +1,6 @@
-ccd86bb8dcfc02ab6d199c951d93a946a9a594436d68f096b3d400e770117101  pippit-tool-cli-0.0.21-darwin-amd64.tar.gz
-7aebaaffe3ae5115e6896889316d79662591816deaac7db629029c44b692c18b  pippit-tool-cli-0.0.21-darwin-arm64.tar.gz
-8b7b63d04e778eedb0acddf9ad922c6db45c4e2ae98f8432dc5912fde3b11ead  pippit-tool-cli-0.0.21-linux-amd64.tar.gz
-baf3b5fccbad34bdcfb374680536ec9da7a38b5dad988dcdf8ad82d9647c2c4d  pippit-tool-cli-0.0.21-linux-arm64.tar.gz
-dca29c43a2d968eaef1d69236920479893c0e7351b822577645b7e9ed747ce21  pippit-tool-cli-0.0.21-windows-amd64.zip
-a309a1b47d1116be922d92826df75933f721cfab1f9fa99c95332611f8a9cbf9  pippit-tool-cli-0.0.21-windows-arm64.zip
+6622f32c85491b9287ac690b269ad42a67c652793261c1068a1a39958505db31  pippit-tool-cli-0.0.23-darwin-amd64.tar.gz
+fe18af3140b0def41eb954e671d81a9e4fd6e9973c87a942c6b7cd59363731e3  pippit-tool-cli-0.0.23-darwin-arm64.tar.gz
+9a5b56a42a0611a540d30f04ba50ce430040188c67446bcd42bd0297c6bbee60  pippit-tool-cli-0.0.23-linux-amd64.tar.gz
+bad0a2c0d311bda3fce24652a4116b1d620fc12008a1f5b2ea77017f677dd9c8  pippit-tool-cli-0.0.23-linux-arm64.tar.gz
+cb44ff96743bd5a47eec7d05b5a228b491c36907ba2f013af4c7b2259b18781f  pippit-tool-cli-0.0.23-windows-amd64.zip
+70ea30297e07c800a14c4aa52eecc6d9ea7f78a259892b5f9efc05d9e7385d22  pippit-tool-cli-0.0.23-windows-arm64.zip

package/cmd/short_drama/short_drama.go

@@ -104,11 +104,15 @@ func newShortDramaDownloadResultCommand(stdout, stderr io.Writer, runner *common
 		Short: "Download a generated result URL",
 		Args:  cobra.NoArgs,
 		RunE: withErrorLog("short-drama +download-result", func() map[string]string {
-			return map[string]string{
+			fields := map[string]string{
 				"output_path": opts.OutputPath,
 				"has_url":     strconv.FormatBool(strings.TrimSpace(opts.URL) != ""),
 				"workers":     strconv.Itoa(opts.Workers),
 			}
+			if opts.UpdatedAt > 0 {
+				fields["updated_at"] = strconv.FormatInt(opts.UpdatedAt, 10)
+			}
+			return fields
 		}, func(cmd *cobra.Command, _ []string) error {
 			opts.OutputPath = strings.TrimSpace(opts.OutputPath)
 			if opts.OutputPath == "" {
@@ -133,6 +137,7 @@ func newShortDramaDownloadResultCommand(stdout, stderr io.Writer, runner *common
 	cmd.SetErr(stderr)
 	cmd.Flags().StringVar(&opts.URL, "url", "", "URL to download")
 	cmd.Flags().StringVar(&opts.OutputPath, "output-path", "", "local output file path")
+	cmd.Flags().Int64Var(&opts.UpdatedAt, "updated-at", 0, "remote file update time as a Unix timestamp")
 	cmd.Flags().IntVar(&opts.Workers, "workers", 5, "parallel download workers")
 	return cmd
 }

package/cmd/short_drama_test.go

@@ -184,9 +184,7 @@ func TestShortDramaSubmitRunRequiresAccessKey(t *testing.T) {
 	if err == nil {
 		t.Fatal("Execute() error = nil, want access key error")
 	}
-	if !strings.Contains(err.Error(), "XYQ_ACCESS_KEY is required") {
-		t.Fatalf("error = %q, want access key guidance", err)
-	}
+	assertAccessKeyGuidance(t, err)
 }
 
 func TestShortDramaUploadFile(t *testing.T) {
@@ -286,9 +284,7 @@ func TestShortDramaUploadFileRequiresAccessKey(t *testing.T) {
 	if err == nil {
 		t.Fatal("Execute() error = nil, want access key error")
 	}
-	if !strings.Contains(err.Error(), "XYQ_ACCESS_KEY is required") {
-		t.Fatalf("error = %q, want access key guidance", err)
-	}
+	assertAccessKeyGuidance(t, err)
 }
 
 func TestShortDramaUploadFileRejectsUnsupportedFileType(t *testing.T) {
@@ -408,6 +404,111 @@ func TestShortDramaDownloadResultSkipsExistingFile(t *testing.T) {
 	assertFileContent(t, outputPath, "existing-data")
 }
 
+func TestShortDramaDownloadResultSkipsExistingFileWhenLocalIsFresh(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 when target file is fresh")
+	}))
+	defer server.Close()
+
+	chdirTemp(t)
+	outputPath := filepath.Join("results", "cover.jpeg")
+	if err := os.MkdirAll(filepath.Dir(outputPath), 0o755); err != nil {
+		t.Fatalf("MkdirAll(): %v", err)
+	}
+	if err := os.WriteFile(outputPath, []byte("existing-data"), 0o644); err != nil {
+		t.Fatalf("WriteFile(): %v", err)
+	}
+	remoteUpdatedAt := int64(1779716734)
+	localUpdatedAt := time.Unix(remoteUpdatedAt+10, 0)
+	if err := os.Chtimes(outputPath, localUpdatedAt, localUpdatedAt); err != nil {
+		t.Fatalf("Chtimes(): %v", err)
+	}
+
+	var stdout, stderr bytes.Buffer
+	root := NewRootCommand(&stdout, &stderr)
+	root.SetArgs([]string{
+		"short-drama", "+download-result",
+		"--output-path", outputPath,
+		"--updated-at", "1779716734",
+		"--url", server.URL + "/image",
+	})
+
+	if err := root.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v, stderr = %s", err, stderr.String())
+	}
+	if serverCalled {
+		t.Fatal("server was called, want fresh existing file to skip download")
+	}
+
+	got := decodeJSON(t, stdout.Bytes())
+	alreadyExist, ok := got["already_exist"].([]any)
+	if !ok || len(alreadyExist) != 1 || alreadyExist[0] != outputPath {
+		t.Fatalf("already_exist = %#v, want existing output path", got["already_exist"])
+	}
+	assertFileContent(t, outputPath, "existing-data")
+}
+
+func TestShortDramaDownloadResultOverwritesStaleExistingFile(t *testing.T) {
+	serverCalled := false
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		serverCalled = true
+		if r.URL.Path != "/image" {
+			t.Fatalf("path = %s, want /image", r.URL.Path)
+		}
+		_, _ = w.Write([]byte("new-data"))
+	}))
+	defer server.Close()
+
+	chdirTemp(t)
+	outputPath := filepath.Join("results", "cover.jpeg")
+	if err := os.MkdirAll(filepath.Dir(outputPath), 0o755); err != nil {
+		t.Fatalf("MkdirAll(): %v", err)
+	}
+	if err := os.WriteFile(outputPath, []byte("existing-data"), 0o644); err != nil {
+		t.Fatalf("WriteFile(): %v", err)
+	}
+	remoteUpdatedAt := int64(1779716734)
+	staleUpdatedAt := time.Unix(remoteUpdatedAt-10, 0)
+	if err := os.Chtimes(outputPath, staleUpdatedAt, staleUpdatedAt); err != nil {
+		t.Fatalf("Chtimes(): %v", err)
+	}
+
+	var stdout, stderr bytes.Buffer
+	root := NewRootCommand(&stdout, &stderr)
+	root.SetArgs([]string{
+		"short-drama", "+download-result",
+		"--output-path", outputPath,
+		"--updated-at", "1779716734",
+		"--url", server.URL + "/image",
+	})
+
+	if err := root.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v, stderr = %s", err, stderr.String())
+	}
+	if !serverCalled {
+		t.Fatal("server was not called, want stale existing file to be downloaded")
+	}
+
+	got := decodeJSON(t, stdout.Bytes())
+	downloaded, ok := got["downloaded"].([]any)
+	if !ok || len(downloaded) != 1 || downloaded[0] != outputPath {
+		t.Fatalf("downloaded = %#v, want output path", got["downloaded"])
+	}
+	if _, ok := got["overwritten"]; ok {
+		t.Fatalf("overwritten should not be returned: %#v", got)
+	}
+	assertFileContent(t, outputPath, "new-data")
+	info, err := os.Stat(outputPath)
+	if err != nil {
+		t.Fatalf("Stat(%s): %v", outputPath, err)
+	}
+	if info.ModTime().Unix() != remoteUpdatedAt {
+		t.Fatalf("mtime = %d, want %d", info.ModTime().Unix(), remoteUpdatedAt)
+	}
+}
+
 func TestShortDramaDownloadResultDownloadsMetaJSON(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path != "/meta.json" {
@@ -513,6 +614,7 @@ func TestShortDramaDownloadResultAllFailed(t *testing.T) {
 	defer server.Close()
 
 	chdirTemp(t)
+	clearDailyErrorLog(t)
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
 	root.SetArgs([]string{
@@ -528,6 +630,17 @@ func TestShortDramaDownloadResultAllFailed(t *testing.T) {
 	if !strings.Contains(err.Error(), "all 1 download(s) failed") {
 		t.Fatalf("error = %q, want all-failed message", err)
 	}
+	logs := readDailyErrorLog(t)
+	if len(logs) != 1 {
+		t.Fatalf("logs = %#v, want one error log", logs)
+	}
+	fields, ok := logs[0]["fields"].(map[string]any)
+	if !ok {
+		t.Fatalf("fields = %#v, want object", logs[0]["fields"])
+	}
+	if _, ok := fields["updated_at"]; ok {
+		t.Fatalf("updated_at should be omitted when --updated-at is not provided: %#v", fields)
+	}
 }
 
 func TestShortDramaDownloadResultOutputPath(t *testing.T) {
@@ -651,9 +764,7 @@ func TestShortDramaGetThreadRequiresAccessKey(t *testing.T) {
 	if err == nil {
 		t.Fatal("Execute() error = nil, want access key error")
 	}
-	if !strings.Contains(err.Error(), "XYQ_ACCESS_KEY is required") {
-		t.Fatalf("error = %q, want access key guidance", err)
-	}
+	assertAccessKeyGuidance(t, err)
 }
 
 func TestShortDramaListThreadFile(t *testing.T) {
@@ -684,7 +795,7 @@ func TestShortDramaListThreadFile(t *testing.T) {
 		if body["page_size"] != float64(10) {
 			t.Fatalf("page_size = %v, want 10", body["page_size"])
 		}
-		_, _ = w.Write([]byte(`{"ret":"0","errmsg":"","data":{"total":1,"files":[{"file_name":"ignored.png","file_path":"results/images/cover.png","download_url":"https://example.com/cover.png"}]}}`))
+		_, _ = w.Write([]byte(`{"ret":"0","errmsg":"","data":{"total":1,"files":[{"file_name":"ignored.png","file_path":"results/images/cover.png","download_url":"https://example.com/cover.png","updated_at":1779716734}]}}`))
 	}))
 	defer server.Close()
 
@@ -727,6 +838,9 @@ func TestShortDramaListThreadFile(t *testing.T) {
 	if file["download_url"] != "https://example.com/cover.png" {
 		t.Fatalf("download_url = %v, want returned url", file["download_url"])
 	}
+	if file["updated_at"] != float64(1779716734) {
+		t.Fatalf("updated_at = %v, want 1779716734", file["updated_at"])
+	}
 }
 
 func TestShortDramaListThreadFileMessageWhenPageFull(t *testing.T) {
@@ -772,6 +886,23 @@ func TestShortDramaListThreadFileRequiresThreadID(t *testing.T) {
 	}
 }
 
+func TestShortDramaListThreadFileRequiresAccessKey(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatal("server should not receive request without access key")
+	}))
+	defer server.Close()
+
+	var stdout, stderr bytes.Buffer
+	root := newTestRootCommandWithAccessKey(t, &stdout, &stderr, server.URL, "")
+	root.SetArgs([]string{"short-drama", "+list-thread-file", "--thread-id", "thread_123"})
+
+	err := root.Execute()
+	if err == nil {
+		t.Fatal("Execute() error = nil, want access key error")
+	}
+	assertAccessKeyGuidance(t, err)
+}
+
 func TestShortDramaListThreadFileRejectsPageSizeAboveMax(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	root := NewRootCommand(&stdout, &stderr)
@@ -805,6 +936,23 @@ func newTestRootCommandWithAccessKey(t *testing.T, stdout, stderr io.Writer, bas
 	return newRootCommand(stdout, stderr, runner)
 }
 
+func assertAccessKeyGuidance(t *testing.T, err error) {
+	t.Helper()
+	if err == nil {
+		t.Fatal("error = nil, want access key guidance")
+	}
+	msg := err.Error()
+	if !strings.Contains(msg, "XYQ_ACCESS_KEY is required") {
+		t.Fatalf("error = %q, want access key guidance", err)
+	}
+	if !strings.Contains(msg, "https://xyq.jianying.com/home?tab_name=home") {
+		t.Fatalf("error = %q, want access key settings URL", err)
+	}
+	if !strings.Contains(msg, `export XYQ_ACCESS_KEY="<access-key>"`) {
+		t.Fatalf("error = %q, want setup command guidance", err)
+	}
+}
+
 func decodeJSON(t *testing.T, data []byte) map[string]any {
 	t.Helper()
 	var got map[string]any

package/internal/common/access_key.go

@@ -22,7 +22,7 @@ func (a *accessKeyAuthorizer) Inject(ctx context.Context, req *http.Request) err
 		return err
 	}
 	if a.accessKey == "" && req.Method == http.MethodPost {
-		return fmt.Errorf("%s is required for authenticated requests", config.EnvXYQAccessKey)
+		return fmt.Errorf("%s 缺失. 请前往小云雀官网个人设置页创建 Access Key，地址：https://xyq.jianying.com/home?tab_name=home\n配置后重试：\n  export %s=\"<your-access-key>\"", config.EnvXYQAccessKey, config.EnvXYQAccessKey)
 	}
 	if a.accessKey != "" {
 		req.Header.Set("Authorization", "Bearer "+a.accessKey)

package/internal/common/download_results.go

@@ -23,6 +23,7 @@ import (
 type DownloadResultOptions struct {
 	URL        string `json:"url"`
 	OutputPath string `json:"output_path"`
+	UpdatedAt  int64  `json:"updated_at,omitempty"`
 	Workers    int    `json:"workers"`
 }
 
@@ -45,8 +46,9 @@ const (
 )
 
 type downloadTask struct {
-	url      string
-	filepath string
+	url       string
+	filepath  string
+	updatedAt int64
 }
 
 type downloadTaskResult struct {
@@ -67,15 +69,16 @@ func DownloadResult(ctx context.Context, opts DownloadResultOptions, runner *Run
 	if outputPath == "" {
 		return nil, fmt.Errorf("output_path is required")
 	}
-	// check if the output path exists and is a file
 	if info, err := os.Stat(outputPath); err == nil {
 		if info.IsDir() {
 			return nil, fmt.Errorf("output path %q is a directory", outputPath)
 		}
-		return &DownloadResultResponse{
-			OutputPath:   outputPath,
-			AlreadyExist: []string{outputPath},
-		}, nil
+		if shouldSkipExistingFile(info, opts.UpdatedAt) {
+			return &DownloadResultResponse{
+				OutputPath:   outputPath,
+				AlreadyExist: []string{outputPath},
+			}, nil
+		}
 	} else if !os.IsNotExist(err) {
 		return nil, fmt.Errorf("stat output path: %w", err)
 	}
@@ -93,8 +96,9 @@ func DownloadResult(ctx context.Context, opts DownloadResultOptions, runner *Run
 	}
 	tasks := []downloadTask{
 		{
-			url:      rawURL,
-			filepath: outputPath,
+			url:       rawURL,
+			filepath:  outputPath,
+			updatedAt: opts.UpdatedAt,
 		},
 	}
 
@@ -117,7 +121,7 @@ func DownloadResult(ctx context.Context, opts DownloadResultOptions, runner *Run
 			for task := range taskCh {
 				resultCh <- downloadTaskResult{
 					filepath: task.filepath,
-					err:      downloadFileWithRetry(ctx, runner.Client, task.url, task.filepath),
+					err:      downloadFileWithRetry(ctx, runner.Client, task.url, task.filepath, task.updatedAt),
 				}
 			}
 		}()
@@ -167,7 +171,14 @@ func DownloadResult(ctx context.Context, opts DownloadResultOptions, runner *Run
 	return result, nil
 }
 
-func downloadFileWithRetry(ctx context.Context, client Client, rawURL string, targetPath string) error {
+func shouldSkipExistingFile(info os.FileInfo, updatedAt int64) bool {
+	if updatedAt <= 0 {
+		return true
+	}
+	return info.ModTime().Unix() >= updatedAt
+}
+
+func downloadFileWithRetry(ctx context.Context, client Client, rawURL string, targetPath string, updatedAt int64) error {
 	var lastErr error
 	for attempt := 0; attempt <= maxDownloadRetries; attempt++ {
 		if attempt > 0 {
@@ -180,7 +191,7 @@ func downloadFileWithRetry(ctx context.Context, client Client, rawURL string, ta
 			case <-timer.C:
 			}
 		}
-		err := downloadFile(ctx, client, rawURL, targetPath)
+		err := downloadFile(ctx, client, rawURL, targetPath, updatedAt)
 		if err == nil {
 			return nil
 		}
@@ -203,7 +214,7 @@ func isRetryableError(err error) bool {
 	return false
 }
 
-func downloadFile(ctx context.Context, client Client, rawURL string, targetPath string) error {
+func downloadFile(ctx context.Context, client Client, rawURL string, targetPath string, updatedAt int64) error {
 	var resp *http.Response
 	if err := client.SendRequest(ctx, rawURL, nil, &resp); err != nil {
 		return err
@@ -211,6 +222,12 @@ func downloadFile(ctx context.Context, client Client, rawURL string, targetPath
 	defer resp.Body.Close()
 
 	tmpPath := targetPath + ".tmp"
+	tempActive := true
+	defer func() {
+		if tempActive {
+			_ = os.Remove(tmpPath)
+		}
+	}()
 	out, err := os.Create(tmpPath)
 	if err != nil {
 		return fmt.Errorf("create temp file: %w", err)
@@ -218,16 +235,18 @@ func downloadFile(ctx context.Context, client Client, rawURL string, targetPath
 	_, copyErr := io.Copy(out, resp.Body)
 	closeErr := out.Close()
 	if copyErr != nil {
-		_ = os.Remove(tmpPath)
 		return fmt.Errorf("write temp file: %w", copyErr)
 	}
 	if closeErr != nil {
-		_ = os.Remove(tmpPath)
 		return fmt.Errorf("close temp file: %w", closeErr)
 	}
 	if err := os.Rename(tmpPath, targetPath); err != nil {
-		_ = os.Remove(tmpPath)
 		return fmt.Errorf("replace target file: %w", err)
 	}
+	tempActive = false
+	if updatedAt > 0 {
+		modTime := time.Unix(updatedAt, 0)
+		_ = os.Chtimes(targetPath, time.Now(), modTime)
+	}
 	return nil
 }

package/internal/common/list_thread_file.go

@@ -22,6 +22,7 @@ type ListThreadFileOptions struct {
 type ThreadFile struct {
 	FilePath    string `json:"file_path"`
 	DownloadURL string `json:"download_url"`
+	UpdatedAt   *int64 `json:"updated_at,omitempty"`
 }
 
 // ListThreadFileResult is the JSON envelope printed by `pippit-tool-cli short-drama +list-thread-file`.
@@ -45,6 +46,7 @@ type listThreadFileResponse struct {
 type threadFileResponse struct {
 	FilePath    string `json:"file_path"`
 	DownloadURL string `json:"download_url"`
+	UpdatedAt   *int64 `json:"updated_at,omitempty"`
 }
 
 func ListThreadFile(ctx context.Context, opts *ListThreadFileOptions, runner *Runner) (*ListThreadFileResult, error) {
@@ -81,6 +83,7 @@ func ListThreadFile(ctx context.Context, opts *ListThreadFileOptions, runner *Ru
 		files = append(files, &ThreadFile{
 			FilePath:    threadFilePath(opts.ThreadID, file.FilePath),
 			DownloadURL: file.DownloadURL,
+			UpdatedAt:   file.UpdatedAt,
 		})
 	}
 

package/package.json

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

package/skills/short-drama/SKILL.md

@@ -67,6 +67,14 @@ metadata:
 npx @pippit-dev/cli@latest install
 ```
 
+部分功能需要先配置 `XYQ_ACCESS_KEY`。缺失时 CLI 会直接提示用户先创建 Access Key，此时请等待用户给与Access Key后再继续运行。
+
+Access Key 创建地址：https://xyq.jianying.com/home?tab_name=home
+
+```bash
+export XYQ_ACCESS_KEY="<access-key>"
+```
+
 ## 使用方法
 
 ### 1. 提交短剧任务
@@ -121,7 +129,8 @@ pippit-tool-cli short-drama +list-thread-file --thread-id THREAD_ID --page-num 1
 ```json
 {
   "file_path": "./{thread-id}/路径/文件名", // 文件完整路径，包含文件名
-  "download_url": "https://..." // URL
+  "download_url": "https://...", // URL
+  "updated_at": 1779716734 // 文件更新时间，Unix 秒级时间戳
 }
 ```
 
@@ -131,10 +140,10 @@ pippit-tool-cli short-drama +list-thread-file --thread-id THREAD_ID --page-num 1
 
 ```bash
 # 下载文件资源到指定文件路径
-pippit-tool-cli short-drama +download-result --url DOWNLOAD_URL --output-path FILE_PATH
+pippit-tool-cli short-drama +download-result --url DOWNLOAD_URL --output-path FILE_PATH --updated-at UPDATED_AT
 ```
 
-`FILE_PATH` 必须直接使用 `+list-thread-file` 返回的完整 `file_path`，包含文件名，不要取父目录。`+download-result` 负责把会话产生的文件通过 URL 下载到该目标文件路径；如果目标文件已存在，跳过下载。
+`FILE_PATH` 必须直接使用 `+list-thread-file` 返回的完整 `file_path`，包含文件名，不要取父目录。`UPDATED_AT` 使用同一文件对象返回的 `updated_at`；如果没有 `updated_at`，可省略 `--updated-at`。`+download-result` 负责把会话产生的文件通过 URL 下载到该目标文件路径；如果目标文件已存在且本地修改时间不早于 `updated_at`，跳过下载；如果本地文件早于 `updated_at`，覆盖更新。
 
 ## 典型工作流
 
@@ -151,7 +160,7 @@ pippit-tool-cli short-drama +download-result --url DOWNLOAD_URL --output-path FI
    - 如果任务仍在进行中：展示可读进展，继续查询
    - 如果后端 Agent 提出问题：从 readable_text 中提取问题并展示，等待用户回复
 5. 检查 `list-thread-file` 返回的 files：
-   - 对每个文件取 file_path、download_url
+   - 对每个文件取 file_path、download_url、updated_at
    - 将 file_path 作为本地目标文件路径，包含文件名
    - 有 download_url 的重要资产：加入本轮下载队列
    - 不判断 file_path 在本地是否已存在，是否跳过由 +download-result 内部处理
@@ -159,6 +168,7 @@ pippit-tool-cli short-drama +download-result --url DOWNLOAD_URL --output-path FI
 6. 对重要资产，立即调用 +download-result 并行下载资源：
    - 使用第 5 步获取的 download_url 作为 --url
    - 使用第 5 步获取的完整 file_path 作为 --output-path
+   - 如果第 5 步返回 updated_at，作为 --updated-at 传入
    - 剧本设计、场景设计、场景图、人物角色设计、人物图、最终视频产物都属于重要资产
 7. 查询或下载失败时，不要直接放弃；记录失败项，并在后续轮询中主动重试
 8. 只有会话进展已处理，且已发现的重要资产均已下载或明确重试失败后，才向用户汇总最终结果
@@ -249,7 +259,8 @@ Thread: thread_...
   "files": [
     {
       "file_path": "./{thread-id}/{file_path}/{file_name}",
-      "download_url": "https://..."
+      "download_url": "https://...",
+      "updated_at": 1779716734
     }
   ],
   "total": 1,
@@ -274,12 +285,12 @@ Thread: thread_...
 
 ### 获取会话文件
 
-从 `+list-thread-file` 的 `files` 中逐个读取文件元信息：`file_path`、`file_name`、`download_url`。重点识别剧本设计、场景设计、场景图、人物角色设计、人物图、分集草稿、故事板、最终视频产物等重要资产。
+从 `+list-thread-file` 的 `files` 中逐个读取文件元信息：`file_path`、`file_name`、`download_url`、`updated_at`。重点识别剧本设计、场景设计、场景图、人物角色设计、人物图、分集草稿、故事板、最终视频产物等重要资产。
 
 ```
 1. 有download_url的重要资产
-   → 记录该file_path和URL
-   → 使用 +download-result 将URL资源下载到该file_path
+   → 记录该file_path、URL和updated_at
+   → 使用 +download-result 将URL资源下载到该file_path；有updated_at时传入--updated-at
 2. 本轮total达到200
    → 下一轮page-num加1，继续查询新一页结果
 3. 本轮total未达到200
@@ -293,7 +304,7 @@ Thread: thread_...
 
 对带 `download_url` 的重要资产调用下载工具，可并行。重要资产必须主动下载，不要等用户再次要求，也不要在调用下载工具前先检查本地文件是否存在。
 
-1. 调用 `pippit-tool-cli short-drama +download-result --url DOWNLOAD_URL --output-path FILE_PATH`。
+1. 调用 `pippit-tool-cli short-drama +download-result --url DOWNLOAD_URL --output-path FILE_PATH --updated-at UPDATED_AT`；如果文件对象没有 `updated_at`，省略 `--updated-at`。
 2. 下载完成后，向用户展示本地文件路径；如果某个文件下载失败，记录失败项并在后续轮询中重试，不阻塞已成功落盘的文件展示。
 
 ## 向用户展示内容
@@ -335,4 +346,4 @@ Thread: thread_...
 - 单次创作会话中（相同 `thread_id`），`+submit-run` 只支持绑定一个剧本文件。不要在同一 `thread_id` 下重复上传并追加第二个剧本 `asset_id`；用户给多个剧本时，先让用户选择一个，或分别开启新的创作会话。
 - `+list-thread-file` 只需要 `thread_id`；分页参数使用 `--page-num 1 --page-size 200` 起步，`total` 达到 200 时下一轮递增 `page-num`。
 - `+list-thread-file` 和 `+download-result` 是两个不同的 CLI 指令：前者获取会话文件元信息，后者下载 URL 资源并写入到本地目标文件路径。
-- `+download-result` 接收 `--url`、`--output-path`、`--workers`；`--output-path` 必须是包含文件名的目标文件路径。
+- `+download-result` 接收 `--url`、`--output-path`、`--updated-at`、`--workers`；`--output-path` 必须是包含文件名的目标文件路径。