lark-im

im (v1)

重要：开始前 MUST 先使用 Read 工具读取 ../lark-shared/SKILL.md，其中包含认证和权限处理说明。

核心概念

• 消息：聊天中的单条消息，由 message_id（om_xxx）标识。支持的类型包括：文本、帖子、图片、文件、音频、视频、贴纸、交互式卡片、分享聊天、分享用户、合并转发等。
• 聊天：群聊或点对点会话，由 chat_id（oc_xxx）标识。
• 线程：消息下的回复线程，由 thread_id（om_xxx 或 omt_xxx）标识。
• 表情回应：消息上的表情回应。
• 标记：消息或线程上的书签。
• Feed 快捷方式：固定在当前用户 Feed 侧边栏中的聊天，由 feed_card_id（CHAT 类型的 oc_xxx open_chat_id）标识。
• Feed 分组：Feed 列表中用于对 Feed 卡片分组的标签，由 feed_group_id（ofg_xxx）标识。成员为 Feed 卡片，每个卡片由 feed_id + feed_type 标识。有两种类型：normal（显式管理成员）和 rule（根据规则自动确定成员）。

资源关系

Chat (oc_xxx)
├── Message (om_xxx)
│   ├── Thread (reply thread)
│   ├── Reaction (emoji)
│   └── Resource (image / file / video / audio)
└── Member (user / bot)

重要说明

AppLink 和分享链接

优先使用 CLI 返回的链接：使用 chat_app_link 打开已加入的会话，使用 message_app_link 打开消息，使用 share_link 邀请他人加入群组。如果手动构建已加入会话的 AppLink，请使用 https://<applink_host>/client/chat/open?openChatId=<oc_xxx>，切勿使用 chatId=<oc_xxx> 或 lark://...chat_id=<oc_xxx>。

身份与令牌映射

• --as user 表示用户身份，并使用 user_access_token。调用以已授权的最终用户身份执行，因此权限取决于应用权限范围以及该用户对目标聊天、消息或资源的访问权限。
• --as bot 表示机器人身份，并使用 tenant_access_token。调用以应用机器人身份执行，因此行为取决于机器人的成员资格、应用可见性、可用范围和机器人专属权限范围。
• 如果某个 IM API 声明同时支持 user 和 bot，令牌类型会决定操作者身份。同一个 API 可能以一种身份调用成功、以另一种身份调用失败，因为所有者／管理员身份、聊天成员资格、租户边界或应用可用性都会根据当前调用者进行检查。

发件人名称解析

获取消息时（+chat-messages-list、+threads-messages-list、+messages-mget、+messages-search），CLI 会显示用户和机器人发件人的显示名称：

• 服务端提供的名称：读取 API 会在每条消息的 sender 中返回 sender_name（以及包含完整国际化信息的 sender_i18n_names 映射）；CLI 会将其作为用户和机器人的 name 显示。无需查询名称，也无需额外权限——不需要联系人权限范围，也不需要 application:bot.basic_info:read。
• 回退为 ID：如果服务端未提供名称，则显示发件人的 ID，命令仍会以退出码 0 结束。不会回退到联系人目录查询。

原始 sender_name 不会在输出中重复（其值已包含在 name 中）；完整的 sender_i18n_names 映射（所有语言区域）会予以保留，供需要特定语言的使用方使用；机器人发件人还可能包含可选的 open_bot_id（ou_），与消息接收事件通道保持一致。系统消息（msg_type: system）没有发件人名称，这是正常情况，并非错误。

默认消息增强（表情回应／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。

精简消息输出（--concise）

部分消息列表快捷命令支持使用 --concise 输出精简的 Markdown。用户要求精简输出或较小的结果／文件时使用；通过 --help 检查是否支持，且不要将其与显式的 --format、启用的 --json 或非空的 --jq 一起使用。

选择性自动下载资源（--download-resources）

+chat-messages-list、+messages-mget 和 +threads-messages-list 支持使用 --download-resources 将符合条件的附件保存到 ./lark-im-resources/，并为每条消息添加一个 resources 数组。默认关闭；贴纸无法下载。附件下载失败时，会在对应资源上报告错误，不会中止消息拉取。单个附件请使用 +messages-resources-download。有关输出约定，请参阅 references/lark-im-message-enrichment.md。

文件夹资源是容器，不是文件——不能直接下载文件夹的 file_key。请先使用 lark-cli im files folder --recursive --file-key <folder_key> --srctype message --srcid <message_id> 展开文件夹，再使用 +messages-resources-download 下载其中的文件。

卡片消息（交互式）

发送、回复或更新任何 interactive 卡片（+messages-send / +messages-reply / messages.patch）之前，必须阅读 references/card/lark-im-card-create.md 并遵循其中的工作流。 传入 --msg-type interactive --content（发送／回复）或 messages.patch --data（更新）的卡片 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 将原始文件作为附件发送。

将文档内容作为消息发送

将从 Lark 文档获取的内容作为消息发送时，请使用 --doc-format im-markdown 获取文档，再使用 --markdown 格式将其作为消息发送。获取的内容已经是 Markdown；在任何转发内容的场景中，都应保留获取到的原始文本，并使用 --markdown 格式发送。注意：如果文档包含 type="user" 的 cite 标签，请原样保留，不要移除该标签。

标记类型

标记支持两层：

• 消息层标记：(ItemTypeDefault, FlagTypeMessage)——常规消息书签
• Feed 层标记：(ItemTypeThread/ItemTypeMsgThread, FlagTypeFeed)——线程作为 Feed 层书签

Feed 层标记的项目类型：

• ItemTypeThread（4）= 主题式聊天中的线程
• ItemTypeMsgThread（11）= 常规聊天中的线程

Feed 快捷方式

Feed 快捷方式会将聊天添加到当前用户的 Feed 侧边栏。它们与标记不同：

• 标记 = 对消息／线程的书签，限定在用户的书签列表中。
• Feed 快捷方式 = 用户 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 可包含 p2p 单聊（仅限用户）；用户/机器人；支持排序、自动分页、--exclude-muted（仅限用户）
+chat-members-list	列出聊天成员；分别返回 users[] / bots[] 分组；可由用户或机器人调用；--member-types 可筛选要返回的成员类型；--page-all 可分页；当服务端限制某个分组的数量时，会显示 truncations[]
+chat-messages-list	列出聊天或 P2P 会话中的消息；用户/机器人；接受 --chat-id 或 --user-id，可解析 P2P chat_id，支持时间范围、--order asc/desc 排序和自动分页
+chat-search	按 --query 关键词和/或 --member-ids 搜索可见群聊；用户/机器人；例如，按群名称查找 chat_id；支持类型筛选、排序、自动分页和 --exclude-muted（仅限用户身份）
+chat-update	更新群聊名称或描述；用户/机器人；更新聊天的名称或描述
+message-read-users	列出已读某条消息的用户；用户/机器人；权限范围因身份而异；支持有界自动分页
+messages-edit	编辑消息内容（text/post，包括附件区域）；仅限机器人（服务端会拒绝用户身份）；PUT /open-apis/im/v1/messages/:message_id
+messages-mget	按 ID 批量获取消息；用户/机器人；最多获取 50 个 om_ 消息 ID，格式化发送者名称，并展开线程回复
+messages-read-status	批量查询当前用户是否已读 1–50 条消息；仅限用户；返回可读取的条目和无效消息 ID
+messages-reply	回复消息（支持线程回复）；用户/机器人；支持 text/markdown/post/media 回复、在话题中回复和幂等键
+messages-resources-download	下载消息中的图片/文件；无法直接下载文件夹——请先使用 im files folder --recursive 展开，再下载其中的文件；用户/机器人
+messages-search	以用户或机器人身份跨聊天搜索消息（支持关键词、发送者、时间范围筛选）；按聊天/发送者/附件/时间筛选，支持通过 --page-all / --page-limit 自动分页，并通过批量 mget 和 chats batch_query 丰富结果
+messages-send	向聊天或私聊发送消息；用户/机器人；可向 chat-id 或 user-id 发送 text/markdown/post/media，支持幂等键
+threads-messages-list	列出线程中的消息；用户/机器人；接受 om_/omt_ 输入，可将消息 ID 解析为 thread_id，支持 --order asc/desc 排序和自动分页
+flag-create	为消息添加书签；仅限用户；默认添加消息层书签；使用 --flag-type feed 添加动态层书签（根据聊天模式自动检测 item_type）
+flag-cancel	取消（移除）书签。未提供 --flag-type 时，会尽力同时取消：移除消息层书签，并在可确定 chat_type 时移除动态层书签
+flag-list	列出书签；仅限用户；自动补充 feed 类型线程条目的消息内容；--page-all 受 --page-limit 限制（默认值为 20，最大值为 1000），且 has_more=true 表示结果不完整
+feed-shortcut-create	将聊天添加到用户的动态快捷方式；仅限用户；仅接受 oc_xxx 聊天 ID；每次调用最多批量处理 10 个；--head/--tail 控制插入顺序；部分失败时会返回 ok:false 记录
+feed-shortcut-remove	从用户的动态快捷方式中移除聊天；仅限用户；每次调用最多批量处理 10 个；移除不存在的快捷方式会以幂等方式成功；单项实际失败时会返回 ok:false 记录
+feed-shortcut-list	列出用户动态快捷方式的一页内容；仅限用户；第一页不传入 --page-token；默认输出会在 detail 下补充 CHAT 条目的信息；传入 --no-detail 可跳过额外查询和 im:chat:read 权限范围
+feed-group-list	列出调用者的动态分组（标签）；仅限用户；支持通过 --page-all 自动分页
+feed-group-list-item	列出动态分组（标签）中的动态卡片；仅限用户；根据 feed_id 解析 chat_name 并补充到每个条目；支持 --page-all 自动分页
+feed-group-query-item	按 ID 查找动态分组（标签）中的指定动态卡片；仅限用户；根据 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.join_requests

• list — 列出群的待审批入群申请（仅群主/管理员，user_access_token）。列出群的待处理入群申请。身份：仅支持 user（user_access_token）；调用方必须是群主或管理员。支持分页（page_size 为 1-100）；当 has_more == false 时停止——即使在最后一页也会返回 page_token，因此只要该字段存在就继续分页将永远不会终止。
• handle — 批量审批入群申请（approve/reject，仅群主/管理员，user_access_token）。批量批准或拒绝待处理的入群申请（1-50 项，按顺序处理）。身份：仅支持 user（user_access_token）；调用方必须是群主或管理员。results[] 的数量和顺序与 items[] 一致——请检查每项的 result（success / failed / already_handled）；退出码 0 不代表每项都成功。

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

• read_status — 批量查询当前用户对消息的已读状态。身份：仅支持 user（user_access_token）；最多接受 50 个消息 ID，并返回可读取的项目以及无效消息 ID。必读
• delete — 撤回消息。身份：支持 user 和 bot；对于 bot 调用，机器人必须在聊天中才能撤回群消息；要撤回其他用户发送的群消息，机器人必须是所有者、管理员或创建者；对于用户发起的 P2P 撤回，目标用户必须在机器人的可用范围内。
• forward — 转发消息。身份：支持 user 和 bot。
• merge_forward — 合并转发消息。身份：仅支持 bot（tenant_access_token）。
• read_users — 查询消息已读信息。身份：支持 user 和 bot；调用者必须仍在聊天中。用户可以查询自己在过去 7 天内发送的消息，而机器人只能查询自己在过去 7 天内发送的消息。必读
• patch — 更新已发送的消息卡片。更新应用发送的交互式消息卡片。身份：支持 user 和 bot；消息必须在过去 14 天内发送，且 content 必须是 JSON 序列化字符串，大小不超过 30 KB。必读
• 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 — 上传图片。身份：支持 user 和 bot；用户身份需要在 UAT 上具有 im:resource 范围。

files

• create — 上传文件。身份：支持 user 和 bot；用户身份需要在 UAT 上具有 im:resource 范围。

pins

• create — 固定消息。身份：支持 user 和 bot。
• delete — 移除固定消息。身份：支持 user 和 bot。
• list — 获取群内固定消息。身份：支持 user 和 bot。

feed.groups

• batch_add_item — 批量将信息流卡片添加到信息流分组。身份：仅支持 user（user_access_token）。必读
• batch_query — 批量查询信息流分组。身份：仅支持 user（user_access_token）。必读
• batch_remove_item — 批量从信息流分组中移除信息流卡片。身份：仅支持 user（user_access_token）。必读
• create — 创建信息流分组。身份：仅支持 user（user_access_token）。必读
• delete — 删除信息流分组。身份：仅支持 user（user_access_token）。必读
• update — 更新信息流分组。身份：仅支持 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
chat.join_requests.list	im:chat.membership_application:read
chat.join_requests.handle	im:chat.membership_application:write
+messages-read-status	user: im:message:readonly (recommended), im:message, or im:message:get_as_user
+message-read-users	user: im:message:readonly (recommended), im:message, im:message:basic, or im:message:get_as_user; bot: im:message:readonly
messages.read_status	im:message:readonly (recommended), im:message, or im:message:get_as_user
messages.delete	im:message:recall
messages.forward	im:message
messages.merge_forward	im:message
messages.read_users	user: im:message:readonly (recommended), im:message, im:message:basic, or im:message:get_as_user; bot: im:message:readonly
messages.patch	im:message:update
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
files.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