name: feishu-cli-chat description: >- 飛書會話瀏覽、訊息互動與群聊管理。檢視聊天記錄、獲取群聊歷史訊息、搜尋群聊、 獲取訊息詳情、Reaction 表情回應、Pin 置頂/取消置頂、刪除訊息、 群聊資訊查詢與管理（獲取/更新/解散/成員管理）。 支援普通群和話題群兩種模式，話題群自動獲取執行緒回覆。所有命令需要 User Token。 當用戶請求"檢視聊天記錄"、"看和某人的訊息"、"群聊歷史"、"群訊息"、"搜尋群聊"、 "查群資訊"、"群成員"、"最近訊息"、"聊天記錄"、"Reaction"、"表情回應"、 "置頂訊息"、"Pin"、"刪除訊息"、"獲取訊息"、"訊息詳情"、 "和誰聊了什麼"、"群裡說了什麼"、"總結群訊息"、"話題回覆"、"執行緒回覆"、 "thread replies"時使用。 也適用於：使用者給出一個群聊名稱或 chat_id 並希望瀏覽其訊息的場景， 即使沒有明確說"聊天記錄"。當用戶想了解某個群最近在討論什麼、 想找和某人的對話內容、或想對訊息進行互動操作時，都應使用此技能。 argument-hint: user-invocable: true allowed-tools: Bash, Read, Write

飛書會話瀏覽與管理

通過 feishu-cli 瀏覽飛書單聊/群聊訊息歷史、搜尋會話、管理群聊資訊和成員。

前置條件

本技能的核心命令必須使用 User Token，使用前需先登入。chat create、chat link、msg read-users 使用 App Token，屬於 feishu-cli-toolkit 技能。

feishu-cli auth login

未登入時命令會直接報錯並提示登入方式。登入後 token 自動載入，無需手動傳參。

身份說明

User Token 能力： - 檢視 bot 不在的群聊訊息 - 檢視私聊（p2p）訊息 - 搜尋使用者有許可權的所有會話

自動降級機制

當使用 User Token 呼叫 msg history / msg list 時，如果 bot 不在目標群中，API 會返回空結果。CLI 會自動檢測這種情況並降級為 search + get 方式獲取訊息：

list API 返回空 + has_more=true → 自動切換到搜尋模式 → 逐條獲取訊息內容

這個過程對使用者透明，無需手動干預。

場景一：檢視群聊歷史訊息

這是最常見的場景——使用者想看某個群最近在聊什麼。

步驟 1：找到群聊

如果使用者給了群名而不是 chat_id，先搜尋：

feishu-cli msg search-chats --query "群名關鍵詞" -o json

輸出中的 chat_id（形如 oc_xxx）就是後續命令需要的標識。

步驟 2：獲取訊息

# 獲取最近 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 返回的訊息欄位：

訊息中的執行緒相關欄位

普通群：一次獲取全部訊息

普通群的 msg history 返回所有訊息（獨立訊息 + 執行緒回覆），平鋪在同一列表中。通過 root_id/parent_id 可重建回覆關係，不需要額外獲取執行緒。

獨立訊息:       無 thread_id、無 root_id
被回覆的訊息:   有 thread_id（被回覆後自動產生）
執行緒回覆:       有 thread_id + root_id + parent_id

話題群：需要逐個話題獲取回覆（重要）

話題群的 msg history --container-id-type chat 僅返回每個話題的首條訊息，執行緒回覆不在主訊息流中。必須按 thread_id 逐個獲取：

# 獲取單個話題的所有回覆（按時間正序，方便閱讀）
feishu-cli msg history \
  --container-id omt_xxx \
  --container-id-type thread \
  --page-size 50 \
  --sort-type ByCreateTimeAsc \
  -o json

完整的話題群獲取流程：

# 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 字串，常見格式：

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

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

完整示例：獲取並總結群聊最近 N 條訊息

# 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 的 page_size 與 List API 不同，降級模式下每頁實際返回數量可能少於請求值。建議迴圈翻頁直到 has_more=false 或達到目標數量。

場景二：檢視和某人的私聊記錄

飛書 Open API 不支援直接按使用者查詢 p2p 聊天記錄。需要通過搜尋 API 間接實現。

方法：搜尋 + 篩選

# 搜尋私聊訊息
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：

# 通過郵箱查詢使用者
feishu-cli user search --email user@example.com -o json

# 通過手機號查詢使用者
feishu-cli user search --mobile 13800138000 -o json

注意：user search 僅支援 --email 和 --mobile 精確查詢，不支援按姓名模糊搜尋。

限制說明

• 搜尋 API 的 query 引數不能為空，至少需要一個空格 " "
• p2p 聊天無法通過 msg search-chats 搜尋（該 API 只搜尋群聊）
• 搜尋結果返回的是訊息 ID 列表，需要逐條 msg get 獲取完整內容
• msg get 對私聊訊息可能返回 230001 錯誤（API 限制：部分私聊訊息不支援通過 Get API 獲取詳情），此時只能依賴搜尋結果中的摘要資訊

場景三：搜尋群聊

搜尋群聊列表

# 按關鍵詞搜尋群聊
feishu-cli msg search-chats --query "關鍵詞" -o json

# 分頁獲取所有群
feishu-cli msg search-chats --page-size 100 -o json

在群內搜尋訊息

# 在指定群中搜索訊息
feishu-cli search messages "關鍵詞" --chat-ids oc_xxx -o json

更多搜尋功能（按時間範圍、訊息型別、傳送者、跨模組搜尋文件/應用等）請使用 feishu-cli-search 技能，提供完整的篩選引數和 Token 排錯指南。

場景四：群聊資訊管理

檢視群資訊

feishu-cli chat get oc_xxx

預設輸出 JSON 格式，包含群名、描述、群主、群型別、成員數量等。

檢視群成員

# 獲取成員列表
feishu-cli chat member list oc_xxx

# 指定 ID 型別
feishu-cli chat member list oc_xxx --member-id-type user_id

# 分頁獲取（大群）
feishu-cli chat member list oc_xxx --page-size 100 --page-token "xxx"

Scope 要求：使用 User Token 時需要 im:chat:readonly 或 im:chat.members:read scope。若報 99991679 錯誤，需通過 auth login --scopes "... im:chat:readonly" 重新授權。

7w4.net提供免費和付費技能下載。

修改群資訊

# 改群名
feishu-cli chat update oc_xxx --name "新群名"

# 改群描述
feishu-cli chat update oc_xxx --description "新的群描述"

# 轉讓群主
feishu-cli chat update oc_xxx --owner-id ou_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

# 使用 user_id 型別
feishu-cli chat member add oc_xxx --id-list user_xxx --member-id-type user_id

建立群聊

feishu-cli chat create --name "新群聊" --user-ids ou_xxx,ou_yyy

注意：chat create 和 chat link（獲取分享連結）僅支援 App Token（租戶身份），不支援 User Token。

解散群聊

feishu-cli chat delete oc_xxx
# 會要求確認，不可逆操作

場景五：訊息詳情與互動

獲取單條訊息詳情

feishu-cli msg get om_xxx -o json

檢視訊息已讀情況

feishu-cli msg read-users om_xxx -o json

限制：僅支援查詢 bot 自己傳送的、7 天內的訊息，且 bot 必須在會話內。此命令僅使用 App Token。

檢視群內建頂訊息

feishu-cli msg pins --chat-id oc_xxx -o json

置頂/取消置頂訊息

# 置頂訊息
feishu-cli msg pin <message_id>

# 取消置頂
feishu-cli msg unpin <message_id>

Reaction 表情回應

# 新增表情
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> [--emoji-type THUMBSUP] [--page-size 20]

常用 emoji-type：THUMBSUP（點贊）、SMILE（微笑）、LAUGH（大笑）、HEART（愛心）、JIAYI（加一）、OK、FIRE

刪除訊息

僅能刪除機器人自己傳送的訊息，不可恢復。

feishu-cli msg delete <message_id>

常見操作速查表

標記 User 的命令必須先 auth login，未登入會報錯。標記 App 的命令使用應用身份，無需登入。

處理大量訊息的最佳實踐

當需要獲取並分析大量訊息（如 100+ 條）時：

1. 儲存到檔案：每頁結果用 -o json 輸出，重定向到檔案
2. 迴圈翻頁：檢查 HasMore 和 PageToken，迴圈獲取直到滿足條件
3. 用 Python 解析：JSON 訊息結構需要解析 body.content 提取文本
4. 注意限頻：搜尋 API 有頻率限制，大量請求間加 1s 延遲；msg history 限頻較寬鬆，可安全併發
5. 時間戳：create_time 是毫秒級時間戳，需除以 1000 轉為秒
6. 話題群併發獲取執行緒：話題群需要對每個 thread_id 單獨呼叫 msg history --container-id-type thread，建議並行呼叫多個話題以提高效率（實測 10-20 個併發無問題）
7. 已撤回訊息：deleted: true 的訊息內容為 "This message was recalled"，彙總時應跳過

import json
from datetime import datetime

# 解析訊息時間
ts = int(msg['create_time']) / 1000
dt = datetime.fromtimestamp(ts)
time_str = dt.strftime('%Y-%m-%d %H:%M')

# 提取文本內容
content = json.loads(msg['body']['content'])
text = content.get('text', '')

許可權要求

與其他技能的分工

這個 Skill 質量不錯，文件寫得詳細清晰，能滿足檢視聊天記錄、管理群聊、搜尋訊息、新增表情互動等多種需求。內容按場景分類，容易理解，速查表和許可權說明也很實用。不過目前只有文字文件，沒有示例檔案，實際使用前可能需要自己動手試錯。總體來說功能較全、指引明確，是一款實用的飛書聊天管理工具。