qiming/qimingclaw/crates/agent-electron-client/docs/v2/07-KNOWLEDGE-WORKFLOW-PLUGIN.md

version, last-updated, status

version	last-updated	status
2.0	2026-03-09	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

class KnowledgeSyncAdapter {
  constructor(private qimingClient: QimingApiClient) {}

  /** 拉取 Agent 绑定的知识库列表（用于 UI 展示） */
  async pullKnowledgeList(agentId: number): Promise<KnowledgeInfo[]> {
    const components = await this.qimingClient.request<AgentComponentInfo[]>(
      "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<KnowledgeInfo>(
        "GET",
        `/api/knowledge/config/${kc.refId}`,
      );
      result.push(detail);
    }

    return result;
  }

  /** 上传文档到知识库（客户端提供便捷上传入口） */
  async uploadDocument(
    knowledgeId: number,
    file: Buffer,
    filename: string,
  ): Promise<void> {
    await this.qimingClient.upload(
      `/api/knowledge/document/add`,
      file,
      filename,
    );
  }

  /** 查询文档索引进度 */
  async getDocumentStatus(docId: number): Promise<KnowledgeDocumentInfo> {
    return this.qimingClient.request("GET", `/api/knowledge/document/${docId}`);
  }

  /** 绑定知识库到 Agent */
  async bindToAgent(agentId: number, knowledgeIds: number[]): Promise<void> {
    await this.qimingClient.request(
      "POST",
      "/api/agent/component/knowledge/update",
      { agentId, knowledgeBaseIds: knowledgeIds },
    );
  }
}

4.2 ChatEngine 中的 RAG 调用

当 Chat 需要知识库检索时，通过服务器 API 代理执行：

class ServerRAGTool implements ToolExecutor {
  constructor(private qimingClient: QimingApiClient) {}

  /** 作为 ToolRegistry 中的工具被 ChatEngine 调用 */
  async execute(
    args: { query: string; knowledgeId: number },
    context: ToolContext,
  ): Promise<ToolResult> {
    // 委托服务器做 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

class WorkflowProxy {
  constructor(private qimingClient: QimingApiClient) {}

  /** 拉取 Agent 绑定的工作流列表 */
  async pullWorkflowList(agentId: number): Promise<WorkflowInfo[]> {
    const components = await this.qimingClient.request<AgentComponentInfo[]>(
      "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<IgetDetails>(
        "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<string, unknown>,
    requestId: string,
  ): Promise<unknown> {
    return this.qimingClient.request("POST", "/api/workflow/test-run", {
      workflowId,
      requestId,
      params,
    });
  }

  /** 绑定工作流到 Agent */
  async bindToAgent(agentId: number, workflowIds: number[]): Promise<void> {
    await this.qimingClient.request(
      "POST",
      "/api/agent/component/workflow/update",
      { agentId, workflowIds },
    );
  }
}

---

六、插件集成

6.1 PluginProxy

class PluginProxy {
  constructor(private qimingClient: QimingApiClient) {}

  /** 拉取 Agent 绑定的插件列表 */
  async pullPluginList(agentId: number): Promise<PluginInfo[]> {
    const components = await this.qimingClient.request<AgentComponentInfo[]>(
      "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<PluginInfo>(
        "GET",
        `/api/plugin/${pc.refId}`,
      );
      result.push(detail);
    }

    return result;
  }

  /** 插件试运行（代理到服务器） */
  async testPlugin(
    pluginId: number,
    params: Record<string, unknown>,
  ): Promise<PluginTestResult> {
    return this.qimingClient.request("POST", "/api/plugin/test", {
      pluginId,
      ...params,
    });
  }

  /** 绑定插件到 Agent */
  async bindToAgent(agentId: number, pluginIds: number[]): Promise<void> {
    await this.qimingClient.request(
      "POST",
      "/api/agent/component/plugin/update",
      { agentId, pluginIds },
    );
  }
}

---

七、IPC 接口设计

// 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 端完成。

---

相关文档

• 总体架构
• Skills & MCP — MCP / 技能 / 自学工具
• 会话管理 — ChatEngine 调用工具链
• Agent 自我进化 — 记忆系统