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

# weixin-agent-sdk 集成指南

## 安装 weixin-agent-sdk

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

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

## 创建 nanobot 适配器

创建文件 `nanobot-adapter.js`：

```javascript
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）

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

等待看到：
```
🚀 启动 WeChat-Nanobot Bridge
📡 服务地址: http://localhost:5000
```

### 2. 测试 bridge（可选）

```bash
./scripts/test.sh
```

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

```bash
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

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

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

### 问题 2: nanobot 无响应

```bash
# 检查 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`：

```ini
[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
```

启动服务：
```bash
sudo systemctl enable weixin-nanobot-bridge
sudo systemctl start weixin-nanobot-bridge
sudo systemctl status weixin-nanobot-bridge
```

### 使用 nginx 反向代理

```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. **监控告警**
   - 服务状态监控
   - 异常告警通知