> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 目标管理

> 定义长时目标，含预算控制、验收标准与自主执行。

# 目标管理

目标将 Myrm 从聊天助手变为自主工作者。定义目标、设约束，让 Agent 跨多轮独立工作。

## 创建目标

### 从 GUI

1. 在消息输入区域切换 **目标模式**（右下方切换按钮）
2. 配置面板展开，包含以下区域：
   * **预算** — 设置 `max_tokens`、`max_usd`、`max_time_seconds`、`max_turns` 的任意组合
   * **验收标准** — 定义 Shell 命令和语义检查
   * **约束** — Agent 执行期间必须遵守的规则
   * **保护路径** — 禁止 Agent 修改的文件 glob 模式（如 `*.env`、`migrations/**`）
   * **高级** — `loop_on_pause` 自动重启、`convergence_window` 收敛窗口、**逐步暂停确认**（Per-Todo Checkpoint）
3. 在消息框输入目标后发送 — Agent 开始规划执行

### 从对话

用自然语言描述复杂任务，Agent 识别需持续努力并提议创建目标。

## 目标生命周期

```
QUEUED → ACTIVE → PAUSED / WAIT / BUDGET_LIMITED / NEEDS_HUMAN_REVIEW → COMPLETE / CANCELLED
           ↑                            ↓
    PENDING_APPROVAL ←───────── (resume)
```

| 状态                   | 说明                                                          |
| -------------------- | ----------------------------------------------------------- |
| `QUEUED`             | 排队等待当前活跃目标结束                                                |
| `ACTIVE`             | Agent 积极向目标推进                                               |
| `PENDING_APPROVAL`   | 等待用户批准执行计划                                                  |
| `PAUSED`             | 用户暂停或收敛检测暂停                                                 |
| `WAIT`               | Agent 被阻塞，需要用户输入或等待外部事件（如后台任务完成、用户提供凭据等），或判定目标在无用户指导的情况下不可达 |
| `BUDGET_LIMITED`     | 预算耗尽 — 需用户追加预算并恢复                                           |
| `NEEDS_HUMAN_REVIEW` | 验证失败 — 需人工审核反馈                                              |
| `COMPLETE`           | 目标达成并验证                                                     |
| `CANCELLED`          | 用户显式取消                                                      |

## 预算控制

每个目标 4 维预算：

| 维度                 | 说明          | 示例         |
| ------------------ | ----------- | ---------- |
| `max_tokens`       | 最大总 Token   | 500,000    |
| `max_usd`          | 最大美元花费      | \$5.00     |
| `max_time_seconds` | 最大墙钟时间      | 3600（1 小时） |
| `max_turns`        | 最大 Agent 轮次 | 30         |

预算耗尽时暂停并附结构化进度摘要。可随时**恢复**并追加预算。

## 验收标准

定义「完成」标准：

```
All tests pass, code coverage > 80%, no new linting errors
```

Agent 使用**双引擎验证**：

1. **Shell 验证** — 运行测试命令（`pytest`、`npm test`）检查结果
2. **语义验证** — LLM 对照验收标准评估

两引擎均通过才标为完成。

### 高级用法：逻辑一致性验证

对于长文档生成任务，语义验证可确保全文逻辑一致、前后呼应：

```
检查报告所有章节逻辑一致：前文提到的数据和观点在后文得到回应，无矛盾或遗漏
```

Agent 写完报告后，LLM 会读取完整产出物并判定逻辑是否连贯。不通过则 Agent 自动修复（最多 3 次重试，之后自动暂停等待人工介入）。

## 约束

Agent 必须遵守的硬规则：

```
Do not modify the database schema
Do not introduce new dependencies
Keep all changes backward compatible
```

每轮作为「CONSTRAINTS (MUST NOT VIOLATE)」块注入提示词，语义裁判在完成验证时评估合规。

## 14 层防死循环盾

每轮末 14 层守卫链决定是否继续 — 杜绝失控执行、成本超支、Token 浪费、轨迹偏离和沙箱越权：

| #  | 守卫层            | 作用                                                                    |
| -- | -------------- | --------------------------------------------------------------------- |
| 1  | **用户取消**       | 通过取消令牌即时中断                                                            |
| 2  | **4 维预算**      | Token / USD / 时间 / 轮次，任一维度耗尽即暂停                                       |
| 3  | **转向令牌**       | 有待处理用户消息时暂停，确保用户消息优先                                                  |
| 4  | **工具完成检测**     | 检测工具是否已报告目标完成                                                         |
| 5  | **沙箱边界 HITL**  | 连续 3 次 `PERMISSION_DENIED` → 优雅暂停（非暴力中断）+ 前端红色警报等待人工审查                |
| 6  | **轨迹偏离检测**     | 每 5 轮用 LITE\_MODEL 评估偏离分 0-10。≥3 注入纠偏提示；≥7 暂停等待人工审查。LLM 失败时 fail-open |
| 7  | **逐步人工确认**     | Opt-in 模式：每完成一个 todo 自动暂停，等待用户确认后继续。适用于生产部署、数据迁移等高风险多步骤任务             |
| 8  | **语义裁判（LLM）**  | 根据对话上下文判断目标是否达成                                                       |
| 9  | **约束合规**       | 检查验收标准和文件保护规则                                                         |
| 10 | **零进度暂停**      | 本轮无工具调用→自动暂停，防"说很多但没做事"                                               |
| 11 | **Judge 解析熔断** | 连续 3 次不可解析→暂停（避免劣质模型浪费 Token）                                         |
| 12 | **验证保险丝**      | 连续 3 次验证失败→暂停（防验证死循环）                                                 |
| 13 | **收敛检测**       | 连续 K 轮无进展→自动完成（`convergence_window`）                                  |
| 14 | **优雅收尾**       | 预算耗尽时注入收尾提示，最后一轮总结 — 不中途断句                                            |

此外，**渐进预算降级**（WARNING → FINALIZATION，含动态剩余 USD 注入）和**4 层上下文窗口溢出保护**在中间件层运作，在守卫链之前捕获边缘情况。

### 裁判反馈闭环

当语义裁判判定目标**尚未完成**时，会给出具体原因（如"5 张图表只完成了 3 张"）。该原因自动注入下一轮提示词，让 Agent 精确知道差距所在——消除冗余重分析，减少不必要的轮次。

### 逐步人工确认（Per-Todo Checkpoint）

在高级设置中开启\*\*"逐步暂停确认"\*\*即可激活该模式。开启后，Agent 每完成一个 todo 项会自动暂停，等待你确认后再继续。

**工作流程：**

1. Agent 通过 `todo_write` 报告某 todo 已完成
2. 守卫链检测到新完成项，自动暂停目标
3. GoalStatusCard 展示刚完成的步骤和**继续**按钮
4. 你审查结果，点击**继续**推进到下一步

**适用场景：**

* **生产部署** — 每步迁移确认后再继续
* **数据管道** — 每阶段验证数据完整性
* **复杂重构** — 逐步审查代码变更
* **学习模式** — 了解 Agent 每步的执行逻辑

默认关闭，不影响现有体验。开启后 Agent 每步可控，适合高风险多步骤任务。

## 优先级队列

多目标自动排队：

* 首个立即运行
* 后续进入 `QUEUED`
* 活跃目标结束自动启动下一个
* GUI 拖放重排

`auto_approve: true` 跳过审批，支持目标链完全无人值守。

## 自适应收敛与自动续跑

目标能自动检测 Agent 是否已完成工作，支持无人值守的持续执行。

### 收敛检测

当 Agent 连续 `convergence_window` 轮未调用任何工具时，系统判定目标已自然收敛（完成）。避免 Agent 空转浪费 Token。

| 参数                   | 说明          | 默认    |
| -------------------- | ----------- | ----- |
| `convergence_window` | 无进展多少轮后自动收敛 | （未启用） |

### 自动续跑（Loop-on-Pause）

启用后，因收敛暂停的目标会自动重启并获得全新上下文，最多重启可配置次数。适用于长期监控或迭代优化任务。

| 参数                  | 说明        | 默认      |
| ------------------- | --------- | ------- |
| `loop_on_pause`     | 收敛暂停后自动重启 | `false` |
| `max_loop_restarts` | 最大自动重启次数  | 0       |

### 恢复安全

手动恢复暂停目标时，所有运行时计数器（`no_progress_streak`、`loop_restarts`、`consecutive_judge_parse_failures`）自动归零，确保 Agent 获得完整新机会，不会立即再次触发收敛或误暂停。

### Judge 失败熔断

如果语义 Judge 模型连续 **3 次**返回无法解析的输出（非有效 JSON），目标自动暂停以防止 token 浪费。此机制保护以下场景：

* 使用了不支持 JSON 格式回复的弱模型
* 模型暂时降级产生无效输出
* 避免无限重试循环浪费预算

暂停时，reason 字段明确说明原因并建议切换更强的 Judge 模型。恢复目标后计数器自动重置。

API/网络错误**不**计入此阈值——仅内容级解析失败触发熔断。

### 服务重启恢复

如果服务重启（升级、崩溃或容器重调度）时目标正在执行，孤儿目标会被自动检测并暂停：

* 启动时扫描所有仍标记为 ACTIVE 但无执行引擎驱动的目标
* 每个孤儿目标转为 **PAUSED**，reason 显示"Server restarted — resume when ready"
* 系统通知提醒您有目标被暂停
* 打开对应会话即可看到暂停状态并一键恢复

这样既防止了静默的 token 浪费（不会未经同意自动恢复），又确保中断的工作不会丢失。

### 前端状态

目标状态卡片差异化显示：

* **已收敛** — 目标通过收敛检测完成
* **重启中 (#N)** — 目标正通过自动续跑重启（显示重启次数）

## 全局 Goal 追踪

无需切换页面，在任何位置实时监控所有活跃目标：

* **导航栏 Badge** — 实时显示活跃目标数量，通过 SSE 推送即时更新。
* **后台任务面板** — 点击 badge 展开 Popover，查看所有会话的活跃目标：目标、状态、token 消耗、运行时间。
* **快捷操作** — 直接在面板中暂停、恢复或取消任意目标。操作完成后 toast 确认。
* **会话导航** — 「跳转到会话」按钮直达目标所在的聊天上下文。
* **系统通知** — 目标完成/失败/暂停时推送 OS 通知，即使浏览器在后台也不会错过。

支持所有部署模式 — 本地 WebUI、Tauri 桌面端、云托管沙箱。

## 动态子目标

执行中可添加新目标而不中断：

1. 打开活跃目标详情
2. 添加子目标（如「为新模块补单元测试」）
3. 以最高优先级注入上下文

子目标纳入语义裁判完成标准。

## IM 斜杠命令

在任意 IM 渠道（Slack、飞书、Telegram、WhatsApp 等）中完整管理目标：

| 命令                       | 说明            |
| ------------------------ | ------------- |
| `/goal set <目标>`         | 创建目标          |
| `/goal status`           | 查看目标状态、约束和子目标 |
| `/goal pause`            | 暂停目标          |
| `/goal resume`           | 恢复目标          |
| `/goal clear`            | 取消并清除目标       |
| `/goal budget <额度>`      | 追加预算          |
| `/goal constraint <文本>`  | 添加硬约束         |
| `/goal constraint`       | 查看全部约束        |
| `/goal constraint clear` | 清除全部约束        |
| `/subgoal add <文本>`      | 添加子目标         |
| `/subgoal list`          | 列出子目标         |
| `/subgoal remove <序号>`   | 按序号移除子目标      |
| `/subgoal clear`         | 清除全部子目标       |

通过 IM 添加的约束以"CONSTRAINTS (MUST NOT VIOLATE)"注入 Agent 提示词，语义裁判在完成验证时强制执行，与 GUI 设置的约束行为完全一致。

## 目标热编辑

执行中可改方向：

1. 打开活跃目标详情
2. 编辑目标文本
3. 作为转向消息注入 — Agent 调整航向不丢进度

## 执行摘要

完成后每个目标产出 `GoalExecutionSummary`：

* 修改文件（含 diff 链接）
* Token 用量分解
* 按模型成本分解
* 耗时
* 轮次
* 完成原因

GUI 与 API 均可查看。

## 交付物 Bundle

当目标完成且产出 **2 个或以上的交付物**（文档、电子表格、演示文稿等）时，Myrm 会自动将它们聚合为 **交付物 Bundle** 卡片：

* **自动收集** — 目标 session 期间产出的所有 artifacts 自动收集，无需手动操作
* **一键 ZIP 下载** — 将整个 bundle 打包为 ZIP 一键下载
* **逐个预览** — 点击任意交付物在 Artifact Portal 中格式感知渲染
* **文件名去重** — 同名文件自动追加唯一标识

### 使用场景：办公全链路交付

使用预置的 **「办公全链路交付」** 智能体模板，一次对话生成完整文档套件：

1. 在智能体选择器中选择「办公全链路交付」
2. 描述交付需求（例如："帮我准备季度汇报全套材料：Excel 数据表 + PPT 演示 + Word 总结报告"）
3. 智能体以 Goal 模式执行，确保所有文档间数据一致
4. 完成后交付物 Bundle 卡片自动出现，全部文件一键下载

### API 访问

交付物也可通过 REST API 获取：

* `GET /api/goals/{goal_id}/status` — 返回 `deliverables` 数组（含 artifact ID 和文件名）
* `POST /api/files/download-bundle` — 将多个 artifacts 打包为 ZIP 下载

## 示例工作流

```
用户：「将 API 从 Express 迁到 Fastify」

创建目标：
  目标：Express → Fastify 迁移
  标准：现有测试全过、API 契约不变
  约束：不改数据库层
  预算：max_turns=50, max_usd=$10

Agent：
  第 1-3 轮：规划迁移，识别 12 个受影响文件
  第 4-15 轮：重写路由
  第 16-20 轮：更新中间件
  第 21-25 轮：修失败测试
  第 26 轮：测试全过，语义裁判确认完成

目标 COMPLETED — 26 轮，花费 $3.47
```

## 项目里程碑（跨会话目标）

Goal 在单次会话内运作，而**项目里程碑**跨越多个会话。你可以为整个项目定义战略目标，Agent 在每次对话中自动感知它们。

### 工作原理

1. **创建里程碑** — 在侧边栏项目面板中添加
2. **自动上下文注入** — `ProjectRoadmapMiddleware` 将紧凑的路线图上下文（\~100 token）注入该项目的每次对话
3. **追踪进度** — 里程碑关联看板任务，自动计算完成率

### 创建里程碑

在侧边栏导航到你的项目，找到**里程碑**区域：

* 点击 `+` 按钮添加新里程碑
* 每个里程碑有**标题**、可选的**描述**和**验收标准**
* 目标达成后标记为已完成

### 自动上下文注入

当你在有里程碑的项目中对话时，Agent 会收到类似这样的上下文：

```
Project: Q3 产品升级 — 完成核心功能迭代
Current Focus: 完成里程碑系统并上线

Active Milestones:
  - [active] MVP 发布 (criteria: 所有核心 API 通过集成测试)
  - [active] Beta 公测

Completed: 技术调研
```

这一切自动发生 — 无需任何命令。

### Goal vs 里程碑

| 维度   | Goal                       | 里程碑                           |
| ---- | -------------------------- | ----------------------------- |
| 范围   | 单次会话                       | 跨会话（项目级）                      |
| 生命周期 | QUEUED → ACTIVE → COMPLETE | active → completed → archived |
| 执行方式 | Agent 自主执行                 | 战略方向指引，手动标记完成                 |
| 预算   | 有（token、费用、轮次、时间）          | 无预算 — 纯组织管理                   |
| 使用场景 | "将 API 迁移到 Fastify"        | "Q3：发布 v2.0 到生产环境"            |