Lark AgentX：用你的飞书账号做 AI Agent，逆向飞书协议 + MCP 函数调用，免申请 Bot

标签: Lark AgentX / 飞书 / MCP / AI Agent / 逆向协议 / Function Call / 开源 / Python
原文: 微信公众号「三丰述码」https://mp.weixin.qq.com/s/Y46suSsnPiL5wVXas69aJQ
GitHub: https://github.com/cv-cat/LarkAgentX

项目简介

Lark AgentX（Lark MCP） —— 用你自己的飞书账号做 AI Agent。不走官方 Bot API，逆向飞书客户端 WebSocket + Protobuf 协议实时收消息，交给本地大模型做意图理解 → Function Call → 返回结果。

解决什么痛点？

飞书官方 Bot 要创建企业自建应用、管理员审批、配 Webhook、有公网 IP……对个人玩家或快速验证想法的开发者来说，门槛偏高。

Lark AgentX 的思路：用你自己的飞书号 = AI 助手，零配置，开箱即用。

核心原理

三件事

#	模块	说明
1️⃣	逆向飞书私有协议	抓取飞书 PC 端 Cookie → 模拟用户身份 → 建立 WebSocket 长连接 → 接收 Protobuf 编码的实时消息帧（私聊 + 群聊）→ HTTP POST + Protobuf 主动发消息、查联系人
2️⃣	MCP 函数调用框架	`@register_tool` 装饰器注册 Python 函数 → LLM 自动选择匹配的 tool 并传参执行
3️⃣	消息落库 + 异步管道	SQLAlchemy ORM → MySQL 存储所有收发消息 → 全程 async/await → Docker Compose 一键部署

消息流转

用户在飞书输入: /run 北京今天天气咋样
    ↓
Agent 识别意图 → 调 get_weather("北京")
    ↓
把结果发回飞书对话框
    ↓
全程无人工路由

MCP 函数调用框架

装饰器注册

@register_tool(name="get_weather", description="获取指定城市天气")
def get_weather(city: str) -> str:
    ...

开发者只需写好 Python 函数 + docstring，LLM（支持 OpenAI 兼容接口）根据用户自然语言，自动选择最匹配的 tool 并传参执行。

内置示例函数

🌤 天气查询
😂 讲笑话
🎲 抽运势
📊 统计今日发言人数
📦 提取订单信息

适用场景

场景	说明
🏠 个人效率助手	私聊飞书让 Agent 查日历、查天气、跑本地脚本、搜笔记
🤫 工作群机器人（隐身版）	监听群消息做关键词提取、订单解析、日报统计，不打扰别人
🧪 快速原型验证	验证"大模型 + 企业内部 API + IM"的 Function Call 闭环，不用等管理员批应用
📚 MCP 学习 & 二次开发	理解 Model Context Protocol 在真实 IM 场景中落地，扩展自己的 Tool 集

对比其他方案

维度	官方 Bot	Lark AgentX
目标用户	企业生产	个人开发者、极客、快速 PoC
申请流程	创建企业自建应用 + 管理员审批	零申请，用自己的飞书号
公网 IP	需要	不需要
Webhook	需要配置	不需要
协议	官方 Bot API	逆向 WebSocket + Protobuf
部署	复杂	`docker-compose up -d`

简单来说：官方 Bot 更适合企业生产，Lark AgentX 更适合个人开发者、极客和快速 PoC。

快速开始

环境要求

Docker + Docker Compose
飞书 PC 端 Cookie
OpenAI 兼容的 LLM API Key

部署

# 1. 克隆项目
git clone https://github.com/cv-cat/LarkAgentX.git

# 2. 配置 .env
# 填入飞书 Cookie 和模型 Key

# 3. 启动
docker-compose up -d

⚠️ 注意事项

逆向私有协议存在封号理论风险，建议小号测试，勿用于生产敏感业务。

技术栈

技术	说明
Python async	异步服务，IO 非阻塞
WebSocket	飞书实时消息长连接
Protobuf	消息编解码
MCP (Model Context Protocol)	函数调用框架
SQLAlchemy ORM	消息落库（MySQL）
Docker Compose	一键部署

总结

核心价值

✅ 免申请 Bot —— 用自己飞书号直接跑，零配置
✅ 逆向协议 —— WebSocket + Protobuf 实时消息
✅ MCP 函数调用 —— @register_tool 装饰器，LLM 自动选择 tool
✅ 消息落库 —— MySQL 存储，方便回溯分析
✅ 一键部署 —— Docker Compose 启动
✅ 适合个人/极客 —— 快速 PoC，不等管理员审批