52 KiB

Raw Blame History

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

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 原生。R10 提前至 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）。kb_acl 表定义于 rag_platform/store.py（PostgreSQL，与 KB 元数据同库）以保证事务边界一致 — 不放在 server/auth/models.py。kb_acl.kb_id 外键 → KB 表 id ON DELETE CASCADE。Agent 检索时通过 filter_kb_by_user_acl() 过滤，与部门级过滤并行。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。语义缓存在 P3（U17）由自研替换为 LiteLLM 内置 Redis Semantic Cache — KTD7 保留自研指的是 P1/P2 阶段，P3 完成后自研缓存废弃。

KTD8: 加密 DB 列存储平台凭证。 单部署企业场景下，加密 DB 列 + master key 足够。避免引入 HashiCorp Vault 外部依赖。加密算法强制 AES-256-GCM（非泛指 "AES-256"），每行使用随机 96-bit nonce 与密文一同存储。采用 envelope encryption（master key 包裹 per-row data key）或 HKDF with per-row salt 派生 per-row 密钥。生产环境 master key 必须存储于云 KMS（AWS KMS / 阿里云 KMS），应用启动 guard 在生产模式下若仅检测到环境变量 key 则拒绝启动；环境变量仅作为开发环境 fallback。凭证轮换通过 API 触发 re-encrypt。访问审计记录到现有审计日志。Master key 轮换采用双密钥窗口策略：新 key 与旧 key 同时有效（DB 列存储 key_id 标识），后台批量 re-encrypt 旧密钥数据到新密钥，完成后旧 key 失效。Master key 泄露恢复流程从 Deferred 提升至 Risks（见 Risks & Dependencies）。

KTD9: 新建 src/agentkit/rag_platform/ 顶层模块。 与 memory/ 职责分离：rag_platform/ 服务企业知识库场景，memory/ 服务 Agent 运行时记忆。LocalRAGService 对 KB 场景废弃，Agent 记忆（EpisodicMemory）保留使用。明确决策：rag_platform/ 定义自己的检索模型；现有 memory/knowledge_base.py 中的 KnowledgeBase protocol 对 KB 用途废弃。MemoryRetriever 将在新的单元中重新接线，直接调用 rag_platform/retrieval.py。由于当前无外部代码 import LocalRAGService，"代码重复"顾虑不再成立 — 真正的问题是 protocol 复用，答案是：新 protocol、清晰边界、MemoryRetriever 内置 adapter。

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

KTD11: RetrievalPrincipal 用于非交互路径的 ACL 强制执行。 定义 RetrievalPrincipal 概念，封装用户身份用于 ACL 过滤。WebSocket chat：principal = JWT 用户。MCP 工具调用：principal = per-client API Key 绑定的身份（要求 per-client keys，非全局 key）。TaskIQ worker：principal 序列化进任务 payload 并在 worker 内 re-hydrate。多端 webhook：IM 用户 → AgentKit 用户映射步骤。没有此机制，非交互路径的 ACL 会被静默绕过。

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 设置]
        U3 --> 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] --> U17[U17 LiteLLM 语义缓存]
        U16[U16 langchain-mcp-adapters]
    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。
pgvector Schema Isolation: LlamaIndex PGVectorStore 必须使用显式表名（如 rag_platform_kb_chunks），不可使用默认 data_<name>。确认 create_if_not_exists 不会触碰 episodic_memory 或任何 memory/ 所属表。KB chunk 表（含 search_vector）与 LlamaIndex 向量表应统一为单表（同时含两列）或通过 FK 关联并维持同步不变式：每个 chunk 行恰好对应一个 embedding 行。
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）+ kb_acl 表定义
- src/agentkit/rag_platform/models.py — ORM 模型（SQLAlchemy 2 DeclarativeBase + Mapped）
- src/agentkit/rag_platform/acl.py — per-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()。使用 SQLAlchemy 2 ORM（DeclarativeBase + Mapped）而非原始 SQL — 便于 Alembic 迁移演进 schema。Alembic 迁移在本单元范围内。
Migration note: 现有内存 KnowledgeSourceStore 数据是 ephemeral 的；首次 PG 后端启动时，若内存 store 非空，记录 warning 日志以便运维重新注册 KB。这对未在 config 中捕获的 KB 状态是破坏性变更。
Invariant: ACL 条目与 KB 元数据共享事务边界（同一 PG DB）。kb_acl.kb_id FK → KB 表 id ON DELETE CASCADE。
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（jieba-aware 自定义 SentenceSplitter + MetadataExtractor）；现有 memory/document_loader.py 的 DocumentLoader 用于解析；文档状态模型（pending→parsing→segmenting→vectorizing→indexed|failed）。LlamaIndex 默认 SentenceSplitter 按英文标点/空格切分，中文场景需自定义 splitter（基于 jieba 分词边界切分）以保证分段质量。分段预览端点必须复用 require_permission + per-KB ACL 校验（owner/viewer 可预览，其他拒绝）。
Failure & Retry Semantics: 向量化是 all-or-nothing（单个 PG 事务包裹所有 chunk+embedding INSERT）。失败时部分工作回滚。segmenting 阶段产生的孤儿 chunks 标记为 orphaned 并从检索中排除。重试从 pending 重新处理，按 document hash + chunk hash 去重。不变式：检索永不返回来自非 indexed 文档的 chunk。
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 写入/查询
- src/agentkit/rag_platform/models.py — 新增 RetrievalRequest 模型（含可选 retrieval_mode 与 hit_processing_mode 覆盖字段，默认值为 KB 配置值）
Patterns: LlamaIndex hybrid retriever（VectorStoreRetriever + NLSQLRetriever 或自定义）；jieba 在 Python 层分词后写入 search_vector 列。集成机制：Python 层调用 jieba.cut(text) 得到 token 列表，用空格连接后写入 tsvector 列（to_tsvector('simple', space_joined_tokens)），查询时同样用 jieba 分词后构造 tsquery。避免依赖 PG 扩展（pg_jieba/zhparser）。
Agent access: Agent 通过 MemoryRetriever 参数访问（隐式，按 session 配置）— 不是单独的 Tool。Chat handler 通过 Agent context 传播 per-query 覆盖。
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() 加载术语表。Rerank API 调用将文档 chunks 发送到第三方（Cohere 等），需在 KB 设置中标注数据出境风险并提供本地部署选项（BGE-Reranker via Xinference）作为敏感数据 KB 的默认。
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。KB 设置端点必须复用 require_permission + per-KB ACL 校验（仅 owner 可修改设置，viewer 只读）。
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: 后端文件类型白名单 + 内容净化。
Depends on: U3（U7 重写 upload_document() 端点，U3 也重写同一端点 — 两者必须协同实施，U7 的白名单/净化逻辑嵌入 U3 的上传管道）
Files:
- src/agentkit/rag_platform/sanitize.py — 内容净化（markdown sanitize + PDF 安全）
- src/agentkit/server/routes/kb_management.py — 上传端点增加白名单验证
Patterns: memory/document_loader.py 的模块级函数 _detect_format()（注意：是模块级函数，非 DocumentLoader 方法）映射作为白名单源；bleach 或 markdown 库净化 HTML/markdown；PDF 解析限制页面数/大小。
Expanded attack surface:
- (a) ZIP 类格式（.docx/.xlsx/.pptx）的解压比率限制 — 比率 > 100:1 或解压后 > N MB 时拒绝（防 zip bomb）。
- (b) XML parser 加固 — 对 XML-based 格式禁用 ENTITY 解析、外部 DTD、XInclude（防 XXE）。
- (c) URL egress 过滤 — deny by default（allowlist 模式）。Blocked ranges 必须包含：127.0.0.0/8（loopback）、10.0.0.0/8、172.16.0.0/12、192.168.0.0/16（RFC1918）、169.254.0.0/16（link-local + cloud metadata）、::1（IPv6 loopback）、fc00::/7（IPv6 ULA）、fe80::/10（IPv6 link-local）。优先使用 egress allowlist（resolve target，仅允许 public IP）以覆盖未来内部范围。
- (d) 嵌入图片的像素数上限（防 image bomb）。
- (e) 若使用 LlamaParse 托管服务，添加与 U5 rerank note 相同的数据出境警告 + per-KB opt-in。
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）。
Worker liveness & sweeper: 在 document/task 记录上增加 worker_heartbeat_at 时间戳列，由 worker 周期性更新。新增 sweeper 任务（TaskIQ scheduled job），将卡在 parsing/segmenting/vectorizing 超过 TTL 的记录转回 failed 并写入 error_message="worker_timeout"。测试场景："worker 在 vectorization 中途死亡 → sweeper 在 TTL 后转为 failed → 用户可重试。"
Redis isolation: TaskIQ broker 使用独立 Redis DB index（如 db=1）或 key 前缀 taskiq:。连接池与 bus/cache 分离。
Security:
- (a) per-user 任务并发上限 + per-task 内存/CPU 上限。
- (b) 任务参数 schema 校验（每种 task type 一个 Pydantic 模型）。
- (c) error_message 在暴露给用户前净化（剥离内部路径、redact 租户标识）。
- (d) 任务参数在 Redis 中带 TTL（完成后 + grace period 自动过期）。
- (e) worker 权限分离建议（worker 进程以低于主服务的权限运行）。
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/views/KnowledgeBaseView.vue — 扩展
- src/agentkit/server/frontend/src/components/kb/DocumentUpload.vue — 增加状态展示
- src/agentkit/server/frontend/src/components/kb/SearchTest.vue — 扩展检索测试
- src/agentkit/server/frontend/src/components/kb/SourceConfig.vue — 扩展 ACL 配置（现有组件，可能需扩展以支持 per-KB ACL 设置）
- src/agentkit/server/frontend/src/components/kb/SegmentPreview.vue — 新建分段预览组件
- src/agentkit/server/frontend/src/components/kb/KBSettings.vue — 新建 KB 设置组件
Patterns: 现有 Ant Design Vue 组件模式；WebSocket 推送文档处理状态（复用现有 ws 协议）。
Test scenarios:
- 上传后显示处理进度（pending→parsing→...→indexed）
- 分段预览显示分段结果（只读）
- 检索测试支持三模式切换
- KB 设置可配置检索模式默认/命中处理默认/授权用户
- 文档处理失败时显示 failed 状态 + error_message
- 失败文档可触发重试（UI 按钮 → 重新提交 TaskIQ 任务）
- 任务历史列表可查看（按 KB/时间筛选，显示状态/耗时/错误）
Verification: npm run typecheck + 手动验证

P2: 平台触达扩展

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

Goal: 创建 MessageAdapter ABC + secrets store 基础设施。
Files:
- src/agentkit/channels/__init__.py — 模块入口
- src/agentkit/channels/base.py — MessageAdapter ABC（receive_message/send_message/verify_signature/close，与 KBAdapter 的 authenticate()/close() 生命周期方法对齐 — verify_signature() 对应 authenticate()）
- src/agentkit/channels/secrets.py — 加密 DB 列 secrets store
- src/agentkit/server/routes/channels.py — 渠道管理端点
Patterns: MessageAdapter 应为 ABC（与 KBAdapter 模式一致），不是 Protocol。加密 DB 列按 KTD8 更新：AES-256-GCM + per-row 96-bit nonce，envelope encryption 或 HKDF with per-row salt。渠道管理端点必须复用 require_permission（管理员级 CRUD 权限）。Webhook 端点必须实现重放攻击保护：验证请求时间戳（拒绝超出窗口的请求，飞书 5 分钟、钉钉 1 小时）+ nonce 去重（Redis 缓存已见 nonce，TTL 与时间戳窗口一致）。渠道 onboarding 前端需新增 ChannelConfig.vue 组件（管理员导航→选择平台→输入凭证→系统生成 webhook URL→连通性测试），归入 U10 范围。
Webhook fail-closed: webhook 端点在 Redis 不可用时必须返回 503（fail-closed），不可跳过 nonce dedup 直接处理消息。
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）。
Rate limiting: webhook 端点必须在签名验证前应用 per-IP rate limiting（默认 100 req/min），超限返回 429。
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）。
Rate limiting: webhook 端点必须在签名验证前应用 per-IP rate limiting（默认 100 req/min），超限返回 429。
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 工具。向后兼容：现有独立 mcp/server.py 的客户端可能硬编码旧路径，迁移期间保留旧路径的 301 重定向到 /api/v1/mcp/（至少 1 个版本周期），并在发布说明中标注破坏性变更。
API Key → permission mapping: MCP 必须使用 per-client API keys（非全局 server key），每个 key 绑定到一个 synthetic principal，带显式 permission scope（Permission bits 的子集）和可选 KB-allowlist。MCP per-client API keys 必须存储在 U10 的加密 secrets store 中（非 clients.yaml 明文）。pair CLI 命令应扩展以 mint MCP-scoped keys。
Port-change breakage: 现有 mcp/server.py 运行在 port 8080；合并到主 app（port 8001）会破坏硬编码端口的客户端。要么保留 reverse-proxy/redirect 从 8080 → 主 app，要么文档化 port 8080 deprecation 与迁移时间线。
MCP endpoint permission levels: tools/list = member，tools/call = member，publish = Permission.SYSTEM_CONFIG（注意：Permission.ADMIN 不存在 — admin role 拥有 SYSTEM_CONFIG 权限）。
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 工具。
Depends on: U13（U14 扩展 mcp/server.py，U13 先重构该文件 — U13 必须先完成）
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.SYSTEM_CONFIG（admin role 拥有此权限；Permission.ADMIN 不存在）— 或在 enum 中新增 Permission.MCP_PUBLISH。配置字段（工具名称/描述/输入 schema/鉴权方式/速率限制）。
Dangerous tools: 包装危险工具（terminal、file）的已发布 Skill 必须要求显式 per-tool admin approval，并默认排除出 MCP 发布，需 opt-in flag。
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 适配器。
Depends on: U10（凭证迁移到 secrets store 要求 U10 的 secrets store 先建好）
Files:
- src/agentkit/llm/providers/ — 重写为 LiteLLM 统一接口（package 目录，含 6 个 provider 模块 + tracker.py + usage_store.py）。明确排除 tracker.py 和 usage_store.py 出 rewrite 范围（usage tracking 保留）。
- src/agentkit/llm/gateway.py — 适配上层网关逻辑
- src/agentkit/llm/config.py — provider 配置更新
Patterns: LiteLLM completion() / acompletion() 统一接口；保留自研 fallback 链/用量追踪/部门级配额；RemoteLLMProvider 保留不动。本单元同时负责迁移现有明文 ProviderConfig.api_key 到 U10 的加密 secrets store（读取现有 DB 列 → 加密写入 → 验证 → 删除明文列或标记 deprecated）。
Migration safety: dual-write/dual-read 窗口 — 新加密列与明文列并行写入；读取优先 encrypted，fallback 到 plaintext。明文列在每行加密值验证后立即用 NULL 覆盖（非仅标记 deprecated）。明文列在迁移完成（100% 行迁移+验证）后的下一个 release 中 drop。per-row 迁移状态 flag 用于 partial-failure resume。文档化 rollback procedure。
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 替换自研语义缓存。
Depends on: U15（U17 修改 gateway.py 缓存配置，U15 也修改 gateway.py — U15 必须先完成 provider 替换，U17 在此基础上叠加缓存配置）；U6（per-KB "caching disabled" flag 在 U6 KB 设置中定义，U17 必须读取此 flag）
Files:
- src/agentkit/llm/cache.py — 重写为 LiteLLM 缓存配置（或废弃，由 gateway 直接配置）
- src/agentkit/llm/gateway.py — 集成 LiteLLM caching 配置
Patterns: LiteLLM RedisSemanticCache；阈值调优（默认 0.87）；缓存 key 必须显式配置包含 system prompt + temperature（LiteLLM 默认 cache key 排除 system prompt，会导致不同 system prompt 的查询误命中缓存 — 需通过 cache_params 显式覆盖）。
Security & confidentiality (reframed from quality): 缓存风险本质是 SECURITY/confidentiality 问题，非仅质量问题。要求：
- (a) cache key 必须包含 tenant/user scope（per-user cache namespace），杜绝跨用户碰撞。
- (b) 对源自 ACL-scoped KBs 的 model_opt 响应，要么禁用缓存，要么在 cache key 中包含 KB-ACL-scope hash（hash 必须包含 ACL 版本号或 permission-set hash，ACL 变更时必须触发缓存失效）。
- (c) 在 KB 设置（U6）中增加 per-KB "caching disabled" flag。
- (d) LiteLLM 必须以 library mode（in-process）运行 — 若必须 proxy mode，强制 mTLS。
- (e) 测试场景："User A 查询不返回 User B 的缓存响应，即使语义相似。"
Test scenarios:
- 语义相似查询命中缓存
- 不同 system prompt 不命中缓存
- 缓存命中率可统计
- 阈值调优生效
Verification: pytest tests/unit/llm/test_cache.py

Cross-Unit Integration Tests

tests/integration/test_upload_pipeline.py — upload → sanitize → parse → segment → vectorize → index → retrieve（覆盖 U3+U7+U4）
tests/integration/test_llm_gateway_e2e.py — LiteLLM provider + fallback + cache + usage tracking + quota（覆盖 U15+U17）
tests/integration/test_mcp_e2e.py — auth + published Skill tool + existing tool call（覆盖 U13+U14）
tests/integration/test_rag_agent_runtime.py — Agent → MemoryRetriever → rag_platform retrieval with ACL（覆盖 U2+U4+RetrievalPrincipal）
所有测试按项目约定标记 @pytest.mark.integration。

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/团队。
Agent runtime retrieval path: MemoryRetriever rewire + user-context propagation for ACL（RetrievalPrincipal 概念，见 KTD11）。
向后兼容: LocalRAGService 对 KB 场景废弃但保留（Agent 记忆仍用）；RemoteLLMProvider 保留不动；现有 ToolRegistry 工具仍可通过 MCP 访问。

Redis Resource Isolation

每个 consumer 的 key-prefix 契约：taskiq:、litellm-cache:、bus:、wm:。每 consumer 的内存预算估算（尤其 LiteLLM semantic cache 存储 embeddings）。必需的 maxmemory-policy：推荐 noeviction 用于 TaskIQ broker — fail loud 而非静默丢任务。LiteLLM semantic cache 应使用独立 Redis DB index（如 db=2）以隔离内存压力。

Risks & Dependencies

LlamaIndex breaking changes: LlamaIndex 频繁发布 breaking changes。缓解：版本锁定（pyproject.toml pin major version）+ 集成测试覆盖核心管道。
jieba 中文分词质量: jieba 默认词典可能不覆盖领域术语。缓解：术语表通过 jieba.load_userdict() 扩展；检索测试覆盖中文场景。
TaskIQ 成熟度: TaskIQ 社区较小（~2k★）。缓解：API 简单，必要时可替换为 SAQ（asyncio-native）或 Dramatiq（async adapter）。注意 ProcessPoolExecutor 不可作为 fallback — 它不兼容 asyncio 事件循环（会在 worker 中阻塞），仅适用于 CPU-bound 同步任务。
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 代码）。
Redis outage: bus + TaskIQ + cache + WorkingMemory 同时失败 — 缓解：Redis HA（Sentinel/Cluster）是生产环境的硬依赖，或接受 degraded mode 并文档化 blast radius。
MCP API Key scope creep: 全局 key 复用授予无界访问。缓解：per-client API keys 带显式 permission scope。
TaskIQ worker compromise via malicious document: 缓解：argument validation、resource caps、error sanitization、worker privilege separation。
LiteLLM semantic cache cross-tenant data leakage: 缓解：per-user cache namespace、ACL-scope hash in cache key、per-KB caching-disable flag。
Master key leakage: 需 incident-response runbook：detection、emergency re-encrypt、historical-credential revocation。（从 Deferred 提升。）
Document parsing supply-chain attacks (zip bombs, XXE, SSRF): 缓解：decompression limits、XML hardening、egress filtering。

Open Questions

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

Deferred / Open Questions

From 2026-06-24 review

Master key 泄露恢复流程未定义 — KTD8/U10 (P1, security-lens, confidence 75)

KTD8 定义了 master key 轮换的双密钥窗口策略，但未定义 master key 泄露后的恢复流程。泄露场景下所有加密凭证需立即 re-encrypt 到新 key，但旧 key 已泄露意味着历史数据暴露。需定义：泄露检测机制、紧急轮换流程、历史凭证失效策略、审计追溯。
Per-KB ACL 与部门过滤器交互未解决 — U2/KTD5 (P1, adversarial, confidence 75)

KTD5 定义 per-KB ACL（owner/viewer）与部门级过滤并行运行，但两者交互未明确。当用户属于部门 A 且被授权 KB X（属于部门 B）时，ACL 过滤是否覆盖部门过滤？部门过滤是否作为 ACL 的前置筛选？交集还是并集？需在 U2 实施前明确语义。
R17 与 origin 的缓存决策相矛盾 — R17/KTD7 (P1, product-lens, confidence 75)

Origin 需求文档中缓存策略是"保留自研语义缓存"，但 R17 将其替换为 LiteLLM 内置 Redis Semantic Cache。KTD7 已调和（P1/P2 保留自研，P3 替换），但 origin 文档未更新。需确认 origin 文档是否同步修订，或在本计划中标注 origin 偏离。
kb_acl 存储位置与 KB 数据存储不一致 — U2 (P2, feasibility, confidence 75)

U2 将 kb_acl 表放在 server/auth/models.py（现有 auth SQLite？），但 KB 元数据在 PostgreSQL。跨库 JOIN 不可行，ACL 过滤需应用层两次查询。需确认 server/auth/models.py 的实际数据库后端，或将 kb_acl 移至 rag_platform/ PG schema。
语义缓存保留期和敏感数据策略缺失 — U17 (P2, security-lens, confidence 75)

U17 用 LiteLLM Redis Semantic Cache 替换自研缓存，但未定义缓存保留期（TTL）和敏感数据策略。语义缓存可能存储包含 PII 的 LLM 响应，Redis 持久化策略需明确：TTL 上限、敏感 KB 禁用缓存选项、缓存清除 API。
Per-tool MCP auth 方法未充分指定 — U14 (P2, security-lens, confidence 75)

U14 配置字段包含"鉴权方式"但未列举可选值。MCP 工具的 per-tool auth 是 API Key、JWT、还是 OAuth？不同鉴权方式的客户端体验和密钥管理差异显著。需在 U14 实施前枚举支持的 auth 方法及其适用场景。
Standalone MCP auth middleware 未考虑 — U13 (P2, adversarial, confidence 75)

U13 将 MCP Server 合并至主 app 并复用 require_permission，但现有 mcp/server.py 作为独立 app 运行时（如开发模式或独立部署）的 auth middleware 未考虑。合并后是否完全废弃独立运行模式？若保留，独立模式如何复用主 app 的 auth 依赖？
扩展 LocalRAGService vs 替换未考虑 — U1/KTD9 (P2, adversarial, confidence 75)

KTD9 新建 rag_platform/ 并废弃 LocalRAGService 对 KB 场景的使用。但 LocalRAGService 已有 pgvector 集成、分块、嵌入逻辑。是否考虑扩展 LocalRAGService 而非新建模块？新建意味着代码重复（解析/嵌入/检索逻辑），扩展意味着职责混合（Agent 记忆 + KB 场景）。需确认新建的收益超过重复成本。
Preview 确认 vs 自动转换未解决 — U9 (P2, design-lens, confidence 75)

状态机图显示 segmenting → vectorizing: 预览确认/自动，但 U9 前端未明确：预览后是必须用户确认才向量化，还是可配置自动转换？默认行为是什么？自动转换时预览是否仍展示？需在 U9 实施前明确交互模式。

From 2026-06-24 review (Round 2)

Alembic migration infrastructure not present in codebase — U2/U15 (P1, feasibility, confidence 75)

Plan references SQLAlchemy async migrations and "dual-write/dual-read" migration windows for U15, but the codebase has no Alembic setup. U2 creates new PG tables (kb_acl, KB metadata) and U15 migrates ProviderConfig.api_key — both need schema migrations. Implementer must either introduce Alembic or document the manual DDL approach. Affects: U2, U15, and any unit adding/modifying DB schema.
Cross-database breakage: department_kb_bindings in SQLite vs KB metadata in PG — U2 (P1, feasibility, confidence 75)

Existing department_kb_bindings may live in SQLite (default config) while U2 moves KB metadata to PostgreSQL. Cross-database JOINs are impossible. Need to either migrate department_kb_bindings to PG in U2 or document the single-DB (PG-only) deployment requirement. Check server/auth/models.py and current DB config before implementing.
pair CLI stores API keys in plaintext YAML — U13 (P2, security-lens, confidence 75)

U13 requires MCP per-client API keys to be stored in U10's encrypted secrets store, but the existing pair CLI command (cli/ module) writes API keys to plaintext YAML files. The plan does not address migrating the pair CLI output to the encrypted store. Implementer must update pair CLI to write to the secrets store or document the transition path.
MemoryRetriever rewiring + RetrievalPrincipal no owning unit — KTD9/KTD11 (P2, coherence, confidence 75)

KTD9 states "MemoryRetriever 将在新的单元中重新接线" but no implementation unit claims ownership of this rewiring. KTD11 defines RetrievalPrincipal but no unit explicitly implements it as a standalone component — it's implied across U4/U10/U14. Implementer must decide: create a new unit, or fold RetrievalPrincipal into U1/U4 and MemoryRetriever rewiring into U4. Risk: both get dropped silently.
LlamaIndex jieba SentenceSplitter integration unverified — U3/KTD6 (P2, feasibility, confidence 50)

KTD6 chooses application-layer jieba tokenization for PG full-text search, and U3 uses LlamaIndex IngestionPipeline for segmentation. Whether LlamaIndex's SentenceSplitter can be composed with jieba tokenization for Chinese text is unverified. If LlamaIndex's splitter doesn't support custom tokenizers, a custom transformation node or pre-processing step is needed. Implementer should spike this in U1/U3 before committing to the approach.
MCP 301 redirect port 8080 requires standalone listener — U13 (P3, feasibility, confidence 50)

U13's backward compatibility plan offers "301 重定向从旧路径" but the existing mcp/server.py runs on port 8080 while the main app runs on port 8001. A 301 redirect from port 8080 requires a standalone listener on that port, which defeats the purpose of merging into the main app. Implementer should either: (a) document port 8080 deprecation without redirect, (b) use a reverse proxy, or (c) run a minimal redirect-only listener on 8080 during the transition period.

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）

52 KiB Raw Blame History Unescape Escape