飞书会话浏览与管理

通过 feishu-cli 浏览飞书单聊/群聊消息历史、搜索会话、管理群聊信息和成员。

前置条件

本技能的核心命令必须使用 User Token，使用前需先登录。chat create、chat link、msg read-users 使用 App Token，属于 feishu-cli-toolkit 技能。

CODEBLOCK0

未登录时命令会直接报错并提示登录方式。登录后 token 自动加载，无需手动传参。

身份说明

身份	使用场景
User Token（必须）	本技能所有读取/管理命令：chat get/update/delete、member list/add/remove、msg get/history/list/pins/reaction/search-chats、search messages
App Token

仅 chat create、chat link、msg read-users（这三个命令不属于本技能核心流程） |

User Token 能力：

- 查看 bot 不在的群聊消息
查看私聊（p2p）消息
搜索用户有权限的所有会话

自动降级机制

当使用 User Token 调用 msg history / msg list 时，如果 bot 不在目标群中，API 会返回空结果。CLI 会自动检测这种情况并降级为 search + get 方式获取消息：

CODEBLOCK1

这个过程对用户透明，无需手动干预。

场景一：查看群聊历史消息

这是最常见的场景——用户想看某个群最近在聊什么。

步骤 1：找到群聊

如果用户给了群名而不是 chat_id，先搜索：

CODEBLOCK2

输出中的 chat_id（形如 oc_xxx）就是后续命令需要的标识。

步骤 2：获取消息

CODEBLOCK3

步骤 2.5：判断群类型并获取线程回复

飞书群聊分为普通群和话题群两种，消息结构和获取策略完全不同。

如何判断群类型

观察 msg history 返回的消息字段：

群类型	特征	示例
话题群	每条消息都有 `thread_id`（形如 `omt_xxx`），主消息流仅包含每个话题的首条消息	泰国华商群
普通群

独立消息无 thread_id，仅被回复的消息和回复消息才有 thread_id | Claude Code闲聊群 |

消息中的线程相关字段

字段	说明	出现条件
INLINECODE15	线程/话题 ID（形如 `omt_xxx`）	话题群所有消息 / 普通群中参与线程的消息
INLINECODE17

普通群：一次获取全部消息

普通群的 msg history 返回所有消息（独立消息 + 线程回复），平铺在同一列表中。通过 root_id/parent_id 可重建回复关系，不需要额外获取线程。

CODEBLOCK4

话题群：需要逐个话题获取回复（重要）

话题群的 msg history --container-id-type chat 仅返回每个话题的首条消息，线程回复不在主消息流中。必须按 thread_id 逐个获取：

CODEBLOCK5

完整的话题群获取流程：

CODEBLOCK6

性能提示：话题群中活跃话题可能有 10-20 个，建议并发获取多个话题的回复。飞书 API 对 msg history 无严格 QPS 限制（不同于搜索 API），可以安全并发。

步骤 3：解析消息内容

API 返回的消息 body.content 是 JSON 字符串，常见格式：

msg_type	content 格式	说明
text	INLINECODE24	纯文本，`@_user_1` 是 at 占位符
post

富文本 JSON | 包含标题和段落结构 |
| image | {"image_key":"xxx"} | 图片 |
| interactive | 卡片 JSON | 交互式卡片 |
| sharecalendarevent | {"summary":"会议名","start_time":"ms","end_time":"ms",...} | 日历事件分享 |
| sticker | {"sticker_key":"xxx"} | 表情包 |
| file | {"file_key":"xxx","file_name":"..."} | 文件 |

用 Python 提取文本内容的常用方式：

CODEBLOCK7

完整示例：获取并总结群聊最近 N 条消息

CODEBLOCK8

注意：Search API 的 page_size 与 List API 不同，降级模式下每页实际返回数量可能少于请求值。建议循环翻页直到 has_more=false 或达到目标数量。

场景二：查看和某人的私聊记录

飞书 Open API 不支持直接按用户查询 p2p 聊天记录。需要通过搜索 API 间接实现。

方法：搜索 + 筛选

CODEBLOCK9

查找用户 ID

如果用户只给了邮箱或手机号，可以查找对应的 open_id：

CODEBLOCK10

注意：user search 仅支持 --email 和 --mobile 精确查找，不支持按姓名模糊搜索。

限制说明

- 搜索 API 的 query 参数不能为空，至少需要一个空格 INLINECODE35
p2p 聊天无法通过 msg search-chats 搜索（该 API 只搜索群聊）
搜索结果返回的是消息 ID 列表，需要逐条 msg get 获取完整内容
msg get 对私聊消息可能返回 230001 错误（API 限制：部分私聊消息不支持通过 Get API 获取详情），此时只能依赖搜索结果中的摘要信息

场景三：搜索群聊

搜索群聊列表

CODEBLOCK11

在群内搜索消息

CODEBLOCK12

更多搜索功能（按时间范围、消息类型、发送者、跨模块搜索文档/应用等）请使用 feishu-cli-search 技能，提供完整的筛选参数和 Token 排错指南。

场景四：群聊信息管理

查看群信息

CODEBLOCK13

默认输出 JSON 格式，包含群名、描述、群主、群类型、成员数量等。

查看群成员

CODEBLOCK14

Scope 要求：使用 User Token 时需要 im:chat:readonly 或 im:chat.members:read scope。若报 99991679 错误，需通过 auth login --scopes "... im:chat:readonly" 重新授权。

修改群信息

CODEBLOCK15

群成员管理

CODEBLOCK16

创建群聊

CODEBLOCK17

注意：chat create 和 chat link（获取分享链接）仅支持 App Token（租户身份），不支持 User Token。

解散群聊

CODEBLOCK18

场景五：消息详情与互动

获取单条消息详情

CODEBLOCK19

查看消息已读情况

CODEBLOCK20

限制：仅支持查询 bot 自己发送的、7 天内的消息，且 bot 必须在会话内。此命令仅使用 App Token。

查看群内置顶消息

CODEBLOCK21

置顶/取消置顶消息

CODEBLOCK22

Reaction 表情回应

CODEBLOCK23

常用 emoji-type：THUMBSUP（点赞）、SMILE（微笑）、LAUGH（大笑）、HEART（爱心）、JIAYI（加一）、OK、INLINECODE50

删除消息

仅能删除机器人自己发送的消息，不可恢复。

CODEBLOCK24

常见操作速查表

用户意图	命令	Token
看某群最近消息	INLINECODE51	User
看话题群的线程回复

标记 User 的命令必须先 auth login，未登录会报错。标记 App 的命令使用应用身份，无需登录。

处理大量消息的最佳实践

当需要获取并分析大量消息（如 100+ 条）时：

1. 保存到文件：每页结果用 -o json 输出，重定向到文件
循环翻页：检查 HasMore 和 PageToken，循环获取直到满足条件
用 Python 解析：JSON 消息结构需要解析 body.content 提取文本
注意限频：搜索 API 有频率限制，大量请求间加 1s 延迟；msg history 限频较宽松，可安全并发
时间戳：create_time 是毫秒级时间戳，需除以 1000 转为秒
话题群并发获取线程：话题群需要对每个 thread_id 单独调用 msg history --container-id-type thread，建议并行调用多个话题以提高效率（实测 10-20 个并发无问题）
已撤回消息：deleted: true 的消息内容为 "This message was recalled"，汇总时应跳过

CODEBLOCK25

权限要求

scope	说明	对应命令
INLINECODE79	消息读取	msg get/history/list
INLINECODE80

与其他技能的分工

场景	使用技能
浏览聊天记录、搜索群聊、群信息/成员管理、Reaction/Pin/删除/获取消息	feishu-cli-chat（本技能）
发送消息、回复、转发/合并转发

飞书会话浏览与管理

通过 feishu-cli 浏览飞书单聊/群聊消息历史、搜索会话、管理群聊信息和成员。

前置条件

本技能的核心命令必须使用 User Token，使用前需先登录。chat create、chat link、msg read-users 使用 App Token，属于 feishu-cli-toolkit 技能。

bash
feishu-cli auth login

未登录时命令会直接报错并提示登录方式。登录后 token 自动加载，无需手动传参。

身份说明

身份	使用场景
User Token（必须）	本技能所有读取/管理命令：chat get/update/delete、member list/add/remove、msg get/history/list/pins/reaction/search-chats、search messages
App Token

仅 chat create、chat link、msg read-users（这三个命令不属于本技能核心流程） |

User Token 能力：

- 查看 bot 不在的群聊消息
查看私聊（p2p）消息
搜索用户有权限的所有会话

自动降级机制

当使用 User Token 调用 msg history / msg list 时，如果 bot 不在目标群中，API 会返回空结果。CLI 会自动检测这种情况并降级为 search + get 方式获取消息：

list API 返回空 + has_more=true → 自动切换到搜索模式 → 逐条获取消息内容

这个过程对用户透明，无需手动干预。

场景一：查看群聊历史消息

这是最常见的场景——用户想看某个群最近在聊什么。

步骤 1：找到群聊

如果用户给了群名而不是 chat_id，先搜索：

bash
feishu-cli msg search-chats --query 群名关键词 -o json

输出中的 chatid（形如 ocxxx）就是后续命令需要的标识。

步骤 2：获取消息

bash

获取最近 50 条消息（API 单次上限 50）

feishu-cli msg history \
--container-id oc_xxx \
--container-id-type chat \
--page-size 50 \
--sort-type ByCreateTimeDesc \
-o json

按时间范围获取（--start-time 为毫秒级时间戳，仅返回该时间之后的消息）

feishu-cli msg history \ --container-id oc_xxx \ --container-id-type chat \ --page-size 50 \ --start-time 1773778860000 \ --sort-type ByCreateTimeDesc \ -o json

获取更早的消息（使用上一次返回的 page_token 翻页）

feishu-cli msg history \ --container-id oc_xxx \ --container-id-type chat \ --page-size 50 \ --page-token 上一页返回的token \ -o json

步骤 2.5：判断群类型并获取线程回复

飞书群聊分为普通群和话题群两种，消息结构和获取策略完全不同。

如何判断群类型

观察 msg history 返回的消息字段：

群类型	特征	示例
话题群	每条消息都有 threadid（形如 omtxxx），主消息流仅包含每个话题的首条消息	泰国华商群
普通群

独立消息无 threadid，仅被回复的消息和回复消息才有 threadid | Claude Code闲聊群 |

消息中的线程相关字段

字段	说明	出现条件
threadid	线程/话题 ID（形如 omtxxx）	话题群所有消息 / 普通群中参与线程的消息
root_id

普通群：一次获取全部消息

普通群的 msg history 返回所有消息（独立消息 + 线程回复），平铺在同一列表中。通过 rootid/parentid 可重建回复关系，不需要额外获取线程。

独立消息: 无 threadid、无 rootid
被回复的消息: 有 thread_id（被回复后自动产生）
线程回复: 有 threadid + rootid + parent_id

话题群：需要逐个话题获取回复（重要）

话题群的 msg history --container-id-type chat 仅返回每个话题的首条消息，线程回复不在主消息流中。必须按 thread_id 逐个获取：

bash

获取单个话题的所有回复（按时间正序，方便阅读）

feishu-cli msg history \
--container-id omt_xxx \
--container-id-type thread \
--page-size 50 \
--sort-type ByCreateTimeAsc \
-o json

完整的话题群获取流程：

bash

1. 获取主消息流（每个话题的首条消息）

feishu-cli msg history \
--container-id oc_xxx \
--container-id-type chat \
--page-size 50 \
--sort-type ByCreateTimeDesc \
-o json

2. 从返回结果中提取所有 thread_id

3. 对每个 thread_id 获取回复（可并发执行，提高效率）

feishu-cli msg history --container-id omt_xxx --container-id-type thread --page-size 50 --sort-type ByCreateTimeAsc -o json feishu-cli msg history --container-id omt_yyy --container-id-type thread --page-size 50 --sort-type ByCreateTimeAsc -o json

... 多个话题可并行获取

性能提示：话题群中活跃话题可能有 10-20 个，建议并发获取多个话题的回复。飞书 API 对 msg history 无严格 QPS 限制（不同于搜索 API），可以安全并发。

步骤 3：解析消息内容

API 返回的消息 body.content 是 JSON 字符串，常见格式：

msgtype	content 格式	说明
text	{text:消息内容}	纯文本，@user_1 是 at 占位符
post

富文本 JSON | 包含标题和段落结构 |
| image | {image_key:xxx} | 图片 |
| interactive | 卡片 JSON | 交互式卡片 |
| sharecalendarevent | {summary:会议名,starttime:ms,endtime:ms,...} | 日历事件分享 |
| sticker | {sticker_key:xxx} | 表情包 |
| file | {filekey:xxx,filename:...} | 文件 |

用 Python 提取文本内容的常用方式：

python
import json
content = json.loads(msg[body][content])
text = content.get(text, )

完整示例：获取并总结群聊最近 N 条消息

bash

1. 搜索群聊

feishu-cli msg search-chats --query Go讨论区 -o json

2. 获取消息（循环翻页直到够数）

feishu-cli msg history \ --container-id oc_xxx \ --container-id-type chat \ --page-size 50 \ --sort-type ByCreateTimeDesc \ -o json > /tmp/chat_page1.json

3. 提取 page_token 获取下一页

... 循环直到获取足够消息

注意：Search API 的 pagesize 与 List API 不同，降级模式下每页实际返回数量可能少于请求值。建议循环翻页直到 hasmore=false 或达到目标数量。

场景二：查看和某人的私聊记录

飞书 Open API 不支持直接按用户查询 p2p 聊天记录。需要通过搜索 API 间接实现。

方法：搜索 + 筛选

bash

搜索私聊消息

feishu-cli search messages 关键词 \
--chat-type p2p_chat \
-o json

如果知道对方的 open_id，可以按发送者筛选

feishu-cli search messages 关键词 \ --chat-type p2p_chat \ --from-ids ou_xxx \ -o json

获取单条消息详情

feishu-cli msg get om_xxx -o json

查找用户 ID

如果用户只给了邮箱或手机号，可以查找对应的 open_id：

bash

通过邮箱查找用户

feishu-cli user search --email user@example.com -o json

feishu-cli-chat飞书命令行聊天

feishu-cli-chat

飞书会话浏览与管理

前置条件

身份说明

自动降级机制

场景一：查看群聊历史消息

步骤 1：找到群聊

步骤 2：获取消息

步骤 2.5：判断群类型并获取线程回复

如何判断群类型

消息中的线程相关字段

普通群：一次获取全部消息

话题群：需要逐个话题获取回复（重要）

步骤 3：解析消息内容

完整示例：获取并总结群聊最近 N 条消息

场景二：查看和某人的私聊记录

方法：搜索 + 筛选

查找用户 ID

限制说明

场景三：搜索群聊

搜索群聊列表

在群内搜索消息

场景四：群聊信息管理

查看群信息

查看群成员

修改群信息

群成员管理

创建群聊

解散群聊

场景五：消息详情与互动

获取单条消息详情

查看消息已读情况

查看群内置顶消息

置顶/取消置顶消息

Reaction 表情回应

删除消息

常见操作速查表

处理大量消息的最佳实践

权限要求

与其他技能的分工

飞书会话浏览与管理

前置条件

身份说明

自动降级机制

场景一：查看群聊历史消息

步骤 1：找到群聊

步骤 2：获取消息

获取最近 50 条消息（API 单次上限 50）

按时间范围获取（--start-time 为毫秒级时间戳，仅返回该时间之后的消息）

获取更早的消息（使用上一次返回的 page_token 翻页）

步骤 2.5：判断群类型并获取线程回复

如何判断群类型

消息中的线程相关字段

普通群：一次获取全部消息

话题群：需要逐个话题获取回复（重要）

获取单个话题的所有回复（按时间正序，方便阅读）

1. 获取主消息流（每个话题的首条消息）

2. 从返回结果中提取所有 thread_id

3. 对每个 thread_id 获取回复（可并发执行，提高效率）

... 多个话题可并行获取

步骤 3：解析消息内容

完整示例：获取并总结群聊最近 N 条消息

1. 搜索群聊

2. 获取消息（循环翻页直到够数）

3. 提取 page_token 获取下一页

... 循环直到获取足够消息

场景二：查看和某人的私聊记录

方法：搜索 + 筛选

搜索私聊消息

如果知道对方的 open_id，可以按发送者筛选

获取单条消息详情

查找用户 ID

通过邮箱查找用户

通过手机号查找用户

标签

通过对话安装

方式一：安装 SkillHub 和技能

方式二：设置 SkillHub 为优先技能安装源

通过命令行安装