# Agent Context 构建

AgentState 如何变成 LLM API call 的 messages 数组。定义见 `src/state.rs`。

## AgentState

```rust
struct AgentState {
    phase: AgentPhase,                              // Planning | Executing { step } | Completed
    steps: Vec<Step>,                               // 执行计划，每个 step 有 status + optional summary
    current_step_chat_history: Vec<ChatMessage>,     // 当前步骤内的多轮对话，step 切换时 clear
    scratchpad: String,                             // LLM 的跨步骤工作区
}
```

整个结构体 `Serialize/Deserialize`，可 JSON 直接存 DB。

## Step 生命周期

```
Pending → Running → Done(summary) 或 Failed
```

summary 在 step 完成时由 LLM 填入，作为后续步骤的压缩上下文。

## Messages 组装

### Planning 阶段

```
[ system(planning_prompt), user(requirement), ...current_step_chat_history ]
```

### Executing 阶段

```
[ system(execution_prompt), user(step_context), ...current_step_chat_history ]
```

`step_context` 由 `build_step_context()` 拼接：

```
## 需求
{requirement}

## 计划概览
1. 分析代码结构  done
2. 实现核心逻辑  >> current
3. 写测试        FAILED
4. 集成测试

## 当前步骤（步骤 2）
标题：实现核心逻辑
描述：...

## 已完成步骤摘要          ← 从 steps 中 filter Done，取 summary
- 步骤 1: ...

## Scratchpad              ← LLM 自己维护的跨步骤笔记
...
```

## 持久化

### DB 表

- **agent_state_snapshots** — step 切换时 insert 一行 AgentState JSON 快照（追加，不覆盖，保留历史）。恢复时取最新一行。
- **execution_log** — tool call 的输入输出记录（不可变历史），前端展示 + report 生成用。

Plan 步骤只从 AgentState JSON 读，不再单独写表。

### Executing 阶段 text response

LLM 返回纯文本时不隐含"workflow 结束"，写 execution_log 显示给用户。只有显式调 `advance_step` 才推进步骤。

## 待做：Context 压缩

当前无长度限制，`current_step_chat_history` 在单步 tool call 轮次过多时会无限增长。

压缩按优先级从低到高砍：

| 优先级 | 内容 | 处理 |
|---|---|---|
| 高 | system prompt / requirement / plan 概览 | 不压缩 |
| 中 | 当前步骤最近 N 轮 tool call | 完整保留 |
| 低 | 当前步骤早期 tool call | 替换为摘要 |