首页 › 全部文章 › 开源引擎实操
01 企业微信专题

开源企微 AI 客服引擎实测单文件 Node.js,5 分钟自建

自建企微 AI 客服的工程量清单: 官方回调加解密、验签、知识库引擎、转人工、会话上下文。开源项目 wework-ai-kefu 把这些打包成一个文件 —— 3 条命令本地跑通,接企微后台只要 3 个环境变量。本文是上手实录。

微客AI团队 · 2026-11-17 · 阅读约 7 分钟 · 开源 MIT · Node.js ≥ 18 · 单文件零依赖 · 22 测试用例

先说结论: 这个开源引擎适合想自己掌控、又不想从零写加解密的团队。它只走企业微信官方回调接口(合规路线的原理见上一篇),单文件零依赖,MIT 商用免费,克隆下来 node 一下就能跑,接企微后台配置 3 个环境变量完成。以下是完整上手路径。

一、它是什么

wework-ai-kefu 是一个 GitHub 开源的企微 AI 客服框架,一个 JS 文件 + 一个示例知识库,就是全部。能力四件:

  • 知识库打分匹配: 关键词规则命中越多分越高,秒回常见问题;
  • 转人工词表: 投诉、退款、资金安全这类词命中即转人工并安抚,AI 不做承诺性表态;
  • 兜底话术: 没命中也不冷场,有默认回复,日志可查;
  • 会话上下文: 保留近 10 轮,连续追问有记忆。

企微官方回调的加解密(AES-256-CBC + SHA1 验签,含 GET 验证与 POST 双验签)已完整实现,用 Node 内置 crypto,所以零 npm 依赖。测试 22 个用例,CI 跑 Node 18/20/22 三个版本矩阵。

二、5 分钟跑通(本地)

要求只有一条: Node.js ≥ 18。

git clone https://github.com/22109906/wework-ai-kefu.git
cd wework-ai-kefu
node wework-ai-kefu.js

浏览器打开 http://127.0.0.1:3100/,本地控制台直接聊,三个试验感受引擎行为:

  • 输入「押金多少」→ 命中知识库规则,秒回标准答案;
  • 输入「我要投诉押金不给退」→ 触发转人工词,回安抚句并标记 handoff;
  • 输入「你们在火星有门店吗」→ 无命中,走兜底话术,不冷场。

想跑测试: npm test,22 个用例覆盖引擎逻辑、加解密回环、HTTP 接口与回调端到端。

三、知识库怎么写

客服大脑在 kb.sample.json,结构一目了然:

{ "rules": [{ "q": ["押金", "多少钱"], "a": "押金 300-800 元,归还后 1-3 个工作日退回。" }],
  "fallback": "这个问题我记下了,马上帮您确认下哈。",
  "persona": { "welcome": "您好,我是智能客服…", "humanKeywords": ["投诉", "退款", "资金安全"], "humanReply": "稍等哈,这边给您转专员处理。" } }

三条写法经验: q 是关键词组,多词规则要求语义重合才计高分,避免误命中; fallback 必须有,兜底是体验底线; 每条 a 别超过 300 字,信息密度优先 —— 结构化的短知识,现在 AI 检索引擎也偏好这种表达。改完保存重启即生效。

四、接企微官方回调

本地试好后,四步接真环境:

  1. 企业微信管理后台创建自建应用;
  2. 「接收消息」配置回调 URL 填 https://你的域名/wecom/callback,生成 Token 与 EncodingAESKey;
  3. 带环境变量启动: WECOM_TOKEN、WECOM_AES_KEY、WECOM_CORP_ID 三个;
  4. 后台点「保存」—— GET 验证(echostr 解密回显)自动通过,客户发消息即收到自动回复。

注: 公网回调需 HTTPS; 本地调试可用内网穿透把 3100 端口映射出去。

五、可选: 接大模型

不配置时是纯规则模式; 配置后 LLM 优先、规则兜底,LLM 调用失败自动回落,不冷场。任意 OpenAI 兼容接口都行(DeepSeek、通义千问、智谱、本地 Ollama 等):

LLM_BASE_URL=https://api.openai.com/v1 LLM_KEY=sk-xxx LLM_MODEL=gpt-4o-mini node wework-ai-kefu.js

系统提示词来自 persona.system,近 10 轮会话作为上下文。大模型路线的选型讨论见企微接大模型。

六、转人工安全阀

自动回复的底线是「该交给人的交给人」。词表放 persona.humanKeywords: 情绪类(投诉、曝光)、售后类(退款、扣钱)、风险类(资金安全)、业务边界(超范围、承诺性请求)。命中即返回安抚句并标记 handoff。两种消费方式:

  • 通知钩子: 设 HUMAN_NOTIFY_URL,每次转人工命中即 POST 给你的通道(企微群机器人 webhook、工单、IM),fire-and-forget 不阻塞回复;
  • 标记自取: 自建集成时直接读 /api/chat 返回里的 rule.handoff。

七、生产要点

上生产前四个开关值得知道:

  • 限速: RATE_PER_MIN 每 IP 每分钟上限,默认 30,设 0 关闭;
  • 会话淘汰: SESSIONS_MAX 会话 FIFO 上限,默认 2000,防内存涨;
  • 多实例: 会话默认存内存,多实例自己换 Redis;
  • 量级参考: 单实例中小客服量级(日均万级消息)轻松。

自建要服务器、要运维、要调知识库 —— 如果只想用结果,微客 AI 托管版把这些都包了(同样只走官方接口),见托管版详情。

02 常见疑问

关于这个开源引擎的 4 个疑问

会封号吗?
只走企业微信开放平台的官方回调 API,与任何第三方协议、hook、外挂无关。合规使用不存在封号问题。
免费商用吗?
MIT 协议,商用免费,保留署名即可。仓库里 LICENSE 文件是唯一法律依据。
需要企业认证吗?
注册企业微信组织免费,自建应用消息回调对未认证企业同样开放; 未认证主体有部分接口限制,以官方文档为准。
支持群聊吗?
当前版本聚焦单聊自动回复; 群聊 @ 消息回调在官方 Roadmap 里。
03 继续阅读

配套读这几篇

04 自建或托管

一个文件,5 分钟起步

clone → node → 浏览器开箱即试; 不想运维再看托管版。

GitHub 开源引擎

零依赖单文件

Node ≥ 18 直接跑, 加解密全用内置 crypto, 不装任何包。

官方回调全链路

GET 验证、POST 双验签、应答回签, 全按官方协议。

转人工安全阀

词表命中即安抚并标记, HUMAN_NOTIFY_URL 通知钩子直连你的通道。

MIT 开源,商用免费

22 个测试用例,CI 三版本矩阵全绿,clone 即用。

MIT · Node.js ≥ 18 · 单文件零依赖 · 官方接口合规路线