marswon/workbuddy-gettoken-seedance-skill

GetToken Seedance 2.0 视频生成

使用 scripts/gettoken_seedance.py 调用 GetToken 的 New API 异步视频接口。保持 GetToken 为唯一视频供应商；语言模型只负责提示词与编排。

路由原则

1. 遇到“使用 GetToken/自己的 Seedance API 生成视频”时触发本技能。
2. 需要写分镜或优化提示词时，先调用已安装的 seedance-video-prompt 技能，再把逐镜提示词交给本技能。
3. 不调用 /v1/chat/completions。Seedance 不是聊天模型。
4. 不调用 WorkRally、LibTV 或内置 VideoGen 代替 GetToken。
5. 不在回复、日志、命令参数或项目文件中输出 API Key。
6. 处理任何生成请求前，遵守 references/workbuddy_interaction_protocol.md 的模式枚举、两阶段确认和证据规则。
7. 用户未明确镜头数、模式或执行方式时先提问；不得自行假设“5 镜”“每镜 5 秒”或直接扣费生成。只有用户明确说“未填项使用默认值”时才使用默认参数。
8. WorkBuddy 本地后台 job ID 不是 GetToken task_id。只有得到 task_... 才能说“已提交”；MP4 实际存在只能证明“已生成”，短剧/漫剧还需 review-check 通过才能说“已验收”。
9. 用户提到短剧、漫剧、连续角色、剧本或多集内容时，必须读取 references/series_workflow.md，先建立项目、人物/场景/道具资产和确认门，不得从一句模糊需求直接猜镜头并付费生成。
10. 本技能只执行 GetToken 视频和原生音频。人物图生成、视频链接复刻、独立配音/字幕/BGM 和多镜剪辑尚未实现；可以规划这些资产，但必须明确能力边界。

前置检查

先执行不扣费检查：

python3 {baseDir}/scripts/gettoken_seedance.py doctor

只有返回 "ok": true 才继续。若未配置密钥，引导用户在 WorkBuddy 终端亲自执行：

python3 {baseDir}/scripts/gettoken_seedance.py configure

密钥保存到 ~/.config/gettoken-seedance/config.json，文件权限为 600。也可临时使用环境变量 GETTOKEN_API_KEY，但不要把密钥直接拼进命令。

单镜生成

文生视频：

python3 {baseDir}/scripts/gettoken_seedance.py generate \
  --prompt "<Seedance逐镜提示词>" \
  --duration 5 \
  --size 9:16 \
  --output-dir "<项目目录>/videos" \
  --name "EP01_SC01"

首帧图生视频：

python3 {baseDir}/scripts/gettoken_seedance.py generate \
  --prompt "<只描述动作、运镜和连续性>" \
  --image "<可公开访问的首帧URL>" \
  --duration 5 \
  --size 9:16 \
  --resolution 720p \
  --output-dir "<项目目录>/videos" \
  --name "EP01_SC01"

首尾帧过渡：

python3 {baseDir}/scripts/gettoken_seedance.py generate \
  --prompt "保持主体身份、服装和场景布局，只生成两帧之间的连续动作，镜头缓慢推进" \
  --first-frame "<可公开访问的首帧URL>" \
  --last-frame "<可公开访问的尾帧URL>" \
  --duration 5 \
  --size 9:16 \
  --resolution 720p \
  --output-dir "<项目目录>/videos" \
  --name "EP01_SC01"

首尾帧请求会同时发送 images，并在 metadata.content 中明确写入 role: first_frame 和 role: last_frame。size 会映射为豆包上游的 metadata.ratio，resolution 默认 720p。尾帧不能单独使用，--last-frame 必须配合 --first-frame。默认模型固定为 doubao-seedance-2-0-260128。

短剧与漫剧项目

短剧/漫剧不是普通 batch。先创建类似 assets/series-project.example.json 的项目文件；模板中的占位 URL 和 proposed 状态必须由用户素材与确认替换，不能直接生成。项目至少包含：

• project：类型、锁定模型、independent_shots 策略、画幅、分辨率、时长、语言、一致性和原生音频策略；换模型必须增加 revision 并重新确认。
• creative_bible：统一画风、色彩、节奏、全局禁止项和连续性规则。
• entities.characters：人物外观、服装版本、多角度参考图、声音和批准状态。
• entities.locations/props：场景布局、光线、关键道具和参考图。
• episodes/scenes/shots：分集、场次、叙事目的、角色/服装/场景引用、动作、对白、运镜、时长和首尾帧。
• approval_gates：短剧/漫剧默认要求 script_parse、character_assets、storyboard 已批准，并绑定当前内容 SHA-256。
• postproduction：剪辑、字幕、音频混合和最终交付由外部工具执行的状态，不得省略或冒充已完成。

每次用户确认后用 project-approve 绑定当前 revision 的内容摘要，不要只手改 status。例如：

python3 {baseDir}/scripts/gettoken_seedance.py project-approve "<project.json>" \
  --gate script_parse --approver "<用户>" --output "<project.json>"
python3 {baseDir}/scripts/gettoken_seedance.py project-approve "<project.json>" \
  --gate character_assets --approver "<用户>" --output "<project.json>"
python3 {baseDir}/scripts/gettoken_seedance.py project-approve "<project.json>" \
  --gate storyboard --approver "<用户>" --output "<project.json>"

实体内容或分镜素材变更后，原内容 SHA-256 会失效，必须重新确认并 approve。然后做离线检查：

python3 {baseDir}/scripts/gettoken_seedance.py project-check "<project.json>"

只有返回 ready_to_render: true 才编译：

python3 {baseDir}/scripts/gettoken_seedance.py project-compile "<project.json>" \
  --output "<shotlist.json>"
python3 {baseDir}/scripts/gettoken_seedance.py batch "<shotlist.json>" \
  --project-file "<project.json>" --dry-run

将 project-check 摘要、blockers、warnings 和 dry-run 计划交给用户确认。收到“确认生成”后才正式执行，并始终重新绑定原项目：

python3 {baseDir}/scripts/gettoken_seedance.py batch "<shotlist.json>" \
  --project-file "<project.json>" --output-dir "<videos目录>"

脚本会重算 project revision、审批状态、项目摘要和编译镜头摘要；旧 revision 或修改过的 shotlist 会被拒绝。

人物资产规则：

1. 重复角色必须有稳定外观描述、服装版本和 approved/locked 状态。
2. 小云雀手册说明最多上传 9 图且多角度人物图有助于一致性，但这是小云雀产品能力；当前 GetToken adapter 不会发送 reference_images/reference_urls，它们只用于资产登记和人工制作逐镜首帧。
3. 人物参考图、场景图、首帧和尾帧是不同概念，不得混用。只有逐镜 first_frame/last_frame 会被当前 adapter 发送给模型。
4. project-check 对参考图通过只表示 URL 与资产记录合法，不表示 Seedance 已看到这些图；禁止据此声称多角度参考已生效。
5. 当前技能不生成人物图。缺素材时列出待补 URL 或先进入独立图片流程，不得虚构图片。
6. 对写实真人脸素材先做合规确认；小云雀手册提示该类上传素材暂不支持。

音频可显式控制：

# 要求 Seedance 原生音频
python3 {baseDir}/scripts/gettoken_seedance.py generate ... --generate-audio

# 明确生成无声视频
python3 {baseDir}/scripts/gettoken_seedance.py generate ... --no-audio

对白、音效和配乐意图应写进逐镜项目。generate_audio=false 时不得同时要求对白、音效或配乐。独立 TTS、字幕文件、BGM 混音和多镜拼接不属于当前执行能力。

生成并下载只表示“待审核”，不等于短剧项目完成。创建逐镜审核表：

python3 {baseDir}/scripts/gettoken_seedance.py review-init "<videos目录>/batch-manifest.json" \
  --output "<shot-review.json>"

人工检查人物一致性、服装/道具连续性、动作、异常文字、口型/音频和内容合规，将每镜设为 approved 或 rejected；驳回必须写原因。然后运行：

python3 {baseDir}/scripts/gettoken_seedance.py review-check "<shot-review.json>" \
  --manifest "<videos目录>/batch-manifest.json"

只有 ready_for_final: true 才能说“镜头审核完成”。驳回后增加 project revision、修改诉求/素材并重新 approve，再生成只含被驳回镜头的可验证子项目：

python3 {baseDir}/scripts/gettoken_seedance.py project-select "<project.json>" \
  --shots shot_ep001_002 --output "<redo.project.json>"

project-select 会把 scope 变化的 storyboard/真人合规门恢复为 proposed。用户确认重做子项目后，对 invalidated_gates 逐个运行 project-approve；只有重新 ready_to_render=true 才能 compile/batch。使用新输出目录保留旧结果。

重做镜头通过 review-check 后，与原审核合并为唯一生效 take 集合：

python3 {baseDir}/scripts/gettoken_seedance.py review-merge "<原shot-review.json>" \
  --redo-review "<redo-shot-review.json>" --output "<final-shot-set.json>"

ready_for_external_postproduction=true 只代表镜头集合可交给外部后期。创建并校验剪辑、字幕、混音和最终交付记录：

python3 {baseDir}/scripts/gettoken_seedance.py delivery-init "<final-shot-set.json>" --output "<delivery.json>"
python3 {baseDir}/scripts/gettoken_seedance.py delivery-check "<delivery.json>" --shot-set "<final-shot-set.json>"

只有 ready_for_delivery=true 且最终文件大小/SHA-256 匹配，才能说“成片已最终交付”。

普通镜头清单批量

完整短剧/漫剧优先使用上述项目流程。只有人物、场景和分镜已经在外部确认，或任务没有持续角色时，才直接使用简化 shotlist。

1. 将一集拆成 4–8 秒的单镜头，每镜只保留一个核心动作。
2. 统一角色外观描述、服装、场景锚点和画幅。
3. 需要控制镜头起点时使用首帧；需要锁定结束构图时同时提供首帧和尾帧。两张图片都必须是可访问 URL，不能直接把本地路径传给 GetToken。
4. 按 EPxx_SCxx 命名，每镜独立调用 generate，避免一个失败拖垮整集。
5. 每次提交后保存 task_id。脚本会轮询 /v1/video/generations/{task_id} 并下载结果。
6. 先用 5 秒、9:16 做低成本样片；确认角色一致性后再扩批。
7. 任何额度不足、内容审核或渠道错误必须原样报告，不自动切换供应商。

批量生成使用镜头清单，默认逐镜执行并在第一处错误立即停止，以保护额度：

python3 {baseDir}/scripts/gettoken_seedance.py batch \
  "{baseDir}/assets/shotlist.example.json" \
  --output-dir "<项目目录>/videos"

提交前先做零网络预检：

python3 {baseDir}/scripts/gettoken_seedance.py batch "<镜头清单.json>" --dry-run

每次真实提交后会写入 batch-manifest.json。再次运行同一命令时，已下载镜头自动跳过，运行中的 task_id 会继续轮询。只有用户明确要求“失败也继续”时才添加 --continue-on-error。

分步控制

只提交、不等待：

python3 {baseDir}/scripts/gettoken_seedance.py submit --prompt "<提示词>" --duration 5 --size 9:16

查询一次：

python3 {baseDir}/scripts/gettoken_seedance.py status <task_id>

继续轮询并下载：

python3 {baseDir}/scripts/gettoken_seedance.py wait <task_id> \
  --output-dir "<项目目录>/videos" --name "EP01_SC01"

WorkBuddy 触发话术映射

默认采用两阶段交互：第一阶段整理结构化计划并 dry-run，明确报告“尚未提交，GetToken task_id 为 0”；用户回复“确认生成”后才进入第二阶段。只有用户明确要求“直接生成”时才能跳过等待确认。完整规范见 references/workbuddy_interaction_protocol.md，可复制模板见 assets/workbuddy-request-template.md。

按用户话术选择命令，不要把所有请求都当成 generate：

• “用 GetToken/我的 API 生成 Seedance 视频” → 先 doctor，再按需求选择 generate 或 batch。
• “做短剧/漫剧/把剧本生成视频/保持角色一致” → 进入 series_project。第一轮只用不超过 5 个简短问题询问作品类型、现有内容、目标篇幅、视觉方向、素材与声音；允许用户回答“还没想好/没有/请推荐”，禁止立即输出完整 project.json、人物表或分镜。收到回答后先给简短立项摘要，确认方向后再逐步创建项目并进入人物、场景、分镜和 dry-run。
• “只整理人物/人物形象/角色设定集” → 只更新 entities.characters 和人物批准状态，不调用视频 API。
• “人物已确认，继续分镜” → 建立 locations/props/episodes/scenes/shots，运行 project-check 与 project-compile；有 blockers 时停止。
• “审核这一集/哪些镜头要重做” → 对 manifest 运行 review-init，让用户逐镜填写检查项，再运行 review-check；MP4 存在不等于已验收。
• “重做 EP01_SC02/按修改诉求再生成” → 在审核表记录拒绝原因，增加项目 revision，重新确认受影响资产与分镜，通过 project-select 生成子项目，并使用新输出目录保留旧 take。
• “服务失败，原参数重试” → 默认仍禁止重提；再次明确确认会产生新费用后，才可对原 manifest 加 --retry-failed，旧 task_id 保存到 previous_attempts。
• “只用首帧/以这张图开场” → generate --image <URL>。
• “首尾帧/从图A过渡到图B/锁定结束画面” → generate --first-frame <URL> --last-frame <URL>；提交前优先 dry-run 检查两个 role。
• “先看请求/不要扣费/只做清单” → 创建 shotlist 后仅执行 batch --dry-run，禁止正式提交。
• “只提交/稍后再查” → submit，返回并保存 task_id，不自动轮询。
• “继续任务/查进度/下载已有任务” → 先 status；运行中再 wait，不得重新提交。
• “批量做一集/四镜样片” → batch 顺序生成，默认首错即停，保留 manifest。
• “检查配置/为什么报错” → 只运行 doctor 或分析已有错误，不用有效 prompt 反复试单。

完整首尾帧话术示例：

使用 gettoken-seedance-video，通过我的 GetToken API 调用 Seedance 2.0。
首帧 URL：<FIRST_URL>
尾帧 URL：<LAST_URL>
保持主体身份、服装和场景布局，只生成两帧之间的连续动作。
5秒，9:16，720p，命名为 EP01_SC01 并下载。
提交前先 dry-run，确认 metadata.content 中同时有 first_frame 和 last_frame。
不要使用 WorkRally、LibTV、聊天端点或内置 VideoGen。

完整批量话术示例：

读取 <shotlist.json>，使用 GetToken 的 doubao-seedance-2-0-260128。
先 batch --dry-run，检查每镜 mode、ratio、resolution 和 frame roles；通过后顺序生成，
按 EP01_SC01 起名并下载到 <videos目录>。每镜成功后才提交下一镜，首个错误立即停止，
写入 batch-manifest.json 并原样报告，不要添加 --continue-on-error，不要切换供应商。

后台任务证据

• 启动后台命令后只能说“本地执行器已启动”，并标明尚未获得 GetToken task_id。
• 继续读取后台任务输出，不能立即结束并承诺“全部镜头正在生成”。
• provider_task_submitted：可报告该镜已提交及真正的 task_...。
• provider_task_completed：检查 downloaded_to 文件存在后只能报告“该镜已生成，待人工审核”，不能报告项目完成。
• provider_task_failed 或后台进程非零退出：立即停止成功文案，报告镜头、task_id（如有）、HTTP 状态和 request ID。
• 批处理按顺序执行。第一镜 task_id 不能证明后续镜头已提交。
• 生成状态以 manifest/MP4 为准，镜头验收以 review-check ready_for_final=true 为准，成片交付以 delivery-check ready_for_delivery=true 为准；不以计划、ETA 或 WorkBuddy job ID 为准。

错误处理

• new_api_panic：通常是把视频模型发到了聊天端点；检查是否绕过了本技能。
• insufficient_user_quota：GetToken 余额不足；停止提交，不切换到 WorkRally 积分。
• task_not_exist：任务 ID 或查询域名错误。
• prompt is required：无扣费路由探针的预期响应；doctor 会将其判定为路由正常。
• 尾帧需要同时提供首帧：本地参数校验失败；补充 --first-frame，不要把尾帧当成普通参考图单独发送。
• 状态 failed/rejected/expired/cancelled：报告服务端原始消息并保留 task_id。

参考文件：

• 接口字段与响应兼容：references/api_reference.md
• WorkBuddy 状态与证据协议：references/workbuddy_interaction_protocol.md
• 短剧/漫剧人物、场景、分镜和音频流程：references/series_workflow.md
• 可复制请求模板：assets/workbuddy-request-template.md
• 完整项目示例：assets/series-project.example.json