Skip to main content
参考

Loop 命令参考

/loop 循环执行的参数格式、间隔单位、预算上限、默认值与取消方式

/loop 让 Qoder CLI 重复执行一段提示或斜杠命令：可以按固定间隔（底层通过定时任务系统实现），也可以由 Qoder 自行掌握节奏。本页说明其参数格式、间隔换算、预算上限与取消方式。关于循环执行的使用指南，见 重复执行任务。

用法

/loop [间隔] [标记] <提示>
  • [间隔]（可选）：执行间隔。给出时进入固定间隔模式；省略时进入动态节奏模式。
  • [标记]（可选）：持久化与预算上限，见下表。
  • <提示>（必填）：要重复执行的提示文本或斜杠命令。斜杠命令原样透传。

两种模式

模式选中条件机制
固定间隔输入中含间隔间隔换算为 cron 表达式并注册为定时任务。
动态节奏输入中不含间隔每次运行后由 Qoder 自行安排下一次唤醒，延迟被限制在 [60, 3600] 秒。不再安排即结束循环。
特殊情况：
  • /loop 不带任何参数：若存在 .qoder/loop.md，Qoder 会以动态节奏模式循环执行该任务清单；否则显示用法提示。
  • /loop 5m（有间隔无提示）：显示用法提示。
  • 只有标记、没有提示（如 /loop --max-turns 3）：Qoder 每次迭代做一次通用的项目健康检查，按动态节奏模式运行。

标记

标记取值说明
--durable—任务落盘，重启后仍然存在，且不自动过期。
--durable <N>d天数任务落盘，并在 N 天后过期。
--permanent、-p—等价于不带过期时间的 --durable。
--max-turns <N>整数跑满 N 次后停止循环。
--max-credits <N>数字累计消耗 N 积分后停止循环。允许小数。
标记的解析规则：
  • 上限同时支持空格写法（--max-turns 6）与等号写法（--max-turns=6）。
  • 标记可以出现在输入的任意位置，并且会在解析间隔之前被剔除，所以 /loop --max-turns 5 10m check the deploy 读到的间隔仍是 10m，而不是 5。
  • 同一个标记重复出现时取第一个值，且所有副本都会从提示中移除。
  • --durable 与 --permanent 只作用于固定间隔循环。动态节奏的循环始终只属于当前会话。

间隔单位

间隔由数字加单位后缀组成：
后缀单位说明
s秒向上取整到最近的分钟（最小粒度 1 分钟）。
m分钟每 N 分钟。
h小时每 N 小时。
d天每 N 天（本地时间午夜触发）。
最小粒度为 1 分钟。以秒为单位的间隔会被向上取整为 ceil(N/60) 分钟，取整时会提示你。

解析规则

剔除标记后，/loop 按以下优先级解析剩余输入：
  1. 前导 token：若第一个词匹配 ^\d+[smhd]$（如 5m、2h），则作为间隔，其余为提示 → 固定间隔模式。
  2. 尾随 every 子句：否则若输入以 every <N><单位> 或 every <N> <单位词> 结尾（如 every 20m、every 5 minutes），提取为间隔并从提示中去除 → 固定间隔模式。仅当 every 后接时间表达式时才匹配——check every PR 不含间隔。
  3. 其余情况：不含间隔，整段输入作为提示 → 动态节奏模式。

示例

/loop 5m /babysit-prs          # 每 5 分钟执行 /babysit-prs
/loop 30m check the deploy     # 每 30 分钟检查部署
/loop 1h /standup 1            # 每小时执行 /standup 1
/loop run tests every 20m      # 每 20 分钟运行测试
/loop monitor CI pipeline      # 动态节奏：由 Qoder 决定时机
/loop --durable 30d 1h /standup 1        # 落盘，30 天后过期
/loop --max-turns 6 10m check the deploy # 跑满 6 次后停止

间隔到 cron 的换算

间隔模式cron 表达式说明
Nm（N ≤ 59）*/N * * * *每 N 分钟
Nm（N ≥ 60）0 */H * * *换算为小时（H = N/60，需整除 24）
Nh（N ≤ 23）0 */N * * *每 N 小时
Nd0 0 */N * *每 N 天午夜
Ns视为 ceil(N/60)mcron 最小粒度为 1 分钟
若间隔不能整除其单位（如 7m 会产生不均匀间隔、90m 无法用 cron 表达），会选择最接近的整齐间隔并在创建任务前告知取整结果。

预算上限

上限是"到达即停"，不是"允许超过"：用量一旦达到上限，循环即停止。两个上限都设时先到者停止循环；若同时到达，提示报的是轮次上限。
上限计数依据判定时机精确度
--max-turns任务整个生命周期内的运行次数每次运行之前精确——--max-turns 2 恰好触发两次。
--max-credits累计消耗的积分一轮记账完成之后最后一轮可能略微超过上限；进行中的一轮绝不会被掐断。
其他规则：
  • 只接受正数。调度工具对 0 或负数直接报错拒绝，而不是静默丢弃；已有任务文件里的非正数上限会在读取时被丢弃，该任务视为无上限。
  • 轮次是终身计数，重启 Qoder CLI 不会清零。
  • 触顶与过期是两件事。触顶后任务被移除且无法恢复，需要继续时新起一个循环。
  • 触顶时你和 Qoder 都会收到通知——你看到 Scheduled task <id> stopped: it used 2 of 2 turns.（动态节奏模式下为 Loop stopped: it used 3 of 3 turns.），Qoder 则被要求如实汇报停止，而不是重建任务。

落盘字段

对于落盘任务，上限与用量与其他字段一起保存在 .qoder/scheduled_tasks.json 中：
字段说明
fireCount终身运行次数，与 maxTurns 对照。
creditsUsed累计消耗的积分。缺失表示从未计量，与 0 不同义。
maxTurns轮次上限。缺失表示无上限。
maxCredits积分上限。缺失表示无上限。
在这些字段出现之前写下的任务文件即视为无上限，照常运行。

动态节奏模式的上限

动态节奏模式下，上限与用量在循环期间保存在内存中：
  • 粘性：在启动循环的那次 /loop 上给出标记，后续每次唤醒都继续生效；后续未重复该标记的唤醒不会清除上限。
  • 停止即清零：停止循环会同时清除上限与已用量，下一个 /loop 从零开始，不继承上一个循环的消耗。
  • 触顶会取消待执行的唤醒，循环不会再醒来。

工具参数

Qoder 自行安排任务时同样可以设这两个上限，因此你也可以用自然语言表达（"检查五次就停"）：
工具参数
定时任务创建maxTurns、maxCredits——回执中以 Stops after N turns or M credits. 的形式说明。
动态节奏唤醒maxTurns、maxCredits——对整个循环粘性生效。

面板控件

在 /crontab 面板中：
  • USAGE 列在设了上限时显示 3/10 turns · 12.5/50 credits，未设上限时显示 2 turns · 8.25 credits；消耗从未计量时，已花费的部分显示为破折号（—/50 credits）。从未运行且无上限的任务该列为空。
  • 任务详情页显示 Turns 3 / 10 (stops at the limit) 与 Credits 12.5 / 50 (stops at the limit)。
  • 按 t 编辑轮次上限，按 b 编辑积分上限。输入空值清除上限；非正数不被接受，Esc 取消。

取消与失效

  • 默认创建的是会话级周期任务：进程退出即停止。
  • 周期任务在创建后 7 天自动过期，除非用 --durable（不过期）或 --durable <N>d（自定义过期）创建。
  • 可在过期前手动删除对应的定时任务（用自然语言请求 Agent 删除并提供任务 ID，或在 /crontab 面板中删除）。
  • 动态节奏模式下，让 Qoder 停止即结束循环并取消待执行的唤醒。
  • 创建循环任务后会立即执行一次当前提示，不等待第一次 cron 触发。

下一步

开始使用
核心概念
使用 Qoder CLI
扩展 Qoder CLI
远程与集成
配置与安全
参考
故障排查