# https://github.com/langbot-app/LangBot 项目说明书

生成时间：2026-06-22 20:21:37 UTC

## 目录

- [Overview & System Architecture](#page-1)
- [Platform Adapters & IM Integration](#page-2)
- [Pipeline, AI/LLM Integration & Extensibility (Plugins/MCP/Skills/RAG)](#page-3)
- [Deployment, Configuration, Data Management & Operations](#page-4)

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

## Overview & System Architecture

### 相关页面

相关主题：[Platform Adapters & IM Integration](#page-2), [Pipeline, AI/LLM Integration & Extensibility (Plugins/MCP/Skills/RAG)](#page-3), [Deployment, Configuration, Data Management & Operations](#page-4)

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

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

- [README.md](https://github.com/langbot-app/LangBot/blob/main/README.md)
- [skills/README.md](https://github.com/langbot-app/LangBot/blob/main/skills/README.md)
- [src/langbot/pkg/api/mcp/__init__.py](https://github.com/langbot-app/LangBot/blob/main/src/langbot/pkg/api/mcp/__init__.py)
- [src/langbot/pkg/api/http/controller/groups/monitoring.py](https://github.com/langbot-app/LangBot/blob/main/src/langbot/pkg/api/http/controller/groups/monitoring.py)
- [src/langbot/pkg/api/http/service/knowledge.py](https://github.com/langbot-app/LangBot/blob/main/src/langbot/pkg/api/http/service/knowledge.py)
- [web/src/app/infra/entities/api/index.ts](https://github.com/langbot-app/LangBot/blob/main/web/src/app/infra/entities/api/index.ts)
- [examples/web-page-bot/README.md](https://github.com/langbot-app/LangBot/blob/main/examples/web-page-bot/README.md)
- [examples/http-bot/README.md](https://github.com/langbot-app/LangBot/blob/main/examples/http-bot/README.md)
- [skills/schemas/README.md](https://github.com/langbot-app/LangBot/blob/main/skills/schemas/README.md)
- [skills/qa-agent-docs/qa-agent/README.md](https://github.com/langbot-app/LangBot/blob/main/skills/qa-agent-docs/qa-agent/README.md)
</details>

# Overview & System Architecture

LangBot 是一个**开源、生产级的即时通讯 AI 机器人平台**，旨在将各种大语言模型（LLM）连接到任意聊天平台，让用户能够构建具备对话、工具调用与外部集成能力的智能代理 资料来源：[README.md:1-15]()。该项目以单一代码库覆盖 Discord、Telegram、Slack、QQ、企业微信、微信公众号、飞书、钉钉、KOOK 等十余种 IM 平台，并通过统一的 Web 管理面板与 API 提供运维、监控与扩展能力 资料来源：[README.md:54-82]()。

## 核心设计理念

LangBot 将 AI Bot 的搭建抽象为三层协同：**适配器（Adapter）— 流水线（Pipeline）— 模型/插件（Model & Plugin）**。适配器负责对接具体 IM 平台的协议（如 Telegram Bot API、企业微信回调）；流水线承载多轮对话、RAG、工具调用与多模态处理逻辑；模型与插件层则对接 OpenAI、DeepSeek、Dify、Coze、n8n、Langflow 等上游 LLM 与低代码平台 资料来源：[README.md:15-30]()。这种解耦使得同一份业务流水线可被多个 IM 平台复用，从而显著降低多渠道部署成本。

平台在管理层提供 WebUI、HTTP API 与 MCP（Model Context Protocol）三种入口。HTTP API 暴露 Bot、Pipeline、Plugin、Model、知识库与监控等全部资源；MCP 服务则将同一套接口以 MCP 工具的形式暴露，使外部 AI Agent（如 Claude Code、Codex）可直接通过协议管理 LangBot 实例，认证复用 `config.yaml` 中的全局 API Key 资料来源：[src/langbot/pkg/api/mcp/__init__.py:1-15]()。

## 系统架构总览

下图展示了从用户消息进入到最终回复的完整数据流，以及各子系统之间的关系：

```mermaid
flowchart LR
    User[终端用户] -->|IM 协议| Adapter[适配器 Adapter]
    Adapter -->|标准化事件| Pipeline[流水线 Pipeline]
    Pipeline -->|检索/工具| RAG[知识库 RAG]
    Pipeline -->|推理请求| LLM[LLM / 代理平台]
    RAG --- Plugin[插件 Plugin]
    LLM --- Plugin
    Plugin -->|回调| Pipeline
    Pipeline -->|回复内容| Adapter
    Adapter -->|平台 API| User
    WebUI[Web 管理面板] <-->|HTTP/MCP| API[LangBot API 层]
    API <--> Adapter
    API <--> Pipeline
    API <--> Plugin
    Monitor[监控与导出] -->|日志/指标| API
```

`web/src/app/infra/entities/api/index.ts` 中定义了大量与该图对应的 TypeScript 实体，例如 `KnowledgeEngine`、`ParserInfo`、`KnowledgeBaseFile`、`Skill`、`MCPServer` 等，表明前端 UI 与后端 API 在数据模型上保持严格一致 资料来源：[web/src/app/infra/entities/api/index.ts:1-50]()。

## 关键子系统

### 适配器与平台支持

LangBot 内置十余种官方适配器，并提供 **Page Bot**（嵌入式网页聊天部件）与 **HTTP Bot**（通用 Webhook + HMAC-SHA256 签名回调）两类自包含适配器，便于将机器人嵌入任意网站或自有系统。`examples/web-page-bot/README.md` 给出了零依赖的浏览器演示页；`examples/http-bot/README.md` 则提供了 Python 与 TypeScript 两份参考客户端，签名格式为 `sha256=hex(HMAC(secret, "{timestamp}." + body))` 资料来源：[examples/http-bot/README.md:1-15]()。

社区方面，企业微信智能机器人 API（支持被 @、被邀请入群）已被多次请求 资料来源：社区议题 #1607；引用消息回复能力 资料来源：社区议题 #1007 也是平台交互体验改进的常见方向。

### 流水线、模型与 RAG

流水线的核心是消息处理管线，可挂载模型、工具、知识库与插件。RAG 引擎以插件形式注册，前端通过 `creation_schema` 与 `retrieval_schema` 动态渲染表单，后端在 `src/langbot/pkg/api/http/service/knowledge.py` 中按 schema 校验必填字段，并交给 `RAGManager` 创建知识库 资料来源：[src/langbot/pkg/api/http/service/knowledge.py:1-30]()。这种“协议化的插件配置”使 LangBot 能在不修改核心代码的前提下接入新的向量库与解析器。

### 监控、可观测性与导出

`src/langbot/pkg/api/http/controller/groups/monitoring.py` 实现了多类数据的批量导出端点，包括消息记录（`messages`）、错误日志（`errors`，含堆栈）、会话快照（`sessions`，含活跃标记）、用户反馈（`feedback`）等，支持按 `bot_ids`、`pipeline_ids` 与时间区间筛选 资料来源：[src/langbot/pkg/api/http/controller/groups/monitoring.py:1-50]()。该模块直接服务 WebUI 上的实时监控大屏（消息量、模型调用、成功率与活跃会话） 资料来源：[README.md:10-15]()。

### 插件市场与扩展机制

扩展是 LangBot 架构的一等公民。仓库根目录的 `skills/` 是面向 AI Agent 的“技能说明书”，覆盖后端开发、插件 SDK、Docker/K8s 部署、WebUI E2E QA、MCP 实例运维、Space 市场浏览等八大技能 资料来源：[skills/README.md:1-15]()。`skills/schemas/README.md` 通过 JSON Schema 约束 case、suite、troubleshooting 等结构化资产，使 `bin/lbs validate` 能在 CI 阶段发现字段缺失 资料来源：[skills/schemas/README.md:1-15]()。同时，`skills/qa-agent-docs/qa-agent/README.md` 明确指出当前 QA 重心是**黑盒 E2E**：打开真实 WebUI、点击真实控件、检查可见 UI 结果，再辅以 console、network、截图与日志证据 资料来源：[skills/qa-agent-docs/qa-agent/README.md:1-15]()。

社区对扩展能力也有持续诉求，例如插件市场缺少详情页 资料来源：社区议题 #1097、回调数据库（历史对话持久化）以避免重启丢记忆 资料来源：社区议题 #804、以及按用户/群维度细化频率限制 资料来源：社区议题 #189，这些方向都已纳入 LangBot 的公开路线图 资料来源：[README.md:1-5]()。

## 部署与运行时

官方提供 Docker、Compose、Kubernetes、Bt Panel、Zeabur、Railway 等多种部署模板 资料来源：[README.md:50-60]()。运行时由 `main.py` 启动 Quart HTTP 应用，将 WebUI、HTTP API 与 MCP Server 三者统一挂载在同一 ASGI 实例上，因此同一份认证既可给浏览器使用，也可给 MCP 客户端使用 资料来源：[src/langbot/pkg/api/mcp/__init__.py:5-15]()。

## See Also

- [Plugins & Skills](Plugins-and-Skills.md)
- [Pipelines & RAG](Pipelines-and-RAG.md)
- [MCP Server](MCP-Server.md)
- [Deployment Guide](Deployment-Guide.md)
- [Monitoring & Observability](Monitoring-and-Observability.md)

---

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

## Platform Adapters & IM Integration

### 相关页面

相关主题：[Overview & System Architecture](#page-1), [Pipeline, AI/LLM Integration & Extensibility (Plugins/MCP/Skills/RAG)](#page-3), [Deployment, Configuration, Data Management & Operations](#page-4)

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

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

- [README.md](https://github.com/langbot-app/LangBot/blob/main/README.md)
- [examples/http-bot/README.md](https://github.com/langbot-app/LangBot/blob/main/examples/http-bot/README.md)
- [examples/web-page-bot/README.md](https://github.com/langbot-app/LangBot/blob/main/examples/web-page-bot/README.md)
- [src/langbot/pkg/api/mcp/__init__.py](https://github.com/langbot-app/LangBot/blob/main/src/langbot/pkg/api/mcp/__init__.py)
- [src/langbot/pkg/api/mcp/server.py](https://github.com/langbot-app/LangBot/blob/main/src/langbot/pkg/api/mcp/server.py)
- [src/langbot/pkg/api/http/controller/groups/monitoring.py](https://github.com/langbot-app/LangBot/blob/main/src/langbot/pkg/api/http/controller/groups/monitoring.py)
- [src/langbot/pkg/api/http/controller/groups/plugins.py](https://github.com/langbot-app/LangBot/blob/main/src/langbot/pkg/api/http/controller/groups/plugins.py)
- [web/src/app/infra/entities/api/index.ts](https://github.com/langbot-app/LangBot/blob/main/web/src/app/infra/entities/api/index.ts)
- [skills/README.md](https://github.com/langbot-app/LangBot/blob/main/skills/README.md)

</details>

# Platform Adapters & IM Integration

## 概述

LangBot 作为一个生产级 IM 机器人平台，核心价值在于「一套代码、多端连接」。Platform Adapters（平台适配器）负责把不同即时通讯平台的协议、消息格式与鉴权方式抽象为统一的内部事件流，使上游 Pipeline 只需要关注业务逻辑（LLM 调用、工具执行、知识库检索），而无需关心底层 IM 协议差异。

资料来源：[README.md:1-50]()

仓库中已提供两类可作为新平台适配器参考的样例：

- **HTTP Bot Adapter** — 基于 HMAC-SHA256 签名 + 回调机制的消息接入方式，参考 `examples/http-bot/README.md`。
- **Page Bot Adapter** — 通过单一 `<script>` 标签嵌入任意网站的聊天小组件，参考 `examples/web-page-bot/README.md`。

## 支持的平台

根据项目主 `README.md` 的能力声明，LangBot 已覆盖以下 IM 平台（✅ 表示官方支持）：

| 平台 | 状态 | 备注 |
| --- | --- | --- |
| Discord | ✅ | 官方 |
| Telegram | ✅ | 官方 |
| Slack | ✅ | 官方 |
| LINE | ✅ | 官方 |
| QQ | ✅ | 个人号与官方 API（频道、私聊、群） |
| WeCom | ✅ | 自建应用、外部客服、AI Bot |
| WeChat | ✅ | 个人号与公众号 |
| Lark | ✅ | 官方 |
| DingTalk | ✅ | 官方 |
| KOOK | ✅ | 官方 |
| Satori | ✅ | 协议层适配 |
| Email | ✅ | Matrix / Satori 通道 |
| Matrix | ✅ | 桥接 Signal、WhatsApp、Messenger、iMessage、Mattermost、Google Chat、IRC、XMPP、Zulip 等 |

资料来源：[README.md:supported-platforms]()

## 适配器集成模式

仓库内的两个示例工程演示了适配器在「事件入站」与「消息出站」上的两种典型形态。

**HTTP Bot（拉模式 + 回调）** 使用 HMAC-SHA256 签名方案 `sha256=hex(HMAC(secret, "{timestamp}." + body))`，服务端在收到 POST 后立即返回 `202 Accepted`；当 Pipeline 产生多段回复时，按 `sequence` 编号通过 callback 端点逐段回流。客户端只要实现同一签名规则即可与适配器互通。

资料来源：[examples/http-bot/README.md:1-50]()

**Page Bot（嵌入式组件）** 则把整个聊天窗口打包成一段 JS，由 WebUI 在用户创建 Bot 时生成对应 UUID，浏览器侧只需配置 LangBot base URL 与 Bot UUID，即可通过 `data-title` 等属性控制外观，实现零依赖嵌入。

资料来源：[examples/web-page-bot/README.md:1-30]()

两种模式的共同点在于：**平台无关的 Bot 实体**是适配器与 Pipeline 之间的桥接层；同一套 Pipeline 配置可以同时被多种适配器复用，从而实现「一套大脑、多端部署」。

## 平台无关的扩展与可观测能力

适配器层之上，LangBot 通过以下机制把 IM 协议差异进一步屏蔽到统一接口之下：

- **MCP Server** — `src/langbot/pkg/api/mcp/__init__.py` 中的 `LangBotMCPServer` 在 `/mcp` 端点上以 [Model Context Protocol](https://modelcontextprotocol.io/) 协议暴露 Bot、Pipeline、模型、知识库、插件的管理能力，外部代理（Claude、Cursor 等）只需使用与 HTTP API 相同的 API Key 即可对接到任何适配器后端。
- **统一扩展类型** — 前端 API 实体 `ExtensionItem`（定义于 `web/src/app/infra/entities/api/index.ts`）把插件、MCP 服务器、技能（Skill）归一化为同一列表项，方便 WebUI 与适配器共享展示与安装逻辑。
- **监控与导出** — `src/langbot/pkg/api/http/controller/groups/monitoring.py` 中的 monitoring 控制器支持按 `export_type`（`sessions` / `feedback` / `errors` 等）、时间窗以及 `bot_ids` / `pipeline_ids` 过滤后导出 CSV，便于跨平台统一审计。
- **插件资源路径标准化** — `src/langbot/pkg/api/http/controller/groups/plugins.py` 中的 `_normalize_plugin_asset_path` 把插件内的相对路径归一化为 `assets/...` 或 `components/pages/...`，是适配器与插件 UI 共享资源的桥梁。

资料来源：[src/langbot/pkg/api/mcp/server.py:1-30]()、[web/src/app/infra/entities/api/index.ts:1-120]()、[src/langbot/pkg/api/http/controller/groups/monitoring.py:1-60]()、[src/langbot/pkg/api/http/controller/groups/plugins.py:1-40]()

此外，仓库内 `skills/` 目录提供了与 LangBot 协作的代理技能（包括 `langbot-mcp-ops`、`langbot-dev` 等），并通过 `AGENTS.md` 强制要求：API 的任何改动必须同步更新 MCP server 与相关 skill，从而确保跨适配器的行为一致性。

资料来源：[skills/README.md:1-30]()

## 社区驱动的演进方向

围绕适配器层，Issue 区集中反映了以下高频需求：

- **企业微信智能机器人 API（#1607）** — 现有 `wecom.py` 自建应用方式无法被 @ 提及或被邀请入群，社区要求扩展支持智能机器人接口（`aibotid`、回调 URL、Token、`EncodingAESKey`）。
- **细粒度频率限制（#189）** — 建议把全局限流下放到单用户/单群维度，并支持白名单豁免。
- **引用消息回复（#1007）** — 期望群聊中能针对被引用消息直接触发 AI 命令。
- **历史对话持久化（#804）** — 角色扮演场景下重启后丢失上下文严重影响体验，需要回调 v2 的数据库能力。

这些需求在实现层面都要求适配器在「事件归一化」环节暴露更丰富的上下文字段（被引用的消息 ID、发送者身份、群组 ID），再由上层的访问控制与持久化层消费。LangBot 的 MCP + Skills 体系让外部代理可以协助把同一类改动同步落到适配器、API 与文档三个面，避免平台之间出现行为漂移。

## 参见

- [HTTP Bot Adapter 示例](../examples/http-bot/README.md)
- [Page Bot Adapter 示例](../examples/web-page-bot/README.md)
- [MCP Server 入口](../src/langbot/pkg/api/mcp/__init__.py)
- [LangBot Skills 目录](../skills/README.md)

---

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

## Pipeline, AI/LLM Integration & Extensibility (Plugins/MCP/Skills/RAG)

### 相关页面

相关主题：[Overview & System Architecture](#page-1), [Platform Adapters & IM Integration](#page-2), [Deployment, Configuration, Data Management & Operations](#page-4)

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

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

- [README.md](https://github.com/langbot-app/LangBot/blob/main/README.md)
- [web/src/app/infra/entities/api/index.ts](https://github.com/langbot-app/LangBot/blob/main/web/src/app/infra/entities/api/index.ts)
- [src/langbot/pkg/api/mcp/__init__.py](https://github.com/langbot-app/LangBot/blob/main/src/langbot/pkg/api/mcp/__init__.py)
- [src/langbot/pkg/api/http/controller/groups/plugins.py](https://github.com/langbot-app/LangBot/blob/main/src/langbot/pkg/api/http/controller/groups/plugins.py)
- [src/langbot/pkg/api/http/controller/groups/monitoring.py](https://github.com/langbot-app/LangBot/blob/main/src/langbot/pkg/api/http/controller/groups/monitoring.py)
- [skills/README.md](https://github.com/langbot-app/LangBot/blob/main/skills/README.md)
- [skills/schemas/README.md](https://github.com/langbot-app/LangBot/blob/main/skills/schemas/README.md)
- [skills/qa-agent-docs/qa-agent/README.md](https://github.com/langbot-app/LangBot/blob/main/skills/qa-agent-docs/qa-agent/README.md)
- [examples/http-bot/README.md](https://github.com/langbot-app/LangBot/blob/main/examples/http-bot/README.md)
- [examples/web-page-bot/README.md](https://github.com/langbot-app/LangBot/blob/main/examples/web-page-bot/README.md)
</details>

# Pipeline, AI/LLM Integration & Extensibility (Plugins/MCP/Skills/RAG)

## 一、总体定位与作用

LangBot 是一套用于构建 AI 即时通讯机器人的生产级开源平台，其核心是 **Pipeline（消息处理流水线）**，负责把来自任意 IM 平台（Discord、Telegram、Slack、QQ、企业微信、飞书、钉钉、KOOK、邮件、Matrix 等）的消息路由到 LLM、可观测组件与回复发送端。README 中明确指出，LangBot 提供多轮对话、工具调用、多模态、流式输出，并内置 RAG 知识库以及与 Dify、Coze、n8n、Langflow、Deerflow、Weknora 的深度集成 资料来源：[README.md]()。

在 Pipeline 之上，LangBot 通过四类机制实现可扩展性：

| 扩展机制 | 角色 | 关键产物 |
| --- | --- | --- |
| **Pipeline** | 消息处理与编排核心 | Bot × Pipeline × Stage 拓扑 |
| **Plugin** | 运行时功能扩展（LLM 后端、平台适配器、事件监听器、工具） | `.lbplugin` 包、`Plugin` 实体 |
| **MCP Server** | 把 HTTP API 暴露为 [Model Context Protocol](https://modelcontextprotocol.io/) 工具，让外部 agent 管理 LangBot | `LangBotMCPServer`、`/mcp` 端点 |
| **Skills** | 面向 AI agent 的指令包，用于辅助插件/核心开发、部署、QA | `skills/<skill>/` 目录与 `bin/lbs` CLI |
| **RAG / Knowledge Base** | 内置检索增强生成能力，由 Knowledge Engine 插件驱动 | `KnowledgeEngine`、`ParserInfo` 实体 |

社区中也存在与扩展性高度相关的诉求，例如 #1607 希望把企业微信适配器升级为智能机器人 API（影响 Pipeline 适配层），#804 希望回调 v2 提供数据库持久化（影响 Pipeline 会话存储层），而 #189 关于个人/群级频率限制的诉求则直接落到 Pipeline 的 `ratelimit` 阶段。

## 二、Pipeline 与 AI/LLM 集成

Pipeline 把"消息接收 → 预处理 → 限速 → 会话加载 → LLM 调用 → 工具调用 → 回复发送"串联成一条可插拔的处理链。前端类型定义清晰反映了 Bot 与 Pipeline 的关联模型：一个 Bot 可绑定一个 Pipeline，Pipeline 中包含若干个 stage，并可以关联 `knowledge_base_id` 与 `knowledge_engine_plugin_id` 等字段 资料来源：[web/src/app/infra/entities/api/index.ts]()。

LLM 集成方面，README 列出了对 OpenAI、Anthropic、DeepSeek、Dify、MCP、SiliconFlow、阿里云百炼、字节火山方舟、ModelScope 等众多 Provider 的支持 资料来源：[README.md]()。模型运行时由 Plugin 体系托管：每个 LLM 后端都通过 `langbot_plugin` SDK 注册为 Plugin 组件，从而被 Pipeline 动态调用。社区中 #1007 关于"针对引用消息回复"的诉求，会经由消息预处理阶段的引用消息字段识别后，再进入 LLM 调用流程。

可观测性方面，`monitoring.py` 的导出端点支持按 `bot_ids`、`pipeline_ids`、`start_time`、`end_time` 过滤调用记录、错误、会话与反馈 资料来源：[src/langbot/pkg/api/http/controller/groups/monitoring.py]()。这让运维可以基于 Pipeline 维度追溯某条回复背后的模型调用细节。

## 三、插件、MCP 与 Skills 三层扩展机制

```mermaid
flowchart LR
    subgraph LangBot Runtime
        Pipeline[Pipeline]
        Plugin[Plugin Runtime]
        API[HTTP API]
        MCP[MCP Server /mcp]
    end
    subgraph 扩展来源
        LLM[LLM Provider Plugin]
        Adapter[Platform Adapter Plugin]
        Tool[Tool / Event Plugin]
        KB[Knowledge Engine Plugin]
        Skill[Skill Pack]
    end
    Pipeline --> Plugin
    Plugin --> LLM
    Plugin --> Adapter
    Plugin --> Tool
    Plugin --> KB
    API --> MCP
    Skill -. 用作开发指引 .- Plugin
    Skill -. 用作 QA 手册 .- Pipeline
```

- **Plugin**：由 `src/langbot/pkg/api/http/controller/groups/plugins.py` 提供 HTTP 控制器，负责安装、加载、卸载以及前端 SDK 注入（`_PAGE_SDK_PATH` 从 `langbot_plugin.assets` 解析 `langbot-page-sdk.js`），并通过 `_normalize_plugin_asset_path` 防止路径穿越（拒绝 `..` 与绝对路径） 资料来源：[src/langbot/pkg/api/http/controller/groups/plugins.py]()。前端 `ExtensionItem` 联合类型把 plugin、MCP server、skill 统一在同一个"扩展"列表中呈现 资料来源：[web/src/app/infra/entities/api/index.ts]()。社区 #1097 希望在插件市场新增"查看详情"二级页面，其数据契约已具备：`Plugin` 实体包含 `author`、`description`、`version`、`author`、`homepage_url`、`tags`、`tools: PluginTool[]` 等字段。
- **MCP Server**：`LangBotMCPServer` 把 HTTP API 子集以 MCP 工具形式暴露，复用 `config.yaml` 中的全局 API Key 鉴权 资料来源：[src/langbot/pkg/api/mcp/__init__.py]()。README 同时指出 LangBot Space 也对外提供独立的 MCP Server，用于浏览插件/MCP/Skill 市场 资料来源：[README.md]()。
- **Skills**：仓库 `skills/` 目录是面向 AI agent 的"指令单一可信源"，由 `bin/lbs` CLI 驱动，包含 8 类技能（核心开发、插件开发、部署、QA、env-setup、MCP 运维、Space 运维、企业微信适配器开发） 资料来源：[skills/README.md]()。QA 类 Skill 通过 `case`/`suite`/`troubleshooting` 三种 YAML 资产描述测试路径，并由 JSON Schema 约束结构 资料来源：[skills/schemas/README.md]()。校验器要求每条 case 列出 `skills`、`troubleshooting`、`evidence_required`、`setup_automation` 等字段，并要求 `ci_eligible` 为布尔 资料来源：[skills/src/commands/validate.ts]()。社区 #2246 中关于"Preserve LiteLLM usage details"的改动，正是为了让 LLM 用量在 Skill QA 报告中可追溯。

## 四、RAG / Knowledge Base

RAG 在前端类型层被建模为 `KnowledgeEngine` 与 `KnowledgeBaseFile`。每个 Bot 可声明 `knowledge_engine_plugin_id`、`creation_settings`、`retrieval_settings`，由选定的 Knowledge Engine 插件接管 资料来源：[web/src/app/infra/entities/api/index.ts]()。

引擎与解析器对外暴露两类只读元数据：

- `KnowledgeEngine.capabilities`：引擎能力描述；
- `ParserInfo.supported_mime_types`：文件解析器支持的 MIME 类型集合 资料来源：[web/src/app/infra/entities/api/index.ts]()。

RAG 的运行时调用发生在 Pipeline 的"LLM 调用"阶段之前：插件形态的 Knowledge Engine 负责把 `KnowledgeBaseFile`（包含 `uuid` / `file_name` / `status`）切片、向量化、检索，再把上下文注入 Prompt。HTTP Bot 与 Page Bot 适配示例都依赖同一套 Pipeline，因此也具备完整的 RAG 能力 资料来源：[examples/http-bot/README.md]() 资料来源：[examples/web-page-bot/README.md]()。

## 五、扩展性最佳实践

1. **优先复用 Pipeline 阶段**，而不是另起进程：限速、回复、消息预处理都已有对应 stage，新需求（如 #189 的细粒度频率限制）应落到 `ratelimit` stage 并复用既有的 `trigger_time` 时间窗。
2. **新增 LLM/平台/工具一律走 Plugin SDK**：保持与 `_normalize_plugin_asset_path` 的安全约束一致，避免直接修改核心包。
3. **同步维护 MCP 工具与 Skills**：README 明确 API 变更必须同时更新 MCP server 与 skill 索引 资料来源：[README.md]()。
4. **QA 用 Skill 资产而非 ad-hoc 脚本**：把可复用路径沉淀为 `case`/`troubleshooting`，借助 `bin/lbs validate` 自动校验 资料来源：[skills/README.md]()。

## See Also

- 消息预处理与频率限制（Pipeline Stage）
- 平台适配器开发（Plugin Adapter SDK）
- MCP Server 工具清单
- Skills 目录与 `bin/lbs` CLI 用法
- 监控与导出（Monitoring & Export）

---

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

## Deployment, Configuration, Data Management & Operations

### 相关页面

相关主题：[Overview & System Architecture](#page-1), [Platform Adapters & IM Integration](#page-2), [Pipeline, AI/LLM Integration & Extensibility (Plugins/MCP/Skills/RAG)](#page-3)

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

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

- [README.md](https://github.com/langbot-app/LangBot/blob/main/README.md)
- [src/langbot/pkg/api/mcp/__init__.py](https://github.com/langbot-app/LangBot/blob/main/src/langbot/pkg/api/mcp/__init__.py)
- [src/langbot/pkg/api/http/service/knowledge.py](https://github.com/langbot-app/LangBot/blob/main/src/langbot/pkg/api/http/service/knowledge.py)
- [src/langbot/pkg/api/http/controller/groups/monitoring.py](https://github.com/langbot-app/LangBot/blob/main/src/langbot/pkg/api/http/controller/groups/monitoring.py)
- [skills/README.md](https://github.com/langbot-app/LangBot/blob/main/skills/README.md)
- [skills/schemas/README.md](https://github.com/langbot-app/LangBot/blob/main/skills/schemas/README.md)
- [skills/src/commands/test.ts](https://github.com/langbot-app/LangBot/blob/main/skills/src/commands/test.ts)
- [skills/src/commands/validate.ts](https://github.com/langbot-app/LangBot/blob/main/skills/src/commands/validate.ts)
- [web/src/app/infra/entities/api/index.ts](https://github.com/langbot-app/LangBot/blob/main/web/src/app/infra/entities/api/index.ts)
- [examples/web-page-bot/README.md](https://github.com/langbot-app/LangBot/blob/main/examples/web-page-bot/README.md)
- [skills/qa-agent-docs/qa-agent/README.md](https://github.com/langbot-app/LangBot/blob/main/skills/qa-agent-docs/qa-agent/README.md)
</details>

# Deployment, Configuration, Data Management & Operations

## 1. 概述与适用范围

LangBot 是一个面向生产环境的开源即时消息机器人平台，提供从部署、配置、数据管理到日常运维的完整链路支持。本页聚焦"部署、配置、数据管理与运维"四个维度，覆盖容器化与编排部署、全局配置、运行时数据（知识库、会话、监控）以及通过 MCP / Skills 体系进行的运维操作。

资料来源：[README.md:1-200]() 描述了项目支持 Discord、Telegram、Slack、LINE、QQ、WeCom、WeChat、Lark、DingTalk、KOOK、Satori、Email、Matrix 等多种 IM 平台，并通过 Docker、Railway、Zeabur、Kubernetes、Manual、BTPanel 等多种方式部署。

## 2. 部署方式

LangBot 提供多种部署选项以适配不同的运维环境：

| 部署方式 | 适用场景 | 关键特性 |
| --- | --- | --- |
| Docker | 单机快速启动 | 官方镜像、Compose 编排 |
| Kubernetes | 生产级集群 | Helm/YAML 模板、水平扩展 |
| Railway / Zeabur | 一键托管 | 模板化部署、无需运维 |
| Manual | 自定义环境 | 源码运行、深度定制 |
| BTPanel | 宝塔面板用户 | 图形化部署 |

部署完成后，浏览器侧可通过 `http://<host>:5300` 访问 WebUI（参见 [README.md:88-103]() 中的部署按钮与文档入口）。

```mermaid
flowchart LR
  A[用户] -->|访问| B[WebUI :5300]
  B --> C{部署形态}
  C -->|Docker| D[容器实例]
  C -->|K8s| E[Pod/Service]
  C -->|Railway/Zeabur| F[托管平台]
  D & E & F --> G[(SQLite/Postgres<br>数据持久化)]
  B -.MCP.-> H[/mcp 端点/]
  H -->|API Key| I[外部 AI Agent]
```

## 3. 配置体系

### 3.1 核心配置文件

LangBot 的运行时由 `config.yaml` 驱动，其中包含全局 API Key、数据库连接、模型密钥等关键参数。该文件是所有部署形态的"单一事实来源"。

### 3.2 MCP Server 配置

LangBot 内置 Model Context Protocol 端点，位于 `/mcp`，复用 HTTP API 的 API Key 鉴权机制（既支持 `config.yaml` 中的全局 Key，也支持 per-user Key）。资料来源：[src/langbot/pkg/api/mcp/__init__.py:1-15]() 中明确说明 MCP 服务器"reuses the same API-key authentication as the HTTP API (including the global API key from `config.yaml`)"。

WebUI 的"API & MCP"选项卡用于配置 MCP 端点；启用后，外部 AI 代理可直接调用 bot、pipeline、plugin、model 等管理接口。

### 3.3 知识库配置

知识库（Knowledge Base）创建时由 Knowledge Engine 插件提供 schema，服务层会校验 `creation_settings` 与 `retrieval_settings` 中的必填字段。资料来源：[src/langbot/pkg/api/http/service/knowledge.py:75-120]() 中 `_validate_schema_required_fields` 方法遍历插件 schema，对缺失或空值字段抛出 `ValueError`，确保知识库在创建时即满足引擎约束。

## 4. 数据管理

### 4.1 监控数据导出

监控控制器提供多种导出类型，覆盖请求、错误、会话、反馈等维度。资料来源：[src/langbot/pkg/api/http/controller/groups/monitoring.py:40-110]() 中 `export_type` 支持 `requests`、`errors`、`sessions`、`feedback` 四类，每类返回不同的字段集合，例如：

- `requests`：`id`, `timestamp`, `bot_name`, `model_name`, `prompt_tokens`, `total_tokens`, `duration_ms`, `status`, `error_message`, `query_text`, `session_id` 等；
- `errors`：额外包含 `error_type` 与 `stack_trace`；
- `sessions`：包含 `message_count`、`start_time`、`last_activity`、`is_active`、`platform`、`user_id`；
- `feedback`：用户对回复的反馈信息。

所有导出均支持按 `bot_ids`、`pipeline_ids`、`start_time`、`end_time`、`limit` 过滤。

### 4.2 扩展项管理

前端 API 实体定义中统一了 Plugin、MCP Server、Skill 三类扩展项。资料来源：[web/src/app/infra/entities/api/index.ts:130-160]() 中 `ExtensionItem` 使用判别联合（discriminated union）区分 `type: 'plugin' | 'mcp' | 'skill'`，为前端提供一致的数据模型。

### 4.3 历史对话持久化

社区关注点 #804 提出"回调数据库（历史对话持久化）"诉求，角色扮演场景下重启进程会导致记忆丢失。该功能依赖数据库持久化当前对话上下文，并已逐步在 v4.10.x 系列中完善（参见 [README.md:30-60]() 中关于 Dify、Coze、n8n 等 LLMOps 集成的描述）。

## 5. 运维与 Skills 体系

### 5.1 Skills 目录

`skills/` 目录是 LangBot 面向 AI Agent 的"单一技能目录"，整合自已归档的 `langbot-skills` 仓库。资料来源：[skills/README.md:1-30]() 列出 8 个核心技能：`langbot-dev`、`langbot-plugin-dev`、`langbot-deploy`、`langbot-testing`、`langbot-env-setup`、`langbot-mcp-ops`、`langbot-space-ops`、`langbot-eba-adapter-dev`，分别覆盖后端/前端开发、插件开发、部署、QA 测试、本地环境、MCP 运维、Space 市场与企业微信适配器开发。

### 5.2 测试与校验

- `bin/lbs validate` 校验 skills/cases、suites、troubleshooting 文件结构（资料来源：[skills/src/commands/validate.ts:1-40]()）；
- `bin/lbs test plan/run/report` 编排结构化测试用例并生成报告（资料来源：[skills/src/commands/test.ts:1-60]()）；
- Schema 目录约束 case/suite/troubleshooting 的字段格式（资料来源：[skills/schemas/README.md:1-30]()）。

### 5.3 运行时监控与限流

社区关注点 #189 建议将频率限制细化到个人或群组，可在 pipeline 层面通过会话级计数器实现。当前 pipeline 已在请求链路中维护 token 计数与配额，运维侧可通过 [src/langbot/pkg/api/http/controller/groups/monitoring.py:1-200]() 的导出接口观察请求分布，结合 WebUI 仪表盘进行调优。

## 6. 常见部署与运维注意事项

1. **API Key 隔离**：在公网部署时务必修改 `config.yaml` 中的全局 API Key，并启用 per-user Key；
2. **数据持久化**：建议将 `data/` 目录挂载到持久卷，避免容器重建导致知识库与会话丢失（回应 #804）；
3. **MCP 端点暴露**：`/mcp` 默认与 HTTP API 同端口，如需对外暴露请配置反向代理与鉴权；
4. **Skills 同步**：API 变更必须同步更新 `skills/langbot-dev` 等技能文件（README 中明确要求）；
5. **插件市场查看**：社区 #1097 建议在插件市场内嵌详情页，便于用户在安装前预览插件效果与配置说明。

## See Also

- [README.md](https://github.com/langbot-app/LangBot/blob/main/README.md) — 项目总体说明与功能矩阵
- [skills/README.md](https://github.com/langbot-app/LangBot/blob/main/skills/README.md) — Agent 技能目录
- [src/langbot/pkg/api/mcp/](https://github.com/langbot-app/LangBot/blob/main/src/langbot/pkg/api/mcp/) — MCP 服务器实现
- [examples/web-page-bot/README.md](https://github.com/langbot-app/LangBot/blob/main/examples/web-page-bot/README.md) — Page Bot 嵌入示例

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：langbot-app/LangBot

摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：运行坑 - 来源证据：[Bug]: 无法回复消息。

## 1. 运行坑 · 来源证据：[Bug]: 无法回复消息

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug]: 无法回复消息
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/langbot-app/LangBot/issues/2275 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：[Bug]: Gemini 无法调用工具，需要思路签名 Function call is missing a thought_signature in functionCall parts.

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Gemini 无法调用工具，需要思路签名 Function call is missing a thought_signature in functionCall parts.
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/langbot-app/LangBot/issues/1899 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

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

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

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

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/langbot-app/LangBot | no_demo; severity=medium

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

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

## 8. 安全/权限坑 · 来源证据：Skill activation: `/workspace/.skills/<name>` missing scripts/data subdirs on docker backend (nested bind mount)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Skill activation: `/workspace/.skills/<name>` missing scripts/data subdirs on docker backend (nested bind mount)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/langbot-app/LangBot/issues/2271 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

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

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

<!-- canonical_name: langbot-app/LangBot; human_manual_source: deepwiki_human_wiki -->