# AgentKit 架构完善需求文档

**Created:** 2026-06-05
**Status:** active
**Topic:** agentkit-architecture-gap-analysis
**Type:** feature

---

## 问题框架

当前 AgentKit 已实现 12 个核心模块、37 个源文件、6,470 行代码、535 个测试通过。但存在 4 个关键缺口，如果不补齐，框架不能称为"生产就绪的标准 Agent 开发架构"。

**目标**：将 AgentKit 从"功能完整但缺少生产级特性"提升为"可直接用于生产的标准 Agent 框架"。

---

## 当前架构状态

### 已完整实现（10 个模块）

| 模块 | 核心能力 | 测试覆盖 |
|------|---------|---------|
| **BaseAgent** | 生命周期、状态机、并发控制、钩子 | ✅ |
| **ConfigDrivenAgent** | 4 种任务模式（react/llm/tool/custom） | ✅ |
| **ReAct Engine** | Think-Act-Observe 循环、Function Calling、文本解析 | ✅ |
| **LLM Gateway** | Provider 注册、模型路由、Fallback 链、用量追踪 | ✅ |
| **Skill System** | SkillConfig、SkillRegistry、SkillLoader、向后兼容 | ✅ |
| **Intent Router** | 关键词匹配 + LLM 分类两级路由 | ✅ |
| **Quality Gate** | 4 维度检查（必填/字数/Schema/自定义）+ 自动重试 | ✅ |
| **Output Standardizer** | Schema 验证 + 类型归一化 + 元数据 | ✅ |
| **Tool System** | FunctionTool、AgentTool、MCPTool、组合模式 | ✅ |
| **MCP** | Server + Transport（HTTP/SSE）+ Client | ✅ |
| **Orchestrator** | PipelineEngine（DAG + 并行）+ HandoffManager | ✅ |
| **Server** | FastAPI + REST API + Python SDK + AgentPool | ✅ |

### 存在缺口（4 个）

| 缺口 | 当前状态 | 缺失内容 | 严重度 |
|------|---------|---------|--------|
| **A. Evolution 集成** | 代码完整，未集成 | Reflector/PromptOptimizer/ABTester 未接入 Agent 生命周期 | 中 |
| **B. 服务化安全** | 无认证无限流 | API Key 认证 + 速率限制 + CORS 修复 + SSRF 防护 | 高 |
| **C. 流式输出** | 不支持 | SSE streaming + ReAct 事件流 + 客户端流式消费 | 中 |
| **D. 异步任务** | Placeholder | 异步执行 + 状态轮询 + WebSocket 推送 | 高 |

### 已知小问题

| 问题 | 位置 | 状态 |
|------|------|------|
| pgvector 向量检索未实现 | `episodic.py:99` | 降级方案可用（时间衰减） |
| custom_handler 缺少白名单 | `config_driven.py` | 已在 Phase 1 审查中标识 |
| CORS 配置不当 | `server/app.py` | `allow_origins=["*"]` + `allow_credentials=True` 冲突 |

---

## 需求

### R1. API Key 认证
所有 Server API 端点（除健康检查外）必须验证 API Key。通过 `X-API-Key` 请求头传递，密钥从环境变量 `AGENTKIT_API_KEY` 读取。

### R2. 速率限制
Server 必须限制请求频率，防止 LLM 成本耗尽。默认每分钟 60 次请求（可配置），超过时返回 429 Too Many Requests。

### R3. CORS 修复
修复 `allow_origins=["*"]` + `allow_credentials=True` 冲突。生产环境应限制具体域名。

### R4. Callback URL SSRF 防护
TaskDispatcher 的 callback URL 必须验证：只允许 http/https 协议，拒绝内网 IP。

### R5. 异步任务执行
`POST /api/v1/tasks` 必须支持异步模式：提交后返回 task_id，后台执行任务。

### R6. 任务状态追踪
`GET /api/v1/tasks/{task_id}` 必须返回真实状态：PENDING / RUNNING / COMPLETED / FAILED。

### R7. 任务结果存储
异步任务的结果必须存储（Redis 或内存），供状态查询和结果获取。

### R8. LLM 流式输出
LLM Gateway 必须支持 streaming 模式，逐 chunk 返回 LLM 响应。

### R9. ReAct 事件流
ReAct Engine 必须支持 streaming 事件输出，让用户实时看到 Think/Act/Observe 进展。

### R10. SSE 流式端点
Server 必须提供 SSE 端点（`/api/v1/tasks/stream`），支持长时间任务的实时进展推送。

### R11. Evolution 集成到 Agent 生命周期
BaseAgent 必须在 `on_task_complete()` 后自动调用 Reflector 反思，触发 PromptOptimizer 和 ABTester。

### R12. Evolution 配置化
Agent 应可通过 YAML 配置启用/禁用 Evolution 功能（`evolution: { enabled: true, reflect_after_task: true }`）。

---

## 成功标准

1. **安全**：无 API Key 的请求返回 401，超过速率限制返回 429
2. **异步**：提交任务后 100ms 内返回 task_id，后台异步执行
3. **流式**：ReAct 循环的每个 step（Think/Act/Observe）实时推送给客户端
4. **进化**：Agent 完成任务后自动生成反思记录，可触发 Prompt 优化
5. **测试**：所有新增功能有对应测试，总测试数 600+

---

## 范围边界

**本需求包含**：
- B：服务化安全（R1-R4）
- D：异步任务（R5-R7）
- C：流式输出（R8-R10）
- A：Evolution 集成（R11-R12）

**本需求不包含**：
- GEO 项目的任何改动
- 新的 LLM Provider 实现（如 Anthropic SDK 原生支持）
- 前端 UI 开发
- 生产环境部署配置（K8s、Prometheus 监控等）
- pgvector 向量检索实现（已有降级方案）

---

## 关键决策

### KTD1：认证采用 API Key 方案（非 JWT/OAuth）
**理由**：AgentKit Server 是内部服务间调用场景，API Key 足够简单有效。JWT/OAuth 增加复杂度但无明显收益。

### KTD2：速率限制采用内存计数器（非 Redis）
**理由**：单实例部署下内存计数器足够。多实例场景后续可升级为 Redis 滑动窗口。

### KTD3：异步任务使用 Redis 存储状态
**理由**：AgentKit 已有 Redis 依赖（WorkingMemory），复用最简单。内存模式作为降级方案。

### KTD4：流式输出使用 SSE（非 WebSocket）
**理由**：SSE 单向推送足够（服务端 → 客户端），实现比 WebSocket 简单，HTTP 兼容性好。

### KTD5：Evolution 采用可选集成
**理由**：不是所有场景都需要自我进化。通过 YAML 配置 `evolution.enabled: false` 可关闭。

---

## 实现顺序

```
Phase B（安全） → Phase D（异步任务） → Phase C（流式输出） → Phase A（Evolution）
```

### Phase B：服务化安全（4 个实施单元）

#### U1. CORS 修复 + API Key 认证中间件
- 修改 `src/agentkit/server/app.py`
- 新建 `src/agentkit/server/middleware.py`
- 实现 `APIKeyAuthMiddleware`

#### U2. 速率限制中间件
- 添加到 `src/agentkit/server/middleware.py`
- 实现 `RateLimiter`（固定窗口计数器）
- 可配置：`rate_limit_per_minute`

#### U3. Callback URL SSRF 防护
- 修改 `src/agentkit/core/dispatcher.py`
- 实现 `_validate_callback_url()` 函数

#### U4. custom_handler 模块前缀白名单
- 修改 `src/agentkit/core/config_driven.py`
- 添加 `_ALLOWED_HANDLER_PREFIXES` 白名单

### Phase D：异步任务（3 个实施单元）

#### U5. 任务状态存储
- 新建 `src/agentkit/server/task_store.py`
- 支持 Redis 和内存两种后端
- TaskState: PENDING / RUNNING / COMPLETED / FAILED

#### U6. 异步任务执行
- 修改 `src/agentkit/server/routes/tasks.py`
- `POST /api/v1/tasks` 改为异步提交
- 返回 `{"task_id": "...", "status": "PENDING"}`

#### U7. 状态查询 + 结果获取
- 修改 `GET /api/v1/tasks/{task_id}` 返回真实状态
- 新增 `GET /api/v1/tasks/{task_id}/result` 获取结果

### Phase C：流式输出（3 个实施单元）

#### U8. LLM Gateway 流式支持
- 修改 `src/agentkit/llm/gateway.py`
- 新增 `stream()` 方法，SSE chunk-by-chunk
- 修改 `OpenAICompatibleProvider` 支持 `stream=True`

#### U9. ReAct Engine 事件流
- 修改 `src/agentkit/core/react.py`
- 新增 `execute_streaming()` 方法
- 每个 Think/Act/Observe step 发出事件

#### U10. SSE 流式端点
- 新增 `src/agentkit/server/routes/streaming.py`
- `POST /api/v1/tasks/stream` SSE 端点
- Client SDK 支持流式消费

### Phase A：Evolution 集成（2 个实施单元）

#### U11. Evolution 生命周期钩子
- 修改 `src/agentkit/core/base.py`
- `on_task_complete()` 后自动调用 Reflector
- 通过 EvolutionMixin 集成

#### U12. Evolution 配置化
- 修改 `AgentConfig` 添加 `evolution` 字段
- 修改 `SkillConfig` 继承 evolution 配置
- YAML 配置示例

---

## 风险与缓解

| 风险 | 影响 | 缓解 |
|------|------|------|
| 流式输出改动大 | ReAct Engine 需要重构 | 保持原有同步接口不变，新增 streaming 接口 |
| 异步任务需要 Redis | 测试环境可能没有 Redis | 提供内存降级方案 |
| API Key 认证破坏现有测试 | 测试需要传递 API Key | 测试环境设置环境变量 |
| Evolution 集成后 Agent 变慢 | 反思和优化增加延迟 | 可配置关闭，异步执行 |