@wagemule/daemon 0.1.2 → 0.1.4

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

@@ -0,0 +1,136 @@
+# im +chat-search
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Search the list of group chats visible to a user or bot, including chats the user or bot belongs to and public chats visible to them. Supports keyword matching on chat names and member names, including pinyin and prefix fuzzy search.
+
+This skill maps to the shortcut: `lark-cli im +chat-search` (internally calls `POST /open-apis/im/v2/chats/search`).
+
+## Commands
+
+```bash
+# Search chats by keyword
+lark-cli im +chat-search --query "project"
+
+# Restrict by search types
+lark-cli im +chat-search --query "project" --search-types "private,public_joined"
+
+# Filter by member open_ids (with keyword)
+lark-cli im +chat-search --query "project" --member-ids "ou_xxx,ou_yyy"
+
+# Search by member open_ids only
+lark-cli im +chat-search --member-ids "ou_xxx,ou_yyy"
+
+# Only show chats you created or manage
+lark-cli im +chat-search --query "project" --is-manager
+
+# Set page size
+lark-cli im +chat-search --query "project" --page-size 10
+
+# Pagination
+lark-cli im +chat-search --query "project" --page-token "xxx"
+
+# JSON output
+lark-cli im +chat-search --query "project" --format json
+
+# Preview the request without executing it
+lark-cli im +chat-search --query "project" --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Limits | Description |
+|------|------|------|------|
+| `--query <keyword>` | No (at least one of `--query` / `--member-ids` required) | Max 64 characters | Search keyword. Supports matching localized chat names, member names, multilingual search, pinyin, and prefix fuzzy search. If the query contains `-`, it is automatically wrapped in quotes |
+| `--search-types <types>` | No | Comma-separated: `private`, `external`, `public_joined`, `public_not_joined` | Restrict the visible chat types returned by search |
+| `--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-by <field>` | No | `create_time_desc`, `update_time_desc`, `member_count_desc` | Sort field in descending order |
+| `--page-size <n>` | No | 1-100, default 20 | Number of results per page |
+| `--page-token <token>` | No | - | Pagination token from the previous response |
+| `--exclude-muted` | No | User identity only | Drop chats the current user has muted (do-not-disturb). Under `--as bot`, the flag is silently inactive (mute is a per-user setting); see "Filtering muted chats" below |
+| `--format json` | No | - | Output as JSON |
+| `--dry-run` | No | - | Preview the request without executing it |
+
+> **Note:** Supports both `--as user` (default) and `--as bot`. When using bot identity, the app must have bot capability enabled.
+
+## Output Fields
+
+| Field | Description |
+|------|------|
+| `chat_id` | Chat ID (`oc_xxx` format) |
+| `name` | Chat name |
+| `description` | Chat description |
+| `owner_id` | Owner ID |
+| `external` | Whether the chat is external |
+| `chat_status` | Chat status (`normal` / `dissolved` / `dissolved_save`) |
+
+## Filtering muted chats
+
+`--exclude-muted` (user identity only) drops chats the current user has set to do-not-disturb. After the search call, the CLI batches the page's chat_ids through `POST /open-apis/im/v1/chat_user_setting/batch_get_mute_status` and filters client-side. Under `--as bot`, the mute API is UAT-only and the filter is silently skipped.
+
+When the flag is set, the JSON envelope gains a `filter` sub-object (absent otherwise, so existing consumers are unaffected); `fetched_count == returned_count + filtered_count` always holds:
+
+```json
+{
+  "chats": [...],
+  "filter": {
+    "applied": "exclude_muted",
+    "fetched_count": 20,
+    "returned_count": 19,
+    "filtered_count": 1,
+    "hint": "Filtered out 1 muted chat(s) on this page (19 remaining, including 2 non-member public group(s)); use --page-token to fetch more."
+  }
+}
+```
+
+Note: only confirmed-muted chats count toward `filtered_count`; non-member public groups are retained and surfaced in `hint`. For strict member-only results, combine with `--search-types "private,public_joined,external"`.
+
+## Usage Scenarios
+
+### Scenario 1: Search chats that contain a keyword
+
+```bash
+lark-cli im +chat-search --query "design review"
+```
+
+### Scenario 2: Search a chat and list recent messages
+
+```bash
+CHAT_ID=$(lark-cli im +chat-search --query "project" --format json | jq -r '.data.chats[0].chat_id')
+lark-cli im +chat-messages-list --chat-id "$CHAT_ID"
+```
+
+### Scenario 3: Search a chat and send a message
+
+```bash
+CHAT_ID=$(lark-cli im +chat-search --query "daily report" --format json | jq -r '.data.chats[0].chat_id')
+lark-cli im +messages-send --chat-id "$CHAT_ID" --text "Today's progress update"
+```
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| `--query and --member-ids cannot both be empty` | Both were omitted | Provide at least `--query` or `--member-ids` |
+| Empty results | No visible chats matched the keyword or filters | Relax the keyword or filters and try again |
+| `--page-size must be an integer between 1 and 100` | page-size is out of range or not an integer | Use an integer between 1 and 100 |
+| Permission denied (99991672) | The bot app does not have `im:chat:read` TAT permission enabled | Enable the permission for the app in the Open Platform console |
+| Permission denied (99991679) with `--as user` | UAT is not authorized for `im:chat:read` | Run `lark-cli auth login --scope "im:chat:read"` |
+| `Bot ability is not activated` (232025) | The app does not have bot capability enabled | Enable bot capability in the Open Platform console |
+
+## AI Usage Guidance
+
+When the user asks to search chats, follow these rules:
+
+1. **At least one filter required:** `--query` and `--member-ids` cannot both be empty. Either alone or combined together are valid.
+2. **Search scope is limited:** only chats visible to the current user or bot can be found (joined chats plus public chats). This is not a global search over all chats.
+3. **Control result volume:** the result set may be large. Use `--page-size` deliberately.
+4. **Suggest follow-up actions:** after finding a chat, common next steps include listing recent messages (`im +chat-messages-list`) or sending a message (`im +messages-send`).
+5. **NEVER fall back to chats list:** If `+chat-search` returns empty results, do NOT attempt to use `+chat-list` or `GET /open-apis/im/v1/chats` as a fallback. The list API is not a search API — it returns all chats without keyword filtering and will not help locate the target chat. Instead, ask the user to refine the keyword or check whether the chat is visible to the current identity.
+
+## References
+
+- [lark-im](../SKILL.md) - all IM commands
+- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters

package/dist/skills/larksuite/lark-im/references/lark-im-chat-update.md

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

package/dist/skills/larksuite/lark-im/references/lark-im-flag-cancel.md

@@ -0,0 +1,67 @@
+# im +flag-cancel
+
+> **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 +flag-cancel`. Underlying API: `POST /open-apis/im/v1/flags/cancel`.
+
+## Double-Cancel Behavior (Important)
+
+A message can have flags on both layers simultaneously:
+- Message layer: `(default, message)`
+- Feed layer: `(thread, feed)` or `(msg_thread, feed)` depending on chat type
+
+**When no `--flag-type` is specified, the shortcut performs double-cancel**: removes both message layer and feed layer flags. The server handles cancel requests for non-existent flags idempotently, so this is safe.
+
+**Feed layer item_type is determined by chat_mode**:
+- Topic-style chat (`chat_mode=topic`) → `item_type=thread`
+- Regular chat (`chat_mode=group`) → `item_type=msg_thread`
+
+## Commands
+
+```bash
+# Double-cancel both layers (recommended default)
+lark-cli im +flag-cancel --as user --message-id om_xxx
+
+# Only cancel message layer
+lark-cli im +flag-cancel --as user --message-id om_xxx --flag-type message
+
+# Only cancel feed layer (need to specify item-type)
+lark-cli im +flag-cancel --as user --message-id om_xxx --item-type thread --flag-type feed
+
+# Preview request
+lark-cli im +flag-cancel --as user --message-id om_xxx --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|------|------|------|
+| `--message-id <om_xxx>` | Required | Message ID |
+| `--flag-type <name>` | No | `message` or `feed`; **when omitted, double-cancels both layers** |
+| `--item-type <name>` | No | `default\|thread\|msg_thread`; required when `--flag-type feed` |
+| `--as user` | Required | Currently only supports user identity |
+
+## Idempotency
+
+The server doesn't return an error for cancel requests when the flag doesn't exist, so repeated `+cancel` calls are idempotent.
+
+## Permissions
+
+- Required scopes: `im:feed.flag:write`, `im:message.group_msg:get_as_user`, `im:message.p2p_msg:get_as_user`, `im:chat:read`
+- The message/chat read scopes are used by the default double-cancel path to auto-detect the feed-layer item type.
+
+## Note
+
+- **Do not call +flag-list for verification**: If the cancel API returns success, the flag is removed. Calling +flag-list to verify is expensive (requires full pagination) and unnecessary.
+
+## Finding Message ID Efficiently
+
+If you have message content but not the message ID:
+
+1. **Use `+messages-search`** to find the message by content, then extract `message_id` from the result
+2. **Do NOT use `+flag-list`** to find the message — it requires full pagination and is very inefficient
+
+```bash
+# Search by message content to find message_id
+lark-cli im +messages-search --as user --query "message content here" -q '.data.items[0].message_id'
+```

package/dist/skills/larksuite/lark-im/references/lark-im-flag-create.md

@@ -0,0 +1,67 @@
+# im +flag-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 +flag-create`. Underlying API: `POST /open-apis/im/v1/flags`.
+
+## Default Behavior
+
+- **Message-layer flag** (default): `item_type=default, flag_type=message`
+- **Feed-layer flag**: Use `--flag-type feed` — automatically detects chat type to determine `item_type`:
+  - Topic-style chat (`chat_mode=topic`) → `item_type=thread`
+  - Regular chat (`chat_mode=group`) → `item_type=msg_thread`
+
+## Commands
+
+```bash
+# Flag a message (default: message-layer)
+lark-cli im +flag-create --as user --message-id om_xxx
+
+# Create feed-layer flag (auto-detects chat type)
+lark-cli im +flag-create --as user --message-id om_xxx --flag-type feed
+
+# Explicit item-type override (rarely needed)
+lark-cli im +flag-create --as user --message-id om_xxx --item-type thread --flag-type feed
+
+# Preview request (dry-run, doesn't send)
+lark-cli im +flag-create --as user --message-id om_xxx --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|------|------|------|
+| `--message-id <om_xxx>` | Required | Message ID |
+| `--flag-type <name>` | No | `message` (default) or `feed` |
+| `--item-type <name>` | No | Override auto-detection: `default\|thread\|msg_thread` (rarely needed) |
+| `--as user` | Required | Currently only supports user identity |
+
+## Valid Combinations
+
+The server only accepts these `(item_type, flag_type)` pairs:
+
+- `(default, message)` — regular message flag
+- `(thread, feed)` — feed flag in topic-style chat
+- `(msg_thread, feed)` — feed flag in regular chat
+
+## Permissions
+
+- Required scopes: `im:feed.flag:write`, `im:message.group_msg:get_as_user`, `im:message.p2p_msg:get_as_user`, `im:chat:read`
+- The message/chat read scopes are used when `--flag-type feed` is used without explicit `--item-type` so the CLI can auto-detect chat type.
+- If missing, CLI will prompt with `lark-cli auth login --scope "..."`
+
+## Note
+
+- **Do not call +flag-list for verification**: If the create API returns success, the flag is created. Calling +flag-list to verify is expensive (requires full pagination) and unnecessary.
+
+## Finding Message ID Efficiently
+
+If you have message content but not the message ID:
+
+1. **Use `+messages-search`** to find the message by content, then extract `message_id` from the result
+2. **Do NOT use `+flag-list`** to find the message — it requires full pagination and is very inefficient
+
+```bash
+# Search by message content to find message_id
+lark-cli im +messages-search --as user --query "message content here" -q '.data.items[0].message_id'
+```

package/dist/skills/larksuite/lark-im/references/lark-im-flag-list.md

@@ -0,0 +1,100 @@
+# im +flag-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 +flag-list`. Underlying API: `GET /open-apis/im/v1/flags`.
+
+## Sorting Rules (Important)
+
+The API returns data sorted by `update_time` in **ascending order**, meaning **oldest first, newest last**. When `has_more=true`, you cannot simply take the first page's items as the latest flags — you must paginate through all pages and take the last item on the last page as the newest.
+
+Recommended: use `--page-all` for auto-pagination to get the complete list, then use `-q '.data.flag_items[-1]'` to get the latest item.
+
+## Commands
+
+```bash
+# Fetch first page (default page-size=50)
+lark-cli im +flag-list --as user
+
+# Manual pagination with custom page size
+lark-cli im +flag-list --as user --page-size 30 --page-token <page_token>
+
+# Auto-paginate to get all flags (recommended)
+lark-cli im +flag-list --as user --page-all
+
+# Auto-paginate + get the latest flag
+lark-cli im +flag-list --as user --page-all -q '.data.flag_items[-1]'
+
+# Auto-paginate + get only item_id list
+lark-cli im +flag-list --as user --page-all -q '.data.flag_items[].item_id'
+
+# Disable auto-enrichment of message content (enabled by default)
+lark-cli im +flag-list --as user --page-all --enrich-feed-thread=false
+
+# Limit max pages (default 20, max 1000)
+lark-cli im +flag-list --as user --page-all --page-limit 10
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|------|------|------|
+| `--page-size <n>` | 50 | Range 1-50 (server max is 50) |
+| `--page-token <token>` | empty | Pagination token from previous page; empty string must still be provided |
+| `--page-all` | false | Auto-paginate to fetch all pages and merge results |
+| `--page-limit <n>` | 20 | Max pages in `--page-all` mode (max 1000) |
+| `--enrich-feed-thread` | true | Auto-enrich feed-layer thread entries with message content (calls `im.messages.mget`) |
+| `--as user` | Required | Currently only supports user identity |
+
+## Response Structure
+
+The response has `data` as the main body, with fields described below:
+
+| Field | Type | Description |
+|------|------|------|
+| `flag_items` | array | List of currently existing (not canceled) flags, sorted by `update_time` ascending |
+| `delete_flag_items` | array | List of previously canceled flags, sorted by `update_time` ascending |
+| `messages` | array | Message content inlined by the server for `(default, message)` type flags |
+| `has_more` | boolean | Whether there's a next page |
+| `page_token` | string | Pagination token for the next page |
+
+Note: `(thread, feed)` / `(msg_thread, feed)` entries are automatically enriched via `mget` by the shortcut, and written to the corresponding entry's `message` field.
+
+## Limitations
+
+- **delete_flag_items are not enriched**: Message content is only fetched for active flags (`flag_items`), not canceled flags (`delete_flag_items`). If you need message content for a canceled flag, query the message separately using `+messages-mget --message-ids <item_id>`.
+
+## Response Example (Sanitized)
+
+```json
+{
+  "data": {
+    "delete_flag_items": [
+      {
+        "create_time": "xxx",
+        "flag_type": "xxx",
+        "item_id": "xxx",
+        "item_type": "xxx",
+        "update_time": "xxx"
+      }
+    ],
+    "flag_items": [
+      {
+        "create_time": "xxx",
+        "flag_type": "xxx",
+        "item_id": "xxx",
+        "item_type": "xxx",
+        "update_time": "xxx"
+      }
+    ],
+    "has_more": false,
+    "messages": [],
+    "page_token": "xxx"
+  }
+}
+```
+
+## Permissions
+
+- Base scope: `im:feed.flag:read`
+- Additional scopes only when `--enrich-feed-thread=true` needs to fetch missing message content: `im:message.group_msg:get_as_user`, `im:message.p2p_msg:get_as_user`

package/dist/skills/larksuite/lark-im/references/lark-im-messages-mget.md

@@ -0,0 +1,95 @@
+# im +messages-mget
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Fetch message details in batch. Given a list of message IDs, this returns the full content for multiple messages in one call and automatically resolves sender names.
+
+> **Supports both `--as user` (default) and `--as bot`.**
+
+This skill maps to the shortcut: `lark-cli im +messages-mget` (internally calls `GET /open-apis/im/v1/messages/mget`).
+
+## Commands
+
+```bash
+# Fetch a single message
+lark-cli im +messages-mget --message-ids om_xxx
+
+# Fetch multiple messages in batch (comma-separated)
+lark-cli im +messages-mget --message-ids "om_aaa,om_bbb,om_ccc"
+
+# JSON output
+lark-cli im +messages-mget --message-ids "om_aaa,om_bbb" --format json
+
+# Preview the request without executing it
+lark-cli im +messages-mget --message-ids "om_aaa" --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Limits | Description |
+|------|------|------|------|
+| `--message-ids <ids>` | Yes | At least one, max 50, `om_xxx` format, comma-separated | Message ID list |
+
+## Output Fields
+
+| Field | Description |
+|------|------|
+| `messages` | Message array |
+| `total` | Number of messages returned |
+
+Each message contains:
+
+| Field | Description |
+|------|------|
+| `message_id` | Message ID |
+| `msg_type` | Message type (`text`, `image`, `file`, etc.) |
+| `create_time` | Creation time |
+| `sender` | Sender information (includes `name`) |
+| `content` | Message content |
+
+## Usage Scenarios
+
+### Scenario 1: Fetch the full content of a specific message
+
+```bash
+lark-cli im +messages-mget --message-ids om_xxx --format json
+```
+
+### Scenario 2: Fetch multiple messages in one batch
+
+```bash
+lark-cli im +messages-mget --message-ids "om_aaa,om_bbb,om_ccc"
+```
+
+### Scenario 3: Use together with the message list command
+
+First get message IDs via `+chat-messages-list`, then fetch full content via `+messages-mget`:
+
+```bash
+# Get the message list
+lark-cli im +chat-messages-list --chat-id oc_xxx --format json
+
+# Fetch specific message details
+lark-cli im +messages-mget --message-ids "om_aaa,om_bbb"
+```
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| `--message-ids requires at least one message ID` | No message ID was provided | Provide at least one message ID |
+| `invalid message ID: must start with om_` | Invalid message ID format | Message IDs must start with `om_` |
+| Permission denied | Message read permission is missing | Ensure the app has `im:message:readonly` and `contact:user.base:readonly` enabled |
+| Empty result | Message IDs do not exist or are not accessible | Verify the IDs and access permissions |
+
+## AI Usage Guidance
+
+1. **Use JSON for full content:** table output truncates content. Use `--format json` when the full body matters.
+2. **Sender names are already enriched:** the command resolves sender names automatically, so no extra lookup is required.
+3. **Images are rendered as placeholders:** image messages appear as placeholders such as `[Image: img_xxx]`. Use `+messages-resources-download` when you need the binary resource.
+4. **Batching is more efficient:** fetching multiple IDs in one request is better than calling the API repeatedly.
+
+## References
+
+- [lark-im](../SKILL.md) - all IM commands
+- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters