Feishu Im Read

核心约束

1. 时间范围：确保消息覆盖完整

当用户没有明确指定时间范围时，根据用户意图推断合适的 relative_time，确保返回的消息能完整覆盖用户关心的内容。用户明确指定时间时直接使用用户的值。

2. 分页：根据需要翻页获取更多结果

• page_size 范围 1-50，默认 50
• 返回结果中 has_more=true 时，可使用 page_token 继续获取下一页
• 根据用户需求判断是否需要翻页：需要完整结果时继续翻页，浏览概览时第一页通常够用

3. 话题回复：主动展开话题获取上下文

获取历史消息时，返回的消息中如果包含 thread_id 字段，推荐主动获取话题的最新 10 条回复（page_size: 10, sort_rule: "create_time_desc"）以提供更完整的上下文。

注意：话题消息不支持时间过滤（飞书 API 限制），只能通过分页获取。

4. 跨会话消息搜索

feishu_im_user_search_messages 支持跨所有会话搜索消息：

搜索结果每条消息额外包含 chat_id、chat_type（p2p/group）、chat_name。单聊消息还有 chat_partner（对方 open_id 和名字）。

5. 图片/文件/媒体资源的提取

消息内容中可能出现以下资源标记，用 feishu_im_user_fetch_resource 下载：

从消息的 message_id 字段和内容中的 file_key 组合即可调用 fetch_resource。

注意：文件大小限制 100MB，不支持下载表情包、卡片中的资源。

6. 时间过滤

feishu_im_user_get_messages 和 feishu_im_user_search_messages 支持时间过滤，话题消息不支持。

• relative_time 和 start_time/end_time 互斥，不能同时使用
• 可用的 relative_time 值：today、yesterday、day_before_yesterday、this_week、last_week、this_month、last_month、last_{N}_{unit}（unit: minutes/hours/days）

7. open_id 与 chat_id 的选择

两者必须二选一，优先使用 chat_id。

使用场景示例

场景 1: 获取群聊消息并展开话题

步骤 1：获取群聊消息

{ "chat_id": "oc_xxx" }

步骤 2：返回的消息中发现 thread_id，展开话题最新回复：

{ "thread_id": "omt_xxx", "page_size": 10, "sort_rule": "create_time_desc" }

场景 2: 跨会话搜索消息

{ "query": "项目进度", "chat_id": "oc_xxx" }

场景 3: 分页获取更多消息

第一次调用返回 has_more: true 和 page_token: "xxx"，继续获取：

{ "chat_id": "oc_xxx", "page_token": "xxx" }

场景 4: 下载消息中的资源

{ "message_id": "om_xxx", "file_key": "img_v3_xxx", "type": "image" }

常见错误与排查