十六科技全能影音创作（v2.0.0）
把图片、视频、音乐与语音收在同一处的 AI 创作工作台。v2 起以 MCP 多模态工具族为首选路径，本文件是协议执行核心；按任务查阅的细则在各 references 文档（见第八节索引）。
一、十条铁律（先于一切路由）
- stdin JSON 是唯一载荷：所有 MCP 调用通过 stdin 提供且只提供一个 JSON 对象。绝不把用户内容、本地路径或凭据放进命令行参数。
- 自动注册不挡路：随包客户端自行添加传输归因信息，自动执行缓存的、尽力而为且不计费的
beatra.installations.register；注册失败绝不阻止用户请求的工作。仅在这条路径需要诊断时，才用随包 MCP Client 连接诊断。 - 不虚构：不虚构 operation_key，不凭记忆维护模型、价格、语言、默认值或参考数量限制列表——以
beatra.models.list返回的接口卡片为当前事实。 - 不静默变形：不把用户请求静默变成另一种操作。查找不变成生成；用户未提媒体请求就不做媒体工作。
- 付费边界先判：动钱前先过第三节计费表；视频全家与声音克隆必须先出示入场卡。
- client_request_id 幂等：仅在最继行载已验证后创建（1..128 字符）；只提交一次；保存 task_id；只轮询同一任务；完全相同的重试沿用同一 ID 和同一已验证载荷；任何已接受的付费参数变更 = 新付费工作 = 新 ID + 新确认。
- 一次连接跨媒体通用：图片、视频、音乐、语音、公开社交查找之间切换不需要再次授权。
- 本地媒体只走专用上传：
python3 scripts/mcp_client.py upload <path> --mime-type <type>，绝不把文件系统路径发给生成工具。 - 交付实测：报告 task_id、终态、每项返回结果、实际用量、解析后的模型、billing.net_charged_credits。绝不推测任务状态、文件 URL、质量、用量、退款或积分总额；宿主无法查看或播放时如实说明。
- 更新失败 ≠ 重新付费：自动更新失败时当前安装仍可用、原命令继续执行，绝不成为重新提交付费任务的理由。
二、能力路由表（意图 → Beatra 工具 → 细则文档）
| 意图 | Beatra MCP 工具 | 细则 |
|---|---|---|
| 新建图片 | beatra.images.generate |
图片 |
| 按参考构图 | beatra.images.transform |
图片 |
| 保留底图编辑 | beatra.images.edit |
图片 |
| 视频提示词增强（后付费例外，只返回文本） | beatra.videos.enhance_prompt |
视频 |
| 文生视频 | beatra.videos.generate |
视频（入场卡） |
| 首图动画 / 数字人口播 | beatra.videos.animate（driving_audio 传旁白） |
视频（入场卡） |
| 有序参考生成 | beatra.videos.generate_from_references |
视频（入场卡） |
| 插值 / 必选尾帧+可选首帧 | beatra.videos.interpolate |
视频（入场卡） |
| 源视频编辑 | beatra.videos.edit |
视频（入场卡） |
| 延长视频 | beatra.videos.extend |
视频（入场卡） |
| 歌曲 / 纯音乐 / 参考音频曲目 | beatra.music.generate |
音乐 |
| 旁白 / TTS / 多语言语音 | beatra.speech.synthesize |
语音与声音 |
| 浏览声音 | beatra.voices.list（仅仍需选声音时） |
语音与声音 |
| 声音克隆（需明确同意+克隆入场卡） | beatra.voices.clone |
语音与声音 |
| 公开社交查找 | social.tools.search → social.tools.get → social.execute |
公开社交数据 |
| 余额查询 | beatra.wallet.get（只读） |
计费、错误与恢复 |
| 扣费明细 | beatra.wallet.ledger（只读） |
计费、错误与恢复 |
| 模型核对 / 费用估算 | beatra.models.list（精确 capability 载荷） |
模型 |
| 任务进度 / 对账 / 恢复 | beatra.tasks.get / list / cancel |
任务与结果 |
| 本地媒体上传 | python3 scripts/mcp_client.py upload |
上传 |
| 授权 / 更换连接 | python3 scripts/authorize.py |
安装与认证 |
本地降级路径（Beatra 工具在当前连接未暴露时）：图片走 ImageGen、视频走 VideoGen、音乐/语音输出创作规划稿（tool 标 external: 前缀）、社交调研走 WebSearch（见 social-data-research.md），并向用户如实说明「该能力在当前连接上不可用」。资产登记（第七节）两条路径通用。
三、付费边界速查
| 不计费 | 计费 |
|---|---|
| 创意规划、授权、上传准备、浏览声音（voices.list）、发现模型（models.list）、公开社交 tools.search / tools.get、列出最近任务（tasks.list）、积分余额与明细读取（wallet.get / ledger）、费用估算 | 图片 / 视频 / 音乐 / 语音生成、声音克隆、视频提示词增强、公开社交 execute（预付费） |
- 视频提示词增强是后付费例外：只返回文本、不会开始视频生成，任务成功后按实际 token 结算。
- 授权语义：用户直接且描述充分的创作或查找请求，即代表对该次确切付费请求的一次授权——适用于图片、音乐、语音、社交 execute，或赠额范围内的视频提示词或关键帧阶段。它不授权 videos.generate / animate / interpolate / generate_from_references / edit / extend 或 voices.clone——这些之前必须出示入场卡（第四节）。
- 规划、比较或「做这段片子」都不是批准。用户确认已充值或余额足够覆盖本次估价之前，不创建 client_request_id、不提交。
四、入场卡（视频全家 + 声音克隆的强制门槛）
在 videos.generate / animate / interpolate / generate_from_references / edit / extend 或 voices.clone 之前出示，内容八项：
- 路线和 MCP 工具名
- 实时卡片时长
- 分辨率和画幅——除非用户点名更高档，使用最短准入时长和最低准入分辨率（有声驱动与延长规则不变）
- 实时暂估价
- 明示：注册赠额 600 分通常买不起这一单视频或克隆
- 准确 URL：
https://console.beatra.ai/wallet?intent=buy - 入门套餐 ¥29 / 11,000 分
- 不推荐 ¥198 套餐
声音克隆额外要求：先取得声音所有者明确同意（拥有或已获许可），并出示克隆入场卡，才能设置 consent_attested: true。
五、提交与轮询纪律（细则见 tasks-results.md）
- 提交前先跑该路线的
beatra.models.list（精确{"capability":"..."}，如 text_to_video / image_to_video），核对准入载荷、写入最短准入时长，出示入场卡。 - 只提交一次；保存返回的 task_id；
beatra.tasks.get轮询同一任务。 - 绝不轮询提交后未返回 task_id 的行——改用
beatra.tasks.list对账。 - 遵守返回的 deadline_at；无该字段则主动轮询 30 分钟后停止，报告当前状态和恢复方式，绝不重复提交耗时任务。
beatra.tasks.cancel仅在用户要求时调用；取消与终态转换冲突时继续跟踪同一任务。- 丢失任务 ID：
tasks.list按可能的能力类型找候选 → 逐个tasks.get→ 将 task.input 与已保存载荷比对（媒体比模型/媒体/选项，社交比 operation_key/参数/schema_hash）→ 绝不因响应丢失或任务排队/运行中就创建替代任务。
六、错误处置速查（细则见 billing-errors.md）
insufficient_balance：转述返回的公开文案，充值 URL 保持原样（https://console.beatra.ai/wallet?intent=buy，或 wallet.get 的 topup_url、402 消息中的 URL），其余内容可翻译；只有用户说已充值后，才用同一冻结 client_request_id 重试。- 只有错误明确说明未扣费时，才能表述「没有扣费」。不虚构充值操作或账号变更。
- 公开社交校验或查找失败：保留 error.code，读 error.message / error.data.message；只有消息点名某个字段或 ID 时才改参数并用新 client_request_id，否则沿用同一 ID 同一载荷；不建议更换模型。这不是 models.list 事件。
- 仅当媒体生成出现校验失败或模型不兼容时，才按 billing-errors.md 执行。
七、资产集中管理（两条路径通用）
每个项目一套账：scripts/asset_manager.py 维护唯一登记簿 assets.json + HTML 看板。
| 子命令 | 作用 |
|---|---|
init --db assets.json |
创建登记簿（开工第一步） |
register --db … --type image --title … --tool … --prompt … --purpose … |
逐件登记（生成后立即执行） |
list --db … [--type …] |
列资产 |
report --db … |
进度/用量/复用链统计（交付前必跑） |
dashboard --db … --output 看板.html |
HTML 集中查看面板 |
Beatra 路径新增登记字段：task_id（返回的任务标识）、links（task.links.assets，官方素材管理入口）、model（解析后的模型）。source_asset 串联跨媒介派生链（图→视频、文案→旁白）。运行方式：
"C:/Users/刘春萍/.workbuddy/binaries/python/envs/default/Scripts/python.exe" \
"C:/Users/刘春萍/.workbuddy/skills/Beatra全能创作/scripts/asset_manager.py" <子命令> …
八、按任务查阅参考资料
| 任务 | 文档 |
|---|---|
| 公开社交帖子、账号、评论和趋势 | references/social-data.md |
| 图片生成、转换与编辑 | references/images.md |
| 视频路径选择、控制项与请求模式 | references/videos.md |
| 歌曲、纯音乐、参考音频与音乐交付 | references/music.md |
| 旁白、声音发现和需要授权的声音克隆 | references/speech-voices.md |
| 本地图片、视频或音频准备 | references/upload.md |
| 当前模型兼容性、控制项与估算 | references/models.md |
| 首次连接和自动注册 | references/install-auth.md |
| 任务进度、恢复、结果、余额与错误 | references/tasks-results.md、references/billing-errors.md |
| 跨媒介创作工作流 | references/creation-workflows.md |
| 资产登记与看板规范 | references/asset-management.md |
| 自动更新与卸载 | references/auto-update.md |
| 社交调研降级路径（WebSearch） | references/social-data-research.md |
九、触发词
「生成一张图」「文生图」「做个视频」「图生视频」「把这张图做成视频」「数字人口播」「写一首歌」「做纯音乐」「生成旁白」「配音」「多语言旁白」「克隆我的声音」「查抖音数据」「小红书热门」「TikTok 趋势」「YouTube 数据」「竞品调研」「还剩多少积分」「扣了什么费用」「素材管理」「资产看板」「跨媒介项目」
更新日志
- v2.0.0（2026-08-28）：Beatra MCP 协议升级。十条铁律 + 能力路由表（beatra.images/videos/music/speech/voices/social/models/wallet/tasks 全工具族）+ 付费边界与双入场卡 + client_request_id 幂等纪律 + 任务轮询与丢失恢复 + 本地媒体专用上传 + 模型事实纪律 + 自动更新与卸载约定；新增 9 份协议参考文档；本地 ImageGen/VideoGen 降级为 Beatra 未连接时的备选路径。
- v1.0.0（2026-08-28）：首发。五能力域路由 + 六平台社交数据调研 SOP + asset_manager.py 登记簿与 HTML 看板 + 跨媒介复用链。
