# https://github.com/1Panel-dev/MaxKB 项目说明书

生成时间：2026-06-22 18:50:39 UTC

## 目录

- [项目概览、技术栈与系统架构](#page-overview)
- [知识库管理、文档处理与 RAG 检索](#page-knowledge-rag)
- [应用、对话流水线与 Agentic 工作流引擎](#page-application-workflow)
- [模型提供商、工具、MCP 与扩展机制](#page-model-extension)

<a id='page-overview'></a>

## 项目概览、技术栈与系统架构

### 相关页面

相关主题：[知识库管理、文档处理与 RAG 检索](#page-knowledge-rag), [应用、对话流水线与 Agentic 工作流引擎](#page-application-workflow), [模型提供商、工具、MCP 与扩展机制](#page-model-extension)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/1Panel-dev/MaxKB/blob/main/README.md)
- [apps/tools/api/tool.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/tools/api/tool.py)
- [apps/knowledge/api/knowledge.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/knowledge.py)
- [apps/knowledge/api/knowledge_version.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/knowledge_version.py)
- [apps/knowledge/api/document.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/document.py)
- [apps/knowledge/api/paragraph.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/paragraph.py)
- [apps/knowledge/api/termbase.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/termbase.py)
- [ui/src/api/trigger/trigger.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/trigger/trigger.ts)
- [ui/src/api/system/role.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system/role.ts)
- [ui/src/api/shared-workspace.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/shared-workspace.ts)
- [ui/src/api/type/common.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/common.ts)
- [ui/src/api/type/application.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/application.ts)
</details>

# 项目概览、技术栈与系统架构

## 一、项目定位与目标

MaxKB（Maximally Knowledge Base）是一款面向企业的开源智能体（Agent）平台，旨在帮助开发者与业务团队快速搭建具备知识检索、工具调用与流程编排能力的 AI 应用。根据 [README.md](https://github.com/1Panel-dev/MaxKB/blob/main/README.md) 的描述，MaxKB 的核心目标是"强大易用的企业级智能体平台"，通过将大语言模型（LLM）、向量检索与工作流编排整合在同一系统中，降低企业构建 AI 应用的门槛。

项目以 GPLv3 协议开源，对外提供 Docker 镜像与发布包，支持私有化部署。从代码组织上可以观察到项目同时覆盖了知识库管理、文档处理、工具扩展、应用编排、权限与工作空间管理等模块，是一个面向生产场景的综合平台，而不仅仅是单一功能的工具。

## 二、技术栈

依据 [README.md](https://github.com/1Panel-dev/MaxKB/blob/main/README.md) 中的"Technical stack"章节，MaxKB 的核心技术选型如下：

| 层级 | 技术 | 用途 |
| --- | --- | --- |
| 前端 | Vue.js | 单页应用与组件化界面 |
| 后端 | Python / Django | Web 框架、ORM、REST 接口 |
| LLM 框架 | LangChain | 大模型调用、链式推理、Agent 能力 |
| 数据库 | PostgreSQL + pgvector | 关系数据存储与向量检索 |
| API 文档 | DRF OpenAPI | 自动生成接口定义 |

在前端类型层，[ui/src/api/type/common.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/common.ts) 定义了 `pageRequest`、`PageList`、`Dict` 等通用类型，说明前端采用 TypeScript 并通过统一分页协议与后端交互。后端则在 [apps/knowledge/api/knowledge.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/knowledge.py) 与 [apps/tools/api/tool.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/tools/api/tool.py) 等文件中通过 `OpenApiParameter` 与 `APIMixin` 显式声明参数与响应，体现了 Django REST Framework + drf-spectacular 的接口契约风格。

## 三、系统架构与模块划分

### 3.1 总体架构

MaxKB 采用前后端分离的 B/S 架构，后端以 Django 多应用（apps）组织业务模块，前端以 Vue 多模块（ui/src/api/*）组织 API 调用层。下图描述了主要模块的依赖关系与数据流。

```mermaid
flowchart LR
    Browser[浏览器 / 前端 Vue] -->|HTTP/JSON| Gateway[Django URL 路由]
    Gateway --> Apps
    subgraph Apps[后端 Django Apps]
        Knowledge[knowledge 知识库]
        Tools[tools 工具]
        Application[application 应用]
        Trigger[trigger 触发器]
        System[system 系统]
    end
    Apps --> ORM[Django ORM]
    ORM --> PG[(PostgreSQL + pgvector)]
    Apps --> LLM[LangChain / 大模型]
    LLM --> Apps
    Browser <-->|WebSocket/Streaming| Apps
```

### 3.2 后端 Django 应用模块

后端通过 `apps/<module>/api/*.py` 拆分业务接口，遵循统一的 OpenAPI 声明规范：

- **knowledge 模块**：负责知识库、文档、段落、术语库与版本管理。[apps/knowledge/api/knowledge.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/knowledge.py) 暴露知识库分页、检索、同步等接口；[apps/knowledge/api/document.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/document.py) 提供文档迁移、源文件下载等能力；[apps/knowledge/api/paragraph.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/paragraph.py) 维护段落顺序与内容；[apps/knowledge/api/knowledge_version.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/knowledge_version.py) 则管理知识库的版本号，便于回滚与差异对比。
- **tools 模块**：[apps/tools/api/tool.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/tools/api/tool.py) 中可见工具按 `SHARED` 与 `WORKSPACE` 两种 `scope` 划分，并支持 `PylintInstance` 校验、`EditIconAPI` 等扩展点，便于接入自定义函数与第三方 API。
- **trigger / application / system 模块**：分别承载触发器调度、智能体应用编排以及用户、角色、权限与工作空间管理。这些模块在 [ui/src/api/trigger/trigger.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/trigger/trigger.ts) 与 [ui/src/api/system/role.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system/role.ts) 的前端调用定义中得到对应体现。

### 3.3 前端 Vue 模块

前端 `ui/src/api` 目录按照"业务域 + 共享层"的方式组织：

- **业务域 API**：如 `knowledge/`、`trigger/` 等目录内的 `.ts` 文件，对应后端具体业务模块，例如 [ui/src/api/knowledge/document.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/document.ts) 中定义了 `getDocumentDetail`、`putDocument` 等与文档相关的请求方法。
- **共享层 API**：`system-shared/`、`system-resource-management/`、`shared-workspace.ts` 等文件提供跨模块复用的接口，例如 [ui/src/api/shared-workspace.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/shared-workspace.ts) 中 `getUserGroupList`、`getUserGroupUserList` 等方法用于在共享工作空间下访问知识库资源。
- **类型定义**：`type/` 目录集中声明通用类型，其中 [ui/src/api/type/application.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/application.ts) 定义了 `chatType`、`Chunk` 等流式对话相关结构，反映出 MaxKB 支持节点级工作流与流式响应（SSE/WebSocket）的能力。

## 四、数据模型与接口契约要点

从前端 API 与后端 OpenAPI 声明中可以提炼出几个贯穿全系统的设计要点：

1. **统一的分页协议**：所有列表接口均要求 `current_page` 与 `page_size`，并通过 `folder_id`、`scope`、`name` 等查询参数做过滤，参见 [apps/knowledge/api/knowledge.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/knowledge.py) 与 [ui/src/api/type/common.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/common.ts) 中的 `pageRequest` 接口。
2. **资源范围（scope）与工作空间隔离**：知识库、工具等资源通过 `workspace_id` 路径参数与 `scope` 查询参数控制可见性，体现多租户设计，例如 [apps/tools/api/tool.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/tools/api/tool.py) 中的 `scope` 枚举 `["SHARED", "WORKSPACE"]`。
3. **资源级触发器绑定**：[ui/src/api/trigger/trigger.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/trigger/trigger.ts) 中 `postResourceTrigger` 等方法按 `source_type` 与 `source_id` 将触发器挂载到任意资源上，`pageTriggerTaskRecord` 则用于查询执行记录，方便审计与排错。
4. **角色与权限管理**：[ui/src/api/system/role.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system/role.ts) 提供角色成员增删、权限保存等接口，与后端的 RBAC 能力相对应。
5. **流式对话结构**：前端 `chatType`、`Chunk` 等类型（见 [ui/src/api/type/application.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/application.ts)）表明应用层采用"节点 + 流式片段"的协议设计，每个 `Chunk` 携带 `chat_id`、`chat_record_id`、`node_id`、`up_node_id` 等字段，便于在 UI 中以工作流节点维度渲染对话过程。

## 五、典型请求流程示例

以"在工作空间中创建一个知识库文档"为例，请求链路如下：

1. 前端在 `knowledge/document.ts` 调用 `postDocument`，构造 `{ name, is_active, meta }` 等字段。
2. 请求经 `prefix.value`（工作空间前缀）拼装后到达 Django URL 路由，匹配 `apps/knowledge/api/document.py` 中声明的参数与序列化器。
3. 视图层通过 ORM 将记录写入 PostgreSQL，并触发 LangChain 流水线完成文档解析、向量化与段落入库。
4. 前端通过 `getDocumentDetail` 拉取最新状态，结合 `chatType` 中的流式协议在 UI 上呈现。

## 六、See Also

- 知识库与文档管理：参考 `apps/knowledge/api/` 目录下各接口文件以及 `ui/src/api/knowledge/` 前端封装。
- 工具与触发器扩展：参考 `apps/tools/api/tool.py` 与 `ui/src/api/trigger/trigger.ts`。
- 角色与工作空间权限：参考 `ui/src/api/system/role.ts` 与 `ui/src/api/shared-workspace.ts`。
- 流式对话与节点渲染：参考 `ui/src/api/type/application.ts` 中 `chatType`、`Chunk` 类型定义。

---

<a id='page-knowledge-rag'></a>

## 知识库管理、文档处理与 RAG 检索

### 相关页面

相关主题：[项目概览、技术栈与系统架构](#page-overview), [应用、对话流水线与 Agentic 工作流引擎](#page-application-workflow), [模型提供商、工具、MCP 与扩展机制](#page-model-extension)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/1Panel-dev/MaxKB/blob/main/README.md)
- [apps/knowledge/api/paragraph.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/paragraph.py)
- [apps/knowledge/api/document.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/document.py)
- [apps/knowledge/api/knowledge_version.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/knowledge_version.py)
- [apps/knowledge/api/termbase.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/termbase.py)
- [apps/tools/api/tool.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/tools/api/tool.py)
- [ui/src/api/knowledge/document.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/document.ts)
- [ui/src/api/knowledge/problem.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/problem.ts)
- [ui/src/api/trigger/trigger.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/trigger/trigger.ts)
- [ui/src/api/system-shared/knowledge.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/knowledge.ts)
- [ui/src/api/type/common.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/common.ts)
- [ui/src/api/type/application.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/application.ts)
</details>

# 知识库管理、文档处理与 RAG 检索

## 1. 概述

MaxKB 是一套面向企业级智能体场景的开源平台，技术栈由 Vue.js 前端、Python/Django 后端、LangChain 框架以及 PostgreSQL + pgvector 组成。在该体系中，"知识库"（Knowledge Base）是 RAG（检索增强生成）能力的核心载体，承载文档入库、段落切分、向量化、相似度检索、术语管理以及与触发器/工具的协同等能力。

资料来源：[README.md:23-26]()

围绕"知识库"这一领域，系统在前后端分别提供了多套 API 客户端与 OpenAPI 描述：
- 后端使用 DRF 风格的 `APIMixin` 描述参数与请求/响应 Schema，参数语义在中文注释中显式给出（如"知识库id"、"工作空间id"），方便国际化与 OpenAPI 文档生成。
- 前端将相同语义封装为 TypeScript 函数，按 `knowledge / document / problem / trigger / tool` 等模块拆分，并通过 `Result<T>` 统一返回类型。

资料来源：[apps/knowledge/api/paragraph.py:1-90]()、[ui/src/api/knowledge/document.ts:1-20]()

## 2. 知识库与文档/段落处理 API

### 2.1 文档级别的迁移与下载

文档级别的迁移涉及"源知识库 → 目标知识库"的跨库搬运，以及"源文档 → 目标文档"的精确迁移两个层级。
- `DocumentMigrateAPI` 仅要求 `workspace_id / knowledge_id / target_knowledge_id` 三个路径参数，使用 `DocumentMigrateSerializer` 作为请求体，语义为"把当前知识库的文档批量迁到目标知识库"。
- `Paragraph` 维度则提供更细粒度的 `BatchSerializer` 入口，使用 `target_knowledge_id` + `target_document_id` 联合定位，使段落级数据可在不同文档间重排。

`DocumentDownloadSourceAPI` 用于下载文档原始来源，参数只到 `workspace_id / knowledge_id`，代表原始资源在知识库粒度进行索引。

资料来源：[apps/knowledge/api/document.py:1-90]()、[apps/knowledge/api/paragraph.py:1-60]()

### 2.2 段落顺序与版本管理

段落顺序的微调由 `ParagraphAdjustOrderAPI` 提供，参数为 `paragraph_id`（查询串）与 `new_position`（查询串），响应使用 `DefaultResultSerializer`，体现"段落顺序可单独维护、不需要重新触发向量化"的设计思路。

`KnowledgeVersionAPI`、`KnowledgeVersionOperateAPI`、`KnowledgeVersionListAPI` 与 `KnowledgeVersionPageAPI` 组成了知识库的版本子系统：
- `KnowledgeVersionListAPI` 在 `KnowledgeVersionOperateAPI` 的基础上额外接受 `name`（Version Name）查询参数，用于按版本名过滤。
- `KnowledgeVersionPageAPI` 复用了 List 的参数定义，但响应从列表升级为分页 `KnowledgePageVersionResult`，符合列表 → 详情 → 分页的常见 API 演进模式。

资料来源：[apps/knowledge/api/paragraph.py:60-90]()、[apps/knowledge/api/knowledge_version.py:1-50]()

### 2.3 术语库（Termbase）

`TermbasePageAPI` 与 `TermbaseDeleteAPI` 把"术语/问题"作为知识库下的二级资源进行管理：
- 分页接口要求 `workspace_id / knowledge_id / current_page / page_size`，与 `pageRequest` 约定一致。
- 删除接口在路径中追加 `problem_id`，与 `ui/src/api/knowledge/problem.ts` 中 `delProblems(knowledge_id, problem_id)` 的前端封装形成对应，后端 `problem_id` 即前端"问题"的实体键。

资料来源：[apps/knowledge/api/termbase.py:1-60]()、[ui/src/api/knowledge/problem.ts:1-30]()

## 3. 工具、触发器与 RAG 协同

工具（Tool）与触发器（Trigger）通过显式的 `scope` 与 `source_type` 字段，与知识库解耦地挂载到工作空间或具体资源上：

| 维度 | 关键参数 | 取值/说明 | 资料来源 |
| --- | --- | --- | --- |
| 工具分页 | `scope` | `SHARED` / `WORKSPACE`，区分共享工具与工作空间工具 | [apps/tools/api/tool.py:1-60]() |
| 工具过滤 | `folder_id`（必填）、`user_id`（可选）、`name`（可选） | 按文件夹/创建者/名称组合检索 | [apps/tools/api/tool.py:1-60]() |
| 触发器挂载 | `source_type` + `source_id` | 资源端创建/更新/查询触发器，资源可以是应用、知识库等 | [ui/src/api/trigger/trigger.ts:1-90]() |
| 触发器执行 | `pageTriggerTaskRecord(trigger_id, page, param)` | 触发器执行记录分页查询 | [ui/src/api/trigger/trigger.ts:1-30]() |

`source_type` + `source_id` 的设计意味着：知识库既可作为触发器的"被作用资源"（如"文档变更时同步重建索引"），也可被应用（Application）作为长期记忆的载体——这一点与 `chatType` 中的 `long_term_enable / long_term_model_id / long_term_trigger_setting` 字段呼应。

资料来源：[ui/src/api/type/application.ts:1-40]()、[ui/src/api/trigger/trigger.ts:30-90]()

## 4. 前端 API 客户端与分页约定

前端 TypeScript 层将后端 API 拆为 `system-shared`（跨工作空间共享）与 `system-resource-management`（资源端管理）两个 bundle，再按业务域 `knowledge / document / problem / trigger / tool` 进一步拆分。

通用分页类型在 `type/common.ts` 中统一定义：

```ts
interface pageRequest { current_page: number; page_size: number }
interface PageList<T>  { current: number; size: number; total: number; records: T }
```

该约定贯穿 `TermbasePageAPI`、`pageTriggerTaskRecord`、`pageKnowledgeDocument` 等所有分页接口，避免前后端在 `current_page` 与 `current`、`page_size` 与 `size` 上的命名漂移。

资料来源：[ui/src/api/type/common.ts:1-20]()、[ui/src/api/system-shared/knowledge.ts:1-20]()、[ui/src/api/system-shared/document.ts:1-20]()

```mermaid
flowchart LR
  A[Workspace] --> B[Knowledge Base]
  B --> C[Document]
  C --> D[Paragraph]
  C --> E[Problem/Termbase]
  B --> F[Knowledge Version]
  D --> G[Embedding Task]
  G --> H[(pgvector)]
  H --> I[RAG 检索 / Chat]
  F -.回滚/对比.-> I
  E -.术语加权.-> I
  J[Tool SHARED/WORKSPACE] --> I
  K[Trigger source_type/source_id] --> C
  K --> G
```

> 上述流程仅基于源码中可见的字段与 API 形态（段落顺序、文档迁移、版本列表、术语库、工具 scope、触发器 source_type）抽象而成，未引入未经源码验证的组件。

## See Also

- 智能体与应用对话：[ui/src/api/type/application.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/application.ts)
- 工具与工作流：[ui/src/api/system-shared/tool.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/tool.ts)
- 触发器执行记录：[ui/src/api/trigger/trigger.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/trigger/trigger.ts)
- 通用分页约定：[ui/src/api/type/common.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/common.ts)

---

<a id='page-application-workflow'></a>

## 应用、对话流水线与 Agentic 工作流引擎

### 相关页面

相关主题：[项目概览、技术栈与系统架构](#page-overview), [知识库管理、文档处理与 RAG 检索](#page-knowledge-rag), [模型提供商、工具、MCP 与扩展机制](#page-model-extension)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [ui/src/api/type/application.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/application.ts)
- [apps/knowledge/api/knowledge_workflow.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/knowledge_workflow.py)
- [apps/knowledge/api/knowledge_version.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/knowledge_version.py)
- [apps/knowledge/api/paragraph.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/paragraph.py)
- [apps/knowledge/api/termbase.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/termbase.py)
- [apps/knowledge/api/document.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/document.py)
- [apps/tools/api/tool.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/tools/api/tool.py)
- [ui/src/api/trigger/trigger.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/trigger/trigger.ts)
- [ui/src/api/type/common.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/common.ts)
- [ui/src/api/knowledge/document.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/document.ts)
- [ui/src/api/knowledge/problem.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/problem.ts)
- [ui/src/api/system/role.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system/role.ts)
</details>

# 应用、对话流水线与 Agentic 工作流引擎

## 一、概述

MaxKB 是一个面向企业级场景的开源智能体（Agent）平台，其核心能力由"应用（Application）"、"对话流水线（Chat Pipeline）"以及"Agentic 工作流引擎"三层结构协同提供。应用层负责将用户会话、模型与外部资源封装为可发布的服务；对话流水线负责在一次问答中按步骤完成问题改写、知识检索、上下文组装、模型推理与回复渲染；而 Agentic 工作流引擎则以知识库工作流（Knowledge Workflow）和触发器（Trigger）为载体，使应用能够基于事件或调度自动执行多步骤推理与外部动作。

本说明围绕仓库中可直接观察到的接口定义、类型声明以及 API 视图类展开，重点说明对话数据结构、知识库工作流的版本化机制、触发器驱动的 Agentic 任务执行以及工具调用等关键能力。

## 二、应用与对话数据结构

前端通过统一的 TypeScript 类型描述一次应用会话的完整生命周期。

### 2.1 会话（chatType）

`ui/src/api/type/application.ts` 中定义的 `chatType` 描述了一条对话记录的全部状态：包括问题文本 `problem_text`、回答文本 `answer_text`、用于流式渲染的缓冲区 `buffer` 与 `answer_text_list`、投票状态 `vote_status`、执行详情 `execution_details` 以及上传的媒体元数据 `upload_meta`。该类型同时暴露 `write_ed`（是否写入结束）与 `is_stop`（是否暂停）等运行时标志，用于驱动前端流式 UI。

### 2.2 流式片段（Chunk）

`Chunk` 类型是流水线单步产出的最小渲染单元，其关键字段包括 `content`、`reasoning_content`、`node_id`、`up_node_id`、`runtime_node_id`、`view_type`、`node_type` 与 `is_end` / `node_is_end`。`child_node` 字段允许一个片段携带子节点，从而支撑多分支、工具嵌套调用等 Agentic 行为。

### 2.3 节点（Node）

`Node` 类型描述流水线图中单个节点的运行态，包含 `buffer`、`node_id`、`up_node_id` 等。结合 `Chunk.child_node`，可以看出 MaxKB 的对话流水线本质上是一棵按节点 ID 与父节点 ID 串联的执行树，而非线性管道。

```mermaid
flowchart LR
    A[用户问题] --> B[问题改写 Step]
    B --> C[知识库检索 Step]
    C --> D[历史消息生成 Step]
    D --> E[LLM 推理 Step]
    E --> F[工具调用 Step]
    F --> G[回复渲染 Chunk 流]
```

## 三、知识库工作流与版本化

知识库工作流是把多步数据处理（采集、清洗、向量化、入库）编排为可视化 DAG 的机制，并由版本系统保证可回滚、可发布。

### 3.1 工作流动作 API

`apps/knowledge/api/knowledge_workflow.py` 通过 `KnowledgeWorkflowActionApi` 暴露工作流执行入口，其 `Operate` 子类要求路径参数 `workspace_id` 与 `knowledge_id`，请求体由 `KnowledgeWorkflowActionRequestSerializer` 序列化。该视图类既支持单步运行，也支持触发完整的 DAG 执行。

### 3.2 工作流版本 API

`apps/knowledge/api/knowledge_version.py` 定义了 `KnowledgeVersionAPI`、`KnowledgeVersionOperateAPI`、`KnowledgeVersionListAPI` 与 `KnowledgeVersionPageAPI` 四类接口，用于版本创建、按 `knowledge_version_id` 操作、按名称过滤以及分页查询。其中 `KnowledgeVersionOperateAPI` 通过 `*KnowledgeVersionAPI.get_parameters()` 复用基础路径参数，体现出 MaxKB 在 OpenAPI Schema 组合上的复用约定。版本响应体 `KnowledgeWorkflowVersionResult` 描述了某一发布快照的全部参数。

### 3.3 段落顺序调整

`apps/knowledge/api/paragraph.py` 中的段落重排接口要求 `document_id`、`paragraph_id` 与 `new_position`，表明知识库工作流的执行结果（段落）支持运行时顺序调整，属于 Agentic 工作流对下游数据再编排的能力。

## 四、触发器驱动的 Agentic 任务

Agentic 行为的关键不在单次问答，而在"何时、以何种上下文、自动触发"。

### 4.1 触发器任务记录

`ui/src/api/trigger/trigger.ts` 提供了 `pageTriggerTaskRecord` 与 `getTriggerTaskRecordDetails` 等接口，用于按 `trigger_id` 分页查询触发器执行历史及单条记录的详情。每条记录包含 `trigger_task_id` 与 `trigger_task_record_id` 两级 ID，便于对一次自动执行链路进行审计与回放。

### 4.2 资源端触发器创建

同文件中的 `postResourceTrigger(source_type, source_id, data)` 接口允许针对某一资源（如知识库、应用）创建触发器，路径为 `${prefixWorkspace.value}/${source_type}/${source_id}/trigger`。`source_type` 的设计使触发器成为可挂载到任意资源上的横切能力，构成 Agentic 工作流的事件入口。

## 五、工具调用与作用域

Agentic 工作流通常需要调用外部工具。`apps/tools/api/tool.py` 在工具分页查询接口中显式声明了 `scope` 查询参数，其枚举值为 `SHARED` 与 `WORKSPACE`，并以 `folder_id` 限定目录、`user_id` 限定创建者、`name` 限定名称。这意味着：

| 维度 | 取值 | 含义 |
| --- | --- | --- |
| scope | SHARED | 跨工作空间共享工具，可在多个 Agent 中复用 |
| scope | WORKSPACE | 仅当前工作空间可见，满足租户隔离 |

工具接口同时暴露 `PylintAPI` 与 `EditIconAPI`，说明工具在保存前会进行代码校验（适用于脚本型 / 函数型工具），并允许上传自定义图标以改善 Agent 编排画布的视觉表现。

## 六、常见注意事项

1. 流式渲染必须正确处理 `is_end` 与 `node_is_end` 的差异：前者表示整条对话结束，后者仅表示当前节点结束，二者均需在前端 chunk 处理逻辑中考虑。资料来源：[ui/src/api/type/application.ts]()
2. 知识库版本一旦发布，修改段落顺序需要走专门的 `new_position` 接口，而非直接编辑文档内容。资料来源：[apps/knowledge/api/paragraph.py]()
3. 触发器任务记录采用两级 ID 设计（`trigger_task_id` / `trigger_task_record_id`），用于区分"任务定义的一次执行"与"该次执行中产生的某条历史"。资料来源：[ui/src/api/trigger/trigger.ts]()
4. 工具的 `SHARED` 与 `WORKSPACE` 作用域在创建后不可更改，新建工具时必须确认所属。资料来源：[apps/tools/api/tool.py]()
5. 工作流版本的查询支持按名称模糊匹配并分页，便于在大规模知识库中定位历史快照。资料来源：[apps/knowledge/api/knowledge_version.py]()

## See Also

- 知识库文档与段落管理：[apps/knowledge/api/document.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/document.py)
- 知识库问题与术语库：[apps/knowledge/api/termbase.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/termbase.py)
- 通用类型定义：[ui/src/api/type/common.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/common.ts)
- 角色与权限：[ui/src/api/system/role.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system/role.ts)

---

<a id='page-model-extension'></a>

## 模型提供商、工具、MCP 与扩展机制

### 相关页面

相关主题：[项目概览、技术栈与系统架构](#page-overview), [知识库管理、文档处理与 RAG 检索](#page-knowledge-rag), [应用、对话流水线与 Agentic 工作流引擎](#page-application-workflow)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [apps/tools/api/tool.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/tools/api/tool.py)
- [ui/src/api/system-shared/tool.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/tool.ts)
- [ui/src/api/system-resource-management/tool.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-resource-management/tool.ts)
- [ui/src/api/system-shared/knowledge.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/knowledge.ts)
- [ui/src/api/trigger/trigger.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/trigger/trigger.ts)
</details>

# 模型提供商、工具、MCP 与扩展机制

## 概述

MaxKB 作为企业级智能体平台，核心扩展能力围绕"工具（Tool）"、"MCP（Model Context Protocol）"、"触发器（Trigger）"以及"工作流（Workflow）"四条主线构建。模型提供商（Model Provider）层负责接入大语言模型；工具与 MCP 层负责让模型在对话中调用外部能力；触发器层负责把"事件"接入到工作流；工作流层则把工具、模型、数据源编排成可复用的扩展单元。本页基于平台暴露的 API 契约说明其交互关系。

## 工具系统架构

工具（Tool）是 MaxKB 扩展机制的基础单元，每个工具既可作为"内置工具（Internal）"使用，也可来源于"工具市场（Store）"或通过"工作流工具"动态生成。平台对工具的管理分为两类作用域：`SHARED`（共享）与 `WORKSPACE`（工作空间级），这一约束在 OpenAPI 参数中显式声明。

```mermaid
flowchart LR
    A[LLM 应用] --> B[工具调用网关]
    B --> C{工具来源}
    C -->|内置| D[addInternalTool]
    C -->|市场| E[addStoreTool / updateStoreTool]
    C -->|工作流| F[putToolWorkflow / debugToolWorkflow]
    B --> G[postToolTestConnection]
    B --> H[delTool / putToolIcon]
```

关键 API 入口集中在两个文件：后端的 [apps/tools/api/tool.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/tools/api/tool.py) 通过 `OpenApiParameter` 定义了 `workspace_id`、`folder_id`、`user_id`、`scope`（`["SHARED", "WORKSPACE"]`）和 `name` 等参数，用于工具的列表分页与查询；前端的 [ui/src/api/system-resource-management/tool.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-resource-management/tool.ts) 暴露了 `getToolListPage`、`getToolById`、`putTool`、`delTool`、`postToolTestConnection` 等方法，与资源管理界面绑定。

工具相关的扩展能力进一步通过 [ui/src/api/system-shared/tool.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/tool.ts) 暴露，包括 `addInternalTool`、`addStoreTool`、`updateStoreTool`（市场工具安装与升级）、`uploadSkillFile` 与 `downloadSkillFile`（技能文件管理）、`generateCode`（代码生成）、`postPylint`（静态校验，由 `PylintAPI` 暴露）、`exportTool`/`importToolWorkflow`（工具导入导出）、`listToolWorkflowVersion` 与 `updateToolWorkflowVersion`（工具工作流版本管理）、`debugToolWorkflow`（调试入口），共同构成"工具即代码 + 工具即工作流"的双形态。

## MCP 集成机制

MCP（Model Context Protocol）作为模型与外部工具/数据源之间的标准协议，在 MaxKB 中通过知识库共享工作空间统一暴露。`getMcpTools` 是 MCP 工具的核心获取入口，定义在 [ui/src/api/system-shared/knowledge.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/knowledge.ts) 的导出列表中。同一文件还导出了 `postTransformWorkflow`，用于将既有工作流转换为 MCP 协议暴露的形态；以及 `exportKnowledgeBundle` 与 `importKnowledgeBundle`，用于以"知识包"形式整体迁移含 MCP 工具的工作流。这意味着 MCP 工具在平台内被视为"知识库 + 工作流"的复合产物，而非单纯的 API 包装。

## 触发器与扩展点

触发器（Trigger）是 MaxKB 把外部事件接入工作流的核心机制。资源端（Resource）可对 `APPLICATION`、`KNOWLEDGE` 等资源绑定触发器，由 [ui/src/api/trigger/trigger.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/trigger/trigger.ts) 提供完整 API：

| 操作 | 方法 | 路径模式 |
|------|------|----------|
| 创建资源触发器 | `postResourceTrigger` | `{workspace}/{source_type}/{source_id}/trigger` |
| 更新资源触发器 | `putResourceTrigger` | `{workspace}/{source_type}/{source_id}/trigger/{trigger_id}` |
| 列出资源触发器 | `getResourceTriggerList` | `{workspace}/{source_type}/{source_id}/trigger` |
| 分页查询执行记录 | `pageTriggerTaskRecord` | `{trigger_id}/task_record/{page}/{size}` |
| 执行记录详情 | `getTriggerTaskRecordDetails` | `{trigger_id}/trigger_task/{task_id}/trigger_task_record/{record_id}` |
| 批量启停 | `activateMulTrigger` | — |

触发器与"长期记忆"在应用层也有显式关联：应用类型 `long_term_trigger_type` 与 `long_term_trigger_setting` 字段（见 [ui/src/api/type/application.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/application.ts)）允许把外部触发器作为长期记忆的写入条件，从而形成"事件 → 触发器 → 工作流 → 记忆/回复"的闭环。

## 工作流扩展与版本管理

工作流既是工具的实现形态，也是知识库的处理流水线。`getWorkflowAction`、`getKnowledgeWorkflowFormList`、`getKnowledgeWorkflowDatasourceDetails` 与 `workflowAction` 用于工作流的查询与执行；`workflowUpload` 与 `putKnowledgeWorkflow` 用于上传与更新；`publish` 触发发布；`listKnowledgeVersion` 与 `getWorkflowActionPage` 提供版本与分页；`exportKnowledgeWorkflow` 与 `importKnowledgeWorkflow` 支持跨环境迁移。`postTransformWorkflow` 进一步把"普通工作流"提升为"MCP 暴露形态"，与上一节的 MCP 机制形成连接。

## See Also

- 知识库与文档管理：[ui/src/api/knowledge/document.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/document.ts)
- 应用与对话类型定义：[ui/src/api/type/application.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/application.ts)
- 触发器任务记录查询：[ui/src/api/trigger/trigger.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/trigger/trigger.ts)

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：1Panel-dev/MaxKB

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 依赖 Docker 环境。

## 1. 安装坑 · 依赖 Docker 环境

- 严重度：medium
- 证据强度：runtime_trace
- 发现：安装/运行入口包含 Docker 命令：docker run -d --name=maxkb --restart=always -p 8080:8080 -v ~/.maxkb:/opt/maxkb 1panel/maxkb
- 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
- 复现命令：`docker run -d --name=maxkb --restart=always -p 8080:8080 -v ~/.maxkb:/opt/maxkb 1panel/maxkb`
- 证据：identity.distribution | https://github.com/1Panel-dev/MaxKB | docker run -d --name=maxkb --restart=always -p 8080:8080 -v ~/.maxkb:/opt/maxkb 1panel/maxkb

## 2. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/1Panel-dev/MaxKB | host_targets=mcp_host, claude, chatgpt

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/1Panel-dev/MaxKB | README/documentation is current enough for a first validation pass.

## 4. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/1Panel-dev/MaxKB | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/1Panel-dev/MaxKB | no_demo; severity=medium

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/1Panel-dev/MaxKB | no_demo; severity=medium

## 7. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/1Panel-dev/MaxKB | issue_or_pr_quality=unknown

## 8. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/1Panel-dev/MaxKB | release_recency=unknown

<!-- canonical_name: 1Panel-dev/MaxKB; human_manual_source: deepwiki_human_wiki -->