loopify

/loopify — 设置 Agent 循环

从 “这项任务应该定期运行” 到搭建一个节奏合适、具备幂等性且能主动退出的循环的向导。参考（Claude Code）：ScheduleWakeup（动态调整节奏）、CronCreate（固定计划）和内置的 /loop（动态自主调整节奏并重新进入）。其他宿主：请参阅第 4 步中的“在 Claude Code 以外的宿主上”。

步骤 0 — 确认循环要执行什么

如果上下文中不明显，请询问：“这个循环每次迭代要执行什么任务？”

然后确认必要信息：

问题	重要性
多久运行一次？	决定采用 cron、动态调整节奏还是单次运行
何时停止？	退出条件——循环必须有退出条件
循环体要做什么？	决定幂等性要求
输出放在哪里？	文件／通知／提交／无
如果运行两次，会出现什么故障？	验证幂等性

步骤 1 — 选择模式

主要有三种模式。根据“多久运行一次”的答案进行选择：

模式 A — Cron（固定计划）

适用场景：任务按可预测的间隔运行——每天早上 8 点、每周五、每小时整点。

工具：CronCreate — 使用 cron 表达式安排周期性任务。

CronCreate({
  schedule: "0 8 * * *",           // daily at 8am local
  prompt: "<loop body prompt>",
  timezone: "America/Los_Angeles"
})

常见 cron 模式：

• 0 8 * * * — 每天早上 8 点
• 0 9 * * 1 — 每周一早上 9 点
• 0 9 * * 5 — 每周五早上 9 点
• 0 */2 * * * — 每 2 小时
• */15 * * * * — 每 15 分钟

权衡：

• ✅ 可预测、易读，便于理解
• ✅ 最适合依赖一天中具体时段的任务（晨间简报、日终总结）
• ❌ 即使上一次运行尚未完成，也会按计划时间启动——循环体必须具备幂等性
• ❌ 不会自主调整节奏——任务耗时变化很大时会安排过多运行

模式 B — 动态调整节奏（自主安排）

适用场景：任务应根据状态而非时钟做出响应。适用于监控直到满足条件的模式，或等待外部事件的任务。

工具：ScheduleWakeup — 当前运行会安排自己的下一次唤醒。

ScheduleWakeup({
  delaySeconds: 270,               // stay in cache window (< 5min)
  reason: "checking build status; sleeping under 5min to stay cache-warm",
  prompt: "<same task, re-entered>"
})

关键延迟规则（来自 ScheduleWakeup 文档——已融入此向导）：

延迟范围	用途	缓存影响
60s–270s	正在积极工作——轮询构建状态、等待即将变化的状态	保留在 5 分钟提示词缓存中——速度快、成本低
300s ❌	不要使用	两头不讨好——付出缓存未命中的代价，却没有摊薄成本
300s–3600s	等待需要几分钟才会变化的事项	付出缓存未命中的代价，但等待时间足够长，值得这样做
1200s–1800s（20–30 分钟）	没有明确信号时的空闲轮询	自主循环的默认值

切勿将延迟设为 300s——要么降到 270s（缓存保持热状态），要么采用 1200s 以上（缓存未命中换取更长等待时间）。

权衡：

• ✅ 自适应——空闲时等待更久，活跃时等待更短
• ✅ 调优得当时可优化缓存使用
• ❌ 循环体需要知道何时安排下一次唤醒（需要额外逻辑）
• ❌ 更难推断它何时会运行

模式 C — 单次循环（直到满足条件）

适用场景：任务持续运行，直到满足某个条件后停止。之后不再重复运行。

工具：/loop（内置），在提示词中设置退出条件。

/loop
Check if the deploy is healthy. If yes → stop. If no → wait 5 min and check again.
Max 10 iterations. If still failing after 10, alert and stop.

权衡：

• ✅ 最适合“检查直到满足条件”的简单任务
• ✅ 有界——最终总会终止
• ❌ 不适用于无限期重复运行——这种情况应使用模式 A 或 B

第 2 步 — 设计具备幂等性的循环体

幂等 = 运行两次循环，产生的结果与运行一次相同。对 cron 和动态模式而言，这是不可妥协的要求，因为上一轮可能仍在运行或尚未完成时，它们就会再次触发。

幂等模式：

• 使用“已完成”标记：例如，提交状态文件 <vault>/.loopify/<name>-last-run.txt，记录上次成功运行的时间戳。循环体在执行工作前检查该时间戳。
• 使用去重键：如果循环会写入数据库或文件，请使用内容哈希或时间戳作为键，这样重跑时就不会产生任何操作。
• 使用事务：循环体中的数据库写入应当是原子的——要么全部提交，要么全部回滚。
• 修改前先查询：应用更改前检查当前状态。如果已经应用，就跳过。

向用户展示循环体草稿，并突出显示幂等性检查。如果还没有检查，就添加一个。

第 3 步 — 退出条件

每个循环都需要退出条件。可选方案：

退出条件	适用场景
最大迭代次数（例如，运行 100 次后停止）	Cron 循环——防止失控
基于状态（例如，指标 X 低于 Y 时停止）	监控循环
基于时间（例如，运行 24 小时后停止）	有时限的监控
基于错误（例如，连续失败 3 次后停止）	所有循环——及时发现性能退化

如果循环确实需要无限期运行（例如，没有结束日期的每周 cron），仍需通过 CronDelete 添加手动退出方式。在 SKILL/循环说明中记录下来，让用户知道如何停止。

第 4 步 — 设置计划

根据第 1 步确定的模式：

Cron（模式 A）：

CronCreate({
  schedule: "<expression>",
  timezone: "<tz>",
  prompt: "<loop body>",
})

报告返回的 cron_id，以便用户之后可以使用 CronDelete。

动态（模式 B）： 包装循环体提示词，使其以 ScheduleWakeup 调用结束：

<do the work>
Then: ScheduleWakeup({delaySeconds: <tuned per Step 1>, prompt: "<same body>", reason: "<why this cadence>"})

单次（模式 C）： 直接运行 /loop <prompt with exit condition>。

在 Claude Code 以外的宿主环境中

CronCreate、ScheduleWakeup 和 /loop 是 Claude Code 的功能。此技能中的其他内容（模式选择、幂等性、退出条件、验证）适用于任何 Agent。在其他宿主环境中，调度器位于 Agent 之外，并调用一次非交互式 Agent 运行：

调度器	适用场景
宿主自身的计划任务（如果支持）	首选。查看宿主文档
系统 cron / launchd / systemd timer	机器始终开机；循环需要访问本地文件
GitHub Actions schedule:	循环适用于仓库（vault 编译、上游检查）；即使笔记本电脑关闭也能运行

作业会运行一个无头 Agent 命令，并将循环体作为提示词，例如 claude -p "<body>"、codex exec "<body>" 或 cursor-agent -p "<body>"。使用 Agent 的 CLI 提供的任意非交互模式。

• 动态节奏（模式 B）没有直接对应的实现方式。请使用固定计划，并让循环体在无事可做时提前退出。
• 单次（模式 C）可改为用 shell while 循环包装无头命令，并在循环条件中加入退出检查。
• 无头运行无法请求批准，因此请为作业授予能够正常工作的最小权限，并让它将输出写入文件或发送通知，而不是等待提示。

第 5 步 — 验证首次运行

等待首次迭代完成（或使用相同提示词通过 /loop 手动触发一次试运行）。确认：

• 输出已写入预期位置
• 幂等性检查正常（运行两次——第二次应无任何操作）
• 触发时退出条件能够正确生效
• 如果已配置，日志/通知会正常显示

第 6 步 — 报告与后续事项

报告：

• 选择的模式（A/B/C）及原因
• 已注册的 Cron ID 或唤醒模式
• 已设置的退出条件
• 已配置的幂等机制
• 如何停止循环（CronDelete <cron_id>，或动态模式下“只需不再调用唤醒”）

提供以下选项：

• “要通过 skillify from-chat 将此循环配置保存为技能吗？”
• “要趁现在再注册一个 weekly-review 或 daily-startup 循环吗？”
• “循环运行时要将输出写入 second-brain 吗？”

常见循环配方

常见循环类型的模板（使用时填写）：

• references/daily-brief.md — 晨间例行循环（日历 + 优先事项 + 夜间情况）
• references/weekly-review.md — 周五投资组合动态
• references/upstream-check.md — 定期检查适配技能的上游是否有更改
• references/vault-compile.md — 定期将 raw/ 编译到 wiki/
• references/metric-monitor.md — 轮询指标，直到超过阈值，然后发出提醒

配合使用

• skillify — -ify 三件套中的同类工具。使用 skillify 编写新的 SKILL.md；如果目标是安排定时任务，而不是创建技能，则使用 loopify。
• toolify — 同类工具。使用 toolify 添加集成；如果目标是在已集成的工具之上按计划运行任务，则使用 loopify。
• second-brain — 许多循环会写入知识库（raw/ 或 outputs/）。适用知识库自动提交模式。
• pm — daily-brief 和 weekly-review 循环通常会在生成输出前从 pm 读取信息。

质量注意事项

• 绝不要为 delaySeconds 选择 300s。 两头不讨好。要么降至 270，要么选择 1200+。
• 每个循环都需要退出机制。 即使是无限循环，也需要记录手动停止的方法。
• cron + dynamic 必须保证幂等性。 假设上一次迭代仍在运行时，循环会再次触发。
• 优先采用动态调度，而不是过于频繁的 cron。 每 15 分钟运行一次 cron，如果任务尚未就绪，只会浪费令牌；动态调度则会在空闲时降低频率。
• 记录 cron_id。 否则循环会变成孤立任务，难以停止。
• 简要记录每次迭代——哪怕只有一行（“2026-06-30 08:00 daily-brief：已运行，3 项”），也能轻松调试偏差。
• 涉及外部 API 的循环需要遵守速率限制。 如果供应商的限制是每天 100 次，就不要安排每天 500 次。
• 不确定时，有限优于无限。 如果不确定该运行一周还是一个月，就先从一周开始；看到效果后再延长。