@yandy0725/pi-lark 0.1.0

package/skills/lark-im/references/lark-im-messages-reply.md

@@ -0,0 +1,267 @@
+# im +messages-reply
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Reply to a specific message. Supports both user identity (`--as user`) and bot identity (`--as bot`). Also supports thread replies.
+
+This skill maps to the shortcut: `lark-cli im +messages-reply` (internally calls `POST /open-apis/im/v1/messages/:message_id/reply`).
+
+## Safety Constraints
+
+Replies sent by this tool are visible to other people. Before calling it, you **must** confirm with the user:
+
+1. Which message to reply to
+2. The reply content
+3. Which identity to use (user or bot)
+
+**Do not** send a reply without explicit user approval.
+
+When using `--as bot`, the reply is sent in the app's name, so make sure the app has already been added to the target chat.
+
+When using `--as user`, the reply is sent as the authorized end user and requires the `im:message.send_as_user` and `im:message` scopes.
+
+## Choose The Right Content Flag
+
+### Default Selection Rule For Agents
+
+- Prefer `--markdown` for headings, lists, links, summaries, investigation notes, or Markdown-looking content.
+- Use `--text` for exact plain text: logs, code, indentation-sensitive text, or literal Markdown.
+- Use `--content` for exact `post` JSON, titles, multiple locales, cards, or unsupported structures.
+
+| Need | Recommended flag | Why |
+|------|------|------|
+| Reply with headings, lists, links, summaries, or investigation notes | `--markdown` | Best default for lightweight formatting; converted to Feishu `post` JSON |
+| Reply with plain text exactly as written | `--text` | Preserves literal text; no Markdown conversion |
+| Precisely control the reply payload | `--content` | You provide the exact JSON |
+| Reply with media | `--image` / `--file` / `--video` / `--audio` | Shortcut uploads URLs, or cwd-relative local files automatically |
+
+### `--text` vs `--markdown`
+
+- Use `--markdown` for lightweight formatted replies.
+- Use `--text` for exact plain text, especially logs, code, indentation, or literal Markdown characters.
+- Use `--content` when you need exact `post` JSON, a card, a title, multiple locales, or any structure that `--markdown` cannot express reliably.
+
+## What `--markdown` Really Does
+
+`--markdown` accepts Markdown-like input and converts it to the Feishu `post` payload required by the reply API.
+
+The shortcut:
+
+1. Forces `msg_type=post`
+2. Resolves remote Markdown images like `![x](https://...)`
+3. Normalizes the Markdown for Feishu post rendering
+4. Wraps the final content as:
+
+```json
+{"zh_cn":{"content":[[{"tag":"md","text":"..."}]]}}
+```
+
+This makes `--markdown` the simplest path for lightweight formatted replies.
+
+### Markdown Boundaries
+
+- It does **not** promise full CommonMark / GitHub Flavored Markdown support.
+- It always becomes a `post` payload with a single `zh_cn` locale.
+- It does **not** let you set a `post` title.
+- Headings are rewritten:
+    - `# Title` becomes `#### Title`
+    - `##` to `######` are normalized to `#####` when the content contains H1-H3
+- Consecutive headings are separated with blank lines after heading normalization.
+- Block spacing and line breaks may be normalized during conversion.
+- Code blocks are preserved as code blocks.
+- Excess blank lines are compressed.
+- Already-uploaded `img_xxx` image keys are the most reliable Markdown image input.
+- Local paths (e.g. `![x](./a.png)`) are **not** supported directly in `--markdown` and will not be auto-uploaded.
+- Remote URLs (`https://...`) will be auto-downloaded and uploaded at runtime; if the download or upload fails, the image is removed with a warning.
+
+If you need a title, multiple locales, cards, unsupported rich structures, or byte-for-byte post JSON control, use `--msg-type post --content ...`.
+
+### Image Constraint for `--markdown`
+
+When using `--markdown` with images, prefer pre-uploading via `images.create` and referencing `![alt](img_xxx)` for predictable results. Remote URLs may work but are not guaranteed.
+
+**Steps:**
+
+```bash
+# 1. Upload image to get image_key
+lark-cli im images create --data '{"image_type":"message"}' --file ./diagram.png
+# Returns: {"image_key":"img_v3_xxxx"}
+
+# 2. Use image_key in --markdown reply
+lark-cli im +messages-reply --message-id om_xxx --markdown $'## Result\n\n![diagram](img_v3_xxxx)\n\nSee above for details.'
+```
+
+## Preserving Formatting
+
+If the reply contains multiple lines, code blocks, indentation, tabs, or a lot of escaping, prefer `$'...'` for either `--markdown` or `--text`.
+
+### When formatting must be preserved
+
+Use `--text` plus `$'...'`:
+
+```bash
+lark-cli im +messages-reply --message-id om_xxx --text $'Received\nI will check this today.\nOwner: alice'
+```
+
+```bash
+lark-cli im +messages-reply --message-id om_xxx --text $'```sql\nselect * from jobs;\n```'
+```
+
+This keeps the reply as plain text instead of converting it to a `post`.
+
+## Commands
+
+```bash
+# Reply with a formatted update
+lark-cli im +messages-reply --message-id om_xxx --markdown $'## Reply\n\n- item 1\n- item 2'
+
+# Reply with a plain one-line message
+lark-cli im +messages-reply --message-id om_xxx --text "Received"
+
+# Equivalent manual JSON
+lark-cli im +messages-reply --message-id om_xxx --content '{"text":"Received"}'
+
+# Reply as a bot
+lark-cli im +messages-reply --message-id om_xxx --text "bot reply" --as bot
+
+# Reply with preserved multi-line text
+lark-cli im +messages-reply --message-id om_xxx --text $'Line 1\nLine 2\n  indented line'
+
+# Reply inside the thread (message appears in the target thread)
+lark-cli im +messages-reply --message-id om_xxx --text "Let's discuss this" --reply-in-thread
+
+# Reply with Markdown containing an image (must pre-upload via images.create)
+lark-cli im images create --data '{"image_type":"message"}' --file ./screenshot.png
+# Use the returned image_key
+lark-cli im +messages-reply --message-id om_xxx --markdown $'## Screenshot\n\n![screenshot](img_v3_xxxx)\n\nConfirmed.'
+
+# If you need exact post structure, send JSON directly
+lark-cli im +messages-reply --message-id om_xxx --msg-type post --content '{"zh_cn":{"title":"Reply","content":[[{"tag":"text","text":"Detailed content"}]]}}'
+
+# Reply with a local image (uploaded automatically before sending)
+lark-cli im +messages-reply --message-id om_xxx --image ./photo.png
+
+# Reply with a local file (uploaded automatically before sending)
+lark-cli im +messages-reply --message-id om_xxx --file ./report.pdf
+
+# Reply with a local video (--video-cover is required as the video cover)
+lark-cli im +messages-reply --message-id om_xxx --video ./demo.mp4 --video-cover ./cover.png
+
+# Reply with a voice message
+lark-cli im +messages-reply --message-id om_xxx --audio ./voice.opus
+
+# With an idempotency key
+lark-cli im +messages-reply --message-id om_xxx --text "Received" --idempotency-key my-unique-id
+
+# Preview the request without executing it
+lark-cli im +messages-reply --message-id om_xxx --markdown $'## Test\n\nhello' --dry-run
+```
+
+## Media Input Rules
+
+- Media flags accept an existing key (`img_xxx` / `file_xxx`), an `http://` or `https://` URL, or a local file path.
+- Local paths must be relative to the current working directory and stay within it after resolving `..` and symlinks.
+- Absolute paths such as `/tmp/photo.png` are rejected. Run the command from the file's directory and pass `./photo.png`, or copy the file into the current directory first.
+- `--audio` sends a voice message and accepts only Opus audio (`.opus` or Ogg Opus `.ogg`) for local paths and URLs. For `mp3`, `wav`, or other non-Opus audio, convert to `.opus` before using `--audio`, or use `--file` to send the original audio as an attachment.
+
+## Parameters
+
+| Parameter | Required | Description                                                                                                                                                                                   |
+|------|------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--message-id <id>` | Yes | ID of the message being replied to (`om_xxx`)                                                                                                                                                 |
+| `--msg-type <type>` | No | Message type (default `text`). If you use `--text` / `--markdown` / media flags, the effective type is inferred automatically. Explicitly setting a conflicting `--msg-type` fails validation |
+| `--content <json>` | One content option | Exact reply content as JSON. The JSON must match the effective `--msg-type`                                                                                                                   |
+| `--text <string>` | One content option | Plain text reply. Use when exact text and formatting preservation matter                                                                                                                      |
+| `--markdown <string>` | One content option | Best default for lightweight formatted replies such as headings, lists, links, summaries, and investigation notes. Internally converted to `post` JSON with Feishu-specific normalization |
+| `--image <path\|url\|key>` | One content option | Cwd-relative local image path, URL, or `image_key` (`img_xxx`)                                                                                                                                |
+| `--file <path\|url\|key>` | One content option | Cwd-relative local file path, URL, or `file_key` (`file_xxx`)                                                                                                                                 |
+| `--video <path\|url\|key>` | One content option | Cwd-relative local video path, URL, or `file_key` (`file_xxx`); **must be used together with `--video-cover`**                                                                                |
+| `--video-cover <path\|url\|key>` | **Required with `--video`** | Cwd-relative local cover image path, URL, or `image_key` (`img_xxx`)                                                                                                                          |
+| `--audio <path\|url\|key>` | One content option | Voice-message audio key, URL, or cwd-relative local path. Local paths and URLs must be Opus (`.opus` or Ogg Opus `.ogg`) |
+| `--reply-in-thread` | No | Reply inside the thread. The reply appears in the target message's thread instead of the main chat stream                                                                                     |
+| `--idempotency-key <key>` | No | Idempotency key; the same key sends only one reply within 1 hour                                                                                                                              |
+| `--as <identity>` | No | Identity type: `bot` or `user` (default `bot`)                                                                                                                                                |
+| `--dry-run` | No | Print the request only, do not execute it                                                                                                                                                     |
+
+> **Mutual exclusivity rule:** `--text`, `--markdown`, `--content`, and `--image`/`--file`/`--video`/`--audio` cannot be used together. Media flags are also mutually exclusive with each other.
+>
+> **Video cover rule:** `--video` **must** be accompanied by `--video-cover`. Omitting `--video-cover` when using `--video` will fail validation. `--video-cover` cannot be used without `--video`.
+
+## Common Mistakes
+
+- Choosing `--text` for headings, lists, links, summaries, or investigation notes. Use `--markdown`.
+- Choosing `--markdown` when you actually need exact plain text. If exact line breaks, spacing, logs, code, or literal Markdown characters matter, use `--text`, usually with `$'...'`.
+- Assuming `--markdown` supports every Markdown feature. It is converted into a Feishu `post` payload and normalized first.
+- Putting local image paths inside Markdown like `![x](./a.png)`. `--markdown` does not auto-upload those paths.
+- **Using local file paths inside Markdown image syntax** (e.g. `![x](./a.png)`) with `--markdown`. Local paths are not auto-uploaded and will not render as an image. Pre-upload via `images.create` to get an `image_key` instead.
+- Using `--content` without making the JSON match the effective `--msg-type`.
+- Explicitly setting `--msg-type` to something that conflicts with `--text`, `--markdown`, or media flags.
+- Mixing `--text`, `--markdown`, or `--content` with media flags in one command.
+
+## Return Value
+
+```json
+{
+  "message_id": "om_xxx",
+  "chat_id": "oc_xxx",
+  "create_time": "1234567890"
+}
+```
+
+## Usage Scenarios
+
+### Scenario 1: Reply in the main chat stream
+
+```bash
+lark-cli im +messages-reply --message-id om_xxx --text "OK, I will handle it"
+```
+
+The reply appears in the main chat stream and references the target message.
+
+### Scenario 2: Reply inside a thread
+
+```bash
+lark-cli im +messages-reply --message-id om_xxx --text "Let me take a look at this" --reply-in-thread
+```
+
+The reply appears in the target message's thread and does not show up in the main chat stream.
+
+## @Mention Format
+
+The `<at>` syntax differs by message type. The shortcut only normalizes mentions for `text` and `post`; `interactive` card content is passed through verbatim, so cards must use the card-native syntax below.
+
+### `text`
+
+- `<at user_id="ou_xxx">name</at>` — the inner text is the mentioned user's display name and is optional (`<at user_id="ou_xxx"></at>` also works)
+- @all: `<at user_id="all"></at>`
+
+### `post`
+
+- Inside a `text` or `md` element, the same inline form as `text` works: `<at user_id="ou_xxx">name</at>`
+- Or use a dedicated `at` element node: `{"tag":"at","user_id":"ou_xxx"}` (use `"all"` to mention everyone)
+
+### `interactive` (card)
+
+Card content is **not** normalized — use the card-native `<at>` syntax inside a `lark_md` / `markdown` element:
+
+- single user by open_id: `<at id=ou_xxx></at>`
+- multiple users: `<at ids=ou_xxx1,ou_xxx2></at>`
+- by email: `<at email=user@example.com></at>`
+
+## Notes
+
+- `--message-id` must be a valid message ID in `om_xxx` format
+- `--content` must be valid JSON
+- When using `--content`, you are responsible for making the JSON structure match the effective `msg_type`
+- `--reply-in-thread` adds `reply_in_thread=true` to the API request
+- `--reply-in-thread` is mainly meaningful in chats that support thread replies
+- `--image`/`--file`/`--video`/`--audio`/`--video-cover` support existing keys, URLs, and cwd-relative local file paths; the shortcut uploads local paths and URLs first, then sends the reply; both the upload and send steps use the same identity (UAT when `--as user`, TAT when `--as bot`)
+- If the provided media value starts with `img_` or `file_`, it is treated as an existing key and used directly
+- `--markdown` always sends `msg_type=post`
+- If you explicitly set `--msg-type` and it conflicts with the chosen content flag, validation fails
+- When using `--video`, `--video-cover` is required as the video cover
+- `--dry-run` uses placeholder image keys for remote Markdown images and placeholder media keys for local uploads
+- Failures return error codes and messages
+- `--as user` uses a user access token (UAT) and requires the `im:message.send_as_user` and `im:message` scopes; the reply is sent as the authorized end user
+- `--as bot` uses a tenant access token (TAT), and requires the `im:message:send_as_bot` scope
+- When using `--markdown` with images, pre-uploading via `images.create` to obtain an `image_key` is recommended for reliability; remote URLs may be auto-resolved at runtime, but if download/upload fails the image is removed with a warning; local paths are not supported

package/skills/lark-im/references/lark-im-messages-resources-download.md

@@ -0,0 +1,94 @@
+# im +messages-resources-download
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Download image or file resources from a message. Supports **automatic chunked download for large files** using HTTP Range requests. Resources are identified by the combination of `message_id` + `file_key`, both of which come directly from message content returned by `im +chat-messages-list`.
+
+> **Note:** read-only message commands render resource keys in message content, but they do not download binaries automatically. Use this command whenever you need to fetch the actual image/file bytes or save them to a specific path.
+
+This skill maps to the shortcut: `lark-cli im +messages-resources-download` (internally calls `GET /open-apis/im/v1/messages/{message_id}/resources/{file_key}`).
+
+## Commands
+
+```bash
+# Download an image (save to the current directory)
+lark-cli im +messages-resources-download --message-id om_xxx --file-key img_v3_xxx --type image
+
+# Download a file
+lark-cli im +messages-resources-download --message-id om_xxx --file-key file_v3_xxx --type file
+
+# Specify the output path
+lark-cli im +messages-resources-download --message-id om_xxx --file-key img_v3_xxx --type image --output ./photo.png
+
+# Download as a bot
+lark-cli im +messages-resources-download --message-id om_xxx --file-key img_v3_xxx --type image --as bot
+
+# Preview the request without executing it
+lark-cli im +messages-resources-download --message-id om_xxx --file-key img_v3_xxx --type image --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|------|------|------|
+| `--message-id <id>` | Yes | Message ID (`om_xxx` format) |
+| `--file-key <key>` | Yes | Resource key (`img_xxx` or `file_xxx`) |
+| `--type <type>` | Yes | Resource type: `image` or `file` |
+| `--output <path>` | No | Output path (relative paths only; `..` traversal is not allowed). When omitted, the server's original filename from `Content-Disposition` is used if available; otherwise defaults to `file_key`. File extension is automatically inferred from `Content-Disposition` or `Content-Type` if not provided |
+| `--as <identity>` | No | Identity type: `user` (default) or `bot` |
+| `--dry-run` | No | Print the request only, do not execute it |
+
+## Large File Download (Auto Chunking)
+
+When downloading large files, the command automatically uses **HTTP Range requests** for reliable chunked downloading:
+
+| Behavior | Details |
+|----------|---------|
+| Probe chunk | First 128 KB to detect file size and Content-Type |
+| Chunk size | 8 MB per subsequent request |
+| Workers | Single-threaded sequential download (ensures reliability) |
+| Retries | Up to 2 retries for transient request failures, with exponential backoff |
+
+**Benefits:**
+- Reduces the impact of transient request failures during large downloads
+- Preserves the server's original filename via `Content-Disposition` (supports RFC 5987 UTF-8 encoding); falls back to `Content-Type`-based extension inference
+- Validates file size integrity after download completion
+
+## `file_key` Sources
+
+Different resource markers in message content correspond to different `file_key` and `type` values:
+
+| Message Type | Marker in Content | `file_key` Format | `--type` |
+|---------|-------------|---------------|--------|
+| Image | `img_xxx` | `img_xxx` | `image` |
+| File | `file_xxx` | `file_xxx` | `file` |
+| Audio | `file_xxx` | `file_xxx` | `file` |
+| Video | `file_xxx` | `file_xxx` | `file` |
+
+## Usage Scenario
+
+### Scenario: Extract and download an image from a message
+
+```bash
+# Step 1: Fetch messages and find one containing an image
+lark-cli im +chat-messages-list --chat-id oc_xxx
+# In the response you see: { "msg_type": "image", "content": "{\"image_key\":\"img_v3_xxx\"}" }
+
+# Step 2: Download the image
+lark-cli im +messages-resources-download --message-id om_xxx --file-key img_v3_xxx --type image
+```
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| Download failed | `file_key` does not match the `message_id` | Make sure the `file_key` came from that message's content |
+| Hit error code 234002 or 14005 | No permission, **not** missing API scope | no access to this chat or file was deleted — do not retry, return the error to the user |
+| Permission denied | `im:message:readonly` is not authorized | Run `auth login --scope "im:message:readonly"` |
+| File size mismatch | Chunked download integrity check failed | Network instability during download; retry the command |
+| Content-Range error | Server returned invalid range header | Transient API issue; retry the command |
+
+## References
+
+- [lark-im](../SKILL.md) - all message-related commands
+- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters

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

@@ -0,0 +1,234 @@
+# im +messages-search
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Search Feishu messages across conversations. This shortcut automatically performs a multi-step workflow: search for message IDs, batch fetch message details, then enrich the results with chat context.
+
+By default each result message also carries a `reactions` block (counts + details from `im.reactions.batch_query`) when the server has reactions for it, and `update_time` for messages that were actually edited. With `--page-all`, every page is enriched; pass `--no-reactions` to skip the extra round-trip. See [message enrichment](lark-im-message-enrichment.md) for the full contract.
+
+> **User identity only** (`--as user`). Bot identity is not supported.
+
+This skill maps to the shortcut: `lark-cli im +messages-search` (internally calls `POST /open-apis/im/v1/messages/search` + batched `GET /open-apis/im/v1/messages/mget`, then batch-fetches chat context).
+
+## Commands
+
+```bash
+# Search by keyword
+lark-cli im +messages-search --query "project progress"
+
+# Restrict search to a specific group chat
+lark-cli im +messages-search --query "weekly report" --chat-id oc_xxx
+
+# Filter by sender (comma-separated)
+lark-cli im +messages-search --query "requirement" --sender ou_xxx,ou_yyy
+
+# Filter by attachment type
+lark-cli im +messages-search --query "report" --include-attachment-type file
+
+# Filter by chat type (group / p2p)
+lark-cli im +messages-search --query "progress" --chat-type group
+
+# Filter by sender type (user / bot)
+lark-cli im +messages-search --query "reminder" --sender-type bot
+
+# Exclude bot senders
+lark-cli im +messages-search --query "reminder" --exclude-sender-type bot
+
+# Only messages that @me
+lark-cli im +messages-search --query "announcement" --is-at-me
+
+# Only messages that @mention specific users (results also include messages that @all)
+lark-cli im +messages-search --query "release" --at-chatter-ids ou_xxx,ou_yyy
+
+# Combined filters + time range
+lark-cli im +messages-search --query "meeting" --sender ou_xxx --chat-type group --start "2026-03-13T00:00:00+08:00" --end "2026-03-20T23:59:59+08:00"
+
+# Specific time range (ISO 8601)
+lark-cli im +messages-search --query "release" --start "2026-03-01T00:00:00+08:00" --end "2026-03-10T00:00:00+08:00"
+
+# Output format options
+lark-cli im +messages-search --query "test" --format pretty
+lark-cli im +messages-search --query "test" --format table
+lark-cli im +messages-search --query "test" --format csv
+
+# Pagination
+lark-cli im +messages-search --query "test" --page-token <PAGE_TOKEN>
+
+# Auto-pagination across multiple pages
+lark-cli im +messages-search --query "test" --page-all --format json
+
+# Auto-pagination with an explicit page cap
+lark-cli im +messages-search --query "test" --page-limit 5 --format json
+
+# Preview the request without executing it
+lark-cli im +messages-search --query "test" --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|------|------|------|
+| `--query <text>` | No | Search keyword (may be empty when used with other filters) |
+| `--chat-id <id>` | No | Restrict to chat IDs, comma-separated (`oc_xxx,oc_yyy`) |
+| `--sender <ids>` | No | Sender open_ids, comma-separated (`ou_xxx`) |
+| `--include-attachment-type <type>` | No | Attachment filter: `file` / `image` / `video` / `link` |
+| `--chat-type <type>` | No | Chat type: `group` / `p2p` |
+| `--sender-type <type>` | No | Sender type: `user` / `bot` |
+| `--exclude-sender-type <type>` | No | Exclude messages from `user` or `bot` senders |
+| `--is-at-me` | No | Only return messages that mention `@me` |
+| `--at-chatter-ids <ids>` | No | Filter by @mentioned user open_ids, comma-separated (`ou_xxx,ou_yyy`). Matched results also include messages that `@all` |
+| `--start <time>` | No | Start time with local timezone offset required (e.g. `2026-03-24T00:00:00+08:00`) |
+| `--end <time>` | No | End time with local timezone offset required (e.g. `2026-03-25T23:59:59+08:00`) |
+| `--page-size <n>` | No | Page size (default 20, range 1-50) |
+| `--page-token <token>` | No | Pagination token for the next page |
+| `--page-all` | No | Automatically paginate through all result pages (up to 40 pages) |
+| `--page-limit <n>` | No | Max pages to fetch when auto-pagination is enabled (default 20, max 40). Setting it explicitly also enables auto-pagination |
+| `--format <fmt>` | No | Output format: `json` (default) / `pretty` / `table` / `ndjson` / `csv` |
+| `--as <identity>` | No | Identity type (defaults to and only supports `user`) |
+| `--dry-run` | No | Print the request only, do not execute it |
+
+## Core Constraints
+
+### 1. Provide at least one filter whenever possible
+
+All parameters are optional, but you should usually provide at least one filter (`--query`, `--sender`, `--chat-id`, etc.). Otherwise the search scope may be too broad and return low-signal results.
+
+### 2. Two-step orchestration is automatic
+
+The shortcut automatically performs:
+
+1. The **search API** returns matching `message_id` values
+2. The **mget API** fetches full message content for those message IDs in batch
+3. Chat context lookup is fetched in batch and attached to each message
+
+The user does not need to manage the orchestration manually. When search results span multiple pages, the shortcut can also paginate automatically with `--page-all` or `--page-limit`.
+
+### 3. Conversation context is enriched automatically
+
+In JSON output, each message automatically includes conversation context:
+
+| Field | Description |
+|------|------|
+| `chat_type` | Conversation type: `p2p` / `group` |
+| `chat_name` | Group name (for groups) or the other participant's name (for p2p chats) |
+| `chat_partner` | For p2p only: the other participant's `open_id` and `name` |
+
+In pretty output, the `chat` column shows the chat name for groups, or `"p2p"` for direct messages.
+
+Each message in JSON output 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 |
+| `chat_id` | ID of the conversation the message belongs to |
+| `deleted` | Whether the message has been recalled (`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 |
+
+### 4. Pagination behavior
+
+- Default behavior is still **single-page**.
+- `--page-token` is the manual continuation mechanism when you already have a token from a previous response.
+- `--page-all` enables auto-pagination and uses a default cap of **40 pages**.
+- `--page-limit <n>` enables auto-pagination with an explicit cap. If you pass `--page-limit` without `--page-all`, auto-pagination is still enabled.
+- When auto-pagination stops because of the configured page cap, the response still includes the last `has_more` / `page_token` so you can continue manually.
+
+### 5. Search results contain follow-up clues
+
+In JSON output, each message includes `chat_id` and `thread_id` (when present). Use them with other shortcuts for deeper inspection:
+
+```bash
+# View the full message stream for the conversation that contains the search result
+lark-cli im +chat-messages-list --chat-id <chat_id>
+
+# View replies in the thread that contains the search result
+lark-cli im +threads-messages-list --thread <thread_id>
+```
+
+## Resource Rendering
+
+Search results reuse the same content formatter as other read commands. Image messages are rendered as placeholders such as `![Image](img_xxx)`; resource binaries are **not** downloaded automatically.
+
+Use `im +messages-resources-download` if you need to fetch the underlying image or file bytes from a specific message.
+
+## AI Usage Guidance
+
+### Query boundary for activity review
+
+Use `--query` only for real message keywords. If the user asks for activity review such as "最近一周我和哪些 Bot 有过交互" or "整理我和某人的聊天记录", and the useful constraints are sender type, chat, person, or time range, keep `--query ""` and rely on those filters. Do not put generic instruction words such as "看看", "总结", "交互内容", or "聊天记录" into `--query`; those words often over-constrain message search and hide the relevant messages.
+
+This guidance applies only when using user identity. `im +messages-search` is user-only; if the user explicitly asks for application/bot identity, do not try `--as bot`. For bot identity with a named group and history/listing intent, resolve the group with `im +chat-search --as bot`, then list messages with `im +chat-messages-list --as bot --chat-id <chat_id>`.
+
+```bash
+# Review recent bot interactions without forcing a keyword
+lark-cli im +messages-search --query "" --sender-type bot --start "<YYYY-MM-DDT00:00:00+08:00>" --end "<YYYY-MM-DDT23:59:59+08:00>" --page-all --format json
+```
+
+Replace the time placeholders at execution time. For example, "最近一周" means computing the start date and end date from the current day before running the command; do not copy date literals from this reference into answers for relative requests.
+
+For activity summaries, validate evidence by message IDs and chat context. The final answer should cite or retain the `message_id`, sender, chat, and create time for each important item. If the row's source data contains concrete `om_...` message IDs or `ou_...` user IDs, treat those IDs as strong recall targets during verification; do not rely only on a high-level keyword match.
+
+### Resolving chat_id from a chat name
+
+When the user refers to a chat by name and you need its `chat_id` for the `--chat-id` filter, use [`+chat-search`](lark-im-chat-search.md) first:
+
+```bash
+# Step 1: Find the chat_id by name
+lark-cli im +chat-search --query "<chat name keyword>" --format json
+
+# Step 2: Use the chat_id to narrow down message search
+lark-cli im +messages-search --query "keyword" --chat-id <chat_id>
+```
+
+**Do not use `im chats search` or `+chat-list` — always use the `+chat-search` shortcut.**
+
+## Work Summary / Report Generation
+
+When the user asks you to summarize work, generate a weekly report, or compile activity from chat messages, you should **paginate through all available results** to get a complete picture. A single page is rarely enough for thorough summarization.
+
+### Strategy
+
+1. **Start with targeted filters** — use `--chat-id`, `--sender`, `--start`, `--end` to narrow the scope as much as possible before paginating.
+2. **Prefer auto-pagination** — for report and summary tasks, use `--page-all --format json` by default. If you need a bounded run, use `--page-limit <n> --format json`.
+3. **Accumulate before summarizing** — collect all pages of messages first, then analyze and summarize. Do not summarize after the first page alone — you will miss important context.
+4. **Fall back to `--page-token` when resuming** — if auto-pagination hits the configured page cap and the response still has `has_more=true`, continue from the returned `page_token`.
+5. **Use `--format json`** — JSON output includes `has_more` and `page_token` fields needed for pagination. `pretty` and `table` formats are useful for reading but not for resuming pagination reliably.
+
+### Example: Weekly work summary from a project chat
+
+```bash
+# Preferred: fetch automatically
+lark-cli im +messages-search --query "" --chat-id oc_xxx --sender ou_me --start "2026-03-18T00:00:00+08:00" --end "2026-03-25T23:59:59+08:00" --page-size 50 --page-all --format json
+
+# If you need to cap the run explicitly
+lark-cli im +messages-search --query "" --chat-id oc_xxx --sender ou_me --start "2026-03-18T00:00:00+08:00" --end "2026-03-25T23:59:59+08:00" --page-size 50 --page-limit 5 --format json
+
+# If the bounded run still returns has_more=true, continue manually
+lark-cli im +messages-search --query "" --chat-id oc_xxx --sender ou_me --start "2026-03-18T00:00:00+08:00" --end "2026-03-25T23:59:59+08:00" --page-size 50 --page-token <token_from_previous_run> --format json
+```
+
+### Key points
+
+- **Always paginate exhaustively** for summary tasks. A single page of 20-50 messages is usually insufficient for a meaningful work summary.
+- Prefer `--page-all`; use `--page-limit` only when you need to bound runtime or output volume.
+- If the user does not specify a time range, default to the current week (Monday to today) for weekly reports, or ask for clarification.
+- When summarizing, group messages by topic/thread rather than by chronological order for better readability.
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| Too few results | The time range is too narrow or the keyword is too specific | Expand the time range and try broader keywords |
+| No results | Missing permission or no match | Confirm `search:message` is authorized and relax the filters |
+| Permission denied | Search scope not authorized | Run `auth login --scope "search:message"` |
+
+## References
+
+- [lark-im](../SKILL.md) - all message-related commands
+- [lark-im-threads-messages-list](lark-im-threads-messages-list.md) - inspect thread replies
+- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters