本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。 英文原文

循环模式与计划任务

状态：生效 范围：当前状态 最近审阅：2026-08-27 负责人：ax-code 运行时

AX Code 有三种可组合的自动化原语：

/loop — 重复提示

/loop <interval> <prompt>   start (interval like 30s, 5m, 1h)
/loop status                show runs, busy-skips, and the prompt
/loop stop                  stop the loop

示例：

/loop 5m check CI for new failures and fix any you find
/loop 30m drain the review queue

规则：

• 间隔界限：30 秒到 24 小时。每个会话一个循环 — 启动 新的循环会替换旧的。
• 会话繁忙时触发的节拍会被 跳过并计数， 从不排队 — 循环不能把回合堆积起来。
• 每一次节拍都是普通的提示回合：权限、提问、自主 上限和完成门禁全都适用。自主关闭时，节拍只会 停在第一个权限提示处。
• 每个循环硬性上限 500 次运行，然后循环会自己停止并给出 通知。
• 循环只存在于后端进程中：它们不能在重启后保留。 若要持久计划，请使用下方的计划任务。

把 /goal 与 /loop 搭配

/goal 拥有目标（“全部测试通过，没有未关闭的审阅发现”）； /loop 提供持续检查的心跳。先创建目标会 运行专门的计划写入器，把可审阅的契约存放在 .ax-code/goals/ 下（当项目不是 git 工作树时，则放在 AX 数据目录）。如果规划失败，目标保持暂停 — /goal resume 会重试 它。衡量此目标差异的 Git 范围检查使用计划时的 HEAD （{BASELINE}），而不是 origin/main，除非目标点名了该远程。 目标完成仍然受验证门禁约束：代理不能在编辑之后、没有通过验证运行的情况下把目标 标记为完成，并且当计划 存在时，它还必须为每一条验收标准提供证据。

/goal keep main green: fix any CI failure the loop finds
/loop 10m check CI status and act on failures

目标保证是选择加入的

/goal <objective> 会立即开始：它不附加冻结的验收契约， 因此完成与否由代理保持的工作计划（待办事项）加上 最后一次变更之后通过的验证来判断。/goal view（以及目标对话框的 “查看目标详情”）会明确这样说明 — “没有保证契约” — 因此这个状态 永远不是你必须去推断的东西。

/goal --assure <objective> 会先运行计划写入器，从而冻结验收 标准、源引用和可执行检查；完成随后还要求每一项必需检查都有 当前成功的回执（verify_project 及其 goalCheck 标识）。当目标的“完成”必须可证明而不是 被描述时，使用它。

--assure 可以与预算标志按任一顺序组合 （/goal --assure --budget 500000 <objective>）。当被替换的目标拥有有效契约时，/goal replace <objective> 会保留 保证，因此替换绝不能悄然削弱一个已经有保证的目标。

目标预算与上限

活动目标会提高每次运行的自动延续上限（session.max_continuations） — 运行会继续，直到目标完成、被阻碍、被暂停，或 受到预算限制。取而代之的界限是：

• token 预算（/goal --budget N …）：耗尽时，代理得到一轮 收尾回合，然后目标变为 budget_limited。
• 时间预算（/goal --time-budget 30m …）：以秒、 分钟（m）或小时（h）计的墙钟限制，可以与 token 预算按任一 顺序组合。它约束 token 预算看不见的已耗时间 — 远程训练 作业、长时间工具调用、提供商停顿。触发时适用同样的收尾回合和 budget_limited 转换。
• 累计步骤上限：活动目标运行共享 Super-Long 的后备上限， 共 max_steps × 40 个总步骤（默认 20,000），而不是普通的 自主上限 max_steps × (max_continuations + 1)。用 session.max_total_steps 覆盖。
• 死循环检测、爆炸半径上限，以及仅工具回合断路器在整个过程中仍然 适用。

目标 CLI（无头）

同样的目标控制在 TUI 之外、ax-code goal 下也可用：

• ax-code goal status [--json] — 显示当前目标（-s/--session 用来 选择会话；默认是该项目唯一可恢复的目标，当选择 会有歧义时报错）。
• ax-code goal pause / ax-code goal clear — 暂停或清除它。
• ax-code goal resume — 恢复目标，并无头驱动它，直到它 稳定下来。没有 --attach 时，它在进程内引导项目；带有 --attach http://localhost:4111 时，它改为驱动正在运行的服务器。退出 码遵循无头目标契约：0 完成，3 被阻碍，4 受预算限制，6 已暂停/非终态，1 会话错误，124 空闲 超时（--idle-timeout-ms，默认 10 分钟）。事件以 JSONL 流式写到 stdout （--event-log PATH 也会记录它们），最后一行 Goal <status>: <objective> 写到 stderr。

当目标运行接近步骤上限时，代理会收到一次 收敛警告，要求它验证并完成目标，或留下一份 干净的交接。如果无论如何达到了上限，目标会被 暂停 — 而不是 失败 — 并可以用 /goal resume 再次接上（如果需要更多余量，请先提高 session.max_total_steps）。

计划任务 — 持久、可用对话设置

直接询问代理；它使用 schedule_task、list_scheduled_tasks 和 manage_scheduled_task 工具：

• “14:30 提醒我检查部署。”
• “每个工作日上午 9 点，总结新的 CI 失败。”
• “列出我的计划任务。” / “暂停 CI 总结任务。”

代理创建和代理管理的计划变更会请求 schedule 权限。只读运行不能更改或触发计划。对于无人值守的 无头创建，使用显式的 ax-code schedule 命令，或为代理配置一项 显式的 schedule 权限授予；宽泛的通配符授予 并不能授权计划变更。

同样的任务也可以从 shell 管理，而不必打开 TUI：

ax-code schedule list                 # status, next run, schedule, id, title
ax-code schedule show <id>            # details plus the five most recent runs
ax-code schedule runs <id>            # run history: fired, failed, skipped and why
ax-code schedule pause|resume <id>
ax-code schedule delete <id>
ax-code schedule run <id>             # trigger now; requires a live runtime

pause/resume/delete 在项目的托管运行时正在 运行时会经过它（立即生效，TUI 实时更新），否则直接写入项目 数据库。run 需要活动的后端 — 用 ax-code runtime start 启动一个 — 因为一次性 CLI 进程不得认领它 无法完成的工作。所有读取子命令都接受 --json。

计划支持一次性运行、每日/每周时间，以及 5 字段 cron 表达式，每一项都可以带可选的 IANA 时区。任务持久化在 项目数据库中，并在该项目的 AX Code 后端 正在运行时触发（60 秒调度器扫描，原子认领 — 即使 打开了多个后端，任务也只触发一次）。计划推进和持久队列插入共享 同一个数据库事务，因此崩溃不能在 没有留下可恢复工作的情况下推进一次发生。 ax-code run 和 ax-code stats 这类一次性命令不会认领到期 任务。用 ax-code runtime start 启动持久后端来分发 它们。

错过的发生默认使用 catchUpPolicy: "run_once"：停机之后， AX Code 会把任何积压合并为一次运行。当过期工作应当 被推进但不运行时，使用 "skip"。任务也可以把 maxRunDurationMs 设为从一 秒到 72 小时；超时的运行会被取消并记录为失败。

若要跨进程和主机重启运行，请把后端放在 监督进程下。systemd、launchd 和 PM2 示例以及确切的恢复语义，见 长时间运行的操作。

长时间无人值守运行

对于多小时的自主会话，Super-Long 模式增加运行截止时间（最多 72 小时）、请求节奏和压缩调优。对于所声明能力支持长代理工作的模型，它会自动启用 （阿里云路由上的 Qwen 3.7+ Max/Plus 以及 z.ai 路由上的 GLM 5.x 这类 1M 上下文推理 模型），也可以按会话、按项目强制，或通过 AX_CODE_SUPER_LONG。运行参与会被记录（super-long run engaged）， 并且提供商节奏只在运行开始后的宽限窗口之后才开始 （默认 2 小时，super_long.pacing_grace_minutes），以便代理运行富有成效的 早期阶段保持完整的工具调用吞吐； 马拉松式的尾部按模型所声明的速率限制档位来调节节奏。