lark-im

im (v1)

关键 — 开始前 MUST 先用 Read 工具读取 ../lark-shared/SKILL.md，其中包含认证、权限处理

核心概念

• 消息（Message）: 聊天中的单条消息，由 message_id（om_xxx）标识。支持类型：文本、富文本、图片、文件、音频、视频、贴纸、交互卡片（interactive）、分享聊天、分享用户、合并转发等。
• 聊天（Chat）: 群聊或单聊会话，由 chat_id（oc_xxx）标识。
• 话题（Thread）: 消息下的回复话题，由 thread_id（om_xxx 或 omt_xxx）标识。
• 表情回复（Reaction）: 消息上的表情回复。
• 标记（Flag）: 消息或话题的书签。
• Feed 置顶（Feed Shortcut）: 置顶到当前用户 Feed 侧边栏的聊天，由 feed_card_id（对于 CHAT 类型为 oc_xxx 的 open_chat_id）标识。
• Feed 分组（Feed Group）: 对 Feed 列表中的卡片进行分组的标签，由 feed_group_id（ofg_xxx）标识。成员为 Feed 卡片，每个卡片由 feed_id + feed_type 标识。两种类型：normal（成员显式管理）和 rule（成员根据规则自动派生）。

资源关系

Chat (oc_xxx)
├── Message (om_xxx)
│   ├── Thread (回复话题)
│   ├── Reaction (表情)
│   └── Resource (图片/文件/视频/音频)
└── Member (用户/机器人)

重要说明

身份与令牌映射

• --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）没有发送者名称——这是正常情况，不是错误。

默认消息丰富（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 将原始文件作为附件发送。

将文档内容作为消息发送

当将从 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 可包含单聊（仅用户）；用户/机器人；支持排序、分页、--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，格式化发送者名称，展开话题回复
+messages-reply	回复消息（支持话题回复）；用户/机器人；支持文本/markdown/富文本/媒体回复、回复到话题、幂等键
+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	列出话题中的消息；用户/机器人；接受 om_/omt_ 输入，将消息 ID 解析为 thread_id，支持排序/分页
+flag-create	在消息上创建书签；仅用户；默认为消息层标记；使用 --flag-type feed 创建 Feed 层标记（item_type 根据聊天模式自动检测）
+flag-cancel	取消（移除）书签。当未指定 --flag-type 时，尽力双重取消：移除消息层，并在可确定 chat_type 时移除 Feed 层
+flag-list	列出书签；仅用户；自动丰富 Feed 类型话题条目的消息内容；--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