diff --git a/skills/lark-im/SKILL.md b/skills/lark-im/SKILL.md index 7a1c315d32..64a8fb7d05 100644 --- a/skills/lark-im/SKILL.md +++ b/skills/lark-im/SKILL.md @@ -232,44 +232,3 @@ lark-cli im [flags] # 调用 API - `create` — Create a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md) - `delete` — Delete a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md) - `update` — Update a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md) - -## 权限表 - -| 方法 | 所需 scope | -|------|-----------| -| `chats.create` | `im:chat:create` | -| `chats.get` | `im:chat:read` | -| `chats.link` | `im:chat:read` | -| `chats.update` | `im:chat:update` | -| `chat.members.create` | `im:chat.members:write_only` | -| `chat.members.delete` | `im:chat.members:write_only` | -| `chat.members.get` | `im:chat.members:read` | -| `+chat-members-list` | `im:chat.members:read` | -| `chat.user_setting.batch_query` | `im:chat.user_setting:read` | -| `chat.user_setting.batch_update` | `im:chat.user_setting:write` | -| `chat.managers.add_managers` | `im:chat.managers:write_only` | -| `chat.managers.delete_managers` | `im:chat.managers:write_only` | -| `chat.moderation.get` | `im:chat.moderation:read` | -| `chat.moderation.update` | `im:chat:moderation:write_only` | -| `messages.delete` | `im:message:recall` | -| `messages.forward` | `im:message` | -| `messages.merge_forward` | `im:message` | -| `messages.read_users` | `im:message:readonly` | -| `messages.urgent_app` | `im:message.urgent` | -| `messages.urgent_phone` | `im:message.urgent:phone` | -| `messages.urgent_sms` | `im:message.urgent:sms` | -| `reactions.batch_query` | `im:message.reactions:read` | -| `reactions.create` | `im:message.reactions:write_only` | -| `reactions.delete` | `im:message.reactions:write_only` | -| `reactions.list` | `im:message.reactions:read` | -| `threads.forward` | `im:message` | -| `images.create` | `im:resource` | -| `pins.create` | `im:message.pins:write_only` | -| `pins.delete` | `im:message.pins:write_only` | -| `pins.list` | `im:message.pins:read` | -| `feed.groups.batch_add_item` | `im:feed_group_v1:write` | -| `feed.groups.batch_query` | `im:feed_group_v1:read` | -| `feed.groups.batch_remove_item` | `im:feed_group_v1:write` | -| `feed.groups.create` | `im:feed_group_v1:write` | -| `feed.groups.delete` | `im:feed_group_v1:write` | -| `feed.groups.update` | `im:feed_group_v1:write` | diff --git a/skills/lark-im/references/lark-im-chat-create.md b/skills/lark-im/references/lark-im-chat-create.md index 71d25eef0d..f592ae2234 100644 --- a/skills/lark-im/references/lark-im-chat-create.md +++ b/skills/lark-im/references/lark-im-chat-create.md @@ -2,82 +2,23 @@ > **Prerequisite:** Before executing this command, ensure [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) has been read once in the current task for authentication, global parameters, and safety rules. Do not reread it if already loaded. -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. +**Run `lark-cli im +chat-create --help` for the authoritative flags, defaults, limits, and enums.** This file covers only what `--help` cannot. -Every create call requires a caller-owned `--idempotency-key` (max 50 characters). Follow the caller-owned idempotency-key protocol in [`lark-shared`](../../lark-shared/SKILL.md#调用方持有的幂等键), then copy the generated literal into `` below. For this command, reuse it for the same logical chat creation for up to 10 hours; a new logical chat must use a new key. +## `--idempotency-key` is required -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" --idempotency-key - -# Create a public group (name is required and must be at least 2 characters) -lark-cli im +chat-create --name "Public Group" --type public --idempotency-key - -# Create a topic chat -lark-cli im +chat-create --name "Topic Group" --chat-mode topic --idempotency-key - -# Specify the group owner -lark-cli im +chat-create --name "My Group" --owner ou_xxx --idempotency-key - -# Invite user members (comma-separated open_ids, up to 50) -lark-cli im +chat-create --name "My Group" --users "ou_aaa,ou_bbb" --idempotency-key - -# Invite bot members (comma-separated app IDs, up to 5) -lark-cli im +chat-create --name "My Group" --bots "cli_aaa,cli_bbb" --idempotency-key - -# Invite both users and bots -lark-cli im +chat-create --name "My Group" --users "ou_aaa" --bots "cli_aaa" --idempotency-key - -# Make the creating bot a group manager (bot identity only) -lark-cli im +chat-create --name "My Group" --set-bot-manager --idempotency-key --as bot - -# JSON output -lark-cli im +chat-create --name "My Group" --idempotency-key --format json - -# Create a group with bot identity -lark-cli im +chat-create --name "My Group" --users "ou_aaa" --idempotency-key --as bot - -# Create a group with user identity -lark-cli im +chat-create --name "My Group" --users "ou_aaa,ou_bbb" --idempotency-key --as user - -# Preview the request without creating anything -lark-cli im +chat-create --name "My Group" --idempotency-key --dry-run -``` - -## Parameters - -| Parameter | Required | Limits | Description | -|------|------|------|------| -| `--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 ` | No | Max 100 characters | Group description | -| `--users ` | No | Up to 50, format `ou_xxx` | Comma-separated user open_ids | -| `--bots ` | No | Up to 5, format `cli_xxx` | Comma-separated bot app IDs | -| `--owner ` | No | Format `ou_xxx` | Owner open_id (defaults to the bot when using `--as bot`, or the authorized user when using `--as user`) | -| `--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 ` | 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`) | -| `--idempotency-key ` | Yes | Max 50 characters | Caller-owned stable key. Generate a UUID with a library or tool, pass its literal value, and reuse that literal for retries of the same logical creation within 10 hours. | -| `--format json` | No | - | Output as JSON | -| `--as ` | 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. +`--help` lists the flag but does not mark it required — it is. Omitting it fails with +`--idempotency-key is required`. Generate one UUID with a library or tool, pass its **literal value**, and +reuse that same literal unchanged when retrying the same logical creation. Do not inline a generator +expression (`$(uuidgen)`) into the command: a fresh value on each retry defeats the protection entirely. ## 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`. +A bot may fail to invite users who are mutually invisible to it during group creation (**error 232043**). `--help` gives no hint of this, and passing other users in `--users` is the natural-looking move that triggers it. Use the two-step flow instead: -1. **Get the current user's open_id:** Run `lark-cli contact +search-user --query ""` to retrieve it. -2. **Create the group — by default include the current user:** +1. **Resolve the current user's open_id** — `lark-cli contact +search-user --query ""`. +2. **Create the group with only that user:** ```bash lark-cli im +chat-create --name "" \ @@ -85,9 +26,9 @@ Bot may fail to invite users who are mutually invisible to it during group creat --users "" --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`. + **Default behavior:** always add the current user, unless they explicitly say "do not add me" or ask for a bot-only group — only then omit `--users`. -3. **Add other members via user identity** (requires the current user to be in the group): +3. **Add the remaining members with user identity** (requires the current user to already be in the group): ```bash lark-cli im chat.members create \ @@ -96,73 +37,29 @@ Bot may fail to invite users who are mutually invisible to it during group creat --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. + `succeed_type=1` makes reachable users succeed while unreachable ones come back 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. +4. **Check `invalid_id_list`** in the response. If it is non-empty, report which members could not be added — silence here reads as success to the user. ### 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 "" --users "ou_aaa,ou_bbb" --idempotency-key --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) | +User identity has no visibility limitation, so creation and invitation happen in one step, and the authorized user is automatically creator and member. Prefer this path whenever the task does not specifically need bot ownership. -## Usage Scenarios +## Gotchas -### Scenario 1: Create a group and specify the owner - -```bash -lark-cli im +chat-create --name "Project Discussion Group" --owner ou_xxx --idempotency-key -``` - -### Scenario 2: Create a group and invite users and a bot - -```bash -lark-cli im +chat-create --name "Project Discussion Group" \ - --idempotency-key \ - --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" --idempotency-key --format json | jq -r '.data.chat_id') -lark-cli im +messages-send --chat-id "$CHAT_ID" --text "Welcome, everyone!" --as bot -``` +- **`owner_id` can come back empty.** When a bot creates the group and `--owner` is not passed, the response's `owner_id` may be blank even though `--help` says the owner defaults to the bot. Do not treat an empty `owner_id` as a failure, and do not feed it into a follow-up call unchecked. +- **`share_link` is omitted when its retrieval fails**, not set to an empty string. A `jq` path that assumes the key exists will break. ## Common Errors and Troubleshooting -| Symptom | Root Cause | Solution | +Only errors whose cause or fix is not evident from `--help`: + +| 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 | -| `--idempotency-key is required` | The caller did not supply replay protection | Generate one UUID with a library or tool, pass its literal value, and reuse it unchanged for retries of this same logical creation | -| `--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 | +| Permission denied (99991672) | App lacks `im:chat:create` (bot) or `im:chat:create_by_user` (user) | Enable that permission for the app in the Open Platform console | +| `--idempotency-key is required` | No replay protection supplied | See the section above — generate one UUID, pass the literal, reuse it on retry | +| `bot is invisible to user` (232043) | Bot and target users are mutually invisible | Use the two-step flow above; do not pass other users in `--users` at creation time | ## References -- [lark-im](../SKILL.md) - all IM commands -- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters +- [lark-im](../SKILL.md) — all IM commands diff --git a/skills/lark-im/references/lark-im-chat-list.md b/skills/lark-im/references/lark-im-chat-list.md index 126b820248..f486cb3db5 100644 --- a/skills/lark-im/references/lark-im-chat-list.md +++ b/skills/lark-im/references/lark-im-chat-list.md @@ -2,107 +2,40 @@ > **Prerequisite:** Before executing this command, ensure [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) has been read once in the current task for authentication, global parameters, and safety rules. Do not reread it if already loaded. -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. +**Run `lark-cli im +chat-list --help` for the authoritative flags, defaults, sort fields, and completeness rule.** This file covers only what `--help` cannot. -**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 - -# 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 ` | No | `open_id` (default), `union_id`, `user_id` | ID type used for `owner_id` in the response | -| `--types ` | 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 ` | No | `create_time` (default, ascending), `active_time` (descending) | Result ordering | -| `--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`) | +**Not a search API** — there is no `--query`; the call always returns the full membership list, paginated. For keyword lookup (find a group by name or by member) use [`+chat-search`](lark-im-chat-search.md) instead. ## Including p2p single chats -Default behavior lists groups only — same as before this feature. To include p2p, pass `--types`: +`--help` says p2p requires `--types` and user identity. What it cannot tell you is which phrasing maps to which call: | User intent | Call | Identity | |---|---|---| -| "list my groups" / 我的群 / 我加入了哪些群 | (default, omit `--types`) | user or bot | +| "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. +For p2p rows: `name` is the peer's display name, `chat_mode = "p2p"`, `owner_id` follows group semantics, 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: : ` 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`. +`tenant_access_token` cannot enumerate p2p chats — a privacy restriction, not a scope gap, so no amount of authorization changes it. The two failure shapes differ, and the second one is the dangerous one: + +- **`--as bot --types=p2p`** → rejected at validation time; **no request is sent**. +- **`--as bot --types=p2p,group`** → the CLI **silently strips** `p2p` and sends `types=group`. The request succeeds and returns only groups, so a caller who does not inspect the warning will believe p2p was covered. It is surfaced two ways: + - 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.` + - stdout JSON: a top-level `notices` array gains `{ "code": "bot_strip_p2p", "message": "…" }` +- `--dry-run` emits the same warning, so a preview truthfully reflects what execution will send. + +To actually include p2p, switch 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. +`--exclude-muted` is applied **client-side after** the list call — the CLI batches the page's chat_ids through a mute-status lookup and drops the muted ones. Two consequences `--help` does not state: -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: +- **Under `--as bot` the filter is silently skipped** (the mute API accepts user tokens only), so bot output comes back unfiltered even with the flag set. +- **Filtering happens per page, so a page can come back short.** The JSON envelope gains a `filter` sub-object (absent when the flag is off), where `fetched_count == returned_count + filtered_count` always holds: ```json { @@ -117,30 +50,23 @@ When the flag is set, the JSON envelope gains a `filter` sub-object (absent othe } ``` -## 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 +Do not read a short page as "no more results" — follow the `hint` and keep paginating. -```bash -lark-cli im +chat-list --sort active_time --exclude-muted -``` +## Gotchas -If the task requires every visible chat, inspect this concrete command's `--help` before executing. +- **`--sort` has no direction flag.** `create_time` is always ascending and `active_time` always descending; the command has no `--order`. "Newest-created first" is therefore **not expressible** — use `active_time` (most recently active first), or tell the user the constraint. Fabricating `--order desc` fails with unknown flag. +- **`notices` and `filter` are separate top-level keys.** Both can appear in one response; neither overrides the other, so check for both. ## Common Errors and Troubleshooting -| Symptom | Root Cause | Solution | +Only errors whose cause or fix is not evident from `--help`: + +| Symptom | Root cause | Solution | |---------|---------|---------| -| 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) | +| p2p chats missing under bot identity | Privacy restriction stripped `p2p` from the request | Re-run with `--as user`; check `notices` for `bot_strip_p2p` | +| Fewer rows than `--page-size` | `--exclude-muted` filtered the page after fetching | Read `filter.filtered_count`, follow the `hint`, keep paginating | +| Permission denied | Chat read scope missing | `auth login --scope "im:chat:read"` | + +## References -> 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.` +- [lark-im](../SKILL.md) — all IM commands diff --git a/skills/lark-im/references/lark-im-chat-messages-list.md b/skills/lark-im/references/lark-im-chat-messages-list.md index 3846db6b70..373eeacee4 100644 --- a/skills/lark-im/references/lark-im-chat-messages-list.md +++ b/skills/lark-im/references/lark-im-chat-messages-list.md @@ -2,138 +2,70 @@ > **Prerequisite:** Before executing this command, ensure [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) has been read once in the current task for authentication, global parameters, and safety rules. Do not reread it if already loaded. -Fetch the message list for a conversation. Supports both group chats and direct messages. +**Run `lark-cli im +chat-messages-list --help` for the authoritative flags, defaults, sort/pagination controls, and completeness rule.** This file covers only what `--help` cannot. -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. +## Automatic enrichment -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). +`--help` names the flags that turn enrichment off; it does not say what arrives when they are left on: -## Commands +- A `reactions` block (counts + details from `im.reactions.batch_query`) on every message that has reactions — so **do not call the reactions API separately** for messages you already pulled here. +- `update_time` on messages that were actually edited (absent otherwise). +- Thread replies expanded via auto-`thread_replies` participate in the same batched enrichment. -```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 -lark-cli im +chat-messages-list --chat-id oc_xxx --order asc - -# JSON output -lark-cli im +chat-messages-list --chat-id oc_xxx --format json -``` - -## Parameters - -| Parameter | Required | Description | -|------|------|------| -| `--chat-id ` | One of two | Specify the conversation by its chat_id directly (e.g., group chat `oc_xxx`) | -| `--user-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