xyq-short-drama-skill
使用 pippit-tool-cli 的短剧场景能力提交和查询短剧创作任务。覆盖短剧生成、续写、改写、剧情扩展、人物设定、分集草稿、世界观设定、会话文件获取、文件资源下载等创作场景。当用户要求创作短剧、写短剧剧本、续写故事、修改剧情、补充角色设定、查询短剧任务进展、获取短剧会话文件或下载短剧文件资源,或提到 pippit-tool-cli short-drama / 小云雀短剧时触发。
Pippit-dev · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Pippit-dev/cli --skill xyq-short-drama-skill技能说明
name: xyq-short-drama-skill description: 使用 pippit-tool-cli 的短剧场景能力提交和查询短剧创作任务。覆盖短剧生成、续写、改写、剧情扩展、人物设定、分集草稿、世界观设定、会话文件获取、文件资源下载等创作场景。当用户要求创作短剧、写短剧剧本、续写故事、修改剧情、补充角色设定、查询短剧任务进展、获取短剧会话文件或下载短剧文件资源,或提到 pippit-tool-cli short-drama / 小云雀短剧时触发。 user-invocable: true metadata: { "openclaw": { "emoji": "📖", "requires": { "bins": ["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 为准,不支持时省略,不因统计字段阻塞任务或重复提交。
功能
- 提交短剧 Run 任务 - 创建新会话或向已有会话发送短剧创作需求。
- 查询会话进展 - 根据
thread_id和可选run_id拉取服务端 v2readable_text,用于展示短剧任务进展、问题和结果。 - 上传文件 - 上传本地
.doc/.docx/.txt参考文件,得到asset_id,供后续任务引用。 - 获取会话文件 - 根据
thread_id拉取会话文件列表,得到file_path、download_url。这和查询会话进展同等重要。 - 下载重要资产 - 使用文件列表中的
download_url下载资源,并按file_path写入用户本地目标文件路径。
重要资产包括但不限于:剧本设计、场景设计、场景图、人物角色设计、人物图、分集草稿、故事板、最终视频产物。只要 list-thread-file 返回了这些资产的 download_url,就要及时调用下载工具落盘,不要只展示文件元信息。
短剧主流程顺序
短剧创作按以下主流程推进。用户侧 Agent 在展示后端 Agent 的表单、问卷、选项或确认问题时,必须先参考这个顺序判断当前阶段和合理下一步。
- 剧本上传 / AI 剧本生成 / AI 剧本编辑
- 剧本合并与完整剧本确认
- 剧本分析
- 短剧风格推荐确认
- 剧本标准化(可选)
- 场景分析
- 所有必要场景图生成
- 角色分析
- 所有必要角色图生成
- 分镜设计
- 分镜视频生成
- 完整视频合成
表单与问卷选项处理原则
后端 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:
npx @pippit-dev/cli@latest install
首次使用原生 CLI 时运行网页登录;CLI 会自动申请或复用本机专属凭证,并保存到系统安全凭证库,不要求用户复制 Access Key:
pippit-tool-cli login
XYQ_ACCESS_KEY 仅保留给 CI、Agent 等非交互环境作为显式覆盖。若该环境变量已设置但无效,CLI 不会静默改用个人网页登录凭证;应先修正或取消该环境变量。
小云雀界面打开契约
+submit-run 返回 web_thread_link 后,用户侧 Agent 必须优先把小云雀短剧 WebUI 打开给用户,而不是只展示链接。
按当前宿主适配打开方式:
Codex Desktop
- 如果
browser:control-in-app-browserskill 可用,先读取并按该 skill 连接 Codex in-app browser。 - 使用 in-app browser 打开
web_thread_link,并让浏览器可见。 - 继续执行
get-thread、list-thread-file和download-result;打开 WebUI 不替代 CLI 轮询和产物下载。
WorkBuddy
- 如果当前 WorkBuddy 会话暴露内置浏览器或页面打开能力,使用宿主提供的能力打开
web_thread_link。 - 不要套用 Codex Desktop 的
browser:control-in-app-browser、node_repl或agent.browsers.get("iab")实现。 - 如果 WorkBuddy 当前没有暴露可调用浏览器工具,说明无法自动打开,并把
web_thread_link交给用户在 WorkBuddy 内置浏览器或普通浏览器中打开。
TRAE Work
- 如果当前 TRAE Work 会话暴露内置浏览器或页面打开能力,使用宿主提供的能力打开
web_thread_link。 - 不要套用 Codex Desktop 的 in-app browser 实现。
- 如果 TRAE Work 当前没有暴露可调用浏览器工具,说明无法自动打开,并把
web_thread_link交给用户手动打开。
其他宿主或未知环境
如果没有明确的宿主浏览器能力、工具不可用或连接失败:
- 明确说明未能自动打开小云雀界面的具体原因。
- 仍然把
web_thread_link展示给用户,作为手动打开入口。 - 不要因此跳过后续进展查询和文件下载。
打开界面的目的只是让用户能进入小云雀编辑/确认界面做视觉 review、流程确认或手动调整;短剧任务提交、状态查询和重要资产落盘仍以 pippit-tool-cli 为准。
使用方法
1. 提交短剧任务
# 创建新会话并提交短剧创作需求
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. 查询短剧任务进展
# 查询会话可读进展
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 传给该命令。
pippit-tool-cli short-drama +upload-file --path /path/to/outline.txt
上传成功后命令只返回 asset_id:
{
"asset_id": "asset_..."
}
后续提交任务时,把该值作为唯一的 --asset-ids 传给 +submit-run。单次创作会话中(相同 thread_id),只支持上传并绑定一个剧本文件;如果用户提供多个剧本文件,先让用户选择一个,或为不同剧本分别开启新的创作会话,不要在同一 thread_id 下重复追加剧本文件。
4. 获取会话文件
# 获取会话文件列表
pippit-tool-cli list-thread-file --thread-id THREAD_ID --page-num 1 --page-size 200
list-thread-file 返回的每个文件对象包含:
{
"file_path": "./{thread-id}/路径/文件名", // 文件完整路径,包含文件名
"download_url": "https://...", // URL
"updated_at": 1779716734 // 文件更新时间,Unix 秒级时间戳
}
list-thread-file 只负责获取会话文件列表,不负责下载文件,也不需要判断本地文件是否已存在。
5. 下载文件资源
# 下载文件资源到指定文件路径
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,跳过下载;如果本地文件早于 `u