---
status: active
date: 2026-06-05
origin: docs/brainstorms/2026-06-05-agentkit-architecture-gap-analysis-requirements.md
---

# AgentKit v2 Phase 2: 架构完善实施计划

**类型**: refactor  
**文件**: `docs/plans/2026-06-05-006-refactor-agentkit-v2-phase2-plan.md`  
**深度**: Deep — 跨模块改造，涉及安全、异步、流式、进化 4 个层面

---

## 问题框架

AgentKit v2 Phase 1 已实现 12 个核心模块、535 个测试通过，但存在 4 个关键缺口使其无法被称为"生产就绪的标准 Agent 框架"：

1. **服务化安全缺失** — 无认证、无限流、CORS 配置不当、SSRF 风险
2. **异步任务占位符** — 任务状态查询返回 placeholder，同步阻塞调用
3. **流式输出不支持** — 长时间 ReAct 循环无中间进展反馈
4. **Evolution 未集成** — 自我进化代码完整但未接入 Agent 生命周期

本计划按 **B → D → C → A** 顺序补齐这 4 个缺口。（需求来源见 origin 文档）

---

## 架构总览

```
                    +------------------------+
                    |    User / Consumer     |
                    +-----------+------------+
                                |
                    +-----------v------------+
                    |   AgentKit Server      |
                    |   [Auth + Rate Limit]  |  ← Phase B 新增
                    +-----------+------------+
                                |
                    +-----------v------------+
                    |   Task Manager         |
                    |   [Async + Streaming]  |  ← Phase D + C 新增
                    +-----------+------------+
                                |
          +----------+----------+----------+----------+
          |          |          |          |          |
   +------v---+ +---v----+ +---v----+ +---v----+     |
   | ReAct    | | Skill  | |Quality | | Intent |     |
   | [Stream] | | System | | Gate   | | Router |     |
   +----+-----+ +--------+ +--------+ +--------+     |
        |                                          |
   +----v------------------------------------------v----+
   |              ConfigDrivenAgent / BaseAgent          |
   |              [+ Evolution Hooks]                     |  ← Phase A 新增
   +------+---------+---------+---------+---------+------+
          |          |         |         |         |
   +------v---+ +---v----+ +---v----+ +---v----+ +---v----+
   | LLM      | | Tool   | | Memory | | MCP    | |Pipeline|
   | [Stream] | | System | | System | | Bridge | |Engine  |
   +----------+ +--------+ +--------+ +--------+ +--------+
```

---

## 关键技术决策（复用 origin 文档 KTD1-KTD5）

| 决策 | 选择 | 理由 |
|------|------|------|
| 认证方案 | API Key（非 JWT/OAuth） | 服务间调用，API Key 足够简单有效 |
| 速率限制 | 内存计数器（非 Redis） | 单实例足够，后续可升级 |
| 异步存储 | Redis + 内存降级 | 已有 Redis 依赖 |
| 流式协议 | SSE（非 WebSocket） | 单向推送足够，HTTP 兼容性好 |
| Evolution | 可选集成 | 通过 YAML `evolution.enabled` 控制 |

---

## 高层次技术设计

### 中间件链（Phase B）

```
Request → CORS Middleware → API Key Auth → Rate Limiter → Route Handler
                                          ↓ 401          ↓ 429
                                    Unauthorized     Too Many Requests
```

### 异步任务流（Phase D）

```
POST /tasks → 生成 task_id → 存入 TaskStore(PENDING)
                          → 后台 asyncio.create_task() 执行
                          → 更新 TaskStore(RUNNING → COMPLETED/FAILED)
                          → 返回 {"task_id": "...", "status": "PENDING"}

GET /tasks/{id} → 查询 TaskStore → 返回真实状态
GET /tasks/{id}/result → 查询 TaskStore → 返回结果或 404
```

### 流式输出流（Phase C）

```
POST /tasks/stream → SSE endpoint
                  → 后台执行任务
                  → 每步发出事件:
                    event: step
                    data: {"type": "think|act|observe", "step": 1, "content": "..."}
                  → 完成时发出:
                    event: done
                    data: {"status": "completed", "output": {...}}
```

### Evolution 生命周期钩子（Phase A）

```
BaseAgent.execute():
  on_task_start()
  handle_task()
  quality_gate → retry
  on_task_complete()
  └─→ [NEW] evolve_after_task()  ← EvolutionMixin
        └─→ Reflector.reflect()
        └─→ PromptOptimizer.optimize() [if suggestions]
        └─→ ABTester.evaluate() [if optimized]
        └─→ EvolutionStore.apply/rollback()
```

---

## 输出结构

```
src/agentkit/
├── server/
│   ├── middleware.py           # NEW: Auth + Rate Limit 中间件
│   ├── task_store.py           # NEW: 任务状态存储
│   ├── routes/
│   │   └── streaming.py       # NEW: SSE 流式端点
│   ├── app.py                 # MODIFIED: 注册中间件
│   ├── client.py              # MODIFIED: 添加流式 + 异步方法
│   └── routes/
│       └── tasks.py           # MODIFIED: 异步任务 + 状态查询
├── core/
│   ├── base.py                # MODIFIED: 集成 Evolution
│   ├── dispatcher.py          # MODIFIED: Callback URL 验证
│   ├── config_driven.py       # MODIFIED: handler 白名单 + evolution 配置
│   └── protocol.py            # MODIFIED: 新增 TaskState 枚举
├── llm/
│   ├── gateway.py             # MODIFIED: 新增 stream() 方法
│   └── providers/
│       └── openai.py          # MODIFIED: 支持 stream=True
├── skills/
│   └── base.py                # MODIFIED: 添加 evolution 配置
├── core/
│   └── react.py               # MODIFIED: 新增 execute_streaming()
└── evolution/                  # 现有代码，无需修改
```

---

## Implementation Units

### U1. CORS 修复 + API Key 认证中间件

**Goal**: 修复 CORS 配置冲突，添加 API Key 认证保护所有 API 端点（健康检查除外）。

**Requirements**: R1, R3

**Dependencies**: 无

**Files**:
- **Create**: `src/agentkit/server/middleware.py`
- **Modify**: `src/agentkit/server/app.py`
- **Test**: `tests/unit/test_server_middleware.py`

**Approach**:
1. 新建 `middleware.py`，实现 `APIKeyAuthMiddleware` 类（Starlette middleware 接口）
2. 从环境变量 `AGENTKIT_API_KEY` 读取密钥，未设置时跳过认证（开发模式）
3. 验证 `X-API-Key` 请求头，不匹配时返回 401
4. 白名单路径：`/api/v1/health` 不需要认证
5. 修改 `app.py`：
   - 移除 `allow_credentials=True`（与 `allow_origins=["*"]` 冲突）
   - 添加 `app.add_middleware(APIKeyAuthMiddleware)`
6. 在 `create_app()` 中添加 `api_key: str | None = None` 参数，允许程序化配置

**Patterns to follow**: Starlette `BaseHTTPMiddleware` 模式，参考 FastAPI 中间件文档

**Test scenarios**:
- 无 API Key 访问受保护端点 → 401 Unauthorized
- 错误 API Key → 401 Unauthorized
- 正确 API Key → 200 OK
- 健康检查端点无需 API Key → 200 OK
- AGENTKIT_API_KEY 未设置时 → 跳过认证（开发模式）
- 程序化传入 api_key 参数 → 使用传入的值

**Verification**: `pytest tests/unit/test_server_middleware.py -v` 全部通过，现有测试不受影响

---

### U2. 速率限制中间件

**Goal**: 添加基于固定窗口的速率限制，防止 LLM 成本耗尽。

**Requirements**: R2

**Dependencies**: U1（中间件基础设施）

**Files**:
- **Modify**: `src/agentkit/server/middleware.py`
- **Test**: `tests/unit/test_server_middleware.py`（追加）

**Approach**:
1. 在 `middleware.py` 中实现 `RateLimiter` 类
2. 使用 `time.time()` + `defaultdict(list)` 实现固定窗口计数器
3. 默认限制：60 requests/minute，通过环境变量 `AGENTKIT_RATE_LIMIT_PER_MINUTE` 配置
4. 基于请求 IP（`request.client.host`）或 API Key 进行独立计数
5. 超过限制时返回 429 Too Many Requests，响应头包含 `Retry-After`
6. 在 `app.py` 中注册速率限制中间件（在 Auth 之后）

**Test scenarios**:
- 请求在限制内 → 正常通过
- 超过限制 → 429 Too Many Requests
- `Retry-After` 响应头正确设置
- 不同 IP 独立计数
- 时间窗口过后计数器重置
- 可配置 rate_limit_per_minute

**Verification**: 新增测试通过，不影响现有路由测试

---

### U3. Callback URL SSRF 防护

**Goal**: 验证 TaskDispatcher 的 callback URL，防止 SSRF 攻击。

**Requirements**: R4

**Dependencies**: 无

**Files**:
- **Modify**: `src/agentkit/core/dispatcher.py`
- **Test**: `tests/unit/test_dispatcher.py`（追加）

**Approach**:
1. 在 `dispatcher.py` 中添加 `_validate_callback_url(url: str) -> bool` 函数
2. 使用 `urllib.parse.urlparse` 解析 URL
3. 校验规则：
   - 协议必须是 `http` 或 `https`
   - 主机不能是内网 IP（127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, ::1）
   - 主机不能是 `localhost`
4. 在 `_trigger_callback()` 中调用验证，无效 URL 记录 warning 并跳过
5. 对 `socket.gethostbyname()` 做 try/except 防止 DNS 解析失败崩溃

**Test scenarios**:
- 合法公网 URL（如 `https://example.com/callback`）→ 验证通过
- localhost URL → 拒绝
- 127.0.0.1 URL → 拒绝
- 10.x.x.x 内网 URL → 拒绝
- 192.168.x.x 内网 URL → 拒绝
- ftp:// 协议 → 拒绝
- file:// 协议 → 拒绝
- 无效 URL 格式 → 拒绝

**Verification**: 新增测试通过，现有 dispatcher 测试不受影响

---

### U4. custom_handler 模块前缀白名单

**Goal**: 为 `ConfigDrivenAgent._import_handler()` 添加模块前缀白名单，防止任意代码执行。

**Requirements**: R4（安全加固补充）

**Dependencies**: 无

**Files**:
- **Modify**: `src/agentkit/core/config_driven.py`
- **Test**: `tests/unit/test_config_driven.py`（追加）

**Approach**:
1. 在 `ConfigDrivenAgent` 类中添加 `_ALLOWED_HANDLER_PREFIXES = ("agentkit.", "app.agent_framework.")`
2. 在 `_import_handler()` 开头添加前缀校验
3. 不在白名单中的路径抛出 `ConfigValidationError`
4. 参考 `QualityGate._import_validator()` 的白名单实现模式

**Test scenarios**:
- `agentkit.xxx.handler` → 允许
- `app.agent_framework.handlers.xxx` → 允许
- `os.system` → 拒绝（ConfigValidationError）
- `subprocess.run` → 拒绝
- 空路径 → 拒绝

**Verification**: 新增测试通过

---

### U5. 任务状态存储

**Goal**: 实现任务状态存储，支持 Redis 和内存两种后端。

**Requirements**: R5, R7

**Dependencies**: 无

**Files**:
- **Create**: `src/agentkit/server/task_store.py`
- **Test**: `tests/unit/test_task_store.py`

**Approach**:
1. 定义 `TaskState` 枚举：`PENDING`, `RUNNING`, `COMPLETED`, `FAILED`
2. 定义 `TaskRecord` dataclass：`task_id`, `state`, `input_data`, `output_data`, `error_message`, `created_at`, `updated_at`, `started_at`
3. 定义 `TaskStore` ABC：`create()`, `update()`, `get()`, `list_tasks()`, `cleanup()`
4. 实现 `InMemoryTaskStore`：使用 `dict` + `asyncio.Lock` 保证线程安全
5. 实现 `RedisTaskStore`：使用 Redis hash 存储，TTL 24 小时自动清理
6. 提供 `create_task_store(redis_url: str | None = None) -> TaskStore` 工厂函数
7. Redis 不可用时自动降级到 InMemory

**Patterns to follow**: 参考 `WorkingMemory` 的 Redis 模式和 `UsageTracker` 的内存模式

**Test scenarios**:
- InMemoryTaskStore: create → get 返回正确记录
- InMemoryTaskStore: update 状态从 PENDING → RUNNING → COMPLETED
- InMemoryTaskStore: get 不存在的 task_id 返回 None
- InMemoryTaskStore: list_tasks 返回所有记录
- InMemoryTaskStore: 并发安全（asyncio.Lock）
- RedisTaskStore: create → get 返回正确记录（skip if no Redis）
- 工厂函数: Redis 可用时返回 RedisTaskStore
- 工厂函数: Redis 不可用时降级到 InMemoryTaskStore

**Verification**: `pytest tests/unit/test_task_store.py -v` 全部通过

---

### U6. 异步任务执行

**Goal**: `POST /api/v1/tasks` 改为异步提交，100ms 内返回 task_id。

**Requirements**: R5, R6

**Dependencies**: U5

**Files**:
- **Modify**: `src/agentkit/server/routes/tasks.py`
- **Test**: `tests/unit/test_server_routes.py`（更新现有测试）
- **Test**: `tests/integration/test_server_e2e.py`（更新）

**Approach**:
1. 在 `tasks.py` 中注入 `TaskStore`（通过 `req.app.state.task_store`）
2. 在 `app.py` 的 `create_app()` 中初始化 `task_store` 并设置到 `app.state`
3. 修改 `submit_task` 路由：
   - 生成 `task_id`，创建 `TaskRecord(PENDING)` 存入 TaskStore
   - 使用 `asyncio.create_task()` 后台执行任务
   - 立即返回 `{"task_id": task_id, "status": "PENDING"}`
4. 后台任务逻辑：
   - 更新 TaskStore 为 RUNNING
   - 执行 `agent.execute(task)`
   - 更新 TaskStore 为 COMPLETED/FAILED，存储 output_data
   - 运行 quality gate 和 output standardizer（存储结果）
5. 添加可选参数 `sync: bool = False`，当 `sync=true` 时保持原有同步行为

**Test scenarios**:
- 提交任务 → 100ms 内返回 task_id + PENDING
- 后台任务执行 → TaskStore 状态变为 COMPLETED
- 后台任务失败 → TaskStore 状态变为 FAILED
- sync=true 参数 → 同步执行（原有行为）
- 输入验证失败 → 400/413 错误（同步返回）

**Verification**: 路由测试通过，E2E 测试验证异步行为

---

### U7. 任务状态查询 + 结果获取

**Goal**: `GET /api/v1/tasks/{task_id}` 返回真实状态，新增结果获取端点。

**Requirements**: R6, R7

**Dependencies**: U5, U6

**Files**:
- **Modify**: `src/agentkit/server/routes/tasks.py`
- **Test**: `tests/unit/test_server_routes.py`（追加）

**Approach**:
1. 修改 `get_task_status` 路由：
   - 从 TaskStore 查询 task_id
   - 返回 `{"task_id": ..., "status": "...", "created_at": "...", "updated_at": "..."}`
   - 不存在时返回 404
2. 新增 `GET /api/v1/tasks/{task_id}/result` 路由：
   - 从 TaskStore 查询 task_id
   - 如果状态是 COMPLETED → 返回完整结果（含 quality_result, standard_output）
   - 如果状态是 PENDING/RUNNING → 返回 202 Accepted + `{"status": "..."}`
   - 如果状态是 FAILED → 返回错误信息
   - 不存在时返回 404

**Test scenarios**:
- 查询存在的 task_id → 返回正确状态
- 查询不存在的 task_id → 404
- PENDING 状态查询结果 → 202 Accepted
- COMPLETED 状态查询结果 → 返回完整输出
- FAILED 状态查询结果 → 返回错误信息

**Verification**: 路由测试通过

---

### U8. LLM Gateway 流式支持

**Goal**: LLM Gateway 支持 streaming 模式，逐 chunk 返回 LLM 响应。

**Requirements**: R8

**Dependencies**: 无

**Files**:
- **Modify**: `src/agentkit/llm/gateway.py`
- **Modify**: `src/agentkit/llm/protocol.py`
- **Modify**: `src/agentkit/llm/providers/openai.py`
- **Test**: `tests/unit/test_llm_gateway.py`（追加）
- **Test**: `tests/unit/test_llm_provider.py`（追加）

**Approach**:
1. 在 `protocol.py` 中添加 `LLMStreamChunk` dataclass：
   - `content: str`（增量文本）
   - `tool_calls: list[ToolCall] | None`
   - `finish_reason: str | None`（`stop`, `tool_calls`, `length`）
   - `usage: TokenUsage | None`（仅在最后一个 chunk 有值）
2. 在 `LLMProvider` ABC 中添加 `stream()` 抽象方法：
   - `async def stream(request: LLMRequest) -> AsyncIterator[LLMStreamChunk]`
3. 在 `OpenAICompatibleProvider` 中实现 `stream()`：
   - 使用 `httpx.AsyncClient.stream()` 发送请求
   - 解析 SSE 格式响应（`data: {...}` 行）
   - yield `LLMStreamChunk` 对象
4. 在 `LLMGateway` 中添加 `stream()` 方法：
   - 解析模型别名和 provider
   - 调用 provider 的 `stream()` 方法
   - 转发 chunk

**Patterns to follow**: OpenAI Python SDK 的 streaming 模式，`response.iter_lines()` 解析 SSE

**Test scenarios**:
- OpenAICompatibleProvider.stream() 逐 chunk yield 内容
- 最后一个 chunk 包含 usage 信息
- finish_reason 为 stop 时流结束
- finish_reason 为 tool_calls 时包含 tool_calls 信息
- LLMGateway.stream() 正确转发 chunk
- 网络错误时抛出 LLMProviderError

**Verification**: 新增流式测试通过

---

### U9. ReAct Engine 事件流

**Goal**: ReAct Engine 支持 streaming 事件输出，实时推送 Think/Act/Observe 进展。

**Requirements**: R9

**Dependencies**: U8

**Files**:
- **Modify**: `src/agentkit/core/react.py`
- **Modify**: `src/agentkit/core/protocol.py`
- **Test**: `tests/unit/test_react_engine.py`（追加）

**Approach**:
1. 在 `protocol.py` 中添加 `ReActEvent` dataclass：
   - `event_type: str`（`think_start`, `think_end`, `tool_call`, `tool_result`, `final_answer`）
   - `step: int`
   - `data: dict`（事件具体数据）
   - `timestamp: datetime`
2. 在 `ReActEngine` 中添加 `execute_streaming()` 方法：
   - 参数与 `execute()` 相同，返回 `AsyncIterator[ReActEvent]`
   - Think 前 yield `think_start` 事件
   - 调用 LLM stream 后 yield `think_end` 事件
   - 每个工具调用 yield `tool_call` 事件
   - 工具执行完成后 yield `tool_result` 事件
   - 最终答案 yield `final_answer` 事件
3. 保持原有 `execute()` 方法不变（向后兼容）

**Test scenarios**:
- execute_streaming() 按顺序 yield 事件
- Think → Act → Observe 事件顺序正确
- 最终 yield final_answer 事件
- 事件中包含 step 编号和 timestamp
- 工具调用失败时 yield tool_result（含 error）
- 与 execute() 结果一致（同一输入产生相同输出）

**Verification**: 新增流式测试通过

---

### U10. SSE 流式端点 + Client SDK

**Goal**: Server 提供 SSE 流式端点，Client SDK 支持流式消费。

**Requirements**: R10

**Dependencies**: U8, U9

**Files**:
- **Create**: `src/agentkit/server/routes/streaming.py`
- **Modify**: `src/agentkit/server/app.py`
- **Modify**: `src/agentkit/server/client.py`
- **Test**: `tests/unit/test_streaming_routes.py`
- **Test**: `tests/unit/test_client_streaming.py`

**Approach**:
1. 新建 `streaming.py`，实现 `POST /api/v1/tasks/stream` 端点：
   - 使用 `StreamingResponse` + `text/event-stream` content type
   - 后台执行任务，调用 `react_engine.execute_streaming()`
   - 每个 `ReActEvent` 序列化为 SSE 格式：`event: <type>\ndata: <json>\n\n`
   - 完成后发送 `event: done\ndata: <json>\n\n`
2. 在 `app.py` 中注册 streaming router
3. 在 `client.py` 中添加 `submit_task_streaming()` 方法：
   - 使用 `httpx.AsyncClient.stream()` 消费 SSE
   - yield `ReActEvent` 对象
   - 支持 async iterator 协议

**Patterns to follow**: Starlette `EventSourceResponse` 或 `StreamingResponse`，参考 FastAPI SSE 文档

**Test scenarios**:
- SSE 端点返回 text/event-stream content type
- 事件按 Think → Act → Observe → done 顺序
- 每个事件包含正确的 event type 和 JSON data
- Client SDK 消费 SSE 流
- Client SDK 正确解析 ReActEvent
- 任务失败时发送 error 事件

**Verification**: 流式路由和客户端测试通过

---

### U11. Evolution 生命周期钩子集成

**Goal**: 将 EvolutionMixin 集成到 BaseAgent，任务完成后自动触发进化流程。

**Requirements**: R11

**Dependencies**: 无

**Files**:
- **Modify**: `src/agentkit/core/base.py`
- **Modify**: `src/agentkit/evolution/lifecycle.py`
- **Test**: `tests/unit/test_evolution_lifecycle.py`（更新）
- **Test**: `tests/unit/test_base_agent_v2.py`（追加）

**Approach**:
1. 在 `BaseAgent` 中添加 Evolution 相关属性：
   - `_reflector: Reflector | None`
   - `_prompt_optimizer: PromptOptimizer | None`
   - `_ab_tester: ABTester | None`
   - `_evolution_store: EvolutionStore | None`
   - `_evolution_enabled: bool = False`
2. 在 `BaseAgent` 中添加 `use_evolution()` 方法：
   - 接受 `reflector`, `prompt_optimizer`, `ab_tester`, `evolution_store` 参数
   - 设置所有 Evolution 组件
   - 设置 `_evolution_enabled = True`
3. 修改 `BaseAgent.execute()` 方法：
   - 在 `on_task_complete()` 之后，如果 `_evolution_enabled` 为 True：
     - 调用 `EvolutionMixin.evolve_after_task(task, result)`（非阻塞，`asyncio.create_task()`）
4. 在 `EvolutionMixin.evolve_after_task()` 中添加开关检查：
   - 如果任何组件为 None，跳过对应步骤并记录 debug 日志

**Patterns to follow**: 参考 `use_tool()`, `use_memory()` 的插件注入模式

**Test scenarios**:
- evolution_enabled=False → 不触发进化流程
- evolution_enabled=True → evolve_after_task 被调用
- Reflector 为 None → 跳过反思
- 完整流程：Reflect → Optimize → AB Test → Apply
- 进化流程非阻塞（不阻塞 execute 返回）
- EvolutionMixin 混入 ConfigDrivenAgent 正常工作

**Verification**: Evolution 集成测试通过，现有测试不受影响

---

### U12. Evolution 配置化

**Goal**: Agent 可通过 YAML 配置启用/禁用 Evolution 功能。

**Requirements**: R12

**Dependencies**: U11

**Files**:
- **Modify**: `src/agentkit/core/config_driven.py`
- **Modify**: `src/agentkit/skills/base.py`
- **Test**: `tests/unit/test_config_driven.py`（追加）
- **Test**: `tests/unit/test_skill_config.py`（追加）

**Approach**:
1. 在 `AgentConfig` 中添加 `evolution: dict[str, Any] | None` 字段
2. 定义 `EvolutionConfig` dataclass：
   - `enabled: bool = False`
   - `reflect_after_task: bool = True`
   - `ab_test_threshold: float = 0.95`
   - `max_optimization_rounds: int = 3`
3. 在 `SkillConfig` 中继承 evolution 配置
4. 修改 `ConfigDrivenAgent.__init__()`：
   - 从 config.evolution 解析 EvolutionConfig
   - 如果 `evolution.enabled = True`，自动创建默认组件并调用 `use_evolution()`
   - 默认组件：Reflector（启发式评分）、PromptOptimizer、ABTester、EvolutionStore（内存模式）
5. YAML 配置示例文档化

**Test scenarios**:
- YAML 中 evolution.enabled=true → Agent 自动启用进化
- YAML 中 evolution.enabled=false → Agent 不启用进化
- YAML 中无 evolution 字段 → 默认不启用
- EvolutionConfig 字段默认值正确
- SkillConfig 继承 evolution 配置

**Verification**: 配置化测试通过

---

## 范围和边界

### 包含

- Phase B：服务化安全（R1-R4）→ U1-U4
- Phase D：异步任务（R5-R7）→ U5-U7
- Phase C：流式输出（R8-R10）→ U8-U10
- Phase A：Evolution 集成（R11-R12）→ U11-U12

### 不包含

- GEO 项目的任何改动
- 新的 LLM Provider 实现
- 前端 UI 开发
- 生产环境部署配置（K8s、Prometheus 等）
- pgvector 向量检索实现

### 推迟到后续工作

- WebSocket 推送（当前使用 SSE）
- Redis 滑动窗口速率限制（当前使用内存计数器）
- Anthropic/Google 原生 Provider
- Evolution 的分布式 A/B 测试
- 任务优先级队列

---

## 风险和缓解

| 风险 | 影响 | 缓解 |
|------|------|------|
| 流式输出改动大 | ReAct Engine 需要重构 | 保持原有同步接口不变，新增 streaming 接口 |
| 异步任务需要 Redis | 测试环境可能没有 Redis | InMemoryTaskStore 降级方案 |
| API Key 认证破坏现有测试 | 测试需要传递 API Key | 测试环境不设置 AGENTKIT_API_KEY（跳过认证） |
| Evolution 集成后 Agent 变慢 | 反思和优化增加延迟 | 异步执行（asyncio.create_task），可配置关闭 |
| SSE 端点与现有同步端点冲突 | 路由冲突 | 使用不同路径 `/tasks/stream` |

---

## 测试策略

- **TDD 原则**：每个单元先写测试，再写实现
- **测试覆盖目标**：总测试数 600+（当前 535）
- **分层测试**：
  - 单元测试：mock 外部依赖，验证逻辑
  - 集成测试：使用真实 Redis/PostgreSQL（docker-compose.test.yml）
  - E2E 测试：验证完整链路
- **回归保护**：每次修改后运行全量测试

---

## 执行顺序

```
Phase B（安全）              Phase D（异步任务）           Phase C（流式输出）           Phase A（Evolution）
┌─────┐                    ┌─────┐                      ┌─────┐                      ┌─────┐
│ U1  │                    │ U5  │                      │ U8  │                      │ U11 │
│ Auth│                    │Store│                      │LLM  │                      │Hooks│
└──┬──┘                    └──┬──┘                      └──┬──┘                      └──┬──┘
   │                         └──┬──┘                      └──┬──┘                      └──┬──┘
┌──▼──┐                       ┌▼────┐                     ┌─▼───┐                     ┌──▼──┐
│ U2  │                       │ U6  │                     │ U9  │                     │ U12 │
│Rate │                       │Async│                     │React│                     │Config│
└─────┘                       └──┬──┘                     └──┬──┘                     └─────┘
                                 └──┬──┘                     └──┬──┘
                               ┌────▼────┐                 ┌───▼────┐
                               │ U7      │                 │ U10    │
                               │Status   │                 │SSE+SDK │
                               └─────────┘                 └────────┘

可并行：U3 + U4（无依赖，可与任何单元并行）
```
