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

title	type	date	origin
AgentKit 门户平台整体演进路线	feat	2026-06-24	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

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

文档处理管道状态机

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

检索流程

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）