企业微信 AI 机器人 PHP SDK —— 免回调地址，三行代码接入，支持流式回复

大家好，分享一个我刚开源的 PHP 扩展包：WeComAiBot —— 企业微信 AI 机器人 PHP SDK。

GitHub: github.com/bangbangda/wecomaibot

做这个包的原因

企业微信官方提供了 AI 机器人的 WebSocket 长连接通道，Node.js 有官方 SDK（@wecom/aibot-node-sdk），但 PHP 生态一片空白。

传统的 HTTP 回调方式，需要公网 IP、域名、SSL 证书，还要处理 5 秒超时——光是环境准备就劝退一大半人。

所以我基于 Workerman 做了这个 SDK，通过 WebSocket 长连接与企微服务器通信，彻底省掉回调地址配置。内网、本地、开发机上都能直接跑。

安装

composer  require  bangbangda/wecomaibot

没有第二步。

三行代码启动

$bot = new  WeComBot([

'bot_id' => 'your-bot-id',

'secret' => 'your-secret',

]);

$bot->onMessage(function (Message  $message, Reply  $reply) {

$reply->text("你好！你说的是：{$message->text}");

});

$bot->start();

php  your-bot.php  start

没了。机器人就活了。

主要特性

• 零门槛接入 — 免回调地址，免 SSL，免公网 IP，内网直接跑

• 流式回复 — 支持”思考中”加载动画 → 逐步更新 → 最终回复，像 ChatGPT 那样的打字效果

• 主动推送 — 不用等用户说话，机器人可以主动找人/找群发消息

• 模板卡片 — 推送交互式卡片，监听按钮点击，5 秒内更新卡片状态

• 全消息类型 — 文本、语音（自动转文字）、图片、文件、图文混排、引用消息

• 文件下载解密 — 企微传输的图片/文件经 AES-256-CBC 加密，SDK 一键下载并解密

• 断线自动重连 — 指数退避 + 随机抖动，心跳保活

• 串行发送队列 — 发送后等 ack 再发下一帧，告别消息丢失和乱序

• 多机器人管理 — 一个进程跑多个 bot，各自独立连接，数据完全隔离

• Laravel 深度集成 — ServiceProvider 自动注册，php artisan wecom:serve 一键启动

流式回复（”思考中”效果）

像 ChatGPT 一样，先显示加载动画，再逐步输出回复内容：

$bot->onMessage(function (Message  $message, Reply  $reply) {

// 立即显示"思考中"加载动画

$reply->stream('<think></think>', finish: false);

// 模拟 AI 处理（实际场景替换成你的 AI 接口调用）

Timer::add(2, function () use ($reply, $message) {

$reply->stream("关于「{$message->text}」，我的回答是...", finish: true);

}, [], false);

});

主动推送消息

不用等用户说话，机器人主动找人。支持单聊和群聊：

$bot->onAuthenticated(function () use ($bot) {

// 推送给指定用户

$bot->pushToUser('zhangsan', '你好，提醒你下午 3 点有个会议');

// 推送到群聊

$bot->pushToGroup('group-chat-id', '各位注意，系统将在 5 分钟后维护');

});

模板卡片消息

推送交互式卡片，监听按钮点击，实时更新卡片状态：

// 推送卡片

$bot->pushTemplateCardToUser('zhangsan', [

'card_type' => 'button_interaction',

'main_title' => ['title' => '服务器告警', 'desc' => 'CPU 超过 90%'],

'button_list' => [

['text' => '确认', 'style' => 1, 'key' => 'confirm'],

['text' => '误报', 'style' => 2, 'key' => 'false_alarm'],

],

'task_id' => 'ALERT_001',

]);

// 监听点击 + 更新卡片

$bot->onTemplateCardEvent(function (Event  $event) use ($bot) {

$bot->updateTemplateCard($event->reqId, [

'card_type' => 'button_interaction',

'main_title' => ['title' => '服务器告警', 'desc' => '已处理'],

'button_list' => [['text' => '已确认', 'style' => 1, 'key' => 'confirm']],

'task_id' => $event->eventData['task_id'] ?? '',

]);

});

Laravel 集成

1. 发布配置 + 设置环境变量：

php  artisan  vendor:publish  --tag=wecomaibot-config

WECOM_BOT_ID=your-bot-id

WECOM_BOT_SECRET=your-bot-secret

2. 写一个 Handler：

// app/Services/WeComHandler.php

class  WeComHandler

{

public  function  onMessage(Message  $message, Reply  $reply): void

{

$reply->text("Echo: {$message->text}");

}

}

3. 启动：

php  artisan  wecom:serve

完事。

环境要求

• PHP >= 8.1

• Composer

• 不需要任何额外 PHP 扩展（纯 PHP 实现）

生产部署

推荐用 Supervisor 守护常驻进程：

[program:wecom-bot]

command=php /path/to/your-bot.php start

autostart=true

autorestart=true

redirect_stderr=true

stdout_logfile=/var/log/wecom-bot.log

也支持 Workerman 自带的守护模式：

php  your-bot.php  start  -d  # 后台运行

php  your-bot.php  status  # 查看状态

php  your-bot.php  stop  # 停止

链接

• GitHub: github.com/bangbangda/wecomaibot

• Packagist: composer require bangbangda/wecomaibot

• 协议: MIT

---

欢迎 Star、Issue、PR。有问题直接在 GitHub 提 Issue 就好。

PHP 是世界上最好的语言，这件事不接受反驳。

本作品采用《CC 协议》，转载必须注明作者和本文链接