fischer-agentkit/docs/brainstorms/2026-06-24-portal-platform-evolution-requirements.md

date	topic
2026-06-24	portal-platform-evolution

AgentKit 门户平台整体演进路线

Summary

按优先级串行推进 AgentKit 门户平台演进：先建独立 RAG 平台对标 MaxKB 功能对等，再扩展多端接入与 MCP Server，最后生态替换降本（MCP/Celery/LiteLLM）。不设硬性时间，按完成度推进。

Problem Frame

AgentKit 定位为企业级统一 AI Agent 门户平台，面向企业用户与开发者。对标 MaxKB（开源企业级智能体平台，GitHub 19k+ stars）后发现，当前能力堆栈在多个方向存在差距：

• RAG 工业级管道：AgentKit 现有 memory/ 模块是开发者级组件库（基础分块 + pgvector 语义检索 + time_decay 重排），MaxKB 是工业级产品功能（双索引检索 + 智能分段 + 问题生成 + 术语表 + 命中处理模式）。RAG 是门户平台服务企业知识库场景的底线能力。
• 平台触达：AgentKit 仅有飞书/Confluence/通用 HTTP 三种 RAG 适配器，MaxKB 原生支持企微/钉钉/飞书/Slack 多端接入。门户平台需要触达企业现有协作工具。
• MCP Server：AgentKit 已有 MCP Client（mcp/client.py）和 MCP Server（mcp/server.py）基础实现，但尚未将 Skill/专家团队发布为 MCP 工具。门户平台应完善 MCP Server 的 Skill/专家团队发布能力。
• 自研 vs 生态：AgentKit 大量自研（Agent 引擎/LLM 网关/工作流画布/MCP 客户端/记忆系统/消息总线），commodity 层维护成本高。

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

Key Decisions

串行演进策略（方案 A）。 按优先级串行推进，每个方向充分交付后再进入下一个。理由：用户要求"对标 MaxKB 功能对等"，MVP 驱动难以一次达标；不设硬性时间契合串行节奏；预防性演进无紧急压力，可保障交付质量。

RAG 平台并行独立。 新建独立 RAG 平台模块，现有 memory/ 保留给 Agent 记忆（WorkingMemory/EpisodicMemory/SemanticMemory）。理由：职责分离，避免 RAG 与 Agent 记忆耦合；RAG 平台作为门户平台基础设施服务于企业用户知识库场景，Agent 记忆服务于 Agent 运行时。

开放引入生态依赖。 commodity 层优先用生态，降低维护成本。约束：需注意开源协议合规，且对已完成或进行中的特性保持向后兼容。差异化层（Agent 引擎/专家团队/自进化/终端安全）保持自研。

保留现有工作流。 FlowCanvas 不替换为 LogicFlow，现有工作流画布保持自研。理由：避免破坏现有节点类型（SkillNode/ApprovalNode/ConditionNode/ParallelNode）和工作流。

对标 MaxKB 功能对等。 RAG 工业级管道的成功标准是功能对等：双索引检索/智能分段/问题生成/术语表/命中处理模式/rerank 全部具备。

Requirements

RAG 工业级管道（优先级 1）

R1. 新建独立 RAG 平台模块，与现有 memory/ 模块职责分离，现有 memory/ 保留给 Agent 记忆使用。现有 memory/local_rag.py 的 LocalRAGService（pgvector + 分块 + 嵌入 + 语义检索）需明确迁移策略：吸收/扩展至新平台、提取至新模块、或新建并废弃 LocalRAGService。

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

R3. 在 RAG 平台模块中实现智能分段与高级分段能力（可参考现有 memory/chunking.py 的分块基础），提供分段预览能力，企业用户可在向量化前查看分段结果。

R4. 支持问题自动生成：为文档段落自动生成相关问题/问法，提升检索召回率。

R5. 支持术语表（Termbase）：通过全文检索分词增强，提升中文场景检索准确率。

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

R7. 支持 rerank 重排：检索结果经 rerank 模型重排后返回，提升相关性排序。

R8. 扩展现有 KnowledgeBaseView/DocumentUpload/SearchTest 组件，提供可视化文档管理：文档上传/分段预览/检索测试，企业用户可通过前端界面管理知识库。知识库必须实施 per-KB 访问控制（owner/authorized-users），Agent 检索必须限定于调用用户授权的知识库。文档上传必须验证文件类型（白名单）、强制大小限制、并在索引前净化解析内容（markdown sanitize、PDF 解析安全）。

平台触达扩展（优先级 2）

R9. 支持多端消息接入：企微/钉钉/飞书/Slack 消息适配器，企业用户可通过现有协作工具使用 AgentKit。各平台适配器必须验证平台提供的请求签名/token（飞书 encrypt_key、钉钉 token、企微信 EncodingAESKey）后处理消息，拒绝未认证请求。所有第三方平台凭证必须存储于 secrets store（非明文配置），定义轮换策略与访问审计。

R10. 完善现有 MCP Server（mcp/server.py）：支持将 Skill/专家团队发布为 MCP 工具，供外部 AI 系统调用。MCP 工具调用必须要求认证与授权（复用现有 JWT+RBAC 或 API Key 机制），发布 Skill/专家团队为 MCP 工具需管理员级授权。

生态替换降本（优先级 3）

目标：将 commodity 层（MCP 客户端/异步任务/LLM Provider 适配）迁移至生态方案，降低自研维护成本，使团队聚焦差异化能力。成功标准：替换后现有功能行为不变，维护代码量减少。

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

R12. 引入 Celery 异步任务：与现有 asyncio 原生共存，承接文档向量化/批量任务（利用现有 Redis 作为 broker，不引入新基础设施），提供任务持久化/重试/调度能力。提供异步任务可视化：进度展示、失败通知与重试、任务历史。

R13. LLM Provider 底层替换为 LiteLLM：上层网关逻辑（fallback/缓存/用量追踪）保留自研，底层 provider 适配走 LiteLLM 统一接口。

Actors

A1. 企业用户 — 通过前端界面管理知识库（上传文档/配置分段/测试检索）、配置多端接入、发布 MCP 工具。

A2. 开发者 — 通过 API/MCP Server 集成 AgentKit 能力到外部系统。

A3. Agent — 运行时调用 RAG 平台检索知识库内容，支撑问答与决策。

Key Flows

F1. RAG 文档处理流程

• Trigger: 企业用户上传文档到知识库。
• Actors: A1, A3
• Steps: 文档解析 → 分段（智能/高级）→ 分段预览 → 向量化 → 全文索引建立 → 问题自动生成 → 可用。
• Outcome: 文档进入知识库，可被 Agent 检索。

F2. RAG 检索流程

• Trigger: Agent 需要检索知识库回答用户问题。
• Actors: A3
• Steps: 查询接收 → 检索模式选择（embedding/keywords/blend）→ 双索引检索 → rerank 重排 → 命中处理（模型优化/直接回答）→ 返回结果。
• Outcome: Agent 获得相关知识库内容。

F3. 多端消息接入流程

• Trigger: 企业用户通过企微/钉钉/飞书/Slack 发送消息。
• Actors: A1, A3
• Steps: 消息适配器接收 → 转换为 AgentKit 标准格式 → Agent 处理 → 响应转换为目标平台格式 → 返回。
• Outcome: 企业用户通过协作工具获得 Agent 响应。

F4. MCP Server 发布流程

• Trigger: 企业用户或开发者将 Skill/专家团队发布为 MCP 工具。
• Actors: A1, A2
• Steps: 选择 Skill/专家团队 → 配置 MCP endpoint → 发布 → 外部 AI 系统可通过 MCP 协议调用。
• Outcome: AgentKit 能力通过 MCP 协议对外输出。

Scope Boundaries

Deferred for later

• 本地模型支持（Ollama）——后续迭代，服务企业私有化部署场景。
• 现有 memory/ 模块重构——保留给 Agent 记忆用，不在本次演进范围。

Outside this product's identity

• FlowCanvas→LogicFlow 替换——保留现有工作流，不替换。
• Agent 引擎（ReActEngine/ReWOO/Reflexion/PlanExec）——保持自研，是核心差异化能力。
• 专家团队编排（流水线 + 私董会）——保持自研，生态无对应方案。
• 自进化系统（16 组件）——保持自研，独有能力。
• 终端安全（6 层白名单）——保持自研，安全必须自主可控。

Dependencies / Assumptions

• 开源协议合规：生态替换涉及的依赖协议需宽松可商用。Celery (BSD-3)、LiteLLM (MIT)、langchain-mcp-adapters 需确认协议。（注：LogicFlow 已因保留 FlowCanvas 决策排除，非协议原因——Apache-2.0 本身可商用）
• 现有特性向后兼容：生态替换（MCP 客户端/Celery/LiteLLM）不能破坏现有功能，需提供迁移路径。
• pgvector 基础设施：RAG 平台与现有 EpisodicMemory 共用 pgvector 基础设施，但数据模型独立。
• 前端组件复用：现有 KnowledgeBaseView/DocumentUpload/SearchTest 组件可能需要重构以支撑 RAG 平台可视化文档管理。

Outstanding Questions

Resolve Before Planning

• [P0 安全] MCP Server 端点缺少认证/授权决策：R10 暴露 Skills/Expert Teams 为 MCP 工具，F4 描述发布流程但未提及认证、授权、限流或访问控制。未认证的 MCP 端点允许任何可达客户端调用 Skills、读取 Expert Team 输出，若工具具备文件系统或 shell 访问权限则构成远程代码执行面。需在规划前明确：认证方案（API Key / JWT 复用 / OAuth / mTLS）、授权模型（按 skill / team / tenant）、限流策略。（ce-doc-review 延期，security-lens，置信度 100）
• [P0 安全] 多端消息适配器缺少输入验证：R9 多平台消息接入（飞书/钉钉/企业微信），F3 未提及签名校验、来源认证或速率限制。外部平台消息为不可信输入边界，缺少验证允许伪造消息、注入恶意内容、触发未授权 Skill 执行。需在规划前明确：各平台签名机制（飞书 encrypt_key、钉钉 token、企微信 EncodingAESKey）、消息格式校验、重放攻击防护。（ce-doc-review 延期，security-lens，置信度 100）
• [P0 安全] 文档上传缺少内容净化：R1/R7 涉及用户上传文档（PDF/Word/Markdown/TXT），需求未提及内容净化、恶意文件检测或大小限制。上传文档可能包含恶意脚本（XSS via markdown）、超大文件导致 OOM、嵌入恶意宏。需在规划前明确：文件类型白名单、大小限制、内容扫描、markdown sanitize、PDF 解析安全。（ce-doc-review 延期，security-lens，置信度 100）

Deferred to Planning

• 飞书消息接入适配器与现有飞书 RAG 适配器（memory/adapters/feishu.py）的复用程度——后续确认。
• RAG 平台数据模型（Knowledge/Document/Paragraph/Problem/Embedding）的具体设计——ce-plan 决策。
• Celery 与现有 asyncio 原生的共存策略——ce-plan 决策。
• LiteLLM 与现有自研 Provider 的迁移路径——ce-plan 决策。
• [P1 战略] 对标 MaxKB ≠ 竞争力：功能对等是底线而非差异化。需明确 AgentKit 相对 MaxKB 的差异化定位（专家团队/自进化/终端安全等独有能力如何与 RAG 平台协同）。（ce-doc-review 延期，product-lens，置信度 75）
• [P1 前提] 演进前提缺少用户痛点证据：文档以"对标 MaxKB 发现差距"为前提，但未提供用户痛点证据（用户反馈/流失原因/竞品丢失原因）。需确认：是否有用户因缺少 RAG/多端/MCP Server 而流失或抱怨？（ce-doc-review 延期，product-lens，置信度 75，ROOT）
• [P1 前提] 未评估"不做"基线：未评估不执行此演进计划的后果。需确认：若不演进，AgentKit 的实际损失是什么？（ce-doc-review 延期，adversarial，置信度 75，DEPENDENT）
• [P1 战略] 同质化追赶 vs 差异化构建：RAG/多端/MCP Server 是 commodity 能力，MaxKB 已有。需确认：投入大量资源追赶 commodity 是否优于强化差异化能力？（ce-doc-review 延期，product-lens，置信度 75）
• [P1 战略] 重建 MaxKB 缺乏正当性论证：RAG 平台并行独立意味着重建 MaxKB 已有的工业级管道。需确认：为何不直接集成 MaxKB 或 fork？（ce-doc-review 延期，adversarial，置信度 75，ROOT）
• [P1 基础设施] 并行 RAG 平台导致基础设施翻倍：独立 RAG 平台与现有 memory/ 共用 pgvector 但数据模型独立，可能导致维护两套 RAG 基础设施。需确认：长期是否合并？（ce-doc-review 延期，product-lens，置信度 75，DEPENDENT）
• [P1 设计] RAG 平台信息架构未定义：RAG 平台的前端信息架构（知识库列表/文档管理/检索测试/配置页）未定义。归 ce-plan 设计。（ce-doc-review 延期，design-lens，置信度 75）
• [P1 设计] 多端配置流程缺失：R9 多端消息接入缺少配置流程（如何添加平台/配置凭证/测试连通性）。归 ce-plan 设计。（ce-doc-review 延期，design-lens，置信度 75）
• [P1 安全] 知识库访问控制未指定：R8 可视化文档管理未指定访问控制（谁可查看/编辑/删除知识库）。需明确 RBAC 模型。（ce-doc-review 延期，security-lens，置信度 75）
• [P1 安全] 适配器凭证管理未定义：R9 多端适配器需要管理各平台 API 凭证（app_id/app_secret/token），需求未提及凭证存储与轮换。归 ce-plan 设计。（ce-doc-review 延期，security-lens，置信度 75）
• [P1 安全] MCP 发布授权未指定：R10 MCP Server 发布流程未指定谁有权发布 MCP 工具。需明确发布权限模型。（ce-doc-review 延期，security-lens，置信度 75）
• [P1 技术] PG 全文检索对中文不适用：R2 依赖 PostgreSQL 全文检索，但 PG 原生全文检索对中文支持差（缺中文分词）。需确认：是否使用 pg_jieba/zhparser 扩展或外部搜索引擎？（ce-doc-review 延期，feasibility，置信度 75）
• [P1 优先级] R12 优先级阻断 P1 交付：R12（Celery）在 P3，但 R1-R8（RAG 管道）的文档向量化需要异步任务能力。需确认：P1 是否依赖 R12？（ce-doc-review 延期，scope-guardian，置信度 75）
• [P2 证据] Celery 替换缺少必要性证据：R12 引入 Celery 但未提供 asyncio 原生不足的证据（具体场景/性能瓶颈/故障案例）。需补充必要性论证。（ce-doc-review 延期，feasibility，置信度 75）
• [P2 量化] LiteLLM 节省未量化：R13 引入 LiteLLM 但未量化节省（维护代码量/开发效率/兼容 provider 数）。需补充量化数据。（ce-doc-review 延期，feasibility，置信度 75）
• [P2 设计] MCP 配置流程未指定：R10 MCP Server 发布流程缺少配置细节（endpoint 路径/工具命名/参数定义）。归 ce-plan 设计。（ce-doc-review 延期，design-lens，置信度 75）
• [P2 设计] 分块预览未定义：R3 分段预览的交互模式未定义（预览界面/编辑能力/重新分段）。归 ce-plan 设计。（ce-doc-review 延期，design-lens，置信度 75）
• [P2 技术] 消息总线替换未处理：现有 bus/（MemoryBus/RedisBus）在生态替换中未提及。需确认：是否保留自研？（ce-doc-review 延期，feasibility，置信度 75）
• [P2 技术] Rerank 模型未处理：R7 rerank 未指定模型（本地/API/开源）。归 ce-plan 决策。（ce-doc-review 延期，feasibility，置信度 75）
• [P1 战略] MaxKB 对等框架解决错误问题：MaxKB 是 RAG 知识库产品，AgentKit 是 Agent 平台。对标不同产品类别的功能对等可能构建不服务于实际用户的能力。需重构为用户结果导向的成功标准。（ce-doc-review 第 2 轮延期，product-lens+adversarial，置信度 100）
• [P1 战略] 串行策略饿死差异化投入：串行执行意味着差异化能力（Agent 引擎/专家团队/自进化）在 P1/P2 完成前零投入。需考虑预留差异化并行轨道。（ce-doc-review 第 2 轮延期，product-lens，置信度 75）
• [P1 战略] Build-vs-buy 未评估：R1-R8 从零构建工业级 RAG 管道，未评估集成 MaxKB 或采用 RAG 框架（LlamaIndex/Haystack）。需补充 build-vs-buy 评估。（ce-doc-review 第 2 轮延期，product-lens+adversarial，置信度 100）
• [P1 前提] 核心替换向后兼容性是假设非验证：R11/R12/R13 替换三个核心组件但假设"现有功能行为不变"。现有 LLM 网关有 6 provider + fallback + 语义缓存 + RemoteLLMProvider 代理。需将向后兼容从假设转为验证前提。（ce-doc-review 第 2 轮延期，adversarial，置信度 75）
• [P1 设计] 文档处理失败状态缺失：F1 未定义解析失败/不支持格式/向量化错误的用户可见状态。归 ce-plan 设计。（ce-doc-review 第 2 轮延期，design-lens，置信度 75）
• [P1 设计] 分段预览交互模式未定义：R3 "查看分段结果"是只读还是可编辑（合并/拆分/重新分段）未定义。归 ce-plan 设计。（ce-doc-review 第 2 轮延期，design-lens，置信度 75）
• [P1 设计] 多端配置与认证流程缺失：F3 缺少多端 onboarding 流程（webhook 配置/OAuth/app 凭证/连通性测试）。归 ce-plan 设计。（ce-doc-review 第 2 轮延期，design-lens，置信度 75）
• [P2 战略] 维护成本痛点延期至 P3：Problem Frame 声明"commodity 层维护成本高"但解决方案在最低优先级 P3。需考虑将高杠杆替换（如 LiteLLM）提前并行。（ce-doc-review 第 2 轮延期，product-lens，置信度 75）
• [P2 战略] R11-R13 是技术债非产品需求：R11-R13 成功标准是"现有功能行为不变"（零用户可见影响），无 Actor 受益。需考虑移至独立工程债轨道。（ce-doc-review 第 2 轮延期，product-lens，置信度 75）
• [P2 战略] 门户触达(P2)反转门户价值主张：门户平台的核心价值是触达，但多端接入在 P2。需考虑在 P1 并行交付至少一个高价值渠道。（ce-doc-review 第 2 轮延期，product-lens，置信度 75）
• [P2 技术] Celery 缺乏必要性论证：R12 引入 Celery 但未论证 asyncio 不足。文档向量化是 CPU-bound（可用 ProcessPoolExecutor），批量任务是 I/O-bound（asyncio 强项）。需补充具体场景。（ce-doc-review 第 2 轮延期，scope-guardian+adversarial，置信度 75）
• [P2 技术] LiteLLM 替换覆盖缺口：R13 未评估 LiteLLM 对 6 个现有 provider（尤其 Doubao/Wenxin/Yuanbao）的覆盖，以及语义缓存/用量追踪/RemoteLLMProvider 代理等网关特性。需补充 feature-gap 分析。（ce-doc-review 第 2 轮延期，scope-guardian+adversarial，置信度 75）
• [P2 战略] 串行策略阻断 MCP Server：R10 完善现有 MCP 基础设施，无依赖 RAG 或多端。串行策略将其阻断在两个无关工作流之后。需考虑解耦 R10。（ce-doc-review 第 2 轮延期，adversarial，置信度 75）
• [P2 设计] MCP 发布配置细节未定义：F4 "配置 MCP endpoint"未定义配置字段（工具名称/描述/输入 schema/鉴权方式/发布前测试）。归 ce-plan 设计。（ce-doc-review 第 2 轮延期，design-lens，置信度 75）
• [P2 设计] 新 RAG 平台门户 IA 未定义：R1 新建独立 RAG 平台模块，但未定义其在门户导航中的位置（顶级 section 还是扩展现有知识库管理区）。归 ce-plan 设计。（ce-doc-review 第 2 轮延期，design-lens，置信度 75）

Sources / Research

• MaxKB 系统架构：https://maxkb.cn/docs/v1/system_arch/
• MaxKB 技术解析：https://juejin.cn/post/7650428235188420651
• MaxKB GitHub：https://github.com/1Panel-dev/MaxKB
• AgentKit 代码库：memory/（RAG 基础组件）、server/routes/（22 路由模块）、src/agentkit/server/frontend/src/components/（前端组件）
• AgentKit 项目规则：AGENTS.md、CLAUDE.md