fischer-agentkit/docs/plans/2026-06-24-005-feat-portal-platform-evolution-plan.md

---
title: "AgentKit 门户平台整体演进路线"
type: feat
date: 2026-06-24
origin: docs/brainstorms/2026-06-24-portal-platform-evolution-requirements.md
---

# AgentKit 门户平台整体演进路线

## Summary

按优先级串行推进 AgentKit 门户平台演进：P1 用 LlamaIndex 构建工业级 RAG 管道 + TaskIQ 异步任务基础；P2 扩展多端消息接入与 MCP Server 认证发布；P3 用 LiteLLM/langchain-mcp-adapters 替换 commodity 层降本。差异化能力（Agent 引擎/专家团队/自进化/终端安全）保持自研，不在本计划范围内。

## Problem Frame

AgentKit 定位为企业级统一 AI Agent 门户平台。对标 MaxKB 后发现四方面差距：RAG 管道是开发者级组件非工业级产品（上传端点从未调用向量化，KB 存储仅内存）；平台触达仅有 RAG 数据源适配器无消息适配器；MCP Server 零认证且未支持 Skill/专家团队发布；commodity 层大量自研维护成本高。

本次演进为预防性演进 + 必备功能补齐。目标是补齐门户平台应有的能力，使 AgentKit 在企业级 AI Agent 平台赛道具备完整竞争力。

## Requirements

### RAG 工业级管道（P1）

R1. 企业用户可上传文档到知识库，文档经 LlamaIndex 管道处理（解析→分段→预览→向量化→索引）后可被检索。现有 `memory/local_rag.py` 的 `LocalRAGService` 对 KB 场景废弃，Agent 记忆（WorkingMemory/EpisodicMemory/SemanticMemory）保留不动。

R2. 知识库支持双索引检索：pgvector 语义检索 + PostgreSQL 全文检索（jieba 中文分词），提供 embedding/keywords/blend 三种模式。检索模式由企业用户按知识库配置默认值，Agent 运行时可按查询特征覆盖。

R3. 文档分段支持智能分段与高级分段（LlamaIndex IngestionPipeline），企业用户可在向量化前预览分段结果（只读预览，编辑能力延后）。

R4. 系统为文档段落自动生成相关问题（LLM-based，参考现有 `memory/contextual_retrieval.py` 的 ContextualChunker 模式），提升检索召回率。

R5. 系统支持术语表（Termbase），通过 jieba 自定义词典增强中文分词，提升领域术语检索准确率。

R6. 知识库支持命中处理模式：模型优化模式（LLM 基于检索结果生成回答）与直接回答模式（直接返回匹配段落），按 KB 配置默认模式，Agent 可按查询场景覆盖。

R7. 检索结果经 rerank 模型重排后返回（API-based reranker，可配置 Cohere Rerank 或 BGE-Reranker）。

R8. 知识库实施 per-KB 访问控制（owner/authorized-users），文档上传验证文件类型（白名单）、强制大小限制、索引前净化解析内容（markdown sanitize、PDF 解析安全）。Agent 检索限定于调用用户授权的知识库。

R9. 知识库元数据持久化到 PostgreSQL（KB 源、文档记录、ACL），重启不丢失。现有内存 `KnowledgeSourceStore` 替换为 PG 后端。

R10. 文档向量化通过 TaskIQ 异步执行（复用现有 Redis 作为 broker），提供进度展示、失败通知与重试、任务历史。文档状态模型：pending → parsing → segmenting → vectorizing → indexed | failed（含 error_message）。

### 平台触达扩展（P2）

R11. 系统支持企微/钉钉/飞书/Slack 消息接入。各适配器验证平台签名/token（飞书 encrypt_key、钉钉 token、企微 EncodingAESKey）后处理消息，拒绝未认证请求。

R12. 平台凭证存储于加密 DB 列（master key 来自环境变量），定义轮换策略与访问审计。现有明文 `ProviderConfig.api_key` 同步迁移。

R13. MCP Server 合并至主 FastAPI app（`/api/v1/mcp/` 路由），所有端点要求认证与授权（复用 `require_permission` + API Key）。现有独立 `mcp/server.py` 重构为路由工厂。

R14. 企业用户/开发者可将 Skill/专家团队发布为 MCP 工具（配置：工具名称、描述、输入 schema、鉴权方式、速率限制），发布需管理员级授权。外部 AI 系统通过 MCP 协议认证调用。

### 生态替换降本（P3）

R15. LLM Provider 底层替换为 LiteLLM：6 个直接 API provider（OpenAI/Anthropic/Gemini/Doubao/Wenxin/Yuanbao）走 LiteLLM 统一接口。上层网关逻辑（fallback/用量追踪/部门级配额）保留自研。`RemoteLLMProvider`（客户端→服务端代理）保留不动。

R16. MCP 客户端替换为 `langchain-mcp-adapters`：跟进行业协议演进，降低自研 3 传输层（Stdio/HTTP/SSE）维护成本。

R17. 自研语义缓存替换为 LiteLLM 内置 Redis Semantic Cache。阈值调优（默认 0.87，约 13% 误命中风险）。现有 `llm/cache.py` 废弃。

## Key Technical Decisions

**KTD1: LlamaIndex 作为 RAG 管道框架。** 外部研究确认 LlamaIndex 2026 原生覆盖所有所需能力（双索引/智能分段/rerank/问题生成），pgvector 一等支持。相比从零构建避免重复造轮子；相比集成 MaxKB 独立服务避免引入 Django + 独立 PG 的运维复杂度。风险：LlamaIndex 频繁 breaking changes → 通过版本锁定 + 集成测试缓解。

**KTD2: TaskIQ 替代 Celery 作为异步任务队列。** 外部研究确认 Celery 对 asyncio 原生栈过度设计（引入 broker + worker + beat = 3 个新运维组件）。TaskIQ 提供一等 FastAPI 集成、Redis broker 支持、asyncio 原生。R12 提前至 P1 解决文档向量化阻塞事件循环的优先级依赖冲突。ARQ 已废弃不采用。

**KTD3: KB 元数据持久化到 PostgreSQL。** 遵循 `memory/episodic.py` 的 EpisodicMemory 模式（SQLAlchemy async session + PG）。KB 源、文档记录、ACL 存关系表，embedding 存 pgvector。替换现有内存 `KnowledgeSourceStore`。

**KTD4: MCP Server 合并至主 FastAPI app。** 现有 `mcp/server.py` 独立 app 零认证是 RCE 面（终端工具存在）。合并为 `/api/v1/mcp/` 子路由，复用 `require_permission` + `APIKeyHeader` 认证。独立 `MCPServer` 类重构为路由工厂。

**KTD5: Per-KB ACL 通过新 `kb_acl` 表实现。** 遵循现有 `filter_kb_sources_by_department` 模式，新增 `kb_acl` 表（kb_id, user_id, role: owner/viewer）。Agent 检索时通过 `filter_kb_by_user_acl()` 过滤，与部门级过滤并行。

**KTD6: 应用层 jieba 分词实现中文全文检索。** PostgreSQL 内置 `tsvector` 不支持中文分词。在 Python 层用 jieba 分词后写入 `tsvector`，避免安装 PG 扩展（pg_jieba/zhparser）的运维复杂度，也避免引入 Elasticsearch 外部搜索引擎。术语表通过 jieba 自定义词典实现。

**KTD7: LiteLLM 替换直接 provider，RemoteLLMProvider 保留。** LiteLLM 原生支持 Volcengine/Doubao；Wenxin/Yuanbao 通过 OpenAI 兼容端点。`RemoteLLMProvider` 是客户端→服务端代理（架构上不同于直接 API provider），LiteLLM 无法替代。语义缓存/fallback/用量追踪保留自研上层逻辑，底层 provider 适配走 LiteLLM。

**KTD8: 加密 DB 列存储平台凭证。** 单部署企业场景下，加密 DB 列 + 环境变量 master key 足够。避免引入 HashiCorp Vault 外部依赖。凭证轮换通过 API 触发 re-encrypt。访问审计记录到现有审计日志。

**KTD9: 新建 `src/agentkit/rag_platform/` 顶层模块。** 与 `memory/` 职责分离：`rag_platform/` 服务企业知识库场景，`memory/` 服务 Agent 运行时记忆。`LocalRAGService` 对 KB 场景废弃，Agent 记忆（EpisodicMemory）保留使用。

**KTD10: 成功标准从"MaxKB 功能对等"重构为"用户结果导向"。** MaxKB 是 RAG 知识库产品，AgentKit 是 Agent 平台。对标不同产品类别的功能对等可能构建不服务于实际用户的能力。成功标准改为：企业用户可上传文档、配置检索、测试召回、通过多端使用 Agent 检索知识库。

## High-Level Technical Design

```mermaid
flowchart TB
    subgraph P1["P1: RAG 工业级管道 + 异步任务"]
        U1[U1 RAG 平台骨架] --> U2[U2 KB 持久化 + ACL]
        U2 --> U3[U3 文档处理管道]
        U3 --> U4[U4 双索引检索]
        U4 --> U5[U5 Rerank/问题生成/术语表]
        U5 --> U6[U6 命中处理 + KB 设置]
        U2 --> U7[U7 上传安全 + 净化]
        U3 --> U8[U8 TaskIQ 异步任务]
        U6 --> U9[U9 前端 KB 管理]
        U8 --> U9
    end

    subgraph P2["P2: 平台触达扩展"]
        U10[U10 适配器骨架 + secrets] --> U11[U11 飞书 IM]
        U11 --> U12[U12 钉钉/企微/Slack]
        U13[U13 MCP 认证 + 合并]
        U13 --> U14[U14 Skill/团队 MCP 发布]
    end

    subgraph P3["P3: 生态替换降本"]
        U15[U15 LiteLLM Provider]
        U16[U16 langchain-mcp-adapters]
        U17[U17 LiteLLM 语义缓存]
    end

    P1 --> P2 --> P3
```

### 文档处理管道状态机

```mermaid
stateDiagram-v2
    [*] --> pending: 上传
    pending --> parsing: TaskIQ 接收
    parsing --> segmenting: 解析成功
    parsing --> failed: 解析失败
    segmenting --> vectorizing: 预览确认/自动
    segmenting --> failed: 分段失败
    vectorizing --> indexed: 向量化+索引成功
    vectorizing --> failed: 向量化失败
    failed --> pending: 用户重试
    indexed --> [*]
```

### 检索流程

```mermaid
flowchart LR
    Q[Agent 查询] --> ACL{Per-KB ACL 过滤}
    ACL -->|授权| Mode{检索模式}
    Mode -->|embedding| Sem[pgvector 语义]
    Mode -->|keywords| FT[PG 全文 jieba]
    Mode -->|blend| Both[双索引合并]
    Sem --> Rerank[rerank 模型]
    FT --> Rerank
    Both --> Rerank
    Rerank --> Hit{命中处理}
    Hit -->|model_opt| LLM[LLM 生成回答]
    Hit -->|direct| Return[返回匹配段落]
    LLM --> Result[检索结果]
    Return --> Result
```

## Implementation Units

### P1: RAG 工业级管道 + 异步任务基础

---

### U1. RAG 平台模块骨架 + LlamaIndex 集成

- **Goal:** 创建 `src/agentkit/rag_platform/` 模块，集成 LlamaIndex 作为管道框架，连接现有 pgvector。
- **Files:**
  - `src/agentkit/rag_platform/__init__.py` — 模块入口
  - `src/agentkit/rag_platform/models.py` — Pydantic 数据模型（KB、Document、Chunk、QueryResult）
  - `src/agentkit/rag_platform/pipeline.py` — LlamaIndex IngestionPipeline 封装
  - `src/agentkit/rag_platform/indexing.py` — pgvector 索引管理（LlamaIndex PGVectorStore）
- **Patterns:** 遵循现有模块结构（cf. `memory/__init__.py`, `mcp/__init__.py`）；LlamaIndex `PGVectorStore` 连接现有 PostgreSQL。
- **Test scenarios:**
  - LlamaIndex PGVectorStore 连接现有 pgvector 扩展
  - 基础 ingest（文档 → chunk → embedding → pgvector INSERT）端到端工作
  - 基础 query（query → embedding → pgvector cosine 检索）返回结果
- **Verification:** `pytest tests/unit/rag_platform/test_pipeline.py`

---

### U2. KB 持久化存储 + Per-KB 访问控制

- **Goal:** 替换内存 `KnowledgeSourceStore` 为 PostgreSQL 持久化，实现 per-KB ACL。
- **Files:**
  - `src/agentkit/rag_platform/store.py` — KB/Document 持久化（SQLAlchemy async）
  - `src/agentkit/rag_platform/acl.py` — per-KB ACL 逻辑
  - `src/agentkit/server/auth/models.py` — 新增 `kb_acl` 表模型
  - `src/agentkit/server/routes/kb_management.py` — 替换 `KnowledgeSourceStore` 调用
- **Patterns:** 遵循 `memory/episodic.py` 的 EpisodicMemory PG 模式（async session）；遵循 `filter_kb_sources_by_department` 模式实现 `filter_kb_by_user_acl()`。
- **Test scenarios:**
  - KB 元数据写入 PG，重启后仍存在
  - owner 用户可查询自己的 KB
  - 非 authorized 用户查询 KB 被拒绝
  - Agent 检索时 ACL 过滤生效（仅返回授权 KB 的结果）
- **Verification:** `pytest tests/unit/rag_platform/test_store.py tests/unit/rag_platform/test_acl.py`

---

### U3. 文档处理管道（LlamaIndex 分段 + 预览 + 向量化）

- **Goal:** 连接上传→解析→分段→预览→向量化→索引管道，使用 LlamaIndex IngestionPipeline。
- **Files:**
  - `src/agentkit/rag_platform/document_processor.py` — 文档处理管道
  - `src/agentkit/rag_platform/preview.py` — 分段预览 API
  - `src/agentkit/server/routes/kb_management.py` — 重写 `upload_document()` 端点
- **Patterns:** LlamaIndex `IngestionPipeline`（SentenceSplitter + MetadataExtractor）；现有 `memory/document_loader.py` 的 `DocumentLoader` 用于解析；文档状态模型（pending→parsing→segmenting→vectorizing→indexed|failed）。
- **Test scenarios:**
  - 上传 PDF → 解析 → 分段 → 返回预览（只读）
  - 确认预览 → 向量化 → 索引 → 可检索
  - 解析失败 → 状态 failed + error_message
  - 向量化失败 → 状态 failed + error_message
  - 重复上传同一文档 → 拒绝或更新（非创建重复）
- **Verification:** `pytest tests/unit/rag_platform/test_document_processor.py`

---

### U4. 双索引检索（pgvector 语义 + PG 全文检索 with jieba）

- **Goal:** 实现双索引检索，支持 embedding/keywords/blend 三种模式。
- **Files:**
  - `src/agentkit/rag_platform/retrieval.py` — 检索逻辑（三模式）
  - `src/agentkit/rag_platform/fulltext.py` — jieba 分词 + tsvector 写入/查询
- **Patterns:** LlamaIndex hybrid retriever（VectorStoreRetriever + NLSQLRetriever 或自定义）；jieba 在 Python 层分词后写入 `search_vector` 列。
- **Test scenarios:**
  - embedding 模式：语义检索返回相关结果
  - keywords 模式：中文全文检索返回包含关键词的结果
  - blend 模式：合并语义+全文结果，去重排序
  - 查询无结果时返回空列表（非报错）
- **Verification:** `pytest tests/unit/rag_platform/test_retrieval.py tests/unit/rag_platform/test_fulltext.py`

---

### U5. Rerank + 问题生成 + 术语表

- **Goal:** 添加 rerank 模型重排、问题自动生成、术语表支持。
- **Files:**
  - `src/agentkit/rag_platform/rerank.py` — rerank 模型集成（Cohere/BGE-Reranker 可配置）
  - `src/agentkit/rag_platform/question_gen.py` — LLM-based 问题生成
  - `src/agentkit/rag_platform/termbase.py` — 术语表管理 + jieba 自定义词典
- **Patterns:** LlamaIndex rerankers（`CohereRerank` 或 `SentenceTransformerRerank`）；参考 `memory/contextual_retrieval.py` 的 ContextualChunker 模式生成问题；jieba `load_userdict()` 加载术语表。
- **Test scenarios:**
  - rerank 后结果相关性顺序改善
  - 问题生成产生与段落内容相关的问题
  - 术语表中的领域术语被正确分词
  - 术语表增强后检索召回率提升
- **Verification:** `pytest tests/unit/rag_platform/test_rerank.py tests/unit/rag_platform/test_question_gen.py tests/unit/rag_platform/test_termbase.py`

---

### U6. 命中处理模式 + KB 设置

- **Goal:** 实现命中处理模式（模型优化/直接回答）+ KB 级别设置。
- **Files:**
  - `src/agentkit/rag_platform/hit_processing.py` — 命中处理逻辑
  - `src/agentkit/rag_platform/settings.py` — KB 设置模型（检索模式默认/命中处理默认/授权用户）
  - `src/agentkit/server/routes/kb_management.py` — KB 设置端点
- **Patterns:** 模型优化模式调用现有 LLM Gateway；直接回答模式返回匹配段落；KB 设置存 PG。
- **Test scenarios:**
  - model_opt 模式：LLM 基于检索结果生成回答
  - direct 模式：直接返回匹配段落
  - KB 设置默认模式生效
  - Agent 运行时覆盖默认模式
- **Verification:** `pytest tests/unit/rag_platform/test_hit_processing.py tests/unit/rag_platform/test_settings.py`

---

### U7. 文件上传安全 + 内容净化

- **Goal:** 后端文件类型白名单 + 内容净化。
- **Files:**
  - `src/agentkit/rag_platform/sanitize.py` — 内容净化（markdown sanitize + PDF 安全）
  - `src/agentkit/server/routes/kb_management.py` — 上传端点增加白名单验证
- **Patterns:** `DocumentLoader._detect_format()` 映射作为白名单源；`bleach` 或 `markdown` 库净化 HTML/markdown；PDF 解析限制页面数/大小。
- **Test scenarios:**
  - 白名单外文件类型被拒绝（.exe, .sh 等）
  - 超大小限制文件被拒绝
  - markdown 中 `<script>` 标签被净化
  - PDF 解析不触发已知 CVE（限制解析器行为）
- **Verification:** `pytest tests/unit/rag_platform/test_sanitize.py`

---

### U8. TaskIQ 异步任务集成

- **Goal:** 集成 TaskIQ 实现异步文档向量化和批量任务。
- **Files:**
  - `src/agentkit/rag_platform/tasks.py` — TaskIQ 任务定义（向量化、批量索引）
  - `src/agentkit/server/app.py` — TaskIQ startup/shutdown
  - `src/agentkit/server/task_store.py` — 扩展状态跟踪（复用现有 TaskStore 模式）
- **Patterns:** TaskIQ FastAPI 集成（`TaskiqMiddleware`）；现有 Redis 作为 broker；`TaskStore` 状态模型（PENDING/RUNNING/COMPLETED/FAILED）。
- **Test scenarios:**
  - 大文档（50MB PDF）向量化在后台执行，不阻塞事件循环
  - 任务状态可查询（pending→running→completed）
  - 任务失败后自动重试（可配置重试次数）
  - 任务历史可查询
- **Verification:** `pytest tests/unit/rag_platform/test_tasks.py`

---

### U9. 前端 KB 管理扩展

- **Goal:** 扩展 KnowledgeBaseView/DocumentUpload/SearchTest 组件，增加分段预览、状态展示、KB 设置。
- **Files:**
  - `src/agentkit/server/frontend/src/components/knowledge/KnowledgeBaseView.vue` — 扩展
  - `src/agentkit/server/frontend/src/components/knowledge/DocumentUpload.vue` — 增加状态展示
  - `src/agentkit/server/frontend/src/components/knowledge/SearchTest.vue` — 扩展检索测试
  - `src/agentkit/server/frontend/src/components/knowledge/SegmentPreview.vue` — 新建分段预览组件
  - `src/agentkit/server/frontend/src/components/knowledge/KBSettings.vue` — 新建 KB 设置组件
- **Patterns:** 现有 Ant Design Vue 组件模式；WebSocket 推送文档处理状态（复用现有 ws 协议）。
- **Test scenarios:**
  - 上传后显示处理进度（pending→parsing→...→indexed）
  - 分段预览显示分段结果（只读）
  - 检索测试支持三模式切换
  - KB 设置可配置检索模式默认/命中处理默认/授权用户
- **Verification:** `npm run typecheck` + 手动验证

### P2: 平台触达扩展

---

### U10. 多端消息适配器骨架 + secrets store

- **Goal:** 创建 MessageAdapter 协议 + secrets store 基础设施。
- **Files:**
  - `src/agentkit/channels/__init__.py` — 模块入口
  - `src/agentkit/channels/base.py` — MessageAdapter 协议（receive_message/send_message/verify_signature）
  - `src/agentkit/channels/secrets.py` — 加密 DB 列 secrets store
  - `src/agentkit/server/routes/channels.py` — 渠道管理端点
- **Patterns:** 新 `MessageAdapter` 协议（cf. `memory/adapters/base.py` 的 KBAdapter）；加密 DB 列（AES-256，master key 来自环境变量）。
- **Test scenarios:**
  - secrets 写入后加密存储（非明文）
  - secrets 读取时解密
  - MessageAdapter 协议被所有适配器实现
  - 渠道管理端点 CRUD 工作
- **Verification:** `pytest tests/unit/channels/test_secrets.py tests/unit/channels/test_base.py`

---

### U11. 飞书 IM 适配器（端到端）

- **Goal:** 实现飞书 IM 消息适配器端到端。
- **Files:**
  - `src/agentkit/channels/feishu.py` — 飞书 IM 适配器
  - `src/agentkit/server/routes/channels.py` — 飞书 webhook 端点
- **Patterns:** 飞书 webhook 签名验证（encrypt_key + AES 解密）；消息格式转换（飞书事件 → AgentKit 标准消息）；现有 chat handler 集成（`RequestPreprocessor` → `ExecutionMode`）。
- **Test scenarios:**
  - 飞书消息 → webhook → 签名验证 → Agent 处理 → 响应返回飞书
  - 无效签名请求被拒绝
  - 文本消息正确转换
  - Agent 响应正确格式化返回飞书
- **Verification:** `pytest tests/unit/channels/test_feishu.py`

---

### U12. 钉钉/企微/Slack 适配器

- **Goal:** 按飞书模式实现其余平台适配器。
- **Files:**
  - `src/agentkit/channels/dingtalk.py` — 钉钉适配器
  - `src/agentkit/channels/wecom.py` — 企微适配器
  - `src/agentkit/channels/slack.py` — Slack 适配器
- **Patterns:** 遵循 U11 飞书模式；平台特定签名验证（钉钉 token、企微 EncodingAESKey、Slack signing secret）。
- **Test scenarios:**
  - 每个平台端到端消息流
  - 每个平台签名验证拒绝无效请求
- **Verification:** `pytest tests/unit/channels/test_dingtalk.py tests/unit/channels/test_wecom.py tests/unit/channels/test_slack.py`

---

### U13. MCP Server 认证 + 合并至主 app

- **Goal:** 将 MCP Server 合并至主 FastAPI app，添加认证。
- **Files:**
  - `src/agentkit/mcp/server.py` — 重构为路由工厂（`create_mcp_router()`）
  - `src/agentkit/server/app.py` — 挂载 MCP 路由到 `/api/v1/mcp/`
- **Patterns:** `require_permission` 依赖注入；`APIKeyHeader` 认证；现有 `ToolRegistry.list_tools()` 暴露为 MCP 工具。
- **Test scenarios:**
  - 无认证调用 `/api/v1/mcp/tools/list` 被拒绝（401）
  - 有效 API Key 调用返回工具列表
  - 有效 JWT + 权限调用返回工具列表
  - 现有工具仍可通过 MCP 协议调用
- **Verification:** `pytest tests/unit/mcp/test_server_auth.py`

---

### U14. Skill/专家团队 MCP 发布

- **Goal:** 支持 Skill/专家团队发布为 MCP 工具。
- **Files:**
  - `src/agentkit/mcp/publisher.py` — Skill/Team → MCP Tool 适配器
  - `src/agentkit/server/routes/mcp_publish.py` — 发布管理端点
  - `src/agentkit/mcp/server.py` — 扩展工具列表包含已发布 Skill/Team
- **Patterns:** Tool 适配器包装（Skill/Team → `Tool` 接口）；管理员级授权（`Permission.ADMIN`）；配置字段（工具名称/描述/输入 schema/鉴权方式/速率限制）。
- **Test scenarios:**
  - 管理员发布 Skill 为 MCP 工具
  - 非管理员发布被拒绝
  - 外部系统通过 MCP 认证调用已发布 Skill
  - 专家团队发布为 MCP 工具
  - 已发布工具在 `/api/v1/mcp/tools/list` 中可见
- **Verification:** `pytest tests/unit/mcp/test_publisher.py`

### P3: 生态替换降本

---

### U15. LiteLLM Provider 替换

- **Goal:** 用 LiteLLM 替换 6 个直接 API provider 适配器。
- **Files:**
  - `src/agentkit/llm/providers.py` — 重写为 LiteLLM 统一接口
  - `src/agentkit/llm/gateway.py` — 适配上层网关逻辑
  - `src/agentkit/llm/config.py` — provider 配置更新
- **Patterns:** LiteLLM `completion()` / `acompletion()` 统一接口；保留自研 fallback 链/用量追踪/部门级配额；`RemoteLLMProvider` 保留不动。
- **Test scenarios:**
  - 6 个 provider 通过 LiteLLM 调用成功（OpenAI/Anthropic/Gemini/Doubao/Wenxin/Yuanbao）
  - fallback 链在 provider 失败时切换
  - 用量追踪记录正确
  - 部门级配额生效
  - `RemoteLLMProvider` 仍正常工作（不受影响）
  - 流式响应正常工作
- **Verification:** `pytest tests/unit/llm/test_providers.py tests/unit/llm/test_gateway.py`

---

### U16. langchain-mcp-adapters 替换 MCP 客户端

- **Goal:** 用 langchain-mcp-adapters 替换自研 MCP 客户端传输层。
- **Files:**
  - `src/agentkit/mcp/client.py` — 重写为 langchain-mcp-adapters 封装
  - `src/agentkit/mcp/transport.py` — 废弃（Stdio/HTTP/SSE 传输由 langchain-mcp-adapters 提供）
- **Patterns:** `langchain-mcp-adapters` 的 `ClientSession` + 传输层；现有 `MCPTool` 包装保留（将远程 MCP 工具暴露为本地 `Tool`）。
- **Test scenarios:**
  - 现有 MCP 工具调用通过新客户端工作
  - Stdio 传输连接成功
  - HTTP 传输连接成功
  - SSE 传输连接成功
  - `MCPTool` 包装仍正常工作
- **Verification:** `pytest tests/unit/mcp/test_client.py`

---

### U17. LiteLLM 语义缓存集成

- **Goal:** 用 LiteLLM 内置 Redis Semantic Cache 替换自研语义缓存。
- **Files:**
  - `src/agentkit/llm/cache.py` — 重写为 LiteLLM 缓存配置（或废弃，由 gateway 直接配置）
  - `src/agentkit/llm/gateway.py` — 集成 LiteLLM caching 配置
- **Patterns:** LiteLLM `RedisSemanticCache`；阈值调优（默认 0.87）；缓存 key 包含 system prompt + temperature。
- **Test scenarios:**
  - 语义相似查询命中缓存
  - 不同 system prompt 不命中缓存
  - 缓存命中率可统计
  - 阈值调优生效
- **Verification:** `pytest tests/unit/llm/test_cache.py`

## Scope Boundaries

### In scope

- P1: RAG 工业级管道（LlamaIndex 集成 + 双索引 + rerank + 问题生成 + 术语表 + 命中处理 + per-KB ACL + 上传安全 + TaskIQ 异步 + 前端扩展）
- P2: 多端消息接入（飞书/钉钉/企微/Slack）+ secrets store + MCP Server 认证 + Skill/团队 MCP 发布
- P3: LiteLLM provider 替换 + langchain-mcp-adapters 客户端替换 + LiteLLM 语义缓存替换

### Deferred for later

- 分段预览编辑能力（合并/拆分/重新分段）— P1 只做只读预览
- 外部 secrets manager（HashiCorp Vault / 云 KMS）— P2 用加密 DB 列，单部署足够
- 分块预览的高级交互模式 — 归 ce-work 设计
- RAG 平台门户 IA 精细化（顶级 section vs 扩展现有）— P1 前端扩展先复用现有 KnowledgeBaseView

### Outside this product's identity

- Agent 引擎/专家团队/自进化/终端安全 — 差异化能力，保持自研，不在本计划范围
- FlowCanvas 工作流画布 — 不替换为 LogicFlow，保持自研
- 消息总线（`bus/`）— 紧耦合 Agent 事件系统，非 commodity，保持自研
- MaxKB 深度集成（共享 DB/embedding model）— MaxKB 作为独立服务集成仅作备选方案，不在本计划实施

## System-Wide Impact

- **数据生命周期:** 新增 KB/Document/Chunk/kb_acl 表到 PostgreSQL；pgvector 索引扩展（现有 Agent 记忆表不动）；`search_vector` 列新增到 KB chunk 表。
- **认证边界:** MCP Server 从零认证变为要求 JWT/API Key；KB 检索新增 per-KB ACL 层；平台凭证从明文变为加密存储。
- **性能姿态:** 文档向量化从同步（阻塞事件循环）变为 TaskIQ 异步；检索从单索引变为双索引 + rerank（增加延迟但提升相关性）。
- **共享基础设施:** Redis 新增 TaskIQ broker 角色（与现有 bus/cache 共存）；PostgreSQL 新增 RAG 平台 schema。
- **Agent/工具对等:** Agent 运行时通过 RAG 平台检索 KB 内容；外部 AI 系统通过 MCP 调用已发布 Skill/团队。
- **向后兼容:** `LocalRAGService` 对 KB 场景废弃但保留（Agent 记忆仍用）；`RemoteLLMProvider` 保留不动；现有 `ToolRegistry` 工具仍可通过 MCP 访问。

## Risks & Dependencies

- **LlamaIndex breaking changes:** LlamaIndex 频繁发布 breaking changes。缓解：版本锁定（`pyproject.toml` pin major version）+ 集成测试覆盖核心管道。
- **jieba 中文分词质量:** jieba 默认词典可能不覆盖领域术语。缓解：术语表通过 `jieba.load_userdict()` 扩展；检索测试覆盖中文场景。
- **TaskIQ 成熟度:** TaskIQ 社区较小（~2k★）。缓解：API 简单，必要时可替换为 SAQ 或回退到 ProcessPoolExecutor。
- **LiteLLM 中文 provider 覆盖:** Wenxin/Yuanbao 通过 OpenAI 兼容端点，可能缺少 provider 特定功能。缓解：feature-gap 分析在 U15 实施时执行；保留自定义 handler 作为 fallback。
- **MCP Server 合并破坏现有集成:** 合并至主 app 可能影响现有 MCP 客户端调用。缓解：保持 `/api/v1/mcp/` 路径与现有 MCP 协议兼容；迁移测试。
- **向后兼容性验证:** R15-R17 替换核心组件，"现有功能行为不变"是假设非验证。缓解：每个替换单元必须有 feature-parity 测试（现有行为 → 新实现行为对比）。
- **GPL v3 合规边界:** MaxKB 作为备选集成方案的 GPL v3 许可证。缓解：本计划不实施 MaxKB 集成（仅作备选）；若未来集成，通过 REST API 独立服务调用（不修改/分发 MaxKB 代码）。

## Open Questions

1. **门户触达(P2)反转门户价值主张:** 门户平台核心价值是触达，但多端接入在 P2。是否在 P1 并行交付至少一个高价值渠道（如飞书 IM）？默认假设：不并行，P1 聚焦 RAG 管道，P2 再做多端。
2. **R11-R13 是技术债非产品需求:** R15-R17（原 R11-R13）成功标准是"现有功能行为不变"（零用户可见影响），无 Actor 受益。是否移至独立工程债轨道？默认假设：保留在 P3，作为 commodity 层降本。
3. **rerank 模型选择:** U5 rerank 模型未指定（Cohere Rerank vs BGE-Reranker vs 其他）。默认假设：API-based（Cohere Rerank 或 BGE-Reranker via Xinference），可配置。
4. **多端 onboarding 流程细节:** U10-U12 的管理员配置流程（webhook URL 生成、app 凭证配置、连通性测试）需在实施时细化。默认假设：admin 导航到渠道配置 → 选择平台 → 输入凭证 → 系统生成 webhook URL → 管理员在平台配置 → 连通性测试。

## Sources / Research

- **LlamaIndex 2026:** 14 index types, sparse+dense hybrid retrieval, auto-rerank, pgvector first-class support, LlamaParse for complex PDFs. Pitfall: frequent breaking changes. — https://blog.csdn.net/yanxilou/article/details/162178538
- **LlamaIndex vs Haystack 2026:** Architecture and decision matrix. — https://myengineeringpath.dev/tools/llamaindex-vs-haystack/
- **LiteLLM v1.89.x:** 157 providers, 2784 models. Volcengine/Doubao native; Wenxin/Yuanbao via OpenAI-compatible endpoint. Redis Semantic Cache, fallback chains, virtual keys, spend tracking built-in. P95 proxy overhead 8ms @ 1k RPS. — https://docs.litellm.ai/docs/providers
- **LiteLLM semantic caching:** Threshold tuning critical (0.87 ≈ 13% false-positive collision risk). Cache key excludes system prompt/temperature by default. — https://theneuralbase.com/litellm/learn/intermediate/semantic-caching-similar-prompts/
- **TaskIQ:** Modern async task queue with first-class FastAPI integration. ARQ deprecated — TaskIQ is spiritual successor. — https://markaicode.com/alternatives/rq-alternatives/
- **Celery vs asyncio:** Celery overkill for asyncio-native stack. Adds broker + worker + beat = 3 new operational components. — https://theneuralbase.com/celery-for-ml/learn/advanced/vs-dramatiq/
- **MaxKB v2.7.0:** 21.4k★, GPLv3, Django + Vue, ships Celery internally. OpenAI-compatible chat API. Cannot share PG/pgvector — brings its own. GPL v3 not a blocker for SaaS-style REST integration (confirmed by FSF FAQ, Chinese judicial precedent 不乱买案). — https://maxkb.cn/docs/v2/user_manual/chat_to_API/
- **GPL v3 commercial use:** Internal-use loophole, distribution trigger. SaaS/network-service via REST does not trigger copyleft. — https://legalclarity.org/can-you-use-gplv3-in-a-commercial-application/
- **AgentKit 代码库:** `memory/local_rag.py`（LocalRAGService — pgvector + 分块 + 嵌入 + 语义检索）、`memory/chunking.py`（TextChunker/StructuralChunker）、`memory/contextual_retrieval.py`（ContextualChunker — LLM 生成上下文前缀）、`mcp/server.py`（零认证 MCP Server）、`mcp/client.py`（3 传输层 MCP 客户端）、`llm/gateway.py`（6 provider + fallback + 语义缓存 + 用量追踪）、`llm/cache.py`（自研语义缓存）、`server/routes/kb_management.py`（KB 管理端点 — 上传未调用向量化）、`server/auth/`（JWT + RBAC + API Key + 部门级过滤）、`server/task_store.py`（任务状态存储 — 仅状态非执行）、`bus/`（MemoryBus/RedisBus）
- **需求文档:** `docs/brainstorms/2026-06-24-portal-platform-evolution-requirements.md`（经两轮 ce-doc-review，36 项延期至 planning）