@wwlocal/aibot-connector

企业微信私有化智能机器人连接器（Node.js版），可以通过简单配置将多个智能机器人和大模型/智能体服务建立连接，方便快速、便捷体验智能机器人功能。

核心能力

| 能力 | 说明 | |------|------| | 多账号管理 | 支持同时对接多个企微智能机器人和智能体服务 | | 多协议适配 | 支持 OpenAI、DeepSeek、Anthropic、Dify、自定义 Webhook 五种适配器 | | 思维链展示 | 支持 DeepSeek/Claude 推理模型的 thinking 内容折叠/显示/隐藏 | | 消息打断 | 用户发送新消息时自动中止正在进行的 AI 回复，立即处理新消息（可配置开关） | | 多轮对话 | 自动记忆对话历史（可配置轮数） | | 媒体处理 | 支持图片/文件的接收和发送 | | 模板卡片 | 支持企微模板卡片消息的生成与交互回调 | | 访问控制 | 私聊白名单、群组白名单、群内发送者白名单三层策略 | | 斜杠命令 | 内置 /new、/help 命令，可扩展的命令框架 |

技术特性

• 可插拔适配器架构：通过 provider 配置字段自动路由到对应适配器，新增 AI 平台只需实现一个适配器类
• 支持权限控制：可针对每一个智能机器人定义谁可以发送消息给机器人、哪些人在哪些群里可以发送消息
• 斜杠命令系统：消息处理管道内置命令拦截层，命中命令直接回复、不触发 AI 调用；新增命令只需实现 SlashCommand 接口并注册
• monitor 层统一节流：替代各适配器的分散节流，在 monitor 层统一控制中间帧发送频率
• 流式过期降级：当企微流式消息超过 6 分钟（errcode 846608）或遇到数据版本冲突（errcode 6000）时，自动降级为主动发送
• 全链路 AbortSignal 打断：用户新消息//stop 命令通过 AbortController 贯穿 monitor → forwarder → adapter → fetch，确保 AI 请求被及时终止
• LRU + TTL 内存管理：消息状态、对话历史、ReqId 存储均有容量限制和自动过期清理

技术栈与依赖

语言与运行时

• 语言：TypeScript 5.x（strict 模式）
• 运行时：Node.js（ESM 模块系统）
• 模块格式：ESM 优先，同时输出 CJS

核心依赖

| 包名 | 版本 | 用途 | |------|------|------| | @wecom/aibot-node-sdk | ^1.0.6 | 企微私有部署 WebSocket 连接、消息收发、认证 | | express | ^4.21.0 | HTTP 健康检查和状态 API | | file-type | ^21.3.0 | 通过文件 buffer 嗅探 MIME 类型 |

整体架构图

┌─────────────────────────────────────────────────────────────────────┐
│                      @wwlocal/aibot-connector                     │
│                                                                     │
│  ┌──────────┐   ┌──────────────┐   ┌─────────────────────────────┐  │
│  │ index.ts │──→│ ServiceManager│──→│  monitorWeComProvider()     │ │
│  │ (入口)    │   │ (多账号管理)  │   │  ┌──────────────────────┐    │ │
│  └──────────┘   └──────────────┘   │  │ WSClient (SDK)       │   │  │
│       │                             │  │ - 连接管理            │  │  │
│       │         ┌──────────────┐   │  │ - 消息监听            │   │  │
│       └────────→│ Express HTTP │   │  │ - 心跳保活            │   │  │
│                 │ /health      │   │  └──────────┬───────────┘   │ │
│                 │ /api/status  │   │             │               │ │
│                 └──────────────┘   │  ┌──────────▼───────────┐   │ │
│                                     │  │ processWeComMessage()│  │ │
│                                     │  │ 1. 解析消息内容        │  │ │
│                                     │  │ 2. 策略检查           │  │ │
│                                     │  │ 3. 下载媒体           │  │ │
│                                     │  │ 4. 斜杠命令拦截       │  │ │
│                                     │  │ 5. 初始化状态         │  │ │
│                                     │  │ 6. 转发到智能体       │  │ │
│                                     │  └──────────┬───────────┘  │ │
│                                     │             │               │ │
│                                     │  ┌──────────▼───────────┐  │ │
│                                     │  │ routeAndDispatchTo   │  │ │
│                                     │  │ Agent()              │  │ │
│                                     │  │ - thinking 消息       │  │ │
│                                     │  │ - deliver 回调       │  │ │
│                                     │  │ - monitor 层节流     │  │ │
│                                     │  │ - 流式中间帧         │  │ │
│                                     │  └──────────┬───────────┘  │ │
│                                     └─────────────┼───────────────┘ │
│                                                   │                 │
│  ┌────────────────────────────────────────────────▼──────────────┐  │
│  │                     Agent Forwarder                           │  │
│  │  ┌─────────────────────────────────────────────────────────┐  │  │
│  │  │              Adapter Registry (适配器注册表)              │  │  │
│  │  ├──────────┬──────────┬──────────┬─────────┬─────────────┤  │  │
│  │  │ OpenAI   │ DeepSeek │Anthropic │  Dify   │  Webhook    │  │  │
│  │  │ Adapter  │ Adapter  │ Adapter  │ Adapter │  Adapter    │  │  │
│  │  └──────────┴──────────┴──────────┴─────────┴─────────────┘  │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                     │
│                                   │                                 │
│                                   ▼                                 │
│                        ┌─────────────────┐                         │
│                        │ 第三方 AI 平台   │                         │
│                        │ (OpenAI/DS/...)  │                         │
│                        └─────────────────┘                         │
└─────────────────────────────────────────────────────────────────────┘

安装

# 全局安装
npm install -g @wwlocal/aibot-connector
# 查看所有相关路径
echo "Node 可执行文件: $(which node)"
echo "Node 版本: $(node -v)"
echo "npm 全局目录: $(npm root -g)"
echo "npm prefix: $(npm config get prefix)"

# 在项目目录中安装
# 1. 创建项目目录
mkdir ~/my-wecom-bot
cd ~/my-wecom-bot
# 2. 初始化 package.json
npm init -y
# 3. 安装依赖（会自动写入 package.json）
npm install @wwlocal/aibot-connector
# 包在 ~/my-wecom-bot/node_modules/ 下

# 检查安装
cd "$(npm root -g)"
npm list @wwlocal/aibot-connector
npm list @wecom/aibot-node-sdk

升级

# 全局安装升级
npm install -g @wwlocal/aibot-connector@latest

# 项目目录内升级
npm update @wwlocal/aibot-connector

# 查看当前版本
aibot-connector --version

升级后需要重启服务才能生效。配置文件（config.json）不会被覆盖。

配置

复制示例配置文件并修改：

cp config.example.json config.json

配置说明

{
  // HTTP 服务端口（默认 3000）
  "port": 3000,
  
  // 数据存储目录（媒体文件等）
  "dataDir": "./data",
  
  // 智能体端点列表
  "agents": [
    {
      "name": "default",                                    // 端点名称
      "provider": "openai",                                 // 适配器类型：openai / deepseek / anthropic / dify / webhook（默认 openai）
      "url": "https://api.openai.com/v1/chat/completions", // API URL
      "apiKey": "sk-xxx",                                   // API Key
      "model": "gpt-4o",                                    // 模型名称
      "stream": true,                                       // 启用流式（默认 true）
      "systemPrompt": "你是一个有用的助手",                   // 系统提示词
      "timeoutMs": 300000,                                   // 请求超时（默认 5 分钟）
      "maxHistoryRounds": 20,                                // 多轮对话最大保留轮数（0=禁用，默认 20）
      "headers": {},                                         // 自定义请求头（可选）
      "providerOptions": {}                                  // 适配器专属配置（可选，见下方各适配器说明）
    }
  ],
  
  // 企微账号列表
  "accounts": [
    {
      "accountId": "bot-1",           // 账号标识
      "name": "测试机器人",            // 显示名称
      "enabled": true,                // 是否启用（默认 true）
      "websocketUrl": "wss://...",    // WebSocket 连接地址
      "botId": "xxx",                 // 机器人 ID
      "secret": "xxx",                // 机器人密钥
      "caCert": "cert.pem",           // CA 证书文件名（可选）
      "sendThinkingMessage": true,    // 是否发送"正在思考…"提示（默认 true）
      "allowInterrupt": true,          // 是否允许用户新消息打断正在进行的 AI 回复（默认 true）
      
      // 访问控制
      "dmPolicy": "open",             // 私聊策略：open/allowlist/disabled
      "allowFrom": [],                // 私聊白名单 userid 列表
      "groupPolicy": "open",          // 群组策略：open/allowlist/disabled
      "groupAllowFrom": [],           // 群组白名单 chatid 列表
      "groups": {},                   // 群聊专属配置（可为不同群指定不同的 agent）
      
      // 媒体与智能体
      "mediaLocalRoots": [],          // 本地媒体文件搜索路径
      "agentName": "default"          // 使用的智能体端点名称
    }
  ]
}

启动

全局安装后启动（推荐）

# 使用默认配置文件（当前目录下的 ./config.json）
aibot-connector

# 指定配置文件路径
aibot-connector /path/to/config.json

# 通过环境变量指定
AIBOT_CONFIG=/path/to/config.json aibot-connector

在项目目录内启动

# 进入项目目录
cd /path/to/aibot-connector

# 使用默认配置文件（./config.json）
npm start

# 指定配置文件
npm start -- /path/to/config.json

# 通过环境变量指定
AIBOT_CONFIG=/path/to/config.json npm start

注意：npm start 必须在包含 package.json 的目录下运行。全局安装时推荐使用 aibot-connector 命令。

对接第三方智能体示例

连接器内置多种适配器，通过 provider 字段选择。OpenAI 适配器同时兼容所有 OpenAI API 兼容服务。

OpenAI（默认）

兼容所有 OpenAI Chat Completions API 的服务（包括 Azure OpenAI、Ollama、vLLM 等）。

{
  "name": "openai",
  "provider": "openai",
  "url": "https://api.openai.com/v1/chat/completions",
  "apiKey": "sk-xxx",
  "model": "gpt-4o"
}

DeepSeek

支持普通对话模型（deepseek-chat）、推理模型（deepseek-reasoner）和 V4 Pro（deepseek-v4-pro）。

注意：DeepSeek 系列模型不支持图片/多模态输入。收到图片时，适配器会自动将图片转为纯文本描述（文件名、类型、路径），而非发送图片内容给模型。如需图片理解能力，请使用支持多模态的模型（如 OpenAI GPT-4o、智谱 GLM-4V 等）。

DeepSeek V4 Pro（推荐配置）

V4 Pro 支持思考模式（thinking），会在回复前生成推理过程。

{
  "name": "deepseek-v4-pro",
  "provider": "deepseek",
  "url": "https://api.deepseek.com/chat/completions",
  "apiKey": "sk-xxx",
  "model": "deepseek-v4-pro",
  "providerOptions": {
    "reasoningDisplay": "collapse",
    "reasoningEffort": "high"
  }
}

Thinking 模式（思考模式）

DeepSeek 适配器通过 {"thinking": {"type": "enabled/disabled"}} 控制是否启用思考模式。

自动检测规则：模型名包含 reasoner 或 v4-pro 时自动启用 thinking，其他模型默认不启用。

可通过 providerOptions.enableThinking 显式覆盖：

{
  "providerOptions": {
    // 显式启用（默认，reasoner/v4-pro 模型无需设置）
    "enableThinking": true,
    // 或显式禁用
    "enableThinking": false
  }
}

| enableThinking 值 | 效果 | |---|---| | true / "enabled" | 发送 {"thinking": {"type": "enabled"}} | | false / "disabled" | 发送 {"thinking": {"type": "disabled"}} | | 未设置 + 模型名含 reasoner/v4-pro | 自动启用 | | 未设置 + 其他模型 | 自动禁用 |

Reasoning Effort（思考强度）

仅在 thinking 模式启用时生效，控制模型的推理深度：

{
  "providerOptions": {
    "reasoningEffort": "high"   // "high"（默认）或 "max"（复杂任务推荐）
  }
}

对应请求体中的 {"reasoning_effort": "high/max"} 参数。

Reasoning Display（思维链展示）

控制企微客户端中推理过程的展示方式：

| 模式 | 效果 | |---|---| | collapse（默认） | 推理过程包裹在 <think>...</think> 标签中，企微客户端折叠展示 | | show | 推理过程与回答内容一起直接展示 | | hide | 仅展示回答，完全隐藏推理过程 |

DeepSeek providerOptions 汇总

| 选项 | 类型 | 默认值 | 说明 | |---|---|---|---| | enableThinking | boolean \| "enabled" \| "disabled" | 自动检测 | 是否启用思考模式 | | reasoningEffort | "high" \| "max" | — | 思考强度（仅 thinking 启用时生效） | | reasoningDisplay | "show" \| "hide" \| "collapse" | "collapse" | 思维链在企微客户端的展示方式 |

Anthropic Claude

支持 Anthropic 原生 Messages API，以及第三方兼容平台（如 MiniMax）。

{
  "name": "claude-sonnet",
  "provider": "anthropic",
  "url": "https://api.anthropic.com/v1/messages",
  "apiKey": "sk-ant-xxx",
  "model": "claude-sonnet-4-20250514",
  "providerOptions": {
    "maxTokens": 8192,
    "reasoningDisplay": "collapse",
    "useXApiKey": true,
    "anthropicVersion": "2023-06-01"
  }
}

Dify

对接 Dify Chatflow 应用。

{
  "name": "dify-assistant",
  "provider": "dify",
  "url": "https://api.dify.ai/v1/chat-messages",
  "apiKey": "app-your-dify-app-key",
  "providerOptions": {
    "difyAppType": "chat",
    "difyInputs": {
      "language": "zh-CN"
    }
  }
}

本地模型（Ollama）

{
  "name": "ollama",
  "provider": "openai",
  "url": "http://localhost:11434/v1/chat/completions",
  "model": "llama3"
}

providerOptions 参考

| 适配器 | 选项 | 说明 | |--------|------|------| | openai | imageUrlFormat | 图片 base64 格式：data_uri（默认，OpenAI 标准）/ raw_base64（纯 base64，智谱 GLM 等平台） | | deepseek | — | 见上方 DeepSeek 章节的 providerOptions 汇总表 | | anthropic | maxTokens | Anthropic API 必传的 max_tokens（默认 4096） | | anthropic | reasoningDisplay | 思维链展示模式：show / hide / collapse | | anthropic | useXApiKey | 是否使用 x-api-key 头认证（默认 true）。第三方平台设为 false | | anthropic | anthropicVersion | API 版本头（默认 2023-06-01） | | dify | difyAppType | Dify 应用类型：chat | | dify | difyInputs | 传递给 Dify 工作流的自定义变量 | | webhook | requestTemplate | 请求体模板，支持 {{text}}、{{user}}、{{chatId}} 变量 | | webhook | responseTextField | 响应 JSON 中提取回复文本的字段路径（支持嵌套，如 data.reply.content） |

斜杠命令

在会话中发送 /命令 即可触发，命令大小写不敏感。未注册的命令（如 /unknown）会当作普通消息转发给 AI，不会被拦截。

内置命令

| 命令 | 别名 | 说明 | |------|------|------| | /new | /clear | 清除当前会话的对话历史，开始全新对话 | | /stop | /abort | 终止正在进行的 AI 回复 | | /help | — | 列出所有可用命令及说明 | | /health | — | 查看服务健康状态（版本、运行时长） | | /status | — | 查看各账号连接状态 |

/new

清除当前聊天的对话历史（ConversationManager 多轮记忆）和 Dify conversation_id 缓存，开启全新会话。

✅ 会话已重置，开始全新对话吧。

/stop

立即终止当前正在进行的 AI 回复输出。无论 allowInterrupt 配置如何，/stop 命令始终生效。与自动打断的区别：/stop 仅终止输出，不会触发新的 AI 请求。

⏹ 已终止输出。

如果当前没有正在进行的回复：

ℹ️ 当前没有正在进行的回复。

/help

动态列出所有已注册命令及描述。

📋 可用命令：
/new — 清除对话历史，开始全新会话
/stop — 终止正在进行的 AI 回复
/help — 显示可用命令列表
/health — 查看服务健康状态（版本、运行时长）
/status — 查看各账号连接状态

/health

返回与 GET /health 接口相同的数据。

🟢 服务健康状态

- 状态：ok
- 版本：1.0.0
- 运行时长：2天 3小时 15分 40秒
- 当前时间：2026/4/10 11:20:00

/status

返回与 GET /api/status 接口相同的数据，列出所有账号的连接状态。

📊 服务状态

- 版本：1.0.0

账号列表（共 2 个）：

🟢 测试机器人 (`bot-1`)
  - 状态：运行中
  - 最后连接：2026/4/10 09:00:00

🔴 备用机器人 (`bot-2`)
  - 状态：已停止
  - 错误：WSReconnectExhaustedError: max reconnect attempts reached

- 时间：2026/4/10 11:20:00