@yandy0725/pi-lark 0.1.0

package/skills/lark-im/references/lark-im-feed-groups.md

@@ -0,0 +1,452 @@
+# im feed.groups
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+This reference is the shared annotation target for the IM feed-group (tag) APIs: it documents what each method does, the `--params` / `--data` request and response shapes, and the enum surface used in payloads. The full method list is in [Command Overview](#command-overview) below.
+
+> **Important:** The six raw commands (`create`, `update`, `delete`, `batch_query`, `batch_add_item`, `batch_remove_item`) take structured input through `--params '<json>'` and `--data '<json>'` rather than typed flags. The three read methods (`list`, `list_item`, `batch_query_item`) are exposed only as typed `+` shortcut wrappers — see [Shortcuts](#shortcuts). All methods are user-only; see [Common Notes](#common-notes).
+
+> **Picking a read method:** `batch_query` / `+feed-group-query-item` are lightweight ID lookups; `+feed-group-list` / `+feed-group-list-item` paginate the whole set and are much heavier. When you already hold the IDs (`group_id` from `create`, the `feed_id`s you passed to `batch_add_item`), prefer the lightweight lookup. Reserve the list methods for when you actually need to discover IDs you don't have.
+
+## Command Overview
+
+| Method | Purpose |
+|---|---|
+| `feed.groups.create` | Create a new feed group (tag) |
+| `feed.groups.update` | Update a feed group's name and/or rules |
+| `feed.groups.delete` | Delete one feed group |
+| `feed.groups.batch_query` | Look up feed groups by ID list |
+| `feed.groups.list` | List the caller's feed groups with optional time-range filter — **CLI: only via `+feed-group-list` shortcut** |
+| `feed.groups.batch_add_item` | Add feed cards (chats) into a feed group |
+| `feed.groups.batch_remove_item` | Remove feed cards from a feed group |
+| `feed.groups.batch_query_item` | Look up feed cards inside a group by ID list — **CLI: only via `+feed-group-query-item` shortcut** |
+| `feed.groups.list_item` | List feed cards inside one feed group — **CLI: only via `+feed-group-list-item` shortcut** |
+
+> HTTP method and path are not duplicated here. For the six raw methods, inspect them with `lark-cli schema im.feed.groups.<method>` when needed; the three shortcut-only read methods (`list`, `list_item`, `batch_query_item`) use typed flags (see their `--help`).
+
+## Shortcuts
+
+Three typed `+` shortcuts cover the feed-group read paths. All are user-only.
+
+| Shortcut | Purpose | Notes |
+|---|---|---|
+| [`+feed-group-list`](lark-im-feed-group-list.md) | List your feed groups | Its `--page-all` correctly merges the live and soft-deleted lists. No enrichment |
+| [`+feed-group-list-item`](lark-im-feed-group-list-item.md) | List the feed cards inside a group | Enriches each card with `chat_name` |
+| [`+feed-group-query-item`](lark-im-feed-group-query-item.md) | Look up feed cards in a group by ID | Enriches each card with `chat_name` |
+
+The two `*-item` shortcuts resolve `chat_name` via a follow-up `chats/batch_query`, so they need `im:chat:read` in addition to `im:feed_group_v1:read`; `+feed-group-list` needs only `im:feed_group_v1:read`. All three are the **only** CLI surface for their methods — `list`, `list_item`, and `batch_query_item` have no raw command; full flags and response shapes live in the shortcut docs linked above.
+
+## Common Notes
+
+- `feed_group_id` is the feed-group identifier returned by `create`, typically formatted as `ofg_xxx`. It is an opaque string — the group's stable ID.
+- `feed_id` is the identifier of one feed card inside a group. In v1 only the `chat` feed card type is supported (see `feed_card_type` below), so `feed_id` is currently a chat ID such as `oc_xxx`.
+- All `feed.groups.*` methods require `user_access_token`. Run with `--as user`; bot/tenant tokens are rejected.
+- Read APIs (`batch_query`, `list`, `batch_query_item`, `list_item`) return **two parallel lists**: a live list (`groups[]` or `items[]`) and a soft-deleted list (`deleted_groups[]` or `deleted_items[]`). Consumers tracking incremental sync should consume both.
+- Time-range fields (`start_time`, `end_time`, `update_time`) are Unix timestamps **in milliseconds**, encoded as decimal strings (e.g. `1767196800000`).
+- Rule-based feed groups (`type=rule`) auto-populate from the rules declared in `feed_group_creator.rules`. Normal feed groups (`type=normal`) are managed explicitly via `batch_add_item` / `batch_remove_item`.
+
+> **Choose the simplest group that fits** — it keeps `create` / `update` fast and predictable. Apply these in order:
+> 1. **Prefer `type=normal`.** When the target chats are known up front, set membership explicitly with `batch_add_item` / `batch_remove_item`. Use `type=rule` only when membership must be derived automatically.
+> 2. **Keep the rule set smallest.** Use the fewest `rules[]` and `condition_items[]` that express the intent (one condition is ideal). This outranks the style rules below — never split a rule or add conditions just to satisfy them (e.g. one `match_any` rule beats two single-condition rules for "A or B").
+> 3. **Within that, make each condition precise.** Prefer positive, specific conditions (`is`, or `contain` with a distinctive keyword) over exclusion (`is_not`, `not_contain`) or broad keywords, which capture more than intended. For a multi-condition rule, prefer `match_all` (narrower) over `match_any` (wider).
+
+## Inspect Schema
+
+```bash
+lark-cli schema im.feed.groups
+lark-cli schema im.feed.groups.create --format pretty
+lark-cli schema im.feed.groups.batch_add_item --format pretty
+```
+
+> `list`, `list_item`, and `batch_query_item` have no raw method schema (they are shortcut-only). Inspect their flags with `lark-cli im +feed-group-list --help` / `+feed-group-list-item --help` / `+feed-group-query-item --help` instead.
+
+## create
+
+Create a new feed group. Returns the new `group_id` on success.
+
+> **Prefer `type=normal`.** Use `type=rule` only when membership must be derived automatically, and keep the rule set small and precise — see the guidance under [Common Notes](#common-notes).
+
+```bash
+# Normal (empty) group
+lark-cli im feed.groups create --as user \
+  --data '{"feed_group_creator":{"type":"normal","name":"Releases"}}'
+
+# Rule-based group: auto-add p2p chats with "release" in their name
+lark-cli im feed.groups create --as user \
+  --data '{
+    "feed_group_creator":{
+      "type":"rule",
+      "name":"Auto: release chats",
+      "rules":{
+        "rules":[
+          {
+            "condition":{
+              "match_type":"match_all",
+              "condition_items":[
+                {"type":"chat_type","operator":"is","chat_type":"p2p"},
+                {"type":"keyword","operator":"contain","keyword":"release"}
+              ]
+            },
+            "action":"add"
+          }
+        ]
+      }
+    }
+  }'
+```
+
+### Request
+
+#### `--params`
+
+| Parameter | Required | Description |
+|---|---|---|
+| `user_id_type` | No | ID type used when the request body contains `user_id` references inside rules. One of `open_id`, `union_id`, `user_id` |
+
+#### `--data`
+
+| Field | Required | Description |
+|---|---|---|
+| `feed_group_creator.type` | Yes | `normal` (empty group) or `rule` (auto-populated by rules) |
+| `feed_group_creator.name` | Yes | Display name, e.g. `"标签名称测试"` |
+| `feed_group_creator.rules` | No | Rule object (required when `type=rule`). See `feed_group_rules` section below |
+
+### Response
+
+```json
+{
+  "group_id": "ofg_xxx"
+}
+```
+
+## update
+
+Update a feed group's name and/or rules. The `update_fields` array tells the server which fields are being updated.
+
+> **Scope each update to what actually changed.** If you only need to rename, pass `update_fields:[1]` so the rules are left untouched. When you do change rules, the same guidance under [Common Notes](#common-notes) applies to the resulting set.
+
+```bash
+# Rename only
+lark-cli im feed.groups update --as user \
+  --params '{"feed_group_id":"ofg_xxx"}' \
+  --data '{"feed_group_updater":{"name":"测试标签名称","update_fields":[1]}}'
+
+# Replace rules only (rules array uses the feed_group_rules shape — see that section)
+lark-cli im feed.groups update --as user \
+  --params '{"feed_group_id":"ofg_xxx"}' \
+  --data '{
+    "feed_group_updater":{
+      "rules":{"rules":[]},
+      "update_fields":[2]
+    }
+  }'
+```
+
+### Request
+
+#### `--params`
+
+| Parameter | Required | Description |
+|---|---|---|
+| `feed_group_id` | Yes | Path parameter — the feed group to update |
+| `user_id_type` | No | ID type for any `user_id` fields inside `rules` |
+
+#### `--data`
+
+| Field | Required | Description |
+|---|---|---|
+| `feed_group_updater.name` | No | New display name |
+| `feed_group_updater.rules` | No | Replacement rule object. Same structure as `create.feed_group_creator.rules` |
+| `feed_group_updater.update_fields` | No | Array of integer update markers: `1` = name, `2` = rules. Server applies only the listed fields |
+
+### Response
+
+Empty body on success. Inspect the CLI exit code for status.
+
+## delete
+
+Delete one feed group.
+
+```bash
+lark-cli im feed.groups delete --as user \
+  --params '{"feed_group_id":"ofg_xxx"}'
+```
+
+### Request
+
+| Parameter | Required | Description |
+|---|---|---|
+| `feed_group_id` | Yes | Path parameter — the feed group to delete |
+
+### Response
+
+Empty body on success.
+
+## batch_query
+
+Look up feed groups by an explicit list of IDs. Returns both live and soft-deleted matches.
+
+```bash
+lark-cli im feed.groups batch_query --as user \
+  --params '{"user_id_type":"open_id"}' \
+  --data '{"group_ids":["ofg_xxx","ofg_yyy"]}'
+```
+
+### Request
+
+#### `--params`
+
+| Parameter | Required | Description |
+|---|---|---|
+| `user_id_type` | No | ID type used when the response includes `user_id` references inside `groups[].rules` |
+
+#### `--data`
+
+| Field | Required | Description |
+|---|---|---|
+| `group_ids` | Yes | Array of feed group IDs to look up |
+
+### Response
+
+```json
+{
+  "groups": [
+    {
+      "group_id": "ofg_xxx",
+      "type": "normal",
+      "name": "test",
+      "rules": { "rules": [] }
+    }
+  ],
+  "deleted_groups": [
+    {
+      "group_id": "ofg_yyy",
+      "type": "rule",
+      "name": "test",
+      "rules": { "rules": [] }
+    }
+  ]
+}
+```
+
+Each `rules.rules[]` element follows the `feed_group_rules` shape — see that section for the full structure.
+
+### Top-Level Fields
+
+| Field | Type | Meaning |
+|---|---|---|
+| `groups` | `array<object>` | Live feed groups for the requested IDs |
+| `deleted_groups` | `array<object>` | Soft-deleted matches, returned for incremental-sync clients |
+
+Each element carries `group_id`, `type`, `name`, and (when defined) `rules`.
+
+## list
+
+Shortcut-only: [`+feed-group-list`](lark-im-feed-group-list.md). Lists the caller's feed groups, optionally filtered by an update-time window. Its `--page-all` correctly merges the live (`groups`) and soft-deleted (`deleted_groups`) lists across pages. There is no raw command — flags and response shape are in the linked shortcut doc.
+
+## batch_add_item
+
+Add feed cards (chats) into one feed group. Partial failures are reported in `failed_items`.
+
+```bash
+lark-cli im feed.groups batch_add_item --as user \
+  --params '{"feed_group_id":"ofg_xxx"}' \
+  --data '{
+    "items":[
+      {"feed_id":"oc_xxx","feed_type":"chat"},
+      {"feed_id":"oc_yyy","feed_type":"chat"}
+    ]
+  }'
+```
+
+### Request
+
+| Source | Field | Required | Description |
+|---|---|---|---|
+| `--params` | `feed_group_id` | Yes | Path parameter — the target feed group |
+| `--data` | `items[]` | Yes | Array of feed cards to add |
+| `--data` | `items[].feed_id` | No | The chat ID to add (e.g. `oc_xxx`) |
+| `--data` | `items[].feed_type` | Yes (`"chat"` only) | Wire-typed as an open string. v1 OAPI service accepts only `chat`; anything else is rejected at runtime. See the Enums section. |
+
+> Note: `items[].feed_id` is not marked as required in the API schema, but every element of `items` must set it — a missing field yields an unusable entry. Always pass `{"feed_id": "oc_xxx", "feed_type": "chat"}` per item.
+
+### Response
+
+```json
+{
+  "failed_items": [
+    {
+      "item": { "feed_id": "oc_xxx", "feed_type": "chat" },
+      "error_code": 240001,
+      "error_message": "feed_id is invalid"
+    }
+  ]
+}
+```
+
+| Field | Type | Meaning |
+|---|---|---|
+| `failed_items` | `array<object>` | Items that failed; absent or empty means all succeeded |
+| `failed_items[].item` | `object` | The original `{feed_id, feed_type}` element |
+| `failed_items[].error_code` | `integer` | Numeric error code |
+| `failed_items[].error_message` | `string` | Human-readable failure reason |
+
+## batch_remove_item
+
+Remove feed cards from one feed group. Same request and response shape as `batch_add_item`.
+
+```bash
+lark-cli im feed.groups batch_remove_item --as user \
+  --params '{"feed_group_id":"ofg_xxx"}' \
+  --data '{
+    "items":[
+      {"feed_id":"oc_xxx","feed_type":"chat"}
+    ]
+  }'
+```
+
+### Request
+
+| Source | Field | Required | Description |
+|---|---|---|---|
+| `--params` | `feed_group_id` | Yes | Path parameter — the target feed group |
+| `--data` | `items[]` | Yes | Array of feed cards to remove |
+| `--data` | `items[].feed_id` | No | The chat ID to remove |
+| `--data` | `items[].feed_type` | Yes (`"chat"` only) | Wire-typed as an open string. v1 OAPI service accepts only `chat`; anything else is rejected at runtime. See the Enums section. |
+
+> Note: same caveat as `batch_add_item` — `items[].feed_id` is optional per the API schema but must be present in practice.
+
+### Response
+
+Identical shape to `batch_add_item` — `failed_items[]` lists rows that did not remove cleanly.
+
+## batch_query_item
+
+Shortcut-only: [`+feed-group-query-item`](lark-im-feed-group-query-item.md). Looks up feed cards in a group by an explicit ID list and enriches each with `chat_name`. There is no raw command — flags and response shape are in the linked shortcut doc.
+
+## list_item
+
+Shortcut-only: [`+feed-group-list-item`](lark-im-feed-group-list-item.md). Lists the feed cards inside a group (paginated, `--page-all` supported) and enriches each with `chat_name`. There is no raw command — flags and response shape are in the linked shortcut doc.
+
+## Enums
+
+All enum values listed here are exhaustive.
+
+### `feed_group_type`
+
+Used in `feed_group_creator.type` and the response `groups[].type`.
+
+- `normal` — empty group; members managed explicitly via `batch_add_item` / `batch_remove_item`.
+- `rule` — auto-populated; `feed_group_creator.rules` must be supplied.
+
+### `feed_card_type`
+
+Used in `items[].feed_type` everywhere a feed card appears. Wire type is an open string.
+
+- `chat` — the only value the v1 OAPI service accepts. `feed_id` is therefore a chat ID such as `oc_xxx`.
+
+The CLI does not pre-validate this field — passing anything other than `chat` reaches the server and is rejected at runtime. Treat `chat` as effectively required.
+
+### `feed_group_rule_action`
+
+Used inside `feed_group_rules.rules[].action`.
+
+- `add` — when the condition matches, add the matching feed into this group.
+- `remove` — when the condition matches, remove the matching feed from this group.
+
+### `feed_group_rule_cond_match_type`
+
+Used inside `feed_group_rules.rules[].condition.match_type`.
+
+- `match_all` — every condition item must match.
+- `match_any` — at least one condition item must match.
+
+### `feed_group_rule_cond_item_type`
+
+Used inside `feed_group_rules.rules[].condition.condition_items[].type`. Determines which sibling field of the item is consulted.
+
+- `keyword` — match against a keyword; consult the `keyword` field.
+- `chatter` — match against a user; consult the `user_id` field (interpreted per the request's `user_id_type`).
+- `chat_type` — match against a chat type; consult the `chat_type` field.
+
+### `feed_group_rule_cond_item_operator`
+
+Used inside `feed_group_rules.rules[].condition.condition_items[].operator`. Typically paired with the relevant `type`:
+
+- `contain` — substring match; typically paired with `keyword`.
+- `not_contain` — substring non-match; typically paired with `keyword`.
+- `is` — equality; typically paired with `chatter` or `chat_type`.
+- `is_not` — non-equality; typically paired with `chatter` or `chat_type`.
+
+### `feed_group_rule_cond_item_chat_type`
+
+Used inside `feed_group_rules.rules[].condition.condition_items[].chat_type` when `type=chat_type`.
+
+- `p2p`
+- `group`
+- `thread_group`
+- `helpdesk`
+- `bot`
+- `mute`
+- `flag`
+- `cross_tenant`
+- `any`
+
+### `update_fields`
+
+Used inside `feed_group_updater.update_fields`. Multiple values may be listed.
+
+- `1` — update name only.
+- `2` — update rules only.
+
+Wire form: integers (`1` = name, `2` = rules). The server rejects the lowercase string forms (`"name"`, `"rules"`) with `9499 Invalid parameter value`. Omit the array (or pass an empty array) to make no field updates.
+
+## feed_group_rules
+
+The same nested object is used in `feed_group_creator.rules` (create), `feed_group_updater.rules` (update), and in read responses under `groups[].rules`. Shape:
+
+```json
+{
+  "rules": [
+    {
+      "condition": {
+        "match_type": "match_all",
+        "condition_items": [
+          { "type": "chat_type", "operator": "is", "chat_type": "group" },
+          { "type": "keyword",   "operator": "contain", "keyword": "release" }
+        ]
+      },
+      "action": "add"
+    }
+  ]
+}
+```
+
+Per-`type` required-field legend:
+
+- `type=keyword` → `keyword` is required; `user_id` and `chat_type` are ignored.
+- `type=chatter` → `user_id` is required; the request's `user_id_type` query parameter tells the server how to interpret it.
+- `type=chat_type` → `chat_type` is required.
+
+## Permissions
+
+| Method | Scope |
+|---|---|
+| `feed.groups.create` | `im:feed_group_v1:write` |
+| `feed.groups.update` | `im:feed_group_v1:write` |
+| `feed.groups.delete` | `im:feed_group_v1:write` |
+| `feed.groups.batch_query` | `im:feed_group_v1:read` |
+| `feed.groups.batch_add_item` | `im:feed_group_v1:write` |
+| `feed.groups.batch_remove_item` | `im:feed_group_v1:write` |
+
+The three read methods are shortcut-only:
+
+- [`+feed-group-list`](lark-im-feed-group-list.md) — `im:feed_group_v1:read`
+- [`+feed-group-list-item`](lark-im-feed-group-list-item.md) / [`+feed-group-query-item`](lark-im-feed-group-query-item.md) — `im:feed_group_v1:read` **plus** `im:chat:read` (they always resolve `chat_name`)
+
+If a required scope is missing, the CLI surfaces a hint such as `lark-cli auth login --scope "im:feed_group_v1:write"`.
+
+## 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-shortcut-create.md

@@ -0,0 +1,97 @@
+# im +feed-shortcut-create
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) for authentication, global parameters, and security rules.
+
+This skill maps to shortcut: `lark-cli im +feed-shortcut-create`. Underlying API: `POST /open-apis/im/v2/feed_shortcuts`.
+
+## What it does
+
+Adds one or more chats to the **current user's** feed shortcuts — equivalent to right-clicking a chat in the Feishu client and pinning it to the feed sidebar.
+
+- Only **CHAT-type** shortcuts are exposed by the OpenAPI gateway right now (`feed_card_id` must be an `oc_xxx` open_chat_id).
+- Batch up to **10 chat IDs per call**; pass more by issuing multiple calls.
+- Currently only supports **user identity** (`--as user`); bot identity is not allowed by the server.
+- If you only know a group name, resolve its `oc_xxx` first with `im +chat-search` or `im +chat-list`.
+
+## Commands
+
+```bash
+# Add a single chat as a feed shortcut (defaults to head/top insertion)
+lark-cli im +feed-shortcut-create --as user --chat-id oc_xxx
+
+# Add multiple chats; comma-separated or repeated flag both work
+lark-cli im +feed-shortcut-create --as user --chat-id oc_a,oc_b,oc_c
+lark-cli im +feed-shortcut-create --as user --chat-id oc_a --chat-id oc_b
+
+# Append at the bottom of the shortcut list instead of the top
+lark-cli im +feed-shortcut-create --as user --chat-id oc_xxx --tail
+
+# Preview the request without sending
+lark-cli im +feed-shortcut-create --as user --chat-id oc_xxx --dry-run
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|------|------|------|
+| `--chat-id <oc_xxx>` | required | open_chat_id to add as a feed shortcut; repeatable or comma-separated; **max 10 per call** |
+| `--head` | true (implied) | Insert at the top of the shortcut list; mutually exclusive with `--tail` |
+| `--tail` | false | Append at the bottom of the shortcut list |
+| `--as user` | required | Server only accepts user_access_token for this API |
+
+## Response
+
+The response is a batch ledger. A full success exits `0` with `ok:true`. Any non-empty `failed_shortcuts` is a partial failure: the process exits non-zero (currently exit `1`), stdout carries `ok:false`, and the full ledger remains machine-readable:
+
+| Field | Meaning |
+|------|------|
+| `total` | Number of requested shortcuts |
+| `success_count` | Number of requested shortcuts not reported in `failed_shortcuts` |
+| `failure_count` | Number of requested shortcuts reported as failed; `failed_shortcuts` preserves the raw server failure list |
+| `succeeded_shortcuts` | Requested shortcut entries that succeeded |
+| `failed_shortcuts` | Per-item failures returned by the server, enriched with `reason_label` |
+
+The shortcut adds a `reason_label` field next to each numeric `reason`:
+
+| `reason` | `reason_label` | Meaning |
+|---:|------|------|
+| 1 | `no_permission` | User has no permission on the feed card |
+| 2 | `invalid_item` | `feed_card_id` is invalid or type doesn't match |
+| 3 | `has_pending_delete` | The chat is being deleted |
+| 4 | `type_not_support` | Type is not whitelisted (only CHAT is open now) |
+| 5 | `internal_error` | Server internal error |
+
+Example:
+
+```json
+{
+  "ok": false,
+  "data": {
+    "total": 2,
+    "success_count": 1,
+    "failure_count": 1,
+    "succeeded_shortcuts": [
+      { "feed_card_id": "oc_good", "type": 1 }
+    ],
+    "failed_shortcuts": [
+      {
+        "shortcut": { "feed_card_id": "oc_bad", "type": 1 },
+        "reason": 2,
+        "reason_label": "invalid_item"
+      }
+    ]
+  }
+}
+```
+
+## Permissions
+
+- Required scope: `im:feed.shortcut:write`
+- Only available with user identity (`--as user`). The CLI will reject `--as bot` for this shortcut.
+
+## Note
+
+- The shortcut list is **per user**: the call adds shortcuts for the currently authenticated user only.
+- Adding the same chat twice is **idempotent at the user level** (re-adding an existing shortcut is a no-op rather than an error).
+- Scripts should check the process exit code, top-level `ok`, and ledger counts. Partial failures intentionally keep machine-readable success and failure details on stdout.
+- To inspect the current shortcut list, use [`+feed-shortcut-list`](lark-im-feed-shortcut-list.md). To remove a shortcut, use [`+feed-shortcut-remove`](lark-im-feed-shortcut-remove.md).

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

@@ -0,0 +1,103 @@
+# im +feed-shortcut-list
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) for authentication, global parameters, and security rules.
+
+This skill maps to shortcut: `lark-cli im +feed-shortcut-list`. Underlying API: `GET /open-apis/im/v2/feed_shortcuts`.
+
+## What it does
+
+Lists **one page** of the **current user's** feed shortcuts.
+
+- Only **CHAT-type** shortcuts are exposed via OpenAPI today (others in the IDL are not yet whitelisted).
+- The shortcut is a **thin one-page wrapper** — there is no built-in auto-pagination. Callers drive their own loop when they actually need to paginate.
+- Server-side page size is controlled by the service; in normal use one page usually covers the list.
+- Pagination tokens are opaque. If a token is rejected because the shortcut list changed, restart by omitting `--page-token`.
+
+## Commands
+
+```bash
+# First page (the only call most users ever need — --page-token omitted)
+lark-cli im +feed-shortcut-list --as user
+
+# Continue from the previous response's page_token
+lark-cli im +feed-shortcut-list --as user --page-token <token-from-previous-response>
+
+# Skip detail enrichment when only IDs are needed; avoids the extra im:chat:read lookup
+lark-cli im +feed-shortcut-list --as user --no-detail -q '.data.shortcuts[].feed_card_id'
+```
+
+> If you need to walk every page, write the loop yourself: read `data.page_token` from each response and pass it back in until `has_more=false`. The shortcut intentionally does not auto-walk because page-token errors require the caller to decide whether to restart from the first page.
+
+## Parameters
+
+| Parameter | Required | Description |
+|------|------|------|
+| `--page-token <token>` | no | Opaque pagination token from the previous response. **Omit it for the first page.** |
+| `--no-detail` | no (default `false`) | Skip fetching each entry's full info object. By default enrichment is enabled: CHAT-type entries call `im.chats.batch_query`, need `im:chat:read`, and attach the object under the `detail` field. Pass `--no-detail` to skip the extra call and scope. |
+| `--as user` | yes | Server only accepts user_access_token for this API |
+
+## Response Structure
+
+| Field | Type | Description |
+|------|------|------|
+| `shortcuts` | array | Feed shortcut entries; each has `feed_card_id` (oc_xxx) and `type` (1=CHAT). By default (without `--no-detail`), each entry also has a `detail` field with the full per-type info object. |
+| `has_more` | boolean | Whether more pages exist |
+| `page_token` | string | Opaque token to pass to the next call when continuing pagination |
+
+Example (with detail enrichment, CHAT type):
+
+```json
+{
+  "data": {
+    "shortcuts": [
+      {
+        "feed_card_id": "oc_092f0100fe59c35995727db1039777a8",
+        "type": 1,
+        "detail": {
+          "chat_id": "oc_092f0100fe59c35995727db1039777a8",
+          "chat_mode": "group",
+          "name": "Engineering",
+          "avatar": "https://...",
+          "description": "",
+          "external": false,
+          "owner_id": "ou_xxx",
+          "owner_id_type": "open_id",
+          "tenant_key": "..."
+        }
+      },
+      {
+        "feed_card_id": "oc_c82061d126a06635aa3569587b134bb1",
+        "type": 1,
+        "detail": {
+          "chat_id": "oc_c82061d126a06635aa3569587b134bb1",
+          "chat_mode": "p2p",
+          "name": "",
+          "p2p_target_id": "ou_xxx",
+          "p2p_target_type": "user",
+          "avatar": "",
+          "description": "",
+          "external": false,
+          "tenant_key": "..."
+        }
+      }
+    ],
+    "has_more": false,
+    "page_token": "v1.example-opaque-token"
+  }
+}
+```
+
+## Detail Enrichment
+
+The `detail` payload is dispatched **per `type`**. Today only CHAT is wired in; future shortcut types can attach different object shapes. Callers should `switch` on `type` before parsing `detail`. For CHAT (`type=1`):
+
+- **Source**: `POST /open-apis/im/v1/chats/batch_query` (50 ids per call, server limit).
+- **Payload**: the **full chat object** is passed through verbatim — `chat_id`, `chat_mode` (`group` / `p2p` / `topic`), `name`, `avatar`, `description`, `external`, `tenant_key`, plus type-specific fields (`owner_id*` for groups, `p2p_target_*` for p2p).
+- **P2P chats** return an empty `name` because the Feishu client renders the partner's display name there. The rest of the object (especially `p2p_target_id`) still flows through, so callers can resolve the partner via `+contact-search` if a display title is needed.
+- **Lookup failure** (missing scope, network error) → the list still returns successfully; a warning is printed to stderr, the data payload carries a `_notice` field (`"detail enrichment skipped: ..."`), and affected entries simply lack the `detail` field. Check `_notice` to tell "enrichment skipped" from "nothing to enrich".
+
+## Permissions
+
+- Required scope: `im:feed.shortcut:read`
+- Conditional scope (default detail path only): `im:chat:read`; pass `--no-detail` to avoid this extra scope and lookup.
+- Only available with user identity (`--as user`).