Miora Video Studio Agent Skill

miora 视频生成工作台

使用前提：当前环境已经配置 WorkBuddy / Miora 视频工具。若工具不可用，本 Skill 只能用于诊断与解释，不能替代实际的视频生成通道。

若环境同时提供下列 Skill，可以协同加载：

• miora-creative-core —— 底座：确认与费用边界、生成前参数怎么定、画布交付。
• miora-video-generation —— 决策：镜头语言、时长画幅、主体一致性、失败处置。

它们不是本 Skill 的安装前提；本 Skill 自身负责：完成信号怎么判、参数实测到哪、提示词怎么改。

1. 唯一的核心问题：完成信号

miora 生成进程与对话进程是分离的。由此推出五条，任一条都不能违背：

• 完成信号来自落盘事实，不来自接口返回。 返回值可能整体丢失——实测发生过：15 秒视频生成成功、成片已落盘，调用方什么也没收到。把"没返回"当成"失败"是错的。反向情形同样存在：调用会阻塞到任务完成再返回 status: completed + resultFiles[].localPath（实测等约 6.4 分钟），此时仍要走一次 --wait 核验——用文件头读规格，不采信自报值。
• 返回值里带了 localPath 时，那个绑定优先于文件扫描：立刻 --wait --claim <localPath> --job <作业名> 落账（见第 4 节；--claim 不是独立动作，必须和 --submit/--wait/--poll/--poll-all 之一同时给，否则 argparse 直接报错退出）。别让启发式扫描有机会把并发作业的成片算到你头上。
• 提交之前先登记作业，再发起生成。顺序颠倒就失去跨轮追溯能力。
• 生成后立刻轮询，不靠用户再发一句话。视频要 6 ~ 21 分钟，单轮等得完。
• 规格以文件头为准，时长 / 分辨率 / 音轨自己读出来，不采信自报值。
• 不重复提交。 状态不明不等于失败；重复提交会重复计费，且已提交的任务无法取消。

配套脚本 scripts/miora_watch.py 实现上述判定。

调用前需 connect_cloud_service 取会话凭据，把 clientTempToken 作为 tempKey 传给视频工具。凭据有效期不稳定——实测出现过同一 token 在同一分钟内第二次使用就被拒（AUTH_INVALID_TEMP_KEY）。所以：报 AUTH_*_TEMP_KEY 就重新取一次再重试；连续重试时干脆每次重取，比猜有效期省事。凭据内容不得展示给用户。

1.1 第 0 步：先查工具在不在

每次开工都查，不要凭上次的经验跳过——同一台机器上不同会话的可用性可能不同（实测过：同一台机器，一个会话里 mcp__miora__* 正常可用并成功出片，另一个新会话里完全没有注册）。

开工第一步确认当前会话的工具清单里有没有 mcp__miora__*。

判定分三步，顺序不能颠倒——两种"缺失"形态容易混判。

第一步：先看主工具清单。 如果 mcp__miora__miora_reference_to_video / mcp__miora__miora_text_to_video / mcp__miora__miora_write_canvas 这些直接出现在当前会话的可调用工具清单里，那就是可用，直接开工。 无需再做任何探查——它们不在 deferred 索引里，ToolSearch 天生搜不到它们。

第二步（仅当主清单里看不到 mcp__miora__* 时）： ToolSearch 用 queries: ["miora"] 搜。这里的结果只用于识别"server 条目在、子工具一个都没注册"的空壳状态：available_deferred_tools 里列着 mcp__miora，但对比 mcp__agent-mail / mcp__sheetagent 能看到人家的子工具名都展开了，miora 没有。

第三步（二次确认）： 用 DeferExecuteTool 探 mcp__miora__miora_reference_to_video——报 Tool "..." not found in the deferred tools index 才是决定性证据。

第四步（只在确诊缺失后做，用于分清"没配"还是"没启用"）： 三处落盘证据一起看，给用户的结论才具体。

| 文件 | 看到什么 | 说明 |

|---|---|---|

| ~/.workbuddy/mcp.json | 有 mcpServers.miora 条目（command: node + args 指向 miora-mcp/dist/cli.cjs，defer_loading: false） | 配置在，不是"没配" |

| ~/.workbuddy/mcp-approvals.json | 内容是 {} | 没有任何 MCP 被信任/批准 → 服务未启用 |

| ~/.workbuddy/plugins/data/mcp-miora/miora-media 下最新 .mp4 | mtime 是几分钟前 | 通道此前正常，产物都在 |

同时比对 available_deferred_tools：miora 只以光秃秃的 mcp__miora 出现、子工具名不展开，而 mcp__agent-mail / mcp__sheetagent 的子工具名都列全了——这个不对称本身就是空壳签名。加上 defer_loading: false（本该进主清单）却不在主清单里，两点互证。

据此可讲的三件事：① 这是会话级未启用/未注册，不是插件损坏（miora-mcp/dist/cli.cjs 仍在、历史成片仍在）；② 需求规格本身没问题；③ 最小解阻动作是到连接器管理右上角"自定义连接器"里信任 miora 服务、重启会话。不要自己去跑 dist/cli.cjs 或改 mcp-approvals.json 伪造信任。

> ⚠️ 踩过的坑（2026-09-16 实测）：ToolSearch 只索引 deferred 工具，搜不到 mcp__miora__* 不等于没注册。那次 queries: ["miora"] 只回了 connect_cloud_service，看着像"未注册"，但 mcp__miora__miora_reference_to_video 本来就在主清单里，直接调用一次成功出片（15s / 768P / 4 张参考图，约 6.8 分钟）。判断依据是"主清单里有没有"，不是"ToolSearch 搜不搜得到"——按后者办会把能用的通道误判成不可用，白白拦下一次交付。

确诊缺失后要回滚已登记的占位标记。 探查时若顺手跑了 --submit，那是个永远不完成的作业，会污染 --poll-all 列表；用 os.remove 删掉 ~/.workbuddy/miora-jobs/<作业名>.json（只删本次自己刚建的那一个）。

给用户一条落盘证据更有说服力：读 ~/.workbuddy/plugins/data/mcp-miora/miora-media 下最新 .mp4 的 mtime，能说出"最近一次成功出片就在几分钟前"。实测过媒体目录里有约 7 分钟前刚出的 miora_reference_to_video-*.mp4，而新会话里工具完全未注册——据此可讲清这是会话级注册问题，插件本体、历史成片、参考素材都还在，素材和产物都没丢。

没有就停下说明，不要找替代品。 本机 miora-mcp 处于产品层隐藏状态：workbuddy-builtin/mcps/miora-mcp/HIDDEN.md 记录了它已从 marketplace 注册中移除、运行时不会被加载。此时据实告知用户：

• 插件本体、历史成片、参考素材都还在，但当前没有任何可用的 miora 通道；
• 需求规格本身没问题（比如 9 秒落在 4–15 秒的合法区间内），阻塞点只在工具缺失；
• 未做任何环境改动。

不许改用的替代工具：内置的 VideoGen（混元）只吃 1 张首帧 + 1 张尾帧，不支持多张参考图，也没有时长参数——做不出参考生视频的等价结果。换用它就是静默降级。

停在这一步，不要登记作业、不要提交生成。

2. 三种模式

| 手上有什么 | 模式 | 工具 |

|---|---|---|

| 只有文字 | 文生视频 | mcp__miora__miora_text_to_video |

| 有图，要它当起始画面（可另给结束帧） | 首尾帧生视频 | mcp__miora__miora_frame_to_video |

| 有图，要它锚定主体或风格 | 参考生视频 | mcp__miora__miora_reference_to_video |

两条硬规则：

• 有素材就绝不走纯文字工具。 参考图、已确认的锚点、上一轮的定稿都是硬约束；退化成文字描述，拿到的是"像但不是同一个"的东西，而且这次无效生成要用户付费。
• 多图必须写明角色。 提示词开头补一行"图1=角色主体，图2=场景，图3=道具"。用户用 @image#N 引用时，补编号映射表让编号可解析——这是结构性补充，不算改动用户原文。

3. 规格事实

口径来源：MiniMax 官方文档 platform.minimax.cn/docs/guides/video-generation（H3 / H3 Max），2026-09-16 核对；加「本机实测」的条目是本通道跑出来的实际行为。

3.1 闸门一：四个必填参数 —— 缺一个都不许提交

模式、分辨率、时长、画幅这四项必须由用户声明。四项里缺任意一项，都不要调用 miora，也不要替他猜。

| 必填参数 | 合法取值 |

|---|---|

| 模式 | 文生视频 / 首尾帧生视频 / 参考生视频 |

| 分辨率 | 768P / 2K |

| 时长 | 4 ~ 15 秒的整数 |

| 画幅 | 16:9 / 9:16 / 1:1 等 |

缺项时的标准动作：

• 停下，不提交，明确告诉用户还缺哪几项；
• 缺的项一次性列全（不要一项问一轮），说明"四项填齐后才能提交生成"；
• 可以给建议值帮用户决策，但建议不等于默认——用户没点头就不许写进参数里。

禁止的四件事：

• 拿"合理默认值"填上就投——本 skill 不再为这四项设任何自动默认；
• 用文字描述蒙过去（比如不给 duration，指望模型自己定）；
• 只问一部分、先把任务投出去；
• 声称"我按你的意思补了默认值"——你没这个权力。

不算法定缺项的一种情况：用户声明了某一项，但取值不合法（例如分辨率说 720p）。这算已声明——属于取值澄清，不是参数缺失——按合法等价档映射并披露（720p → 768P，见 3.2）。

模式这一项还要和素材对齐：手上有参考图就必须走参考生视频或首尾帧生视频，不许退化成文生视频（见第 2 节）。

四项齐了就直接视为已确认，不要再问一遍；其余参数（提示词内容、参考素材取舍）按第 2 节和第 6 节走。

与 miora-creative-core「生成前必须 AskUserQuestion 确认」的冲突裁决：当四参数齐全、且规格全部由用户自己声明（没有任何一项是模型填的默认值）、参考素材也已明确时，不再重复提问，直接提交——规格本就是用户给的，重复确认只增加一轮往返；用户把脚本写到分镜秒级时间轴这一层时，更是明确的定稿信号。需要重新提问的情形只有：产出规模变化、参数实质变化、用户要求重做。core 的确认环节若确实要做，也要装进"产出什么 / 规格 / 素材"的实质信息，不要做成空泛的"确认继续吗"。

3.2 输出规格

| 项目 | MiniMax H3（本通道在用） | MiniMax H3 Max |

|---|---|---|

| 模型名 | MiniMax-H3 | MiniMax-H3-Max |

| 输出分辨率 | 768P / 2K | 480P / 768P |

| 输出时长 | 4 ~ 15 秒，仅整数 | 5 ~ 15 秒，仅整数 |

• 本机实测：resolution 只接受 768P / 2K，传 720p / 1080p 被上游拒——unsupported video resolution: 720p, supported values: [768P 2K]。用户说 720p 时按 768P 投（16:9 原生档即 1344×768，等价档、不是降级），并在交付说明里写明；用户想要更高档时用 2K。
• 16:9 输出 1344×768；24 FPS；成片带原生立体声音频轨（32 kHz）。
• 本机实测（2026-09-16）：15 秒 + 768P + 4 张参考图一次通过，文件头读到 15.08 秒 / 1344×768 / has_audio: true。4 张正好是通道上限的合法边界值，不必为"以防万一"留余量。
• 成片时长会略长于请求值：请求 9 秒 → 文件头 mvhd 读到 9.42 秒（帧对齐所致）；同一批实测还有 11 秒 → 11.54 秒、12 秒 → 12.25 秒、13 秒 → 13.67 秒（两次一致）、15 秒 → 15.08 秒。核验时按 ±1 秒容忍（实测最大偏差 +0.67 秒），不要因为差这零点几秒判成规格不符，更不要因此重投。
• 从提交到落盘 1.7 ~ 55 分钟，波动很大（实测五次：13 秒档 1.7 分钟、6 分钟，15 秒档 6.8 分钟、20.8 分钟、55.3 分钟）。轮询预算按 60 分钟以上给——单段 --timeout 1800 也未必够，长任务要分段续挂（见第 5 节）；官方推荐轮询间隔 10 秒。
• 最新一次（2026-09-17，15 秒 + 768P + 4 张参考图）：提交 12:14:59 → 落盘 13:10:16，55.3 分钟，文件头 15.08 秒 / 1344×768 / has_audio: true，与同规格历史实测完全一致。中途约 40 分钟时本地无任何文件、上游 query_task 仍报 pending（附带 Request failed with status code 400），但最终正常出片。
• 结论：耗时长不能作为判定失败或重投的依据。 唯一完成信号仍是落盘文件（见第 1 节）。
• 补充实测（2026-09-17，同规格 15 秒 + 768P + 3 张参考图）：提交 13:31:24 → 落盘 13:39:41，8.2 分钟，文件头 15.08 秒 / 1344×768 / has_audio: true。当日两次同规格作业分别为 55.3 分钟与 8.2 分钟，进一步说明耗时离散度极大（约 1.7 ~ 55 分钟），不能靠历史耗时预估本次。
• 补充实测（2026-09-17，15 秒 + 768P + 4 张参考图）：提交 14:12:29 → 落盘 14:24:11，11.7 分钟，文件头 15.08 秒 / 1344×768 / has_audio: true；生成调用前台阻塞至完成并返回 status: completed + resultFiles[].localPath，--wait --claim 绑定后 probe 与自报值一致。同日另一件 15 秒 + 4 图作业为 55.3 分钟——同规格同素材数，11.7 分钟与 55.3 分钟并存，耗时离散度不因规格相同而收窄。
• 补充实测（2026-09-17，11 秒 + 768P + 3 张参考图）：提交 13:45:12 → 落盘 13:50:37，5.4 分钟，文件头 11.54 秒 / 1344×768 / has_audio: true；本次生成调用在前台阻塞至完成并返回 status: completed + resultFiles[].localPath（第 1 节"仍要 --wait --claim 核验"的情形），--claim 落账后 probe 与自报值一致。
• duration 只吃整数，小数会被拒。

时长下限有两套口径，别混说：官方文档写 H3 是 4 秒起；本机历史实测只验证过 5 秒可用，4 秒这一档没验证过。要 4 秒时按"文档允许、本机未验证"如实说明，不要断言一定能做，也不要为了验证它花钱试探。

没有自动默认值。 时长和画幅都是闸一的必填项，用户没给就停下索取。可以给建议（单镜头从 5 秒起，多分镜按分镜数 × 3~6 秒估算），但建议必须经用户采纳才能写进参数。

3.3 输入素材上限

模型口径（H3 全能参考入口）：

| 素材 | 上限 | 附加条件 |

|---|---|---|

| 图片 | ≤ 9 张 | 单张 ≤ 30 MB；JPG / JPEG / PNG / WEBP / HEIC / HEIF |

| 视频 | ≤ 3 段 | 单段 2–15 秒、总 ≤ 15 秒；单段 ≤ 50 MB；H.264/H.265，内含音频 AAC/MP3 |

| 音频 | ≤ 3 段 | 单段 2–15 秒、总 ≤ 15 秒；单段 ≤ 15 MB；WAV/MP3；需搭配图片或视频 |

| 混合合计 | ≤ 12 个文件 | API 请求体 ≤ 64 MB |

| 图片尺寸 | 宽高均在 [256, 5760] | 宽高比 5:2 ~ 2:5 |

通道口径（本机实测，比模型严）：miora 通道对参考图做 ≤ 4 张 校验，超了直接返回

UPSTREAM_ERROR: input.reference_images must contain no more than 4 elements (10005)

• 这是提交层校验失败，不产生生成任务、不计费，可以放心重投。
• 差异在通道侧，不在模型侧：绝不能说"模型只支持 4 张"——官方是 ≤ 9 张，用户一核对就穿帮。
• 超 4 张时按主体优先级取 4 张（主角 / 场景 / 关键道具 / 主要对手），落选素材的设定降级写进提示词文字描述，交付时逐条披露。
• 取舍的真正标准是"文字还原难度"，不是照抄上面那句列举顺序：机械道具（车辆、武器等精密结构）、角色身份最依赖参考图，优先保留；环境最容易靠文字承载（地表材质、光线、远景元素都可写清），可最先舍弃。实测案例：8 张素材里同时有摩托与折叠钢刀两个机械道具时，舍场景图保两张道具图，比分给场景一票更划算。
• 加一条判据：看这个元素在分镜里出镜多少、离镜头多近。 全是近身中景 / 特写时，环境只是背景纹理，场景图首先舍；反过来有大远景、环境即主体的镜头，场景图就值得占一席。同理，末镜只有远景剪影的怪物，属"角色身份"仍优先于环境，但取全身三视图而不是头部特写——远景用不上头部细节。实测：一件四镜全为近身格斗的片子，舍场景图、保"主角 / 武器 / 近身对手 / 远景巨兽轮廓"四张最划算。
• 加一条判据：同一角色有多个形态（换装 / 变身 / 前后期形态）时，只保留本单元实际出现的那一个形态。 形态切换发生在同一个单元内时才需要两张同留——因为"从 A 形态变到 B 形态"这个过程需要模型同时看到起点和终点。反之，单元全程是 B 形态、A 形态 0 出镜时，占一张 A 的槽位就是浪费。实测（2026-09-17）：同一角色素材里有"基础服三视图"与"战斗装甲三视图"，前一单元是装甲自脊柱向全身延展的展开过程 → 两张都留；后一单元全程装甲形态、基础服 0 出镜 → 舍基础服，把槽位让给对手的头部特写（该单元有两处怼头部的关键表现：抬头咆哮、脑后贯穿），取舍正确。
• 先核对「声明的形态」是否真的对应到文件，别照抄附件路径。 实测（2026-09-17）：用户用 @image#1 / @image#2 分别声明「岚·基础战斗服」与「岚·战斗装甲形态」，但两次附的是同一个文件（岚基础三视图.jpg 出现两遍），而素材目录里存在语义对应的 战斗装甲三视图.jpg（Read 该图目视确认为同一角色的全装甲形态）。这是附件滑档，不是用户想拿同一张图当两个形态。处置：① 先去素材目录按形态语义找同名 / 近名文件，用 Read 目视确认是不是同一角色的那一形态；② 确认后按形态语义替换进槽位——槽位有冗余时（唯一素材数 < 4）替换不挤占任何素材，因此不必停机回问，但必须在交付说明里显著披露"改用了哪张、为什么、声明的原路径是什么"；③ 若槽位无冗余（替换会挤掉别的素材）或找不到语义匹配的独立文件，回问，不许替用户决定。判据是"有没有把人原本要的素材挤出去"，不是"有没有动过路径"。
• 想把更多素材塞进 4 个槽位，唯一可行办法是离线拼参考板（本地 PIL 拼接，不重新生成、不损失像素），例如"怪兽全身三视图 + 头部特写"拼成一格。这改动了用户素材，必须先问用户。

3.4 提示词与参数

• 提示词上限 7000 字符。
• 关键描述后可用 [运镜] 指令引导镜头调度——官方推荐的精度控制手法，写镜头语言的段落可以用它。
• H3 自带原生音频输出，没有关音频的参数。所以"无配乐 / 无字幕"这类要求只能写进提示词去压，交付时如实说明这是提示词层面的约束，不是参数保证。
• 对白（人声）：没有台词输入通道。 能把"有人在说话"生成出来，但不保证按你写的句子咬字，也没有逐字配音的可控手段。处理办法：把台词写进提示词时明确标成表演提示（谁在说、什么语气、停顿在哪、口型要有开合），并写明"不做字幕、不做文字叠加"；不要去承诺台词会念对。
• 混音类的描述（"对白期间压低环境声、保留空间底噪"）是后期工序，生成端做不到。照原文写进提示词可以（它会往那个方向靠），但交付时必须说清这是后期的事，别让用户以为生成端已经做了。用户脚本里带这类注记时，通常意味着他本来就有后期配音/混音流程——照投，别为它停工。
• 参数名对照（解读上游报错时用）：miora 的 aspect_ratio = API 的 ratio；miora 的 references 到上游是 input.reference_images；图生视频模式下 ratio 恒为 adaptive，画幅由首帧图决定，不能另行指定。

3.5 闸门二：时长区间 —— 先说，不许先试

时长参数（闸一必填项）落在合法区间之外时，不要调用 miora，直接用文字向用户说明做不到并给出原因。

H3 的合法区间是 4–15 秒（整数）。但 4 秒这一档本机没有验证过（见 3.2），所以：

• 要 < 5 秒 → 说明本通道实测可用下限是 5 秒；文档写的下限是 4 秒但本机未验证，要不要按 4 秒试一次由用户决定，不要自己替他决定，也不要自己花钱去探。
• 要 单次 > 15 秒 → 说明单次最长 15 秒，明确做不到。

不许主动帮用户拆分提示词，也不许分镜分批提交生成。 拆分与否是用户的决定，不是你的补救手段：用户明确要求分批时再照做。

同样不许的三种"假装满足"：

• 把参数写成用户要的值，指望模型自己截断或拉长；
• 把超限需求悄悄做成多条，交付时宣称"完成了"；
• 事后把规格不符说成已实现。

两道闸门都在作业流程之前：先过闸一（四参数齐否）→ 再过闸二（时长在区间内否）→ 才走第 4 节。任一不过就停在原地向用户说明，不许提交。

3.5.1 上游 context ir 报错（实测 2026-09-17）

提交后立即返回 status: failed，errorMessage 为：

1033: system error, MiniMax-H3 context ir (status_code=2000)

含义与处置：

• context ir 指官方的提示词增强环节，失败发生在上游处理链路上，不是参数非法——本次四参数（参考生视频 / 768P / 15s / 16:9）与 4 张参考图全部合法。
• 先用 miora_query_task 复核，别凭猜：本次复核返回同为 failed，确认不是 pending 假象，可以放心重投。
• 实测：约 2400 字中文提示词首投失败 → 压缩到约 1800 字、其余参数与素材全部不变，重投一次成功（15.08s / 1344×768 / 有音轨，约 9.7 分钟落盘）。
• 因果未证实：无法排除上游瞬时抖动，所以不要写成"提示词超长必然触发"。但压缩提示词是低成本的差异化重试手段，优先于原样重投（没有新证据不原样重试）。
• 反向数据点（2026-09-17）：约 1900 字中文提示词 + 3 张参考图，首投即通过（8.2 分钟落盘）。所以 1900 字档是已验证可过的量级——用户分镜脚本落在这一档时直接逐字提交即可，不必预先压缩；压缩只留作首投失败后的差异化手段。
• 失败任务不产生成片、无 resultFiles，重投属于新的一次生成，须向用户说明。

3.5.2 提交返回 MIORA_UNAVAILABLE / ENOTFOUND（实测 2026-09-17）

提交调用可能返回：

{"code":"MIORA_UNAVAILABLE","message":"Miora /api/ai/workbuddy-proxy/video/query-task unreachable: ENOTFOUND.","upstreamTaskId":"v89618551-..."}

含义与处置：

• 这是提交已受理、结果回传通道断了（query-task 域名 DNS 解析失败），不是提交失败。返回值带 upstreamTaskId = 上游确实收了任务。
• 按 resumeHint：不要重投（重复计费，且两份成片归属互相干扰）。先 miora_query_task 复核，再靠第 4 节的本地落盘等待收结果。
• 复核时大概率先撞 AUTH_INVALID_TEMP_KEY——重新 connect_cloud_service 取一次再查即可（与第 1 节的凭据不稳描述一致）。
• 实测链路：提交报 ENOTFOUND → 复核 pending → 本地等待正常出片（15.08s / 1344×768 / 有音轨）。这条路上"接口不可达"从不等于"生成失败"。
• query_task 返回 pending 时附带的 Request failed with status code 400 不改变 pending 这个结论，也不是任务出错的证据；本地无文件就是没成品，继续等。

3.6 官方有、本通道没暴露的能力

用户问到这些时，如实说是通道没开，不要承诺：

| 官方能力 | 本通道情况 |

|---|---|

| MiniMax H3 Max（480P/768P、生成更快、时长 5–15s） | 没有模型选择参数，调不到。用户要"更快"或"480P"时说明做不到 |

| 视频再生成（拿已有 768P 成片 + 原 content 重跑出 2K） | 没有对应工具。想要 2K 只能直接以 2K 重新生成一条，那是新的一次计费生成，须先经用户同意 |

| H3-Context-IR（只返回增强提示词、不生成视频） | 没有对应工具。提示词增强由本 skill 第 6 节自己做 |

| 参考视频 / 参考音频输入 | miora 的参考生视频只收图片，没有视频、音频通道。用户想用参考视频驱动动作或配参考音频时，说明通道不支持 |

| 取消 / 删除任务 | 提交后无法取消 |

4. 作业流程

先过两道闸门：闸一（3.1）四个必填参数是否齐 → 闸二（3.5）时长是否在区间内。任一条不过就停下向用户说明，不许提交。

① 登记   python scripts/miora_watch.py --submit --job <作业名>
② 生成   mcp__miora__miora_*_video（tempKey + 参数）
          ↑ 返回值丢失属正常，不因此重发
②.5 认领 返回值带了 localPath → --wait --claim <localPath> --job <作业名>
          ↑ --claim 是修饰项，必须挂在一个动作上。实测 2026-09-16：单独跑 --claim 报
            "one of the arguments --submit --wait --poll --poll-all is required"
          ↑ 有绑定就用绑定；没返回就跳过，走 ③ 的扫描
③ 等待   python scripts/miora_watch.py --wait --job <作业名> --timeout 1800
④ 核验   从 ③ 的 probe 读时长/分辨率/音轨，与确认过的规格对照

作业名撞车是会真实发生的：同一台机器上多个会话可以同时在生成，时间窗一重叠，"since 之后最早落盘的文件"就不一定属于你。实测过一次：并发作业 22:42:22 提交、本作业 22:44:49 提交，前者的成片 22:49:09 落盘，被本作业的 --wait 认成了自己的结果；本作业真实的成片 22:50:46 才落盘。

两个防线：

• 脚本扫描时跳过其他作业标记里已登记的 file（claimed_by_others），避免认领别人已经拿走的产物；
• 仍存疑时用返回值里的 signedUrl 做指纹对账：下载它，与本地候选文件比 md5。实测这一招能唯一确定归属（signedUrl 与本地文件字节一致）。signedUrl 有效期短，要趁早；它只用于核对，不要交给 present_files。

别把并发作业的成片交出去：两份片子若参数相同、时长相同，靠 probe 分辨不出来，只能靠提交时刻 + 指纹归属。归属没定之前不要写画布、不要 present。

作业名用有意义的名字（lan-15s、shot-03），不要随机串。三个动作都必填 --job，脚本会拒绝空名——空名会生成一个名为 .json 的伪作业污染列表。

忘了在生成前登记也没关系：--wait / --poll 会自动从当次调用时刻起算并补登记，链路不会断。

③ 返回码 2 表示超时，不是失败，转入第 5 节；--wait 被上层超时打断就改后台运行，用任务 id 收结果。

脚本怎么调（Windows 本机实测）：用 Python 绝对路径，脚本路径写 Windows 风格。

"/c/Users/<username>/.workbuddy/binaries/python/versions/3.13.12/python.exe" "C:/Users/<username>/.workbuddy/skills/miora-video-studio/scripts/miora_watch.py" --submit --job <作业名>

两个坑：① 脚本路径传 /c/Users/... 这种 Git Bash 形式会被错误转换成 c:\c\Users\...，报 No such file or directory——脚本路径必须用 C:/...；② 某些会话里 Bash 的 ls / head / cat / which 会 command not found（PATH 缺失），所以脚本输出不要走管道，直接读 stdout，文件探查改用 Glob / Read 或 Python 绝对路径。

两个补充（同样是实测踩到的）：

• 别把路径存进 shell 变量再展开。SK="/c/Users/.../miora_watch.py"; "$PY" "$SK" 一样会被转成 c:\c\Users\...。路径一律写成 C:/... 字面量，不要中转。
• 本机可能没有 curl、没有 ffmpeg。要下载返回值里的 signedUrl 做指纹对账时，用 Python urllib.request；要读视频头规格时，直接 importlib 加载本脚本复用它的 probe()，不必另装工具。

5. 状态同步

| 路径 | 命令 | 适用 |

|---|---|---|

| 同轮闭环 | --wait | 主力。一次轮询就能等到，用户不用再说话 |

| 显式绑定 | --wait --claim <localPath> --job <名> | 生成调用返回值里带了 localPath 时先跑这个，再用 --wait 核验 |

| 跨轮兜底 | --poll --job <名>；新会话用 --poll-all 恢复现场 | 轮到点结束、应用重开后再回来 |

返回码是给上层判断的语义：0 已完成 ／ 2 超时（≠失败）／ 3 仍在生成。作业状态另有 unknown——标记缺失或损坏，无法判定，不等于完成。

后台 --wait 被打断（实测 2026-09-17）：放进后台跑的 --wait 可能被会话切换 / 应用重开 kill，返回 status: killed 且无任何输出，长任务尤其容易撞上。处置：

• 跑一次 --poll 确认当前状态；
• 再重新挂一段 --wait 接着等——since 已登记，续挂不丢上下文、不重复计费；
• killed 不是失败，更不是重投的理由。

长任务建议分段挂（单段 --timeout 900 ~ 1500），比一次挂 1800 秒更抗打断。

三条判定铁规（都是踩过坑才定下来的，改脚本时别破坏）：

• 取 since 之后最早出现的文件，不取最新的。 两个作业时间窗重叠时，取最新会把后提交作业的成片误认成前一个作业的结果——这是真实会发生的误报。
• 已被别的作业认领的文件要排除掉。 只靠上一条仍会撞车：并发作业的成片先落盘时，会被后来的作业抢先认成自己的结果（实测过一次，且两份片子 probe 完全相同、无法用规格分辨）。脚本用 claimed_by_others() 实现，别删。
• since 一旦登记就永不丢失。 无法确定 since 的标记一律标 unknown 并跳过扫描，绝不 fallback 到 0；回退到 0 等于扫描全部历史文件，必然把上一轮的旧成片报成本次完成。

其余可靠性来源：

• 体积稳定判定：连续两次读数一致才认定写完，排除半写文件误报完成。
• 文件头核验：解 mvhd 读时长、tkhd 读分辨率、查 mp4a 判断音轨。
• 标记固定放用户级目录，不随工作目录漂移，换目录、换会话都找得到。

路径：媒体目录 ~/.workbuddy/plugins/data/mcp-miora/miora-media（可用 --media-dir 覆盖）；标记文件 ~/.workbuddy/miora-jobs/<作业名>.json。作业名做成 项目-用途-序号（如 lan-15s-2）以便区分。

没有回调、没有反向唤起。用户不说话时的唯一自动路径是定时自动化——那是例外手段，不要为常规任务常驻。

6. 提示词构建与修正边界

逐字透传的情形：用户已给完整描述，或示意"就用我的原话"。不扩写、不改词，只允许补第 2 节说的编号映射。

含糊则补全，且必补运动——只写静态画面会得到一段几乎不动的视频。四件事说清：

• 主体在做什么（具体动作，不是"一个人站着"）；
• 镜头怎么动（推 / 拉 / 摇 / 跟 / 环绕，一个镜头只用一种运动，叠加会乱）；
• 光线与氛围（主光方向、软硬、色温 + 氛围词）；
• 结束状态（镜头停在哪，不写结尾容易飘）。

写镜头的第 2 条时可用官方支持的 [运镜] 指令：在关键描述后面直接跟 [运镜]，引导镜头调度，比重述一遍自然语言更稳。

总长控制在 7000 字符以内（上限，见 3.4）。用户给的脚本本来就长时，优先保主体身份描述、镜头运动、物理动作和全局约束，压缩美术词藻。

6.1 允许自动改（改完必须在交付说明里逐条披露）

| 明显问题 | 处理 |

|---|---|

| 分镜时间轴重叠、越界、不连续 | 改为顺序衔接并披露 |

| 分镜时间轴合计 ≠ 声明的时长 | 以声明的时长为准（它才是闸一必填项），但时间轴原样保留、不拉伸、不慢放。合计短于声明的 → 把差额写成"延续末镜收尾状态、不新增动作"（实测：10.5s 的分镜放进 13s，末段写"巨兽继续缓慢转身、尘土未落、主角保持跪姿"）；合计长于声明的 → 按比例压缩秒点（实测：14s 压缩到 13s）。两种都要在交付说明里点明冲突与处理方式，并给出"按另一个值重投"的选项。禁止用慢动作、补拍内容或反复切镜去填满时长。 |

| 只有静态描述、无任何运动信息 | 按上面四件事补齐 |

| 未声明参考图角色 / 素材顺序与 @image#N 不一致 | 补角色映射、按用户可见顺序对齐并披露 |

| 设定段里混着本单元并不出镜的条目（惯用固定模板时常见，如"本段有三只怪物缠斗"其实属于上一个单元、或已弃置的道具） | 不许删原文，改为在提示词开头加一段「入画依据」，明确本单元画面里有谁、没有谁；落选者写"仅作世界观背景 / 不在画面内"。实测：一件只有主角与巨兽的单元里，人设仍带着上一单元的小怪条目与弃置摩托，靠「入画依据」段排除，比逐条删改原文更安全、也好披露。 |

| 拼写、标点、明显笔误、格式混乱 | 直接改，保持原意与用词风格 |

| 与显式全局约束冲突（如写了配乐，又要求"无配乐"） | 以显式约束为准并披露 |

| 缺模式 / 分辨率 / 时长 / 画幅中的任一项 | 不许补。这是闸一缺项，停下向用户一次性列全索取（见 3.1） |

| 参考图超过通道上限 4 张 | 按主体优先级裁到 4 张，落选素材的设定改写进提示词文字描述，交付时逐条披露（见 3.3） |

| resolution 声明成 720p / 1080p（已声明但不合法） | 按等价档 768P 投（用户要更高档时 2K）并披露（见 3.2） |

| 提示词超过 7000 字符 | 压到限内，优先保主体 / 运动 / 动作 / 全局约束，交付时说明压掉了什么 |

| 用户要求无配乐 / 无字幕 | 写进提示词（H3 无音频开关），并在交付时说明这是提示词层约束、需目视耳听确认 |

6.2 必须回问，不许自行决定

• 改动主体身份特征、关键设定、台词内容或语气这类用户固定的核心属性；
• 增删参考素材；
• 大幅改变产出规模（条数、时长档位跳变）；
• 用户明确说了"原封不动"的段落——只允许补编号映射，一个字都不许动。

判断不了就问。例外：闸一的四个必填参数（模式 / 分辨率 / 时长 / 画幅）不适用"跳过提问就按默认执行"——那四项属提交前提，用户不声明就一直停着，见 3.1。其余项用户跳过提问时按默认执行并明说。

7. 验收

• 产物真的拿到了：本地路径有效，不是失败占位。
• 实测时长 / 分辨率与确认过的规格一致 —— 读 probe 的值来对，不要复述提示词里写的。
• 用户固定的主体特征没被改掉；同一批成片在同一张画布上；画幅统一。
• 不断言"画面流畅""运镜到位""音效对白正确" —— 文件头读不出来，如实标为需用户目视确认。
• 不合格不要自动重做，是否重做由用户决定。

交付动作（画布、present_files 的参数与顺序）以 miora-creative-core 为准。

8. 两条边界

• 多分镜塞进单次生成，模型会自由取舍，不会严格按你写的秒数切镜头——要精确切分只能分条生成再拼。
• 严格跨条身份一致做不到。 参考图只能逼近，多条之间必有可见差异。用户有硬要求时说明限制让用户决定，不要硬做后交一堆对不上的片子。