用途
lark-im 是飞书开放平台的即时通讯（IM）v1 技能，供 AI 智能体安装后调用飞书的群聊、消息与 Feed 相关能力。官方说明中明确：开始前必须先用 Read 工具读取 ../lark-shared/SKILL.md，其中包含认证与权限处理。
核心概念
- Message（消息）：聊天中的单条消息，用 message_id（om_xxx）标识，支持 text、post、image、file、audio、video、sticker、interactive（卡片）、share_chat、share_user、merge_forward 等类型。
- Chat（会话）：群聊或单聊，用 chat_id（oc_xxx）标识。
- Thread（话题）：消息下的回复串，用 thread_id（om_xxx 或 omt_xxx）标识。
- Reaction：消息上的表情回应。
- Flag：消息或话题上的书签。
- Feed Shortcut：固定在当前用户 Feed 侧栏的会话，用 feed_card_id 标识。
- Feed Group：Feed 列表中用于归组 Feed 卡片的标签，用 feed_group_id（ofg_xxx）标识，成员为 Feed 卡片，分 normal（成员显式管理）与 rule（成员按规则自动生成）两类。
资源关系为：Chat 下含 Message，Message 下含 Thread、Reaction、Resource（image/file/video/audio），Chat 下含 Member（user/bot）。
身份与令牌映射
--as user 表示用户身份，使用 user_access_token，以被授权的终端用户身份调用，权限同时取决于应用权限范围和该用户对目标会话/消息/资源的访问权。--as bot 表示机器人身份，使用 tenant_access_token，以应用机器人身份调用，行为取决于机器人的群成员身份、应用可见性、可用范围与机器人专属权限。同一个 IM 接口即使同时支持用户和机器人，令牌类型会改变操作者身份，可能一方成功而另一方因所有者/管理员状态、群成员身份、租户边界或应用可用范围而失败。
使用方式
官方推荐优先使用 Shortcut（高级封装，形式为 lark-cli im +<verb> [flags]）。使用原生 API 时，必须先运行 lark-cli schema im.<resource>.<method> 查看 --data / --params 参数结构，不要猜测字段格式。
主要 Shortcut 包括：+chat-create（创建群或话题群）、+chat-list（列出当前用户/机器人所在会话）、+chat-members-list（列出群成员）、+chat-messages-list（列出会话消息）、+chat-search（按关键词/成员搜索可见群）、+chat-update（更新群名称或描述）、+message-read-users（查询消息已读用户）、+messages-edit（编辑消息内容，仅机器人）、+messages-mget（按 ID 批量获取消息）、+messages-read-status（批量查询当前用户已读状态）、+messages-reply（回复消息）、+messages-resources-download（下载消息图片/文件）、+messages-search（跨会话搜索消息）、+messages-send（发送消息）、+threads-messages-list（列出话题消息）、+flag-create / +flag-cancel / +flag-list（书签）、+feed-shortcut-create / remove / list（Feed 快捷方式）、+feed-group-list / list-item / query-item（Feed 分组）。
原生 API 资源包括 chats（create/get/link/update）、chat.members（create/delete）、chat.user_setting（batch_query/batch_update）、chat.nickname（get/update/delete）、chat.join_requests（list/handle）、chat.managers（add_managers/delete_managers）、chat.moderation（get/update）、messages（read_status/delete/forward/merge_forward/read_users/patch）等。
主要能力细节
消息拉取类 Shortcut（+messages-mget、+chat-messages-list、+messages-search、+threads-messages-list）会自动附加 reactions 块以及被编辑消息的 update_time，无需单独调用 im.reactions.batch_query，可用 --no-reactions 退出。部分消息列表 Shortcut 支持 --concise 输出紧凑 Markdown。+chat-messages-list、+messages-mget、+threads-messages-list 支持 --download-resources，将符合条件的附件保存到 ./lark-im-resources/ 并在每条消息上增加 resources 数组，默认关闭，贴纸不可下载；文件夹是容器而非文件，其 file_key 不能直接下载，需先用 lark-cli im files folder --recursive --file-key <folder_key> --srctype message --srcid <message_id> 展开，再下载其中的文件。
发送/回复/更新互动卡片前，必须先读取 references/card/lark-im-card-create.md 并遵循其工作流，传给 --msg-type interactive --content 或 messages.patch --data 的卡片 JSON 必须是该工作流的输出，不能手写或复制卡片载荷。
音频消息 --audio 仅支持 Opus 音频文件（如 .opus、Ogg Opus .ogg）；mp3、wav 等非 Opus 音频需先转码或改用 --file 作为附件发送。
发送从飞书文档获取的内容时，先用 --doc-format im-markdown 获取，再用 --markdown 格式发送；若文档含 type="user" 的 cite 标签，应保持原样不要剥离。
Flag 分两层：消息层 flag（ItemTypeDefault, FlagTypeMessage）与 Feed 层 flag（ItemTypeThread/ItemTypeMsgThread, FlagTypeFeed）。Feed Shortcut 与 Flag 不同：Flag 是消息/话题上的书签，Feed Shortcut 是用户 Feed 侧栏中的条目。仅 CHAT 类型（feed_card_id 为 oc_xxx）通过 OpenAPI 暴露，创建/移除/列表均为用户身份，单次批量上限 10。
适用场景
适用于需要通过 AI 智能体操作飞书会话与消息的场景，例如发送与回复消息、检索与搜索消息、管理群聊与群成员、管理群管理员与发言权限、处理入群申请、查询已读状态、下载消息附件、以及管理书签和 Feed 相关设置。
限制与注意事项
使用前必须先读取 ../lark-shared/SKILL.md；原生 API 必须先查看 schema。调用是否成功受身份类型、群成员身份、所有者/管理员状态、租户边界与应用可用范围约束。卡片消息（interactive）目前不支持事件订阅中的紧凑转换，会返回原始事件数据并向 stderr 打印提示。文件夹 file_key 不能直接下载。音频消息仅支持 Opus。本资料未提供收费、价格等商业信息。