AstroResearch/docs/architecture/agent/context.md

# Agent 上下文管理系统

AstroResearch Agent 的上下文管理是一个多层防御架构，涵盖从系统提示词组装、运行时预算监控、多级压缩、错误恢复到跨会话持久化的完整生命周期。

## 架构概览

```mermaid
graph TB
    subgraph 构建阶段["构建阶段"]
        SP["SystemPrompt<br/>模块化组装"]
        HL["+ 历史加载"]
        TR["+ 任务恢复"]
        SL["+ 技能列表"]
        PM["+ 项目记忆"]
    end

    subgraph 运行时监控["运行时监控"]
        TB["TokenBudget<br/>三级渐进Nudge"]
        DR["DimReturns"]
        TD["Todo提醒"]
        BN["后台通知"]
        LD["死循环检测"]
    end

    subgraph 压缩阶段["压缩阶段"]
        L0["snip (L0)"]
        L1["micro (L1)"]
        L2["auto (L2)"]
        L3["aggro_micro (L3)"]
        L4["identity (L4)"]
        L0 --> L1 --> L2 --> L3 --> L4
    end

    subgraph 恢复阶段["恢复阶段"]
        ER["ErrorRecovery<br/>5级恢复阶梯"]
        B4["429指数退避"]
        CB["熔断器保护"]
        FC["file_cache<br/>恢复注入"]
    end

    subgraph 持久化层["持久化层"]
        AM["agent_msgs"]
        AT["agent_tasks"]
        MM["MEMORY.md"]
        TJ["trajectory"]
        AL["audit_log"]
    end

    构建阶段 --> 运行时监控 --> 压缩阶段 --> 恢复阶段 --> 持久化层
```

## 1. 上下文构建 (`runtime/context.rs` + `runtime/session.rs`)

### 1.1 构建流程

每个 turn 开始时 `build_initial_context()` 按以下顺序构建 LLM 消息列表：

1. 从 `agent_messages` 表加载历史消息（按 `agent_name='lead'` 隔离，排除子代理消息）
2. 若历史中无 System 消息，在最前面插入 System Prompt
3. 追加当前用户问题
4. 从 `agent_tasks` 表恢复持久化任务状态，格式化为 `[当前任务状态]` 消息块

### 1.2 System Prompt 模块化组装 (`runtime/system_prompt.rs`)

静态与动态 section 分离，静态 section 在前以最大化 prompt cache 命中率：

| 顺序 | Section | 类型 | 内容 |
|:---|:---|:---|:---|
| 1 | `identity` | 静态 | "你是一位专业的天体物理学研究助手…" |
| 2 | `tools` | 动态 | 从 ToolRegistry 生成工具名称 + 一行描述（~20 tokens/tool） |
| 3 | `skills` | 动态 | 从 SkillRegistry 构建 `<system-reminder>` 技能列表（~20 tokens/skill） |
| 4 | `memory` | 动态 | 从 MemoryManager 加载最近 5 条项目记忆 |
| 5 | `principles` | 静态 | 9 条核心工作原则（主动搜索、引用来源、LaTeX 格式等） |

### 1.3 会话生命周期 (`session.rs`)

- `create_or_resume_session()`：新建会话生成 UUID，恢复会话验证存在性并计算 turn_index
- `load_history_for_agent()`：按 `session_id + agent_name` 加载，还原 role/content/tool_calls/tool_call_id/thought 字段
- 消息隔离：`agent_name="lead"` 仅加载主代理历史，`"*"` 加载全部（调试用）

---

## 2. 上下文运行时监控 (`runtime/mod.rs` ReAct 循环内)

每一步 LLM 调用前执行以下检查：

### 2.1 Token 预算管理 (`runtime/token_budget.rs`)

```
软限制: AGENT_TOKEN_SOFT_LIMIT  (默认 32,000)
硬限制: AGENT_TOKEN_HARD_LIMIT  (默认 40,000)
```

**三级渐进式 Nudge**（每步检查，按优先级仅注入一条）：

| 级别 | 条件 | 图标 | 消息语义 |
|:---|:---|:---|:---|
| `near_soft` | `total_spent ≥ soft_limit × 80%` | 💡 | "Token 预算提示…请注意控制后续步骤的深度" |
| `over_soft` | `total_spent ≥ soft_limit` | 🟡 | "Token 预算警告…请尽快总结关键发现" |
| `over_hard` | `total_spent ≥ hard_limit` | 🔴 | "已耗尽…请立即总结并给出最终答案" |

**Diminishing Returns 检测**：
- 条件：3+ 次延续 + 连续 2 次检查的 token 增量 < 500
- 触发后：强制终止工具调用，注入"请直接给出最终答案"消息，调用 `final_answer_without_tools()`

### 2.2 TodoWrite Nag 提醒

连续 3 步未调用 `todo_write` → 注入提醒消息，防止模型陷入无计划循环。

### 2.3 后台任务通知注入 (`background.rs`)

慢速操作（download_paper, parse_paper）通过 `bg_task_run` 异步执行。
每轮 LLM 调用前，`BgNotificationQueue::drain()` 收集已完成结果并注入：

```
[后台任务完成] ✅ download_paper: 2024A&A... (task_abc123): 下载成功...
```

### 2.4 死循环检测 (`DuplicateDetector`)

- 同一 `(tool_name, arguments)` 连续调用 ≥ 3 次 → 注入错误 tool_result 跳过
- 同时在 metrics 中记录 `duplicate_detections`

---

## 3. 上下文压缩系统 (`compact.rs`)

### 3.1 五层压缩策略

`compress_with_fallback()` 按顺序执行，每层后检查是否需要继续：

```mermaid
graph LR
    L0["Layer 0: snip_compact<br/>零 API 调用<br/>消息超 MAX_MESSAGES 时截断"]
    L1["Layer 1: micro_compact<br/>零 API 调用<br/>替换早期工具结果为占位符"]
    L2["Layer 2: auto_compact<br/>LLM 摘要<br/>历史压缩为 &lt;500 字中文"]
    L3["Layer 3: aggressive_micro<br/>零 API 调用<br/>激进占位符 keep_recent=2"]
    L4["Layer 4: identity_inject<br/>零 API 调用<br/>注入身份确认块"]
    L0 --> L1 --> L2 --> L3 --> L4
```

| 层 | 触发条件 | 算法 | API 调用 | 关键参数 |
|:---|:---|:---|:---|:---|
| **snip** (L0) | 消息数 > `MAX_MESSAGES` (默认 50) | `find_safe_cut_point` 切中间段 → 插入占位消息 | 否 | HEAD_KEEP=3, tail_keep=47 |
| **micro** (L1) | L0 后仍超 `token_soft_limit` | 工具结果 → `[Previous: used {tool_name}]` | 否 | keep_recent=8 |
| **auto** (L2) | L1 后仍超限 | LLM 生成中文摘要替换历史 | 是 | 摘要 ≤500 字 |
| **aggressive_micro** (L3) | L2 后仍超限 | 同 L1 但仅保留最近 2 条工具结果 | 否 | keep_recent=2 |
| **identity** (L4) | 压缩后消息 ≤4 条 | 注入 `[身份确认]` 块 | 否 | 天体物理学研究助手身份 |

### 3.2 压缩触发机制 (在 ReAct 循环中)

```mermaid
flowchart TD
    A["estimated_tokens > token_budget.soft_limit?"]
    A --> B["检查熔断器 can_attempt()"]
    B -->|"Closed / HalfOpen"| C["执行 snapshot_compress_restore()"]
    B -->|"Open"| D["跳过，记录警告"]
    C --> E{"messages.len() < before_len ?"}
    E -->|"是"| F["record_success()"]
    E -->|"否"| G["record_failure()"]
```

Token 估算策略：
- 优先使用 API 返回的精确 `prompt_tokens`
- 辅以增量估算：新增消息数 × (content.len() + 4) 字符估算
- 首次无 API 数据时回退到 `rough_estimate_tokens`

### 3.3 手动压缩 (`compress_context` 工具触发)

- LLM 调用 `compress_context` 工具 → 设置 `pending_manual_compress = true`
- 下一轮循环中执行压缩（若刚已自动压缩则跳过）
- 手动压缩不受熔断器限制，成功后重置熔断器

### 3.4 安全切割点 (`find_safe_cut_point`)

确保不破坏 `assistant(tool_calls) ↔ tool_result` 配对的算法：

1. 计算候选切割点 `messages.len() - desired_keep`
2. 若切割点落在 `tool` 消息上 → 向前追溯到对应 `assistant(tool_calls)` 一并保留
3. 向前扫描孤立 `assistant(tool_calls)`（无 tool_result 配对）→ 切点前移

### 3.5 压缩熔断器 (`runtime/circuit_breaker.rs`)

防止无限自动压缩的三态熔断器，创建于 `AgentRuntime::new()`，跨 turn 共享：

```mermaid
stateDiagram-v2
    [*] --> Closed: 初始状态
    Closed --> Closed: record_success() → 重置计数
    Closed --> Open: 连续失败 3 次
    Open --> HalfOpen: 5 分钟后自动恢复
    HalfOpen --> Closed: record_success()
    HalfOpen --> Open: record_failure()
    Closed --> Closed: reset() (手动压缩成功后)
```

| 参数 | 值 | 说明 |
|:---|:---|:---|
| `MAX_CONSECUTIVE_FAILURES` | 3 | 连续失败次数阈值 |
| `AUTO_RECOVERY_TIMEOUT_SECS` | 300 | 熔断后自动尝试恢复的等待时间 |
| 压缩成功判定 | `messages.len() < before_len` | 消息数减少即视为成功 |

### 3.6 递归守卫

`COMPACTING` AtomicBool — 压缩内部触发的 LLM 调用可能再次触发压缩，递归守卫通过 `compare_exchange` 防止嵌套压缩死循环。

---

## 4. 文件缓存与压缩集成 (`runtime/file_cache.rs`)

压缩前后的文件状态保护循环 (`snapshot_compress_restore`)：

```
压缩前
  ├─ FileStateCache.to_snapshot()      → 保存所有已读文件快照（按时间戳降序）
  └─ FileStateCache.clear()            → 清空缓存

压缩后
  ├─ restore_from_snapshot(max=5)      → 恢复最近 5 个文件到 LRU 缓存
  └─ build_restore_context(max=5)      → 生成 "[压缩后恢复: {path}]" 块注入消息
```

| 参数 | 值 | 说明 |
|:---|:---|:---|
| `MAX_ENTRIES` | 100 | 缓存条目上限 |
| `MAX_CACHE_SIZE_BYTES` | 25 MB | 缓存内容总大小上限 |
| `POST_COMPACT_MAX_FILES_TO_RESTORE` | 5 | 压缩后恢复的文件数 |
| `POST_COMPACT_MAX_CHARS_PER_FILE` | 4,000 | 每文件恢复内容上限 |
| `FILE_UNCHANGED_STUB` | 静态字符串 | 文件未变时返回的占位消息 |

LRU 淘汰策略：容量超限时自动驱逐最久未使用的条目。

---

## 5. 错误恢复系统 (`runtime/error_recovery.rs`)

### 5.1 错误分类 (`classify_error`)

| ErrorKind | 检测关键词 |
|:---|:---|
| `RateLimited` | 429, rate limit, rate_limit, too many requests |
| `Overloaded` | 529, overloaded, overload, service overloaded |
| `PromptTooLong` | prompt_too_long, context length, 413, context_window_exceeded, input length |
| `TokenExhausted` | max_tokens, token limit, token_exhausted, maximum context length |
| `Timeout` | timeout, timed out, deadline exceeded, 408, 504 |
| `ModelError` | 默认归类，携带原始错误字符串 |

### 5.2 恢复阶梯

LLM 流式调用失败后的 5 级恢复：

| 步骤 | RecoveryStep | 操作 | 适用错误 |
|:---|:---|:---|:---|
| 1 | `AggressiveCompact` | snip + micro(keep_recent=2) | PromptTooLong, TokenExhausted |
| 2 | `ReactiveCompact` | LLM 摘要压缩 | 同上 |
| 3 | `EscalateTokens` | 提升 hard_limit → 64,000 | 同上 |
| 4 | `MultiTurn` | 注入分步恢复消息 | 同上 |
| 5 | `Surface` | 放弃恢复，暴露错误 | 不可恢复错误（ModelError 直接到此） |

每步有 `has_attempted` 守卫，防止无限循环。

### 5.3 429/529 退避重试（独立快速路径）

RateLimited/Overloaded 不走恢复阶梯，独立执行指数退避重试（最多 10 次）：

- 延迟公式：`min(500 × 2^attempt, 32,000) + deterministic jitter`
- 支持 `retry_after` header 解析
- 529 连续 3 次过载 → 尝试切换到 `FALLBACK_MODEL` 环境变量指定的备用模型
- 重试期间检查用户取消信号

---

## 6. 子代理上下文隔离 (`subagent.rs`)

父代理通过 `delegate_research` 委托子任务给子代理，子代理拥有独立的上下文环境：

| 组件 | 隔离方式 |
|:---|:---|
| 消息上下文 | 全新 `[system_prompt, user_prompt]`，不含父代理中间工具调用 |
| 工具访问 | 共享 ToolRegistry（可配置受限 registry，如仅只读工具） |
| Hook 管道 | 完整的 PreToolUse/PostToolUse + PermissionChecker |
| 进度通知 | 通过 `progress_tx` 向父代理发送 Thought/ToolCall/ToolResult SSE 事件 |
| 最终返回 | 仅返回 `[子代理活动记录] + [子代理结论]` 文本摘要 |
| 消息持久化 | 以 `agent_name=sub_xxx` 写入父会话的 `agent_messages` 表 |

子代理也有独立的上下文压缩（同 `compact::compress_context`）、死循环检测（同 `DuplicateDetector` 逻辑）、强制终止（超 max_steps 时调用 `force_final_answer`）。

---

## 7. 跨会话持久化

### 7.1 数据库表

| 表 | 持久化内容 | 上下文用途 |
|:---|:---|:---|
| `agent_sessions` | session_id, title, model, turn_count, metadata | 会话生命周期管理 |
| `agent_messages` | role, content, thought, tool_calls(JSON), tool_call_id, token_count, metadata, raw_json(完整 ChatMessage), agent_name | 历史恢复 + 审计追溯 |
| `agent_tasks` | task_id, content, status, blocked_by, owner | 跨 turn 任务状态恢复 |
| `agent_audit_log` | session_id, step, tool_name, status, elapsed_ms, output_preview | 完整审计追踪 |

### 7.2 文件系统记忆 (`memory/`)

- Agent 可通过 `save_memory` 工具将重要信息写入 `~/.claude/projects/{project}/memory/`
- 四类记忆：`user`, `feedback`, `project`, `reference`
- 写入时门控：内容质量检查 + Jaccard 相似度去重（70% 阈值）
- 每 turn 结束时 fire-and-forget 自动提取候选记忆
- 下次会话的 system prompt 中自动加载最近 5 条记忆

### 7.3 Trajectory 导出

每 turn 结束时，`TrajectoryExporter::export()` 将完整会话轨迹导出到文件系统，用于调试和审计。

---

## 8. Lifecycle Hooks 与上下文事件

| Hook | 触发时机 | 上下文影响 |
|:---|:---|:---|
| `OnSessionStart` | 会话创建/恢复 | 通知生命周期开始 |
| `UserPromptSubmit` | 用户提交提示词后 | 记录/审计用户输入 (P2) |
| `PreToolUse` | 工具执行前 | 可 MutateInput 注入上下文、Block 阻止 |
| `PostToolUse` | 工具执行后 | 可 MutateOutput 修改结果、审计日志写入 |
| `PostToolUseFailure` | 工具执行失败 | 记录错误信息，可 MutateOutput |
| `OnStepComplete` | 每步结束 | 日志消息数/预算使用率 |
| `OnPreCompact` | 压缩前 | 记录消息数/预估 tokens |
| `OnPostCompact` | 压缩后 | 记录新消息数/压缩方法 |
| `OnSubagentStart` | 子代理启动 | 通知子代理创建 |
| `OnSubagentStop` | 子代理停止 | 记录结果摘要 |
| `PermissionRequest` | 权限请求前 | 可 Override 权限决策 (P1) |
| `PermissionDenied` | 权限被拒绝后 | 安全审计日志 (P1) |
| `OnSessionStop` | 会话终止 | 清理取消状态、记录终止原因 |

---

## 9. SSE 流事件 — 前端上下文同步

Agent 内部上下文通过 SSE 事件实时同步到前端：

```
Session → Thought → (ToolCall ↔ ToolResult)* → TextDelta → Usage → Done
```

`tool_call.id` 贯穿全链路：LLM 生成 ID → 前端精确匹配 tool_call/tool_result 条目 → 审计日志关联。

---

## 10. 环境变量配置

| 变量 | 默认值 | 作用 |
|:---|:---|:---|
| `AGENT_MAX_STEPS` | 8 | ReAct 最大迭代步数 |
| `AGENT_TOOL_TIMEOUT_SECS` | 120 | 工具执行超时（秒） |
| `AGENT_MAX_TOOL_OUTPUT_CHARS` | 4000 | 工具输出截断长度（字符） |
| `AGENT_TOKEN_SOFT_LIMIT` | 32000 | 各压缩层统一触发阈值（token） |
| `AGENT_TOKEN_SOFT_LIMIT` | 32000 | Token 预算软限制（触发 nudging） |
| `AGENT_TOKEN_HARD_LIMIT` | 40000 | Token 预算硬限制（触发强制动作） |
| `AGENT_MAX_MESSAGES` | 50 | snip_compact 触发阈值（消息数） |
| `FALLBACK_MODEL` | — | 529 连续过载 3 次时的备用模型 |

---

## 11. 关键源文件索引

| 文件 | 职责 |
|:---|:---|
| `src/agent/compact.rs` | 五层压缩 + 安全切割 + 递归守卫 + 身份注入 |
| `src/agent/runtime/mod.rs` | ReAct 循环 + 压缩触发 + 后台通知 + todo nag |
| `src/agent/runtime/context.rs` | 初始上下文构建 + 任务状态恢复 |
| `src/agent/runtime/session.rs` | 会话 CRUD + 历史消息加载 |
| `src/agent/runtime/system_prompt.rs` | 模块化 System Prompt 组装 |
| `src/agent/runtime/token_budget.rs` | Token 预算 + 三级 Nudge + Dim Returns |
| `src/agent/runtime/circuit_breaker.rs` | 压缩熔断器 |
| `src/agent/runtime/error_recovery.rs` | 5 级恢复阶梯 + 错误分类 + 退避重试 |
| `src/agent/runtime/file_cache.rs` | 文件状态缓存 + 压缩快照/恢复 |
| `src/agent/runtime/streaming.rs` | 流式响应 + 取消竞速 |
| `src/agent/runtime/executor.rs` | 工具验证 + 并行执行 + Hook 集成 |
| `src/agent/runtime/finalize.rs` | 会话收尾 + 记忆提取 + 轨迹导出 |
| `src/agent/subagent.rs` | 子代理上下文隔离 + 独立 ReAct 循环 |
| `src/agent/background.rs` | 后台任务队列 + 通知注入 |
| `src/agent/hooks/` | 13 个生命周期事件 + 内置 3 Hook + AsyncAgentHook trait |
| `src/agent/skills.rs` | 两层技能加载 + 热重载 + 条件激活 |
| `src/agent/tools/memory.rs` | save_memory 工具 + 写入门控 |