feishu-cli-chat

用途

本技能处理飞书会话的"读聊天记录 / 管群 / 消息互动"。发送新消息走 feishu-cli-msg；构造卡片走 feishu-cli-card。

主要能力

查看聊天记录

看一段时间窗内的群消息（含话题回复、名字反解、卡片解析）：使用 scripts/fetch_chat_history.py 一条命令搞定。
看一页群聊最新消息（v1.27.1+ 默认自动展开所有话题）：msg history 单次调用。
看私聊记录：msg history --user-email 或 --user-id。
看单条消息 / 合并转发：msg get / msg mget。
看一个话题的全部回复：msg thread-messages <thread_id>。
按关键词搜消息：search messages（属于 feishu-cli-search）。

搜索与定位

搜群：feishu-cli msg search-chats --query "项目群" -o json
搜消息：feishu-cli search messages "关键词" --chat-type p2p_chat -o json

消息互动

Reaction 表情回应：msg reaction add/remove/list
Pin 置顶/取消置顶：msg pin/unpin/pins
删除消息：msg delete（Bot 自撤回或管理员撤回）

群聊管理

获取/更新/解散群：chat get/update/delete
群成员管理：chat member list/add/remove
创建群：chat create

使用方式

认证

按命令类型区分：

读类（msg history/list/get/mget/thread-messages/resource-download）：登录后自动从 ~/.feishu-cli/token.json 加载 User Token，未登录回落 App Token（要求 Bot 在群里）。外部群 Bot 通常不在群里，读外部群必须先登录。
必需 User Token（reaction add/remove/list、pin/unpin/pins、search-chats、chat get/update/delete、chat member list/add/remove）：未登录直接报错。
写类 · 默认 Bot 身份（chat create、chat link）：默认 App Token，无需登录；显式 --user-access-token 时切到 User。
msg delete：默认 App Token，用于 Bot 撤回自己 24 小时内发送的消息；传 --user-access-token 或环境变量时可走管理员撤回场景。

端到端拉群消息

最常见的需求——"把群 X 最近 24 小时的全部消息拉出来"——封装成脚本：

# 默认最近 24 小时
python3 skills/feishu-cli-chat/scripts/fetch_chat_history.py oc_xxxxxxxx --since 24h

# 自定义时间窗 / 输出目录 / Bot 显示名
python3 skills/feishu-cli-chat/scripts/fetch_chat_history.py oc_xxxxxxxx \
    --start 2026-05-20T00:00:00 --end 2026-05-22T00:00:00 \
    --output-dir /tmp/my_chat \
    --bot-name "你的 Bot 显示名"

# 不展开线程（更快，但话题群会丢回复）
python3 skills/feishu-cli-chat/scripts/fetch_chat_history.py oc_xxx --since 24h --no-thread

输出 4 个文件到 --output-dir（默认 /tmp/lark_chat/）：history.json、threads.json、names.json、timeline.txt。

常用读命令

# 群聊一页历史（v1.27.1+ 默认自动展开线程）
feishu-cli msg history --container-id oc_xxx --container-id-type chat --page-size 50 -o json

# 关闭自动展开
feishu-cli msg history --container-id oc_xxx --container-id-type chat \
    --page-size 50 --expand-threads=false -o json

# 私聊
feishu-cli msg history --user-email user@example.com --page-size 50 -o json

# 时间窗内全部消息
feishu-cli msg history --container-id oc_xxx --container-id-type chat \
    --start-time $(date -v-24H +%s) --end-time $(date +%s) \
    --sort-type ByCreateTimeAsc --page-size 50 -o json

# 单条 / 批量消息详情
feishu-cli msg get <message_id> -o json
feishu-cli msg mget --message-ids <id1,id2>

# 话题回复（注意：thread-messages 不接受 -o json，默认就是 JSON 输出）
feishu-cli msg thread-messages <thread_id> --page-size 50 --sort ByCreateTimeAsc

消息互动命令

feishu-cli msg reaction add <message_id> --emoji-type THUMBSUP
feishu-cli msg reaction remove <message_id> --reaction-id <reaction_id>
feishu-cli msg reaction list <message_id>

feishu-cli msg pin <message_id>
feishu-cli msg unpin <message_id>
feishu-cli msg pins --chat-id <chat_id>

feishu-cli msg delete <message_id>                                  # Bot 自撤回
feishu-cli msg delete <message_id> --user-access-token u-xxx        # 管理员撤回

群聊管理命令

feishu-cli chat get oc_xxx
feishu-cli chat update oc_xxx --name "新群名"
feishu-cli chat member list oc_xxx
feishu-cli chat member add oc_xxx --id-list ou_xxx,ou_yyy
feishu-cli chat member remove oc_xxx --id-list ou_xxx
feishu-cli chat create --name "项目群" --user-ids ou_xxx,ou_yyy
feishu-cli chat delete oc_xxx

适用场景

拉取群聊或私聊的完整聊天记录，用于归档、分析或导出。
查看话题群中的话题回复。
搜索特定群聊或按关键词搜索消息。
对消息进行表情回应、置顶或删除。
管理群聊信息，如修改群名、增删成员、解散群。
处理外部群（external=true）的成员名单获取。

限制

外部群（external=true）的群信息/成员/配置类 API 默认禁用，必须满足：App 开启「对外共享能力」，且该 App 的 Bot 已加入此群。
外部群中 chat_members[].member_id 和 items[].sender.id 是不同 namespace，永远不要用 member_id 反查 sender 名字。
跨企业用户 user info 调用会返回 41050 错误，需静默跳过，靠 mentions[].name 兜底。
msg history 默认不展开线程，话题群必须再调 thread-messages 展开，否则丢回复。
thread-messages 不接受 -o json 参数，默认就是 JSON 输出。
撤回消息的 body.content 是字面字符串，需用 try: json.loads(...) 包住。
post content 有两种结构，需兼容 {zh_cn:{title,content}} 和扁平 {title,content}。
system 消息 template 含 {from_user} 占位符，需用同对象其他字段填充。
Bot 发送者 cli_xxx ≠ sender_names 中的 ou_xxx，需单独映射成已知的 bot 名字。
外部群 chat get/member list 等可能返回 232033 错误，需切到开了对外共享的 App 并使用 --as bot。

参考

scripts/fetch_chat_history.py — 端到端拉群消息的可执行脚本
references/output-quirks.md — JSON key / 时间单位 / 错误码 / 卡片解析等所有 API 怪癖
references/external-chat.md — 外部群操作完整路径/错误码/排错