# Agent 缓存系统

本文档描述了使用 DiskCache 实现的 Agent 缓存系统。

## 概述

Agent 缓存系统使用 DiskCache 来持久化缓存 Agent 实例，提供以下功能：

- ✅ **文件持久化**：缓存存储在磁盘上，重启后仍然保留
- ✅ **自动过期**：支持设置过期时间，自动清理过期项
- ✅ **缓存大小限制**：可设置最大缓存大小，自动淘汰旧数据
- ✅ **访问时自动续期**：每次访问时自动延长过期时间
- ✅ **线程安全**：支持多线程并发访问

## 配置

### 环境变量

可以通过以下环境变量配置缓存行为：

- `AGENT_CACHE_DIR`：缓存目录路径（默认：`./projects/agent_cache`）
- `AGENT_CACHE_SIZE_LIMIT`：缓存大小限制，字节（默认：`1073741824` = 1GB）
- `AGENT_CACHE_EXPIRE`：默认过期时间，秒（默认：`180` = 3分钟）

示例：
```bash
export AGENT_CACHE_DIR="/var/cache/agent"
export AGENT_CACHE_SIZE_LIMIT="5368709120"  # 5GB
export AGENT_CACHE_EXPIRE="600"  # 10分钟
```

### 代码配置

```python
from agent.agent_cache_manager import AgentCacheManager

# 创建缓存管理器
cache = AgentCacheManager(
    cache_dir="./cache/agent_cache",
    size_limit=1024*1024*1024,  # 1GB
    default_expire=180,  # 3分钟
    eviction_policy="least-recently-used"  # LRU淘汰策略
)
```

## 使用方法

### 1. 缓存 Agent

缓存系统已集成到 `init_agent` 函数中，会自动根据配置生成缓存键并缓存 Agent。

```python
from agent.deep_assistant import init_agent
from agent.agent_config import AgentConfig

# 创建配置
config = AgentConfig(
    bot_id="your-bot-id",
    session_id="user-session-123",
    # ... 其他配置
)

# 初始化 Agent（会自动使用缓存）
agent = await init_agent(config)
```

### 2. 手动使用缓存

如果需要在其他地方使用缓存：

```python
from agent.agent_cache_manager import get_cache_manager

# 获取全局缓存管理器
cache = get_cache_manager()

# 设置缓存
cache.set("my-key", {"data": "value"}, expire=300)  # 5分钟过期

# 获取缓存
value = cache.get("my-key")
if value is not None:
    print("缓存命中！")
else:
    print("缓存未命中")

# 删除缓存
cache.delete("my-key")

# 获取统计信息
stats = cache.get_stats()
print(f"缓存大小: {stats['size_mb']} MB")
print(f"缓存项数: {stats['total_items']}")
```

## 缓存管理工具

项目提供了缓存管理脚本：

```bash
# 查看缓存统计
poetry run python scripts/cache_manager.py stats

# 清理过期项
poetry run python scripts/cache_manager.py expired

# 清理超过1小时的项
poetry run python scripts/cache_manager.py cleanup --max-age 3600

# 清空所有缓存
poetry run python scripts/cache_manager.py clear

# 列出缓存键
poetry run python scripts/cache_manager.py list

# 删除特定缓存键
poetry run python scripts/cache_manager.py delete my-cache-key
```

## 缓存键生成

缓存键基于以下配置生成唯一哈希值：

- `bot_id`
- `system_prompt`
- `mcp_settings`
- `model_name`
- `language`
- `generate_cfg`
- `enable_thinking`
- `user_identifier`
- `session_id`

如果 `session_id` 为 None，则不使用缓存。

## 注意事项

1. **性能考虑**：
   - 缓存存储在磁盘上，首次访问会有 I/O 开销
   - 建议使用 SSD 存储缓存以提高性能
   - 过期时间不宜设置过短，避免频繁重新创建 Agent

2. **内存管理**：
   - Agent 对象可能占用较大内存
   - 设置合理的缓存大小限制
   - 定期清理不用的缓存项

3. **并发安全**：
   - DiskCache 支持多进程并发访问
   - 但在高并发场景下可能成为瓶颈

4. **调试**：
   - 查看日志中的缓存相关信息
   - 使用 `stats` 命令监控缓存使用情况
   - 必要时清空缓存重置状态

## 故障排查

### 缓存不生效

1. 检查 `session_id` 是否设置（必须有 session_id 才会使用缓存）
2. 检查缓存目录是否存在且有写权限
3. 查看日志中是否有缓存相关错误

### 缓存过多

1. 检查缓存大小限制设置
2. 使用 `cleanup` 命令清理旧缓存
3. 调整默认过期时间

### 性能问题

1. 监控缓存命中率
2. 考虑增加缓存大小
3. 优化 Agent 创建速度

## 示例输出

```
INFO: Using cached agent for session: user-123, cache_key: agent_cache_a1b2c3d4
INFO: Cache stats - Total items: 5, Size: 256.78 MB
INFO: Cached agent for session: user-456, cache_key: agent_cache_e5f6g7h8
```