维音长任务运行框架

解决什么问题

当一段脚本的执行时间超过执行器对单条命令的墙钟时限（常见是 120 秒），不加防护地前台死等的结局是：进程被杀、返回非 0 退出码、输出为空或半截。下载大文件、批量调用外部接口、大目录扫描、跑求解器、转码——这些任务的共同点不在业务形态，而在预估跑不完那几分钟到几十分钟。vxi-longrun 要解决的就是这类"跑久了就死，死了还不知道跑到哪"的问题。

框架如何工作

技能只供给一件东西：长任务框架。业务侧实现 run(ctx)，框架负责周边机制：

• 进度落盘：每步进度写入 outdir 下的 _status.json，而非停留在内存
• 心跳判活：以 heartbeat_seq 是否递增判断任务存活，不看时间戳新旧
• 检查点续跑：业务通过 ctx.checkpoint() 存状态到 _checkpoint.json，中断后可接着上次继续
• 异常转终态：run(ctx) 主线程抛出的异常统一转成 failed，业务只需处理业务逻辑
• 协作式取消：框架认"继续"与"中止"两种指令
• 进度页：每 5 秒自刷新的 progress.html，任务进程自己写，会话关闭后仍在更新

使用前先跑 selftest 验证框架可用，再照着 example_job.py 改自己的业务代码。判"跑完了没"只认 status=done，判"下一步做什么"只照 next_action。

适用边界与注意点

不适用：一眼几秒跑完的脚本，前台直跑即可；完成与否要靠主观判断的任务（框架只认业务交回摘要 dict 这一机械信号）；要边跑边把内容流式输出给人看的任务；使用者可能中途改向的任务。

最隐蔽的坑：静默 worker 失败。框架只能捕获 run(ctx) 主线程的异常；业务自己开的 worker 线程挂了而主线程照常返回摘要 dict 时，终态会是 done——"部分没跑成"被报成"跑完了"。业务自行开线程就要自己收异常并在主线程判断。

框架不设资源上限：内存占用量、worker 线程数、并发连接数完全由业务自己按目标环境控制。

另外注意别把凭据当命令行参数传：运行台账会在家目录 $LONGRUN_HOME/runs 保留最长 14 天，改用配置或环境变量。