小云雀短剧创作

使用小云雀官方 CLI 提交和查询短剧创作任务，支持剧本生成、续写改写、剧情扩展、人物设定、分集草稿、世界观设定及会话产物下载。需安装 pippit-tool-cli 并使用本人小云雀账号登录，生成任务按账号权益消耗积分。

通过 pippit-tool-cli short-drama 命令提交短剧创作任务、上传参考文件，并行查询任务进展和会话产物文件，及时把重要资产下载到用户本地。

短剧场景面向剧情、人物、分集与画面化叙事创作，用户的原始需求通过 --message 发送给后端 Agent。后端 Agent 负责理解任务、编排流程和生成内容；用户侧 Agent 负责提交任务、并行查询进展与产物、主动下载重要资产并展示结果。

宿主来源统计

调用 short-drama +submit-run 时，宿主 Agent 根据可信的实际运行环境静默附加可选 --source：豆包办公为 doubao_office，WorkBuddy 为 workbuddy，Codex 为 codex；其它已知宿主使用真实、稳定的产品标识。不附带版本、会话 ID、用户信息或 prompt，不从用户创作内容猜测来源，不向用户询问或增加确认。来源不明时省略；仅用于统计，不影响实际工具效果，不改写 --message。上传、查询和下载命令不附加此参数。旧版 CLI 以 --help 为准，不支持时省略，不因统计字段阻塞任务或重复提交。

功能

1. 提交短剧 Run 任务 - 创建新会话或向已有会话发送短剧创作需求。
2. 查询会话进展 - 根据 thread_id 和可选 run_id 拉取服务端 v2 readable_text，用于展示短剧任务进展、问题和结果。
3. 上传文件 - 上传本地 .doc / .docx / .txt 参考文件，得到 asset_id，供后续任务引用。
4. 获取会话文件 - 根据 thread_id 拉取会话文件列表，得到 file_path、download_url。这和查询会话进展同等重要。
5. 下载重要资产 - 使用文件列表中的 download_url 下载资源，并按 file_path 写入用户本地目标文件路径。

重要资产包括但不限于：剧本设计、场景设计、场景图、人物角色设计、人物图、分集草稿、故事板、最终视频产物。只要 list-thread-file 返回了这些资产的 download_url，就要及时调用下载工具落盘，不要只展示文件元信息。

短剧主流程顺序

短剧创作按以下主流程推进。用户侧 Agent 在展示后端 Agent 的表单、问卷、选项或确认问题时，必须先参考这个顺序判断当前阶段和合理下一步。

1. 剧本上传 / AI 剧本生成 / AI 剧本编辑
2. 剧本合并与完整剧本确认
3. 剧本分析
4. 短剧风格推荐确认
5. 剧本标准化（可选）
6. 场景分析
7. 所有必要场景图生成
8. 角色分析
9. 所有必要角色图生成
10. 分镜设计
11. 分镜视频生成
12. 完整视频合成

表单与问卷选项处理原则

后端 Agent 通过 readable_text 发出表单、问卷、选项、按钮或询问用户时，用户侧 Agent 不要机械原样转述所有选项。先结合短剧主流程顺序清洗选项，再把合理、必要、当前可执行的流程项呈现给用户。

• 保留当前阶段的确认项，以及不会跳过必要阶段的下一步流程项。
• 剔除跳过必要阶段的选项。例如未完成“剧本合并与完整剧本确认”前，不应让用户直接进入“剧本分析”；未完成“所有必要场景图生成”前，不应让用户直接进入“角色分析”。
• 剔除倒退到无关阶段的选项。只有用户明确要求返工、修改或重新生成时，才展示回退选项。
• 剧本标准化 是可选阶段，只能出现在“短剧风格推荐确认”之后、“场景分析”之前。不要把它包装成任意阶段都可以跳过或补做的通用选项。
• 不替用户决定创意内容，例如风格、剧情方向、角色设定、镜头方案。只能清洗流程选项，不能代替用户选择创作偏好。
• 如果服务端问题混入跨度过大的多个流程选项，重新组织成当前阶段可回答的问题，并说明已按主流程剔除不合理或跳跃选项。

宿主提问工具优先

当后端 Agent 通过 readable_text 要求用户补充信息、选择选项、确认流程或确认创意内容时，优先使用当前宿主提供的 ask-question / confirmation / form 类工具向用户提问，而不是只在普通聊天里输出问题。

按宿主选择准确工具：

• Codex：优先调用 request_user_input。仅在工具已暴露且当前模式允许时调用；不可用时退回普通聊天提问。不要在 Codex 中调用 ask_user_question。
• WorkBuddy：优先调用 ask_user_question（Ask User Question）；工具未暴露时才退回普通聊天提问。
• Trae 及其他宿主：先查看当前宿主实际暴露的工具，再使用同类结构化提问、确认或表单工具；不要臆造具体工具名。没有同类工具时退回普通聊天提问。

使用宿主提问工具前，先按“表单与问卷选项处理原则”清洗问题和选项：

• 只把当前阶段合理、必要、可执行的选项放进提问工具。
• 不把已剔除的跳跃流程、倒退流程或不合理选项放进提问工具。
• 对普通开放问题，用单个清晰问题询问用户；对明确互斥选项，用宿主支持的选择控件。
• 如果当前宿主没有暴露可调用的 ask-question / confirmation / form 工具，才退回普通聊天提问，并说明需要用户回复后才能继续。

真实提交将进入消耗 credits 的图片生成、视频生成或编辑阶段时，如果用户本轮尚未明确确认执行，必须使用上述工具征得明确确认。不要设置默认同意、自动选择或超时后继续；纯文本规划和查询进展不需要额外确认。

前置要求

需要已安装 pippit-tool-cli：

bash

npx @pippit-dev/cli@latest install

首次使用原生 CLI 时运行网页登录；CLI 会自动申请或复用本机专属凭证，并保存到系统安全凭证库，不要求用户复制 Access Key：

bash

pippit-tool-cli login

XYQ_ACCESS_KEY 仅保留给 CI、Agent 等非交互环境作为显式覆盖。若该环境变量已设置但无效，CLI 不会静默改用个人网页登录凭证；应先修正或取消该环境变量。

小云雀界面打开契约

+submit-run 返回 web_thread_link 后，用户侧 Agent 必须优先把小云雀短剧 WebUI 打开给用户，而不是只展示链接。

按当前宿主适配打开方式：

Codex Desktop

1. 如果 browser:control-in-app-browser skill 可用，先读取并按该 skill 连接 Codex in-app browser。
2. 使用 in-app browser 打开 web_thread_link，并让浏览器可见。
3. 继续执行 get-thread、list-thread-file 和 download-result；打开 WebUI 不替代 CLI 轮询和产物下载。

WorkBuddy

1. 如果当前 WorkBuddy 会话暴露内置浏览器或页面打开能力，使用宿主提供的能力打开 web_thread_link。
2. 不要套用 Codex Desktop 的 browser:control-in-app-browser、node_repl 或 agent.browsers.get("iab") 实现。
3. 如果 WorkBuddy 当前没有暴露可调用浏览器工具，说明无法自动打开，并把 web_thread_link 交给用户在 WorkBuddy 内置浏览器或普通浏览器中打开。

TRAE Work

1. 如果当前 TRAE Work 会话暴露内置浏览器或页面打开能力，使用宿主提供的能力打开 web_thread_link。
2. 不要套用 Codex Desktop 的 in-app browser 实现。
3. 如果 TRAE Work 当前没有暴露可调用浏览器工具，说明无法自动打开，并把 web_thread_link 交给用户手动打开。

其他宿主或未知环境

如果没有明确的宿主浏览器能力、工具不可用或连接失败：

• 明确说明未能自动打开小云雀界面的具体原因。
• 仍然把 web_thread_link 展示给用户，作为手动打开入口。
• 不要因此跳过后续进展查询和文件下载。

打开界面的目的只是让用户能进入小云雀编辑/确认界面做视觉 review、流程确认或手动调整；短剧任务提交、状态查询和重要资产落盘仍以 pippit-tool-cli 为准。

使用方法

1. 提交短剧任务

bash

# 创建新会话并提交短剧创作需求
pippit-tool-cli short-drama +submit-run --message "创作一个赛博朋克短剧开头"

# 向已有会话追加新的短剧需求
pippit-tool-cli short-drama +submit-run --message "继续写下一集，重点描写主角的逃亡" --thread-id THREAD_ID

# 携带已上传剧本文件 asset_id 提交任务；同一 thread_id 只允许一个剧本文件
pippit-tool-cli short-drama +submit-run --message "参考这个大纲写第一集" --asset-ids ASSET_ID

2. 查询短剧任务进展

bash

# 查询会话可读进展
pippit-tool-cli get-thread --thread-id THREAD_ID --run-id RUN_ID

thread_id 和 run_id 由 +submit-run 返回。run_id 可省略，省略时返回当前 thread_id 下的所有 Run；传入时只看指定 Run。

3. 上传文件

当用户提供短剧大纲、人物设定、世界观设定、已有分集或剧本等本地参考文件时，可先上传文件。+upload-file 当前只接收本地文件路径，并且只支持 .doc、.docx 和 .txt 后缀；不要把 .md、.pdf、图片、视频或 URL 传给该命令。

bash

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-tool-cli list-thread-file --thread-id THREAD_ID --page-num 1 --page-size 200

list-thread-file 返回的每个文件对象包含：

json

{
  "file_path": "./{thread-id}/路径/文件名", // 文件完整路径，包含文件名
  "download_url": "https://...", // URL
  "updated_at": 1779716734 // 文件更新时间，Unix 秒级时间戳
}

list-thread-file 只负责获取会话文件列表，不负责下载文件，也不需要判断本地文件是否已存在。

5. 下载文件资源

bash

# 下载文件资源到指定文件路径
pippit-tool-cli download-result --url DOWNLOAD_URL --output-path FILE_PATH --updated-at UPDATED_AT

FILE_PATH 必须直接使用 list-thread-file 返回的完整 file_path，包含文件名，不要取父目录。UPDATED_AT 使用同一文件对象返回的 updated_at；如果没有 updated_at，可省略 --updated-at。download-result 负责把会话产生的文件通过 URL 下载到该目标文件路径；如果目标文件已存在且本地修改时间不早于 updated_at，跳过下载；如果本地文件早于 updated_at，覆盖更新。

典型工作流

场景 1：用户要求生成短剧内容

text

1. pippit-tool-cli short-drama +submit-run --message "用户的原始短剧需求"
   → 拿到 thread_id、run_id 和 web_thread_link
2. 立即展示 web_thread_link，并按“小云雀界面打开契约”优先用 in-app browser 打开该链接
3. 并行发起，二者同等重要：
   a. pippit-tool-cli get-thread --thread-id THREAD_ID --run-id RUN_ID
   b. pippit-tool-cli list-thread-file --thread-id THREAD_ID --page-num PAGE_NUM --page-size 200
4. 检查 `get-thread` 返回的 readable_text：
   - 如果任务仍在进行中：展示可读进展，继续查询
   - 如果后端 Agent 提出问题：从 readable_text 中提取问题并展示，等待用户回复
5. 检查 `list-thread-file` 返回的 files：
   - 对每个文件取 file_path、download_url、updated_at
   - 将 file_path 作为本地目标文件路径，包含文件名
   - 有 download_url 的重要资产：加入本轮下载队列
   - 不判断 file_path 在本地是否已存在，是否跳过由 download-result 内部处理
   - 如果本轮 total 达到 200：下一轮将 PAGE_NUM 加 1，继续查询新一页文件
6. 对重要资产，立即调用 download-result 并行下载资源：
   - 使用第 5 步获取的 download_url 作为 --url
   - 使用第 5 步获取的完整 file_path 作为 --output-path
   - 如果第 5 步返回 updated_at，作为 --updated-at 传入
   - 剧本设计、场景设计、场景图、人物角色设计、人物图、最终视频产物都属于重要资产
7. 查询或下载失败时，不要直接放弃；记录失败项，并在后续轮询中主动重试
8. 只有会话进展已处理，且已发现的重要资产均已下载或明确重试失败后，才向用户汇总最终结果
9. 如用户继续追加需求，使用同一 thread_id 再次 submit-run

场景 2：用户提供参考文件要求创作

text

1. 检查用户提供的是一个本地 `.doc`、`.docx` 或 `.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
4. 立即展示 web_thread_link，并按“小云雀界面打开契约”优先用 in-app browser 打开该链接
5. 记录该 thread_id 已绑定这个剧本文件；后续同一 thread_id 的续写或修改只传 --thread-id，不再传新的剧本 asset_id
6. 后续同场景 1 的并行查询、重要资产发现和文件下载流程

场景 3：在已有短剧会话中续写或修改

text

1. pippit-tool-cli short-drama +submit-run --message "用户的新需求" --thread-id THREAD_ID
   → 拿到新的 run_id 和 web_thread_link
2. 立即展示 web_thread_link，并按“小云雀界面打开契约”优先用 in-app browser 打开该链接
3. 如果该 THREAD_ID 已经绑定过剧本文件，不要再上传或通过 --asset-ids 追加第二个剧本文件
4. 继续按场景 1 展示进展、处理用户补充问题、获取新增会话文件列表，并及时下载新增重要资产

轮询策略

• 间隔：每 10 秒查询一次。
• 进展查询：每轮调用 get-thread 查看 readable_text。优先带上本轮 run_id 聚焦当前任务；需要查看整个会话时可省略 --run-id。
• 并行查询：每次 +submit-run 返回 thread_id 后，同时发起 get-thread 和 list-thread-file；二者同等重要，不能只查询会话进展而忽略会话文件。
• 文件分页：list-thread-file 使用 --page-size 200。如果本轮返回的 total 达到 200，下一轮使用 --page-num 加 1 查询新一页结果；如果未达到 200，保持当前页继续轮询新增产物。
• 重要资产识别：每轮都检查 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 返回的 readable_text 作为结束条件。完成前必须同时检查：

1. 已处理 get-thread 返回的最新 readable_text、用户确认问题和最终消息。
2. 已展示 web_thread_link，并按当前宿主尝试打开小云雀 WebUI：Codex Desktop 用 in-app browser；WorkBuddy / TRAE Work 用各自宿主提供的内置浏览器或页面打开能力；如果不能自动打开，已说明原因并提供手动链接。
3. 已用 --page-size 200 调用 list-thread-file 获取会话文件列表；如果本轮 total 达到 200，已在后续轮询中递增 page-num 查询新一页。
4. 对所有带 download_url 的重要资产，已调用 download-result 下载到本地 file_path。
5. 已按短剧主流程顺序检查服务端表单、问卷和选项，没有把跳过必要阶段的选项直接呈现给用户；如果跳过 剧本标准化，已明确这是可选阶段。
6. 对查询失败或下载失败的资产，已在后续轮询中主动重试，并在最终回复中列出仍失败的文件或命令。

输出格式

+submit-run 返回：

json

{
  "thread_id": "thread_...",
  "run_id": "run_...",
  "web_thread_link": "https://xyq.jianying.com/..."
}

get-thread 返回：

text

Thread: thread_...
     标题: ...
     状态: ...

     -- Run #1 --
       [assistant] ...

short-drama +upload-file 返回：

json

{
  "asset_id": "asset_..."
}

+upload-file 通过 multipart/form-data 上传文件，表单文件字段名为 file。本地文件必须存在、不能是目录，后缀必须是 .doc、.docx 或 .txt；不支持的后缀会直接报错。返回的 asset_id 来自服务端 pippit_asset_id，如果没有该字段才回退到 asset_id。

list-thread-file 返回：

json

{
  "files": [
    {
      "file_path": "./{thread-id}/{file_path}/{file_name}",
      "download_url": "https://...",
      "updated_at": 1779716734
    }
  ],
  "total": 1,
  "message": "<system-remind>\n- total reached 200; query the next page with --page-num {page-num} + 1\n</system-remind>"
}

当 total 达到 200 时，message 会用 <system-remind> 提示下一轮将 page-num 加 1 查询新一页。

download-result 返回：

json

{
  "output_path": "./{thread-id}/{file_path}/{file_name}",
  "downloaded": ["./{thread-id}/{file_path}/{file_name}"]
}

会话文件与资源下载

先用 list-thread-file 获取会话文件列表，再用 download-result 并行下载重要资产。获取文件元信息不是最终目标，重要资产落盘才是核心目标。文件是否已存在由下载工具内部检查，list-thread-file 阶段不要做本地存在性判断。

获取会话文件

从 list-thread-file 的 files 中逐个读取文件元信息：file_path、file_name、download_url、updated_at。重点识别剧本设计、场景设计、场景图、人物角色设计、人物图、分集草稿、故事板、最终视频产物等重要资产。

text

1. 有download_url的重要资产
   → 记录该file_path、URL和updated_at
   → 使用 download-result 将URL资源下载到该file_path；有updated_at时传入--updated-at
2. 本轮total达到200
   → 下一轮page-num加1，继续查询新一页结果
3. 本轮total未达到200
   → 后续轮询保持当前页，继续发现新增产物
4. list-thread-file或download-result失败
   → 记录失败参数和错误
   → 后续轮询主动重试，不要直接结束任务

并行下载文件资源

对带 download_url 的重要资产调用下载工具，可并行。重要资产必须主动下载，不要等用户再次要求，也不要在调用下载工具前先检查本地文件是否存在。

1. 调用 pippit-tool-cli download-result --url DOWNLOAD_URL --output-path FILE_PATH --updated-at UPDATED_AT；如果文件对象没有 updated_at，省略 --updated-at。
2. 下载完成后，向用户展示本地文件路径；如果某个文件下载失败，记录失败项并在后续轮询中重试，不阻塞已成功落盘的文件展示。

向用户展示内容

• 任务提交后：立即展示 web_thread_link。
• 在支持内置浏览器或页面打开能力的宿主中：任务提交后按“小云雀界面打开契约”优先打开 web_thread_link，让用户能进入小云雀 WebUI 查看和调整；不同宿主只使用各自提供的浏览器能力，不复用 Codex Desktop 的实现细节。
• 任务进行中：展示后端 Agent 返回的过程消息。
• 需要用户补充信息时：如果是普通问题，按“宿主提问工具优先”提问并等待用户回复；如果包含表单、问卷、选项或按钮，先按短剧主流程清洗不合理或跳跃的流程选项，再用宿主提问工具呈现；没有可用提问工具时才退回普通聊天。
• 任务完成后：展示短剧内容、分集草稿、设定说明或其他结果信息，同时检查是否有未下载的重要资产。
• 获取会话文件后：展示或记录文件元信息，不把它当成已下载结果。
• 文件资源下载后：展示已落盘的本地文件路径；已存在而跳过下载的文件也要标明。
• 如果仍有重要资产下载失败：说明失败文件、失败命令和已进行的重试，不要把它描述为已完成下载。

核心原则：用户侧不做创作，只做传话

你（用户侧 Agent）的职责是传递用户需求和展示后端结果，不是替后端 Agent 创作短剧。

你要做的只有三件事：

1. 上传：如果用户给了本地 .doc / .docx / .txt 参考文件，先调用 +upload-file。
2. 提交任务：首次创作时把用户原始短剧需求和唯一剧本 asset_id 通过 +submit-run --asset-ids 发给后端；同一 thread_id 后续续写或修改不再追加新的剧本文件。
3. 传话、取文件、下载资源：根据 get-thread 返回的 readable_text 展示进展、问题和结果；遇到表单、问卷、选项或按钮时，只做流程合理性清洗，不替用户决定创作内容；根据 list-thread-file 获取文件列表；再根据 download_url 调用 download-result 把缺失资源下载到用户本地。

不要做的事：

• 不要替用户扩写、润色、翻译 prompt。
• 不要自行编排剧情、人物关系、世界观或分集大纲后再提交。
• 不要把用户的一个需求拆成多次 +submit-run，除非用户明确要求分多次处理。
• 不要将自己编写的短剧内容混入后端返回结果。

后端 Agent 会负责理解短剧任务、组织创作流程和生成内容。用户侧 Agent 越俎代庖会降低结果一致性。

注意事项

• --message 是用户的原始短剧需求，不能为空。
• 查询进展时优先使用 +submit-run 返回的 thread_id 和 run_id；如果需要查看整个会话，可以省略 --run-id。
• get-thread 当前固定走服务端 v2 响应，输出字段是 readable_text；不要解析旧版 messages 数组。
• +upload-file 当前用于短剧场景文件上传链路，只支持本地 .doc / .docx / .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、--updated-at、--workers；--output-path 必须是包含文件名的目标文件路径。