feishu-cli-chat

name	feishu-cli-chat
description	飞书会话浏览、消息互动与群聊管理。看聊天记录（单聊/群聊/话题群）、搜群、获取消息详情、 Reaction 表情回应、Pin 置顶/取消置顶、删除消息，以及群聊信息管理（获取/更新/解散/成员）。 当用户请求"看群消息记录 / 拉群聊天记录 / 导出聊天记录 / 获取群历史 / 看话题回复 / 搜群 / 看私聊记录 / dump 飞书消息"时使用本技能；包括话题群（chat_mode=thread）的整线程展开。 读类（msg history/list/get/mget/thread-messages）登录后默认 User Token、未登录回落 Bot； 互动类（reaction/pin/search-chats/chat get/update/delete/member）必需 User Token； msg delete 默认 App Token 用于 Bot 自撤回，可显式 User Token 给管理员撤回场景； chat create/link 默认 Bot 身份创建群/获取群链接。
argument-hint	<chat_id|群名|用户名>
user-invocable	true
allowed-tools	Bash(feishu-cli auth:*), Bash(feishu-cli msg:*), Bash(feishu-cli chat:*), Bash(feishu-cli search:*), Bash(feishu-cli user:*), Bash(python3:*), Read, Write

飞书会话浏览与管理

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

选哪条路径

场景	走哪
看一段时间窗内的群消息（含话题回复、名字反解、卡片解析）	scripts/fetch_chat_history.py（一条命令搞定）
看一页群聊最新消息（v1.27.1+ 默认自动展开所有话题）	msg history 单次调用
看私聊记录	msg history --user-email 或 --user-id
找群	msg search-chats --query
看单条消息 / 合并转发	msg get / msg mget
看一个话题的全部回复	msg thread-messages <thread_id>
按关键词搜消息	search messages（属于 feishu-cli-search）
群成员管理、改群名	chat update / chat member ...
Reaction / Pin / 删除	msg reaction / msg pin / msg delete

认证

按命令类型区分：

• 读类（msg history/list/get/mget/thread-messages/resource-download）：登录后自动从 ~/.feishu-cli/token.json 加载 User Token，未登录回落 App Token（要求 Bot 在群里）。外部群 Bot 通常不在群里，读外部群必须先登录：

  feishu-cli auth check --scope "im:message:readonly im:message.group_msg:get_as_user"
  feishu-cli auth login --domain chat --recommend
  

• 必需 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 小时的全部消息拉出来"——同时涉及翻页、话题展开、 名字反解、撤回消息、富文本和卡片渲染。这些步骤每一步都有不止一个坑（详见 references/output-quirks.md），单条 CLI 解不完，所以封装成脚本：

# 默认最近 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	主消息原始 JSON + 飞书侧返回的部分 sender_names
threads.json	每个 thread_id → 完整回复列表
names.json	合并后的 open_id / app_id → 名字映射
timeline.txt	可读时间线：主消息升序 + 缩进 4 空格的线程回复（└─ 标识）

脚本默认行为：

1. msg history 用 ByCreateTimeAsc + start-time + end-time，按 page_token 翻页到 has_more=false；
2. 收集所有非空 thread_id，对每个 tid 调 msg thread-messages 展开（不传 -o json，因为它默认就是 JSON 且加了反报错）；
3. 名字反解三级降级：mentions[].name → sender_names API 字段 → user info 调用（外部用户会 41050，静默跳过）；
4. Bot app_id（cli_xxx）单独映射成 --bot-name 提供的名字；
5. 渲染时同时处理：撤回消息（content 为字符串非 JSON）、post 双结构、system 模板占位符、interactive v2 卡片递归。

如果脚本不能用，看下面的"手工拉群消息"小节，知道每步在做什么再退化到 jq + bash。

单次调用：常用读命令

# 群聊一页历史（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

# 调整展开规模（默认 per=50, total=500，与 lark-cli 对齐）
feishu-cli msg history --container-id oc_xxx --container-id-type chat \
    --threads-per-page 30 --threads-total-limit 300 -o json

# 私聊：邮箱或 open_id 自动反查 P2P chat_id
feishu-cli msg history --user-email [e-mail] --page-size 50 -o json
feishu-cli msg history --user-id ou_xxx --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

自动展开线程的 JSON 输出（v1.27.1+）

msg history -o json 顶层新增三个字段，与官方 lark-cli +chat-messages-list 对齐：

字段	说明
thread_replies	{thread_id: [reply, ...]}，ASC 顺序，不含根消息
thread_has_more	{thread_id: true} 标记该话题在 threads-per-page 限额内未拉完
thread_replies_card_texts	线程内 interactive 卡片的 card_texts 提取

sender_names 字段同时合并主消息 + merge_forward + thread_replies 三处来源的 mentions 名字，外部用户名字解析率显著提升（实测话题群从 8% → 42%）。

仍未解析的发送者通常是真正的跨租户外部用户且本话题内无人 @过他——这是飞书 OpenAPI 限制，contact basic_batch 不返回，官方 lark-cli 同样拿不到。

搜索与定位

feishu-cli msg search-chats --query "项目群" -o json   # 搜群
feishu-cli search messages "关键词" --chat-type p2p_chat -o json
feishu-cli search messages "关键词" --chat-ids oc_xxx -o json

搜消息属于 feishu-cli-search，本技能在阅读任务里顺带调用。

消息互动

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                          # 外部群可能 232033（看下方"外部群操作"）
feishu-cli chat update oc_xxx --name "新群名"
feishu-cli chat member list oc_xxx                  # 默认 auto；外部群推荐 --as bot
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

chat member list/add/remove 支持 --as bot|user|auto：

• auto（默认）：优先 User Token，回退 Bot Token
• bot：强制 Bot Token，外部群推荐（前提：App 开了"对外共享能力" + Bot 在群里）
• user：强制 User Token

外部群操作（必读）

凡是碰到 232033 错误 或 想拉外部群完整成员名单，先读 references/external-chat.md。

v1.27.2+ 新增：

• msg history 支持 --as bot|user|auto flag（默认 auto = User 优先回退 Bot）
• msg history 对群聊容器自动拉一次 chat member list，结果挂在顶层 chat_members 字段
  • 字段值是 [{member_id, member_id_type, name, tenant_key}, ...] 完整成员名单（含群昵称）
  • 同时有 chat_members_note 提示字段，告诉 Agent 怎么用（避免错配）
• msg history 输出的每条 items[*] 注入 sender_name 字段，省去查 sender_names 字典
• chat member list/add/remove 全部支持 --as bot|user|auto
• 错误码翻译：chat get/update/delete/link/member 命令收到 232033/232011/232006 时自动打印中文解决方案

⚠️ 重大陷阱：外部群里 chat_members[*].member_id 和 items[*].sender.id 是不同 namespace， 永远不要用 member_id 反查 sender 名字。详见 references/external-chat.md 「重大陷阱」段。

拉外部群完整成员（典型用法）

# 切到对外共享 App + Bot Token，从 msg history 顺带拉
FEISHU_APP_ID=cli_xxx FEISHU_APP_SECRET=xxx \
feishu-cli msg history --container-id oc_xxx --container-id-type chat \
  --page-size 1 --as bot --expand-threads=false -o json \
  | jq '.chat_members[] | select(.tenant_key != "<my_tenant>") | .name'
# → 输出所有外部商家名字（即群昵称），可直接喂给名字规范检查脚本

一句话：外部群（external=true）的「群信息/成员/配置」类 API 默认禁用，必须满足：

1. App 开启「对外共享能力」（飞书开放平台 → 应用 → 凭证与基础信息）
2. 该 App 的 Bot 已加入此群

如果你有另一个开了对外共享能力的 App，临时切换即可：

# 临时切 App（不写盘）
FEISHU_APP_ID=cli_对外共享App \
FEISHU_APP_SECRET=xxx \
feishu-cli chat member list oc_xxx --as bot

返回的 name 字段就是用户在该群的群昵称（没设则回落全局名），可直接用于名字规范检查等场景。

判断 chat 是否外部群：feishu-cli msg search-chats --query "..." -o json 看返回的 external 字段。

完整路径/错误码/排错见 references/external-chat.md。

踩坑速查（重要）

写代码前过一眼，否则容易卡 30 分钟。详细版见 references/output-quirks.md。

坑	一句话规避
thread-messages 加 -o json 报错	不要传；它默认就是 JSON 输出
thread-messages 返回 PascalCase	用 d.get("items") or d.get("Items") 兼容两套 key
history 时间秒、thread-messages 时间毫秒	start_sec vs start_sec * 1000，分别传
撤回消息 body.content 是字面字符串	try: json.loads(...) 包住，失败时直接当字符串显示
post content 两种结构	兼容 {zh_cn:{title,content}} 和扁平 {title,content}
system 消息 template 含 {from_user} 占位符	用同对象其他字段填充（list 逗号 join）
Bot 发送者 cli_xxx ≠ sender_names 中的 ou_xxx	单独映射成已知的 bot 名字
外部群 chat get/member list/... 232033	必读 references/external-chat.md；切到开了对外共享的 App + --as bot
跨企业 user info 41050	静默跳过，靠 mentions[].name 兜底
msg history 默认不展开线程	话题群必须再调 thread-messages 展开，否则丢回复

名字反解策略

外部群里大多数发送者飞书后端不返回名字。按可靠性 + 成本排序：

1. mentions[]（消息自带）：{"id":"ou_xxx","id_type":"open_id","name":"张三","key":"@_user_1"}， 还能用 key 替换 text 消息里的 @_user_N 占位符。不受外部租户隔离限制，首选。
2. sender_names（history/thread-messages 顶层）：飞书反解的子集，覆盖率低，作为起点。
3. user info <ou_xxx>：跨企业用户必返 41050 no user authority error，外部群几乎全部命中，静默跳过。
4. Bot cli_xxx：单独映射成你提前知道的 bot 名字（脚本的 --bot-name）。

输出处理

1. JSON 落到临时文件再分析，避免长消息刷屏；
2. 文本内容在 body.content 里，按 msg_type 解析 JSON 字符串（撤回消息除外，见上）；
3. mentions 字段同时含 open_id → name 映射 + @_user_N key → name 映射，比 sender_names 更全，优先用。

卡片消息（interactive）

msg history 默认带 --card-content-type user，会得到 v2 schema JSON + 抽取后的 card_texts。 脚本里已经覆盖 v2 schema 的递归（column_set / form / collapsible_panel / action / button / img / note），手工解析见 references/output-quirks.md 的 §8。

需要"原版 cardDSL"或"OAPI 渲染版"时切换：

feishu-cli msg history --container-id oc_xxx --card-content-type raw      -o json   # 平台内部 cardDSL
feishu-cli msg history --container-id oc_xxx --card-content-type rendered -o json   # OAPI 渲染版/降级版

参考

• scripts/fetch_chat_history.py — 端到端拉群消息的可执行脚本
• references/output-quirks.md — JSON key / 时间单位 / 错误码 / 卡片解析等所有 API 怪癖