# 目标管理指令

本节介绍 `/goal` 指令——基于 Ralph Loop 思想实现的持久化目标驱动循环。

返回：[指令面板说明](./09.0.指令面板说明.md)

---

## `/goal`

持久化目标驱动循环（Ralph Loop）。

- **作用**: 为当前会话绑定一个可验证的目标。在目标 `pursuing` 状态下，AI 每轮回答完成后会自动注入续接提示，驱动下一轮迭代，直到模型显式调用工具 `goal-update_goal` 标记 `achieved`/`unmet`，或 token 预算耗尽。
- **核心思想**:
  - 把模糊需求写成"可验证的契约"——具体可测的交付物
  - 由模型自检审计清单，必须检视真实文件/输出，禁止"测试通过就算完成"等代理信号
  - 仅模型可以将目标转为完成态（`achieved` 或 `unmet`）；`pause` / `resume` / `clear` / 预算调整由用户控制
- **状态机**:
  - `none -> pursuing`（创建）
  - `pursuing -> {paused | achieved | unmet | budget-limited}`
  - `paused -> pursuing`（resume）
  - `* -> none`（clear）

### 子命令一览

| 子命令                         | 作用                                                         |
| ------------------------------ | ------------------------------------------------------------ |
| `/goal <objective>`            | 创建并启动新目标                                             |
| `/goal <objective> --budget=N` | 创建并设置 token 预算，单位 M（默认 2，即 2,000,000 tokens） |
| `/goal` 或 `/goal status`      | 查看当前目标摘要                                             |
| `/goal pause`                  | 暂停当前目标（停止自动续接）                                 |
| `/goal resume`                 | 恢复已暂停的目标（立即触发一轮续接）                         |
| `/goal clear`                  | 清除当前目标                                                 |

### 参数说明

- **`<objective>`**: 目标描述。请写成可验证的契约，避免模糊措辞。
  - 推荐: `Refactor src/auth/login.ts to async/await; verify with npm test`
  - 不推荐: `Improve the repo`
- **`--budget=N`**: token 预算上限，单位 M（百万 tokens）。支持形如 `--budget=1.5` 或 `--budget 1.5`。默认 2（即 2,000,000 tokens）；触达上限后目标进入 `budget-limited`，模型还会有一次收尾轮次。

### 使用示例

```text
/goal Refactor source/utils/foo.ts to async/await; pass npm test
/goal Add unit tests for parseArgs() in source/utils/commands/goal.ts --budget=1
/goal pause
/goal resume
/goal status
/goal clear
```

### 行为细节

- **创建即启动**: 创建目标后会立即触发第一轮 AI 响应，目标摘要会作为一条命令消息显示在对话中。
- **自动续接**: 每次 AI 回答结束（非用户中断）时，下一轮会自动注入续接 prompt（包含目标描述、运行轮次、剩余预算、审计要求）。
- **唯一停止条件**: 必须由模型调用 `goal-update_goal` 工具显式设置 `status=achieved` 或 `status=unmet`，仅靠文字声明"已完成"不会停止循环。
- **token 预算**: 累计输入 / 输出 token，超出后切到 `budget-limited`，模型会收到一次"预算耗尽收尾"提示，要求总结进展、给出下一步、避免虚假完成声明。
- **暂停**: 输入 `/goal pause`、按 `ESC` 也可暂停当前轮。`resume` 后会立即触发一次续接。
- **持久化**: 目标记录保存在 `~/.snow/goals/<projectId>/<sessionId>.json`，单会话仅允许一个活跃目标；如已存在 `pursuing` 或 `paused` 目标，需先 `clear` 才能创建新目标。

### 模型如何标记完成

模型通过 MCP 工具 `goal-update_goal` 提交完成状态，必填字段：

- `status`: `achieved` 或 `unmet`
- `explanation`: 简短说明，引用真实证据（文件、命令输出、测试结果）

模型工具的描述里明确强调："不允许把代理信号（例如测试通过）当成目标达成的依据"。

### 相关文件

- `source/utils/commands/goal.ts` —— `/goal` 指令解析与调度
- `source/utils/task/goalManager.ts` —— 状态机、续接提示词、token 预算
- `source/mcp/goal.ts` —— `goal-update_goal` 工具实现