aibot-connect

企业微信 AI 机器人消息调度框架 —— 连接企业微信智能机器人与 AI Agent，处理消息接收、分发与流式回复。

前置条件

Node.js >= 20.6.0
企业微信管理后台权限（能创建智能机器人）

一、在企业微信创建智能机器人

1.1 创建机器人

参考企业微信创建智能机器人的两种方式。

1.2 添加到群聊（可选）

在机器人详情页点击「添加到群聊」，可将机器人加入内部工作群，群成员 @机器人名消息内容 即可对话。

二、安装

npm install aibot-connect

如需使用 Claude Code SDK Agent（可选）：

npm install @anthropic-ai/claude-agent-sdk

三、快速开始（RouterAgent 一行接管）

这是最常用的方式 —— RouterAgent 内置路由、命令、会话管理和流式回复，一行 router.handle(ctx) 即可接入。

3.1 配置环境变量

# .env
WECOM_BOT_ID=上一步获取的 BotId
WECOM_SECRET=上一步获取的 Secret

3.2 编写入口文件

import { createApp, ClaudeCodeCliAgent, RouterAgent } from 'aibot-connect'

// 1. 创建 Agent（选择一种能力源）
const router = new RouterAgent({
  agents: {
    claude: new ClaudeCodeCliAgent({
      cwd: '/your/project',       // Claude Code 工作目录
      model: 'claude-sonnet-4-6', // 模型
    }),
  },
  defaultAgent: 'claude',
  displayName: 'Claude 助手', // 欢迎语中展示的名称
})

// 2. 一行接管消息处理
const app = createApp()
app.onMessage(async (ctx) => {
  await router.handle(ctx)
})

app.onEvent(async (ctx) => {
  await router.handleEvent(ctx)
})

// 3. 启动
await app.start()
process.on('SIGINT', () => app.stop().then(() => process.exit(0)))

3.3 启动

npx tsx index.ts

启动后，在企业微信中找到你的机器人，发送消息即可获得 AI 回复。同时支持以下内置命令：

命令	功能
`/reset`	重置当前会话，开始新对话
`/stop`	中断正在执行的任务
`/status`	查看会话状态和用量统计
`/help`	显示帮助信息

四、示例项目

项目仓库中提供了两个可直接运行的示例，克隆仓库后即可使用：

git clone https://github.com/xesam/aibot-connect.git
cd aibot-connect
cp .env.example .env  # 编辑 .env，填入你的 BotId 和 Secret
pnpm install

示例一：框架基础用法

演示 createApp() 的完整特性：命令注册、流式回复、中间件审计日志、运行时事件监控。

pnpm example:basic

→ 源码：examples/basic.ts

示例二：RouterAgent 多 Agent 路由

演示 Claude Code + Codex 双 Agent，通过自定义路由规则 (@codex 前缀 / 关键词匹配) 自动分配任务。

pnpm example:router

→ 源码：examples/router-bridge.ts

五、`RouterAgent` 详解

RouterAgent 是推荐的高层封装：

router.handle(ctx) 处理消息：

内置命令 /reset /stop /status /help
多 Agent 路由
会话持久化（默认文件存储，重启恢复）
流式回复与中断管理

router.handleEvent(ctx) 处理事件：

入群欢迎语（基于 displayName 和已注册的 Agent 列表）

多 Agent 路由

可以同时配置多个 Agent，按消息内容自动分发：

const router = new RouterAgent({
  agents: {
    claude: new ClaudeCodeCliAgent({ cwd: '/project', model: 'claude-opus-4-6' }),
    codex:  new CodexCliAgent({ cwd: '/project' }),
  },
  defaultAgent: 'claude',
  displayName: 'AI 助手',

  // 自定义路由：根据消息内容选择 Agent
  route: async (ctx) => {
    if (ctx.text.includes('审查') || ctx.text.includes('code review')) {
      return 'codex'
    }
    return 'claude'
  },
})

可用的 Agent

类	调用方式	需要本地环境
`ClaudeCodeCliAgent`	`claude` CLI 子进程	安装 Claude Code
`ClaudeCodeSdkAgent`	`@anthropic-ai/claude-agent-sdk`	无（纯 SDK 调用）
`CodexCliAgent`	`codex` CLI 子进程	安装 Codex CLI

Agent 配置

// Claude CLI
new ClaudeCodeCliAgent({
  cwd: string              // 工作目录
  model?: string           // 模型，如 'claude-sonnet-4-6'
  allowedTools?: string[]  // 工具白名单
  maxTurns?: number        // 最大对话轮数
})

// Claude SDK
new ClaudeCodeSdkAgent({
  cwd: string
  model?: string
  allowedTools?: string[]
  maxTurns?: number
  maxBudgetUsd?: number    // 单次会话费用上限
})

// Codex CLI
new CodexCliAgent({
  cwd: string
  model?: string
})

会话持久化

RouterAgent 默认使用 FileSessionStore（文件存储到 data/sessions.json，30 分钟过期）。可替换：

import { MemorySessionStore, FileSessionStore } from 'aibot-connect'

// 纯内存（测试用，重启丢失）
new RouterAgent({ agents, defaultAgent: 'claude', sessionStore: new MemorySessionStore() })

// 自定义路径与过期时间
new RouterAgent({
  agents,
  defaultAgent: 'claude',
  sessionStore: new FileSessionStore({
    filePath: '/custom/sessions.json',
    sessionTimeoutMin: 60,
  }),
})

六、`createApp()` 框架用法

如果想更灵活地控制消息处理，可以用 createApp() 直接编写 handler。

最小示例

import { createApp } from 'aibot-connect'

const app = createApp()

// 注册命令（优先于 onMessage）
app.onCommand('ping', async (ctx) => {
  await ctx.reply('pong')
})

// 处理事件（如进入会话）
app.onEvent(async (ctx) => {
  await ctx.reply('你好，欢迎进入会话。')
})

// 处理消息
app.onMessage(async (ctx) => {
  await ctx.reply(`你说的是：${ctx.text}`)
})

await app.start()
process.on('SIGINT', () => app.stop().then(() => process.exit(0)))

Context 关键属性

// ctx.kind —— 消息类型
'message'  // 普通消息
'command'  // 命令消息（/xxx），同时 ctx.command 有值
'event'    // 事件（如进入会话）

// ctx 常用字段
ctx.text             // 消息文本
ctx.msgType          // 'text' | 'image' | 'file' | 'voice'
ctx.chatId           // 会话 ID
ctx.userId           // 用户 ID
ctx.conversationKey  // 会话隔离键（框架内部生成）
ctx.state            // 当前会话共享状态（{ [key]: value }）
ctx.command?.name    // 命令名（仅 command 时）
ctx.command?.args    // 命令参数（仅 command 时）
ctx.channelName      // 消息来源渠道名称（如 'wecom'），由 ChannelAdapter 注入

两种回复方式

reply(text) —— 一次性回复：

await ctx.reply('纯文本回复')

replyStream() —— 流式回复：

const rs = ctx.replyStream()
rs.append('第一部分...')
rs.append('第二部分...')
await rs.end() // 或 await rs.error('错误信息')

框架自动处理 19000 字节分片和最终帧发送。

七、高级自定义

调度模式

控制同一会话的并发行为：

const app = createApp({ dispatchMode: 'serial' })   // 默认：同会话串行
const app = createApp({ dispatchMode: 'parallel' }) // 不加锁，无限制

串行模式下可通过 onBusy 处理并发冲突：

const app = createApp({
  dispatchMode: 'serial',
  onBusy: async (ctx) => {
    await ctx.reply('请等待上一条消息处理完毕')
  },
})

中间件

洋葱模型中间件，覆盖 message/command/event 所有路径：

app.use(async (ctx, next) => {
  console.log(`[${ctx.traceId}] 开始处理`)
  await next()
  console.log(`[${ctx.traceId}] 处理完成`)
})

超时与错误处理

const app = createApp({
  handlerTimeoutMs: 120_000, // 2 分钟超时
  onTimeout: async (ctx) => {
    await ctx.reply('处理超时，请稍后重试')
  },
  onError: async (ctx, error) => {
    console.error('Handler 错误:', error.message)
  },
})

自定义会话键

默认会话键为 dm:{userId}（私聊）或 group:{chatId}:user:{userId}（群聊）。可自定义：

const app = createApp({
  conversationKeyResolver: (ctx) => {
    // 群聊中所有用户共享一个会话
    if (ctx.chatId && ctx.chatId !== ctx.userId) return `shared:${ctx.chatId}`
    return `dm:${ctx.userId}`
  },
})

可观测事件

通过 onRuntimeEvent 监听框架运行时事件，可用于日志、监控、告警：

const app = createApp({
  onRuntimeEvent: (event) => {
    // event.event 可取：
    // 'message.received' | 'event.received' | 'handler.started'
    // | 'handler.completed' | 'handler.failed' | 'handler.timed_out'
    // | 'busy.rejected' | 'reply.sent'
    // | 'stream.started' | 'stream.updated' | 'stream.ended' | 'stream.failed'
    console.log('[Event]', event.event, event.durationMs)
  },
})

CliAgent 底层用法

如果不使用 RouterAgent，可以直接调用 Agent 的流式接口，自行管理会话映射和回复编排：

import { createApp, ClaudeCodeCliAgent } from 'aibot-connect'

const agent = new ClaudeCodeCliAgent({ cwd: '/project' })
const sessions = new Map() // 自行管理 chatId → sessionId

const app = createApp()
app.onMessage(async (ctx) => {
  const resume = sessions.get(ctx.chatId)
  const stream = agent.query(ctx.text, { resume })
  const rs = ctx.replyStream()
  let started = false

  for await (const msg of stream) {
    switch (msg.type) {
      case 'session':
        sessions.set(ctx.chatId, msg.sessionId)
        break
      case 'text':
        rs.append(msg.text); started = true
        break
      case 'done':
        started ? await rs.end() : await ctx.reply('（无输出）')
        break
      case 'error':
        started ? await rs.error(msg.message) : await ctx.reply(`出错了：${msg.message}`)
        break
    }
  }
})

八、API 参考

`createApp(options?)`

选项	类型	默认值	说明
`botId`	`string`	`env.WECOM_BOT_ID`	企业微信机器人 BotId
`secret`	`string`	`env.WECOM_SECRET`	企业微信机器人 Secret
`dispatchMode`	`'serial' \| 'parallel' \| 'custom'`	`'serial'`	会话并发控制策略
`onBusy`	`'drop' \| ((ctx) => Promise<void>)`	`undefined`	串行模式下会话忙碌时的处理
`handlerTimeoutMs`	`number`	`undefined`	handler 超时时间（毫秒）
`onTimeout`	`(ctx) => Promise<void>`	`undefined`	超时回调
`onError`	`(ctx, error) => Promise<void>`	`undefined`	错误回调
`onRuntimeEvent`	`(event) => void`	`undefined`	运行时事件监听
`conversationKeyResolver`	`(ctx) => string`	内置规则	自定义会话键
`logLevel`	`'debug' \| 'info' \| 'warn' \| 'error' \| 'silent'`	`'info'`	日志级别
`singleInstance`	`boolean`	`true`	是否启用 PID 文件锁防止多实例
`adapter`	`ChannelAdapter`	WecomChannelAdapter (default)	自定义渠道适配器；提供后 `botId`/`secret` 不再必填

`app.onMessage(handler)`

注册消息处理器，handler 接收 MessageContext（可使用 text / msgType / state / reply / replyStream）。已注册的命令（onCommand）会优先匹配，不会进入此处理器。

`app.onEvent(handler)`

注册事件处理器，接收 EventContext（仅 reply()，无 replyStream()）。当前唯一事件是 enter_chat（入群欢迎）。

`app.onCommand(name, handler)`

注册命令处理器，匹配 /name（大小写不敏感），优先于 onMessage。handler 接收 MessageContext。

`app.use(middleware)`

注册中间件，覆盖所有 message/command/event 路径。

`app.start()` / `app.stop()`

启动/停止服务。start() 获取 PID 锁 → 建立 WebSocket 连接 → 等待 ready。

九、架构边界

IM 渠道 ←→ ChannelAdapter ←→ aibot-connect ←→ onMessage / onCommand / onEvent / middleware
         （默认: WecomChannelAdapter）   │   └─ 流式回复（自动分片 + 终态保护）
                                        │   └─ 会话级并发控制
                                        │   └─ 可观测运行时事件
                                        │
                                        └─ Agent 层（业务自由组合）
                                             ├─ ClaudeCodeCliAgent（CLI 子进程）
                                             ├─ ClaudeCodeSdkAgent（SDK 调用）
                                             ├─ CodexCliAgent（CLI 子进程）
                                             └─ RouterAgent（路由 + 会话 + 回复）

框架负责：接收、分发、回复、并发控制与运行时保障
Agent 负责：AI 模型调用与工具执行
RouterAgent 负责：路由策略、会话管理与流式转发
你负责：选择 Agent、配置路由规则、编写业务逻辑

开发

pnpm test      # 运行测试
pnpm build     # 编译构建

致谢

本项目源于 wecom-claude-bridge，感谢原作者的工作。aibot-connect 在其基础之上进行了以下核心重构：

架构：从单体 Bridge 类重构为 createApp() 工厂 + 中间件管道 + Agent 接口体系
Agent 体系：从仅支持 Claude SDK 扩展为 Claude CLI / Claude SDK / Codex CLI 三种 Agent，通过 RouterAgent 统一路由
会话管理：从 JSON 文件直接读写抽象为 SessionStore 接口（支持文件 / 内存 / 自定义实现）
可观测性：新增 RuntimeEvents 全生命周期事件体系
质量保障：179+ 个测试用例覆盖全部模块，含并发 / 原子写 / 状态机回归

许可证

ISC

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
docs		docs
examples		examples
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

aibot-connect

前置条件

一、在企业微信创建智能机器人

1.1 创建机器人

1.2 添加到群聊（可选）

二、安装

三、快速开始（RouterAgent 一行接管）

3.1 配置环境变量

3.2 编写入口文件

3.3 启动

四、示例项目

示例一：框架基础用法

示例二：RouterAgent 多 Agent 路由

五、RouterAgent 详解

多 Agent 路由

可用的 Agent

Agent 配置

会话持久化

六、createApp() 框架用法

最小示例

Context 关键属性

两种回复方式

七、高级自定义

调度模式

中间件

超时与错误处理

自定义会话键

可观测事件

CliAgent 底层用法

八、API 参考

createApp(options?)

app.onMessage(handler)

app.onEvent(handler)

app.onCommand(name, handler)

app.use(middleware)

app.start() / app.stop()

九、架构边界

开发

致谢

许可证

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

五、`RouterAgent` 详解

六、`createApp()` 框架用法

`createApp(options?)`

`app.onMessage(handler)`

`app.onEvent(handler)`

`app.onCommand(name, handler)`

`app.use(middleware)`

`app.start()` / `app.stop()`

Packages