MAI × TOBATSU · VOICEOVER HOTFIX · TEST ONLY

这次修的是模板跑崩后，Mai 看不到结果的问题

真实 Ignis CLI 已重跑。任务从 Mai 发起，Tobatsu 执行，回调回 Mai Gateway，然后自动写入画布和 `session_messages`。这次没有改 Mai 代码和 DB schema。

01 · 原因

原来为什么前端看不到

不是 Mai Gateway 没接住，也不是 canvas queue 坏了。最早那条任务在 Tobatsu runner 还没读到 payload/callback 前就崩了。

63e5

第一次挂在 import

`voiceover_align.py` 里有 `@dataclass`。runner 用 `importlib` 导入时没有先注册 `sys.modules`，Python dataclass 直接炸了。

没有 callback

Mai 没收到失败

当时还没读 `.tobatsu/context.json`，callback 地址和 token 都没进 runner，所以没法发 `business_failed`。

aa6c

第二层 bug 暴露

v17/v9 修了 import 后，又发现 runner 读 `seg["duration"]`，但 helper 没返回这个字段，于是先 failed 再 self-repair。

02 · 修复

Tobatsu 改了两层，Mai 没改代码

这轮 hotfix 都在 Tobatsu 模板 / skill 侧。Mai 只负责真实发起和回读验证。

版本	改了什么	为什么有用
`voiceover-align v18`	helper `validate_payload()` 返回 `duration` 和 `duration_seconds`，两者都等于 `end - start`。	runner 读 duration 不会再 `KeyError`。即便字段名写错，也会被归成 self-repair。
`voiceover_align workflow v10`	明确 `KeyError` / 字段名 typo 是 agent-owned bug，先修 runner 重跑，再考虑失败 callback。	不再出现“内部代码能修，但已经把 Mai 标失败”的顺序问题。
`mai-platform-delivery v7`	继续用安全 callback 规则：curl、有 UA、有超时、先回调再 terminal。	避免前面发生过的 CF 拦截、callback 卡死、terminal 顺序错。

03 · 真实测试

这条 E2E 是这样跑完的

输入沿用旧素材：`bz1VuX.mp4` + `TdhTyT.json`。CLI 明确要求只提交 `new_task`，不查状态。

Ignis CLI新 session 发起口播对齐任务。

Agent loads skills`mai-async-gateway` + `voiceover-align`。

Gateway accepted`gw_1abf13b2` / `gwr_32833f74`。

Tobatsu runs`voiceover_align v10` + `voiceover-align v18`。

Callback returns`business_success`，HTTP 200。

Mai writes resultR2 file_id、canvas、session message 都写入。

04 · 结果

Mai 里最后写进去了什么

画布里只显示视频和音频。SRT 是 sidecar，挂在视频文件上，不单独占一个 canvas 元素。

核心 DB 状态

tasksucceeded
runsucceeded
callbackbusiness_success: succeeded
business_failed0
platform_terminal0
canvas jobcjob_a784e845 · succeeded · attempts=1

导入的文件

Wz0nan.mp41280×720 · 5062ms · 2,937,728 bytes
WEZLM1.mp35120ms · 82,382 bytes
YIW9k5.srtsidecar · 446 bytes
canvasrevision=1 · files=2 · elements=2

05 · 失败提示

失败也会写一条 tobatsu_result

最终成功样例证明的是成功链路。失败链路用上一条真实复测 `aa6c5715` 证明：Mai 收到 `business_failed` 后写 DB 和 `session_messages`。

失败样例

gateway_taskgw_6a4542ac-3645-43cd-aa74-74acdaa21ffe
gateway_rungwr_cad78969-f903-4153-9099-90b13e31048a
tobatsu_taskaa6c5715-0153-4aea-a035-7b876ea2b6a6
callbackbusiness_failed · failed
message seq286105

{
  "type": "tobatsu_result",
  "status": "failed",
  "summary": "未能生成配音视频：voiceover runner internal error: KeyError",
  "error": {
    "code": "internal_error",
    "message": "voiceover runner internal error: KeyError"
  },
  "file_ids": [],
  "artifacts": [],
  "canvas_id": "2b39bcb1-d78d-4525-9165-7dd199451f04",
  "task_type": "voiceover_align",
  "gateway_task_id": "gw_6a4542ac-3645-43cd-aa74-74acdaa21ffe",
  "gateway_run_id": "gwr_cad78969-f903-4153-9099-90b13e31048a",
  "gateway_result_id": "9ace8eae-a90f-489b-88fc-fea5aa378810"
}

关键区别： 原始 `63e5` 崩在 runner 读 callback 之前，所以那条老任务没有自动失败消息。修复后，后续失败会走 `business_failed`，写 `tobatsu_result`。如果前端在线，实时通知拿同一份 `message_data`；如果不在线，session history / system reminder 也能补账。

06 · 给前端看

前端会看到这些格式

提交任务时不给资产。结果回来后，Gateway 自动写 canvas 和 `session_messages`。

{
  "ok": true,
  "accepted": true,
  "gateway_task_id": "gw_1abf13b2-180f-4b3d-8ad6-8a7565658308",
  "message": "任务已提交。完成后会自动更新画布，并在后续对话中提示结果。",
  "poll": {
    "action": "get_task",
    "gateway_task_id": "gw_1abf13b2-180f-4b3d-8ad6-8a7565658308"
  }
}

{
  "type": "tobatsu_result",
  "status": "succeeded",
  "summary": "已生成中文配音并合成视频，字幕已烧录。",
  "file_ids": ["Wz0nan.mp4", "WEZLM1.mp3", "YIW9k5.srt"],
  "canvas_id": "70e1cf83-8267-41c0-ad4e-15d5d22766d5",
  "task_type": "voiceover_align",
  "gateway_task_id": "gw_1abf13b2-180f-4b3d-8ad6-8a7565658308",
  "gateway_run_id": "gwr_32833f74-95b7-4c81-85f4-df66b642a27c",
  "gateway_result_id": "dc55b4c9-61d9-4a6a-8d28-a39f0ad8383d"
}

人话版： 用户提交后，前端先看到“任务已提交”。等 Tobatsu 回调，Mai 自动把 `Wz0nan.mp4` 和 `WEZLM1.mp3` 放进画布；`YIW9k5.srt` 挂在 `Wz0nan.mp4.sidecars[]`。前端可以用 `session_messages` 里的 `tobatsu_result` 告诉用户任务完成。

07 · 注意

还有什么没动

这次是 test 环境 hotfix 验证。没有发 prod，也没有改 Mai 代码。

项	状态	说明
Mai code/schema	未改	这轮只验证 Tobatsu 模板修复。
旧 63e5 task	未手动补账	老任务当时已卡住。新模板已通过新任务证明修复。
Prod	未发	当前证据来自 test。prod 需要单独授权。