飞书AI机器人Agent架构设计与实现

1. 项目概述：飞书AI机器人Agent架构设计

这个项目构建了一个能与飞书群聊深度集成的AI机器人系统，核心能力包括：

• 通过飞书WebSocket长连接实时收发群消息
• 基于Claude或OpenAI兼容模型的智能对话能力
• 通过MCP协议调用外部工具（如数据库查询、硬件控制）
• 支持通过Markdown文件动态切换AI角色行为（Skill系统）

典型应用场景：在飞书工作群中@机器人，它可以：

1. 回答常规问题（如"项目进度如何？"）
2. 执行工具调用（如"查下昨天的订单量"）
3. 根据场景切换专业角色（如技术支持/会议记录/娱乐模式）

技术栈组成：

mermaid复制graph LR
    A[飞书客户端] --> B[Agent核心]
    B --> C[AI模型API]
    B --> D[MCP工具服务]
    E[Skill系统] --> B

2. 核心模块设计与实现

2.1 飞书消息接入层

飞书客户端(feishu/client.js)采用WebSocket长连接方案，相比HTTP轮询具有：

• 实时性：消息延迟<200ms
• 可靠性：自动重连机制
• 低开销：单连接维持，避免频繁握手

关键实现细节：

javascript复制class FeishuClient {
  constructor() {
    this.ws = new WebSocket(`wss://open.feishu.cn/conn/v1/?app_id=${CONFIG.feishu.appId}`);
    this.ws.on('message', this._handleMessage.bind(this));
  }

  // 消息处理流水线
  _handleMessage(raw) {
    const event = JSON.parse(raw);
    if (event.header.event_type === 'im.message.receive_v1') {
      this.emit('message', {
        msgId: event.event.message.message_id,
        text: event.event.message.content.text.trim()
      });
    }
  }
}

注意事项：

1. 需在飞书开放平台申请机器人权限
2. 消息卡片回复需遵循飞书卡片消息规范
3. 生产环境建议添加消息签名验证

2.2 MCP工具调用系统

MCP(Model Context Protocol)是项目的核心创新点，实现AI与外部工具的交互。系统特点：

1. 多协议支持：

   • Stdio：本地子进程通信（开发常用）
   • SSE：HTTP Server-Sent Events
   • Streamable-HTTP：新版推荐协议

2. 工具注册示例（控制智能家居）：

javascript复制// light_mcp_server.js
server.tool(
  "turn_on_light",
  "开启指定房间的灯",
  { r