深度解析 AI 解说大师任务轮询模式：5秒 while 循环与必须避开的3个坑-平芜编程栈

深度解析 AI 解说大师任务轮询模式：5秒 while 循环与必须避开的3个坑

【免费下载链接】narrator-ai-cli-skillAI 解说大师 — Agent skill；封装 narrator-ai-cli 供 Claude/Codex 等工具调用项目地址: https://gitcode.com/gh_mirrors/na/narrator-ai-cli-skill

AI 解说大师（narrator-ai-cli-skill）是一个封装 narrator-ai-cli 的 Agent 技能，安装后 Claude、Codex 等 AI 工具就能自动完成电影解说视频的全流程制作。而这条自动化流水线能否稳定跑通，关键就在一个容易被新手忽略的环节——任务轮询。本文带你拆解它的 5 秒 while 循环设计原理，并讲清必须避开的 3 个常见坑。🔍

为什么 AI 解说大师离不开任务轮询？

AI 解说大师的制作流程是一条多步流水线：

搜片 → 选模板 → 选 BGM → 选配音 → 生成文案 → 合成视频 → 返回 MP4 下载链接

其中"生成文案、剪辑数据、视频合成"等每一步都是一个异步任务：你通过narrator-ai-cli task create提交任务后，API 只返回一个task_id，真正要反复查询状态，直到任务完成。

查询命令很简单：

narrator-ai-cli task query <task_id> --json

返回结果中的顶层.status字段就是轮询要盯的信号，状态码含义如下：

状态码	含义	轮询动作
0	初始化	继续等待
1	进行中	继续等待
2	成功 ✅	停止轮询，读取结果
3	失败 ❌	停止轮询，检查错误
4	已取消	停止轮询

官方经验数据：大多数任务30 秒到几分钟内完成，只有search-movie（外部搜片）可能耗时 60 秒以上。所以轮询策略要"足够耐心，又不至于傻等"。

标准答案：5 秒间隔的 while 循环

AI 解说大师在 SKILL.md 的强制规则里写得很明确：

始终用 5 秒间隔的标准 while 循环来轮询，绝不用固定次数的 for 循环。

完整脚本收录在 references/operations.md 的 Task Polling 章节，其核心逻辑可以浓缩为：

while [ "$iter" -lt "$MAX_ITERATIONS" ]; do # 每次查询任务状态 task_status=$(narrator-ai-cli task query "$TASK_ID" --json | 解析顶层 status) [ "$task_status" = "2" ] && break # 成功，退出 [ "$task_status" = "3" ] && break # 失败，退出 sleep 5 # 5 秒后再查 done

这个循环还有两道"保险丝"，是新手最容易漏掉的部分：

空响应保护：连续 12 次（约 1 分钟）解析不到状态（比如网络抖动、CLI 报错返回非 JSON），就主动跳出并打印最后的原始响应，避免"空转"；
绝对上限：最多轮询 720 次（约 1 小时），防止任务卡在某个未知状态时无限等待。

为什么是 5 秒？官方给出的理由是：更快的间隔只会增加 API 负载，没有任何收益；而 5 秒对于"30 秒起步"的任务粒度已经足够灵敏。⏱️

坑一：用 for 循环固定次数，替代 while 循环

这是文档里点名禁止的第一条。写法上很诱人：

"我就循环查询 20 次吧，每次 5 秒，最多等 100 秒，任务肯定好了。"

问题在于：视频合成、标准路径的爆款学习任务等耗时不可控，20 次循环耗尽时任务很可能还在跑。此时脚本悄悄退出，既没有拿到结果，也没有报错——Agent 会误以为流程结束，要么卡死，要么拿着半成品数据往下走。

✅正确姿势：while循环 + 明确的退出条件（status=2或3），让循环"跑完任务才停"，而不是"跑满次数才停"。

坑二：轮询了错误的 status 字段 → 静默死循环

task query返回的 JSON 里其实藏着两个status字段，这是"静默无限轮询"的头号来源（官方原话：Reading the wrong path is the #1 cause of silent infinite polling）：

路径	编码体系	该不该轮询
顶层`.status`	0–4（上表）	✅ 唯一正确答案
`.results.tasks[0].status`	另一套体系（如成功时是`9`）	❌ 永远等不到 2

如果你把目光盯在嵌套的.results.tasks[0].status上，它会返回9这种你循环里根本不认识的值——既不等于2，也不等于3，于是循环不报错地转下去，直到耗尽时间上限。

✅正确姿势：只认顶层.status。完整的响应字段结构表（包括.task_order_num、.files[0].file_id该去哪读）都在 references/operations.md 的 Task Query Response Shape 一节，建议轮询前对照一遍。

坑三：变量命名和类型比较的"隐形地雷"

即使循环逻辑写对了，这两颗小地雷也足以让循环从第一行就炸掉或永远转不完：

地雷 1：变量名叫status？

在 macOS 默认的 zsh 里，$status是只读内置变量（$?的别名）。直接写status=...会报read-only variable: status，循环压根跑不起来。官方脚本特意把变量命名为task_status，就是为了绕开这个坑。

地雷 2：Python 里if s == "2"对比整数状态？

API 返回的status是整数2，如果你在 Python 里写字符串比较s == "2"（或反过来），比较永远不成立，循环会无声地跑满 1 小时上限。要么统一用int比较，要么两边都转成字符串，保持一致即可。

✅自查口诀：变量避开status，类型两边对齐。🧨

轮询超时退出了？任务不会消失

很多人担心"循环超时退出 = 任务被取消"，其实不是：

跳出循环只是停止本地查询，服务端任务仍在独立运行。

恢复方法分三步：

单次查询（不进循环）确认当前状态，如果顶层.status已经是2，直接读取结果字段继续下一步；
状态还是0/1？用同一个task_id重新进入 while 循环即可，API 不关心"谁在轮询"；
task_id弄丢了？用narrator-ai-cli task list --status 1 --json列出所有进行中的任务，按类型或时间找到它。

小结：把这三条规则贴在你的轮询脚本上

#	规则	违反后果
1	用`while`循环，按`status=2/3`退出，不用固定次数`for`	任务没跑完就提前离场
2	只轮询顶层`.status`（0–4 体系）	读到`9`等异体系值，静默死循环
3	变量别叫`status`（zsh 只读）；Python 中 int/str 比较保持一致	循环起不来，或永远不匹配