@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/lark-tools/cli-skills/lark-event/references/lark-event-subscribe.md

@@ -0,0 +1,217 @@
+
+# event +subscribe
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Subscribe to Lark events via WebSocket long connection, outputting NDJSON to stdout. Supports compact (agent-friendly) format, regex-based routing, and file output.
+
+**Identity / Risk:**
+- **Identity**: bot-only — uses App ID + App Secret to establish the WebSocket connection. No user login needed (`lark-cli config init` is sufficient).
+- **Risk**: read — this is a read-only subscription command. It receives events but does not modify any resources.
+
+**Platform-side configuration** (must be done in the Lark Open Platform console):
+1. Events & Callbacks → Subscription method → Select "Use long connection to receive events"
+2. Add the events you need (e.g. `im.message.receive_v1`)
+3. Enable the corresponding permissions (e.g. `im:message:receive_as_bot`)
+
+## Commands
+
+```bash
+# Subscribe to all registered events (catch-all mode, 25 common event types)
+lark-cli event +subscribe
+
+# Subscribe to specific event types only
+lark-cli event +subscribe --event-types im.message.receive_v1
+
+# Subscribe to multiple event types
+lark-cli event +subscribe --event-types im.message.receive_v1,calendar.calendar.event.changed_v4
+
+# Client-side regex filter (applied after SDK receives events)
+lark-cli event +subscribe --filter "^im\."
+
+# Agent-friendly format (parse content, strip noise fields)
+lark-cli event +subscribe --event-types im.message.receive_v1 --compact --quiet
+
+# Pretty-print JSON output
+lark-cli event +subscribe --json
+
+# Write each event to a file
+lark-cli event +subscribe --output-dir ./events
+
+# Route events to different directories by regex
+lark-cli event +subscribe \
+  --route '^im\.message=dir:./im/' \
+  --route '^contact\.=dir:./contacts/'
+
+# Route IM events to files, other events to stdout
+lark-cli event +subscribe --route '^im\.=dir:./im-events/'
+
+# Preview configuration without connecting
+lark-cli event +subscribe --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|------|------|------|
+| `--event-types <types>` | No | Comma-separated event types to register with the SDK dispatcher. Only these types will be received. Omit for catch-all mode (24 common types) |
+| `--filter <regex>` | No | Client-side regex filter on event_type, applied after the SDK delivers events. Can be combined with `--event-types` |
+| `--compact` | No | Agent-friendly output: flatten structure, extract human-readable content, strip noise fields (schema, token, tenant_key, app_id) |
+| `--json` | No | Pretty-print JSON instead of NDJSON (one line per event) |
+| `--output-dir <dir>` | No | Write each event as an individual file: `{type}_{id}_{ts}.json` |
+| `--route <spec>` | No | Regex-based event routing. Format: `regex=dir:./path`. Repeatable. Unmatched events fall through to `--output-dir` or stdout |
+| `--quiet` | No | Suppress stderr status messages |
+| `--force` | No | Bypass single-instance lock. **UNSAFE**: the server splits events randomly across connections, each instance only receives a subset |
+| `--dry-run` | No | Print configuration only, do not connect to WebSocket |
+
+## Output Formats
+
+### Default (raw NDJSON)
+
+One event per line, all fields included:
+
+```json
+{"schema":"2.0","header":{"event_id":"xxx","event_type":"im.message.receive_v1","create_time":"1773491924409","app_id":"cli_xxx"},"event":{"message":{"chat_id":"oc_xxx","content":"{\"text\":\"Hello\"}","message_id":"om_xxx","message_type":"text"},"sender":{"sender_id":{"open_id":"ou_xxx"},"sender_type":"user"}}}
+```
+
+### `--compact` (agent-friendly)
+
+Flattened key-value output with semantic fields. The exact fields depend on the event type and its processor.
+
+**IM message events** (`im.message.receive_v1`) have deep compact processing:
+
+```json
+{"type":"im.message.receive_v1","id":"om_xxx","message_id":"om_xxx","chat_id":"oc_xxx","chat_type":"p2p","message_type":"text","content":"Hello","sender_id":"ou_xxx","create_time":"1773491924409","timestamp":"1773491924409"}
+```
+
+- `event.message.content` (double-encoded JSON like `"{\"text\":\"Hello\"}"`) is parsed and converted to human-readable text via convertlib → output as `content`
+- `event.sender.sender_id.open_id` → flattened to `sender_id`
+- `schema`, `token`, `tenant_key`, `app_id` stripped
+- Supports all message types: text, post, image, file, card, etc.
+
+**Other IM events** (reactions, chat member changes, chat updates) also have specialized compact processors with relevant semantic fields.
+
+**Non-IM events** (contact, calendar, approval, task, drive, application) use the generic compact processor:
+- Parses the event payload as a flat map
+- Injects `type` (event_type), `event_id`, and `timestamp` from the event header
+- All original event fields are preserved as-is
+
+Agent pipelines should **always use `--compact --quiet`**.
+
+## Catch-all Event Types
+
+The following 24 event types are registered in catch-all mode (when `--event-types` is omitted):
+
+### IM
+
+| Event Type | Description | Required Scope |
+|-----------|-------------|---------------|
+| `im.message.receive_v1` | Receive message | `im:message:receive_as_bot` |
+| `im.message.message_read_v1` | Message read | `im:message:receive_as_bot` |
+| `im.message.reaction.created_v1` | Reaction added | `im:message:receive_as_bot` |
+| `im.message.reaction.deleted_v1` | Reaction removed | `im:message:receive_as_bot` |
+| `im.chat.member.bot.added_v1` | Bot added to chat | `im:chat:readonly` |
+| `im.chat.member.bot.deleted_v1` | Bot removed from chat | `im:chat:readonly` |
+| `im.chat.member.user.added_v1` | User added to chat | `im:chat:readonly` |
+| `im.chat.member.user.withdrawn_v1` | User add withdrawn | `im:chat:readonly` |
+| `im.chat.member.user.deleted_v1` | User removed from chat | `im:chat:readonly` |
+| `im.chat.updated_v1` | Chat info updated | `im:chat:readonly` |
+| `im.chat.disbanded_v1` | Chat disbanded | `im:chat:readonly` |
+
+### Contact
+
+| Event Type | Description | Required Scope |
+|-----------|-------------|---------------|
+| `contact.user.created_v3` | User created | `contact:user.base:readonly` |
+| `contact.user.updated_v3` | User updated | `contact:user.base:readonly` |
+| `contact.user.deleted_v3` | User deleted | `contact:user.base:readonly` |
+| `contact.department.created_v3` | Department created | `contact:department.base:readonly` |
+| `contact.department.updated_v3` | Department updated | `contact:department.base:readonly` |
+| `contact.department.deleted_v3` | Department deleted | `contact:department.base:readonly` |
+
+### Calendar
+
+| Event Type | Description | Required Scope |
+|-----------|-------------|---------------|
+| `calendar.calendar.acl.created_v4` | Calendar ACL created | `calendar:calendar.acl:readonly` |
+| `calendar.calendar.event.changed_v4` | Calendar event changed | `calendar:calendar:readonly` |
+
+### Approval
+
+| Event Type | Description | Required Scope |
+|-----------|-------------|---------------|
+| `approval.approval.updated` | Approval status updated | `approval:approval:readonly` |
+
+### Application
+
+| Event Type | Description | Required Scope |
+|-----------|-------------|---------------|
+| `application.application.visibility.added_v6` | App visibility added | `application:application.app_visibility:readonly` |
+
+### Task
+
+| Event Type | Description | Required Scope |
+|-----------|-------------|---------------|
+| `task.task.update_tenant_v1` | Task updated (tenant) | `task:task:readonly` |
+| `task.task.update_user_access_v2` | Task updated (user access) | `task:task:readonly` |
+| `task.task.comment_updated_v1` | Task comment updated | `task:task:readonly` |
+
+### Drive
+
+| Event Type | Description | Required Scope |
+|-----------|-------------|---------------|
+| `drive.notice.comment_add_v1` | Drive comment added | `drive:drive:readonly` |
+
+See the full list at [Lark Event List](https://open.feishu.cn/document/server-docs/event-subscription-guide/event-list).
+
+## Agent Pipeline Examples
+
+### Listen for messages and reply with the configured assistant
+
+```bash
+lark-cli event +subscribe \
+  --event-types im.message.receive_v1 --compact --quiet \
+  | while IFS= read -r line; do
+      content=$(echo "$line" | jq -r '.content // empty')
+      message_id=$(echo "$line" | jq -r '.message_id // empty')
+      [[ -z "$content" ]] && continue
+
+      # Requires an installed and authenticated Codex CLI.
+      answer=$(codex exec --ephemeral --ignore-user-config --sandbox read-only --skip-git-repo-check \
+        "Reply concisely: $content" < /dev/null 2>/dev/null)
+
+      # Reply as bot
+      reply_data=$(jq -n --arg t "$answer" '{msg_type:"text",content:({text:$t}|tojson)}')
+      lark-cli api POST "/open-apis/im/v1/messages/$message_id/reply" \
+        --data "$reply_data" --as bot --format data
+    done
+```
+
+### Listen for messages and log to a Lark document
+
+```bash
+lark-cli event +subscribe \
+  --event-types im.message.receive_v1 --compact --quiet \
+  | while IFS= read -r line; do
+      content=$(echo "$line" | jq -r '.content // empty')
+      [[ -z "$content" ]] && continue
+
+      lark-cli docs +update --doc "DOC_URL" --mode append --markdown "- $content"
+    done
+```
+
+## Notes
+
+- **Events must be configured in the Open Platform console** — the CLI cannot dynamically subscribe to event types
+- `--event-types` controls which types the SDK dispatcher registers for. Unregistered types are silently dropped even if the server sends them. Omitting this flag registers 24 common types (catch-all)
+- `--filter` is a pure client-side regex filter applied after the SDK delivers events. It does not affect which events are registered
+- `--force` bypasses the single-instance lock per app. Without it, only one `+subscribe` process is allowed per app to prevent the server from splitting events across connections
+- WebSocket auto-reconnects on disconnection (SDK built-in)
+- `Ctrl+C` gracefully shuts down and prints the total event count
+- Reply to messages with `lark-cli api ... --as bot` — no user login needed
+
+## References
+
+- [lark-im](../../lark-im/SKILL.md) — Messaging commands
+- [lark-doc-update](../../lark-doc/references/lark-doc-update.md) — Update Lark documents
+- [lark-shared](../../lark-shared/SKILL.md) — Authentication and global parameters

package/server/assets/skills/lark-tools/cli-skills/lark-im/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: lark-im
+version: 1.0.0
+description: "飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件（支持大文件分片下载）、管理表情回复。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员时使用。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli im --help"
+---
+
+# im (v1)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+
+## Core Concepts
+
+- **Message**: A single message in a chat, identified by `message_id` (om_xxx). Supports types: text, post, image, file, audio, video, sticker, interactive (card), share_chat, share_user, merge_forward, etc.
+- **Chat**: A group chat or P2P conversation, identified by `chat_id` (oc_xxx).
+- **Thread**: A reply thread under a message, identified by `thread_id` (om_xxx or omt_xxx).
+- **Reaction**: An emoji reaction on a message.
+
+## Resource Relationships
+
+```
+Chat (oc_xxx)
+├── Message (om_xxx)
+│   ├── Thread (reply thread)
+│   ├── Reaction (emoji)
+│   └── Resource (image / file / video / audio)
+└── Member (user / bot)
+```
+
+## Important Notes
+
+### Identity and Token Mapping
+
+- `--as user` means **user identity** and uses `user_access_token`. Calls run as the authorized end user, so permissions depend on both the app scopes and that user's own access to the target chat/message/resource.
+- `--as bot` means **bot identity** and uses `tenant_access_token`. Calls run as the app bot, so behavior depends on the bot's membership, app visibility, availability range, and bot-specific scopes.
+- If an IM API says it supports both `user` and `bot`, the token type changes who the operator is. The same API can succeed with one identity and fail with the other because owner/admin status, chat membership, tenant boundary, or app availability are checked against the current caller.
+
+### Sender Name Resolution with Bot Identity
+
+When using bot identity (`--as bot`) to fetch messages (e.g. `+chat-messages-list`, `+threads-messages-list`, `+messages-mget`), sender names may not be resolved (shown as open_id instead of display name). This happens when the bot cannot access the user's contact info.
+
+**Root cause**: The bot's app visibility settings do not include the message sender, so the contact API returns no name.
+
+**Solution**: Check the app's visibility settings in the Lark Developer Console — ensure the app's visible range covers the users whose names need to be resolved. Alternatively, use `--as user` to fetch messages with user identity, which typically has broader contact access.
+
+### Card Messages (Interactive)
+
+Card messages (`interactive` type) are not yet supported for compact conversion in event subscriptions. The raw event data will be returned instead, with a hint printed to stderr.
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用操作的高级封装（`lark-cli im +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+chat-create`](references/lark-im-chat-create.md) | Create a group chat; user/bot; creates private/public chats, invites users/bots, optionally sets bot manager |
+| [`+chat-messages-list`](references/lark-im-chat-messages-list.md) | List messages in a chat or P2P conversation; user/bot; accepts --chat-id or --user-id, resolves P2P chat_id, supports time range/sort/pagination |
+| [`+chat-search`](references/lark-im-chat-search.md) | Search visible group chats by keyword and/or member open_ids (e.g. look up chat_id by group name); user/bot; supports member/type filters, sorting, and pagination |
+| [`+chat-update`](references/lark-im-chat-update.md) | Update group chat name or description; user/bot; updates a chat's name or description |
+| [`+messages-mget`](references/lark-im-messages-mget.md) | Batch get messages by IDs; user/bot; fetches up to 50 om_ message IDs, formats sender names, expands thread replies |
+| [`+messages-reply`](references/lark-im-messages-reply.md) | Reply to a message (supports thread replies); user/bot; supports text/markdown/post/media replies, reply-in-thread, idempotency key |
+| [`+messages-resources-download`](references/lark-im-messages-resources-download.md) | Download images/files from a message; user/bot; supports automatic chunked download for large files (8MB chunks), auto-detects file extension from Content-Type |
+| [`+messages-search`](references/lark-im-messages-search.md) | Search messages across chats (supports keyword, sender, time range filters) with user identity; user-only; filters by chat/sender/attachment/time, supports auto-pagination via `--page-all` / `--page-limit`, enriches results via batched mget and chats batch_query |
+| [`+messages-send`](references/lark-im-messages-send.md) | Send a message to a chat or direct message; user/bot; sends to chat-id or user-id with text/markdown/post/media, supports idempotency key |
+| [`+threads-messages-list`](references/lark-im-threads-messages-list.md) | List messages in a thread; user/bot; accepts om_/omt_ input, resolves message IDs to thread_id, supports sort/pagination |
+
+## API Resources
+
+```bash
+lark-cli schema im.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli im <resource> <method> [flags] # 调用 API
+```
+
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+
+### chats
+
+  - `create` — 创建群。Identity: `bot` only (`tenant_access_token`).
+  - `get` — 获取群信息。Identity: supports `user` and `bot`; the caller must be in the target chat to get full details, and must belong to the same tenant for internal chats.
+  - `link` — 获取群分享链接。Identity: supports `user` and `bot`; the caller must be in the target chat, must be an owner or admin when chat sharing is restricted to owners/admins, and must belong to the same tenant for internal chats.
+  - `list` — 获取用户或机器人所在的群列表。Identity: supports `user` and `bot`.
+  - `update` — 更新群信息。Identity: supports `user` and `bot`.
+
+### chat.members
+
+  - `create` — 将用户或机器人拉入群聊。Identity: supports `user` and `bot`; the caller must be in the target chat; for `bot` calls, added users must be within the app's availability; for internal chats the operator must belong to the same tenant; if only owners/admins can add members, the caller must be an owner/admin, or a chat-creator bot with `im:chat:operate_as_owner`.
+  - `delete` — 将用户或机器人移出群聊。Identity: supports `user` and `bot`; only group owner, admin, or creator bot can remove others; max 50 users or 5 bots per request.
+  - `get` — 获取群成员列表。Identity: supports `user` and `bot`; the caller must be in the target chat and must belong to the same tenant for internal chats.
+
+### messages
+
+  - `delete` — 撤回消息。Identity: supports `user` and `bot`; for `bot` calls, the bot must be in the chat to revoke group messages; to revoke another user's group message, the bot must be the owner, an admin, or the creator; for user P2P recalls, the target user must be within the bot's availability.
+  - `forward` — 转发消息。Identity: `bot` only (`tenant_access_token`).
+  - `merge_forward` — 合并转发消息。Identity: `bot` only (`tenant_access_token`).
+  - `read_users` — 查询消息已读信息。Identity: `bot` only (`tenant_access_token`); the bot must be in the chat, and can only query read status for messages it sent within the last 7 days.
+
+### reactions
+
+  - `batch_query` — 批量获取消息表情。Identity: supports `user` and `bot`.[Must-read](references/lark-im-reactions.md)
+  - `create` — 添加消息表情回复。Identity: supports `user` and `bot`; the caller must be in the conversation that contains the message.[Must-read](references/lark-im-reactions.md)
+  - `delete` — 删除消息表情回复。Identity: supports `user` and `bot`; the caller must be in the conversation that contains the message, and can only delete reactions added by itself.[Must-read](references/lark-im-reactions.md)
+  - `list` — 获取消息表情回复。Identity: supports `user` and `bot`; the caller must be in the conversation that contains the message.[Must-read](references/lark-im-reactions.md)
+
+### images
+
+  - `create` — 上传图片。Identity: `bot` only (`tenant_access_token`).
+
+### pins
+
+  - `create` — Pin 消息。Identity: supports `user` and `bot`.
+  - `delete` — 移除 Pin 消息。Identity: supports `user` and `bot`.
+  - `list` — 获取群内 Pin 消息。Identity: supports `user` and `bot`.
+
+## 权限表
+
+| 方法 | 所需 scope |
+|------|-----------|
+| `chats.create` | `im:chat:create` |
+| `chats.get` | `im:chat:read` |
+| `chats.link` | `im:chat:read` |
+| `chats.list` | `im:chat:read` |
+| `chats.update` | `im:chat:update` |
+| `chat.members.create` | `im:chat.members:write_only` |
+| `chat.members.delete` | `im:chat.members:write_only` |
+| `chat.members.get` | `im:chat.members:read` |
+| `messages.delete` | `im:message:recall` |
+| `messages.forward` | `im:message` |
+| `messages.merge_forward` | `im:message` |
+| `messages.read_users` | `im:message:readonly` |
+| `reactions.batch_query` | `im:message.reactions:read` |
+| `reactions.create` | `im:message.reactions:write_only` |
+| `reactions.delete` | `im:message.reactions:write_only` |
+| `reactions.list` | `im:message.reactions:read` |
+| `images.create` | `im:resource` |
+| `pins.create` | `im:message.pins:write_only` |
+| `pins.delete` | `im:message.pins:write_only` |
+| `pins.list` | `im:message.pins:read` |

package/server/assets/skills/lark-tools/cli-skills/lark-im/references/lark-im-chat-create.md

@@ -0,0 +1,156 @@
+# im +chat-create
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Create a group chat. Supports both user identity (`--as user`) and bot identity (`--as bot`). You can specify the group name, description, members (users/bots), owner, and chat type (private/public).
+
+This skill maps to the shortcut: `lark-cli im +chat-create` (internally calls `POST /open-apis/im/v1/chats`).
+
+- `--as bot` requires the `im:chat:create` scope.
+- `--as user` requires the `im:chat:create_by_user` scope.
+
+## Commands
+
+```bash
+# Create a private group (default)
+lark-cli im +chat-create --name "My Group"
+
+# Create a public group (name is required and must be at least 2 characters)
+lark-cli im +chat-create --name "Public Group" --type public
+
+# Specify the group owner
+lark-cli im +chat-create --name "My Group" --owner ou_xxx
+
+# Invite user members (comma-separated open_ids, up to 50)
+lark-cli im +chat-create --name "My Group" --users "ou_aaa,ou_bbb"
+
+# Invite bot members (comma-separated app IDs, up to 5)
+lark-cli im +chat-create --name "My Group" --bots "cli_aaa,cli_bbb"
+
+# Invite both users and bots
+lark-cli im +chat-create --name "My Group" --users "ou_aaa" --bots "cli_aaa"
+
+# Make the creating bot a group manager (bot identity only)
+lark-cli im +chat-create --name "My Group" --set-bot-manager --as bot
+
+# JSON output
+lark-cli im +chat-create --name "My Group" --format json
+
+# Create a group with bot identity
+lark-cli im +chat-create --name "My Group" --users "ou_aaa" --as bot
+
+# Create a group with user identity
+lark-cli im +chat-create --name "My Group" --users "ou_aaa,ou_bbb" --as user
+
+# Preview the request without creating anything
+lark-cli im +chat-create --name "My Group" --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Limits | Description |
+|------|------|------|------|
+| `--name <name>` | Required for public groups | Max 60 characters; at least 2 characters for public groups | Group name (`"(no subject)"` for private groups if omitted) |
+| `--description <text>` | No | Max 100 characters | Group description |
+| `--users <ids>` | No | Up to 50, format `ou_xxx` | Comma-separated user open_ids |
+| `--bots <ids>` | No | Up to 5, format `cli_xxx` | Comma-separated bot app IDs |
+| `--owner <open_id>` | No | Format `ou_xxx` | Owner open_id (defaults to the bot when using `--as bot`, or the authorized user when using `--as user`) |
+| `--type <type>` | No | `private` (default) or `public` | Group type |
+| `--set-bot-manager` | No | - | Set the creating bot as a group manager (only effective with `--as bot`) |
+| `--format json` | No | - | Output as JSON |
+| `--as <identity>` | No | `bot` or `user` | Identity type |
+| `--dry-run` | No | - | Preview the request without executing it |
+
+## AI Usage Guidance
+
+### When using `--as bot`
+
+Bot may fail to invite users who are mutually invisible to it during group creation (error 232043). To avoid this, use the **two-step flow** below instead of passing other users' open_ids in `--users`.
+
+1. **Get the current user's open_id:** Run `lark-cli contact +search-user --query "<name or email>"` to retrieve it.
+2. **Create the group — by default include the current user:**
+
+   ```bash
+   lark-cli im +chat-create --name "<group name>" \
+     --users "<current user open_id>" --as bot
+   ```
+
+   **Default behavior:** Always add the current user to the group, unless the user explicitly says "do not add me" or "bot-only group" — only then omit `--users`.
+
+3. **Add other members via user identity** (requires the current user to be in the group):
+
+   ```bash
+   lark-cli im chat.members create \
+     --params '{"chat_id":"<chat_id from step 2>","member_id_type":"open_id","succeed_type":1}' \
+     --data '{"id_list":["ou_aaa","ou_bbb"]}' \
+     --as user
+   ```
+
+   `succeed_type=1` ensures reachable users are added successfully; unreachable ones are returned in `invalid_id_list` instead of failing the whole request.
+
+4. **Check `invalid_id_list`** in the response. If non-empty, report to the user which members could not be added.
+
+### When using `--as user`
+
+User identity does not have the bot visibility limitation, so you can create the group and invite members in one step:
+
+```bash
+lark-cli im +chat-create --name "<group name>" --users "ou_aaa,ou_bbb" --as user
+```
+
+The authorized user is automatically the group creator and member.
+
+## Output Fields
+
+| Field | Description |
+|------|------|
+| `chat_id` | The new group's ID (`oc_xxx` format) |
+| `name` | Group name |
+| `chat_type` | Group type (`private` / `public`) |
+| `owner_id` | Owner ID (may be empty when a bot creates the group and `--owner` is not specified) |
+| `external` | Whether the group is external |
+| `share_link` | Group share link (omitted if retrieval fails) |
+
+## Usage Scenarios
+
+### Scenario 1: Create a group and specify the owner
+
+```bash
+lark-cli im +chat-create --name "Project Discussion Group" --owner ou_xxx
+```
+
+### Scenario 2: Create a group and invite users and a bot
+
+```bash
+lark-cli im +chat-create --name "Project Discussion Group" \
+  --owner ou_xxx \
+  --users "ou_aaa,ou_bbb" \
+  --bots "cli_aaa"
+```
+
+### Scenario 3: Create a group and send a welcome message
+
+```bash
+CHAT_ID=$(lark-cli im +chat-create --name "New Group" --format json | jq -r '.data.chat_id')
+lark-cli im +messages-send --chat-id "$CHAT_ID" --text "Welcome, everyone!"
+```
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| Permission denied (99991672) | The app does not have `im:chat:create` (bot) or `im:chat:create_by_user` (user) permission enabled | Enable the required permission for the app in the Open Platform console |
+| `--name is required for public groups and must be at least 2 characters` | A public group was created without a name or with a name shorter than 2 characters | Provide a name with at least 2 characters |
+| `--name exceeds the maximum of 60 characters` | The group name is too long | Shorten the name to 60 characters or fewer |
+| `--description exceeds the maximum of 100 characters` | The group description is too long | Shorten the description to 100 characters or fewer |
+| `--users exceeds the maximum of 50` | Too many user members were provided | Split the operation into batches and add more members later |
+| `--bots exceeds the maximum of 5` | Too many bot members were provided | Invite at most 5 bots at once |
+| `invalid user id: expected open_id (ou_xxx)` | Invalid user ID format | Use the `ou_xxx` format for users |
+| `invalid bot id: expected app ID (cli_xxx)` | Invalid bot ID format | Use the `cli_xxx` format for bots |
+| `invalid --owner: expected open_id (ou_xxx)` | Invalid owner ID format | Use the `ou_xxx` format for the owner |
+| `bot is invisible to user` (232043) | The bot and target users are mutually invisible | Follow the two-step flow in AI Usage Guidance above — do not pass other users in `--users` during creation |
+
+## References
+
+- [lark-im](../SKILL.md) - all IM commands
+- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters

package/server/assets/skills/lark-tools/cli-skills/lark-im/references/lark-im-chat-identity.md

@@ -0,0 +1,55 @@
+# Group Chat Identity Rules
+
+> Warning: The most common source of failure in group operations is choosing the wrong identity. Confirm the identity before performing the action.
+
+Group-chat operations support both `--as user` (UAT user identity) and `--as bot` (TAT bot identity). Choosing the correct identity is critical for success.
+
+## Basic Principles
+
+- **If the user explicitly specifies an identity:** use exactly what the user requested (`--as user` or `--as bot`) without guessing.
+- **If the user does not specify an identity:** infer the correct identity from context instead of relying on the default.
+
+## Identity Selection by Operation
+
+| Operation | Recommended Identity | Why |
+|------|---------|-----------------------------------|
+| Create group (`+chat-create`) | Depends on the scenario | Infer from context |
+| Add members (member-management flow) | `--as user` | Bot visibility is limited and often fails when the target user is mutually invisible to the bot (232024) |
+| Update group (`+chat-update`) | Owner identity | Permission changes require owner/admin privileges; owner transfer requires owner identity |
+
+## Inferring the Owner
+
+When an owner-level action is needed and the owner is unknown, infer in this order:
+
+1. A bot created the group and `--owner` was **not** specified -> the owner is the bot (`--as bot`)
+2. A bot created the group and `--owner ou_xxx` **was** specified -> the owner is that user (`--as user`)
+3. A user created the group and `--owner` was **not** specified -> the owner is the current user (`--as user`)
+4. Still unclear -> ask the user to confirm who owns the group before making owner-level changes
+
+### When the Owner Is Neither the Current User Nor the Bot
+
+If the query shows that the owner is a third-party user (`owner_id` is neither the currently authorized user nor the bot), the current identity does not have owner privileges. In that case:
+
+- **Permission/setting changes:** if the bot is an admin of the group, `--as bot` can still perform admin-level operations such as renaming the group or changing permissions.
+- **Owner-only actions such as owner transfer:** require the actual owner to complete UAT authorization via `lark-cli auth login`, then perform the action as that owner.
+- Explain the limitation clearly to the user instead of retrying blindly.
+
+## Common Pitfalls
+
+### Inviting Members During Group Creation
+
+If a bot creates a group and `--users` includes users who are mutually invisible to the bot, the entire request fails with 232043. Use two steps instead:
+
+1. Create the group with the bot first, excluding invisible users: `lark-cli im +chat-create --name "Group Name"`
+2. Add users later with a user-identity member-management flow
+
+### Insufficient Privileges
+
+- **232016 / 232002 / 232017:** the current identity is not the owner or an admin -> switch to the owner identity
+- **232011:** the current user is not in the group -> use a group-member identity, or join the group first
+- **232024:** the bot and the target user are mutually invisible -> switch to `--as user`
+
+## References
+
+- [lark-im](../SKILL.md) - all IM commands
+- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters