接入 AI-HIVE Connector
本 Skill 通过 AI-HIVE Connector 调用底层模型生成能力。CLI OAuth 模式接入流程：
- 首次安装：在 WorkBuddy 连接器列表中找到「AI-HIVE」，点击进入
- 完成授权：点击「连接」会弹出浏览器到 ai-hive.iclip.cn，在该网站登录 AI-HIVE 账户（无账户需先注册），点击授权
- 回到 WorkBuddy：授权完成后自动返回，Token 在本机保存（用户看不到）
- 日常使用：用户无需再次操作，直接调用本 Skill 即可
- 连接过期/失败：在 WorkBuddy 连接器列表中重新找到「AI-HIVE」，点击「重新连接」→ 完成浏览器 OAuth
- Token 安全：如 Token 疑似泄露，到 ai-hive.iclip.cn → 账户设置 → 撤销所有 Token
能力范围
AI-HIVE 视频生成 Skill 通过 AI-HIVE Connector 完成端到端视频创作。本 Skill 使用 AI-HIVE Connector 提供的以下工具：
get_user_info：查询当前账户与余额；不接收参数。list_models：用modelType="VIDEO"列出当前可用视频模型及价格快照。upload_media_from_path：上传本地图片、视频或 MP3/WAV 音频并返回mediaId；音频单文件最大 15 MiB。generate_video：使用选定模型与可选参考素材创建视频任务。get_generation_task：使用generate_video返回的taskId查询任务状态与结果。
文本生成与图片生成请分别改用 text-creator 或 image-creator。
提示词写法参考 references/prompt-optimization.md（视频公式 + 运镜词表 + 稳定/角色约束）。
覆盖场景：产品讲解视频 / 培训录屏 / 宣传短片 / 会议摘要视频 / 首尾帧过渡 / 多模态参考 / 5–15 秒不同时长 / 1:1 / 9:16 等画幅。
典型触发：当用户说"生成 10 秒 9:16 产品讲解视频"、"用这两张首尾图生成过渡视频"、"按这组参考图做一段 15 秒培训片段"、"做一个 5 秒宣传开场动画"等需求时使用本 Skill。用户只是咨询能力、参数或费用时，直接回答，不创建任务。
Prompt 骨架（通用模板）
逐场景组装时，按以下字段结构化；缺省字段留空，不强行填充：
| 字段 | 含义 | 示例 |
|---|---|---|
| 用途 | 视频用在哪（产品讲解 / 宣传片 / 分镜） | 产品宣传短片 |
| 主体 | 核心对象 / 人物 | 产品 + 模特 |
| 镜头脚本 | 分镜与时长（0-4s / 4-8s …） | 0-4s 推进特写 |
| 运镜 | 相机运动 | 环绕 / 横移 |
| 视觉风格 | 电影级 / 动画 / 实拍 | 电影级调色 |
| 光线色彩 | 光向与色调 | 暖光、霓虹 |
| 音频 | 原生音 / 配乐 / BGM | Synthwave 124BPM |
| 保留项 | 图生视频须保留要素 | 人物不变形 |
| 输出规格 | 时长 / 画幅 / 分辨率 | 12s / 9:16 / 480P |
组装顺序：用途 → 主体 → 镜头脚本 → 运镜 → 视觉风格 → 光线色彩 → 音频 → 保留项 → 输出规格。仅保留有值的字段。
调用流程
本 Skill 的标准调用顺序如下。每步有明确的输入与输出；上一步失败时不得跳到下一步。
Step 0：连接检查
- 用户已通过 AI-HIVE Connector 完成 OAuth CLI 流程（如未连接，引导用户连接）。
Step 1：账户与模型初查
- 调用
get_user_info检查账户与余额。 - 调用
list_models(modelType="VIDEO")获取可用视频模型与价格快照。
Step 2：模型推荐与选派
- 对照
references/model-scenarios.md中各视频模型的擅长场景，结合用户需求的镜头类型、时长、是否有首尾帧、是否需参考素材、是否需音画等特点匹配擅长模型。 - 结合
list_models返回的可用routingMode及其对应pricingSnapshot，权衡成片质量与成本，向用户说明推荐理由；不假设每个模型都提供固定三档路由。 - 若用户未指定偏好，默认推荐效果与成本均衡的选项。
- 用户确认
publicModelId与routingMode后，进入下一步。
Step 3：（可选）上传参考素材
- 首帧、尾帧或多模态参考图/视频/音频：调用
upload_media_from_path上传，拿到mediaId备用。 - 外部音频按上传顺序编号为音频1、音频2……；只有当前模型配置明确支持参考音频及该输入组合时才提交。
- 不需要参考时直接跳到 Step 4。
Step 4：创建任务
- 将选中项的
publicModelId、routingMode与pricingSnapshot原样传入。 - 构造
prompt；图片、视频与外部音频分别放入imageMediaIds/videoMediaIds/audioMediaIds，首尾帧使用对应单值字段；时长、画幅、分辨率和原生声音开关等放入params。 - 模型不支持外部参考音频时保持
audioMediaIds=[]；Prompt 中的声音描述与params原生声音开关不能替代外部音频素材。 - 失败时按
../references/error-catalog.md处理，不重试扣费。
Step 5：跟踪结果
- 用 Step 4 返回的
taskId调用get_generation_task轮询。 PENDING/SUBMITTED/PROCESSING→ 简要报告真实状态；COMPLETED→ 返回所有视频 URL；FAILED→ 展示安全失败字段。
Step 6：交付
- 把成功视频的 URL、时长与画幅呈现给用户；失败候选如实报告错误码。
适用场景
- 用户希望生成 5–15 秒的产品讲解视频、培训录屏或宣传短片。
- 用户上传了首帧或尾帧，希望控制镜头过渡。
- 用户上传多张人物、商品或场景参考图，要求保持参考一致性。
- 用户希望快速多版本对比并跟踪任务状态。
非适用场景
- 目标是文本或图片；切换到
text-creator或image-creator。 - 本地参考素材未上传到对话或路径不可访问。
- 用户要求绕过积分、版权或安全审核；或内容明显违法、侵权、色情、暴力、仇恨、欺诈。
- 涉及真人、名人、商标或未授权素材；先向用户确认授权。
- 用户只是咨询能力、参数或费用，并未要求实际创建任务；不调用付费工具。
事实与合规边界
- 只使用工具真实返回的
taskId、状态、错误与结果链接作为事实；不编造任务、进度或成功结果。 - 不擅自构造或修改
pricingSnapshot；最终费用按 AI-HIVE 实际用量与账单计算。 - 不静默切换用户选定的模型、时长、画幅或参考素材。
- 不宣称对版权、商标或肖像权作法律判定；引用第三方作品或人物前先提示用户确认授权。
- 对未成年人、裸露、暴力、仇恨与违法内容采取保守判断；无法确认合规时停止创建。
- Token 只在 AI-HIVE Connector 凭证设置中填写，不在对话中粘贴。
输入检查
正式调用前逐项确认：
- 明确视频时长、画幅、清晰度、数量、是否包含声音与文字。
- 本地参考素材必须来自用户主动选择的文件；MP3/WAV 音频单文件不得超过 15 MiB；不接受
localhost、file:URL 或私网地址。 - 调用
get_user_info检查余额；不足时直接提示充值。 - 调用
list_models(modelType="VIDEO")选择模型；时长/画幅仅使用服务端支持的枚举值。 - 使用参考前先调用
upload_media_from_path上传并保留返回的mediaId；外部音频仅在当前模型配置明确支持参考音频和当前组合时进入audioMediaIds，否则保持空数组。 - 涉及真人、商标或公众人物时必须先确认用户已获得授权，否则不创建任务。
调用示例
全部示例均基于上文"输入检查"，遵循
../references/tool-catalog.md与../references/error-catalog.md的口径。 用户表达 → AI 的多步行为 → 输出。
示例 1：产品展示视频
用户表达：生成一段 10 秒 9:16 的产品讲解视频。
AI 行为：
get_user_info→ 余额检查。list_models(modelType="VIDEO")→ 选定支持 10 秒 9:16 的模型，记录pricingSnapshot。generate_video(prompt="...", params={duration: 10, aspectRatio: "9:16"}, publicModelId=..., routingMode=..., pricingSnapshot=...)→ 拿到taskId；参数键和值须由当前模型配置确认。get_generation_task(taskId)跟踪到COMPLETED。
输出：
taskId：xxx- 视频 URL、时长、画幅
- 下一步：等待用户确认或调整
示例 2：首尾帧过渡
用户表达：用这两张图作为首帧和尾帧，生成一段 6 秒过渡视频。
AI 行为：
upload_media_from_path上传首图 →firstFrameMediaId；上传尾图 →lastFrameMediaId。list_models(modelType="VIDEO")选择支持首尾帧的模型。generate_video(prompt="...", params={duration: 6}, firstFrameMediaId="firstFrameMediaId", lastFrameMediaId="lastFrameMediaId", publicModelId=..., routingMode=..., pricingSnapshot=...)；duration须由当前模型配置确认。get_generation_task跟踪到COMPLETED。
输出：
taskId：xxx- 视频 URL 与所用
firstFrameMediaId/lastFrameMediaId - 下一步：等待用户确认
示例 3：超时或长任务
用户表达：生成一个 15 秒视频。
AI 行为：
generate_video创建任务成功，连续get_generation_task收到PROCESSING但无进度数字。- 不自行估算完成时间；保留工具原始状态与时间戳。
- 必要时提示用户稍后继续查询；如决定"取消重做"则需重新扣费，必须重新走 Step 3 拿新
taskId。
输出：
- 工具真实状态与时间戳
- 下一步：等待 / 取消重做
工具参数
get_user_info
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| — | — | — | 不接收参数 |
list_models
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
modelType | string | 可选 | — | TEXT / IMAGE / VIDEO；本 Skill 显式传入 "VIDEO" |
upload_media_from_path
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
path | string | ✅ | — | 用户授权的本地文件绝对路径 |
filename | string | 可选 | 原文件名 | 覆盖上传文件名 |
contentType | string | 可选 | 客户端识别 | 覆盖 MIME 类型；不确定时省略 |
图片、视频上传后分别在 imageMediaIds、videoMediaIds 或首尾帧字段中引用。MP3/WAV 音频单文件最大 15 MiB，成功返回 mediaType=AUDIO；音频按上传顺序放入 audioMediaIds。
generate_video
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
publicModelId | string | ✅ | — | 来自 list_models |
routingMode | string | ✅ | — | 选中模型实际返回的路由 |
prompt | string | ✅ | — | 描述主体、动作、镜头、光线、风格与声音 |
imageMediaIds | array | 可选 | 空 | 参考图片 mediaId 列表 |
videoMediaIds | array | 可选 | 空 | 参考、编辑或延长视频 mediaId 列表 |
audioMediaIds | array | 可选 | 空 | 外部参考音频 mediaId 列表；仅兼容模型与合法组合使用 |
firstFrameMediaId | string | 可选 | — | 首帧图片 mediaId |
lastFrameMediaId | string | 可选 | — | 尾帧图片 mediaId |
params | object | 可选 | 空对象 | 当前模型支持的时长、画幅、分辨率与声音等字段 |
pricingSnapshot | object | ✅ | — | 对应模型与路由的价格快照，原样传入 |
get_generation_task
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
taskId | string | ✅ | 仅使用 generate_video 的真实返回值 |
费用授权
generate_video调用即按服务端计费并扣费。- 失败、被拒绝或余额不足时不重试扣费，只返回错误并询问用户下一步。
- 用户修改模型、提示词、时长、画幅或参考素材后必须重新调用，不复用旧扣费配额。
状态与错误处理
余额不足 / 任务被拒
AI-HIVE 官网：https://ai-hive.iclip.cn
充值路径（账户已存在）：
- 访问 https://ai-hive.iclip.cn → 登录 AI-HIVE 账户
- 进入「账户中心」/「钱包」/「充值」页面
- 选择充值套餐或自定义金额 → 完成支付
- 充值成功后回到 WorkBuddy，无需重新连接 Connector，直接重试任务
注册路径（首次用户）：
- 直接访问 https://ai-hive.iclip.cn/login，进入注册页面
- 使用手机号完成注册
- 登录 → 回到 WorkBuddy 重新连接 AI-HIVE Connector 即可
价格透明：
- 每次调用前可调
get_user_info查看当前余额 - 调用后实际扣费以服务端
pricingSnapshot为准 - 若工具明确提示余额不足，停止创建任务；任务进入
FAILED时按failure安全字段展示 - 详细价格参考：https://ai-hive.iclip.cn/pricing
常见扣费场景参考（具体以服务端为准）：
- 文本生成：按 token 数计费
- 图片生成：按张数 + 分辨率计费
- 视频生成：按秒数 + 分辨率计费
其他被拒原因：
-
账户被风控：联系 AI-HIVE 客服（https://ai-hive.iclip.cn → 登录 → 设置 → 联系客服）
-
模型临时不可用：稍后重试或换模型
-
内容违规审核：调整 prompt 后重试（避免敏感内容）
-
PENDING/PROCESSING：返回工具真实状态或进度；没有进度数字时不要自行估算。 -
COMPLETED：返回所有可用视频链接、缩略图与工具明确给出的部分失败信息。 -
FAILED：保留可安全展示的failure.code、failure.summary、failure.suggestion，不暴露内部凭证或堆栈。 -
超时或网络不明：拿到
taskId时只查询原任务；不知道是否创建成功时不要再次创建。 -
鉴权失败 / 连接过期：WorkBuddy → Connector 设置 → 找到 AI-HIVE → 点击"重新连接" → 完成浏览器 OAuth 流程；如仍失败，到 ai-hive.iclip.cn → 账户设置 → 撤销所有 Token → 重新发起授权
-
AI-HIVE 账户无余额：展示余额不足的可读消息，引导用户在 ai-hive.iclip.cn 完成充值后再试
-
AI-HIVE 服务端错误：按
error-catalog.md处理，不自行重试扣费 -
单个视频或子任务失败：仅返回成功的视频与失败子任务的明确错误，不补写视频内容。
输出模板
成功
taskId：工具真实返回的值- 模型与参数：服务端实际采用值
- 视频：逐项列出可用 URL、缩略图、时长与画幅
- 下一步：等待用户确认、调整或保存
失败
- 失败码：
failure.code（仅在工具实际返回时安全展示） - 错误摘要：
failure.summary或工具返回的可读消息 - 原因摘要：工具给出的可读描述
- 下一步建议：充值、改连 Connector、调整提示词或切换模型
部分失败
- 成功视频：完整呈现 URL、时长与画幅
- 失败子任务：错误码与对应的
prompt概要 - 不补写：不得为失败任务猜测视频内容
