企业微信 → 小爱同学 TTS 桥接服务

通过企业微信长连接（WebSocket）接收智能机器人消息，调用小爱音箱 TTS 朗读出来。

你发什么，小爱就说什么。

---

工作原理

你在企业微信给机器人发消息
    → 企微服务器通过 WebSocket 推送消息给本服务
        → 调用小爱音箱 TTS API 朗读
            → 小爱音箱发声
                → 回复"已播报"到企微

全程无需公网 IP、域名、回调 URL，通过长连接主动连接企微，内网直接可用。

---

项目结构

wework_xiaoai_bot/
├── app/services/
│   ├── ws_client.py     # WebSocket 客户端（核心）
│   └── tts.py           # 小爱 TTS 服务
├── config.py            # 配置加载（从 .env 读取）
├── run.py               # 程序入口
├── save_token.py        # 小米 Token 续期工具
├── Dockerfile           # Docker 镜像
├── docker-compose.yml   # Docker 编排
├── deploy.sh            # NAS 一键部署脚本
├── requirements.txt     # Python 依赖
├── tests/               # 测试
├── .env.example         # 环境变量模板
└── README.md

---

前置条件

1. 企业微信智能机器人

在企微管理后台创建智能机器人，开启「API 模式」→「长连接」：

1. 登录 企业微信管理后台
2. 进入「应用管理」→「智能机器人」
3. 创建机器人，开启 API 模式，选择「长连接」
4. 获取 Bot ID 和 Secret

2. 小爱音箱

需要一个已配网的小爱音箱，且已登录小米账号。

---

快速开始（本地/Docker）

1. 配置

cp .env.example .env

编辑 .env，填入你的企微 Bot ID 和 Secret：

WECOM_BOT_ID=你的BotID
WECOM_BOT_SECRET=你的Secret

2. 生成小米 Token

在 Windows/Mac（有图形界面的机器）上运行一次：

pip install -r requirements.txt
python save_token.py

按提示输入小米密码，脚本自动生成 .mi.token 文件。

Token 有效期通常 1-3 个月。过期后重新运行此脚本即可。

3. 启动

Docker（推荐）

docker compose up -d

管理命令：

docker compose logs -f     # 查看实时日志
docker compose restart     # 重启
docker compose down        # 停止

直接运行

pip install -r requirements.txt
python run.py

---

NAS 部署（Docker）

1. 准备工作

在 Windows 上完成「快速开始」的第 1、2 步，确保 .env 和 .mi.token 都在项目目录下。

2. 传到 NAS

scp -r wework_xiaoai_bot/ user@nas-ip:/opt/wework_xiaoai_bot/

3. 在 NAS 上启动

ssh user@nas-ip
cd /opt/wework_xiaoai_bot
docker compose up -d

也可以用 deploy.sh 一键部署：

chmod +x deploy.sh
./deploy.sh <nas-ip> <用户名>

---

Token 续期

当 Token 过期（小爱播报失败，日志出现 Login failed）：

1. 在 Windows 上运行 python save_token.py
2. 将生成的 .mi.token 传到 NAS 项目目录
3. docker compose restart

---

配置说明

环境变量	说明	必填
WECOM_BOT_ID	企微智能机器人 Bot ID	是
WECOM_BOT_SECRET	企微智能机器人 Secret	是
XIAOMI_USER_ID	小米账号 ID	否
XIAOMI_TOKEN_PATH	小米 Token 文件路径	否（默认 .mi.token）
XIAOMI_SPEAKER_DID	小爱音箱设备 ID	否
TTS_ENABLED	是否启用 TTS	否（默认 true）
TTS_MAX_TEXT_LENGTH	最大播报长度	否（默认 500）

---

日志示例

正常运行时：

[INFO] Connecting to wss://openws.work.weixin.qq.com ...
[INFO] WebSocket connected
[INFO] Subscribed successfully
[INFO] Received: 你好世界
[INFO] TTS success

故障时自动重连：

[ERROR] Connection lost, reconnecting in 5s...
[INFO] WebSocket connected
[INFO] Subscribed successfully

---

技术要点

• 长连接：WebSocket wss://openws.work.weixin.qq.com，无需公网 IP
• 消息加解密：长连接模式免加解密，ws 协议层自带加密
• 心跳保活：WebSocket 层 + 应用层双重心跳，每 30 秒
• 断线重连：自动检测断线，5 秒后重连
• Token 保护：passToken 自动备份，防止 serviceToken 过期时丢失

---

依赖

aiohttp>=3.9.0
python-dotenv>=1.0.0
miservice_fork>=2.9.0

---

License

MIT