Messaging Bots.zh CN

🌐 Language: English | 中文

消息机器人

KinetAios 可以通过 WebSocket 长连接接收飞书和企业微信消息,路由到任意 Agent 引擎处理后回复 —— 还能自动发送 Agent 产出的文件/图片。

这把你的 IM 应用变成了远程 Agent 终端:发一条文本消息,得到带文件附件的 AI 回复。

支持平台

平台	SDK	连接方式
飞书 / Lark	@larksuiteoapi/node-sdk	WebSocket 长连接
企业微信	@wecom/aibot-node-sdk	WebSocket 长连接

均使用官方 SDK,内置心跳保活、断线指数退避重连、消息幂等去重。

配置

飞书

1. 进入飞书开放平台→ 创建应用
2. 开启机器人能力
3. 事件订阅中切换为长连接模式(非 HTTP 回调)
4. 订阅 im.message.receive_v1 事件
5. 复制 App ID 和 App Secret → 粘贴到 设置 → 消息 tab

企业微信

1. 进入企业微信开发者后台→ 创建智能机器人
2. 从机器人管理页复制 Bot ID 和 Secret
3. 粘贴到 设置 → 消息 tab

配置字段

字段	说明
启用	开关机器人。切换后自动重连
App ID / Bot ID	飞书 App ID 或企微 Bot ID
App Secret / Secret	对应密钥
引擎	处理消息的 Agent 引擎:direct / directV2 / claudeCode / codex
流式回复	开 → 先发"⏳ 正在思考…"占位,完成后替换为答案
默认工作目录	Agent 工具调用(shell、文件操作)的工作目录

消息路由流程

IM 用户发送消息
    ↓
SDK WebSocket 接收
    ↓
Bridge (feishu.ts / wecom.ts) 归一化为文本
    ↓
斜杠指令? ── 是 → 立即处理并回复
    ↓ 否
入 per-user 串行队列
    ↓
TaskManager.send(convId, text)
    ↓
引擎处理(ReAct 循环 / CLI 调用)
    ↓
从最后一轮提取答案
    ↓
提取产出物(工具输出中的文件/图片路径)
    ↓
回复文本 + 上传并发送附件

斜杠指令

用户可直接在 IM 聊天中管理会话 —— 无需打开桌面端。

指令	动作
/new	开启新对话(清除当前上下文)
/reset	清空当前会话的对话历史(保留会话,抹掉 turns)
/list	显示最近 5 个会话,含时间戳和轮次
/switch N	切换到 /list 中的第 N 个会话
/context	显示当前会话信息(轮次、token、费用、cwd)

无法识别的 /... 会显示帮助文本。

会话管理

按用户复用会话

同一用户的消息自动路由到同一会话,保持多轮上下文。映射 key 取决于聊天类型:

聊天类型	Key 格式	行为
飞书单聊	feishu:${open_id}	每用户独立会话
飞书群聊	feishu:group:${chat_id}	全群共享一个会话
企微单聊	wecom:${userid}	每用户独立会话
企微群聊	wecom:group:${chatid}	全群共享一个会话

持久化

feishuKey / wecomKey 存储在 SQLite 的 Conversation 记录上。应用重启时,Bridge 扫描所有会话重建内存 Map<key, convId>。Map 查找未命中时,fallback 到 SQLite 全扫描。

淘汰机制

每个用户(或群)最多保留 5 个会话。超出时自动删除最旧的会话。

并发消息处理

同一用户的消息通过 per-user promise chain(enqueue()) 串行处理。如果用户 A 快速连发 3 条消息,它们排队逐一执行。不同用户的消息并行处理。

这替代了旧的轮询方案(while + setTimeout(2000) 阻塞 120 秒)。

文件/图片自动发送(仅飞书)

当 Agent 在工具执行过程中产出文件或图片时,Bridge 自动:

1. 提取工具输出(write_file、shell、read_file、feishu_send_file)中的文件路径
2. 上传每个文件到飞书(im.image.create / im.file.create)
3. 回复图片/文件类型的富媒体消息

支持类型:PNG、JPG、GIF、WebP(图片);PDF、DOC、XLS、PPT、MP4、MP3(文件)。

Agent 也可通过 feishu_send_file 工具主动发送文件。

来源提示

当会话来源是飞书或企微时,系统提示词中注入来源提示,让 Agent 知道它通过 IM 渠道通信:

• 飞书:"你在飞书对话中回复。保持回复简洁。使用 feishu_send_file 发送文件。"
• 企微:"你在企业微信对话中回复。保持回复简洁(支持 markdown,最长约 4000 字)。"

关键源文件

文件	职责
src/main/feishu.ts	FeishuBridge:WS 连接、消息处理、文件上传
src/main/wecom.ts	WeComBridge:WS 连接、消息处理
src/main/engines.ts	sourceHintSection() — 注入 IM 上下文到系统提示词
src/main/tools.ts	feishuSendFile 工具注册
src/shared/types.ts	FeishuBotConfig、WeComBotConfig、feishuKey、wecomKey 字段
src/main/settings.ts	机器人默认配置
src/main/main.ts	IPC handler、启动自动连接、设置变更重连