lark-im

im (v1)

重要 — 開始前 MUST 先用 Read 工具讀取 ../lark-shared/SKILL.md，其中包含認證、權限處理

核心概念

• Message: 聊天中的單一訊息，由 message_id (om_xxx) 識別。支援類型：text、post、image、file、audio、video、sticker、interactive (card)、share_chat、share_user、merge_forward 等。
• Chat: 群聊或一對一對話，由 chat_id (oc_xxx) 識別。
• Thread: 訊息下的回覆串，由 thread_id (om_xxx 或 omt_xxx) 識別。
• Reaction: 訊息上的表情回覆。
• Flag: 訊息或 Thread 的書籤。
• Feed Shortcut: 固定到目前使用者 Feed 側邊欄的聊天，由 feed_card_id (CHAT 類型為 oc_xxx open_chat_id) 識別。
• Feed Group: 在 Feed 列表中將 Feed 卡片分組的標籤，由 feed_group_id (ofg_xxx) 識別。成員是 Feed 卡片，每個由 feed_id + feed_type 識別。兩種類型：normal（成員明確管理）和 rule（成員根據規則自動衍生）。

資源關係

Chat (oc_xxx)
├── Message (om_xxx)
│   ├── Thread (回覆串)
│   ├── Reaction (表情)
│   └── Resource (圖片 / 檔案 / 影片 / 音訊)
└── Member (使用者 / 機器人)

重要注意事項

身份與 Token 對應

• --as user 表示使用者身份，使用 user_access_token。呼叫以授權終端使用者身份執行，因此權限取決於應用範圍以及該使用者對目標聊天/訊息/資源的存取權限。
• --as bot 表示機器人身份，使用 tenant_access_token。呼叫以應用機器人身份執行，因此行為取決於機器人的成員資格、應用可見性、可用範圍以及機器人特定範圍。
• 如果 IM API 表示同時支援 user 和 bot，則 Token 類型會改變操作者身份。同一個 API 可能以一種身份成功，另一種身份失敗，因為擁有者/管理員狀態、聊天成員資格、租戶邊界或應用可用性會根據當前呼叫者進行檢查。

發送者名稱解析

擷取訊息時（+chat-messages-list、+threads-messages-list、+messages-mget、+messages-search），CLI 會為使用者和機器人發送者顯示顯示名稱：

• 伺服器提供的名稱：讀取 API 會回傳每個訊息 sender 上的 sender_name（以及完整的 i18n sender_i18n_names 對應）；CLI 將其顯示為使用者和機器人發送者的 name。不需要名稱查詢和額外權限 — 不需要 contact scope 和 application:bot.basic_info:read。
• 回退到 ID：當伺服器未提供名稱時，發送者會以其 ID 顯示，且指令仍以 exit 0 結束。沒有通訊錄回退。

原始 sender_name 不會在輸出中重複（其值在 name 中）；完整的 sender_i18n_names 對應（所有語言）會保留給需要特定語言的消費者，同時為機器人發送者提供可選的 open_bot_id (ou_)，與訊息接收事件通道對齊。系統訊息（msg_type: system）沒有發送者名稱 — 這是正常情況，不是錯誤。

預設訊息豐富化（reactions / update_time）

四個訊息拉取快捷指令（+messages-mget、+chat-messages-list、+messages-search、+threads-messages-list）會自動為每個回傳的訊息附加 reactions 區塊和（對於已編輯訊息）update_time — 不需要單獨呼叫 im.reactions.batch_query。傳遞 --no-reactions 可選擇退出。有關完整合約（輸出結構、im:message.reactions:read 範圍要求，以及「缺少欄位 ≠ 擷取失敗」的資料規則），請閱讀 references/lark-im-message-enrichment.md。

選擇性資源自動下載（--download-resources）

+chat-messages-list、+messages-mget 和 +threads-messages-list 接受 --download-resources（預設關閉 — 省略時沒有 resources 區塊和額外請求）。設定後，符合條件的訊息資源（圖片/檔案/音訊/影片/媒體 + 貼文嵌入；貼圖排除）會下載到 ./lark-im-resources/，每個訊息會獲得一個 resources 陣列，包含 {message_id, key, type, local_path, size_bytes}。下載會根據 (message_id, file_key) 去重，以有限並行度執行，並隔離單一資源失敗（error: true + stderr 警告）。範圍： 需要 im:message:readonly（已由列表指令宣告 — 不需要額外範圍）；在使用者和機器人身份下均可運作。對於一次性下載，請使用 +messages-resources-download。完整合約：references/lark-im-message-enrichment.md。

卡片訊息（互動式）

在使用任何 interactive 卡片發送或回覆（+messages-send / +messages-reply）之前，你 MUST 閱讀 references/card/lark-im-card-create.md 並遵循其工作流程。 傳遞給 --msg-type interactive --content 的卡片 JSON 必須是該工作流程的輸出 — 切勿手寫或複製卡片負載。

卡片訊息（interactive 類型）尚未支援事件訂閱中的緊湊轉換。原始事件資料將被回傳，並在 stderr 中印出提示。

interactive 卡片支援回呼事件（card.action.trigger）— 請參閱 references/lark-im-card-action-reply.md。

音訊訊息

--audio 發送語音訊息，僅支援 Opus 音訊檔案，例如 .opus 檔案或 Ogg Opus (.ogg) 檔案。對於 mp3、wav 或其他非 Opus 音訊，請先轉換為 .opus 並繼續使用 --audio，或使用 --file 將原始檔案作為附件發送。

將文件內容作為訊息發送

將從飛書文件擷取的內容作為訊息發送時，請使用 --doc-format im-markdown 擷取文件，然後使用 --markdown 格式將其作為訊息發送。擷取的內容已經是 markdown；在任何內容轉發場景中，保留擷取的原始文字並以 --markdown 格式發送。注意：如果文件包含 type="user" 的 cite 標籤，請保持原樣，不要移除該標籤。

Flag 類型

Flag 支援兩層：

• 訊息層 flag：(ItemTypeDefault, FlagTypeMessage) — 常規訊息書籤
• Feed 層 flag：(ItemTypeThread/ItemTypeMsgThread, FlagTypeFeed) — Thread 作為 Feed 層書籤

Feed 層 flag 的項目類型：

• ItemTypeThread (4) = 話題式聊天中的 Thread
• ItemTypeMsgThread (11) = 常規聊天中的 Thread

Feed Shortcut

Feed Shortcut 將聊天新增到目前使用者的 Feed 側邊欄。它們與 Flag 不同：

• Flag = 訊息/Thread 上的書籤，範圍限定於使用者的書籤列表。
• Feed shortcut = 使用者 Feed 側邊欄中的條目（目前僅限聊天）。

主要限制：

• 僅 CHAT 類型（feed_card_id 為 oc_xxx）透過 OpenAPI 公開；文件/應用/訂閱快捷方式存在於內部，但尚未列入白名單。
• 所有三個操作（建立/移除/列表）均為僅限使用者身份 — 它們使用 user_access_token 簽署。
• 批次大小為每次呼叫 10 個用於建立/移除；列表是單頁包裝器，具有不透明的 page_token 分頁。

快捷指令（建議優先使用）

快捷指令是對常用操作的高階封裝（lark-cli im +<verb> [flags]）。有快捷指令的操作優先使用。

快捷指令	說明
+chat-create	建立群聊或話題聊天；使用者/機器人；--chat-mode group
+chat-list	列出目前使用者/機器人為成員的聊天；預設為群組；傳遞 --types=p2p,group 以包含一對一聊天（僅限使用者）；使用者/機器人；支援排序、分頁、--exclude-muted（僅限使用者）
+chat-members-list	列出聊天的成員；回傳單獨的 users[] / bots[] 桶；可以使用者或機器人身份呼叫；--member-types 過濾要回傳的類型；--page-all 分頁；當伺服器限制桶大小時顯示 truncations[]
+chat-messages-list	列出聊天或一對一對話中的訊息；使用者/機器人；接受 --chat-id 或 --user-id，解析 P2P chat_id，支援時間範圍/排序/分頁
+chat-search	透過 --query 關鍵字和/或 --member-ids 搜尋可見的群聊；使用者/機器人；例如按群組名稱查詢 chat_id；支援類型過濾、排序、分頁和 --exclude-muted（僅限使用者身份）
+chat-update	更新群聊名稱或描述；使用者/機器人；更新聊天的名稱或描述
+messages-mget	按 ID 批次取得訊息；使用者/機器人；擷取最多 50 個 om_ 訊息 ID，格式化發送者名稱，展開 Thread 回覆
+messages-reply	回覆訊息（支援 Thread 回覆）；使用者/機器人；支援文字/markdown/貼文/媒體回覆、在 Thread 中回覆、冪等金鑰
+messages-resources-download	從訊息下載圖片/檔案；使用者/機器人；支援大檔案自動分塊下載（8MB 塊），從 Content-Type 自動偵測副檔名
+messages-search	跨聊天搜尋訊息（支援關鍵字、發送者、時間範圍過濾），使用使用者身份；僅限使用者；按聊天/發送者/附件/時間過濾，支援透過 --page-all / --page-limit 自動分頁，透過批次 mget 和 chats batch_query 豐富結果
+messages-send	發送訊息到聊天或直接訊息；使用者/機器人；發送到 chat-id 或 user-id，使用文字/markdown/貼文/媒體，支援冪等金鑰
+threads-messages-list	列出 Thread 中的訊息；使用者/機器人；接受 om_/omt_ 輸入，將訊息 ID 解析為 thread_id，支援排序/分頁
+flag-create	在訊息上建立書籤；僅限使用者；預設為訊息層 flag；使用 --flag-type feed 用於 Feed 層 flag（item_type 從聊天模式自動偵測）
+flag-cancel	取消（移除）書籤。當未給出 --flag-type 時，盡力雙重取消：移除訊息層，並在可確定 chat_type 時移除 Feed 層
+flag-list	列出書籤；僅限使用者；自動豐富 Feed 類型 Thread 條目的訊息內容；--page-all 受 --page-limit 限制（預設 20，最大 1000），has_more=true 表示結果不完整
+feed-shortcut-create	將聊天新增到使用者的 Feed 快捷方式；僅限使用者；僅 oc_xxx 聊天 ID；每次呼叫最多批次 10 個；--head/--tail 控制插入順序；部分失敗回傳 ok:false 帳本
+feed-shortcut-remove	從使用者的 Feed 快捷方式移除聊天；僅限使用者；每次呼叫最多批次 10 個；移除不存在的快捷方式是冪等成功；實際逐項失敗回傳 ok:false 帳本
+feed-shortcut-list	列出使用者 Feed 快捷方式的一頁；僅限使用者；省略 --page-token 以取得第一頁；預設輸出在 detail 下豐富 CHAT 條目；傳遞 --no-detail 以跳過額外查詢和 im:chat:read 範圍
+feed-group-list	列出呼叫者的 Feed 群組（標籤）；僅限使用者；支援 --page-all 自動分頁
+feed-group-list-item	列出 Feed 群組（標籤）中的 Feed 卡片；僅限使用者；使用從 feed_id 解析的 chat_name 豐富每個項目；支援 --page-all 自動分頁
+feed-group-query-item	按 ID 查詢 Feed 群組（標籤）中的特定 Feed 卡片；僅限使用者；使用從 feed_id 解析的 chat_name 豐富每個項目

API 資源

lark-cli schema im.<resource>.<method>   # 呼叫 API 前必須先查看參數結構
lark-cli im <resource> <method> [flags] # 呼叫 API

重要：使用原生 API 時，必須先執行 schema 查看 --data / --params 參數結構，不要猜測欄位格式。

chats

• create — 建立群組。身份：僅 bot (tenant_access_token)。
• get — 取得群組資訊。身份：支援 user 和 bot；呼叫者必須在目標聊天中才能取得完整詳細資訊，且對於內部聊天必須屬於同一租戶。
• link — 取得群組分享連結。身份：支援 user 和 bot；呼叫者必須在目標聊天中，當聊天分享僅限擁有者/管理員時必須是擁有者或管理員，且對於內部聊天必須屬於同一租戶。
• update — 更新群組資訊。身份：支援 user 和 bot。

chat.members

• create — 將使用者或機器人加入群聊。身份：支援 user 和 bot；呼叫者必須在目標聊天中；對於 bot 呼叫，新增的使用者必須在應用可用範圍內；對於內部聊天，操作者必須屬於同一租戶；如果只有擁有者/管理員可以新增成員，則呼叫者必須是擁有者/管理員，或是具有 im:chat:operate_as_owner 的聊天建立機器人。
• delete — 將使用者或機器人移出群聊。身份：支援 user 和 bot；只有群組擁有者、管理員或建立者機器人可以移除他人；每次請求最多 50 個使用者或 5 個機器人。

chat.user_setting

• batch_query — 批次查詢目前使用者在群組中的個人偏好設定（例如 is_muted 靜音一般訊息，is_mute_at_all 靜音 @all 訊息）；每次請求最多 10 個聊天。身份：僅 user (user_access_token)；呼叫者必須在每個目標聊天中。
• batch_update — 批次更新目前使用者在群組中的個人偏好設定（例如 is_muted 靜音一般訊息，is_mute_at_all 靜音 @all 訊息）；每次請求最多 10 個聊天。身份：僅 user (user_access_token)；呼叫者必須在每個目標聊天中。

chat.nickname

• get — 取得自己的群組暱稱。僅限自己。身份：僅 user (user_access_token)；未設定暱稱時回傳空字串。
• update — 設定自己的群組暱稱。僅限自己。身份：僅 user (user_access_token)；nickname 必須是非空字串（最多 300 位元組）。使用 DELETE 清除。
• delete — 清除自己的群組暱稱。僅限自己。身份：僅 user (user_access_token)。

chat.managers

• add_managers — 指定群組管理員。身份：支援 user 和 bot；只有群組擁有者可以新增管理員；每個聊天最多 10 個管理員（超大群組為 20 個），且每次請求最多 5 個機器人。
• delete_managers — 刪除群組管理員。身份：支援 user 和 bot；只有群組擁有者可以移除管理員；每次請求最多 50 個使用者或 5 個機器人。

chat.moderation

• get — 取得群組成員發言權限。身份：支援 user 和 bot；呼叫者必須在目標聊天中且屬於同一租戶。
• update — 更新群組發言權限。身份：支援 user 和 bot；只有群組擁有者（或具有 im:chat:operate_as_owner 的建立者機器人）可以更新；呼叫者必須在聊天中。

messages

• delete — 撤回訊息。身份：支援 user 和 bot；對於 bot 呼叫，機器人必須在聊天中才能撤回群組訊息；要撤回其他使用者的群組訊息，機器人必須是擁有者、管理員或建立者；對於使用者一對一撤回，目標使用者必須在機器人的可用範圍內。
• forward — 轉發訊息。身份：支援 user 和 bot。
• merge_forward — 合併轉發訊息。身份：僅 bot (tenant_access_token)。
• read_users — 查詢訊息已讀資訊。身份：僅 bot (tenant_access_token)；機器人必須在聊天中，且只能查詢其在過去 7 天內發送的訊息的已讀狀態。
• urgent_app — 發送應用內加急。身份：僅 bot (tenant_access_token)；機器人必須是訊息發送者且必須在包含該訊息的對話中。
• urgent_phone — 發送電話加急。身份：僅 bot (tenant_access_token)；機器人必須是訊息發送者且必須在包含該訊息的對話中。
• urgent_sms — 發送簡訊加急。身份：僅 bot (tenant_access_token)；機器人必須是訊息發送者且必須在包含該訊息的對話中。

reactions

• batch_query — 批次取得訊息表情。身份：支援 user 和 bot。必讀
• create — 新增訊息表情回覆。身份：支援 user 和 bot；呼叫者必須在包含該訊息的對話中。必讀
• delete — 刪除訊息表情回覆。身份：支援 user 和 bot；呼叫者必須在包含該訊息的對話中，且只能刪除自己新增的表情。必讀
• list — 取得訊息表情回覆。身份：支援 user 和 bot；呼叫者必須在包含該訊息的對話中。必讀

threads

• forward — 轉發話題。身份：支援 user 和 bot。

images

• create — 上傳圖片。身份：僅 bot (tenant_access_token)。

pins

• create — Pin 訊息。身份：支援 user 和 bot。
• delete — 移除 Pin 訊息。身份：支援 user 和 bot。
• list — 取得群組內 Pin 訊息。身份：支援 user 和 bot。

feed.groups

• batch_add_item — 批次新增 Feed 卡片到 Feed 群組。身份：僅 user (user_access_token)。必讀
• batch_query — 批次查詢 Feed 群組。身份：僅 user (user_access_token)。必讀
• batch_remove_item — 批次從 Feed 群組移除 Feed 卡片。身份：僅 user (user_access_token)。必讀
• create — 建立 Feed 群組。身份：僅 user (user_access_token)。必讀
• delete — 刪除 Feed 群組。身份：僅 user (user_access_token)。必讀
• update — 更新 Feed 群組。身份：僅 user (user_access_token)。必讀

權限表

方法	所需 scope
chats.create	im:chat:create
chats.get	im:chat:read
chats.link	im:chat:read
chats.update	im:chat:update
chat.members.create	im:chat.members:write_only
chat.members.delete	im:chat.members:write_only
chat.members.get	im:chat.members:read
+chat-members-list	im:chat.members:read
chat.user_setting.batch_query	im:chat.user_setting:read
chat.user_setting.batch_update	im:chat.user_setting:write
chat.managers.add_managers	im:chat.managers:write_only
chat.managers.delete_managers	im:chat.managers:write_only
chat.moderation.get	im:chat.moderation:read
chat.moderation.update	im:chat:moderation:write_only
messages.delete	im:message:recall
messages.forward	im:message
messages.merge_forward	im:message
messages.read_users	im:message:readonly
messages.urgent_app	im:message.urgent
messages.urgent_phone	im:message.urgent:phone
messages.urgent_sms	im:message.urgent:sms
reactions.batch_query	im:message.reactions:read
reactions.create	im:message.reactions:write_only
reactions.delete	im:message.reactions:write_only
reactions.list	im:message.reactions:read
threads.forward	im:message
images.create	im:resource
pins.create	im:message.pins:write_only
pins.delete	im:message.pins:write_only
pins.list	im:message.pins:read
feed.groups.batch_add_item	im:feed_group_v1:write
feed.groups.batch_query	im:feed_group_v1:read
feed.groups.batch_remove_item	im:feed_group_v1:write
feed.groups.create	im:feed_group_v1:write
feed.groups.delete	im:feed_group_v1:write
feed.groups.update	im:feed_group_v1:write