pi-feishu-cli 0.1.0

package/skills/lark-im/references/lark-im-chat-create.md

@@ -0,0 +1,162 @@
+# im +chat-create
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Create a group chat. Supports both user identity (`--as user`) and bot identity (`--as bot`). You can specify the group name, description, members (users/bots), owner, chat type (private/public), and group mode. Set `--chat-mode topic` to create a topic chat.
+
+This skill maps to the shortcut: `lark-cli im +chat-create` (internally calls `POST /open-apis/im/v1/chats`).
+
+- `--as bot` requires the `im:chat:create` scope.
+- `--as user` requires the `im:chat:create_by_user` scope.
+
+## Commands
+
+```bash
+# Create a private group (default)
+lark-cli im +chat-create --name "My Group"
+
+# Create a public group (name is required and must be at least 2 characters)
+lark-cli im +chat-create --name "Public Group" --type public
+
+# Create a topic chat
+lark-cli im +chat-create --name "Topic Group" --chat-mode topic
+
+# Specify the group owner
+lark-cli im +chat-create --name "My Group" --owner ou_xxx
+
+# Invite user members (comma-separated open_ids, up to 50)
+lark-cli im +chat-create --name "My Group" --users "ou_aaa,ou_bbb"
+
+# Invite bot members (comma-separated app IDs, up to 5)
+lark-cli im +chat-create --name "My Group" --bots "cli_aaa,cli_bbb"
+
+# Invite both users and bots
+lark-cli im +chat-create --name "My Group" --users "ou_aaa" --bots "cli_aaa"
+
+# Make the creating bot a group manager (bot identity only)
+lark-cli im +chat-create --name "My Group" --set-bot-manager --as bot
+
+# JSON output
+lark-cli im +chat-create --name "My Group" --format json
+
+# Create a group with bot identity
+lark-cli im +chat-create --name "My Group" --users "ou_aaa" --as bot
+
+# Create a group with user identity
+lark-cli im +chat-create --name "My Group" --users "ou_aaa,ou_bbb" --as user
+
+# Preview the request without creating anything
+lark-cli im +chat-create --name "My Group" --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Limits | Description |
+|------|------|------|------|
+| `--name <name>` | Required for public groups | Max 60 characters; at least 2 characters for public groups | Group name (`"(no subject)"` for private groups if omitted) |
+| `--description <text>` | No | Max 100 characters | Group description |
+| `--users <ids>` | No | Up to 50, format `ou_xxx` | Comma-separated user open_ids |
+| `--bots <ids>` | No | Up to 5, format `cli_xxx` | Comma-separated bot app IDs |
+| `--owner <open_id>` | No | Format `ou_xxx` | Owner open_id (defaults to the bot when using `--as bot`, or the authorized user when using `--as user`) |
+| `--type <type>` | No | `private` (default) or `public` | Group type. Default to `private`; pass `public` only when the user explicitly asks for a discoverable/public group. |
+| `--chat-mode <mode>` | No | `group` (default) or `topic` | Group mode; `topic` creates a topic chat (not the same as `group_message_type=thread`). When the user asks for a topic chat, pass `topic` explicitly — do not rely on the default. |
+| `--set-bot-manager` | No | - | Set the creating bot as a group manager (only effective with `--as bot`) |
+| `--format json` | No | - | Output as JSON |
+| `--as <identity>` | No | `bot` or `user` | Identity type |
+| `--dry-run` | No | - | Preview the request without executing it |
+
+> **`--chat-mode topic` vs "normal group with topic-message mode"**: `--chat-mode topic` here creates a 话题群 — the entire group is a topic chat. This is different from "normal group (`chat_mode=group`) + topic-message mode (`group_message_type=thread`)". This CLI exposes only `chat_mode`; `group_message_type` is intentionally not surfaced.
+
+## AI Usage Guidance
+
+### When using `--as bot`
+
+Bot may fail to invite users who are mutually invisible to it during group creation (error 232043). To avoid this, use the **two-step flow** below instead of passing other users' open_ids in `--users`.
+
+1. **Get the current user's open_id:** Run `lark-cli contact +search-user --query "<name or email>"` to retrieve it.
+2. **Create the group — by default include the current user:**
+
+   ```bash
+   lark-cli im +chat-create --name "<group name>" \
+     --users "<current user open_id>" --as bot
+   ```
+
+   **Default behavior:** Always add the current user to the group, unless the user explicitly says "do not add me" or "bot-only group" — only then omit `--users`.
+
+3. **Add other members via user identity** (requires the current user to be in the group):
+
+   ```bash
+   lark-cli im chat.members create \
+     --params '{"chat_id":"<chat_id from step 2>","member_id_type":"open_id","succeed_type":1}' \
+     --data '{"id_list":["ou_aaa","ou_bbb"]}' \
+     --as user
+   ```
+
+   `succeed_type=1` ensures reachable users are added successfully; unreachable ones are returned in `invalid_id_list` instead of failing the whole request.
+
+4. **Check `invalid_id_list`** in the response. If non-empty, report to the user which members could not be added.
+
+### When using `--as user`
+
+User identity does not have the bot visibility limitation, so you can create the group and invite members in one step:
+
+```bash
+lark-cli im +chat-create --name "<group name>" --users "ou_aaa,ou_bbb" --as user
+```
+
+The authorized user is automatically the group creator and member.
+
+## Output Fields
+
+| Field | Description |
+|------|------|
+| `chat_id` | The new group's ID (`oc_xxx` format) |
+| `name` | Group name |
+| `chat_type` | Group type (`private` / `public`) |
+| `owner_id` | Owner ID (may be empty when a bot creates the group and `--owner` is not specified) |
+| `external` | Whether the group is external |
+| `share_link` | Group share link (omitted if retrieval fails) |
+
+## Usage Scenarios
+
+### Scenario 1: Create a group and specify the owner
+
+```bash
+lark-cli im +chat-create --name "Project Discussion Group" --owner ou_xxx
+```
+
+### Scenario 2: Create a group and invite users and a bot
+
+```bash
+lark-cli im +chat-create --name "Project Discussion Group" \
+  --owner ou_xxx \
+  --users "ou_aaa,ou_bbb" \
+  --bots "cli_aaa"
+```
+
+### Scenario 3: Create a group and send a welcome message
+
+```bash
+CHAT_ID=$(lark-cli im +chat-create --name "New Group" --format json | jq -r '.data.chat_id')
+lark-cli im +messages-send --chat-id "$CHAT_ID" --text "Welcome, everyone!"
+```
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| Permission denied (99991672) | The app does not have `im:chat:create` (bot) or `im:chat:create_by_user` (user) permission enabled | Enable the required permission for the app in the Open Platform console |
+| `--name is required for public groups and must be at least 2 characters` | A public group was created without a name or with a name shorter than 2 characters | Provide a name with at least 2 characters |
+| `--name exceeds the maximum of 60 characters` | The group name is too long | Shorten the name to 60 characters or fewer |
+| `--description exceeds the maximum of 100 characters` | The group description is too long | Shorten the description to 100 characters or fewer |
+| `--users exceeds the maximum of 50` | Too many user members were provided | Split the operation into batches and add more members later |
+| `--bots exceeds the maximum of 5` | Too many bot members were provided | Invite at most 5 bots at once |
+| `invalid user id: expected open_id (ou_xxx)` | Invalid user ID format | Use the `ou_xxx` format for users |
+| `invalid bot id: expected app ID (cli_xxx)` | Invalid bot ID format | Use the `cli_xxx` format for bots |
+| `invalid --owner: expected open_id (ou_xxx)` | Invalid owner ID format | Use the `ou_xxx` format for the owner |
+| `bot is invisible to user` (232043) | The bot and target users are mutually invisible | Follow the two-step flow in AI Usage Guidance above — do not pass other users in `--users` during creation |
+
+## References
+
+- [lark-im](../SKILL.md) - all IM commands
+- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters

package/skills/lark-im/references/lark-im-chat-identity.md

@@ -0,0 +1,55 @@
+# Group Chat Identity Rules
+
+> Warning: The most common source of failure in group operations is choosing the wrong identity. Confirm the identity before performing the action.
+
+Group-chat operations support both `--as user` (UAT user identity) and `--as bot` (TAT bot identity). Choosing the correct identity is critical for success.
+
+## Basic Principles
+
+- **If the user explicitly specifies an identity:** use exactly what the user requested (`--as user` or `--as bot`) without guessing.
+- **If the user does not specify an identity:** infer the correct identity from context instead of relying on the default.
+
+## Identity Selection by Operation
+
+| Operation | Recommended Identity | Why |
+|------|---------|-----------------------------------|
+| Create group (`+chat-create`) | Depends on the scenario | Infer from context |
+| Add members (member-management flow) | `--as user` | Bot visibility is limited and often fails when the target user is mutually invisible to the bot (232024) |
+| Update group (`+chat-update`) | Owner identity | Permission changes require owner/admin privileges; owner transfer requires owner identity |
+
+## Inferring the Owner
+
+When an owner-level action is needed and the owner is unknown, infer in this order:
+
+1. A bot created the group and `--owner` was **not** specified -> the owner is the bot (`--as bot`)
+2. A bot created the group and `--owner ou_xxx` **was** specified -> the owner is that user (`--as user`)
+3. A user created the group and `--owner` was **not** specified -> the owner is the current user (`--as user`)
+4. Still unclear -> ask the user to confirm who owns the group before making owner-level changes
+
+### When the Owner Is Neither the Current User Nor the Bot
+
+If the query shows that the owner is a third-party user (`owner_id` is neither the currently authorized user nor the bot), the current identity does not have owner privileges. In that case:
+
+- **Permission/setting changes:** if the bot is an admin of the group, `--as bot` can still perform admin-level operations such as renaming the group or changing permissions.
+- **Owner-only actions such as owner transfer:** require the actual owner to complete UAT authorization via `lark-cli auth login`, then perform the action as that owner.
+- Explain the limitation clearly to the user instead of retrying blindly.
+
+## Common Pitfalls
+
+### Inviting Members During Group Creation
+
+If a bot creates a group and `--users` includes users who are mutually invisible to the bot, the entire request fails with 232043. Use two steps instead:
+
+1. Create the group with the bot first, excluding invisible users: `lark-cli im +chat-create --name "Group Name"`
+2. Add users later with a user-identity member-management flow
+
+### Insufficient Privileges
+
+- **232016 / 232002 / 232017:** the current identity is not the owner or an admin -> switch to the owner identity
+- **232011:** the current user is not in the group -> use a group-member identity, or join the group first
+- **232024:** the bot and the target user are mutually invisible -> switch to `--as user`
+
+## References
+
+- [lark-im](../SKILL.md) - all IM commands
+- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters

package/skills/lark-im/references/lark-im-chat-list.md

@@ -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-im/references/lark-im-chat-messages-list.md

@@ -0,0 +1,148 @@
+# im +chat-messages-list
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Fetch the message list for a conversation. Supports both group chats and direct messages.
+
+This skill maps to the shortcut: `lark-cli im +chat-messages-list` (internally calls `GET /open-apis/im/v1/messages`, and automatically resolves the p2p chat_id when needed).
+
+## Commands
+
+```bash
+# Get group chat messages (json output by default)
+lark-cli im +chat-messages-list --chat-id oc_xxx
+
+# Get direct messages with a user (pass open_id and resolve p2p chat_id automatically)
+lark-cli im +chat-messages-list --user-id ou_xxx
+
+# Specify a time range (ISO 8601)
+lark-cli im +chat-messages-list --chat-id oc_xxx --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00"
+
+# Specify a time range (date only)
+lark-cli im +chat-messages-list --chat-id oc_xxx --start 2026-03-10 --end 2026-03-11
+
+# Control sort order and page size (max 50)
+lark-cli im +chat-messages-list --chat-id oc_xxx --sort asc --page-size 20
+
+# Pagination
+lark-cli im +chat-messages-list --chat-id oc_xxx --page-token "xxx"
+
+# JSON output
+lark-cli im +chat-messages-list --chat-id oc_xxx --format json
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|------|------|------|
+| `--chat-id <id>` | One of two | Specify the conversation by its chat_id directly (e.g., group chat `oc_xxx`) |
+| `--user-id <id>` | One of two | Specify a DM conversation by the other user's open_id (`ou_xxx`); p2p chat_id is resolved automatically. Requires user identity (`--as user`); not supported with bot identity |
+| `--start <time>` | No | Start time (ISO 8601 or date only) |
+| `--end <time>` | No | End time (ISO 8601 or date only) |
+| `--sort <order>` | No | Sort order: `asc` / `desc` (default `desc`) |
+| `--page-size <n>` | No | Page size (default 50, max 50) |
+| `--page-token <token>` | No | Pagination token |
+
+> Rule: `--chat-id` and `--user-id` are mutually exclusive. You must provide exactly one of them.
+
+## Resource Rendering
+
+Messages are rendered into human-readable text for inspection. Image messages are shown as placeholders such as `[Image: img_xxx]`; files and videos are rendered with resource keys in the content. Resource binaries are **not** downloaded automatically by this command.
+
+Use [lark-im-messages-resources-download](lark-im-messages-resources-download.md) when you need to download an image or file from a specific message.
+
+| Resource Type | Marker in Content | Behavior |
+|---------|-------------|------|
+| Image | `[Image: img_xxx]` | Download manually with `im +messages-resources-download --type image` |
+| File | `<file key="file_xxx" .../>` | Download manually with `im +messages-resources-download --type file` |
+| Audio | `<audio key="file_xxx" .../>` | Download manually with `im +messages-resources-download --type file` |
+| Video | `<video key="file_xxx" .../>` | Download manually with `im +messages-resources-download --type file` |
+
+## Thread Expansion (`thread_id`)
+
+In JSON output, a message may contain a `thread_id` (`omt_xxx`) field, which means the message has replies in a thread. Use [`im +threads-messages-list`](lark-im-threads-messages-list.md) to inspect replies in that thread:
+
+```bash
+lark-cli im +threads-messages-list --thread omt_xxx
+```
+
+| Scenario | Recommendation |
+|------|------|
+| You need context | Call `im +threads-messages-list --sort desc --page-size 10` for the discovered thread_id to inspect recent replies |
+| The user asks for the "full discussion" | Use `im +threads-messages-list --sort asc --page-size 50`, then paginate if needed |
+| You only need an overview | Skip thread expansion |
+
+## Output Fields
+
+| Field | Description |
+|------|------|
+| `messages` | Message array |
+| `total` | Number of messages in the current page |
+| `has_more` | Whether additional pages are available |
+| `page_token` | Pagination token for the next page |
+
+Each message contains:
+
+| Field | Description |
+|------|------|
+| `message_id` | Message ID |
+| `msg_type` | Message type: `text`, `image`, `file`, `interactive`, `post`, `audio`, `video`, `system`, etc. |
+| `create_time` | Creation time |
+| `sender` | Sender information (includes `name` for user senders) |
+| `content` | Message content |
+| `deleted` | Whether the message has been recalled (always present, `true` = recalled) |
+| `updated` | Whether the message has been edited after sending |
+| `mentions` | Array of @mentions in the message; each item contains `{id, key, name}`. Present only when the message contains @mentions |
+| `thread_id` | Thread ID (`omt_xxx`) if the message has replies in a thread. Present only when replies exist |
+
+## Pagination (`has_more` / `page_token`)
+
+`im +chat-messages-list` returns `has_more` and `page_token` when more data is available. Use `--page-token` to continue:
+
+```bash
+lark-cli im +chat-messages-list --chat-id oc_xxx --page-token <PAGE_TOKEN>
+```
+
+You can also fall back to the generic API:
+
+```bash
+lark-cli api GET /open-apis/im/v1/messages \
+  --params 'container_id_type=chat&container_id=oc_xxx&page_size=50&page_token=<PAGE_TOKEN>'
+```
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| `specify --chat-id <chat_id> or --user-id <open_id>` | Neither `--chat-id` nor `--user-id` was provided | You must provide exactly one |
+| `--chat-id and --user-id cannot be specified together` | Both parameters were provided | Use only one |
+| `--user-id requires user identity (--as user); use --chat-id when calling with bot identity` | `--user-id` was used with bot identity | The p2p resolution endpoint requires user identity. Either pass `--as user` or look up the p2p `chat_id` separately and pass it via `--chat-id` |
+| `P2P chat not found for this user` | `--user-id` was used but no p2p chat exists for the current identity and that user | Confirm the target direct-message relationship exists for the current identity |
+| `--start: invalid time format` | Invalid time format | Use ISO 8601 or date-only format such as `2026-03-10` |
+| Permission denied | Message read permissions are missing | Ensure the app has `im:message:readonly` and `im:chat:read` enabled |
+
+## AI Usage Guidance
+
+1. **Resolving chat_id from a chat name:** When the user refers to a chat by name and you don't have the `chat_id`, use [`+chat-search`](lark-im-chat-search.md) first:
+   ```bash
+   # Find chat_id by name, then list messages
+   lark-cli im +chat-search --query "<chat name keyword>" --format json
+   lark-cli im +chat-messages-list --chat-id <chat_id>
+   ```
+   **Do not use `im chats search` or `+chat-list` — always use the `+chat-search` shortcut.**
+2. **Prefer `--chat-id` when available:** if the chat_id is already known, use it directly to avoid extra API calls.
+3. **For direct messages:** use `--user-id` to resolve the p2p chat automatically instead of looking it up manually. This requires user identity (`--as user`); with bot identity, resolve the p2p `chat_id` yourself and pass it via `--chat-id`.
+4. **For time ranges:** both ISO 8601 and date-only inputs are supported. Date-only is usually simpler.
+5. **For full content:** table output truncates content. Use `--format json` when you need the complete message body.
+6. **For sender info:** the command already resolves sender names, so you do not need a separate lookup.
+7. **Application/bot identity + named group history:** If the user says "使用应用身份/以 bot 身份" and asks to list or read historical messages for a named group, use bot identity for both steps:
+   ```bash
+   lark-cli im +chat-search --as bot --query "<chat name keyword>" --format json
+   lark-cli im +chat-messages-list --as bot --chat-id <chat_id> --page-size 50 --format json
+   ```
+   Do not use `im +messages-search --as bot`; `+messages-search` is user-only. Continue with `--page-token` if `has_more=true`.
+
+## References
+
+- [lark-im](../SKILL.md) - all IM commands
+- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters