# Choose Loop Wakeup Interval

> 通过 `ScheduleWakeup` 工具或 `/loop` 斜杠命令调度循环唤醒时，选择 `delaySeconds` 值。涵盖三档缓存感知决策（缓存温热小于 5 分钟、 缓存未命中 5 分钟到 1 小时、空闲默认 20 到 30 分钟）、300 秒反模式、 [60, 3600] 运行时夹紧、分钟边界舍入特性，以及编写有遥测价值的 `reason` 字段。在设计自主循环、规划心跳节奏、调优轮询节奏，或事后审查循环成本 发现间隔尺寸不当时使用。

- Skill: `pjt222/choose-loop-wakeup-interval-4` (Agent Skill)
- Install (CLI): `npx get-skill add pjt222/choose-loop-wakeup-interval-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/choose-loop-wakeup-interval-4/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: pjt222 (https://skillmd.com/u/pjt222)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/pjt222/choose-loop-wakeup-interval-4

---


# 选择循环唤醒间隔

为 `ScheduleWakeup` 选择一个 `delaySeconds` 值，以尊重提示缓存的 5 分钟 TTL、调度器的整分钟粒度以及 `[60, 3600]` 运行时夹紧。该决策在结构上并不简单：常见直觉"等约 5 分钟"恰好落入两面皆差的区间 —— 既支付缓存未命中的代价，又未能摊销等待。

推理随 `ScheduleWakeup` 工具描述在工具调用时出现，但那时循环已经在被调度。本技能将该推理提前到规划时刻，那才是它该在的地方。

## 适用场景

- 设计自主 `/loop` 或 `ScheduleWakeup` 驱动的延续，并选择每次 tick 的延迟
- 为长时间运行的代理规划心跳节奏（将进行轮询、监视或迭代）
- 针对成本或缓存温热压力调优轮询节奏
- 事后审查循环成本并发现间隔尺寸不当
- 编写涉及选择 `delaySeconds` 的指南、运行手册或工作示例

## 输入

- **必需**：循环正在等待什么（特定事件、状态转换、空闲 tick、定期检查）
- **必需**：此 tick 的读者是否需要新鲜上下文（缓存温热）或可容忍冷重读（缓存未命中可接受）
- **可选**：所等待事件可能发生的最早时刻的任何已知下界（如"构建至少需要 4 分钟"）
- **可选**：整个循环的成本上限（tick 数 × 每 tick 成本）

## 步骤

### 第 1 步：分类等待

决定等待属于哪个层级：

- **主动监视（缓存温热）**：预期接下来 5 分钟内会发生变化 —— 即将完成的构建、被轮询的状态转换、刚刚启动的进程
- **缓存未命中等待**：从现在起 5 分钟内没有值得检查的事；上下文缓存会变冷且这是可接受的
- **空闲**：没有特定信号要监视；循环检查是因为它*可能*发现什么，而非*将会*发现什么

**预期结果：** 清晰的分类：active-watch、cache-miss 或 idle。

**失败处理：** 若等待无法分类 —— 若对"我在等什么？"没有诚实答案 —— 该循环可能不应存在。跳到第 5 步并考虑根本不调度唤醒。

### 第 2 步：应用三档决策

基于分类选择 `delaySeconds`：

| 档位 | 范围 | 缓存行为 | 何时使用 |
|---|---|---|---|
| 缓存温热 | **60 – 270 s** | 缓存保持温热（低于 5 分钟 TTL） | 主动监视 —— 下个 tick 需要快速、便宜的重入 |
| 缓存未命中 | **1200 – 3600 s** | 缓存变冷；一次未命中买来漫长等待 | 真正空闲，或所等待事件不可能更早发生 |
| 空闲默认 | **1200 – 1800 s**（20–30 分钟） | 缓存变冷 | 无特定信号；用户可中断的定期检查 |

**不要选 300 s。** 它是两面皆差的间隔：缓存未命中，但等待太短无法摊销未命中。如果你发现自己想"约 5 分钟"，降到 270 s（保持温热）或承诺 1200 s+（摊销未命中）。

**预期结果：** 从三档之一选择特定的 `delaySeconds` 值，而非习惯性挑选的整分钟数。

**失败处理：** 若选择不断落到 300 s，潜在问题通常是"该循环是否应以此节奏存在？" —— 重新审视第 1 步。

### 第 3 步：为分钟边界留余地

调度器在整分钟边界触发。`delaySeconds` 为 `N` 会产生 `N` 到 `N + 60` 秒的实际延迟，取决于你在哪一秒调用工具。

工作示例：

> 在 `HH:MM:40` 调用 `ScheduleWakeup({delaySeconds: 90})` 产生目标 `HH:(MM+2):00` —— 即实际等待 140 秒，而非 90 秒。

后果：亚分钟意图毫无意义。将传入的值视为**底线**，而非精确调度。如果一分钟的偏差很重要，你的循环节奏对此机制而言太紧。

**预期结果：** 你已接受实际等待将比请求的 `delaySeconds` 多最多 60 秒。对缓存温热 tick 这很重要 —— 270 s 在实际中可能变为约 330 s，倾入缓存未命中区域。

**失败处理：** 若接近上限的值（如目标缓存温热时的 265 s）很常见，向下填充 —— 使用 240 s 而非 270 s，以在最坏分钟边界偏差下仍保留缓存温热保证。

### 第 4 步：尊重夹紧

运行时将 `delaySeconds` 夹紧到 `[60, 3600]` —— 范围外的值被静默调整。遥测区分模型请求的内容（`chosen_delay_seconds`）与实际调度的内容（`clamped_delay_seconds`），并在任何不匹配时设置 `was_clamped: true`。

针对夹紧后的值进行规划，而非请求的值：

- 请求低于 60 → 实际等待为 60 秒加分钟边界偏差（实际中最多 120 秒）
- 请求高于 3600 → 实际等待为 3600 秒（1 小时）
- 没有运行时延伸上限；多小时等待需要多个 tick

**预期结果：** 你选择的值落在 `[60, 3600]` 内，或你已刻意接受夹紧行为。

**失败处理：** 若需求确实是多小时（如"4 小时后叫醒我"），链接唤醒 —— 调度一个 3600 s tick 自身重新调度 —— 或改用基于 cron 的循环（`CronCreate` with `kind: "loop"`）。

### 第 5 步：写一个具体的 `reason`

`reason` 字段是遥测、用户可见状态和提示缓存温热推理三合一。被截断到 200 个字符。要具体。

- 好：`checking long bun build`、`polling for EC2 instance running-state`、`idle heartbeat — watching the feed`
- 坏：`waiting`、`loop`、`next tick`、`continuing`

此字段的读者是试图理解循环在做什么的用户，他们不必预先预测你的节奏。为他们而写。

**预期结果：** 一个具体的、单短语的 reason，让一眼看状态的用户看得懂。

**失败处理：** 若给不出具体 reason，重新审视该循环是否应存在（第 1 步和第 6 步）。

### 第 6 步：识别"不要循环"的情况

并非每个"稍后再来"的冲动都值得调度唤醒。**不要**调度 tick 的情况：

- 用户正在主动观看 —— 他们的输入才是正确触发，而不是计时器
- 没有收敛标准 —— 循环没有"完成"的定义
- 任务是交互式的（在 tick 之间询问用户）
- 所需节奏短于夹紧底线（60 s）—— 那么紧的轮询属于事件驱动机制，而非循环

**预期结果：** 在调度唤醒和根本不循环之间做出有意识的选择。"因为我能"不是循环的理由。

**失败处理：** 若你不断调度被用户在触发前打断的唤醒，模式错了 —— 而不是间隔。

## 验证清单

- [ ] 等待被分类为 active-watch、cache-miss 或 idle（三选一）
- [ ] 选择的 `delaySeconds` 落在三档范围之一（60–270、1200–3600，或 idle 的 1200–1800）
- [ ] 值不是 300（两面皆差）
- [ ] 值在 `[60, 3600]` 内或显式接受夹紧行为
- [ ] 已考虑分钟边界偏差（将值视为底线）
- [ ] `reason` 具体且少于 200 字符
- [ ] 已执行"不要循环"检查 —— 唤醒确实有理由

## 常见问题

- **整分钟默认值（300 s）**：最常见的单一错误。"约 5 分钟"感觉自然但恰恰错误。降到 270 s 或承诺 1200 s+。
- **忽略分钟边界偏差**：在分钟末尾请求 60 s 会产生约 120 s 实际延迟。对缓存温热 tick，这可能意外推过 5 分钟 TTL。
- **追求亚分钟精度**：调度器有分钟粒度。请求 85 s vs 90 s vs 95 s 是噪声 —— 选个值继续走。
- **不透明的 `reason` 字段**：`"waiting"` 没告诉用户什么，使遥测不太有用。把 reason 写得像用户会在状态行上读它。
- **用此技能来证明不必要的循环合理**：若对"我在监视什么？"的诚实答案模糊，没有间隔选择会有帮助 —— 该循环不应存在。
- **在提示中手动夹紧**：不要在模型推理中夹紧（"我会在 3600 处封顶以保险"）。运行时会夹紧。让它来。
- **遗忘 7 天老化**：动态循环默认 7 天后被回收（用户可配置最多 30 天）。长时间运行的循环应设计为远在该上限之前结束，而非与之竞速。

## 示例

### 示例 1 —— 缓存温热主动监视

`bun build` 已启动；代理希望快速登记，以便结果到达时缓存仍温热。

- 分类：主动监视（第 1 步）
- 档位：缓存温热（第 2 步），选 **240 s**
- 分钟边界（第 3 步）：最坏情况实际等待约 300 s —— 在 60 s 缓冲下仍低于 5 分钟 TTL
- Reason（第 5 步）：`checking long bun build`

### 示例 2 —— 空闲心跳

自主代理每小时监视一次低流量信息源，寻找值得行动的事项。

- 分类：空闲（第 1 步）
- 档位：空闲默认（第 2 步），选 **1800 s**（30 分钟）
- 分钟边界（第 3 步）：无关 —— 在此节奏下 60 s 偏差可忽略
- Reason（第 5 步）：`idle heartbeat — watching the feed`

### 示例 3 —— 反模式

代理希望"等 5 分钟"等远程 API 重试。请求是 300 s。

- 问题：缓存在 5 分钟变冷，所以 300 s 支付未命中 —— 但 300 s 太短无法摊销未命中
- 修复：降到 270 s（保持温热）或承诺 1500 s（摊销未命中）。不要选 300。

## 相关技能

- `manage-token-budget` —— 长寿代理循环的成本上限；缓存感知尺寸是一个杠杆
- `du-dum` —— observe/act 分离模式；当循环无 cron 时，此技能调整观察时钟间隔
- `read-continue-here` —— 跨会话交接；此技能涵盖会话内唤醒
- `write-continue-here` —— `read-continue-here` 的对偶

<!-- Keep under 500 lines. Current: ~200 lines. -->

