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

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

做这个包的原因

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

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

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

安装

bash 复制代码

composer require bangbangda/wecomaibot

没有第二步。

三行代码启动

php 复制代码

$bot = new WeComBot([
    'bot_id' => 'your-bot-id',
    'secret' => 'your-secret',
]);

$bot->onMessage(function (Message $message, Reply $reply) {
    $reply->text("你好！你说的是：{$message->text}");
});

$bot->start();

bash 复制代码

php your-bot.php start

没了。机器人就活了。

主要特性

零门槛接入 --- 免回调地址，免 SSL，免公网 IP，内网直接跑
流式回复 --- 支持"思考中"加载动画 → 逐步更新 → 最终回复，像 ChatGPT 那样的打字效果
主动推送 --- 不用等用户说话，机器人可以主动找人/找群发消息
模板卡片 --- 推送交互式卡片，监听按钮点击，5 秒内更新卡片状态
全消息类型 --- 文本、语音（自动转文字）、图片、文件、图文混排、引用消息
文件下载解密 --- 企微传输的图片/文件经 AES-256-CBC 加密，SDK 一键下载并解密
断线自动重连 --- 指数退避 + 随机抖动，心跳保活
串行发送队列 --- 发送后等 ack 再发下一帧，告别消息丢失和乱序
多机器人管理 --- 一个进程跑多个 bot，各自独立连接，数据完全隔离
Laravel 深度集成 --- ServiceProvider 自动注册，php artisan wecom:serve 一键启动

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

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

php 复制代码

$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);
});

主动推送消息

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

php 复制代码

$bot->onAuthenticated(function () use ($bot) {
    // 推送给指定用户
    $bot->pushToUser('zhangsan', '你好，提醒你下午 3 点有个会议');

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

模板卡片消息

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

php 复制代码

// 推送卡片
$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. 发布配置 + 设置环境变量：

bash 复制代码

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

env 复制代码

WECOM_BOT_ID=your-bot-id
WECOM_BOT_SECRET=your-bot-secret

2. 写一个 Handler：

php 复制代码

// app/Services/WeComHandler.php
class WeComHandler
{
    public function onMessage(Message $message, Reply $reply): void
    {
        $reply->text("Echo: {$message->text}");
    }
}

3. 启动：

bash 复制代码

php artisan wecom:serve

完事。

多机器人管理

一个进程同时跑多个机器人，销售部、财务部、客服部各一个，互不干扰：

php 复制代码

$manager = new BotManager();

$salesBot = $manager->addBot('sales', ['bot_id' => '...', 'secret' => '...']);
$salesBot->onMessage(fn(Message $msg, Reply $reply) => $reply->text("【销售助手】{$msg->text}"));

$financeBot = $manager->addBot('finance', ['bot_id' => '...', 'secret' => '...']);
$financeBot->onMessage(fn(Message $msg, Reply $reply) => $reply->text("【财务助手】{$msg->text}"));

$manager->start();

环境要求

PHP >= 8.1
Composer
不需要任何额外 PHP 扩展（纯 PHP 实现）

生产部署

推荐用 Supervisor 守护常驻进程：

ini 复制代码

[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 自带的守护模式：

bash 复制代码

php your-bot.php start -d   # 后台运行
php your-bot.php status     # 查看状态
php your-bot.php stop       # 停止

链接

GitHub : github.com/bangbangda/...
Packagist : composer require bangbangda/wecomaibot
协议: MIT

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

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