# Goal 系统详解

## 什么是 Goal？

**Goal（目标）** 是这个 Agent 框架中的**计划管理系统**，用于帮助 Agent 组织和追踪复杂任务的执行过程。

### 核心概念

```
Goal = 执行计划中的一个目标节点
GoalTree = 目标树，管理整个执行计划的层级结构
```

可以把 Goal 理解为：
- **任务分解**：将大任务拆分成小目标
- **工作记忆**：记录当前在做什么、做完了什么
- **进度追踪**：跟踪每个目标的状态和结果

## 为什么需要 Goal？

### 问题场景

当 Agent 执行复杂任务时，会遇到这些问题：

1. **任务复杂**：一个大任务需要多个步骤
2. **容易迷失**：执行过程中忘记原本要做什么
3. **难以追踪**：不知道哪些完成了，哪些还没做
4. **缺乏规划**：没有清晰的执行路径

### Goal 的解决方案

```
用户任务: "帮我实现一个用户登录功能"

没有 Goal:
Agent → 直接开始写代码 → 可能遗漏测试、文档等

有 Goal:
Agent → 创建计划:
  1. 设计数据库表结构
  2. 实现登录接口
    2.1 实现密码加密
    2.2 实现 JWT 生成
    2.3 实现登录验证
  3. 编写单元测试
  4. 编写 API 文档

→ 按计划逐步执行 → 完整、有序、可追踪
```

## Goal 的结构

### Goal 对象

```python
@dataclass
class Goal:
    id: str                    # 唯一 ID（如 "1", "2", "3"）
    description: str           # 目标描述（如 "实现登录接口"）
    reason: str               # 创建理由（为什么要做这个）
    parent_id: Optional[str]  # 父目标 ID（构建层级关系）
    status: GoalStatus        # 状态：pending/in_progress/completed/abandoned
    summary: Optional[str]    # 完成时的总结（记录关键结论）

    # 统计信息
    self_stats: GoalStats     # 自身统计（消息数、token、成本）
    cumulative_stats: GoalStats  # 累计统计（包含所有子目标）
```

### GoalTree 目标树

```python
@dataclass
class GoalTree:
    mission: str              # 总任务描述
    goals: List[Goal]         # 所有目标的扁平列表
    current_id: Optional[str] # 当前焦点目标 ID
```

### 层级结构示例

```
GoalTree
├── mission: "实现用户登录功能"
├── current_id: "2.1"
└── goals:
    ├── Goal(id="1", description="设计数据库表结构", status="completed")
    ├── Goal(id="2", description="实现登录接口", status="in_progress")
    │   ├── Goal(id="3", parent_id="2", description="实现密码加密", status="completed")
    │   ├── Goal(id="4", parent_id="2", description="实现 JWT 生成", status="in_progress") ← 当前焦点
    │   └── Goal(id="5", parent_id="2", description="实现登录验证", status="pending")
    ├── Goal(id="6", description="编写单元测试", status="pending")
    └── Goal(id="7", description="编写 API 文档", status="pending")
```

显示为：

```
[Mission] 实现用户登录功能

1. [✓] 设计数据库表结构
2. [→] 实现登录接口
   2.1 [✓] 实现密码加密
   2.2 [→] 实现 JWT 生成  ← 当前焦点
   2.3 [ ] 实现登录验证
3. [ ] 编写单元测试
4. [ ] 编写 API 文档
```

## Goal 工具的使用

Agent 通过 `goal` 工具来管理计划：

### 1. 创建目标

```python
# 创建顶层目标
goal(add="设计方案, 实现代码, 编写测试")

# 创建子目标
goal(add="实现接口, 实现逻辑", under="2")

# 在某个目标后添加同级目标
goal(add="编写文档", after="3")
```

### 2. 切换焦点

```python
# 聚焦到目标 1，开始执行
goal(focus="1")

# 聚焦到子目标
goal(focus="2.1")
```

### 3. 完成目标

```python
# 完成当前目标，记录关键结论
goal(done="方案确定使用 JWT 认证，安全性高")

# 完成并切换到下一个
goal(done="接口实现完成", focus="2")
```

### 4. 放弃目标

```python
# 放弃不可行的目标
goal(abandon="方案 A 需要 Redis，但环境不支持")
```

## Goal 的工作流程

### 典型执行流程

```
1. 用户提交任务
   ↓
2. Agent 分析任务，创建初步计划
   goal(add="调研方案, 实现功能, 测试验证")
   ↓
3. 聚焦到第一个目标
   goal(focus="1")
   ↓
4. 执行目标（调用工具、分析结果）
   ↓
5. 完成目标，记录结论
   goal(done="确定使用 OpenPose 方案")
   ↓
6. 切换到下一个目标
   goal(focus="2")
   ↓
7. 如果需要，创建子目标
   goal(add="设计接口, 实现代码", under="2")
   ↓
8. 重复 3-7，直到所有目标完成
```

### 动态调整

```
执行过程中发现新问题：
goal(add="修复 Bug", after="2")

发现某个方案不可行：
goal(abandon="方案 A 性能不达标")
goal(add="尝试方案 B", after="1")
```

## Goal 的作用

### 1. 任务分解

将复杂任务拆分成可管理的小目标：

```
大任务: "开发一个博客系统"
↓
Goal Tree:
1. 设计数据库
   1.1 设计用户表
   1.2 设计文章表
   1.3 设计评论表
2. 实现后端 API
   2.1 用户管理
   2.2 文章管理
   2.3 评论管理
3. 实现前端页面
4. 部署上线
```

### 2. 进度追踪

清楚知道当前进度：

```
[Mission] 开发博客系统

1. [✓] 设计数据库
   1.1 [✓] 设计用户表
   1.2 [✓] 设计文章表
   1.3 [✓] 设计评论表
2. [→] 实现后端 API  ← 当前在这里
   2.1 [✓] 用户管理
   2.2 [→] 文章管理  ← 具体在这个子任务
   2.3 [ ] 评论管理
3. [ ] 实现前端页面
4. [ ] 部署上线

进度: 5/10 完成 (50%)
```

### 3. 工作记忆

记录关键结论，避免重复工作：

```
Goal 1: 调研数据库方案
Summary: "选择 PostgreSQL，支持 JSON 字段，性能好"

Goal 2: 实现用户认证
Summary: "使用 JWT + Redis 存储 token，过期时间 7 天"

→ 后续目标可以参考这些结论
```

### 4. 上下文管理

系统会定期将当前计划注入到 Agent 的上下文中：

```
System: 当前计划状态：
[Mission] 开发博客系统
1. [✓] 设计数据库 (已完成: 选择 PostgreSQL)
2. [→] 实现后端 API (进行中)
   2.1 [✓] 用户管理 (已完成: JWT 认证)
   2.2 [→] 文章管理 (当前焦点)
   2.3 [ ] 评论管理
...

Agent: 好的，我现在在做文章管理，已经完成了用户管理...
```

### 5. 可视化和调试

通过 API Server 可以可视化查看 Goal Tree：

```bash
python api_server.py
# 访问 http://localhost:8000/api/traces/{trace_id}
```

可以看到：
- 目标的层级结构
- 每个目标的状态
- 执行时间和成本
- 工具调用序列

## 实际案例

### 案例 1：简单任务（单个 Goal）

```python
任务: "将 CSV 文件转换为 JSON"

Goal Tree:
1. [→] 将 CSV 转换为 JSON

执行:
- 读取 CSV 文件
- 解析数据
- 转换为 JSON
- 保存文件
- goal(done="转换完成，输出到 output.json")
```

### 案例 2：中等任务（多个 Goal）

```python
任务: "分析销售数据并生成报告"

Goal Tree:
1. [✓] 读取销售数据
2. [✓] 数据清洗和预处理
3. [→] 数据分析
   3.1 [✓] 计算总销售额
   3.2 [→] 分析销售趋势
   3.3 [ ] 识别热销产品
4. [ ] 生成可视化图表
5. [ ] 编写分析报告
```

### 案例 3：复杂任务（深层嵌套）

```python
任务: "实现一个完整的用户认证系统"

Goal Tree:
1. [✓] 需求分析和方案设计
2. [→] 后端实现
   2.1 [✓] 数据库设计
       2.1.1 [✓] 设计用户表
       2.1.2 [✓] 设计权限表
   2.2 [→] API 实现
       2.2.1 [✓] 注册接口
       2.2.2 [→] 登录接口
       2.2.3 [ ] 登出接口
       2.2.4 [ ] 密码重置接口
   2.3 [ ] 安全加固
3. [ ] 前端实现
4. [ ] 测试
5. [ ] 部署
```

## 最佳实践

### 1. 先规划再执行

```python
# ✅ 好的做法
goal(add="调研方案, 实现功能, 测试验证")
goal(focus="1")
# 开始执行...

# ❌ 不好的做法
# 直接开始执行，没有计划
```

### 2. 记录关键结论

```python
# ✅ 好的做法
goal(done="选择 PostgreSQL，支持 JSON 字段，性能优于 MySQL")

# ❌ 不好的做法
goal(done="调研完成")  # 没有信息量
```

### 3. 保持焦点在具体目标

```python
# ✅ 好的做法
goal(add="设计接口, 实现代码", under="2")
goal(focus="2.1")  # 聚焦到具体的子目标

# ❌ 不好的做法
goal(focus="2")  # 聚焦在父目标，太宽泛
```

### 4. 灵活调整计划

```python
# 执行中发现新问题
goal(add="修复性能问题", after="3")

# 发现方案不可行
goal(abandon="方案 A 不支持并发")
goal(add="尝试方案 B", after="1")
```

### 5. 简单任务不过度拆分

```python
# ✅ 简单任务
goal(add="读取文件并统计行数")
# 一个目标就够了

# ❌ 过度拆分
goal(add="打开文件, 读取内容, 统计行数, 关闭文件")
# 太细碎，没必要
```

## 总结

### Goal 是什么？

- **计划管理系统**：帮助 Agent 组织和追踪任务执行
- **工作记忆**：记录当前在做什么、做完了什么
- **层级结构**：支持任务分解和嵌套

### Goal 的核心价值

1. **任务分解**：将复杂任务拆分成可管理的小目标
2. **进度追踪**：清楚知道完成了什么、还剩什么
3. **工作记忆**：记录关键结论，避免重复工作
4. **上下文管理**：系统自动注入计划状态到 Agent
5. **可视化调试**：通过 API Server 查看执行过程

### 何时使用 Goal？

- ✅ 复杂任务需要多个步骤
- ✅ 需要清晰的执行计划
- ✅ 需要追踪进度和结果
- ✅ 任务可能需要动态调整

- ❌ 非常简单的单步任务
- ❌ 不需要计划的即时响应

### 类比理解

```
Goal 就像是：

📋 待办清单（Todo List）
- 记录要做的事情
- 勾选完成的项目
- 添加新的任务

🗺️ 导航地图
- 规划路线
- 追踪当前位置
- 调整路径

🧠 工作记忆
- 记住当前在做什么
- 记录重要结论
- 避免迷失方向
```

---

**Goal 让 Agent 像人类一样有计划地工作，而不是盲目执行！** 🎯