npm - pi-feishu-cli - Versions diffs - 0.1.0 - Mend

pi-feishu-cli 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (407) hide show

package/skills/lark-drive/references/lark-drive-version-revert.md ADDED Viewed

@@ -0,0 +1,198 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <link rel="icon" href="favicon.ico" />
+  <title></title>
+  <style>
+      * {
+          box-sizing: border-box;
+          padding: 0;
+          margin: 0;
+      }
+      .open-platform-wrapper {
+          display: flex;
+          flex-direction: column;
+          align-items: center;
+          justify-content: center;
+          height: 100vh;
+          background-color: #ffffff;
+      }
+      .open-platform-icon {
+          width: 120px;
+          height: 120px;
+          display: block;
+      }
+      .open-platform-desc {
+          margin-top: 16px;
+          line-height: 22px;
+          font-size: 14px;
+          color: #646a73;
+          text-align: center
+      }
+      .open-platform-back {
+          border-radius: 6px;
+          font-size: 14px;
+          height: 32px;
+          line-height: 22px;
+          min-width: 80px;
+          padding: 4px 11px;
+          text-align: center;
+          text-decoration: none;
+          touch-action: manipulation;
+          transition: color .1s ease-in, background-color .1s ease-in, border-color .1s ease-in, width .2s ease-in;
+          user-select: none;
+          white-space: nowrap;
+          background: #1456f0;
+          border: 1px solid #1456f0;
+          color: #ffffff;
+          margin-top: 16px;
+      }
+  </style>
+</head>
+<body>
+<div class="open-platform-wrapper">
+  <img class="open-platform-icon"
+       src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTIwIiBoZWlnaHQ9IjEyMCIgdmlld0JveD0iMCAwIDEyMCAxMjAiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZD0iTTEyLjkxMyA1NS4yNDRjLTUuNjMyIDIuOTUtOC4yNDYgNi4yODQtOC4yNDYgOS40NHY5LjcyYzAtMy4xNTYgMi42MTQtNi40OSA4LjI0Ni05LjQ0di05LjcyWm05NC4xNjMtMTIuMDg0di05LjcyNmM1LjkzNC0zLjE5IDguOTgxLTYuODkxIDguOTgxLTEwLjcyNXY5LjcyYzAgMy44NC0zLjA0NyA3LjU0My04Ljk4MSAxMC43MzJaIiBmaWxsPSIjMEMyOTZFIi8+PHBhdGggZD0iTTYwLjIyOSAxOS4wNTkgNDguNzMgNDkuOTIyIDYwLjM2NSA3Mi45MmwtOC40NzQgMjMuODczSDE2LjkyM2E0IDQgMCAwIDEtNC00VjIzLjA2YTQgNCAwIDAgMSA0LTRINjAuMjNaIiBmaWxsPSIjQkJCRkM0IiBmaWxsLW9wYWNpdHk9Ii40NSIvPjxwYXRoIGQ9Ik03MS40MDggMTkuMDU5IDYwLjAxMyA0OS45MjIgNzEuNDYgNzIuOTJsLTguMzI1IDIzLjg3M2gzOS45NDNhNCA0IDAgMCAwIDQtNFYyMy4wNmE0IDQgMCAwIDAtNC00aC0zMS42N1oiIGZpbGw9IiNCQkJGQzQiIGZpbGwtb3BhY2l0eT0iLjQ1Ii8+PHBhdGggZD0iTTIxLjkyMyAyNi4xYTIgMiAwIDEgMSAwIDQgMiAyIDAgMCAxIDAtNFptMyAyYTMgMyAwIDEgMC02IDAgMyAzIDAgMCAwIDYgMFptNi45MTUtMmEyIDIgMCAxIDEgMCA0IDIgMiAwIDAgMSAwLTRabTMgMmEzIDMgMCAxIDAtNiAwIDMgMyAwIDAgMCA2IDBabS0xNS43NjMgNy4zOTRhLjUuNSAwIDAgMSAuNS0uNWgzMS41ODFhLjUuNSAwIDAgMSAwIDFIMTkuNTc1YS41LjUgMCAwIDEtLjUtLjVabTQ4LjQ3NyAwYS41LjUgMCAwIDEgLjUtLjVoMzIuNDY1YS41LjUgMCAwIDEgMCAxSDY4LjA1MmEuNS41IDAgMCAxLS41LS41WiIgZmlsbD0iIzhGOTU5RSIvPjxwYXRoIGQ9Ik05OCAxMTFjOS45NDEgMCAxOC04LjA1OSAxOC0xOHMtOC4wNTktMTgtMTgtMThjLTkuOTQyIDAtMTggOC4wNTktMTggMThzOC4wNTggMTggMTggMThaIiBmaWxsPSIjRjgwIi8+PHBhdGggZD0iTTk3LjE4MSA4NC44MThhLjgxOC44MTggMCAwIDAtLjgxOC44MTl2OS44MThjMCAuNDUyLjM2Ni44MTguODE4LjgxOGgxLjYzN2EuODE4LjgxOCAwIDAgMCAuODE4LS44MTh2LTkuODE5YS44MTguODE4IDAgMCAwLS44MTgtLjgxOEg5Ny4xOFptMCAxMy4wOTJhLjgxOC44MTggMCAwIDAtLjgxOC44MTh2MS42MzZjMCAuNDUyLjM2Ni44MTguODE4LjgxOGgxLjYzN2EuODE4LjgxOCAwIDAgMCAuODE4LS44MTh2LTEuNjM2YS44MTguODE4IDAgMCAwLS44MTgtLjgxOUg5Ny4xOFoiIGZpbGw9IiNmZmYiLz48cGF0aCBkPSJNNC4wMjcgODUuMzFjMi40OSA1LjUxIDE0Ljc3IDkuOTQgNDEuNDUgOS45M3Y5LjcyMWMtMjYuNjguMDEtMzguOTYtNC40Mi00MS40NS05Ljkzdi05LjcyWm04NC44MS0yNy4yN2MxNy41Mi0yLjY5IDI1LjgwNy03LjAyNiAyNy4yLTExLjcxdjkuNzJjLS4zMyA0LjY3LTkuNjggOS4wMi0yNy4yIDExLjcxdi05LjcyWiIgZmlsbD0iIzMzNzBGRiIvPjxwYXRoIGQ9Ik04OS4yMzcgMTMuMDFjMTguMDU4IDAgMjYuOCAzLjI1IDI2LjggOS43MnY5LjcyYzAtNi40Ny04Ljc0Mi05LjcyLTI2LjgtOS43MnYtOS43MlptLTg0LjU3IDUxLjdjMCA2LjYgMTEuMzcgMTIuNDUgMzAuNDcgMTIuNDR2OS43MmMtMTkuMSAwLTMwLjQ3LTUuODQtMzAuNDctMTIuNDR2LTkuNzJaIiBmaWxsPSIjMDBENkI5Ii8+PC9zdmc+"
+       alt="">
+  <div class="open-platform-desc">The page does not exist.</div>
+  <a class="open-platform-back" href="/">Go to homepage</a>
+</div>
+<script>window.gfdatav1={"env":"prod","ver":"1.0.0.13","canary":0,"garrModules":null,"envName":"prod","region":"CN","idc":"lf","webServerCodeType":"DeployServerlessWebServer","runtime":"node","extra":{"canaryType":null}}</script><script>
+  function parseQueryString(queryString) {
+    // 移除开头的 "?"
+    if (queryString.charAt(0) === '?') {
+      queryString = queryString.substring(1);
+    }
+    var params = {};
+    if (!queryString) return params;
+    // 分割参数对
+    var paramPairs = queryString.split('&');
+    for (var i = 0; i < paramPairs.length; i++) {
+      var paramPair = paramPairs[i].split('=');
+      var key = decodeURIComponent(paramPair[0]);
+      var value = paramPair.length > 1 ? decodeURIComponent(paramPair[1]) : '';
+      // 处理重复参数（转为数组）
+      if (params[key] === undefined) {
+        params[key] = value;
+      } else if (!Array.isArray(params[key])) {
+        params[key] = [params[key], value];
+      } else {
+        params[key].push(value);
+      }
+    }
+    return params;
+  }
+  function getLocale() {
+    var zhLang = 'zh-CN';
+    var enLang = 'en-US';
+    var queryLang = parseQueryString(window.location.search).lang;
+    var cookieLang = getCookieLocale();
+    var lang = enLang;
+    <!--从cookie中取值-->
+    function getCookieLocale() {
+      var locale = '';
+      var cookies = document.cookie.split('; ');
+      var loclaeKey = 'open_locale';
+      for (var i = 0; i < cookies.length; i++) {
+        var cookie = cookies[i].trim();
+        var cookieArr = cookie.split('=');
+        if (cookieArr[0] === loclaeKey) {
+          locale = cookieArr[1];
+          break;
+        }
+      }
+      return locale;
+    }
+    function setLocaleCookie(lang) {
+      var date = new Date();
+      // 300天到期
+      date.setTime(date.getTime() + (300 * 24 * 60 * 60 * 1000));
+      var expires = 'expires=' + date.toUTCString();
+      document.cookie = 'open_locale=' + lang + '; ' + expires + '; path=/;';
+    }
+    // 获取浏览器默认语言
+    if (navigator.language.indexOf('en') !== -1) {
+      lang = enLang;
+    } else if (navigator.language.indexOf('zh') !== -1) {
+      lang = zhLang;
+    }
+    if (cookieLang === enLang) {
+      lang = enLang;
+    } else if (cookieLang === zhLang) {
+      lang = zhLang;
+    }
+    if (queryLang === enLang) {
+      lang = enLang;
+    } else if (queryLang === zhLang) {
+      lang = zhLang;
+    }
+    // 设置cookie
+    setLocaleCookie(lang);
+    return lang;
+  }
+  // 根据域名获取当前brand
+  function isLarkDomain() {
+    var defaultBrandMap = {
+      lark: ['larksuite'],
+      feishu: ['feishu', 'larkoffice', 'larkenterprise'],
+    };
+    const { hostname } = window.location;
+    if (defaultBrandMap.feishu.some((item) => hostname.includes(item))) {
+      return false;
+    }
+    if (defaultBrandMap.lark.some((item) => hostname.includes(item))) {
+      return true;
+    }
+    if (window.domainBrand) {
+      return window.domainBrand === 'lark';
+    }
+    return false;
+  }
+  var isLarkBrand = isLarkDomain();
+  var config = {
+    'zh-CN': {
+      'desc': '抱歉，您访问的页面不存在',
+      'back': '返回首页',
+      'title': (isLarkBrand ? 'Lark' : '飞书') + '开放平台',
+    },
+    'en-US': {
+      'desc': 'The page does not exist.',
+      'back': 'Go to homepage',
+      'title': (isLarkBrand ? 'Lark': 'Feishu') + ' Open Platform',
+    },
+  };
+  var locale = getLocale();
+  var descObj = document.querySelector('.open-platform-desc');
+  var backObj = document.querySelector('.open-platform-back');
+  descObj.innerHTML = config[locale].desc;
+  backObj.innerHTML = config[locale].back;
+  document.title = config[locale].title;
+</script>
+</body>
+</html>

package/skills/lark-event/SKILL.md ADDED Viewed

@@ -0,0 +1,145 @@
+---
+name: lark-event
+version: 1.0.0
+description: "Lark/Feishu real-time event listening / subscribing / consuming: stream events as NDJSON via `lark-cli event consume <EventKey>` (covers IM message receive, reactions, chat member changes, etc.). Use for Lark bots, real-time message processing, long-running subscribers, streaming webhook/push handlers. Supports `--max-events` / `--timeout` bounded runs and a stderr ready-marker contract — designed for AI agents running as subprocesses."
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli event --help"
+---
+# Lark Events
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) first for authentication, `--as user/bot` switching, `Permission denied` handling, and safety rules.
+## Core commands
+| Command | Purpose |
+|------|------|
+| `lark-cli event list [--json]` | List all subscribable EventKeys |
+| `lark-cli event schema <EventKey> [--json]` | Show an EventKey's params and output schema |
+| `lark-cli event consume <EventKey> [flags]` | Blocking consume; events → stdout NDJSON |
+| `lark-cli event status [--json] [--fail-on-orphan]` | Inspect the local bus daemon status |
+| `lark-cli event stop [--all] [--force]` | Stop the bus daemon |
+## Common flags
+| Flag | Description |
+|---|---|
+| `--param key=value` / `-p` | Business params (repeatable; comma-separated for multi-value). Unknown keys fail with valid names listed inline |
+| `--jq <expr>` | jq expression to filter / transform each event; empty output skips the event |
+| `--max-events N` | Exit after N events. Default 0 = unlimited |
+| `--timeout D` | Exit after duration D (e.g. `30s`, `2m`). Default 0 = no timeout. Whichever of `--max-events` / `--timeout` fires first wins |
+| `--output-dir <dir>` | Write each event as a file (relative paths only; prevents traversal) |
+| `--quiet` | Suppress stderr diagnostics. **AI should not use this** — it silences the ready marker |
+| `--as user\|bot\|auto` | Identity for the session (see lark-shared) |
+## Examples
+```bash
+# Default: stream every event for the key (no filter, no projection)
+lark-cli event consume im.message.receive_v1 --as bot
+# Grab one sample event to inspect payload shape
+lark-cli event consume im.message.receive_v1 --max-events 1 --timeout 30s --as bot
+# Run for 10 minutes then auto-exit
+lark-cli event consume im.message.receive_v1 --timeout 10m --as bot
+# Consume multiple EventKeys concurrently (one shape per process, no dispatcher)
+lark-cli event consume im.message.receive_v1          --as bot > receive.ndjson &
+lark-cli event consume im.message.reaction.created_v1 --as bot > reaction.ndjson &
+wait
+```
+## Call flow
+1. `lark-cli event list --json` → pick a legal key
+2. `lark-cli event schema <key> --json` → read `resolved_output_schema` + `jq_root_path` to determine field paths
+3. `lark-cli event consume <key> [--jq '<expr>']` → consume
+## Subprocess contract
+### Ready marker
+`event consume`'s stderr emits a fixed line `[event] ready event_key=<key>`. **Parent processes should block on stderr until this line appears, then start reading stdout.** Do not fall back to `sleep`.
+### stdin EOF = graceful exit
+`event consume` treats stdin close as a shutdown signal (wired for AI subprocess callers). `< /dev/null` / `nohup` / systemd's default `StandardInput=null` will cause an immediate graceful exit (stderr `reason: signal`). To keep running:
+- Feed stdin a source that never EOFs: `< <(tail -f /dev/null)`
+- Or run bounded: `--max-events N` / `--timeout D`
+### Exit codes & reason
+On exit, the last stderr line is `[event] exited — received N event(s) in Xs (reason: ...)`.
+| exit code | reason | Trigger |
+|---|---|---|
+| 0 | `reason: limit` | `--max-events` reached |
+| 0 | `reason: timeout` | `--timeout` reached |
+| 0 | `reason: signal` | Ctrl+C / SIGTERM / stdin EOF |
+| non-0 | `Error: ...` (no `exited` line) | Startup / runtime failure (permissions, network, params, config) |
+Orchestrators should treat `reason: limit/timeout/signal` (all exit 0) as "business completion" and non-zero as "failure".
+### Never `kill -9`
+**Avoid `kill -9` on consume processes**: for EventKeys with a **PreConsume hook** (those that register server-side subscriptions via OAPI), `kill -9` skips the OAPI unsubscribe and leaks server-side subscriptions (symptoms: "subscription already exists" on restart, duplicate event delivery). Prefer SIGTERM or closing stdin.
+### One consume, one EventKey (multi-key = multi-shell)
+The command takes exactly one positional argument; `k1,k2` and wildcards are unsupported. Listening to N keys means N subprocesses — this is **intentional**:
+- One shape per process stdout; no dispatcher logic required in the AI
+- Fault isolation (one key failing doesn't affect others)
+- Independent `--as` / `--jq` / `--max-events` / `--timeout` per key
+All N consumers share a single bus daemon (UDS local IPC), so the overhead is small
+## Writing jq via schema
+`event schema <key> --json` is the source of truth for writing `--jq`. Four things to look at:
+**(1) Where fields start** — see `jq_root_path`
+- Value `"."` → fields are at the top level, write `.chat_id`
+- Value `".event"` → fields are inside a V2 envelope, write `.event.chat_id`
+**(2) Field list and types** — see `resolved_output_schema.properties.<name>`
+Each field carries `type` / `description`, and some also have `format`. Snippet (from `event schema im.message.receive_v1 --json`):
+```json
+{
+  "chat_id":     {"type":"string", "format":"chat_id",      "description":"Chat ID, prefixed with oc_"},
+  "sender_id":   {"type":"string", "format":"open_id",      "description":"Sender open_id, prefixed with ou_"},
+  "create_time": {"type":"string", "format":"timestamp_ms", "description":"Send time as ms-epoch string"}
+}
+```
+**(3) Field semantics** — see the `format` tag
+Lark-defined semantic tags (**not** JSON Schema's standard `format`). Common values: `open_id` / `chat_id` / `message_id` / `timestamp_ms` / `email`. Purpose: distinguish "same string type, different meanings" fields so you can reverse-lookup via API or convert formats.
+**(4) Decoded state** — read the field's `description`
+`event consume` runs Process hooks that may pre-decode some payload fields (flattening V2 envelopes, rendering `.content` to plain text, etc.) — behavior differs from raw OAPI. **Always read the field's `description` before writing jq**, especially for generic field names like `content` / `data` / `body` / `payload`.
+**Why it matters**: blindly applying `fromjson` to an already-decoded text field makes jq error on every event and silently drop it — the consumer looks alive but emits nothing, with only a single `WARN` line buried on stderr. (This is the general behavior: any jq runtime error skips the event with a one-line WARN; the loop does not abort.)
+**Don't shortcut the schema**: when projecting `event schema --json` with jq, do not strip `.description` from `properties` — that's the field that tells you whether a field is already decoded. Dump the full property objects, not just keys.
+---
+**Aside**: `--param`'s valid parameters also live in the schema — the `params` section lists `name` / `type` / `required` / `enum` / `default` / `description`; **section missing = this key accepts no `--param`**.
+## Topic index
+| Topic | Reference | Coverage |
+|---|---|---|
+| IM | [`references/lark-event-im.md`](references/lark-event-im.md) | Catalog of 11 IM EventKeys + shape notes (flat vs V2 envelope) + `im.message.receive_v1` field gotchas (`sender_id` is open_id only; `.content` is plain text except for `interactive` cards) + common jq recipes (filter by chat_type / message_type / sender) |

package/skills/lark-event/references/lark-event-im.md ADDED Viewed

@@ -0,0 +1,86 @@
+# IM Events
+> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
+>
+> **Heads-up for AI agents**: this key's `.content` is **NOT** the raw OAPI payload shape your training data may suggest. `lark-cli` runs a Process hook (`convertlib`) that flattens the V2 envelope and **pre-renders** `.content` to human-readable text for `text` / `post` / `image` / `file` / `audio` / etc. Only `interactive` (cards) keeps the raw JSON string. Don't blindly `fromjson`.
+## Key catalog (11)
+| EventKey | Purpose |
+|---|---|
+| `im.message.receive_v1` | Receive IM messages |
+| `im.message.message_read_v1` | User read a bot's **p2p** message (group messages don't fire this) |
+| `im.message.reaction.created_v1` | Reaction added to a message |
+| `im.message.reaction.deleted_v1` | Reaction removed from a message |
+| `im.chat.updated_v1` | Chat settings changed (owner, avatar, name, permissions, etc.) |
+| `im.chat.disbanded_v1` | Chat disbanded |
+| `im.chat.member.bot.added_v1` | Bot added to a chat |
+| `im.chat.member.bot.deleted_v1` | Bot removed from a chat |
+| `im.chat.member.user.added_v1` | User joined a chat (including topic chats) |
+| `im.chat.member.user.deleted_v1` | User left voluntarily **or** was removed |
+| `im.chat.member.user.withdrawn_v1` | Pending chat invite withdrawn (inviter canceled; user never actually joined) |
+> **Shape**: `im.message.receive_v1` is the only flat key (fields at `.xxx`); the other 10 are V2-enveloped (fields at `.event.xxx`).
+## Gotchas (`im.message.receive_v1`)
+**sender_id is open_id only**: the event payload carries no display name. Call the contact API separately if you need the sender's name.
+**`.content` shape depends on `message_type`** (this key uses a flat Custom schema; see [`events/im/message_receive.go`](../../../events/im/message_receive.go)):
+| message_type | `.content` shape | How to read |
+|---|---|---|
+| `text` / `post` / `image` / `file` / `audio` / `sticker` / `share_chat` / `share_user` / `media` / `system` | Human-readable text (convertlib-processed; `@mentions` resolved to display names) | Use `.content` directly |
+| `interactive` (card) | Raw card JSON string (structured actions can't be losslessly flattened) | `.content \| fromjson` to get the card object |
+**Do not blindly `fromjson`** — for non-interactive messages it fails with `jq: fromjson cannot be applied to "hello"` because `.content` isn't JSON-encoded.
+```bash
+# text: .content is plain text — no fromjson needed
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.message_type=="text") | .content'
+# interactive: .content is a JSON string — fromjson to parse
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.message_type=="interactive") | .content | fromjson'
+```
+## On-demand filter recipes
+> **Default = no `--jq`.** Run `lark-cli event consume im.message.receive_v1 --as bot` to see every message. The recipes below are only for cases where the user has asked to narrow the stream.
+### 1. Filter by chat type (p2p vs group)
+`chat_type` is an enum with values `p2p` / `group`.
+```bash
+# p2p only (direct messages)
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.chat_type=="p2p") | {from: .sender_id, msg: .content}'
+# group only
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.chat_type=="group") | {chat: .chat_id, from: .sender_id, msg: .content}'
+```
+### 2. Filter by message type
+```bash
+# text only — content is plain human-readable text
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.message_type=="text") | .content'
+# interactive (card) only — parse the card body
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.message_type=="interactive") | .content | fromjson'
+```
+### 3. Filter by sender (only one user's messages)
+```bash
+# example: only messages from the given open_id
+lark-cli event consume im.message.receive_v1 --as bot\
+  --jq 'select(.sender_id=="ou_xxxxxxxxxxxxxxxxxxxxxxxxxx") | {msg_id: .message_id, text: .content}'
+```
+Get your own open_id via `lark-cli contact +get-user --as user`; other users' via `lark-cli contact +search-user`.

package/skills/lark-im/SKILL.md ADDED Viewed

@@ -0,0 +1,162 @@
+---
+name: lark-im
+version: 1.0.0
+description: "飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件（支持大文件分片下载）、管理表情回复。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据时使用。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli im --help"
+---
+# im (v1)
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+## Core Concepts
+- **Message**: A single message in a chat, identified by `message_id` (om_xxx). Supports types: text, post, image, file, audio, video, sticker, interactive (card), share_chat, share_user, merge_forward, etc.
+- **Chat**: A group chat or P2P conversation, identified by `chat_id` (oc_xxx).
+- **Thread**: A reply thread under a message, identified by `thread_id` (om_xxx or omt_xxx).
+- **Reaction**: An emoji reaction on a message.
+- **Flag**: A bookmark on a message or thread.
+## Resource Relationships
+```
+Chat (oc_xxx)
+├── Message (om_xxx)
+│   ├── Thread (reply thread)
+│   ├── Reaction (emoji)
+│   └── Resource (image / file / video / audio)
+└── Member (user / bot)
+```
+## Important Notes
+### Identity and Token Mapping
+- `--as user` means **user identity** and uses `user_access_token`. Calls run as the authorized end user, so permissions depend on both the app scopes and that user's own access to the target chat/message/resource.
+- `--as bot` means **bot identity** and uses `tenant_access_token`. Calls run as the app bot, so behavior depends on the bot's membership, app visibility, availability range, and bot-specific scopes.
+- If an IM API says it supports both `user` and `bot`, the token type changes who the operator is. The same API can succeed with one identity and fail with the other because owner/admin status, chat membership, tenant boundary, or app availability are checked against the current caller.
+### Sender Name Resolution with Bot Identity
+When using bot identity (`--as bot`) to fetch messages (e.g. `+chat-messages-list`, `+threads-messages-list`, `+messages-mget`), sender names may not be resolved (shown as open_id instead of display name). This happens when the bot cannot access the user's contact info.
+**Root cause**: The bot's app visibility settings do not include the message sender, so the contact API returns no name.
+**Solution**: Check the app's visibility settings in the Lark Developer Console — ensure the app's visible range covers the users whose names need to be resolved. Alternatively, use `--as user` to fetch messages with user identity, which typically has broader contact access.
+### Card Messages (Interactive)
+Card messages (`interactive` type) are not yet supported for compact conversion in event subscriptions. The raw event data will be returned instead, with a hint printed to stderr.
+### Flag Types
+Flags support two layers:
+- **Message-layer flag**: `(ItemTypeDefault, FlagTypeMessage)` — regular message bookmark
+- **Feed-layer flag**: `(ItemTypeThread/ItemTypeMsgThread, FlagTypeFeed)` — thread as feed-layer bookmark
+Item types for feed-layer flags:
+- **ItemTypeThread** (4) = thread in a topic-style chat
+- **ItemTypeMsgThread** (11) = thread in a regular chat
+## Shortcuts（推荐优先使用）
+Shortcut 是对常用操作的高级封装（`lark-cli im +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+| Shortcut | 说明 |
+|----------|------|
+| [`+chat-create`](references/lark-im-chat-create.md) | Create a group chat or topic chat; user/bot; --chat-mode group|topic; private/public; invites users/bots; optionally sets bot manager |
+| [`+chat-list`](references/lark-im-chat-list.md) | List groups the current user/bot is a member of; user/bot; supports sorting, pagination, and --exclude-muted (user identity only) |
+| [`+chat-messages-list`](references/lark-im-chat-messages-list.md) | List messages in a chat or P2P conversation; user/bot; accepts --chat-id or --user-id, resolves P2P chat_id, supports time range/sort/pagination |
+| [`+chat-search`](references/lark-im-chat-search.md) | Search visible group chats by --query keyword and/or --member-ids; user/bot; e.g. look up chat_id by group name; supports type filters, sorting, pagination, and --exclude-muted (user identity only) |
+| [`+chat-update`](references/lark-im-chat-update.md) | Update group chat name or description; user/bot; updates a chat's name or description |
+| [`+messages-mget`](references/lark-im-messages-mget.md) | Batch get messages by IDs; user/bot; fetches up to 50 om_ message IDs, formats sender names, expands thread replies |
+| [`+messages-reply`](references/lark-im-messages-reply.md) | Reply to a message (supports thread replies); user/bot; supports text/markdown/post/media replies, reply-in-thread, idempotency key |
+| [`+messages-resources-download`](references/lark-im-messages-resources-download.md) | Download images/files from a message; user/bot; supports automatic chunked download for large files (8MB chunks), auto-detects file extension from Content-Type |
+| [`+messages-search`](references/lark-im-messages-search.md) | Search messages across chats (supports keyword, sender, time range filters) with user identity; user-only; filters by chat/sender/attachment/time, supports auto-pagination via `--page-all` / `--page-limit`, enriches results via batched mget and chats batch_query |
+| [`+messages-send`](references/lark-im-messages-send.md) | Send a message to a chat or direct message; user/bot; sends to chat-id or user-id with text/markdown/post/media, supports idempotency key |
+| [`+threads-messages-list`](references/lark-im-threads-messages-list.md) | List messages in a thread; user/bot; accepts om_/omt_ input, resolves message IDs to thread_id, supports sort/pagination |
+| [`+flag-create`](references/lark-im-flag-create.md) | Create a bookmark on a message or thread; user-only; defaults to message-layer flag; feed-layer flag requires explicit --item-type + --flag-type |
+| [`+flag-cancel`](references/lark-im-flag-cancel.md) | Cancel (remove) a bookmark. When no --flag-type is given, checks if the message is a thread root message; if so, cancels both message and feed layers |
+| [`+flag-list`](references/lark-im-flag-list.md) | List bookmarks; user-only; auto-enriches feed-type thread entries with message content; supports `--page-all` auto-pagination |
+## API Resources
+```bash
+lark-cli schema im.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli im <resource> <method> [flags] # 调用 API
+```
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+### chats
+  - `create` — 创建群。Identity: `bot` only (`tenant_access_token`).
+  - `get` — 获取群信息。Identity: supports `user` and `bot`; the caller must be in the target chat to get full details, and must belong to the same tenant for internal chats.
+  - `link` — 获取群分享链接。Identity: supports `user` and `bot`; the caller must be in the target chat, must be an owner or admin when chat sharing is restricted to owners/admins, and must belong to the same tenant for internal chats.
+  - `update` — 更新群信息。Identity: supports `user` and `bot`.
+### chat.members
+  - `bots` — 获取群内机器人列表。Identity: supports `user` and `bot`; the caller must be in the target chat and must belong to the same tenant for internal chats.
+  - `create` — 将用户或机器人拉入群聊。Identity: supports `user` and `bot`; the caller must be in the target chat; for `bot` calls, added users must be within the app's availability; for internal chats the operator must belong to the same tenant; if only owners/admins can add members, the caller must be an owner/admin, or a chat-creator bot with `im:chat:operate_as_owner`.
+  - `delete` — 将用户或机器人移出群聊。Identity: supports `user` and `bot`; only group owner, admin, or creator bot can remove others; max 50 users or 5 bots per request.
+  - `get` — 获取群成员列表。Identity: supports `user` and `bot`; the caller must be in the target chat and must belong to the same tenant for internal chats.
+### messages
+  - `delete` — 撤回消息。Identity: supports `user` and `bot`; for `bot` calls, the bot must be in the chat to revoke group messages; to revoke another user's group message, the bot must be the owner, an admin, or the creator; for user P2P recalls, the target user must be within the bot's availability.
+  - `forward` — 转发消息。Identity: supports `user` and `bot`.
+  - `merge_forward` — 合并转发消息。Identity: `bot` only (`tenant_access_token`).
+  - `read_users` — 查询消息已读信息。Identity: `bot` only (`tenant_access_token`); the bot must be in the chat, and can only query read status for messages it sent within the last 7 days.
+### reactions
+  - `batch_query` — 批量获取消息表情。Identity: supports `user` and `bot`.[Must-read](references/lark-im-reactions.md)
+  - `create` — 添加消息表情回复。Identity: supports `user` and `bot`; the caller must be in the conversation that contains the message.[Must-read](references/lark-im-reactions.md)
+  - `delete` — 删除消息表情回复。Identity: supports `user` and `bot`; the caller must be in the conversation that contains the message, and can only delete reactions added by itself.[Must-read](references/lark-im-reactions.md)
+  - `list` — 获取消息表情回复。Identity: supports `user` and `bot`; the caller must be in the conversation that contains the message.[Must-read](references/lark-im-reactions.md)
+### threads
+  - `forward` — 转发话题。Identity: supports `user` and `bot`.
+### images
+  - `create` — 上传图片。Identity: `bot` only (`tenant_access_token`).
+### pins
+  - `create` — Pin 消息。Identity: supports `user` and `bot`.
+  - `delete` — 移除 Pin 消息。Identity: supports `user` and `bot`.
+  - `list` — 获取群内 Pin 消息。Identity: supports `user` and `bot`.
+## 权限表
+| 方法 | 所需 scope |
+|------|-----------|
+| `chats.create` | `im:chat:create` |
+| `chats.get` | `im:chat:read` |
+| `chats.link` | `im:chat:read` |
+| `chats.update` | `im:chat:update` |
+| `chat.members.bots` | `im:chat.members:read` |
+| `chat.members.create` | `im:chat.members:write_only` |
+| `chat.members.delete` | `im:chat.members:write_only` |
+| `chat.members.get` | `im:chat.members:read` |
+| `messages.delete` | `im:message:recall` |
+| `messages.forward` | `im:message` |
+| `messages.merge_forward` | `im:message` |
+| `messages.read_users` | `im:message:readonly` |
+| `threads.forward` | `im:message` |
+| `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` |
+| `images.create` | `im:resource` |
+| `pins.create` | `im:message.pins:write_only` |
+| `pins.delete` | `im:message.pins:write_only` |
+| `pins.list` | `im:message.pins:read` |