@amaster.ai/pi-lark 0.1.4 → 0.1.6

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,166 @@
+# im +chat-list
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+List chats the current user (or bot, with `--as bot`) is a member of. **Not a search API — there is no `--query` parameter; the call always returns the full member list, paginated.** For keyword-based lookup (e.g. find a group by name or by member), use [`+chat-search`](lark-im-chat-search.md) instead.
+
+**Defaults to groups only**; pass `--types=p2p,group` (or `--types p2p --types group`) to also include p2p single chats (user identity only — see ["Bot identity and p2p"](#bot-identity-and-p2p)). Supports pagination, sort order, and (user identity only) muted-chat filtering.
+
+This skill maps to the shortcut: `lark-cli im +chat-list` (internally calls `GET /open-apis/im/v1/chats`).
+
+## Commands
+
+```bash
+# List the user's chats (default sort: create_time, ascending)
+lark-cli im +chat-list
+
+# Sort by recent activity (most recently active first)
+lark-cli im +chat-list --sort active_time
+
+# Limit page size
+lark-cli im +chat-list --page-size 50
+
+# Pagination
+lark-cli im +chat-list --page-token "xxx"
+
+# Drop muted chats (user identity only)
+lark-cli im +chat-list --exclude-muted
+
+# JSON output
+lark-cli im +chat-list --format json
+
+# Preview the request without executing it
+lark-cli im +chat-list --dry-run
+
+# Include p2p single chats (user identity only) — comma form
+lark-cli im +chat-list --as user --types p2p,group
+
+# Same, using repeat flag instead of CSV
+lark-cli im +chat-list --as user --types p2p --types group
+
+# Only p2p single chats (user identity only)
+lark-cli im +chat-list --as user --types p2p
+```
+
+## Parameters
+
+| Parameter | Required | Limits | Description |
+|------|------|------|------|
+| `--user-id-type <type>` | No | `open_id` (default), `union_id`, `user_id` | ID type used for `owner_id` in the response |
+| `--types <strings>` | No | `group`, `p2p` (comma-separated or repeated) | Chat types to include. Omitted = groups only (backward compatible). `p2p` requires user identity (`--as user`); under `--as bot`, `--types=p2p` alone is rejected and `--types=p2p,group` is silently downgraded to `group` |
+| `--sort <field>` | No | `create_time` (default, ascending), `active_time` (descending) | Result ordering |
+| `--page-size <n>` | No | 1-100, default 20 | Number of results per page |
+| `--page-token <token>` | No | - | Pagination token from the previous response |
+| `--exclude-muted` | No | User identity only | Drop chats the current user has muted (do-not-disturb). Under `--as bot`, the flag is silently inactive; see "Filtering muted chats" below |
+| `--format json` | No | - | Output as JSON |
+| `--dry-run` | No | - | Preview the request without executing it |
+
+> **Note:** Supports both `--as user` (default) and `--as bot`. When using bot identity, the app must have bot capability enabled.
+
+## Output Fields
+
+| Field | Description |
+|------|------|
+| `chat_id` | Chat ID (`oc_xxx` format) |
+| `name` | Chat name |
+| `description` | Chat description |
+| `owner_id` | Owner ID (type controlled by `--user-id-type`) |
+| `external` | Whether the chat is external |
+| `chat_status` | Chat status (`normal` / `dissolved` / `dissolved_save`) |
+| `chat_mode` | Chat mode discriminator: `group` (regular) / `topic` (topic group) / `p2p` (single chat) |
+| `p2p_target_type` | Peer type, e.g., `user` |
+| `p2p_target_id` | Peer ID (type controlled by `--user-id-type`) |
+
+## Including p2p single chats
+
+Default behavior lists groups only — same as before this feature. To include p2p, pass `--types`:
+
+| User intent | Call | Identity |
+|---|---|---|
+| "list my groups" / 我的群 / 我加入了哪些群 | (default, omit `--types`) | user or bot |
+| "list my p2p chats" / 我的单聊 / 我跟谁有 1v1 | `--types p2p` | **user only** |
+| "all my chats" / 全部聊天 / 所有会话 (ambiguous) | `--types p2p,group` | **user only** |
+
+For p2p rows in the response: `name` is the peer's display name, `owner_id` follows group semantics, `chat_mode = "p2p"`, and `p2p_target_type` / `p2p_target_id` identify the peer.
+
+## Bot identity and p2p
+
+`tenant_access_token` cannot list p2p chats — to protect user privacy, bot identity is not permitted to enumerate p2p single chats. Behavior under `--as bot`:
+
+- `--as bot --types=p2p` → rejected at validation time with an actionable error; no request is sent.
+- `--as bot --types=p2p,group` → CLI strips `p2p` and sends `types=group`. Request proceeds; only groups are returned. The strip is a **request-level adjustment**, surfaced two ways so neither humans nor agents miss it:
+    - **stderr**: `warning: bot_strip_p2p: To protect user privacy, bot identity cannot list p2p chats; --types=p2p,group was sent as types=group. Use --as user to include p2p.` (matches the `warning: <code>: <message>` convention in `shortcuts/common/runner.go`)
+    - **stdout JSON**: a top-level `notices` array gains a structured entry:
+      ```json
+      {
+        "chats": [...],
+        "notices": [
+          { "code": "bot_strip_p2p", "message": "To protect user privacy, bot identity cannot list p2p chats; …" }
+        ]
+      }
+      ```
+    - The `filter` slot stays scoped to `--exclude-muted`; `notices` is a separate top-level key, so the two never collide and no priority is needed when both fire.
+    - DryRun emits the same stderr warning so a previewed request truthfully reflects what Execute will send (parity with `shortcuts/drive/drive_search.go`).
+- `--as bot --types=group` → accepted, returns groups normally.
+- `--as bot` (no `--types`) → unchanged, returns groups.
+
+To include p2p single chats, switch to user identity: `--as user --types=p2p,group`.
+
+## Filtering muted chats
+
+`--exclude-muted` (user identity only) drops chats the current user has set to do-not-disturb. After the list call, the CLI batches the page's chat_ids through `POST /open-apis/im/v1/chat_user_setting/batch_get_mute_status` and filters client-side. Under `--as bot`, the mute API is UAT-only and the filter is silently skipped.
+
+When the flag is set, the JSON envelope gains a `filter` sub-object (absent otherwise, so existing consumers are unaffected); `fetched_count == returned_count + filtered_count` always holds:
+
+```json
+{
+  "chats": [...],
+  "filter": {
+    "applied": "exclude_muted",
+    "fetched_count": 20,
+    "returned_count": 17,
+    "filtered_count": 3,
+    "hint": "Filtered out 3 muted chat(s) on this page (17 remaining); use --page-token to fetch more."
+  }
+}
+```
+
+## Usage Scenarios
+
+### Scenario 1: List my recent chats
+
+```bash
+lark-cli im +chat-list --sort active_time --page-size 10
+```
+
+### Scenario 2: List my non-muted chats sorted by activity
+
+```bash
+lark-cli im +chat-list --sort active_time --exclude-muted
+```
+
+### Scenario 3: Iterate all my chats programmatically
+
+```bash
+TOKEN=""
+while :; do
+  RESP=$(lark-cli im +chat-list --page-size 100 --page-token "$TOKEN" --format json)
+  echo "$RESP" | jq -r '.data.chats[].chat_id'
+  HAS_MORE=$(echo "$RESP" | jq -r '.data.has_more')
+  [ "$HAS_MORE" = "true" ] || break
+  TOKEN=$(echo "$RESP" | jq -r '.data.page_token')
+done
+```
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| `--page-size must be an integer between 1 and 100` | page-size is out of range or not an integer | Use an integer between 1 and 100 |
+| Permission denied (99991672) | The bot app does not have `im:chat:read` TAT permission enabled | Enable the permission for the app in the Open Platform console |
+| Permission denied (99991679) with `--as user` | UAT is not authorized for `im:chat:read` | Run `lark-cli auth login --scope "im:chat:read"` |
+| `Bot ability is not activated` (232025) | The app does not have bot capability enabled | Enable bot capability in the Open Platform console |
+| `--exclude-muted` returns all chats unfiltered and `hint` says "no effect under bot identity" | Running under `--as bot` (mute API is UAT-only) | Switch to `--as user` for mute filtering |
+| `--types=p2p (single chats) is only supported with user identity` | `--as bot` + `--types=p2p` (single-value only; mixed `--types=p2p,group` is downgraded to `group` and surfaces a `bot_strip_p2p` notice via stderr + `outData["notices"]` — see "Bot identity and p2p") | Use `--as user`, or include `group` in `--types` (the bot proceeds with `group` only and emits the `bot_strip_p2p` notice) |
+
+> Full error message of the row above: `--types=p2p (single chats) is only supported with user identity (--as user). To protect user privacy, bot identity cannot list p2p chats. Use --as user, or include "group" in --types.`

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

@@ -0,0 +1,83 @@
+# im +chat-members-list
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+List the members of a chat. Users and bots are returned in **separate buckets** — `users[]` and `bots[]` — with per-bucket totals (`user_total` / `bot_total`). Use `--member-types` to return only one kind.
+
+This skill maps to the shortcut: `lark-cli im +chat-members-list` (internally calls `GET /open-apis/im/v1/chats/{chat_id}/members/list`).
+
+## Commands
+
+```bash
+# Single page (default)
+lark-cli im +chat-members-list --chat-id oc_xxx
+
+# Only users, or only bots
+lark-cli im +chat-members-list --chat-id oc_xxx --member-types user
+lark-cli im +chat-members-list --chat-id oc_xxx --member-types user,bot
+
+# Walk every page (capped by --page-limit; 0 = unlimited)
+lark-cli im +chat-members-list --chat-id oc_xxx --page-all --page-limit 0
+
+# Resume from a specific cursor (single page; --page-all is ignored)
+lark-cli im +chat-members-list --chat-id oc_xxx --page-token "xxx"
+
+# JSON output / preview the request
+lark-cli im +chat-members-list --chat-id oc_xxx --format json
+lark-cli im +chat-members-list --chat-id oc_xxx --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Limits | Description |
+|------|------|------|------|
+| `--chat-id <id>` | Yes | `oc_xxx` | Target chat |
+| `--member-types <strings>` | No | `user`, `bot` (comma-separated or repeated) | Member types to return. Omitted = all |
+| `--member-id-type <type>` | No | `open_id` (default), `union_id`, `user_id` | ID type for `member_id` in the response |
+| `--page-size <n>` | No | 1-100, default 20 | Results per page. With `--page-all` and no explicit `--page-size`, the max (100) is used automatically to minimize round-trips |
+| `--page-token <token>` | No | - | Pagination cursor; **implies a single-page fetch** (disables auto-pagination) |
+| `--page-all` | No | - | Automatically walk every page (capped by `--page-limit`) |
+| `--page-limit <n>` | No | default 10, `0` = unlimited | Max pages to fetch with `--page-all` |
+| `--page-delay <ms>` | No | default 200, `0` = no delay | Delay between pages during `--page-all` (throttle to avoid rate limits on large lists) |
+| `--format json` | No | - | Output as JSON |
+| `--dry-run` | No | - | Preview the request without executing it |
+
+> Supports both `--as user` (default) and `--as bot`. The caller must be in the target chat, and must belong to the same tenant for internal chats.
+
+## Output Fields
+
+| Field | Description |
+|------|------|
+| `chat_id` | The queried chat ID |
+| `users` | Array of user members (`member_id`, `name`, `tenant_key`, …) |
+| `bots` | Array of bot members (`member_id`, `app_id`, `name`, …) |
+| `user_total` / `bot_total` | Server-reported totals for each bucket |
+| `truncations` | Non-empty when the server **capped a bucket** due to security config — see below |
+| `has_more` / `page_token` | Paging signals from the final page fetched |
+
+## Truncation: the result may be incomplete
+
+The server applies a security cap to large member lists. When a bucket is capped, the response carries a `truncations[]` entry (e.g. `[{"limit": 100, "member_type": "user"}]`) **on the final page only**. The shortcut surfaces this two ways so it is never missed:
+
+- **stderr**: `⚠️  member list truncated by server security config: user bucket capped at 100 — the list is INCOMPLETE.`
+- **stdout JSON**: the `truncations` array is preserved verbatim in the output.
+
+A truncated result is *not* fixable by paging further — it is a server-side cap. Treat `users`/`bots` as a partial list whenever `truncations` is non-empty.
+
+## Pagination notes
+
+- Default fetches a single page. Pass `--page-all` to drain every page.
+- With `--page-all` and no explicit `--page-size`, the shortcut uses the maximum page size (100) so a full walk takes the fewest round-trips. An explicit `--page-size` is always honored.
+- `--page-all` sleeps `--page-delay` ms (default 200) between pages to avoid hammering the API when a tenant has no server-side member cap and the list spans many pages. Set `--page-delay 0` to disable.
+- `--page-all` stops at `--page-limit` pages (default 10). When it stops early, `has_more` stays `true` so you know the result is incomplete; re-run with `--page-limit 0` for everything.
+- `--page-token` and `--page-all` together: `--page-token` wins (single-page fetch from the supplied cursor); a stderr warning is emitted.
+- Across pages, `users[]` and `bots[]` are concatenated; `truncations` / `has_more` / `page_token` come from the last page fetched.
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause |   | Solution |
+|---------|---------|---|---------|
+| `--chat-id is required` | `--chat-id` omitted |   | Provide the `oc_xxx` chat ID |
+| `--page-size must be an integer between 1 and 100` | out of range |   | Use 1-100 |
+| `--member-types contains invalid value` | value other than `user`/`bot` |   | Use `user`, `bot`, or both |
+| Permission denied | missing `im:chat.members:read` |   | Bot: enable the scope in the console. User: `lark-cli auth login --scope "im:chat.members:read"` |

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

@@ -0,0 +1,157 @@
+# 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.
+
+By default the response carries a `reactions` block (counts + details from `im.reactions.batch_query`) on every message that has reactions, and `update_time` on messages that were actually edited. Thread replies expanded via auto-`thread_replies` participate in the same batched enrichment. Pass `--no-reactions` to skip the extra round-trip. Pass `--download-resources` to additionally download message resources (image/file/audio/video/media + post-embedded, excluding stickers) into `./lark-im-resources/` and attach a `resources` block — off by default. See [message enrichment](lark-im-message-enrichment.md) for the full contract.
+
+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 --order 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) |
+| `--order <order>` | No | Sort order: `asc` / `desc` (default `desc`) |
+| `--page-size <n>` | No | Page size (default 50, max 50) |
+| `--page-token <token>` | No | Pagination token |
+| `--no-reactions` | No | Skip auto-fetching the `reactions` block |
+| `--download-resources` | No | Download message resources (image/file/audio/video/media + post-embedded, excluding stickers) into `./lark-im-resources/` and attach a `resources` block. Off by default; no extra requests when omitted |
+
+> Rule: `--chat-id` and `--user-id` are mutually exclusive. You must provide exactly one of them.
+
+> **CAUTION:** `--order` is the only sort axis — messages are always ordered by creation time, `asc` or `desc`. There is no field axis: the command cannot sort by sender or any other field, so do **not** attempt `--sort sender` or similar (it is rejected). If the user asks to group or sort by sender, fetch with `--order` and aggregate client-side, and tell them this is local post-processing, not a CLI/API sort capability.
+
+## Resource Rendering
+
+Messages are rendered into human-readable text for inspection. Image messages are shown as placeholders such as `![Image](img_xxx)`; files, audio, and videos are rendered with resource keys in the content (e.g. `<audio key="file_xxx" duration="Xs"/>`). By default resource binaries are **not** downloaded.
+
+Two ways to get the binaries:
+- **In one pass:** add `--download-resources` to this command — every eligible resource (image/file/audio/video/media + post-embedded, excluding stickers) is downloaded into `./lark-im-resources/` and a `resources` block (`{message_id, key, type, local_path, size_bytes}`) is attached to each message. See [message enrichment](lark-im-message-enrichment.md#resource-auto-download---download-resources-opt-in).
+- **One at a time:** use [lark-im-messages-resources-download](lark-im-messages-resources-download.md).
+
+| Resource Type | Marker in Content | Behavior |
+|---------|-------------|------|
+| Image | `![Image](img_xxx)` | `--download-resources`, or manually `im +messages-resources-download --type image` |
+| File | `<file key="file_xxx" .../>` | `--download-resources`, or manually `im +messages-resources-download --type file` |
+| Audio | `<audio key="file_xxx" duration="Xs"/>` | `--download-resources`, or manually `im +messages-resources-download --type file` |
+| Video | `<video key="file_xxx" .../>` | `--download-resources`, or manually `im +messages-resources-download --type file` |
+| Sticker | `[Sticker]` | Not downloadable (Feishu does not support fetching sticker resources) |
+
+## 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 --order 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 --order 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