Skip to content

Pinvou/pinvou-agent / pinvou3-app/src-tauri/resources/common/bundle/lark-skills/lark-im

lark-im

Verified

【何时用:仅当用户明确指向飞书/Lark(发到飞书、飞书文档等)时使用;泛指做个文档或PPT或表格或方案默认走本地工具,不要误用飞书】飞书即时通讯:收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件、管理表情回复、发送应用内/短信/电话加急、发送和处理交互卡片(Interactive Card)与卡片按钮回调(card.action.trigger)。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索或创建群聊/话题群、管理标记数据、Feed 置顶与标签数据、处理卡片回调时使用。

FileKindSize
SKILL.mdskill md24.6 KB
references/card/card-2.0-schema.mdmarkdown6.0 KB
references/card/components/button.mdmarkdown2.8 KB
references/card/components/chart.mdmarkdown2.2 KB
references/card/components/checker.mdmarkdown1.9 KB
references/card/components/collapsible_panel.mdmarkdown1.8 KB
references/card/components/column_set.mdmarkdown2.5 KB
references/card/components/date_picker.mdmarkdown1.6 KB
references/card/components/div.mdmarkdown1.7 KB
references/card/components/form.mdmarkdown2.2 KB
references/card/components/header.mdmarkdown1.6 KB
references/card/components/hr.mdmarkdown425 B
references/card/components/img.mdmarkdown1.4 KB
references/card/components/img_combination.mdmarkdown1.0 KB
references/card/components/input.mdmarkdown2.0 KB
references/card/components/interactive_container.mdmarkdown2.2 KB
references/card/components/markdown.mdmarkdown3.2 KB
references/card/components/multi_select_person.mdmarkdown1.6 KB
references/card/components/multi_select_static.mdmarkdown1.6 KB
references/card/components/overflow.mdmarkdown1.5 KB
references/card/components/person.mdmarkdown907 B
references/card/components/person_list.mdmarkdown1.2 KB
references/card/components/picker_datetime.mdmarkdown1.5 KB
references/card/components/picker_time.mdmarkdown1.5 KB
references/card/components/recycling_container.mdmarkdown1.5 KB
references/card/components/select_img.mdmarkdown1.9 KB
references/card/components/select_person.mdmarkdown1.5 KB
references/card/components/select_static.mdmarkdown1.8 KB
references/card/components/table.mdmarkdown2.1 KB
references/card/lark-im-card-create.mdmarkdown10.8 KB
references/card/lark-im-card-style.mdmarkdown18.3 KB
references/card/resource/colors.mdmarkdown1.4 KB
references/card/resource/icons.mdmarkdown2.3 KB
references/lark-im-card-action-reply.mdmarkdown9.5 KB
references/lark-im-chat-create.mdmarkdown7.9 KB
references/lark-im-chat-identity.mdmarkdown3.3 KB
references/lark-im-chat-list.mdmarkdown9.3 KB
references/lark-im-chat-members-list.mdmarkdown5.2 KB
references/lark-im-chat-messages-list.mdmarkdown11.1 KB
references/lark-im-chat-search.mdmarkdown8.4 KB
references/lark-im-chat-update.mdmarkdown3.5 KB
references/lark-im-feed-group-list-item.mdmarkdown3.1 KB
references/lark-im-feed-group-list.mdmarkdown2.7 KB
references/lark-im-feed-group-query-item.mdmarkdown2.3 KB
references/lark-im-feed-groups.mdmarkdown18.3 KB
references/lark-im-feed-shortcut-create.mdmarkdown4.2 KB
references/lark-im-feed-shortcut-list.mdmarkdown5.0 KB
references/lark-im-feed-shortcut-remove.mdmarkdown2.1 KB
references/lark-im-flag-cancel.mdmarkdown2.9 KB
references/lark-im-flag-create.mdmarkdown2.7 KB
references/lark-im-flag-list.mdmarkdown4.6 KB
references/lark-im-message-enrichment.mdmarkdown7.0 KB
references/lark-im-message-read-status.mdmarkdown4.3 KB
references/lark-im-messages-edit.mdmarkdown6.4 KB
references/lark-im-messages-mget.mdmarkdown6.8 KB
references/lark-im-messages-reply.mdmarkdown17.1 KB
references/lark-im-messages-resources-download.mdmarkdown4.2 KB
references/lark-im-messages-search.mdmarkdown13.6 KB
references/lark-im-messages-send.mdmarkdown19.3 KB
references/lark-im-reactions.mdmarkdown10.3 KB
references/lark-im-scopes.mdmarkdown2.2 KB
references/lark-im-threads-messages-list.mdmarkdown6.4 KB

references/lark-im-chat-list.md

View on GitHub
# 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"

# Fetch multiple pages automatically, up to 10 pages by default
lark-cli im +chat-list --page-all

# 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 | - | Starting cursor, normally returned by a previous response |
| `--page-all` | No | - | Automatically fetch and merge subsequent pages; capped by `--page-limit` |
| `--page-limit <n>` | No | 1-1000, default 10 | Maximum pages fetched by `--page-all` |
| `--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.

With `--page-all`, `--page-token` sets the starting cursor. If `meta.pagination.complete=false`, resume from `meta.pagination.next_token` or raise `--page-limit`.

## 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

Use the CLI's built-in `--jq` to project the pagination fields in one call (no local `jq` or shell text parsing needed, works on all platforms). Read `has_more` / `page_token` from each page's output and issue the next call with `--page-token` until `has_more` is `false`:

```bash
lark-cli im +chat-list --page-size 100 \
  --jq '{chat_ids: [.data.chats[].chat_id], has_more: .data.has_more, page_token: .data.page_token}'

# next page: pass the previous page_token
lark-cli im +chat-list --page-size 100 --page-token "<page_token>" \
  --jq '{chat_ids: [.data.chats[].chat_id], has_more: .data.has_more, page_token: .data.page_token}'
```

## Common Errors and Troubleshooting

| Symptom | Root Cause | Solution |
|---------|---------|---------|
| `invalid --page-size 101: must be between 1 and 100` | page-size is out of range | 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 the on-demand auth flow: `lark-cli auth login --scope "im:chat:read" --no-wait --json` (per lark-shared split-flow; never the blocking login) |
| `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.`
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall