--- version: 2.0 last-updated: 2026-03-09 status: design --- # 07 — 知识库 · 工作流 · 插件（服务器能力代理） ## 一、设计定位 > **客户端不复制服务器的全部功能，而是提供一体化的使用体验和便捷配置入口。** > > 知识库、工作流、插件的核心逻辑（文档解析、节点执行、插件运行）均在**服务器**完成。 > 客户端的职责是： > > 1. **便捷配置** — 提供友好的 UI 配置入口，以替代切换到浏览器操作 > 2. **调用代理** — Chat 过程中需要调用知识库/工作流/插件时，代理转发到服务器 > 3. **状态展示** — 展示知识库索引状态、工作流运行状态、插件可用状态 --- ## 二、服务器已有能力 ### 知识库 API（`workspace/qiming/src/services/knowledge.ts`） | 端点 | 能力 | | -------------------------------------------------- | -------------- | | `POST /api/knowledge/config/add` | 创建知识库 | | `POST /api/knowledge/config/update` | 更新知识库配置 | | `POST /api/knowledge/config/list` | 知识库列表 | | `GET /api/knowledge/config/{id}` | 知识库详情 | | `POST /api/knowledge/document/add` | 上传文档 | | `POST /api/knowledge/document/list` | 文档列表 | | `GET /api/knowledge/document/{id}` | 文档详情 | | `POST /api/knowledge/document/generate-qa` | 生成 Q&A | | `POST /api/knowledge/document/generate-embeddings` | 生成嵌入向量 | | `POST /api/knowledge/raw-segment/list` | 分段列表 | | `POST /api/knowledge/raw-segment/add` | 添加分段 | | `POST /api/knowledge/qa/update` | 更新问答 | Agent 组件绑定：`POST /api/agent/component/knowledge/update` ### 工作流 API（`workspace/qiming/src/services/workflow.ts`） | 端点 | 能力 | | ----------------------------------- | -------------- | | `GET /api/workflow/{id}` | 获取工作流详情 | | `POST /api/workflow/update` | 更新工作流信息 | | `POST /api/workflow/publish` | 发布工作流 | | `POST /api/workflow/test-run` | 工作流试运行 | | `GET /api/workflow/node/list/{id}` | 获取节点列表 | | `POST /api/workflow/node/add` | 新增节点 | | `POST /api/workflow/node/execute` | 单节点试运行 | Agent 组件绑定：`POST /api/agent/component/workflow/update` ### 插件 API（`workspace/qiming/src/services/plugin.ts`） | 端点 | 能力 | | ------------------------------ | -------------- | | `POST /api/plugin/add` | 新增插件 | | `POST /api/plugin/http/update` | 更新 HTTP 插件 | | `POST /api/plugin/code/update` | 更新 Code 插件 | | `POST /api/plugin/test` | 插件试运行 | | `GET /api/plugin/{id}` | 插件详情 | | `POST /api/plugin/delete/{id}` | 删除插件 | | `POST /api/plugin/publish` | 发布插件 | Agent 组件绑定：`POST /api/agent/component/plugin/update` --- ## 三、客户端集成策略 ### 3.1 设计原则 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 客户端（用户电脑 / 云电脑） │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 便捷配置 UI (Configuration Portal) │ │ │ │ ── 知识库管理 ── ── 工作流管理 ── ── 插件管理 ── │ │ │ │ 查看/增删知识库 查看绑定的工作流 查看绑定的插件 │ │ │ │ 上传文档 触发试运行 触发试运行 │ │ │ │ 查看索引进度 查看运行日志 查看运行日志 │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ QimingApiClient 代理转发 │ │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ ToolRegistry 工具注册 │ │ │ │ 知识库/工作流/插件 → 注册为可调用工具 │ │ │ │ ChatEngine 调用时 → 代理到服务器执行 │ │ │ └──────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ HTTP API 调用 │ ┌─────────────────────────────────────────────────────────────────┐ │ Qiming Agent OS（服务器） │ │ 知识库引擎 / 工作流引擎 / 插件运行时 │ │ 文档解析 · 向量化 · RAG 查询 · 节点执行 · 插件执行 │ └─────────────────────────────────────────────────────────────────┘ ``` ### 3.2 三种集成模式 | 模式 | 描述 | 适用场景 | | ------------ | ------------------------------------ | ----------------------------- | | **配置代理** | 客户端 UI 操作 → 调用服务器 API | 知识库创建/文档上传/插件新增 | | **调用代理** | ChatEngine 使用工具 → 转发服务器执行 | Chat 中触发工作流/插件/RAG | | **状态缓存** | 定期拉取服务器状态并本地缓存 | 展示知识库索引进度/插件可用性 | --- ## 四、知识库集成 ### 4.1 KnowledgeSyncAdapter ```typescript class KnowledgeSyncAdapter { constructor(private qimingClient: QimingApiClient) {} /** 拉取 Agent 绑定的知识库列表（用于 UI 展示） */ async pullKnowledgeList(agentId: number): Promise { const components = await this.qimingClient.request( "GET", `/api/agent/component/list/${agentId}`, ); const knowledgeComponents = components.filter( (c) => c.type === "knowledge", ); const result: KnowledgeInfo[] = []; for (const kc of knowledgeComponents) { const detail = await this.qimingClient.request( "GET", `/api/knowledge/config/${kc.refId}`, ); result.push(detail); } return result; } /** 上传文档到知识库（客户端提供便捷上传入口） */ async uploadDocument( knowledgeId: number, file: Buffer, filename: string, ): Promise { await this.qimingClient.upload( `/api/knowledge/document/add`, file, filename, ); } /** 查询文档索引进度 */ async getDocumentStatus(docId: number): Promise { return this.qimingClient.request("GET", `/api/knowledge/document/${docId}`); } /** 绑定知识库到 Agent */ async bindToAgent(agentId: number, knowledgeIds: number[]): Promise { await this.qimingClient.request( "POST", "/api/agent/component/knowledge/update", { agentId, knowledgeBaseIds: knowledgeIds }, ); } } ``` ### 4.2 ChatEngine 中的 RAG 调用 当 Chat 需要知识库检索时，通过服务器 API 代理执行： ```typescript class ServerRAGTool implements ToolExecutor { constructor(private qimingClient: QimingApiClient) {} /** 作为 ToolRegistry 中的工具被 ChatEngine 调用 */ async execute( args: { query: string; knowledgeId: number }, context: ToolContext, ): Promise { // 委托服务器做 RAG 检索，客户端不做本地向量化 const result = await this.qimingClient.request( "POST", "/api/knowledge/search", { knowledgeId: args.knowledgeId, query: args.query, topK: 5, }, ); return { success: true, output: result, executionTimeMs: 0, }; } } ``` --- ## 五、工作流集成 ### 5.1 WorkflowProxy ```typescript class WorkflowProxy { constructor(private qimingClient: QimingApiClient) {} /** 拉取 Agent 绑定的工作流列表 */ async pullWorkflowList(agentId: number): Promise { const components = await this.qimingClient.request( "GET", `/api/agent/component/list/${agentId}`, ); const wfComponents = components.filter((c) => c.type === "workflow"); const result: WorkflowInfo[] = []; for (const wc of wfComponents) { const detail = await this.qimingClient.request( "GET", `/api/workflow/${wc.refId}`, ); result.push({ id: detail.id, name: detail.name, description: detail.description, nodeCount: detail.nodes?.length || 0, }); } return result; } /** 触发工作流执行（代理到服务器） */ async executeWorkflow( workflowId: number, params: Record, requestId: string, ): Promise { return this.qimingClient.request("POST", "/api/workflow/test-run", { workflowId, requestId, params, }); } /** 绑定工作流到 Agent */ async bindToAgent(agentId: number, workflowIds: number[]): Promise { await this.qimingClient.request( "POST", "/api/agent/component/workflow/update", { agentId, workflowIds }, ); } } ``` --- ## 六、插件集成 ### 6.1 PluginProxy ```typescript class PluginProxy { constructor(private qimingClient: QimingApiClient) {} /** 拉取 Agent 绑定的插件列表 */ async pullPluginList(agentId: number): Promise { const components = await this.qimingClient.request( "GET", `/api/agent/component/list/${agentId}`, ); const pluginComponents = components.filter((c) => c.type === "plugin"); const result: PluginInfo[] = []; for (const pc of pluginComponents) { const detail = await this.qimingClient.request( "GET", `/api/plugin/${pc.refId}`, ); result.push(detail); } return result; } /** 插件试运行（代理到服务器） */ async testPlugin( pluginId: number, params: Record, ): Promise { return this.qimingClient.request("POST", "/api/plugin/test", { pluginId, ...params, }); } /** 绑定插件到 Agent */ async bindToAgent(agentId: number, pluginIds: number[]): Promise { await this.qimingClient.request( "POST", "/api/agent/component/plugin/update", { agentId, pluginIds }, ); } } ``` --- ## 七、IPC 接口设计 ```typescript // Knowledge（配置代理） 'knowledge:list' → KnowledgeInfo[] 'knowledge:documents' → KnowledgeDocumentInfo[] 'knowledge:upload' → { success: boolean } 'knowledge:bind' → { success: boolean } 'knowledge:status' → { indexed: number; total: number } // Workflow（配置代理 + 调用代理） 'workflow:list' → WorkflowInfo[] 'workflow:execute' → { requestId: string; result: unknown } 'workflow:bind' → { success: boolean } // Plugin（配置代理 + 调用代理） 'plugin:list' → PluginInfo[] 'plugin:test' → PluginTestResult 'plugin:bind' → { success: boolean } ``` --- ## 八、UI 设计要点 ### 一体化配置面板 客户端提供统一的 Agent 组件配置面板，对应服务器 Agent 编排的 7 个 Tab： ``` ┌─ Agent 配置 ──────────────────────────────────────────────┐ │ │ │ [规划] [工具] [技能] [知识] [记忆] [对话] [界面] │ │ │ │ ── 知识库 ────────────────────────────────── │ │ │ 产品文档库 │ 12 文档 │ ✅ 索引完成 │ [上传] │ │ │ API 文档 │ 3 文档 │ ⏳ 索引中 │ [上传] │ │ │ [+ 新建知识库] │ │ │ │ ── 工作流 ────────────────────────────────── │ │ │ 数据分析流程 │ 5 节点 │ ✅ 已发布 │ [试运行] │ │ │ 报告生成流程 │ 8 节点 │ 🔧 开发中 │ [试运行] │ │ │ [+ 绑定工作流] │ │ │ │ ── 插件 ────────────────────────────────── │ │ │ 天气查询 │ HTTP │ ✅ 可用 │ [测试] │ │ │ 代码执行 │ Code │ ✅ 可用 │ [测试] │ │ │ [+ 绑定插件] │ │ │ │ 💡 复杂编辑请使用 Web 端: │ │ https://testagent.xspaceagi.com/space/752/agent/276 │ └────────────────────────────────────────────────────────────┘ ``` > 💡 设计理念：客户端提供 **80% 场景** 的便捷配置。 > 复杂操作（如工作流节点编排、知识库分段策略）引导用户跳转到 Web 端完成。 --- ## 相关文档 - [总体架构](./01-ARCHITECTURE.md) - [Skills & MCP](./03-SKILLS-MCP.md) — MCP / 技能 / 自学工具 - [会话管理](./04-SESSION-CHAT.md) — ChatEngine 调用工具链 - [Agent 自我进化](./06-SELF-EVOLUTION.md) — 记忆系统