nanocode/weixin-nanobot-bridge/docs/weixin-agent-integration.md

weixin-agent-sdk 集成指南

安装 weixin-agent-sdk

# 安装 Node.js >= 22
node --version

# 安装 weixin-agent-sdk
npm install -g weixin-agent-sdk

创建 nanobot 适配器

创建文件 nanobot-adapter.js：

const { Agent, login, start } = require('weixin-agent-sdk');
const axios = require('axios');

const NANOBOT_BRIDGE_URL = process.env.NANOBOT_BRIDGE_URL || 'http://localhost:5000/chat';

const nanobotAgent = {
  async chat(request) {
    try {
      const response = await axios.post(NANOBOT_BRIDGE_URL, {
        conversationId: request.conversationId,
        text: request.text,
        media: request.media
      }, {
        timeout: 70000  // 70秒超时（比 nanobot 稍长）
      });
      
      return {
        text: response.data.text,
        media: response.data.media
      };
    } catch (error) {
      console.error('调用 nanobot bridge 失败:', error.message);
      return {
        text: '服务暂时不可用，请稍后再试'
      };
    }
  }
};

async function main() {
  console.log('🔌 连接到 nanobot bridge:', NANOBOT_BRIDGE_URL);
  
  // 扫码登录微信
  await login();
  
  // 启动消息循环
  await start(nanobotAgent);
}

main().catch(console.error);

启动步骤

1. 启动 nanobot bridge（终端 1）

cd /home/ubuntu/nanocode/weixin-nanobot-bridge
./scripts/start.sh

等待看到：

🚀 启动 WeChat-Nanobot Bridge
📡 服务地址: http://localhost:5000

2. 测试 bridge（可选）

./scripts/test.sh

3. 启动微信适配器（终端 2）

cd /home/ubuntu/nanocode/weixin-nanobot-bridge

# 安装依赖
npm install axios weixin-agent-sdk

# 设置桥接地址
export NANOBOT_BRIDGE_URL=http://localhost:5000/chat

# 启动
node nanobot-adapter.js

4. 扫码登录

运行后会显示二维码，用微信扫码登录。

消息流程

用户微信消息
    ↓
weixin-agent-sdk 接收
    ↓
nanobot-adapter.js 转发
    ↓
HTTP POST /chat
    ↓
weixin-nanobot-bridge 处理
    ↓
nanobot 生成回复
    ↓
逐级返回给用户

支持的微信消息类型

类型	支持状态	说明
文本	✅ 完整支持	直接转发给 nanobot
图片	⚠️ 部分支持	发送图片 URL，nanobot 需支持图像识别
语音	⚠️ 转文字后支持	weixin-agent-sdk 自动转为文字
视频	❌ 暂不支持	可发送文字说明
文件	⚠️ 部分支持	发送文件描述
引用消息	✅ 支持	作为上下文的一部分

安全注意事项

1. 微信封号风险

• 非官方项目，可能违反微信用户协议
• 建议：
  • 使用小号测试
  • 不要频繁发送消息
  • 避免发送敏感内容

2. nanobot 权限限制

当前配置禁止以下操作：

• 删除系统文件 (rm -rf /)
• 格式化磁盘 (mkfs)
• 关机和重启命令
• 访问敏感文件 (~/.ssh/*)

3. 速率限制

• 每分钟最多 10 条消息
• 超过限制会提示"请求过于频繁"

故障排查

问题 1: 无法连接到 bridge

# 检查 bridge 是否运行
curl http://localhost:5000/health

# 检查端口占用
lsof -i :5000

问题 2: nanobot 无响应

# 检查 nanobot 命令是否可用
which nanobot
nanobot --version

# 查看 bridge 日志
tail -f logs/server.log

问题 3: 微信登录失败

• 确保 Node.js >= 22
• 检查网络连接
• 尝试重新扫码

问题 4: 消息发送失败

• 检查 NANOBOT_BRIDGE_URL 环境变量
• 确认 bridge 和适配器在同一网络
• 查看适配器输出日志

生产环境部署

使用 systemd 管理服务

创建 /etc/systemd/system/weixin-nanobot-bridge.service：

[Unit]
Description=WeChat Nanobot Bridge
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/nanocode/weixin-nanobot-bridge
ExecStart=/home/ubuntu/nanocode/weixin-nanobot-bridge/venv/bin/python3 src/server.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl enable weixin-nanobot-bridge
sudo systemctl start weixin-nanobot-bridge
sudo systemctl status weixin-nanobot-bridge

使用 nginx 反向代理

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

后续优化方向

1. 多模态支持

   • 图片理解和生成
   • 文件内容摘要

2. 用户管理

   • 白名单机制
   • 用户权限分级

3. 群聊支持

   • @ 机器人触发
   • 群上下文管理

4. 性能优化

   • 消息队列
   • 并发处理

5. 监控告警

   • 服务状态监控
   • 异常告警通知