loopify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/loopify — Set up an agent loop

/loopify — 设置Agent循环

Wizard for going from "this task should run periodically" to a working loop with the right pacing, idempotency, and bail-out. Reference:

ScheduleWakeup

(dynamic pacing),

CronCreate

(fixed schedule), and the built-in

/loop

(dynamic self-paced re-entry).

本向导可帮你从“这项任务应定期运行”的需求，转化为具备合适调优策略、幂等性和退出条件的可运行循环。参考工具：

ScheduleWakeup

（动态调优）、

CronCreate

（固定调度）和内置的

/loop

（动态自调优重入）。

Step 0 — Confirm what you're looping

步骤0 — 确认循环执行的任务

Ask if not obvious from context: "What task should this loop do each iteration?"

Then get the essentials:

Question	Why it matters
How often?	Determines cron vs dynamic vs one-shot
When to stop?	Bail-out condition — loops must have one
What's the loop body doing?	Determines idempotency requirements
Where does output go?	File / notification / commit / nothing
What's the failure mode if it runs twice?	Idempotency validation

若上下文不明确，询问用户：“每次循环应执行什么任务？”

然后获取关键信息：

问题	重要性
执行频率？	决定使用Cron、动态调优还是一次性循环
何时停止？	退出条件——所有循环必须设置
循环体执行什么操作？	决定幂等性要求
输出去向？	文件/通知/提交/无输出
重复执行两次会有什么失败风险？	幂等性验证依据

Step 1 — Pick the pattern

步骤1 — 选择模式

Three primary patterns. Route by the answer to "how often":

三种主要模式，根据“执行频率”的答案选择：

Pattern A — Cron (fixed schedule)

模式A — Cron（固定调度）

Use when: task runs at predictable intervals — daily at 8am, weekly on Fridays, hourly on the hour.

Tool:

CronCreate

— schedules a recurring task with a cron expression.

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

Common cron patterns:

```
0 8 * * *
```
— daily at 8am
```
0 9 * * 1
```
— Mondays at 9am
```
0 9 * * 5
```
— Fridays at 9am
```
0 */2 * * *
```
— every 2 hours
```
*/15 * * * *
```
— every 15 minutes

Trade-offs:

✅ Predictable, human-readable, easy to reason about
✅ Best for time-of-day-dependent tasks (morning brief, EOD summary)
❌ Runs at the scheduled time even if the last run isn't done — need idempotent body
❌ No self-pacing — over-schedules if the task duration varies wildly

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

工具：

CronCreate

——使用Cron表达式调度重复任务。

CronCreate({
  schedule: "0 8 * * *",           // 本地时间每天早8点
  prompt: "<循环体提示词>",
  timezone: "America/Los_Angeles"
})

常见Cron模式：

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

权衡：

✅ 可预测、易读、易于理解
✅ 最适合依赖特定时段的任务（晨间简报、工作日结束总结）
❌ 即使上一次运行未完成，仍会按调度时间执行——需要幂等性循环体
❌ 无自调优能力——若任务时长差异极大，会过度调度

Pattern B — Dynamic pacing (self-scheduled)

模式B — 动态调优（自调度）

Use when: task should react to state, not the clock. Monitor-until-condition-met patterns. Waiting on an external event.

Tool:

ScheduleWakeup

— the current run schedules its own next wake-up.

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

Critical delay rules (from

ScheduleWakeup

docs — internalized in the wizard):

Delay range	Use for	Cache impact
60s–270s	Active work — polling build, waiting for state that's about to change	Stays in 5-min prompt cache — fast + cheap
300s ❌	DON'T USE THIS	Worst of both worlds — pay cache miss without amortizing
300s–3600s	Waiting on something that takes minutes to change	Pay cache miss but justified
1200s–1800s (20–30 min)	Idle ticks with no specific signal	Default for autonomous loops

Never pick 300s literally — either drop to 270 (cache stays warm) or commit to 1200+ (cache miss buys longer wait).

Trade-offs:

✅ Adaptive — sleeps longer when idle, shorter when active
✅ Cache-optimal when tuned right
❌ Requires the loop body to know when to schedule next (extra logic)
❌ Harder to reason about when it'll run

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

工具：

ScheduleWakeup

——当前运行实例调度自身的下一次唤醒。

ScheduleWakeup({
  delaySeconds: 270,               // 保持在缓存窗口内（<5分钟）
  reason: "检查构建状态；休眠时间小于5分钟以保持缓存温暖",
  prompt: "<相同任务，重新进入>"
})

关键延迟规则（来自

ScheduleWakeup

文档——已内置于向导中）：

延迟范围	适用场景	缓存影响
60秒–270秒	活跃工作——轮询构建状态、等待即将变化的状态	保持在5分钟提示缓存内——快速且低成本
300秒 ❌	禁止使用	最糟情况——既会缓存失效，又无法摊销成本
300秒–3600秒	等待需要数分钟才会变化的事物	缓存失效但合理
1200秒–1800秒（20–30分钟）	无特定信号的空闲轮询	自主循环的默认值

绝对不要选择300秒——要么降至270秒（保持缓存温暖），要么设置为1200秒以上（缓存失效换取更长等待时间）。

权衡：

✅ 自适应——空闲时休眠更长，活跃时休眠更短
✅ 调优得当可实现缓存最优
❌ 需要循环体知道何时调度下一次运行（额外逻辑）
❌ 难以预测运行时间

Pattern C — One-shot loop (until-condition)

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

Use when: task runs until a condition is met, then stops. No recurrence after that.

Tool:

/loop

(built-in) with an exit condition in the prompt itself.

/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.

Trade-offs:

✅ Simplest for check-until-condition
✅ Bounded — always eventually terminates
❌ Not for indefinite recurrence — that's Pattern A or B

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

工具：内置的

/loop

，在提示词中包含退出条件。

/loop
检查部署是否健康。如果是→停止。如果否→等待5分钟后再次检查。
最多10次迭代。如果10次后仍失败，发送警报并停止。

权衡：

✅ 检查直到条件满足的最简单方式
✅ 有界——最终总会终止
❌ 不适合无限重复——那是模式A或B的用途

Step 2 — Design the loop body for idempotency

步骤2 — 设计幂等性循环体

Idempotent = running the loop twice produces the same result as running it once. Non-negotiable for cron and dynamic patterns because they'll fire while the previous iteration is still running or partially complete.

Idempotency patterns:

Use "already done" markers: e.g., commit a state file
```
<vault>/.loopify/<name>-last-run.txt
```
with the timestamp of last successful run. Loop body checks the timestamp before doing work.
Use dedupe keys: if the loop writes to a DB or file, key by content-hash or timestamp so re-runs are no-ops.
Use transactions: DB writes in the loop body should be atomic — either all commit or all roll back.
Query before mutate: check current state before applying the change. If already applied, skip.

Show the user the loop body draft, highlighting the idempotency check. If none exists, add one.

幂等性 = 运行两次循环的结果与运行一次相同。对于Cron和动态模式，这是必不可少的，因为它们可能在上一次迭代仍在运行或部分完成时触发。

幂等性模式：

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

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

Step 3 — Bail-out condition

步骤3 — 设置退出条件

Every loop needs one. Options:

Bail-out	When to use
Max iterations (e.g., stop after 100 runs)	Cron loops — prevents runaway
State-based (e.g., stop when metric X drops below Y)	Monitoring loops
Time-based (e.g., stop after 24 hours)	Bounded monitoring
Error-based (e.g., stop on 3 consecutive failures)	All loops — catches degradation

If the loop is truly indefinite (e.g., a weekly cron with no end), still add a manual bail-out via

CronDelete

. Document it in the SKILL/loop notes so the user knows how to stop it.

每个循环都需要退出条件。选项：

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

如果循环确实是无限的（例如，无终止时间的每周Cron），仍需通过

CronDelete

添加手动退出条件。在SKILL/循环说明中记录，以便用户知道如何停止它。

Step 4 — Set the schedule

步骤4 — 设置调度

Based on the pattern from Step 1:

Cron (Pattern A):

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

Report the

cron_id

returned so the user can

CronDelete

later.

Dynamic (Pattern B): Wrap the loop body prompt so it ends with a

ScheduleWakeup

call:

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

One-shot (Pattern C): Just run

/loop <prompt with exit condition>

根据步骤1选择的模式：

Cron（模式A）：

CronCreate({
  schedule: "<表达式>",
  timezone: "<时区>",
  prompt: "<循环体>",
})

返回生成的

cron_id

，以便用户后续使用

CronDelete

停止任务。

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

ScheduleWakeup

调用结尾：

<执行工作>
然后：ScheduleWakeup({delaySeconds: <根据步骤1调优的值>, prompt: "<相同循环体>", reason: "<此节奏的原因>"})

一次性循环（模式C）： 直接运行

/loop <包含退出条件的提示词>

。

Step 5 — Verify the first run

步骤5 — 验证首次运行

Wait for the first iteration (or trigger it manually via

/loop

with the same prompt for a dry-run). Confirm:

Output landed where expected
Idempotency check works (run twice — second should be a no-op)
Bail-out condition would fire correctly if triggered
Log/notification appears if configured

等待首次迭代（或通过

/loop

手动触发相同提示词进行试运行）。确认：

输出已到达预期位置
幂等性检查有效（运行两次——第二次应为空操作）
触发时退出条件会正确生效
若配置了日志/通知，已正常显示

Step 6 — Report + follow-ups

步骤6 — 报告与后续跟进

Report:

Pattern picked (A/B/C) + why
Cron ID or wakeup pattern registered
Bail-out condition set
Idempotency mechanism in place
How to stop the loop (
```
CronDelete <cron_id>
```
or "just don't call the wakeup" for dynamic)

Offer:

"Save this loop configuration as a skill via
skillify from-chat
?"
"Want to also register a
weekly-review
or
daily-startup
loop while we're here?"
"Should the loop write to
second-brain
outputs when it runs?"

报告内容：

选择的模式（A/B/C）及原因
注册的Cron ID或唤醒模式
设置的退出条件
采用的幂等性机制
如何停止循环（
```
CronDelete <cron_id>
```
，或对于动态模式“不调用唤醒即可停止”）

提供后续选项：

“是否通过
skillify from-chat
将此循环配置保存为技能？”
“是否要同时注册
weekly-review
或
daily-startup
循环？”
“循环运行时是否应写入
second-brain
输出？”

Common loop recipes

常见循环模板

Templates for frequent loop types (fill in as they're used):

```
references/daily-brief.md
```
— morning routine loop (calendar + priorities + overnight)
```
references/weekly-review.md
```
— Friday portfolio pulse
```
references/upstream-check.md
```
— periodic check for changes to an adapted skill's upstream
```
references/vault-compile.md
```
— periodic raw/ → wiki/ compilation
```
references/metric-monitor.md
```
— poll a metric until it crosses a threshold, then alert

针对频繁使用的循环类型的模板（使用时填充内容）：

```
references/daily-brief.md
```
— 晨间流程循环（日历+优先级+隔夜事项）
```
references/weekly-review.md
```
— 周五工作回顾推送
```
references/upstream-check.md
```
— 定期检查适配技能的上游变更
```
references/vault-compile.md
```
— 定期将raw/目录内容编译到wiki/目录
```
references/metric-monitor.md
```
— 轮询指标直到超过阈值，然后发送警报

Composes with

可组合工具

skillify
— sibling in
```
-ify
```
trifecta. Use
```
skillify
```
to author a new SKILL.md — use
```
loopify
```
when the goal is a scheduled task, not a skill.
toolify
— sibling. Use
```
toolify
```
for adding an integration — use
```
loopify
```
when the goal is running something on top of an already-integrated tool on a schedule.
second-brain
— many loops write to the vault (raw/ or outputs/). The vault auto-commit pattern applies.
pm
— daily-brief and weekly-review loops often read from pm before generating output.

skillify
— "-ify"三件套的姊妹工具。使用
```
skillify
```
创作新的SKILL.md——当目标是调度任务而非创作技能时，使用
```
loopify
```
。
toolify
— 姊妹工具。使用
```
toolify
```
添加集成——当目标是在已集成工具之上按调度运行任务时，使用
```
loopify
```
。
second-brain
— 许多循环会写入知识库（raw/或outputs/目录）。知识库自动提交模式适用。
pm
— 每日简报和每周回顾循环通常会先读取pm的内容再生成输出。

Notes on quality

质量注意事项

Never pick 300s for
delaySeconds
. Worst of both worlds. Drop to 270 or commit to 1200+.
Every loop needs a bail-out. Even indefinite ones need a documented manual stop.
Idempotency is non-negotiable for cron + dynamic. Assume the loop will fire twice while a previous iteration is running.
Prefer dynamic pacing over over-frequent cron. Cron every 15 min wastes tokens if the work isn't ready; dynamic pacing scales down when idle.
Document the cron_id. Otherwise the loop is orphaned and hard to stop.
Log every iteration briefly — even a single line ("2026-06-30 08:00 daily-brief: ran, 3 items") makes debugging drift trivial.
Loops that touch external APIs need rate-limit respect. If the vendor has a 100/day limit, don't schedule 500/day.
Bounded > unbounded when uncertain. If unsure whether to run for a week or a month, start with a week — extend after seeing it work.

绝对不要为
delaySeconds
选择300秒。最糟情况。降至270秒或设置为1200秒以上。
每个循环都需要退出条件。即使是无限循环也需要记录手动停止方式。
对于Cron和动态模式，幂等性必不可少。假设循环会在上一次迭代运行时触发两次。
优先选择动态调优而非过于频繁的Cron。每15分钟一次的Cron如果工作未准备好会浪费令牌；动态调优会在空闲时自动缩减。
记录cron_id。否则循环会成为孤儿，难以停止。
简要记录每次迭代——即使是一行（“2026-06-30 08:00 daily-brief: 已运行，3项内容”）也能让调试变得简单。
涉及外部API的循环需要遵守速率限制。如果供应商限制每天100次，不要调度每天500次。
不确定时优先选择有界循环。如果不确定是运行一周还是一个月，先设置一周——验证有效后再延长。