---
title: "AgentKit 门户平台整体演进路线"
type: feat
date: 2026-06-24
origin: docs/brainstorms/2026-06-24-portal-platform-evolution-requirements.md
deepened: 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

```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 设置]
        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
```

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

```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。
- **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

1. **门户触达(P2)反转门户价值主张:** 门户平台核心价值是触达，但多端接入在 P2。是否在 P1 并行交付至少一个高价值渠道（如飞书 IM）？默认假设：不并行，P1 聚焦 RAG 管道，P2 再做多端。
2. **R15-R17 是技术债非产品需求:** R15-R17 成功标准是"现有功能行为不变"（零用户可见影响），无 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 → 管理员在平台配置 → 连通性测试。

## 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）