# 目标系统与自动模式

## Goal 系统

Goal（目标）系统允许用户通过 `/goal <objective>` 命令设定一个长期目标，让 Agent 在多个对话轮次中持续追寻该目标，直至完成、受阻或暂停。

### 状态机

Goal 的生命周期由以下状态构成：

```
pursuing → paused → achieved / blocked
         → usage-limited / budget-limited
```

- **pursuing（追寻中）**：初始状态，Agent 正在积极地朝目标推进。
- **paused（已暂停）**：用户使用 `/goal pause` 暂停自动续跑，可用 `/goal resume` 恢复。
- **achieved（已完成）**：Agent 认定目标已完全达成。需经过严格的完成审计（Completion Audit）。
- **blocked（已阻塞）**：Agent 遇到无法继续的障碍，需要用户介入。
- **usage-limited / budget-limited**：因 token 预算或费用限制而停止。

### 核心文件

| 文件 | 路径 | 用途 |
|------|------|------|
| goal.tsx | `src/commands/goal/goal.tsx` | `/goal` 命令的 JSX 实现（React Ink 渲染） |
| index.ts | `src/commands/goal/index.ts` | 命令注册入口 |
| goal.ts | `src/utils/goal.ts` | 工具函数：构建续跑提示、状态格式化 |
| useGoalAutoContinue.ts | `src/hooks/useGoalAutoContinue.ts` | React Hook：在每轮对话结束后自动注入续跑提示 |

### 持续提示

`buildContinuationPrompt()`（定义于 `src/utils/goal.ts`）在每轮自动续跑时注入完整的上下文提示，包含：

- **目标描述**（`<objective>` XML 标签包裹）
- **续跑行为指导**：保持目标完整性，不允许缩小范围
- **基于证据的工作原则**：依赖当前工作区状态而非对话记忆
- **完成审计要求**：必须逐项验证所有需求
- **阻塞审计规则**：连续 3 轮相同阻塞条件才允许标记 blocked

`useGoalAutoContinue` hook（`src/hooks/useGoalAutoContinue.ts`）监听 `QueryGuard` 状态：
- 当查询从活跃（running）转为空闲（idle）时触发
- 仅在 goal 状态为 `pursuing` 且非 plan 模式时注入
- 自动清理旧目标的排队续跑，防止冲突
- 每次续跑递增 `continuationCount`

### 完成审计（Completion Audit）

Agent 在决定标记目标为 `achieved` 前，必须执行严格的完成审计：

1. 从目标描述中推导具体的、可验证的需求
2. 不重新定义成功标准——保留原始范围
3. 对每个需求，检查当前状态中的权威证据
4. 确认证据足以证明完成，而非仅未发现未完成的工作
5. 只有在当前证据能够经受逐项审查时，才标记为已达成

### Blocked 审计

防止 Agent 过早放弃的机制（`src/utils/goal.ts` 中 `BLOCKED_AUDIT_TURNS = 3`）：

- 阻塞条件必须连续出现 **至少 3 轮** 才能标记 blocked
- 用户恢复已阻塞的目标后，阻塞审计重置
- 仅在确实无法推进、需要用户输入或外部状态变更时才使用
- 不因任务困难、缓慢或需要澄清而标记 blocked

### 预算跟踪

`checkTokenBudget()`（定义于 `src/query/tokenBudget.ts`）根据 token 消耗决定是否继续自动续跑：

- 使用 `createBudgetTracker()` 跟踪每次续跑的 token 消耗
- `COMPLETION_THRESHOLD = 0.9`：token 消耗达到预算的 90% 时停止
- `DIMINISHING_THRESHOLD = 500`：连续 3 次续跑且每次增量 < 500 token 时视为收益递减
- 返回 `continue` 或 `stop` 决策

---

## Auto Mode（自动模式）

### 激活方式

- 用户通过 `/goal <objective>` 设置目标后自动进入自动模式
- Plan 模式下自动模式被禁用（`inPlanMode` 检查）

### 自动续跑机制

每次 Agent 响应完成后，`useGoalAutoContinue` hook 自动向命令队列注入 `[goal] Continue` 提示：

```typescript
const prompt = buildContinuationPrompt(goal, now)
enqueue({
  mode: 'prompt',
  value: prompt,
  priority: 'later',
  isMeta: true,
})
```

- 只在 `pursuing` 状态下触发
- 跳过 plan 模式
- 用户输入优先于自动续跑（有阻塞性用户输入时不注入）
- 避免为同一目标重复排队

### update_goal 工具

Agent 可通过 `update_goal` 工具报告进度：

- `status='complete'`：目标达成，停止续跑
- `status='blocked'`：受阻，需用户介入
- 调用时必须包含 `goal_id`（与目标 ID 匹配）

### 目标管理命令

| 命令 | 功能 |
|------|------|
| `/goal <objective>` | 设置新目标（若已有活跃目标则提示覆盖确认） |
| `/goal set <objective>` | 同上 |
| `/goal pause` | 暂停当前目标 |
| `/goal resume` | 恢复被暂停的目标（重置续跑计数和预算窗口） |
| `/goal edit <new objective>` | 编辑目标描述 |
| `/goal clear` | 清除当前目标 |
| `/goal`（无参数） | 查看当前目标状态 |

---

## 查询循环（query.ts）

### queryLoop() 主循环

`src/query.ts` 中的 `queryLoop()` 是 Agent 的核心执行循环，在 `QueryEngine.ts` 中被调用。每次迭代处理一个完整的模型调用周期：

```
模型调用 → 流式响应处理 → 工具执行 → stop hooks → 继续决策
```

1. **模型调用**：`queryModelWithStreaming()` 发送消息到 API
2. **流处理**：处理 `content_block_start/delta` 事件
3. **工具执行**：检测 `tool_use` 并执行
4. **stop hooks**：执行 `handleStopHooks()`（记忆提取、自动 dream、prompt 建议等）
5. **继续决策**：检查是否需要继续循环（工具调用、max_output_tokens 恢复、goal 续跑）

### max_output_tokens 恢复

当模型响应被 `max_output_tokens` 截断时，queryLoop 提供最多 **3 次** 恢复尝试（`MAX_OUTPUT_TOKENS_RECOVERY_LIMIT`）：

1. 注入恢复提示，指导模型从中断处继续
2. 若 8K 默认输出限制触发，自动升级到 64K（一次，`tengu_otk_slot_v1` 功能门控）
3. 恢复尝试耗尽后，将错误信息输出给用户

相关变量（`src/query.ts`）：
- `maxOutputTokensRecoveryCount`：当前恢复尝试次数
- `MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3`：最大恢复次数
- `ESCALATED_MAX_TOKENS`：升级后的输出 token 上限

### Reactive Compaction

当上下文超出 API 限制时自动触发压缩：

- `hasAttemptedReactiveCompact`：防止在同一轮迭代中重复压缩
- 上下文超时（prompt-too-long）触发的压缩流程
- 压缩后保持 stop hooks 的阻塞错误处理
- 保留反应式压缩保护（不因 stop hook 错误而重置，防止无限循环）

---

## Task 系统

Task（任务）系统管理 Agent 派发的异步子任务。

### Task 类型

定义于 `src/Task.ts`：

| 类型 | 标识 | 用途 |
|------|------|------|
| `local_bash` | `b` | 本地 Shell 命令执行 |
| `local_agent` | `a` | 本地子 Agent |
| `remote_agent` | `r` | 远程 Agent |
| `in_process_teammate` | `t` | 进程内队友 |
| `local_workflow` | `w` | 本地工作流脚本 |
| `dream` | `d` | 记忆整理任务 |
| `monitor_mcp` | `m` | MCP 监控 |

### 状态

```
pending → running → completed / failed / killed
```

- `pending`：等待分配
- `running`：正在执行
- `completed`：正常完成
- `failed`：执行失败
- `killed`：被终止

### 后台/前台任务

任务系统区分前台任务（阻塞用户交互）和后台任务（在后台运行），但 Task 类型本身不区分配置字段；区分体现在调用上下文中。

### 任务 ID 生成

`generateTaskId()`（`src/Task.ts`）生成格式为 `{类型前缀}{8位随机字母数字}` 的 ID：
- 使用 `randomBytes(8)` 生成安全随机数
- 36 进制字母表（数字 + 小写字母）
- 36^8 ≈ 2.8 万亿种组合，抗暴力枚举

### stopTask（优雅终止）

Task 的 `kill()` 方法实现优雅终止，每个 Task 类型提供独立的 `kill` 实现（`src/tasks.ts`）：

```typescript
export type Task = {
  name: string
  type: TaskType
  kill(taskId: string, setAppState: SetAppState): Promise<void>
}
```

### 任务注册

`src/tasks.ts` 中的 `getAllTasks()` 收集所有可用 Task：
- 始终注册：`LocalShellTask`, `LocalAgentTask`, `RemoteAgentTask`, `DreamTask`
- 条件注册（通过 feature gate）：`LocalWorkflowTask`, `MonitorMcpTask`