把 Dify 应用接进企业微信客服：装一个运行器插件，让 Agent 接管 message.received

场景

客服团队把知识库、提示词和工具都放在 Dify 应用里，企业微信客服这边只负责接客户：客户的问题要人工念给 Dify，再把回答抄回会话。

4.10 里让 Dify 自己回答只能走流水线：把 Dify 当供应商（Dify service API）接进一条流水线。能跑，但同一套编排存在两份——Dify 画布一份、LangBot 流水线一份；一条流水线又只能挂一个机器人，Dify 侧改了编排还得回来对参数。

4.11 换了接法：处理器可以是 Agent，Agent 的运行器由插件提供。于是「让 Dify 应用回答企业微信客服的消息」变成三件配置动作——装插件、建一个填好 Dify 连接信息的 Agent、把机器人的 message.received 路由指过去。下面在本地实例上走一遍。

4.11 里怎么做

运行器（Runner）从插件市场来。 4.11 把原先内置在宿主里的各类 runner 拆成插件发布，Dify 对应官方插件 langbot-team/DifyAgent，运行器 id 是 plugin:langbot-team/DifyAgent/default（官方文档 docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md:29 的映射表：旧 dify-service-api → langbot-team/DifyAgent）。文档把它归入 Batch 1（同文件 :45），并写明旧内置 runner 代码不再提供运行时 fallback（同文件 :22）：4.11 里要用 Dify，先把插件装上。

连接信息填在处理器的运行器配置里。 处理器的「运行器」选中 Dify Agent 之后，要填的就是 Dify 这一侧的信息。本次实测（2026-10-16）读到的字段：基础 URL（本示例 http://dify:5001/v1）、API 密钥、超时（30）、过期（3600）、身份（发送者）；保存后提示「保存成功」。

事件路由只管「事件 → 处理器」，第 1 条命中即用。 匹配顺序是「按 priority 从高到低选择，同优先级按列表顺序，只执行一个响应目标」（官方文档 docs/event-based-agents/04-event-routing.md:118-119）。所以只留一条 message.received 路由：同一事件再挂第二条，也不会让 Dify 多跑一次。

能选到什么事件由适配器声明。 本次实测的适配器声明了 message.received、message.deleted、wecomcs.enter_session 等事件，以及 send_message、reply_message、get_message、get_user_info 这组 API（源码 LangBot/src/langbot/pkg/platform/adapters/wecomcs/adapter.py:79-99）；事件路由里的「常用场景」预设也按适配器声明的事件过滤，没声明的事件不出现在预设里（源码 LangBot/web/src/app/home/bots/components/bot-form/EventBindingsEditor.tsx:1554-1559）。具体支持取决于适配器/平台，请先核对支持矩阵。

动手：步骤

起一个本地演示实例（下面命令与录制现场一致）：

docker network create a4
docker run -d --name a4-core --network a4 --restart on-failure -e TZ=Asia/Shanghai \
  -e BOX__ENABLED=false -e SPACE__DISABLE_TELEMETRY=true -p 15800:5300 \
  -v "$PWD/deploy/a4/data:/app/data" rockchin/langbot:v4.11.0
docker run -d --name a4-runtime --network a4 --network-alias langbot_plugin_runtime --restart on-failure \
  -e TZ=Asia/Shanghai -e SPACE__DISABLE_TELEMETRY=true -v "$PWD/deploy/a4/data/plugins:/app/data/plugins" \
  rockchin/langbot:v4.11.0 uv run --no-sync -m langbot_plugin.cli.__init__ rt

管理员初始账号 demo@langbot.local，初始密码 LangBot411!demo（本地演示值，请自行替换）。

1. 建企业微信客服机器人：机器人 → 新建 → 消息平台选 企业微信客服，填 企业ID、密钥、令牌、消息加解密密钥 四个必填项与 Webhook 回调地址（非必填，真实收发需要公网可达的地址）；字段清单来自 LangBot/src/langbot/pkg/platform/sources/wecomcs.yaml（标了 spec.legacy: true）。实例填的是本地演示值，所以不会出现真实客户消息。

2. 装 Dify Agent 运行器插件：扩展市场 → 搜索 Dify → 卡片「Dify Agent」→ 安装。本次实测（2026-10-16）的进度框文本是「已完成」「100%」「包大小: 169.8 KB」「安装成功」，安装后的卡片 aria-label="已安装 Dify Agent"，插件包署名 langbot-team/DifyAgent。

3. 建 Agent 并选运行器：处理器 → 新建 → 处理方式选 Agent → 「运行器」里选 Dify Agent（本次实测的处理器名是 dify-wecomcs-agent）。

4. 填 Dify 连接信息：基础 URL 填运行时容器能访问到的地址（本演示取 Docker 别名 dify，故为 http://dify:5001/v1，本地演示值，请自行替换）；API 密钥 填 app-demo-dify-key（本地演示值，请自行替换）；超时 30、过期 3600、身份 发送者，保存后出现「保存成功」。

5. 绑定事件路由：机器人详情页（/home/bots?id=<uuid>，查询参数形式，见源码 LangBot/web/src/app/home/bots/page.tsx:7-8）→「事件路由」→ 第 1 条路由 收到消息 message.received 的处理器由 ⚙️ 企业微信客服 流水线 改绑 🤖 dify-wecomcs-agent；保存后重载页面，确认没变回去。
6. 检查路由：同一页点「检查路由」，本次实测（2026-10-16）的返回逐字是 已命中路由 | 目标处理器 | Agent · dify-wecomcs-agent | 命中规则 | 第 1 条路由 | 诊断步骤 | 已选择第 1 条路由。

7. 跑一次事件调试：Agent 详情 → 事件调试 → 运行测试，发一条测试消息（本示例问「请问你们支持私有化部署吗？」）。

验证

只验证两件事：路由上的处理器是不是这个 Agent，消息有没有真的到达 Dify 应用并带回回答。

第一件看「检查路由」的逐字返回（本次实测（2026-10-16））：

已命中路由 | 目标处理器 | Agent · dify-wecomcs-agent | 命中规则 | 第 1 条路由 | 诊断步骤 | 已选择第 1 条路由。

第二件看 Dify 端点侧的请求日志。本次实测用的是本地 Dify 兼容端点（容器 lang7-dify，deploy/a4/dify-stub.py，别名 dify，宿主 127.0.0.1:18710 → 5001，只实现 POST /v1/chat-messages）：

docker logs lang7-dify

一次触发的日志行逐字：

[2026-10-16T16:28:29] POST /v1/chat-messages auth=Bearer app-dem... body={"inputs": {}, "query": "请问你们支持私有化部署吗？", "user": "lb_3ae22b5eaf4cf199693bee82712ae06f5ea6c21128cd9feab3dc347985a5e56", "response_mode": "streaming", "conversation_id": "", "files": []}

换成你自己的 Dify 站点时，看访问日志里出现 /v1/chat-messages 的 POST、query 就是你发的那句话即可。

别据此断言多轮会话。 同一次调试共触发 3 次（16:28:29、16:28:50、16:38:28），三次的 conversation_id 都是空串：这份记录只能证明「消息送到了 Dify 应用并取回回答」，不能证明续接。[推断] 运行器插件从 ctx.state.conversation["external.conversation_id"] 取会话 id，取不到就传空串，所以首次调用必然没有 id；后续是否带上 id，取决于插件有没有把 Dify 返回的 conversation_id 写回 state。官方文档对外部运行器的要求与此一致：平台会话 id 存 plugin storage 或 context runtime state（官方文档 docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md §6）。待确认。

边界与注意

• 本文的 Dify 端点不是真实 Dify 部署。 本地端点只实现了 POST /v1/chat-messages；基础 URL 与 API 密钥 都要换成你自己 Dify 站点的值（本地演示值，请自行替换）。
• 没有真实企业微信客户消息进入系统。 真实收发需要企业微信后台的 企业ID、密钥、令牌、消息加解密密钥 与公网可达的回调地址；实例填的都是本地演示值。本篇验证到的是「配置动作生效 + Agent 与 Dify 应用之间的往返」，不是客户在手机上的真实对话。具体支持取决于适配器/平台，请先核对支持矩阵。
• 调试运行时的平台动作是模拟的。 调试页写着：「平台工具使用 Mock：Agent 真实调用工具，回复、发送等平台动作模拟执行，不发送真实消息。其他工具仍按实际配置执行。」（本次实测（2026-10-16）逐字）——调试通过不等于企业微信侧投递生效。
• 多轮续接待确认。 三次触发的 conversation_id 均为空串，本文不据此宣称会话续接。
• 一个事件只有一个响应目标。 同一事件再挂一条路由不会让 Dify 多跑一次；改绑时注意别把原流水线留在同一事件上（本次实测即把第 1 条路由的处理器从流水线改成该 Agent）。
• 运行器是插件，不是宿主内置功能。 旧内置 runner 无运行时 fallback（官方文档 docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md:22），换机器或换环境时要把插件一起装上。

小结与下一步

把 Dify 应用接到企业微信客服，4.11 里就是三件配置动作：装 langbot-team/DifyAgent 运行器插件 → 建一个处理方式为 Agent 的处理器、填 Dify 的 基础 URL 与 API 密钥 → 把机器人的 message.received 路由指到它。本文实测走通了「消息到达 Dify 应用并取回回答」这一段。

主参考是冻结的迁移文档 pipeline-migration-config-map.zh-CN.md：从 4.10 升级上来时，旧流水线里配过的 Dify 供应商会给出对应的插件与配置映射。系列第 2、3 篇分别讲运行器插件的来源与 4.10 → 4.11 的升级。想省掉自建实例的运行维护，可以再评估托管方式（space.langbot.app）；本文只覆盖自建实例，对托管环境不做承诺。