技能 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 作为最外层守卫包裹整个调用