@yandy0725/pi-lark 0.1.0

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

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

@@ -0,0 +1,142 @@
+# im +chat-search
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Search the list of group chats visible to a user or bot, including chats the user or bot belongs to and public chats visible to them. Supports keyword matching on chat names and member names, including pinyin and prefix fuzzy search.
+
+This skill maps to the shortcut: `lark-cli im +chat-search` (internally calls `POST /open-apis/im/v2/chats/search`).
+
+## Commands
+
+```bash
+# Search chats by keyword
+lark-cli im +chat-search --query "project"
+
+# Restrict by search types
+lark-cli im +chat-search --query "project" --search-types "private,public_joined"
+
+# Filter by chat mode (group = regular group, topic = topic/thread group)
+lark-cli im +chat-search --query "project" --chat-modes "topic"
+
+# Filter by member open_ids (with keyword)
+lark-cli im +chat-search --query "project" --member-ids "ou_xxx,ou_yyy"
+
+# Search by member open_ids only
+lark-cli im +chat-search --member-ids "ou_xxx,ou_yyy"
+
+# Only show chats you created or manage
+lark-cli im +chat-search --query "project" --is-manager
+
+# Set page size
+lark-cli im +chat-search --query "project" --page-size 10
+
+# Pagination
+lark-cli im +chat-search --query "project" --page-token "xxx"
+
+# JSON output
+lark-cli im +chat-search --query "project" --format json
+
+# Preview the request without executing it
+lark-cli im +chat-search --query "project" --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Limits | Description |
+|------|------|------|------|
+| `--query <keyword>` | No (at least one of `--query` / `--member-ids` required) | Max 64 characters | Search keyword. Supports matching localized chat names, member names, multilingual search, pinyin, and prefix fuzzy search. If the query contains `-`, it is automatically wrapped in quotes |
+| `--search-types <types>` | No | Comma-separated: `private`, `external`, `public_joined`, `public_not_joined` | Restrict the visible chat types returned by search |
+| `--chat-modes <modes>` | No | Comma-separated: `group`, `topic` | Filter by chat mode (server-side): `group` = regular group, `topic` = topic/thread group |
+| `--member-ids <ids>` | No (at least one of `--query` / `--member-ids` required) | Up to 50, format `ou_xxx` | Filter by member open_ids; can be used alone or combined with `--query` |
+| `--is-manager` | No | - | Only show chats you created or manage |
+| `--disable-search-by-user` | No | - | Disable member-name-based matching and search by group name only |
+| `--sort <field>` | No | `create_time`, `update_time`, `member_count` | Sort field (always descending) |
+| `--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 (mute is a per-user setting); 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.
+
+> **CAUTION:** `--sort` is **always descending** — the search API only ranks the chosen field high-to-low (e.g. `member_count` = most members first). There is no ascending option. If the user asks for "fewest first / ascending / 从少到多", tell them the search API does not support ascending order; any low-to-high view requires re-sorting the fetched page client-side and is not an upstream sort. Do **not** invent values like `member_count_asc` or pass `asc` (they are rejected).
+
+## Output Fields
+
+| Field | Description |
+|------|------|
+| `chat_id` | Chat ID (`oc_xxx` format) |
+| `name` | Chat name |
+| `description` | Chat description |
+| `owner_id` | Owner ID |
+| `external` | Whether the chat is external |
+| `chat_status` | Chat status (`normal` / `dissolved` / `dissolved_save`) |
+
+## Filtering muted chats
+
+`--exclude-muted` (user identity only) drops chats the current user has set to do-not-disturb. After the search 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": 19,
+    "filtered_count": 1,
+    "hint": "Filtered out 1 muted chat(s) on this page (19 remaining, including 2 non-member public group(s)); use --page-token to fetch more."
+  }
+}
+```
+
+Note: only confirmed-muted chats count toward `filtered_count`; non-member public groups are retained and surfaced in `hint`. For strict member-only results, combine with `--search-types "private,public_joined,external"`.
+
+## Usage Scenarios
+
+### Scenario 1: Search chats that contain a keyword
+
+```bash
+lark-cli im +chat-search --query "design review"
+```
+
+### Scenario 2: Search a chat and list recent messages
+
+```bash
+CHAT_ID=$(lark-cli im +chat-search --query "project" --format json | jq -r '.data.chats[0].chat_id')
+lark-cli im +chat-messages-list --chat-id "$CHAT_ID"
+```
+
+### Scenario 3: Search a chat and send a message
+
+```bash
+CHAT_ID=$(lark-cli im +chat-search --query "daily report" --format json | jq -r '.data.chats[0].chat_id')
+lark-cli im +messages-send --chat-id "$CHAT_ID" --text "Today's progress update"
+```
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| `--query and --member-ids cannot both be empty` | Both were omitted | Provide at least `--query` or `--member-ids` |
+| Empty results | No visible chats matched the keyword or filters | Relax the keyword or filters and try again |
+| `--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 |
+
+## AI Usage Guidance
+
+When the user asks to search chats, follow these rules:
+
+1. **At least one filter required:** `--query` and `--member-ids` cannot both be empty. Either alone or combined together are valid.
+2. **Search scope is limited:** only chats visible to the current user or bot can be found (joined chats plus public chats). This is not a global search over all chats.
+3. **Control result volume:** the result set may be large. Use `--page-size` deliberately.
+4. **Suggest follow-up actions:** after finding a chat, common next steps include listing recent messages (`im +chat-messages-list`) or sending a message (`im +messages-send`).
+5. **NEVER fall back to chats list:** If `+chat-search` returns empty results, do NOT attempt to use `+chat-list` or `GET /open-apis/im/v1/chats` as a fallback. The list API is not a search API — it returns all chats without keyword filtering and will not help locate the target chat. Instead, ask the user to refine the keyword or check whether the chat is visible to the current identity.
+
+## 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-update.md

@@ -0,0 +1,84 @@
+# im +chat-update
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Update a group's name or description. Supports both **TAT (bot)** and **UAT (user)** identity.
+
+This skill maps to the shortcut: `lark-cli im +chat-update` (internally calls `PUT /open-apis/im/v1/chats/:chat_id`).
+
+## Commands
+
+```bash
+# Update the group name
+lark-cli im +chat-update --chat-id oc_xxx --name "New Group Name"
+
+# Update the group description
+lark-cli im +chat-update --chat-id oc_xxx --description "Updated group description"
+
+# Update multiple fields at once
+lark-cli im +chat-update --chat-id oc_xxx \
+  --name "Q2 Project Team" \
+  --description "Owns Q2 goal tracking"
+
+# Preview the request without executing it
+lark-cli im +chat-update --chat-id oc_xxx --name "Test" --dry-run
+```
+
+## Parameters
+
+### Required
+
+| Parameter | Description |
+|------|------|
+| `--chat-id <oc_xxx>` | Group ID |
+
+### Optional Fields
+
+| Parameter | Limits | Description |
+|------|------|------|
+| `--name <name>` | Max 60 characters | Group name |
+| `--description <text>` | Max 100 characters | Group description |
+
+### Global Parameters
+
+| Parameter | Description |
+|------|------|
+| `--format json` | Output as JSON (default) |
+| `--dry-run` | Preview the request without executing it |
+
+## Usage Scenarios
+
+### Scenario 1: Rename a group and update its description
+
+```bash
+lark-cli im +chat-update --chat-id oc_xxx \
+  --name "Q2 Project Team" \
+  --description "Owns Q2 goal tracking"
+```
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| `invalid --chat-id: expected chat ID (oc_xxx)` | Invalid chat_id format | Use a valid `oc_xxx` chat ID |
+| `--name exceeds the maximum of 60 characters` | Group name too long | Shorten the name to 60 characters or fewer |
+| `--description exceeds the maximum of 100 characters` | Group description too long | Shorten the description to 100 characters or fewer |
+| `at least one field must be specified to update` | No update field was provided | Specify at least one field to update |
+| Permission denied (99991679) | Missing `im:chat:update` permission | Run `lark-cli auth login --scope "im:chat:update"` |
+| Non-owner/admin cannot update (232016/232002/232017) | Current identity is not the owner/admin | Try switching identity with `--as bot` or `--as user` |
+| Not in the group (232011) | The current user is not a member of the group | Use a member identity (`--as bot`) or join the group first |
+
+## AI Usage Guidance
+
+### Identity Selection
+
+`+chat-update` supports both user and bot identity (`--as user` / `--as bot`).
+
+Infer the group owner from context whenever possible (for example, if a bot just created the group, the owner is the bot) and use the matching identity directly. If ownership is unclear, query the group first and confirm `owner_id`.
+
+Identity choice should follow [Group Chat Identity Rules](lark-im-chat-identity.md): if the user explicitly specifies an identity, use it directly; otherwise infer the owner identity from context.
+
+## 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-feed-group-list-item.md

@@ -0,0 +1,68 @@
+# +feed-group-list-item
+
+> Shortcut for `lark-cli im +feed-group-list-item`. List the feed cards inside one feed group (tag), enriched with a readable `chat_name`.
+
+`+feed-group-list-item` is the only CLI surface for the `feed.groups.list_item` read API — there is no raw `feed.groups list_item` command. It resolves a human-readable `chat_name` for every feed card it returns: a v1 feed card's `feed_id` is always a chat ID (`oc_xxx`), so the shortcut issues a follow-up `POST /open-apis/im/v1/chats/batch_query` and injects `chat_name` into each entry of both `items[]` and `deleted_items[]`.
+
+## Identity
+
+User-only. Run with `--as user`.
+
+## Scopes
+
+Because chat-name resolution always runs, this shortcut needs **two** user scopes unconditionally:
+
+- `im:feed_group_v1:read` — to read the items
+- `im:chat:read` — to resolve names
+
+`chat_name` resolution always runs, so there is no single-scope, un-enriched path. For the other raw `feed.groups.*` methods, see [lark-im-feed-groups.md](lark-im-feed-groups.md).
+
+## Usage
+
+```bash
+# First page, enriched with chat names
+lark-cli im +feed-group-list-item --as user --feed-group-id ofg_xxx
+
+# Auto-paginate through everything within a time window
+lark-cli im +feed-group-list-item --as user --feed-group-id ofg_xxx \
+  --page-all --start-time 1767196800000 --end-time 1767200000000
+```
+
+## Flags
+
+| Flag | Required | Description |
+|---|---|---|
+| `--feed-group-id` | Yes | Feed group ID (`ofg_xxx`); path parameter |
+| `--page-size` | No | Records per page, 1–50 (default 50) |
+| `--page-token` | No | Continuation token for a specific page |
+| `--page-all` | No | Auto-paginate and merge all pages |
+| `--page-limit` | No | Max pages when `--page-all` is set, 1–1000 (default 20) |
+| `--start-time` | No | Update-time window start (Unix milliseconds as a decimal string) |
+| `--end-time` | No | Update-time window end (Unix milliseconds as a decimal string) |
+
+When `--page-token` is set explicitly, it wins over `--page-all` (you get exactly that page).
+
+## Output
+
+JSON keeps the raw envelope and adds `chat_name` to each resolvable item:
+
+```json
+{
+  "items": [
+    { "feed_id": "oc_abc", "feed_type": "chat", "update_time": "1767196800000", "chat_name": "Release Team" }
+  ],
+  "deleted_items": [
+    { "feed_id": "oc_def", "feed_type": "chat", "update_time": "1767196800000", "chat_name": "Old Channel" }
+  ],
+  "page_token": "",
+  "has_more": false
+}
+```
+
+A feed card whose chat cannot be resolved (soft-deleted or no permission) simply omits `chat_name` — the command still exits 0. p2p (direct) chats also omit `chat_name`: the server returns an empty `name` for them (the client UI shows the partner's display name instead); if a label is needed, fetch the chat via `chats/batch_query`, read `p2p_target_id`, and resolve it with a contact lookup.
+
+## See also
+
+- [lark-im-feed-groups.md](lark-im-feed-groups.md) — raw `feed.groups.*` APIs, enums, and rule guidance
+- [lark-im-feed-group-list.md](lark-im-feed-group-list.md) — list your feed groups
+- [lark-im-feed-group-query-item.md](lark-im-feed-group-query-item.md) — look up specific feed cards by ID

package/skills/lark-im/references/lark-im-feed-group-list.md

@@ -0,0 +1,65 @@
+# +feed-group-list
+
+> Shortcut for `lark-cli im +feed-group-list`. List the caller's feed groups (tags) with auto-pagination that correctly merges both the live and soft-deleted lists.
+
+`+feed-group-list` is the only CLI surface for listing feed groups — there is no raw `feed.groups list` command. The list response carries two parallel arrays — `groups` (live) and `deleted_groups` (soft-deleted). The shortcut paginates this dual-list response correctly: its `--page-all` merges **both** arrays across pages (a naive single-array pager would silently drop one list's later pages). It adds no enrichment.
+
+## Identity
+
+User-only. Run with `--as user`.
+
+## Scopes
+
+- `im:feed_group_v1:read`
+
+## Usage
+
+```bash
+# First page
+lark-cli im +feed-group-list --as user
+
+# Auto-paginate through all your feed groups (both live and deleted)
+lark-cli im +feed-group-list --as user --page-all
+
+# Within an update-time window
+lark-cli im +feed-group-list --as user --page-all \
+  --start-time 1767196800000 --end-time 1767200000000
+```
+
+## Flags
+
+| Flag | Required | Description |
+|---|---|---|
+| `--page-size` | No | Records per page, 1–50 (default 50). Caps the combined `groups` + `deleted_groups` count, so a page may hold fewer live groups than the size suggests |
+| `--page-token` | No | Continuation token for a specific page |
+| `--page-all` | No | Auto-paginate and merge all pages (both lists) |
+| `--page-limit` | No | Max pages when `--page-all` is set, 1–1000 (default 20) |
+| `--start-time` | No | Update-time window start (Unix milliseconds as a decimal string) |
+| `--end-time` | No | Update-time window end (Unix milliseconds as a decimal string) |
+
+When `--page-token` is set explicitly, it wins over `--page-all` (you get exactly that page).
+
+## Output
+
+JSON keeps the raw envelope; with `--page-all` both lists are returned fully merged:
+
+```json
+{
+  "groups": [
+    { "group_id": "ofg_xxx", "type": "normal", "name": "Releases", "rules": { "rules": [] } }
+  ],
+  "deleted_groups": [
+    { "group_id": "ofg_yyy", "type": "rule", "name": "Old", "rules": { "rules": [] } }
+  ],
+  "page_token": "",
+  "has_more": false
+}
+```
+
+> `page_size` counts live and deleted groups together, and the per-page count can be smaller still when entries are filtered — so never infer completeness from counts. Pagination is governed solely by `has_more`.
+
+## See also
+
+- [lark-im-feed-groups.md](lark-im-feed-groups.md) — raw `feed.groups.*` APIs, enums, and rule guidance
+- [lark-im-feed-group-list-item.md](lark-im-feed-group-list-item.md) — list the feed cards inside one group
+- [lark-im-feed-group-query-item.md](lark-im-feed-group-query-item.md) — look up specific feed cards by ID

package/skills/lark-im/references/lark-im-feed-group-query-item.md

@@ -0,0 +1,44 @@
+# +feed-group-query-item
+
+> Shortcut for `lark-cli im +feed-group-query-item`. Look up specific feed cards inside one feed group (tag) by ID, enriched with a readable `chat_name`.
+
+`+feed-group-query-item` is the only CLI surface for the `feed.groups.batch_query_item` read API — there is no raw `feed.groups batch_query_item` command. It resolves a human-readable `chat_name` for every feed card it returns: a v1 feed card's `feed_id` is always a chat ID (`oc_xxx`), so the shortcut issues a follow-up `POST /open-apis/im/v1/chats/batch_query` and injects `chat_name` into each entry of both `items[]` and `deleted_items[]`.
+
+## Identity
+
+User-only. Run with `--as user`.
+
+## Scopes
+
+Because chat-name resolution always runs, this shortcut needs **two** user scopes unconditionally:
+
+- `im:feed_group_v1:read` — to read the items
+- `im:chat:read` — to resolve names
+
+`chat_name` resolution always runs, so there is no single-scope, un-enriched path. For the other raw `feed.groups.*` methods, see [lark-im-feed-groups.md](lark-im-feed-groups.md).
+
+## Usage
+
+```bash
+lark-cli im +feed-group-query-item --as user \
+  --feed-group-id ofg_xxx --feed-id oc_a,oc_b
+```
+
+## Flags
+
+| Flag | Required | Description |
+|---|---|---|
+| `--feed-group-id` | Yes | Feed group ID (`ofg_xxx`); path parameter |
+| `--feed-id` | Yes | Comma-separated chat IDs (`oc_xxx`); `feed_type` is fixed to `chat` |
+
+## Output
+
+The command sends `{"items":[{"feed_id":"oc_a","feed_type":"chat"},{"feed_id":"oc_b","feed_type":"chat"}]}`, then enriches the response (`items[]` and `deleted_items[]`) with `chat_name` exactly as `+feed-group-list-item` does. There is no pagination for this method.
+
+A feed card whose chat cannot be resolved (soft-deleted or no permission) simply omits `chat_name` — the command still exits 0. p2p (direct) chats also omit `chat_name`: the server returns an empty `name` for them (the client UI shows the partner's display name instead); if a label is needed, fetch the chat via `chats/batch_query`, read `p2p_target_id`, and resolve it with a contact lookup.
+
+## See also
+
+- [lark-im-feed-groups.md](lark-im-feed-groups.md) — raw `feed.groups.*` APIs, enums, and rule guidance
+- [lark-im-feed-group-list.md](lark-im-feed-group-list.md) — list your feed groups
+- [lark-im-feed-group-list-item.md](lark-im-feed-group-list-item.md) — list all feed cards in a group (paginated)