fischer
/
fischer-agentkit
1
0
Fork 0
Code Issues Pull Requests Actions 87 Packages Projects Releases Wiki Activity
fischer-agentkit/docs/plans/2026-06-05-005-refactor-age...

11 KiB
Raw Blame History

AgentKit 框架完善计划

问题框架

目标：完善 fischer-agentkit 框架本身，修复安全性问题、补全缺失功能、提升代码质量。

范围：仅修改 fischer-agentkit/ 目录下的代码。GEO 项目集成留在 GEO 开发会话中完成。

当前状态：

  • Phase 1（U1-U8）全部实现完成，535 个单元测试通过
  • 61 个文件变更未提交（在 feat/agentkit-v2-phase1 分支）
  • 代码审查发现 19 个问题（4 P0 + 6 P1 + 9 P2/P3），已全部修复
  • 1 个 TODO 待解决（pgvector 向量检索）
  • README 已编写

需求追踪

来自代码审查和框架分析的问题清单：

ID 分类 描述 严重度
R1 安全 pgvector 向量检索未实现 高
R2 安全 custom_handler 缺少模块前缀白名单 高
R3 安全 Server 缺少 API 认证 高
R4 安全 CORS 配置不当（allow_origins=["*"] + allow_credentials=True） 高
R5 安全 缺少速率限制 高
R6 安全 Callback URL SSRF 风险 高
R7 代码质量 registry.py 死代码 中
R8 代码质量 pipeline_engine.py 死代码 中
R9 代码质量 reflector.py error_type 提取 bug 低
R10 功能 get_task_status 返回 placeholder 中
R11 功能 Quality Gate/Standardization 失败静默忽略 中
R12 功能 MCP Server 未使用官方 SDK 中
R13 依赖 pyproject.toml 缺少 pgvector 依赖 中
R14 依赖 pyproject.toml 缺少 fastapi/uvicorn 依赖 低（Phase 1 已部分修复）
R15 测试 18 个模块测试覆盖不足 中

关键决策

KTD1：安全修复优先于功能补全

所有安全问题（R1-R6）必须在功能补全之前修复。框架的安全性是生产就绪的前提。

KTD2：API 认证采用 API Key 方案

不引入 JWT/OAuth 等复杂方案。Server 模式使用 API Key 认证即可满足需求。实现方式：

  • 通过环境变量 AGENTKIT_API_KEY 配置
  • 请求头 X-API-Key 验证
  • 健康检查端点不需要认证

KTD3：速率限制采用固定窗口算法

不引入 Redis 滑动窗口等复杂方案。使用内存中的固定窗口计数器即可，后续可升级为 Redis 方案。

KTD4：Callback URL SSRF 防护采用白名单方案

只允许 http:// 和 https:// 协议，拒绝内网 IP（127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16）。

KTD5：pgvector 向量检索在 Phase 2 实现

当前使用时间衰减排序作为降级方案是可接受的。pgvector 实现需要 PostgreSQL 扩展支持，作为独立单元实现。

KTD6：静默失败改为结构化日志记录

quality gate 和 output standardization 的失败不应静默忽略，应记录 warning 日志并在响应中附带质量状态信息。

实现单元

U1. 提交 Phase 1 代码并创建新分支

目标：将 Phase 1 的 61 个文件变更提交到 git，创建新的开发分支。

依赖：无

Files：

  • 当前工作目录所有变更

Approach：

  1. 在 feat/agentkit-v2-phase1 分支上提交所有变更
  2. 创建新分支 feat/agentkit-framework-hardening
  3. 后续工作在新分支上进行

验证：git log -1 显示提交，git status 显示干净工作树

U2. 修复安全：custom_handler 模块前缀白名单

目标：为 ConfigDrivenAgent._import_handler() 添加模块前缀白名单，防止任意代码执行。

依赖：无

Files：

  • src/agentkit/core/config_driven.py

Approach：

  1. 在 ConfigDrivenAgent 类中添加 _ALLOWED_HANDLER_PREFIXES 常量
  2. 在 _import_handler() 方法开头添加白名单校验
  3. 白名单前缀："agentkit.", "app.agent_framework."

Patterns to follow：参考 QualityGate._import_validator() 的白名单实现

Test scenarios：

  • 白名单前缀的 handler 可以正常导入
  • 非白名单前缀的 handler 抛出 ImportError
  • 空路径、畸形路径的处理

验证：pytest tests/unit/test_config_driven.py -v 新增测试通过

U3. 修复安全：CORS 配置 + API Key 认证

目标：修复 CORS 配置不当问题，添加 API Key 认证中间件。

依赖：无

Files：

  • src/agentkit/server/app.py
  • src/agentkit/server/middleware.py（新建）

Approach：

  1. 修复 CORS：移除 allow_credentials=True（与 allow_origins=["*"] 冲突）
  2. 创建 APIKeyAuthMiddleware：
    • 从环境变量 AGENTKIT_API_KEY 读取密钥
    • 验证请求头 X-API-Key
    • 健康检查端点（/api/v1/health）不需要认证
  3. 在 create_app() 中注册中间件

Test scenarios：

  • 无 API Key 的请求返回 401
  • 正确 API Key 的请求通过
  • 健康检查端点不需要 API Key
  • CORS 预检请求正常响应

验证：pytest tests/unit/test_server_middleware.py -v 新增测试通过

U4. 修复安全：速率限制

目标：添加请求速率限制中间件，防止 LLM 成本耗尽。

依赖：U3（需要中间件基础设施）

Files：

  • src/agentkit/server/middleware.py（修改）

Approach：

  1. 创建 RateLimiter 类：固定窗口计数器，基于 IP 或 API Key 限流
  2. 默认配置：每分钟 60 次请求（可配置）
  3. 在 create_app() 中注册速率限制中间件
  4. 超过限制时返回 429 Too Many Requests

Test scenarios：

  • 请求在限制内正常通过
  • 超过限制返回 429
  • 时间窗口过后计数器重置
  • 不同 API Key 独立计数

验证：pytest tests/unit/test_rate_limiter.py -v 新增测试通过

U5. 修复安全：Callback URL SSRF 防护

目标：为 TaskDispatcher._trigger_callback() 添加 URL 验证。

依赖：无

Files：

  • src/agentkit/core/dispatcher.py

Approach：

  1. 创建 _validate_callback_url(url) 函数
  2. 校验规则：
    • 只允许 http:// 和 https:// 协议
    • 拒绝内网 IP：127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
    • 拒绝 localhost/127.0.0.1
  3. 无效 URL 抛出 ValueError

Test scenarios：

  • 合法公网 URL 通过验证
  • 内网 IP 被拒绝
  • localhost 被拒绝
  • 非 http/https 协议被拒绝（ftp, file, etc.）

验证：pytest tests/unit/test_callback_url.py -v 新增测试通过

U6. 修复代码质量：清理死代码 + Bug

目标：清理发现的死代码和修复 reflector.py 的 error_type 提取 bug。

依赖：无

Files：

  • src/agentkit/core/registry.py
  • src/agentkit/orchestrator/pipeline_engine.py
  • src/agentkit/evolution/reflector.py

Approach：

  1. registry.py:51：删除无用的 stmt = type(db).execute.__self__.__class__ 行
  2. pipeline_engine.py:73-74：删除不可能的条件分支 if sr.output_data and isinstance(sr, dict): pass
  3. reflector.py:110：修复 error_type 提取逻辑，不再使用 type(result.error_message).__name__（永远是 "str"）

Test scenarios：

  • 清理后原有测试全部通过
  • reflector.py 修复后 error_type 能正确提取错误类型

验证：pytest tests/unit/ -v --ignore=tests/unit/test_working_memory.py --ignore=tests/unit/test_handoff.py 全部通过

U7. 修复功能：get_task_status 实现 + 静默失败日志化

目标：实现真正的任务状态查询，将静默失败改为结构化日志记录。

依赖：无

Files：

  • src/agentkit/server/routes/tasks.py

Approach：

  1. get_task_status 端点：添加简单的任务状态追踪（内存字典或 Redis）
  2. Quality Gate 失败：记录 warning 日志，在响应中附带 quality_status: "skipped" 字段
  3. Output Standardization 失败：记录 warning 日志，在响应中附带 standardization_status: "skipped" 字段

Test scenarios：

  • 提交任务后能查询到任务状态
  • Quality Gate 失败时响应包含 quality_status 字段
  • Standardization 失败时响应包含 standardization_status 字段
  • 日志中包含失败原因

验证：pytest tests/unit/test_server_routes.py -v 更新后的测试通过

U8. 修复功能：pgvector 向量检索实现

目标：实现 EpisodicMemory 的 pgvector 语义搜索。

依赖：无（需要 PostgreSQL 实例运行）

Files：

  • src/agentkit/memory/episodic.py
  • pyproject.toml

Approach：

  1. 添加 pgvector 到 pyproject.toml 依赖
  2. 修改 EpisodicMemory.search() 方法：
    • 如果有 _embedder 且安装了 pgvector，使用 embedding.cosine_distance(query_embedding) 排序
    • 否则回退到时间衰减排序
  3. 添加迁移或建表语句（如果需要 vector 类型列）

Test scenarios：

  • 有 pgvector 时按余弦距离排序返回结果
  • 无 pgvector 时回退到时间衰减排序
  • 空查询返回空列表

验证：pytest tests/unit/test_episodic_memory.py -v 更新后的测试通过

U9. 修复依赖：完善 pyproject.toml

目标：确保所有运行时依赖正确声明。

依赖：U8（pgvector 依赖）

Files：

  • pyproject.toml

Approach：

  1. 添加 pgvector>=0.2 到 dependencies（episodic memory 需要）
  2. 确认 fastapi>=0.110, uvicorn>=0.27 在 optional-dependencies.server 中（Phase 1 已添加）
  3. 确认 mcp>=1.0 与实际使用一致（如果使用官方 SDK）

验证：pip install -e ".[server]" 成功安装所有依赖

U10. 补充测试覆盖（可选）

目标：为测试覆盖不足的模块添加测试。

依赖：U1-U9 全部完成

Files：

  • tests/unit/test_registry.py（扩展现有）
  • tests/unit/test_dispatcher.py（扩展现有）
  • tests/unit/test_pipeline_engine.py（新建）
  • tests/unit/test_handoff.py（扩展现有）
  • tests/unit/test_mcp_*.py（扩展现有）

Approach：

  • 每个模块添加 5-10 个核心测试用例
  • 优先覆盖 happy path 和错误路径
  • 集成测试需要真实 Redis/PostgreSQL 的可以标记为 skip

验证：总测试数达到 600+，覆盖率提升到 80%+

执行顺序

U1（提交代码） → U2（白名单） → U3（CORS + 认证） → U4（速率限制）
                                                    ↓
U6（死代码清理） → U7（任务状态 + 日志） → U8（pgvector） → U9（依赖完善）
                                                                    ↓
                                                          U10（补充测试，可选）

并发性：

  • U2, U6, U7 可以并行执行（无依赖）
  • U3 和 U4 有依赖关系（U3 先于 U4）
  • U5 独立，可与任何单元并行
  • U8 和 U9 有依赖关系（U9 需要 U8 的 pgvector 信息）

风险与缓解

风险 影响 缓解
pgvector 需要 PostgreSQL 扩展 测试环境可能没有 pgvector 使用 skip 标记，提供降级方案
API Key 认证破坏现有测试 测试需要传递 API Key 测试环境设置环境变量
速率限制影响 E2E 测试 测试可能被限流 测试环境提高限制或使用 mock

范围边界

本计划包含：

  • AgentKit 框架本身的安全修复
  • 代码质量清理
  • 缺失功能补全
  • 依赖完善

本计划不包含：

  • GEO 项目的任何改动（留在 GEO 开发会话中完成）
  • 新的 Agent 类型或 Skill 类型
  • 前端 UI 开发
  • 生产环境部署配置（K8s、监控等）