技能
Reference
Cron-Agent 模式
为通过 cron 编排、调用外部 API(LLM CLI、HTTP、子进程)的 agent 提供分层超时防御 — 嵌套层级、反模式、预留余量。
概述
一个通过 cron 编排、会发起外部 API 调用(LLM CLI、HTTP 客户端、子进程)的 agent 可能会挂起、超出其时间窗口,或与下一次 cron 触发重叠。本技能通过嵌套超时来防御这种情况 — 每一层都严格小于包裹它的那一层 — 再加上对称的截止时间守卫,以及为下一级回退层显式预留的余量。在实现或审查任何按计划运行(cron、systemd timer、sleep 循环)且会发起可能无限期阻塞的调用的 agent 时,加载本技能。
分层超时阶梯
对超时进行排序,使每个内层预算都严格小于包裹它的预算。违反严格嵌套不变式意味着内层永远无法在外层抢占它之前触发 — 内层守卫变成了死代码。
- (a) 单次调用超时 — 为每个单独的外部调用设定上限(HTTP 读取超时、子进程超时、LLM CLI
--timeout)。必须能容纳在 (b) 之内,包括重试和回退。 - (b) 单周期截止时间预算 — 在周期开始时用单调时钟计算一次截止时间;在每次外部调用前检查它。
- (c) SIGALRM 安全网 — 库级超时无法中断阻塞在 C 层系统调用中的调用;设置一个硬闹钟,强制进程回到处理器中。
- (d) Shell 最外层守卫 — 将整个调用包裹在
timeout --kill-after=<grace> <hard-limit> <cmd>中,这是进程内一切均已卡死时的最后一道防线。
该模式与具体技术栈无关 — 各层名称可映射到任何运行时(Python signal/subprocess、Node 定时器/AbortController、Go context、shell timeout)。
反模式
以下每一种都曾导致真实的生产事故:
- 单次调用超时 == 周期预算。 如果单次调用上限等于整个周期预算,那么从数学上就禁止该调用与重试或下一级回退同时容纳。
max(N, deadline - now)下限。 将单次调用超时下限设为一个常量,会在截止时间已经过去之后重新抬高一个注定失败的调用。绝不要为剩余预算设下限 — 如果它为零或负数,就跳过该调用。except Exception: pass吞掉闹钟。 在调用体周围使用裸异常处理器会静默吞掉 SIGALRM 抛出的异常,导致安全网永远无法传播。在通用处理器之前重新抛出超时异常。
必需的守卫
- 每个回退层中对称的截止时间已过守卫。 回退链(主 → 次 → 三级提供方)必须在每一层之前检查截止时间,而不仅仅是在第一层之前。
- 为下一级回退显式预留余量。 从交给每一层的预算中减去一个具名预留常量,这样在主层超时后回退仍能运行。没有余量,主层会消耗掉整个预算,回退一启动就已死亡。
检查清单
- 每个超时层都严格小于包裹它的层(a<b<c<d)
- 周期截止时间在周期开始时用单调时钟计算一次
- 单次调用超时绝不会被下限重新抬到剩余预算之上
- 在每次外部调用和每个回退层之前都检查截止时间
- 为 C 层阻塞的系统调用设置 SIGALRM(或等价物)
- 在任何通用异常处理器之前重新抛出超时异常
- 为下一级回退层显式预留余量
- Shell
timeout --kill-after作为最外层守卫包裹整个调用