Dify接入企业微信客服：Runner插件化实战

将 Dify 的知识库和编排能力接入企业微信客服，过去需要搭建一条完整流水线，把 Dify 作为服务提供方嵌入 LangBot 的 pipeline。这种做法的代价是编排逻辑重复：Dify 画布是一套模型、提示词和会话设置，LangBot 流水线里又要再配一套，而且一条流水线只能服务一个机器人。LangBot 4.11 把处理器升级为 Agent，Runner 改为从插件市场安装，整个接入过程被压缩成三个配置动作。本文基于本地实例的实测记录，梳理具体步骤和需要留意的边界。

4.11 的架构变化：Runner 成为市场插件

在 4.11 中，Dify 不再是内置运行器，而是官方插件 langbot-team/DifyAgent，runner id 为 plugin:langbot-team/DifyAgent/default。官方文档 OFFICIAL_RUNNER_PLUGINS.md 明确将旧的 dify-service-api 运行器映射到该插件，并将其归入第一批“传统服务 API 运行器”，同时指出旧的内置运行器代码不再提供运行时回退。这意味着迁移到新版本后，任何环境都必须先安装插件，否则 Dify 连接无法生效。

另一个关键机制是事件路由。适配器声明平台支持的事件，企业微信客服适配器声明了 message.received、message.deleted、wecomcs.enter_session 等入站事件，以及 send_message、reply_message、get_message、get_user_info 等出站动作。路由按优先级从高到低匹配，命中第一条后只执行一个响应目标。这一点直接影响配置方式：同一个 message.received 事件上挂第二条路由，并不会让 Dify 被调用两次，反而可能产生非预期的行为。

Runner 与 Pipeline 的区别：在 LangBot 的早期架构中，Pipeline（流水线）是一个由用户自行编排的完整处理链，包含模型选择、提示词、会话管理等环节；而 Runner 更接近“运行器”的角色，负责驱动某种特定的后端服务（如 Dify、FastGPT 等）。4.11 将 Runner 从内置代码改为插件市场上可安装的插件，意味着核心不再预置任何服务 API 的运行逻辑，所有外部集成都必须以插件形式加载。这样做的好处是核心更轻、集成可独立更新，代价是部署时多了一步显式安装，且插件运行环境（容器网络、依赖）需要与核心对齐。

事件路由的优先级匹配机制：LangBot 的事件路由系统允许为同一类事件（如 message.received）配置多条路由规则，每条规则有优先级。系统按优先级从高到低逐条匹配，一旦某条规则的条件满足，就执行该规则指定的响应目标，并停止后续匹配。因此，同一个事件上挂第二条路由并不会让处理器被调用两次，而是作为备用或更低优先级的处理路径；如果第一条路由已经命中，第二条永远不会执行。这解释了为什么迁移时应将旧流水线路由替换为新 Agent 处理器，而不是新增一条路由。

三步完成接入的实操路径

第一步：创建企业微信客服机器人

在 Bots 页面新建机器人，平台选择“企业微信客服”。需要填写企业 ID、密钥、令牌和消息加解密密钥，Webhook 回调地址为可选项，但真实流量需要公网可访问的回调地址。本地演示实例保留了示例值，这些值在实际部署时必须替换。

第二步：从市场安装 Dify Agent 插件

进入 Marketplace 搜索 Dify，找到「Dify Agent」并安装。实测安装进度显示包大小 169.8 KB，安装完成后卡片带有 aria-label="已安装 Dify Agent" 标记。安装动作本身很快，但需要注意的是，插件运行时容器必须与 LangBot 核心在同一网络中，后续的 Dify 基础 URL 才能被解析到。

第三步：创建 Agent 模式处理器并填写连接信息

在 Processors 中新建处理器，模式选择 Agent，runner 选择 Dify Agent。处理器配置中需要填写 Dify 侧的值：基础 URL、API 密钥、超时（实测填 30）、过期（3600）以及身份（发送者）。基础 URL 必须从运行时容器内可访问，本地演示中使用了容器别名 dify，因此地址为 http://dify:5001/v1。API 密钥同样是演示值，真实部署需替换为自己 Dify 应用的密钥。

基础 URL 与容器网络：Dify 的基础 URL 是 LangBot 插件运行时访问 Dify API 的入口。在自托管部署中，LangBot 核心和 Dify 通常运行在同一个 Docker 网络内，因此可以使用容器别名（如 http://dify:5001/v1）而非公网地址。如果插件运行在独立的容器中，必须确保该容器与 Dify 容器在同一网络，否则即便 URL 格式正确也无法解析。此外，Dify 的 API 版本路径通常为 /v1，需与 Dify 部署的版本匹配。

API 密钥与身份字段：Dify 应用的 API 密钥在 Dify 控制台的“访问 API”页面生成，每个应用独立。LangBot 处理器中的“身份（发送者）”字段决定向 Dify 传递的用户标识，影响 Dify 侧的会话隔离和用量统计；通常填写发送者 ID 或固定值，需根据业务需求选择。超时和过期参数分别控制单次请求的超时时间和会话上下文的过期时间（秒），实测值 30 和 3600 可作为起点，但高延迟场景应适当调大超时。

第四步：绑定事件路由

进入机器人详情页，找到事件路由设置。默认的第 1 条路由是“收到消息 message.received”，将其处理器从旧的“企业微信客服 流水线”切换为新建的 dify-wecomcs-agent，然后重新加载。路由检查的返回值可以直接确认命中情况，实测回复为“已命中路由 | 目标处理器 | Agent · dify-wecomcs-agent | 命中规则 | 第 1 条路由”。

第五步：用事件调试验证链路

在 Agent 详情页进入事件调试，发送测试问题“请问你们支持私有化部署吗？”。调试页面会明确提示平台工具使用 Mock：Agent 真实调用工具，但回复、发送等平台动作是模拟执行，不会发送真实消息。因此调试通过只能证明配置生效且 Agent 与 Dify 之间的往返正常，不能证明企业微信侧的最终送达。

验证与关键边界

验证链路是否真正打通，最直接的方式是查看 Dify 端点的日志。实测中本地 Dify 兼容端点收到了一条 POST /v1/chat-messages 请求，请求体中的 query 正是调试时发送的那句话，response_mode 为 streaming。在自己的部署上，可以按同样的方式核对这条请求。

多轮对话的连续性在本次测试中未被证实。会话触发了三次，每次的 conversation_id 都是空字符串。作者推断，runner 插件从上下文状态中读取外部会话 ID，首次调用时该值为空；后续调用只有在插件把 Dify 返回的 conversation_id 写回状态后才会携带。官方文档建议外部运行器将该 ID 保存在插件存储或上下文运行时状态中，而不是依赖 LangBot 内部的会话结构。这一点仍需进一步确认。

conversation_id 的持久化机制：Dify 的对话 API 通过 conversation_id 字段维持多轮上下文。首次调用时该字段为空，Dify 会创建新会话并在响应中返回新的 conversation_id；后续调用需将该 ID 回传才能延续同一会话。在 LangBot 的插件架构中，外部运行器需要自行管理这个 ID 的存储——官方建议保存在插件存储或上下文运行时状态中，而不是依赖 LangBot 内部的会话结构。本次测试中三次调用均为空，说明插件尚未将 Dify 返回的 ID 写回状态，或写回后未被读取。要验证多轮连续性，可在 Dify 日志中观察第二次请求是否携带了非空的 conversation_id，或检查插件存储中是否有对应键值。

适用场景与限制清单

这套方案适合已经用 Dify 维护知识库和提示词、希望把它接入企业微信客服的团队，尤其是那些不想在流水线里重复维护一套模型和会话配置的场景。接入后，Dify 应用画布是唯一的编排入口，调整提示词或更换模型不需要在 LangBot 侧做同步修改。

需要留意的限制包括：演示环境不是真实的 Dify 部署，基础 URL 和 API 密钥必须替换；没有真实企业微信客户消息进入系统，真实流量依赖完整的企业微信凭证和公网回调地址，适配器与平台的支持范围需要先查支持矩阵；调试中的平台动作是模拟的；多轮连续性未验证；同一事件只能有一个响应目标，旧流水线不应继续挂在该事件上；Runner 是插件，旧内置运行器没有运行时回退，每个环境都需要单独安装插件。

如果不想自行维护实例，官方提供了托管选项 space.langbot.app，但本文的步骤仅针对自托管部署。迁移的配置映射可参考仓库中的 pipeline-migration-config-map.zh-CN.md，该文档将旧流水线中的 Dify 提供方映射到对应的插件和配置项。