pippit-skill

Pippit 技能工作流

使用这项独立技能处理面向海外的 Pippit.ai 工作流。它在本地包含两组后端脚本：

• scripts/nest/：Pippit Nest AI 生成、编辑、参考素材上传、进度轮询和结果下载。
• scripts/publish/：社交账号查询、视频上传、定时发布、任务增删改查和分析。

无需外部 Pippit 技能目录。运行本地命令时，将 {baseDir} 解析为此技能文件夹。有关发布载荷字段的详细信息，请阅读 references/publishing-api.md。

Pippit Nest 负责创意解读、提示词扩展、模型选择、分镜制作和工作流路由。本地 Agent 只需上传参考素材、传递用户请求、轮询进度、处理澄清请求、下载结果，然后在用户提出要求时发布选定的视频。

路由请求

• 仅创作：使用 scripts/nest/ 生成或编辑、轮询并下载输出。返回本地文件后即停止，除非用户要求发布。
• 仅发布：使用 scripts/publish/ 处理现有本地视频、已绑定账号检查、定时发布、任务增删改查或分析。
• 从创作到发布：先使用 scripts/nest/，下载生成的视频，然后使用 scripts/publish/ 上传并安排发布时间。
• 仅图像输出：仅支持发布视频。如果用户想发布图片或海报，请询问是否要先将其生成为视频或转换为视频。

处理创作请求

• 将用户的创作或编辑请求原样传递给 scripts/nest/submit_run.py --message。除非用户明确要求，否则不要压缩、总结、改写、润色、翻译或拆分请求，也不要添加提示词内容。
• 一项创作任务只提交一次 Nest。除非用户明确要求分别运行，否则不要将单个请求拆分成逐镜头、逐场景或逐素材的运行任务。
• 不要在本地手动编写分镜、推断摄像方案、分析风格、选择模型或编排子提示词。让 Pippit Nest 完成这些工作。
• 提供参考图像或视频时，先上传它们，再附上返回的素材 ID 提交原始请求。不要用自己的描述替换用户对参考素材的表述。
• Pippit 要求澄清或交互时，将问题展示给用户，并把用户的回答提交到同一个 thread_id；不要代替用户作答。

访问密钥

创建和发布均使用同一个 Pippit 访问密钥。按以下顺序查找：

1. PIPPIT_ACCESS_KEY
2. PippitAccessKey
3. $CODEX_HOME/pippit-skill/secrets.json 中的本地缓存

使用以下任一本地保存脚本保存新密钥：

python3 {baseDir}/scripts/nest/save_access_key.py --access-key "..."

不要编造、获取或回显完整访问密钥。如果没有可用密钥，请用英文回复：“No Pippit access key is configured. Please get one from https://www.pippit.ai, then provide it or save it before continuing.”

端到端流程

1. 收集最少的缺失信息：
   • 创意需求以及任何参考图片／视频文件
   • 目标平台：TikTok、Facebook Page 或 Instagram
   • 已绑定的平台账号
   • 标题或说明文字
   • 发布模式：默认发布，除非用户明确要求定时发布
   • 对于定时发布：包含时区的定时发布时间
2. 对于 Pippit 生成／编辑，告知用户此操作会消耗积分，并在调用 submit_run.py 前等待用户明确确认。
3. 如果用户提供了参考文件，使用 scripts/nest/upload_file.py 逐个上传。
4. 将用户的原始创意需求作为单个 scripts/nest/submit_run.py --message 值提交，并在有已上传资源时附上其 ID。
5. 返回 web_thread_link（若有），然后使用 scripts/nest/get_thread.py 同时传入 thread_id 和 run_id 进行轮询。
6. 如果 Pippit 请求澄清或交互，将问题展示给用户，并把用户的回答提交到同一线程。
7. 使用 scripts/nest/download_results.py 下载生成结果的 URL。
8. 选择要发布的生成视频文件。如果有多个视频且用户尚未指定，请让用户选择。
9. 使用 scripts/publish/list_user_platform_account.py 列出已绑定的社交账号。如果没有可用账号，请停止操作，并引导用户在 Pippit 上绑定账号。
10. 使用 scripts/publish/upload_file.py 上传最终的本地视频。
11. 如果用户没有提到定时安排，则按默认发布处理；不要询问用户选择发布模式。
12. 对于默认发布，将其转换为明确的近期定时时间；默认设为当前本地时间加 5 分钟，并向上取整到下一分钟，除非用户要求其他较短延迟。对于定时发布，必须提供包含时区的明确绝对发布时间。
13. 重述平台、账号、视频文件、说明文字／标题、发布模式和绝对定时时间。仅当平台／账号／视频／说明文字缺失或含糊，或用户要求定时发布但未提供具体时间时，才等待确认。不要仅仅因为默认发布模式或其近期定时时间是推断得出的就询问用户。
14. 使用 scripts/publish/batchcreate_schedule_task.py 创建定时任务。Pippit 仅支持定时发布；绝不要声称可以立即发布。
15. 返回任务 ID／状态、生成的本地文件路径以及 Pippit 线程链接。如果采用了默认发布，简要说明也支持定时发布。

本地命令

完整命令示例请参阅 references/command-map.md。常用命令：

python3 {baseDir}/scripts/nest/submit_run.py --message "Create a product video..."
python3 {baseDir}/scripts/nest/get_thread.py --thread-id THREAD_ID --run-id RUN_ID --after-seq 0
python3 {baseDir}/scripts/nest/download_results.py --urls URL1 URL2 --output-dir ./pippit_output --prefix artifact
python3 {baseDir}/scripts/publish/list_user_platform_account.py
python3 {baseDir}/scripts/publish/upload_file.py /path/to/video.mp4
python3 {baseDir}/scripts/publish/batchcreate_schedule_task.py --platform tiktok --platform-user-id PLATFORM_USER_ID --asset-id ASSET_ID --title "TITLE_OR_CAPTION" --schedule-time "2026-05-15T20:00:00+08:00"

发布规则

• 仅通过 scripts/publish/ 发布视频。
• 将未指定的发布模式视为默认发布。默认发布意为“尽快发布”，仍必须通过近期定时任务实现。
• 如果没有平台账号、说明文字／标题、发布模式和明确的绝对定时时间，不要创建定时任务。对于默认发布，创建任务前先计算近期定时的绝对时间。
• 成功创建默认发布任务后，简短说明也支持定时发布。
• 定时发布前，将“今天”“明天”或“下周五”等相对日期转换为绝对日期。
• 对于 TikTok、Instagram 或 Facebook 专属设置，请使用脚本标志和 JSON 覆盖选项。不要猜测复杂的平台负载；请先阅读 references/publishing-api.md。
• 单次批量创建最多支持 10 个任务。更大的批次请有计划地拆分。

后续操作

• 若要更新、删除或列出已安排的任务，请使用 scripts/publish/ 中的任务脚本，并在查询中保留平台和 platform_user_id。
• 若要分析已发布的帖子，请使用 scripts/publish/list_videos.py；在有数据时，汇总标题、平台、发布时间、观看量、点赞数、评论数、分享数和互动率。
• 若要在发布前优化生成的素材，请使用 scripts/nest/submit_run.py --thread-id 继续同一个 Pippit Nest 线程。

输出要求

面向用户的回复应简洁，但需包含他们需要的操作标识：

• Nest 生成：thread_id、run_id、web_thread_link、已下载的本地文件
• 发布：平台、platform_user_id、已上传的 asset_id、任务 ID、任务状态、预定时间
• 分析：平台、账号、视频标题、发布时间、核心指标

除非相关本地脚本返回成功，否则不要声称生成、上传或发布任务已成功。