@pippit-dev/cli 0.0.12 → 0.0.14

package/README.md

@@ -1,4 +1,4 @@
-# pippit-cli
+# pippit-tool-cli
 
 Minimal demo CLI for Pippit workflows.
 
@@ -10,11 +10,11 @@ matching prebuilt binary for macOS, Linux, or Windows:
 ```bash
 npx @pippit-dev/cli@latest install
 export XYQ_ACCESS_KEY="<access-key>"
-pippit-cli --version
-pippit-cli short-drama +submit-run --message "写一个赛博朋克短剧开头"
-pippit-cli short-drama +upload-file --path ./reference.doc
-pippit-cli short-drama +get-thread --thread-id thread_123 --run-id run_456 --after-seq 0
-pippit-cli short-drama +download-result --output-path ./thread_123/results/result.mp4 --url URL
+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 --after-seq 0
+pippit-tool-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

package/checksums.txt

@@ -1,6 +1,6 @@
-5062d1d4950aa9e0d8b1770e62476d9bb2076f4492cd24a541ad93b05a254f49  pippit-cli-0.0.12-darwin-amd64.tar.gz
-5a0c8d044ebcb717d18954147433ac5f54f2dc89285e2e50f6be6755431ee99c  pippit-cli-0.0.12-darwin-arm64.tar.gz
-456420a71cd9909e152907faa96f35abb93e62079786021d1bee28cfac61e8ff  pippit-cli-0.0.12-linux-amd64.tar.gz
-1c6681fa8f8edaa19dac835dd9bdf4bc17c06936700316f7d74b68d55d572460  pippit-cli-0.0.12-linux-arm64.tar.gz
-e7c156bb35fb373fa89d05c729252b20951a41c70f3bbd4e8794e4c5abe65e06  pippit-cli-0.0.12-windows-amd64.zip
-2832786f9c13069f3580407e24037e95cc9452534e9996366dc6751f841fcd26  pippit-cli-0.0.12-windows-arm64.zip
+2d0d79a7a277b9969076a38d3584b6dfc9fece10d6505edc314e56a67ab78974  pippit-tool-cli-0.0.14-darwin-amd64.tar.gz
+e1ecf0319de259bf7e790e90a96e0e596a4a04b5f0b5c774196fd7a5048e9336  pippit-tool-cli-0.0.14-darwin-arm64.tar.gz
+09056e9f1b2241c7021bb9cb47279d6497848adaea72fb5531cf1ed62a7e6e88  pippit-tool-cli-0.0.14-linux-amd64.tar.gz
+2b50fa3f7745e6cb5436d82f309870cf17b7faa52ab5129b3179cee69e6b6c88  pippit-tool-cli-0.0.14-linux-arm64.tar.gz
+ffaaca77e50f4962713ce871a871d47992c276ac174c8721c507359b369afcb4  pippit-tool-cli-0.0.14-windows-amd64.zip
+6cb91adab8d2004160f6792014fd948aea3368c38f38f30aabccd381d31e82eb  pippit-tool-cli-0.0.14-windows-arm64.zip

package/cmd/root.go

@@ -13,7 +13,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-// Execute runs the pippit-cli command tree.
+// Execute runs the pippit-tool-cli command tree.
 func Execute() error {
 	return NewRootCommand(os.Stdout, os.Stderr).Execute()
 }
@@ -27,7 +27,7 @@ func NewRootCommand(stdout, stderr io.Writer) *cobra.Command {
 
 func newRootCommand(stdout, stderr io.Writer, runner *common.Runner) *cobra.Command {
 	root := &cobra.Command{
-		Use:           "pippit-cli",
+		Use:           "pippit-tool-cli",
 		Short:         "Pippit CLI",
 		Long:          "Pippit CLI submits short-drama workflows, downloads generated assets, and updates the installed CLI package.",
 		Version:       version.Current(),

package/cmd/update/update.go

@@ -18,7 +18,7 @@ const defaultPackage = "@pippit-dev/cli"
 func NewCommand(stdout, stderr io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "update",
-		Short: "Update pippit-cli and bundled skills",
+		Short: "Update pippit-tool-cli and bundled skills",
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			return runUpdate(stdout, stderr)
 		},
@@ -32,14 +32,14 @@ func runUpdate(stdout, stderr io.Writer) error {
 		pkg = defaultPackage + "@latest"
 	}
 
-	fmt.Fprintf(stderr, "Updating pippit-cli via npm: %s\n", pkg)
+	fmt.Fprintf(stderr, "Updating pippit-tool-cli via npm: %s\n", pkg)
 	restore, err := prepareSelfReplace()
 	if err != nil {
 		return fmt.Errorf("prepare self replace: %w", err)
 	}
 	if err := runInheritEnv(stderr, []string{"PIPPIT_CLI_SKIP_SKILLS=1"}, "npm", "install", "-g", pkg); err != nil {
 		restore()
-		return fmt.Errorf("update pippit-cli: %w", err)
+		return fmt.Errorf("update pippit-tool-cli: %w", err)
 	}
 
 	root, err := globalPackageRoot(defaultPackage)
@@ -47,12 +47,12 @@ func runUpdate(stdout, stderr io.Writer) error {
 		return fmt.Errorf("locate global package: %w", err)
 	}
 
-	fmt.Fprintln(stderr, "Updating pippit-cli skills...")
+	fmt.Fprintln(stderr, "Updating pippit-tool-cli skills...")
 	if err := installSkills(root, stderr); err != nil {
-		return fmt.Errorf("update pippit-cli skills: %w", err)
+		return fmt.Errorf("update pippit-tool-cli skills: %w", err)
 	}
 
-	fmt.Fprintln(stdout, "pippit-cli and skills updated")
+	fmt.Fprintln(stdout, "pippit-tool-cli and skills updated")
 	return nil
 }
 
@@ -107,7 +107,7 @@ func prepareSelfReplace() (func(), error) {
 	if err != nil {
 		return nil, err
 	}
-	if filepath.Base(exe) != "pippit-cli.exe" || !strings.Contains(exe, "node_modules") {
+	if filepath.Base(exe) != "pippit-tool-cli.exe" || !strings.Contains(exe, "node_modules") {
 		return func() {}, nil
 	}
 	old := exe + ".old"

package/internal/common/download_results.go

@@ -31,7 +31,7 @@ type DownloadResultError struct {
 	Error string `json:"error"`
 }
 
-// DownloadResultResponse is the JSON envelope printed by `pippit-cli short-drama +download-result`.
+// DownloadResultResponse is the JSON envelope printed by `pippit-tool-cli short-drama +download-result`.
 type DownloadResultResponse struct {
 	OutputPath   string                 `json:"output_path"`
 	Downloaded   []string               `json:"downloaded"`

package/internal/common/list_thread_file.go

@@ -24,7 +24,7 @@ type ThreadFile struct {
 	DownloadURL string `json:"download_url"`
 }
 
-// ListThreadFileResult is the JSON envelope printed by `pippit-cli short-drama +list-thread-file`.
+// ListThreadFileResult is the JSON envelope printed by `pippit-tool-cli short-drama +list-thread-file`.
 type ListThreadFileResult struct {
 	Files   []*ThreadFile `json:"files"`
 	Total   int64         `json:"total"`

package/internal/common/upload_file.go

@@ -17,7 +17,7 @@ type UploadFileOptions struct {
 	FileName string `json:"file_name"`
 }
 
-// UploadFileResult is the JSON envelope printed by `pippit-cli short-drama +upload-file`.
+// UploadFileResult is the JSON envelope printed by `pippit-tool-cli short-drama +upload-file`.
 type UploadFileResult struct {
 	AssetID string `json:"asset_id"`
 }

package/internal/short_drama/get_thread.go

@@ -22,7 +22,7 @@ type ThreadEntry struct {
 	Content []any  `json:"content"`
 }
 
-// GetThreadResult is the JSON envelope printed by `pippit-cli short-drama +get-thread`.
+// GetThreadResult is the JSON envelope printed by `pippit-tool-cli short-drama +get-thread`.
 type GetThreadResult struct {
 	Messages []*ThreadEntry `json:"messages"`
 }

package/internal/short_drama/submit_run.go

@@ -15,7 +15,7 @@ type SubmitRunOptions struct {
 	AssetIDs []string `json:"asset_ids,omitempty"`
 }
 
-// SubmitRunResult is the JSON envelope printed by `pippit-cli short-drama +submit-run`.
+// SubmitRunResult is the JSON envelope printed by `pippit-tool-cli short-drama +submit-run`.
 type SubmitRunResult struct {
 	ThreadID      string `json:"thread_id"`
 	RunID         string `json:"run_id"`

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@pippit-dev/cli",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "Pippit CLI",
   "bin": {
-    "pippit-cli": "scripts/run.js"
+    "pippit-tool-cli": "scripts/run.js"
   },
   "scripts": {
     "postinstall": "node scripts/install.js",

package/scripts/install-wizard.js

@@ -17,12 +17,12 @@ function getGloballyInstalledVersion() {
   }
 }
 
-function whichPippitCli() {
+function whichPippitToolCli() {
   try {
     const prefix = runSilent("npm", ["prefix", "-g"], { timeout: 15000 }).toString().trim();
     const bin = isWindows
-      ? path.join(prefix, "pippit-cli.cmd")
-      : path.join(prefix, "bin", "pippit-cli");
+      ? path.join(prefix, "pippit-tool-cli.cmd")
+      : path.join(prefix, "bin", "pippit-tool-cli");
     if (fs.existsSync(bin)) return bin;
   } catch (_) {
     // Fall back to PATH lookup.
@@ -30,7 +30,7 @@ function whichPippitCli() {
 
   try {
     const cmd = isWindows ? "where" : "which";
-    return runSilent(cmd, ["pippit-cli"]).toString().split("\n")[0].trim();
+    return runSilent(cmd, ["pippit-tool-cli"]).toString().split("\n")[0].trim();
   } catch (_) {
     return null;
   }
@@ -39,7 +39,7 @@ function whichPippitCli() {
 function main() {
   const installed = getGloballyInstalledVersion();
   if (installed) {
-    console.log(`Updating global pippit-cli (${installed}) via ${PKG}...`);
+    console.log(`Updating global pippit-tool-cli (${installed}) via ${PKG}...`);
   } else {
     console.log(`Installing ${PKG} globally...`);
   }
@@ -48,7 +48,7 @@ function main() {
     env: { ...process.env, PIPPIT_CLI_SKIP_SKILLS: "1" },
   });
 
-  console.log("Installing pippit-cli skills...");
+  console.log("Installing pippit-tool-cli skills...");
   try {
     installGlobalPackageSkills(DEFAULT_PKG);
   } catch (err) {
@@ -60,15 +60,15 @@ function main() {
     installGlobalPackageSkills(DEFAULT_PKG);
   }
 
-  const bin = whichPippitCli();
+  const bin = whichPippitToolCli();
   if (!bin) {
-    console.error("pippit-cli was installed, but no global command was found in npm prefix.");
+    console.error("pippit-tool-cli was installed, but no global command was found in npm prefix.");
     console.error("Check that npm's global bin directory is in PATH.");
     process.exit(1);
   }
 
-  console.log(`pippit-cli is ready: ${bin}`);
-  console.log("Try: pippit-cli short-drama +submit-run --message \"写一个短剧开头\"");
+  console.log(`pippit-tool-cli is ready: ${bin}`);
+  console.log("Try: pippit-tool-cli short-drama +submit-run --message \"写一个短剧开头\"");
 }
 
 main();

package/scripts/install.js

@@ -9,7 +9,7 @@ const { installSkillsFromRoot } = require("./skills");
 
 const VERSION = require("../package.json").version.replace(/-.*$/, "");
 const REPO = "Pippit-dev/cli";
-const NAME = "pippit-cli";
+const NAME = "pippit-tool-cli";
 const ROOT = path.join(__dirname, "..");
 const BIN_DIR = path.join(ROOT, "bin");
 
@@ -121,7 +121,7 @@ function install() {
 
   fs.mkdirSync(BIN_DIR, { recursive: true });
 
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pippit-cli-"));
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pippit-tool-cli-"));
   const archivePath = path.join(tmpDir, archiveName);
   try {
     download(releaseURL, archivePath);

package/scripts/run.js

@@ -6,7 +6,7 @@ const path = require("path");
 const { maybeWarnNewVersion } = require("./version-check");
 
 const ext = process.platform === "win32" ? ".exe" : "";
-const bin = path.join(__dirname, "..", "bin", "pippit-cli" + ext);
+const bin = path.join(__dirname, "..", "bin", "pippit-tool-cli" + ext);
 const args = process.argv.slice(2);
 
 const oldBin = bin + ".old";
@@ -50,7 +50,7 @@ if (args[0] === "install") {
       });
     } catch (_) {
       console.error(
-        "\nFailed to prepare pippit-cli binary.\n" +
+        "\nFailed to prepare pippit-tool-cli binary.\n" +
         "Make sure Go is installed and available in PATH, then retry.\n"
       );
       process.exit(1);

package/scripts/version-check.js

@@ -85,7 +85,7 @@ function maybeWarnNewVersion(args = [], opts = {}) {
   if (compareSemver(latest, current) <= 0) return;
 
   const warn = opts.warn || console.error;
-  warn(`[pippit-cli] New version available: ${current} -> ${latest}. Run: pippit-cli update`);
+  warn(`[pippit-tool-cli] New version available: ${current} -> ${latest}. Run: pippit-tool-cli update`);
 }
 
 module.exports = {

package/skills/short-drama/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pippit-short-drama-skill
-description: 使用 pippit-cli 的短剧场景能力提交和查询短剧创作任务。覆盖短剧生成、续写、改写、剧情扩展、人物设定、分集草稿、世界观设定、会话文件获取、文件资源下载等创作场景。当用户要求创作短剧、写短剧剧本、续写故事、修改剧情、补充角色设定、查询短剧任务进展、获取短剧会话文件或下载短剧文件资源，或提到 pippit-cli short-drama / 小云雀短剧时触发。
+description: 使用 pippit-tool-cli 的短剧场景能力提交和查询短剧创作任务。覆盖短剧生成、续写、改写、剧情扩展、人物设定、分集草稿、世界观设定、会话文件获取、文件资源下载等创作场景。当用户要求创作短剧、写短剧剧本、续写故事、修改剧情、补充角色设定、查询短剧任务进展、获取短剧会话文件或下载短剧文件资源，或提到 pippit-tool-cli short-drama / 小云雀短剧时触发。
 user-invocable: true
 metadata:
   {
@@ -9,7 +9,7 @@ metadata:
         "emoji": "📖",
         "requires":
           {
-            "bins": ["pippit-cli"]
+            "bins": ["pippit-tool-cli"]
           }
       }
   }
@@ -17,7 +17,7 @@ metadata:
 
 # 小云雀短剧创作
 
-通过 `pippit-cli short-drama` 命令提交短剧创作任务、上传参考文件，并行查询任务进展和会话产物文件，及时把重要资产下载到用户本地。
+通过 `pippit-tool-cli short-drama` 命令提交短剧创作任务、上传参考文件，并行查询任务进展和会话产物文件，及时把重要资产下载到用户本地。
 
 短剧场景面向剧情、人物、分集与画面化叙事创作，用户的原始需求通过 `--message` 发送给后端 Agent。后端 Agent 负责理解任务、编排流程和生成内容；用户侧 Agent 负责提交任务、并行查询进展与产物、主动下载重要资产并展示结果。
 
@@ -25,7 +25,7 @@ metadata:
 
 1. **提交短剧 Run 任务** - 创建新会话或向已有会话发送短剧创作需求。
 2. **查询会话进展** - 根据 `thread_id`、`run_id`、`after_seq` 拉取短剧任务消息列表。
-3. **上传文件** - 上传短剧相关参考文件，得到文件 ID，供后续任务引用。
+3. **上传文件** - 上传本地 `.doc` / `.txt` 参考文件，得到 `asset_id`，供后续任务引用。
 4. **获取会话文件** - 根据 `thread_id` 拉取会话文件列表，得到 `file_path`、`download_url`。这和查询会话进展同等重要。
 5. **下载重要资产** - 使用文件列表中的 `download_url` 下载资源，并按 `file_path` 写入用户本地目标文件路径。
 
@@ -33,7 +33,7 @@ metadata:
 
 ## 前置要求
 
-需要已安装 `pippit-cli`：
+需要已安装 `pippit-tool-cli`：
 
 ```bash
 npx @pippit-dev/cli@latest install
@@ -45,37 +45,47 @@ npx @pippit-dev/cli@latest install
 
 ```bash
 # 创建新会话并提交短剧创作需求
-pippit-cli short-drama +submit-run --message "创作一个赛博朋克短剧开头"
+pippit-tool-cli short-drama +submit-run --message "创作一个赛博朋克短剧开头"
 
 # 向已有会话追加新的短剧需求
-pippit-cli short-drama +submit-run --message "继续写下一集，重点描写主角的逃亡" --thread-id THREAD_ID
+pippit-tool-cli short-drama +submit-run --message "继续写下一集，重点描写主角的逃亡" --thread-id THREAD_ID
 
-# 携带已上传文件 ID 提交任务
-pippit-cli short-drama +submit-run --message "参考这个大纲写第一集" --asset-ids ASSET_ID
+# 携带已上传剧本文件 asset_id 提交任务；同一 thread_id 只允许一个剧本文件
+pippit-tool-cli short-drama +submit-run --message "参考这个大纲写第一集" --asset-ids ASSET_ID
 ```
 
 ### 2. 查询短剧任务进展
 
 ```bash
 # 查询会话消息列表
-pippit-cli short-drama +get-thread --thread-id THREAD_ID --run-id RUN_ID --after-seq 0
+pippit-tool-cli short-drama +get-thread --thread-id THREAD_ID --run-id RUN_ID --after-seq 0
 ```
 
 > `thread_id` 和 `run_id` 由 `+submit-run` 返回。`after-seq` 用于增量拉取消息，首次查询可使用 `0`。
 
 ### 3. 上传文件
 
-当用户提供短剧大纲、人物设定、世界观设定、已有分集或剧本等本地文件路径时，可先上传文件。
+当用户提供短剧大纲、人物设定、世界观设定、已有分集或剧本等本地参考文件时，可先上传文件。`+upload-file` 当前只接收本地文件路径，并且只支持 `.doc` 和 `.txt` 后缀；不要把 `.md`、`.pdf`、图片、视频或 URL 传给该命令。
 
 ```bash
-pippit-cli short-drama +upload-file --path /path/to/outline.md
+pippit-tool-cli short-drama +upload-file --path /path/to/outline.txt
 ```
 
+上传成功后命令只返回 `asset_id`：
+
+```json
+{
+  "asset_id": "asset_..."
+}
+```
+
+后续提交任务时，把该值作为唯一的 `--asset-ids` 传给 `+submit-run`。单次创作会话中（相同 `thread_id`），只支持上传并绑定一个剧本文件；如果用户提供多个剧本文件，先让用户选择一个，或为不同剧本分别开启新的创作会话，不要在同一 `thread_id` 下重复追加剧本文件。
+
 ### 4. 获取会话文件
 
 ```bash
 # 获取会话文件列表
-pippit-cli short-drama +list-thread-file --thread-id THREAD_ID --page-num 1 --page-size 200
+pippit-tool-cli short-drama +list-thread-file --thread-id THREAD_ID --page-num 1 --page-size 200
 ```
 
 `+list-thread-file` 返回的每个文件对象包含：
@@ -93,7 +103,7 @@ pippit-cli short-drama +list-thread-file --thread-id THREAD_ID --page-num 1 --pa
 
 ```bash
 # 下载文件资源到指定文件路径
-pippit-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
 ```
 
 `FILE_PATH` 必须直接使用 `+list-thread-file` 返回的完整 `file_path`，包含文件名，不要取父目录。`+download-result` 负责把会话产生的文件通过 URL 下载到该目标文件路径；如果目标文件已存在，跳过下载。
@@ -103,12 +113,12 @@ pippit-cli short-drama +download-result --url DOWNLOAD_URL --output-path FILE_PA
 ### 场景 1：用户要求生成短剧内容
 
 ```
-1. pippit-cli short-drama +submit-run --message "用户的原始短剧需求"
+1. pippit-tool-cli short-drama +submit-run --message "用户的原始短剧需求"
    → 拿到 thread_id、run_id 和 web_thread_link
 2. 立即将 web_thread_link 展示给用户
 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 PAGE_NUM --page-size 200
+   a. pippit-tool-cli short-drama +get-thread --thread-id THREAD_ID --run-id RUN_ID --after-seq SEQUENCE
+   b. pippit-tool-cli short-drama +list-thread-file --thread-id THREAD_ID --page-num PAGE_NUM --page-size 200
 4. 检查 `get-thread` 返回的 messages：
    - 如果任务仍在进行中：展示过程消息，继续查询
    - 如果后端 Agent 提出问题：展示问题，等待用户回复
@@ -130,19 +140,22 @@ pippit-cli short-drama +download-result --url DOWNLOAD_URL --output-path FILE_PA
 ### 场景 2：用户提供参考文件要求创作
 
 ```
-1. pippit-cli short-drama +upload-file --path /path/to/file
-   → 拿到 file_id
-2. pippit-cli short-drama +submit-run --message "用户的原始短剧需求" --asset-ids file_id
+1. 检查用户提供的是一个本地 `.doc` 或 `.txt` 剧本文件路径；如果不是，告知当前上传命令只支持这两类文件，不要擅自转换或改写文件。
+2. pippit-tool-cli short-drama +upload-file --path /path/to/file.txt
+   → 拿到 asset_id
+3. pippit-tool-cli short-drama +submit-run --message "用户的原始短剧需求" --asset-ids asset_id
    → 拿到 thread_id、run_id 和 web_thread_link
-3. 后续同场景 1 的并行查询、重要资产发现和文件下载流程
+4. 记录该 thread_id 已绑定这个剧本文件；后续同一 thread_id 的续写或修改只传 --thread-id，不再传新的剧本 asset_id
+5. 后续同场景 1 的并行查询、重要资产发现和文件下载流程
 ```
 
 ### 场景 3：在已有短剧会话中续写或修改
 
 ```
-1. pippit-cli short-drama +submit-run --message "用户的新需求" --thread-id THREAD_ID
+1. pippit-tool-cli short-drama +submit-run --message "用户的新需求" --thread-id THREAD_ID
    → 拿到新的 run_id 和 web_thread_link
-2. 继续按场景 1 展示进展、处理用户补充问题、获取新增会话文件列表，并及时下载新增重要资产
+2. 如果该 THREAD_ID 已经绑定过剧本文件，不要再上传或通过 --asset-ids 追加第二个剧本文件
+3. 继续按场景 1 展示进展、处理用户补充问题、获取新增会话文件列表，并及时下载新增重要资产
 ```
 
 ## 轮询策略
@@ -202,17 +215,12 @@ pippit-cli short-drama +download-result --url DOWNLOAD_URL --output-path FILE_PA
 
 ```json
 {
-  "scene": "short-drama",
-  "file_id": "file_...",
-  "status": "uploaded",
-  "uploaded_at": "2026-05-19T00:00:00Z",
-  "request": {
-    "path": "/path/to/file",
-    "file_name": "file.md"
-  }
+  "asset_id": "asset_..."
 }
 ```
 
+`+upload-file` 通过 `multipart/form-data` 上传文件，表单文件字段名为 `file`。本地文件必须存在、不能是目录，后缀必须是 `.doc` 或 `.txt`；不支持的后缀会直接报错。返回的 `asset_id` 来自服务端 `pippit_asset_id`，如果没有该字段才回退到 `asset_id`。
+
 **+list-thread-file** 返回：
 
 ```json
@@ -264,7 +272,7 @@ pippit-cli short-drama +download-result --url DOWNLOAD_URL --output-path FILE_PA
 
 对带 `download_url` 的重要资产调用下载工具，可并行。重要资产必须主动下载，不要等用户再次要求，也不要在调用下载工具前先检查本地文件是否存在。
 
-1. 调用 `pippit-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`。
 2. 下载完成后，向用户展示本地文件路径；如果某个文件下载失败，记录失败项并在后续轮询中重试，不阻塞已成功落盘的文件展示。
 
 ## 向用户展示内容
@@ -283,8 +291,8 @@ pippit-cli short-drama +download-result --url DOWNLOAD_URL --output-path FILE_PA
 
 你要做的只有三件事：
 
-1. **上传**：如果用户给了本地参考文件，先调用 `+upload-file`。
-2. **提交任务**：把用户原始短剧需求和文件 ID 通过 `+submit-run` 发给后端。
+1. **上传**：如果用户给了本地 `.doc` / `.txt` 参考文件，先调用 `+upload-file`。
+2. **提交任务**：首次创作时把用户原始短剧需求和唯一剧本 `asset_id` 通过 `+submit-run --asset-ids` 发给后端；同一 `thread_id` 后续续写或修改不再追加新的剧本文件。
 3. **传话、取文件、下载资源**：根据 `+get-thread` 返回的消息展示进展、问题和结果；根据 `+list-thread-file` 获取文件列表；再根据 `download_url` 调用 `+download-result` 把缺失资源下载到用户本地。
 
 **不要做的事：**
@@ -301,7 +309,9 @@ pippit-cli short-drama +download-result --url DOWNLOAD_URL --output-path FILE_PA
 - `--message` 是用户的原始短剧需求，不能为空。
 - 查询进展时优先使用 `+submit-run` 返回的 `thread_id` 和 `run_id`。
 - `--after-seq` 用于增量拉取消息，首次查询可设置为 `0`。
-- `+upload-file` 当前用于短剧场景文件上传链路，上传后将返回可传给 `+submit-run` 的文件 ID。
+- `+upload-file` 当前用于短剧场景文件上传链路，只支持本地 `.doc` / `.txt` 文件；`--path` 不能为空，路径必须指向真实文件，不能是目录。
+- `+upload-file` 上传成功后只返回 `asset_id`；把该值原样作为 `+submit-run --asset-ids` 的参数。
+- 单次创作会话中（相同 `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` 必须是包含文件名的目标文件路径。