@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.28c4f05 → 0.1.0-dev.4e64c13

package/shared/lark-cli/lark-drive/references/lark-drive-files-list.md

@@ -0,0 +1,183 @@
+# drive files list（原生 API：读取 Drive 文件夹清单）
+
+`drive files list` 是原生 API 命令，不是 shortcut。它用于读取 Drive 根目录或某个 Drive 文件夹的直接子项；如果要递归盘点目录树，Agent 必须基于返回的子文件夹 token 继续调用本命令。
+
+## 什么时候使用
+
+| 场景 | 是否使用 | 说明 |
+|------|----------|------|
+| 盘点一个已确认的 Drive 文件夹树 | 使用 | 从目标 `folder_token` 开始递归列取 |
+| 盘点用户明确确认的 Drive 根目录 | 使用 | 第一层用空 `folder_token`，子文件夹继续按普通文件夹递归 |
+| 验证移动 / 创建后的实际位置 | 使用 | 读取目标目录直接子项，再按需递归验证 |
+| 根据关键词、标题、时间、owner 找资源 | 不使用 | 本 API 只按文件夹层级列取直接子项，不做关键词检索 |
+| 读取 Docx 正文内容 | 不使用 | 属 lark-doc 能力 |
+| 读取 Sheet 内部数据 | 不使用 | 切到 `lark-sheets`；多维表格 / Base 切 `lark-base` |
+
+## 标准命令模板
+
+读取普通文件夹：
+
+```bash
+lark-cli drive files list \
+  --params '{"folder_token":"<folder_token>","page_size":200}' \
+  --format json
+```
+
+继续翻页：
+
+```bash
+lark-cli drive files list \
+  --params '{"folder_token":"<folder_token>","page_size":200,"page_token":"<PAGE_TOKEN>"}' \
+  --format json
+```
+
+读取当前用户 Drive 根目录的直接子项：
+
+```bash
+lark-cli drive files list \
+  --params '{"folder_token":"","page_size":200}' \
+  --format json
+```
+
+也可以省略 `folder_token` 字段来请求根目录，但在 Agent 编排中建议显式传空字符串，避免把“忘记传参数”和“确认请求根目录”混在一起。
+
+## 按时间排序
+
+默认不要传 `order_by` / `direction`；服务端会按默认顺序返回。只有用户明确要求按创建时间或编辑时间排序时，才使用服务端排序参数。
+
+按创建时间升序列出当前文件夹直接子项：
+
+```bash
+lark-cli drive files list \
+  --params '{"folder_token":"<folder_token>","order_by":"CreatedTime","direction":"ASC","page_size":200}' \
+  --format json
+```
+
+按编辑时间降序列出当前文件夹直接子项：
+
+```bash
+lark-cli drive files list \
+  --params '{"folder_token":"<folder_token>","order_by":"EditedTime","direction":"DESC","page_size":200}' \
+  --format json
+```
+
+以上示例返回排序后的当前页；如果返回 `has_more=true`，保持相同 `folder_token` / `order_by` / `direction` / `page_size`，把 `next_page_token` 放入 `page_token` 继续翻页。
+
+## 参数规则
+
+1. `folder_token` 必须放在 `--params` JSON 里；不要使用不存在的 `--folder-token` flag。
+2. `page_token` 必须放在 `--params` JSON 里；不要依赖 shell 变量拼接不完整的 JSON。
+3. 默认不要传 `order_by` / `direction`；只有用户明确要求按创建时间 / 编辑时间排序时才使用服务端排序参数。
+4. 排序参数映射：创建时间 -> `order_by:"CreatedTime"`；编辑时间 / 修改时间 -> `order_by:"EditedTime"`；升序 -> `direction:"ASC"`；降序 -> `direction:"DESC"`。不要省略排序参数后再用 Python / shell 客户端排序替代。
+5. 排序查询建议带 `page_size:200` 减少翻页；只有用户要求完整分页、递归盘点、大目录全量导出，或当前页返回 `has_more=true` 后继续翻页时，才加入 `page_token`。
+6. `page_size` 在分页、递归盘点或全量导出时建议显式设置为 `200`。如果服务端或环境返回参数错误，再降级到服务端允许的值，并记录降级原因。
+7. 调用前如果不确定字段结构，先运行 `lark-cli schema drive.files.list` 查看 `--params` 结构。
+
+## 返回结构与解析
+
+`--format json` 输出中，Agent 只使用 `data` 中符合 `schema drive.files.list` 的 API 返回字段。
+
+常用字段：
+
+| 字段 | 用途 |
+|------|------|
+| `data.files` | 当前页直接子项列表 |
+| `data.has_more` | 当前目录是否还有下一页 |
+| `data.next_page_token` | 下一页 token；当 `has_more=true` 时放回 `--params.page_token` |
+| `data.files[].type` | 文件类型；等于 `folder` 时可递归 |
+| `data.files[].token` | 当前资源 token；文件夹递归时作为下一层 `folder_token` |
+| `data.files[].name` | 生成路径和展示标题 |
+| `data.files[].url` | 资源浏览器链接 |
+| `data.files[].owner_id` | 资源所有者 |
+| `data.files[].created_time` / `data.files[].modified_time` | 创建 / 更新时间 |
+
+字段名以 `schema drive.files.list` 为准。Agent MUST 以实际返回为准；如果字段缺失，先用 `schema drive.files.list` 或一页样本确认结构，不要猜测。
+
+## 根目录语义
+
+1. `folder_token` 为空字符串或省略时，请求的是当前调用用户的 Drive 根目录直接子项。
+2. 根目录返回值不是递归结果；不能把根目录第一页或直接子项数量当作整个云空间资源总量。
+3. 根目录只作为目录树起点。返回的子文件夹必须用其自己的 `folder_token` 继续调用 `drive files list`。
+4. 根据 schema 描述，根目录第一层清单不支持分页且不返回快捷方式；不要基于根目录响应推断子文件夹内容、根目录第一层快捷方式或无法分页的根目录剩余项已经被覆盖。
+
+## 递归盘点规则
+
+1. 只对返回项中的 `folder` 类型继续递归。
+2. 每个目录独立维护分页状态；一个目录的 `page_token` 不可复用于其他目录。
+3. 对每个目录持续请求，直到返回 `has_more=false`。非根目录的普通文件夹清单可能返回 `type=shortcut` 条目；不要假设这些条目会携带 `shortcut_info` 目标信息。
+4. 递归过程中生成稳定 `path`；不要只保存标题，否则同名资源无法区分。
+5. URL、owner、创建时间和更新时间优先使用 `files.list` 返回字段；如果字段缺失，以实际返回为准，不要从标题或路径猜元数据。
+6. 深度、数量、每目录页数等限制只能作为内部批次 checkpoint；不能作为递归完成条件。
+7. 达到深度 checkpoint 时，把更深层子文件夹加入 continuation queue，并在下一批从这些子文件夹继续，保留原始 `path`。
+8. 达到数量 checkpoint 时，保存当前目录、当前页 token、剩余目录队列和已收集资源计数，并立即继续下一批；不要进入分析或规划阶段。
+
+### 递归算法
+
+Agent 盘点 Drive 文件夹树时，按以下顺序执行：
+
+1. 初始化待处理队列，放入起点目录：
+   - 普通文件夹：`{folder_token:"<folder_token>", path:"<folder_name>"}`
+   - Drive 根目录：`{folder_token:"", path:""}`
+2. 从队列取出一个目录，请求第一页。
+3. 用 `(folder_token, page_token)` 生成当前页 key；同一页 key 只允许追加一次，避免 retry 时重复计数。
+4. 从 `data.files` 取当前页直接子项，按 `dedupe_key` 去重后生成 `path` 并加入结果集。
+5. 如果新追加的子项是 `folder`，把子文件夹 token、子路径和 depth 加入队列。
+6. 如果 `has_more=true`，取 `data.next_page_token` 继续请求同一目录下一页。
+7. 同一目录分页结束后，再处理队列中的下一个目录。
+8. 如果达到深度、数量或每目录页数 checkpoint，把当前目录 / 页 token / 剩余队列 / 已访问页 key / dedupe key 写入 continuation queue，并继续下一批。
+9. 普通队列和 continuation queue 都为空，且没有分页 blocker 时，才可以认为本次确认范围盘点完成。
+
+简化伪代码：
+
+```text
+queue = [root_or_start_folder]
+visited_pages = set()
+dedupe_keys = set()
+while queue not empty:
+  folder = queue.pop()
+  page_token = folder.page_token or ""
+  retry_without_token = 0
+  while true:
+    page_key = (folder.folder_token, page_token or "first")
+    page = drive files list(folder.folder_token, page_token)
+    if page_key not in visited_pages:
+      append only files whose dedupe_key is not in dedupe_keys
+      enqueue newly appended child folders with folder_token, path, and depth
+      add page_key to visited_pages
+    if page.has_more != true:
+      break
+    next = page.next_page_token
+    if next is empty:
+      retry_without_token += 1
+      if retry_without_token >= 3:
+        record pagination blocker for folder
+        break
+      continue
+    page_token = next
+    retry_without_token = 0
+```
+
+## 分页与异常
+
+1. 默认手动处理 `has_more` 和返回中的 `next_page_token`。
+2. 不要使用 `--page-all` 作为脚本 JSON 解析输入；自动翻页输出可能不适合直接 `json.loads`。
+3. 如果 `has_more=true` 但没有可用的 `next_page_token`，重试同一页最多 3 次。
+4. 重试后仍无 continuation token 时，记录受影响的目录和 pagination blocker，停止扩展该目录；不要无限循环，也不要宣称该目录已完整覆盖。
+5. 如果触发深度、数量或每目录页数限制，把它视为批处理 checkpoint；在确认范围内继续下一批，而不是把当前结果说成完整。
+6. 不要因为达到 `max_depth=3`、`max_items=500` 或类似单批阈值就结束盘点；只有队列耗尽或遇到权限 / API / 工具预算 blocker 才能结束当前确认范围的盘点。
+
+## JSON 解析规则
+
+1. stdout 是数据通道。脚本解析 JSON 时只读取 stdout。
+2. stderr 可能包含刷新 token、进度、warning 或其他提示；不要把 stderr 合并进 JSON 输入，例如不要用 `2>&1` 后再 `json.loads`。
+3. 使用 `--format json` 保持 stdout 为结构化 JSON；解析 Drive 文件清单时只读取 `data.files` / `data.has_more` / `data.next_page_token` 等 schema 字段。
+4. 不要用根目录响应数量或当前页数量推断递归总量；递归总量必须由实际遍历并去重后的资源集合计算。
+
+## 常见错误
+
+| 错误用法 | 问题 | 正确做法 |
+|----------|------|----------|
+| `lark-cli drive files list --folder-token <token>` | `files.list` 不提供 `--folder-token` flag | 使用 `--params '{"folder_token":"<token>"}'` |
+| 根目录返回 N 项就认为云空间只有 N 项 | 根目录只返回直接子项，不是递归结果 | 对返回的子文件夹继续递归 |
+| `--page-all \| python json.loads(...)` | 自动翻页输出不适合作为单个 JSON 对象解析 | 手动使用 `page_token` 翻页并逐页解析 |
+| `cmd 2>&1` 后解析 JSON | stderr 提示污染 JSON 输入 | 只解析 stdout，stderr 作为日志处理 |

package/shared/lark-cli/lark-im/README.md

@@ -0,0 +1,84 @@
+# im (v1)
+
+## Core Concepts
+
+- **Chat**: A group chat or P2P conversation, identified by `chat_id` (oc_xxx).
+- **Message**: A single message in a chat, identified by `message_id` (om_xxx).
+- **Reaction**: An emoji reaction on a message.
+- **Member**: An entry in a chat's member list — a user account or a bot (returned in separate `users[]` / `bots[]` buckets).
+
+所有命令以当前用户身份运行（`--as user`，默认值，无需显式指定）；能否读到某个群 / 成员 / 消息取决于该用户对目标资源的可见性。
+
+## Resource Relationships
+
+```
+Chat (oc_xxx)
+├── Message (om_xxx)
+│   └── Reaction (emoji)
+└── Member (user / bot)
+```
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用操作的高级封装（`lark-cli im +<verb> [flags]`）。有 Shortcut 的操作优先使用。本沙箱只透出以下 3 个只读快捷命令：
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+chat-list`](references/lark-im-chat-list.md) | List chats the current user is a member of; defaults to groups; pass --types=p2p,group to include p2p single chats; supports sorting, auto-pagination (--page-all), --exclude-muted |
+| [`+chat-members-list`](references/lark-im-chat-members-list.md) | List members of a chat; returns separate users[] / bots[] buckets; --member-types filters which kinds to return; --page-all pagination; surfaces truncations[] when the server caps a bucket |
+| [`+chat-search`](references/lark-im-chat-search.md) | Search visible group chats by --query keyword and/or --member-ids; e.g. look up chat_id by group name; supports type filters, sorting, auto-pagination (--page-all), and --exclude-muted |
+
+## API Resources
+
+```bash
+lark-cli schema im.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli im <resource> <method> [flags]  # 调用 API
+```
+
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+
+本沙箱只透出以下只读 API 命令（均为 read-only）；**不要**尝试列表之外的 `im <service>/<api>` 组合。
+
+### chats
+
+  - `get` — 获取群信息。调用方需在目标群内才能拿到完整信息；内部群还需与群属于同一租户。
+
+### chat.members
+
+  - `bots` — 读取群内机器人成员信息。上游 skill 未提供 typed-flag 文档，调用前先 `lark-cli schema im.chat.members.bots` 查看参数与返回结构。
+  - `get` — 读取群成员信息。上游 skill 未提供 typed-flag 文档，调用前先 `lark-cli schema im.chat.members.get` 查看参数与返回结构。
+
+### chat.moderation
+
+  - `get` — 获取群成员发言权限。调用方需在目标群内并与群属于同一租户。
+
+### chat.nickname
+
+  - `get` — 获取自己的群昵称（self-only）；未设置昵称时返回空字符串。
+
+### chat.user_setting
+
+  - `batch_query` — 批量查询当前用户在群内的个人偏好设置（如 `is_muted` 静音普通消息、`is_mute_at_all` 静音 @all 消息）；单次最多 10 个群；调用方需在每个目标群内。
+
+### pins
+
+  - `list` — 获取群内 Pin 消息。
+
+### reactions
+
+  - `batch_query` — 批量获取多条消息的表情回复。[Must-read](references/lark-im-reactions.md)
+  - `list` — 获取单条消息的表情回复记录。[Must-read](references/lark-im-reactions.md)
+
+## 权限表
+
+| 方法 | 所需 scope |
+|------|-----------|
+| `chats.get` | `im:chat:read` |
+| `+chat-list` / `+chat-search` | `im:chat:read` |
+| `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.moderation.get` | `im:chat.moderation:read` |
+| `reactions.batch_query` | `im:message.reactions:read` |
+| `reactions.list` | `im:message.reactions:read` |
+| `pins.list` | `im:message.pins:read` |

package/shared/lark-cli/lark-im/references/lark-im-chat-list.md

@@ -0,0 +1,140 @@
+# im +chat-list
+
+List chats the current user 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. Supports pagination, sort order, and 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
+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 — comma form
+lark-cli im +chat-list --types p2p,group
+
+# Same, using repeat flag instead of CSV
+lark-cli im +chat-list --types p2p --types group
+
+# Only p2p single chats
+lark-cli im +chat-list --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) |
+| `--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 | - | Drop chats the current user has muted (do-not-disturb); see "Filtering muted chats" below |
+| `--format json` | No | - | Output as JSON |
+| `--dry-run` | No | - | Preview the request without executing it |
+
+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 |
+|---|---|
+| "list my groups" / 我的群 / 我加入了哪些群 | (default, omit `--types`) |
+| "list my p2p chats" / 我的单聊 / 我跟谁有 1v1 | `--types p2p` |
+| "all my chats" / 全部聊天 / 所有会话 (ambiguous) | `--types p2p,group` |
+
+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.
+
+## Filtering muted chats
+
+`--exclude-muted` 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.
+
+When the flag is set, the JSON envelope gains a `filter` sub-object (absent otherwise, so existing consumers are unaffected); `fetched_count == returned_count + filtered_count` always holds:
+
+```json
+{
+  "chats": [...],
+  "filter": {
+    "applied": "exclude_muted",
+    "fetched_count": 20,
+    "returned_count": 17,
+    "filtered_count": 3,
+    "hint": "Filtered out 3 muted chat(s) on this page (17 remaining); use --page-token to fetch more."
+  }
+}
+```
+
+## Usage Scenarios
+
+### Scenario 1: List my recent chats
+
+```bash
+lark-cli im +chat-list --sort active_time --page-size 10
+```
+
+### Scenario 2: List my non-muted chats sorted by activity
+
+```bash
+lark-cli im +chat-list --sort active_time --exclude-muted
+```
+
+### Scenario 3: Iterate all my chats programmatically
+
+```bash
+TOKEN=""
+while :; do
+  RESP=$(lark-cli im +chat-list --page-size 100 --page-token "$TOKEN" --format json)
+  echo "$RESP" | jq -r '.data.chats[].chat_id'
+  HAS_MORE=$(echo "$RESP" | jq -r '.data.has_more')
+  [ "$HAS_MORE" = "true" ] || break
+  TOKEN=$(echo "$RESP" | jq -r '.data.page_token')
+done
+```
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| `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 | The current identity is not authorized for `im:chat:read` | 鉴权由沙箱运行环境提供，无需手动补登录；确认目标群对当前用户可见后重试 |

package/shared/lark-cli/lark-im/references/lark-im-chat-members-list.md

@@ -0,0 +1,84 @@
+# im +chat-members-list
+
+List the members of a chat. Users and bots are returned in **separate buckets** — `users[]` and `bots[]` — with per-bucket totals (`user_total` / `bot_total`). Use `--member-types` to return only one kind.
+
+This skill maps to the shortcut: `lark-cli im +chat-members-list` (internally calls `GET /open-apis/im/v1/chats/{chat_id}/members/list`).
+
+## Commands
+
+```bash
+# Single page (default)
+lark-cli im +chat-members-list --chat-id oc_xxx
+
+# Only users, or users + bots
+lark-cli im +chat-members-list --chat-id oc_xxx --member-types user
+lark-cli im +chat-members-list --chat-id oc_xxx --member-types user,bot
+
+# Walk every page (capped by --page-limit; 0 = unlimited)
+lark-cli im +chat-members-list --chat-id oc_xxx --page-all --page-limit 0
+
+# Fetch one page starting at a specific cursor
+lark-cli im +chat-members-list --chat-id oc_xxx --page-token "xxx"
+
+# Continue automatically from a specific cursor
+lark-cli im +chat-members-list --chat-id oc_xxx --page-token "xxx" --page-all
+
+# JSON output / preview the request
+lark-cli im +chat-members-list --chat-id oc_xxx --format json
+lark-cli im +chat-members-list --chat-id oc_xxx --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Limits | Description |
+|------|------|------|------|
+| `--chat-id <id>` | Yes | `oc_xxx` | Target chat |
+| `--member-types <strings>` | No | `user`, `bot` (comma-separated or repeated) | Member types to return. Omitted = all |
+| `--member-id-type <type>` | No | `open_id` (default), `union_id`, `user_id` | ID type for `member_id` in the response |
+| `--page-size <n>` | No | 1-100, default 20 | Results per page. With `--page-all` and no explicit `--page-size`, the max (100) is used automatically to minimize round-trips |
+| `--page-token <token>` | No | - | Starting cursor, normally returned by a previous response |
+| `--page-all` | No | - | Automatically walk every page (capped by `--page-limit`) |
+| `--page-limit <n>` | No | default 10, `0` = unlimited | Max pages to fetch with `--page-all` |
+| `--page-delay <ms>` | No | default 200, `0` = no delay | Delay between pages during `--page-all` (throttle to avoid rate limits on large lists) |
+| `--format json` | No | - | Output as JSON |
+| `--dry-run` | No | - | Preview the request without executing it |
+
+> The caller must be in the target chat, and must belong to the same tenant for internal chats.
+
+## Output Fields
+
+| Field | Description |
+|------|------|
+| `chat_id` | The queried chat ID |
+| `users` | Array of user members (`member_id`, `name`, `tenant_key`, …) |
+| `bots` | Array of bot members (`member_id`, `app_id`, `name`, …) |
+| `user_total` / `bot_total` | Server-reported totals for each bucket |
+| `truncations` | Non-empty when the server **capped a bucket** due to security config — see below |
+| `has_more` / `page_token` | Paging signals from the final page fetched |
+
+## Truncation: the result may be incomplete
+
+The server applies a security cap to large member lists. When a bucket is capped, the response carries a `truncations[]` entry (e.g. `[{"limit": 100, "member_type": "user"}]`) **on the final page only**. The shortcut surfaces this two ways so it is never missed:
+
+- **stderr**: `⚠️  member list truncated by server security config: user bucket capped at 100 — the list is INCOMPLETE.`
+- **stdout JSON**: the `truncations` array is preserved verbatim in the output.
+
+A truncated result is *not* fixable by paging further — it is a server-side cap. Treat `users`/`bots` as a partial list whenever `truncations` is non-empty.
+
+## Pagination notes
+
+- Default fetches a single page. Pass `--page-all` to drain every page.
+- With `--page-all` and no explicit `--page-size`, the shortcut uses the maximum page size (100) so a full walk takes the fewest round-trips. An explicit `--page-size` is always honored.
+- `--page-all` sleeps `--page-delay` ms (default 200) between pages to avoid hammering the API when a tenant has no server-side member cap and the list spans many pages. Set `--page-delay 0` to disable.
+- `--page-all` stops at `--page-limit` pages (default 10). When it stops early, `has_more` stays `true` so you know the result is incomplete; re-run with `--page-limit 0` for everything.
+- `--page-token` and `--page-all` together: automatic pagination starts at the supplied cursor and continues until exhaustion or `--page-limit`.
+- Across pages, `users[]` and `bots[]` are concatenated; `truncations` / `has_more` / `page_token` come from the last page fetched.
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| `--chat-id is required` | `--chat-id` omitted | Provide the `oc_xxx` chat ID |
+| `invalid --page-size 101: must be between 1 and 100` | out of range | Use 1-100 |
+| `--member-types contains invalid value` | value other than `user`/`bot` | Use `user`, `bot`, or both |
+| Permission denied | missing `im:chat.members:read` | 鉴权由沙箱运行环境提供，无需手动补登录；确认目标群对当前用户可见后重试 |

package/shared/lark-cli/lark-im/references/lark-im-chat-search.md

@@ -0,0 +1,135 @@
+# im +chat-search
+
+Search the list of group chats visible to the current user, including chats the user 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"
+
+# Fetch multiple pages automatically, up to 10 pages by default
+lark-cli im +chat-search --query "project" --page-all
+
+# 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 | - | 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 | - | Drop chats the current user has muted (do-not-disturb); see "Filtering muted chats" below |
+| `--format json` | No | - | Output as JSON |
+| `--dry-run` | No | - | Preview the request without executing it |
+
+With `--page-all`, `--page-token` sets the starting cursor. If `meta.pagination.complete=false`, resume from `meta.pagination.next_token` or raise `--page-limit`.
+
+> **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` 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.
+
+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 its members
+
+```bash
+CHAT_ID=$(lark-cli im +chat-search --query "project" --format json | jq -r '.data.chats[0].chat_id')
+lark-cli im +chat-members-list --chat-id "$CHAT_ID"
+```
+
+## 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 |
+| `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 | The current identity is not authorized for `im:chat:read` | 鉴权由沙箱运行环境提供，无需手动补登录；确认目标群对当前用户可见后重试 |
+
+## 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 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, a common next step is listing its members (`im +chat-members-list`).
+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](../README.md) - all IM commands