飞书数据的 AI 管道：从企业 IM 到结构化知识

为什么飞书数据这么重要

一个中层管理者的日常信息流：

飞书几乎包含了管理者 80% 的工作信息源。 如果 AI Agent 不能接入飞书，它就只能当一个"事后顾问"——你告诉它发生了什么，它才能帮忙。

我的目标是让 AI 能主动获取这些数据。

架构：分层适配

三层的职责边界：

• 数据层: 飞书原始 API（不可控，随飞书版本变化）
• 适配层: 统一封装、认证、限流（变化在此处吸收）
• 消费层: AI 技能只知道"调什么方法拿什么数据"，不关心底层

核心挑战

挑战 1: 认证

企业内部飞书 App 有两种身份：

• Bot 身份: 能看到群消息、能搜索通讯录，但权限受限
• User 身份: 能看到用户自己的一切（包括私聊），但需要 OAuth 授权

我的选择: 两种都用。Bot 做批量操作（群列表、通讯录查询），User 做个人数据操作（私聊历史、我的日历）。

挑战 2: 数据量与限流

飞书 API 有严格的 Rate Limit。当你要拉一个 500 人群的 30 天消息时：

• 每次最多 50 条
• 需要分页翻完
• 还有每分钟调用次数限制

适配层需要内置：

• 自动分页
• 失败重试（指数退避）
• 增量游标（下次从上次停的地方继续）
• 请求合并（同一群的多个时间段合并为一次请求）

挑战 3: 数据结构化

飞书消息的原始格式是 JSON（富文本），包含各种类型：

• 纯文本、@提及、链接、图片、文件
• 合并转发、引用回复、消息卡片
• 表情反应、投票、日程分享

适配层需要把这些统一转为 Markdown——AI 能读懂的格式：

[2026-04-15 09:23] @张三:
决定下周一开始灰度，@李四 负责准备环境。
> 引用: [王五 04-14] 环境准备需要 2 天

消息采集实践

chat-collector 的实际工作流：

增量采集 是关键——不是每次都拉全量。游标记录了"上次采到哪里"，下次从那里继续。幂等性保证重复跑不会重复存。

妙记采集

飞书妙记是最有价值的数据源之一——它包含会议的完整逐字稿和 AI 纪要。

# 采集今天的会议妙记
meeting-collector --date today
# 1. 查日历拿今天的会议列表
# 2. 对每个结束的会议，查是否有妙记
# 3. 下载逐字稿 + 智能纪要
# 4. 存到 meetings/{date}-{topic}/

妙记数据的特点：

• 逐字稿很长（1 小时会议 = 5000-10000 字）
• 但智能纪要高度结构化（议题/决策/待办）
• 两者互补：纪要给结论，逐字稿给上下文

安全与隐私

处理企业 IM 数据，安全是首要考虑：

经验总结

做了 3 个月企业 IM 数据接入的教训：

1. 限流是最大的工程挑战 — 不是"能不能调"的问题，是"多快能调完"的问题。500 条消息×分页×限流，可能需要几分钟
2. 增量必须从第一天就设计 — 全量拉取在数据量大后不可行
3. 格式转换需要持续迭代 — 飞书消息类型很多，每种转 Markdown 的逻辑不同
4. Bot+User 双身份是必须的 — 单一身份覆盖不了所有场景
5. 认证刷新要自动化 — User Token 会过期，必须自动续期

核心洞察：企业 IM 是管理者最富信息密度的数据源，但它的价值被"非结构化"锁住了。一旦你能把散落的消息、日历、文档、转录变成 AI 可消费的结构化输入——你的 AI Agent 就从"事后顾问"升级为"实时副驾驶"。