---
title: "loop 循环任务与 Goal 模式"
---

`/loop` 是 SolonCode 的循环任务与目标驱动引擎，支持两种运行模式：**定时心跳（HEARTBEAT）** 和 **目标驱动（GOAL）**。它是 SolonCode 实现自主持续运行的核心能力。


### 1、两种任务类型

| 类型 | 命令 | 执行方式 | 适用场景 |
|------|------|---------|---------|
| **HEARTBEAT** | `/loop 5m check CI` | 按固定间隔或 cron 周期触发 | 定时检查、轮询、监控 |
| **GOAL** | `/loop goal fix auth` | 事件驱动持续推进，直至目标达成 | 代码重构、文档编写、Bug 修复等需要多轮自主完成的任务 |


### 2、命令参考

#### 2.1 管理命令

| 子命令 | 说明 |
|--------|------|
| `/loop` | 列出当前会话所有活跃任务 |
| `/loop ls` | 同上 |
| `/loop stop <id>` | 停止指定任务 |
| `/loop stop-all` | 停止当前会话所有任务 |
| `/loop pause <id>` | 暂停一个 Goal 任务（仅 GOAL 类型） |
| `/loop resume <id>` | 恢复一个暂停/阻塞的 Goal 任务 |

#### 2.2 创建心跳任务

```
/loop 5m check if deployment finished     ← 每 5 分钟执行一次
/loop 30s check CI status                 ← 每 30 秒（自动向上取整为 1 分钟）
/loop check CI status                     ← 默认 5 分钟
/loop cron:"0 */5 * * * ?" check status   ← 使用 cron 表达式
/loop 5m --now check status               ← 立即执行首次（--now 标志）
```

#### 2.3 创建 Goal 任务

```
/loop goal fix auth module                ← 简化 Goal 模式，立即执行
/loop goal write a readme.md              ← 编写文档
/loop goal --max-tokens:50000 refactor    ← 限制 Token 预算
/loop goal --max-duration:30 fix tests    ← 限制时间预算（单位：分钟）
```

> **注意**：每个会话同一时间只能有一个活跃的 Goal。需先 `/loop stop <id>` 才能创建新 Goal。


### 3、Goal 状态机

Goal 模式拥有完整的 5 态状态机，实现可中断、可恢复的自主推进：

```
PURSUING ⇄ PAUSED → ACHIEVED | BUDGET_LIMITED
    ↓
  BLOCKED → (resume) → PURSUING
```

| 状态 | 说明 | 可恢复 |
|------|------|--------|
| **PURSUING** | 正在推进中，AI 持续执行 | — |
| **PAUSED** | 用户手动暂停（`/loop pause`） | 是 |
| **BLOCKED** | AI 主动声明阻塞（通过 `goal_update(blocked)`） | 是 |
| **ACHIEVED** | AI 调用 `goal_update(complete)` 标记完成 | 否（终态） |
| **BUDGET_LIMITED** | Token/时间预算耗尽 | 可通过扩容恢复 |

**状态变更方法：**

| 操作 | 方式 | 前置状态 |
|------|------|---------|
| 创建 | `/loop goal <objective>` | — |
| 暂停 | `/loop pause <id>` | PURSUING |
| 恢复 | `/loop resume <id>` | PAUSED / BLOCKED |
| 完成 | `goal_update(complete)` — AI 工具调用 | PURSUING |
| 声明阻塞 | `goal_update(blocked)` — AI 工具调用 | PURSUING |
| 预算耗尽 | 系统自动标记 | PURSUING |
| 扩容恢复 | `goal_update(extend_budget)` — AI 工具调用 | BUDGET_LIMITED |


### 4、Goal 模式深入

#### 4.1 AI 侧工具

Goal 模式下，系统会向 AI 暴露两个工具（仅在存在活跃 Goal 时动态加载，无 Goal 时不出现）：

| 工具 | 说明 | 调用者 |
|------|------|--------|
| `goal_get` | 查询当前 Goal 状态（目标、进度、预算消耗、耗时） | AI |
| `goal_update` | 更新目标状态：`complete`（标记完成）或 `blocked`（声明阻塞） | AI |

**goal_get 返回值示例：**
```json
{
  "goal": {
    "taskId": "a1b2c3d4",
    "objective": "fix auth module",
    "status": "pursuing",
    "iteration": 3,
    "elapsedSeconds": 120,
    "consumedTokens": 15000,
    "maxTokens": 50000,
    "budgetExceeded": false,
    "maxDurationMs": 1800000,
    "remainingDurationSeconds": 1680
  },
  "remaining_tokens": 35000,
  "completionBudgetReport": null
}
```

#### 4.2 Budget 预算管理

Goal 模式支持 Token 和时间双重预算控制：

| 配置方式 | 说明 | 默认值 |
|---------|------|--------|
| `--max-tokens:<N>` | Token 预算上限 | settings.json 中配置 |
| `--max-duration:<N>` | 时间预算上限（分钟） | settings.json 中配置 |
| `settings.json → loop` | 全局默认预算 | 0（不限制） |

**预算阈值体系：**
- **警告阈值（默认 70%）**：引导词中提示 AI 调整策略
- **紧急阈值（默认 85%）**：引导词中增加紧急提示
- **预算耗尽**：触发 wrap-up 收尾回合，AI 总结进展后状态转为 BUDGET_LIMITED

**预算感知引导词（Budget-Aware Prompting）：**

| 剩余预算 | 引导词模式 | 章节数 |
|---------|-----------|--------|
| ≥ 30% | 完整模式 | 7 章节（证据驱动、忠于目标、审计完成、阻塞审计等） |
| 15% ~ 30% | 精简模式 | 3 章节（目标延续、审计完成、上一轮摘要） |
| < 15% | 极简模式 | 单段落 |

#### 4.3 运行时兜底机制

| 机制 | 说明 | 阈值 |
|------|------|------|
| **无进展检测** | 通过指纹对比（工具调用 + 结果长度桶 + 行数桶）检测停滞 | 连续 3 轮（可配置） |
| **连续异常重试** | 异常时递增延迟重试（5s → 10s → 15s...） | 连续 3 次后标记 BLOCKED |
| **CAS 防重入** | `tryStart()` CAS 语义防止同一任务重叠执行 | — |
| **BusyChecker** | 会话繁忙时跳过本轮执行 | 由注册的检查器决定 |
| **事件驱动续行** | Goal 每轮执行完成后自动调度下一轮（1s 冷却间隙） | 仅 PURSUING 且非繁忙时 |
| **ShutdownHook** | JVM 关闭时自动暂停所有活跃 Goal | — |
| **崩溃恢复** | 进程重启后自动恢复未过期任务，自动 resume 暂停/阻塞的 Goal | 持久化到 `loop-tasks.json` |


### 5、配置参考（settings.json）

在 `settings.json` 的 `loop` 节点下配置：

```json
{
  "loop": {
    "budgetWarningPercent": 70,
    "budgetCriticalPercent": 85,
    "defaultMaxTokens": 100000,
    "defaultMaxDurationMinutes": 60,
    "stagnationThreshold": 3,
    "maxConsecutiveErrors": 3,
    "validatorEnabled": true
  }
}
```

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `budgetWarningPercent` | int | 70 | Token 预算警告阈值（%） |
| `budgetCriticalPercent` | int | 85 | Token 预算紧急阈值（%） |
| `defaultMaxTokens` | long | 0（不限制） | Goal 默认 Token 预算上限 |
| `defaultMaxDurationMinutes` | int | 0（不限制） | Goal 默认时间预算上限（分钟） |
| `stagnationThreshold` | int | 3 | 连续无进展轮次阈值 |
| `maxConsecutiveErrors` | int | 3 | 连续异常阈值（超过后标记 BLOCKED） |
| `validatorEnabled` | bool | true | 是否启用目标验证器 |


![](/img/d52ab75af5534f64889cd5fbe2a63be9.png)


### 6、Goal 验证器

当 AI 调用 `goal_update(complete)` 标记目标完成时，系统会先执行客观验证：

- **默认验证器**（NoopValidator）：始终返回通过
- **自定义验证器**：可注册实现 `GoalValidator` 接口的验证器，执行如运行测试套件、检查文件存在等客观校验
- **插件化**：通过 `ValidatorFactory` 根据目标条件自动匹配验证器

验证失败时，系统会返回错误信息，AI 继续改进后重新提交。


### 7、持久化与恢复

- 所有 Loop 任务持久化在会话目录的 `loop-tasks.json` 文件中
- 使用原子写入（先写 `.tmp` 再 `atomicMove`），防止写入中断导致数据损坏
- 进程重启后自动：
  1. 加载 `loop-tasks.json` 恢复未取消的任务
  2. 重新注册调度
  3. 自动 resume 暂停/阻塞状态的 Goal（从 SIGINT 中断恢复）
- 每轮执行后实时持久化状态


### 8、完整示例

#### 定时检查 + Goal 修复

```bash
# 每隔 5 分钟检查构建状态
/loop 5m check if the CI build passed

# 查看所有任务
/loop ls

# 发现构建失败，创建 Goal 任务修复
/loop goal --max-tokens:50000 fix the CI build failure

# 查看 Goal 进展
/loop ls

# 临时暂停 Goal
/loop pause a1b2c3d4

# 恢复 Goal
/loop resume a1b2c3d4

# Goal 完成后，停止定时检查
/loop stop b2c3d4e5
```

#### 带有预算控制的 Goal

```bash
# 重构代码库，限制在 50000 Token 和 30 分钟内
/loop goal --max-tokens:50000 --max-duration:30 refactor the payment module

# 查看任务状态
/loop ls
```


### 9、与 `/continue` 的关系

| 特性 | `/loop goal` | `/continue` |
|------|-------------|-------------|
| 驱动方式 | 事件驱动，自动持续推进 | 手动触发 |
| 状态管理 | 完整状态机（暂停/恢复/完成/预算） | 无状态管理 |
| 预算控制 | Token + 时间预算 | 无预算 |
| 持久化 | 自动持久化，进程重启可恢复 | 仅恢复会话历史 |
| 适用场景 | 需要多轮自主完成的复杂任务 | 从上一次中断处继续聊天 |

> **提示**：如果只是想从上一次对话继续，使用 `/continue`。如果需要 AI 自主推进一个目标直到完成，使用 `/loop goal`。