LangBot 项目说明书

Doramagic 项目包 · 项目说明书

LangBot 项目

生产级多平台智能机器人开发平台，支持 Discord、Slack、LINE、Telegram、微信公众号、企业微信、飞书、钉钉、QQ、Matrix 等平台，集成知识库编排、插件系统，可对接 ChatGPT、DeepSeek、Claude、Gemini、Dify、n8n 等大模型与工具链，快速构建 Agent 机器人。

Overview & System Architecture

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

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 适配器与平台支持

继续阅读本节完整说明和来源证据。

章节 流水线、模型与 RAG

继续阅读本节完整说明和来源证据。

章节 监控、可观测性与导出

继续阅读本节完整说明和来源证据。

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。

系统架构总览

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

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。

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 协议暴露 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 示例
Page Bot Adapter 示例
MCP Server 入口
LangBot Skills 目录

资料来源：README.md:1-50

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

LangBot 是一套用于构建 AI 即时通讯机器人的生产级开源平台，其核心是 Pipeline（消息处理流水线），负责把来自任意 IM 平台（Discord、Telegram、Slack、QQ、企业微信、飞书、钉钉、KOOK、邮件、Matrix 等）的消息路由到 LLM、可观测组件与回复发送端。README 中明确指出，LangBot 提供多轮对话、工具调用、多模态、流式...

章节 相关页面

继续阅读本节完整说明和来源证据。

一、总体定位与作用

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 工具，让外部 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 三层扩展机制

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。

五、扩展性最佳实践

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

Deployment, Configuration, Data Management & Operations

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

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 3.1 核心配置文件

继续阅读本节完整说明和来源证据。

章节 3.2 MCP Server 配置

继续阅读本节完整说明和来源证据。

章节 3.3 知识库配置

继续阅读本节完整说明和来源证据。

1. 概述与适用范围

资料来源：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 中的部署按钮与文档入口）。

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. 常见部署与运维注意事项

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

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：[Bug]: 无法回复消息

可能增加新用户试用和生产接入成本。

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

可能增加新用户试用和生产接入成本。

medium 可能修改宿主 AI 配置

安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。

medium 能力判断依赖假设

假设不成立时，用户拿不到承诺的能力。

Pitfall Log / 踩坑日志

项目：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

来源：Doramagic 发现、验证与编译记录

LangBot 项目

Overview & System Architecture

核心设计理念

系统架构总览

关键子系统

适配器与平台支持

流水线、模型与 RAG

监控、可观测性与导出

插件市场与扩展机制

部署与运行时

See Also

Platform Adapters & IM Integration

概述

支持的平台

适配器集成模式

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

社区驱动的演进方向

参见

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

一、总体定位与作用

二、Pipeline 与 AI/LLM 集成

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

四、RAG / Knowledge Base

五、扩展性最佳实践

See Also

Deployment, Configuration, Data Management & Operations

1. 概述与适用范围

2. 部署方式

3. 配置体系

3.1 核心配置文件

3.2 MCP Server 配置

3.3 知识库配置

4. 数据管理

4.1 监控数据导出

4.2 扩展项管理

4.3 历史对话持久化

5. 运维与 Skills 体系

5.1 Skills 目录

5.2 测试与校验

5.3 运行时监控与限流

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

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

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

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

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

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

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

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

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

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

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