@amaster.ai/pi-lark 0.1.8 → 0.1.10

package/skills/lark-im/SKILL.md

@@ -109,7 +109,9 @@ Shortcut 是对常用操作的高级封装（`lark-cli im +<verb> [flags]`）。
 | [`+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, --order asc/desc sorting, auto-pagination |
 | [`+chat-search`](references/lark-im-chat-search.md) | Search visible group chats by --query keyword and/or --member-ids; user/bot; e.g. look up chat_id by group name; supports type filters, sorting, auto-pagination, and --exclude-muted (user identity only) |
 | [`+chat-update`](references/lark-im-chat-update.md) | Update group chat name or description; user/bot; updates a chat's name or description |
+| [`+message-read-users`](references/lark-im-message-read-status.md) | List users who read one message; user/bot; identity-specific scopes; supports bounded auto-pagination |
 | [`+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-read-status`](references/lark-im-message-read-status.md) | Batch query whether the current user read 1–50 messages; user-only; returns readable items and invalid message IDs |
 | [`+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 an image or file attached to a message; user/bot |
 | [`+messages-search`](references/lark-im-messages-search.md) | Search messages across chats (supports keyword, sender, time range filters) with user or bot identity; filters by chat/sender/attachment/time, supports auto-pagination via `--page-all` / `--page-limit`, enriches results via batched mget and chats batch_query |
@@ -169,10 +171,11 @@ lark-cli im <resource> <method> [flags] # 调用 API
 
 ### messages
 
+  - `read_status` — 批量查询当前用户对消息的已读状态。Identity: `user` only (`user_access_token`); accepts up to 50 message IDs and returns readable items plus invalid message IDs.[Must-read](references/lark-im-message-read-status.md)
   - `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: supports `user` and `bot`.
   - `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.
+  - `read_users` — 查询消息已读信息。Identity: supports `user` and `bot`; the caller must still be in the chat. A user can query messages they sent within the last 7 days, while a bot can query only messages sent by that bot within the last 7 days.[Must-read](references/lark-im-message-read-status.md)
   - `urgent_app` — 发送应用内加急。Identity: `bot` only (`tenant_access_token`); the bot must be the message sender and must be in the conversation that contains the message.
   - `urgent_phone` — 发送电话加急。Identity: `bot` only (`tenant_access_token`); the bot must be the message sender and must be in the conversation that contains the message.
   - `urgent_sms` — 发送短信加急。Identity: `bot` only (`tenant_access_token`); the bot must be the message sender and must be in the conversation that contains the message.
@@ -190,7 +193,11 @@ lark-cli im <resource> <method> [flags] # 调用 API
 
 ### images
 
-  - `create` — 上传图片。Identity: `bot` only (`tenant_access_token`).
+  - `create` — 上传图片。Identity: supports `user` and `bot`; user identity requires `im:resource` scope on the UAT.
+
+### files
+
+  - `create` — 上传文件。Identity: supports `user` and `bot`; user identity requires `im:resource` scope on the UAT.
 
 ### pins
 
@@ -225,10 +232,13 @@ lark-cli im <resource> <method> [flags] # 调用 API
 | `chat.managers.delete_managers` | `im:chat.managers:write_only` |
 | `chat.moderation.get` | `im:chat.moderation:read` |
 | `chat.moderation.update` | `im:chat:moderation:write_only` |
+| `+messages-read-status` | user: `im:message:readonly` (recommended), `im:message`, or `im:message:get_as_user` |
+| `+message-read-users` | user: `im:message:readonly` (recommended), `im:message`, `im:message:basic`, or `im:message:get_as_user`; bot: `im:message:readonly` |
+| `messages.read_status` | `im:message:readonly` (recommended), `im:message`, or `im:message:get_as_user` |
 | `messages.delete` | `im:message:recall` |
 | `messages.forward` | `im:message` |
 | `messages.merge_forward` | `im:message` |
-| `messages.read_users` | `im:message:readonly` |
+| `messages.read_users` | user: `im:message:readonly` (recommended), `im:message`, `im:message:basic`, or `im:message:get_as_user`; bot: `im:message:readonly` |
 | `messages.urgent_app` | `im:message.urgent` |
 | `messages.urgent_phone` | `im:message.urgent:phone` |
 | `messages.urgent_sms` | `im:message.urgent:sms` |
@@ -238,6 +248,7 @@ lark-cli im <resource> <method> [flags] # 调用 API
 | `reactions.list` | `im:message.reactions:read` |
 | `threads.forward` | `im:message` |
 | `images.create` | `im:resource` |
+| `files.create` | `im:resource` |
 | `pins.create` | `im:message.pins:write_only` |
 | `pins.delete` | `im:message.pins:write_only` |
 | `pins.list` | `im:message.pins:read` |

package/skills/lark-im/references/lark-im-message-read-status.md

@@ -0,0 +1,96 @@
+# IM message read status
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first for authentication and global parameters.
+
+Use two focused shortcuts for message read-status queries:
+
+- `im +messages-read-status` queries whether the current user has read 1–50 messages.
+- `im +message-read-users` lists users who have read one message and supports automatic pagination.
+
+Both underlying OpenAPIs support user identity through a user access token (UAT). `+message-read-users` additionally supports bot identity through a tenant access token (TAT).
+
+## Identity and scopes
+
+| Shortcut | Identity | Scope |
+|---|---|---|
+| `+messages-read-status` | user only | `im:message:readonly` (recommended), `im:message`, or `im:message:get_as_user` |
+| `+message-read-users` | user | `im:message:readonly` (recommended), `im:message`, `im:message:basic`, or `im:message:get_as_user` |
+| `+message-read-users` | bot | `im:message:readonly` |
+
+For `+message-read-users`, the caller must still be in the chat. A user can query only messages they sent within the last seven days, while a bot can query only messages sent by that bot within the last seven days.
+The user scopes in the table are alternatives; the CLI preflight uses `im:message:readonly` because it is the least-privileged regular OAuth scope supported by this endpoint.
+
+## Batch query the current user's read status
+
+```bash
+# Preview one request
+lark-cli im +messages-read-status \
+  --message-ids om_xxx,om_yyy \
+  --as user \
+  --dry-run
+
+# Execute with a user access token
+lark-cli im +messages-read-status \
+  --message-ids om_xxx,om_yyy \
+  --as user \
+  --json
+```
+
+The command accepts 1–50 comma-separated `om_` message IDs. The three scopes above are alternatives; any one is sufficient, and the CLI recommends the least-privileged OAuth scope `im:message:readonly`. The response keeps the OpenAPI response unchanged:
+
+- `items[].message_id` and `items[].is_read` contain statuses the server could determine.
+- `invalid_message_ids` contains messages that do not exist, are not visible to the current user, or do not support this query. The API deliberately does not expose a more specific reason.
+
+## List users who read one message
+
+```bash
+# Fetch one page as the current user
+lark-cli im +message-read-users \
+  --message-id om_xxx \
+  --as user \
+  --json
+
+# Fetch every page as a bot, bounded to ten pages by default
+lark-cli im +message-read-users \
+  --message-id om_xxx \
+  --user-id-type open_id \
+  --page-all \
+  --as bot \
+  --json
+```
+
+Pagination flags:
+
+- `--page-size`: 1–100, default 100.
+- `--page-token`: start from a known cursor.
+- `--page-all`: continue until the endpoint is exhausted.
+- `--page-limit`: maximum pages with `--page-all`; default 10, range 1–1000.
+- `--page-delay`: delay in milliseconds between pages; default 200, and 0 disables the delay.
+
+The command preserves each server item, including `user_id_type`, `user_id`, `timestamp`, and `tenant_key`. Pagination metadata reports whether the endpoint was exhausted and retains the next token when a bounded run can be resumed.
+
+## Raw API commands
+
+When Registry MR !128 is published, the corresponding raw commands remain available:
+
+```bash
+lark-cli im messages read_status --data '{"message_ids":["om_xxx"]}' --as user
+lark-cli im messages read_users --params '{"message_id":"om_xxx","user_id_type":"open_id"}' --as user
+```
+
+Prefer the shortcuts for flag validation, identity-specific scope hints, and read-users auto-pagination.
+
+## Troubleshooting
+
+| Symptom | Meaning | Action |
+|---|---|---|
+| `--as bot is not supported` for read status | The batch endpoint requires user identity | Switch to `--as user` |
+| Missing `im:message:readonly` or `im:message` | A regular OAuth scope has not been granted | Follow the CLI authorization hint to grant one supported scope |
+| Missing a user read scope | No supported regular OAuth scope has been granted | Grant `im:message:readonly` and retry |
+| Bot permission denied | The application lacks a bot scope | Open the `console_url` from the typed error and enable the requested scope |
+| Empty read-user list | No user has read the message, or sender/time constraints are not met | Verify chat membership, the message sender, and the seven-day window |
+
+## References
+
+- [lark-im](../SKILL.md)
+- [lark-shared](../../lark-shared/SKILL.md)

package/skills/lark-mail/references/lark-mail-draft-create.md

@@ -24,37 +24,37 @@
 
 ```bash
 # 创建 HTML 草稿（推荐）
-lark-cli mail +draft-create --to alice@example.com --subject '周报' \
+lark-cli mail +draft-create --to 'alice@example.com' --subject '周报' \
   --body '<p>本周进展：</p><ul><li>完成 A 模块</li></ul>'
 
 # 不带收件人的 HTML 草稿（用户之后可自行添加）
 lark-cli mail +draft-create --subject '周报' --body '<p>草稿内容</p>'
 
 # 带附件和内嵌图片的 HTML 草稿（推荐：直接用相对路径，自动解析）
-lark-cli mail +draft-create --to alice@example.com --subject '预览图' --body '<p>见附件和图：<img src="./logo.png" /></p>' --attach ./report.pdf
+lark-cli mail +draft-create --to 'alice@example.com' --subject '预览图' --body '<p>见附件和图：<img src="./logo.png" /></p>' --attach './report.pdf'
 
 # 纯文本草稿（仅在内容极简时使用）
-lark-cli mail +draft-create --to alice@example.com --subject '简短通知' --body '收到，谢谢'
+lark-cli mail +draft-create --to 'alice@example.com' --subject '简短通知' --body '收到，谢谢'
 
 # Dry Run（仅打印请求，不执行）
-lark-cli mail +draft-create --to alice@example.com --subject '测试' --body 'test' --dry-run
+lark-cli mail +draft-create --to 'alice@example.com' --subject '测试' --body 'test' --dry-run
 ```
 
 ## 参数
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--to <emails>` | 否 | 完整收件人列表，多个用逗号分隔。支持 `Alice <alice@example.com>` 格式。省略时草稿不带收件人（之后可通过 `+draft-edit` 添加） |
+| `--to '<email>'` | 否 | 完整收件人列表。多个收件人请重复传 `--to`，每次只放一个地址，参数值用单引号包住。支持 `Alice <alice@example.com>` 格式。省略时草稿不带收件人（之后可通过 `+draft-edit` 添加） |
 | `--subject <text>` | 是 | 草稿主题 |
 | `--body <text>` | 二选一 | 邮件正文。推荐使用 HTML 获得富文本排版；也支持纯文本（自动检测）。使用 `--plain-text` 可强制纯文本模式。支持 `<img src="./local.png" />` 相对路径自动解析为内嵌图片（仅支持相对路径，不支持绝对路径）。与 `--body-file` 互斥 |
 | `--body-file <path>` | 二选一 | 从文件读取邮件正文 HTML（相对路径，仅限 cwd 子树）。与 `--body` 互斥。文件大小上限 32 MB |
 | `--from <email>` | 否 | 发件人邮箱地址（EML From 头）。使用别名（send_as）发信时，设为别名地址并配合 `--mailbox` 指定所属邮箱。省略时使用邮箱主地址 |
 | `--mailbox <email>` | 否 | 邮箱地址，指定草稿所属的邮箱（默认回退到 `--from`，再回退到 `me`）。当发件人（`--from`）与邮箱不同时使用，如通过别名或 send_as 地址发信。可通过 `accessible_mailboxes` 查询可用邮箱 |
-| `--cc <emails>` | 否 | 完整抄送列表，多个用逗号分隔 |
-| `--bcc <emails>` | 否 | 完整密送列表，多个用逗号分隔。与 `--event-*` 不兼容（见 `+send` 日程邀请约束） |
+| `--cc '<email>'` | 否 | 完整抄送列表。多个抄送请重复传 `--cc`，每次只放一个地址，参数值用单引号包住 |
+| `--bcc '<email>'` | 否 | 完整密送列表。多个密送请重复传 `--bcc`，每次只放一个地址，参数值用单引号包住。与 `--event-*` 不兼容（见 `+send` 日程邀请约束） |
 | `--plain-text` | 否 | 强制纯文本模式，忽略 HTML 自动检测。不可与 `--inline` 同时使用。纯文本模式下也会自动追加纯文本签名（HTML 签名经 `PlainTextFromHTML` 转换，内联图片丢弃） |
-| `--attach <paths>` | 否 | 附件文件路径，多个用逗号分隔。相对路径。当附件导致 EML 总大小超过 25 MB 时，超出部分自动上传为超大附件（HTML 邮件插入下载卡片，纯文本邮件追加下载链接），单个文件上限 3 GB |
-| `--inline <json>` | 否 | 高级用法：手动指定内嵌图片 CID 映射。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。仅在需要精确控制 CID 命名时使用此参数。格式：`'[{"cid":"mycid","file_path":"./logo.png"}]'`，在 body 中用 `<img src="cid:mycid">` 引用。不可与 `--plain-text` 同时使用 |
+| `--attach '<path>'` | 否 | 附件文件路径。多个附件请重复传 `--attach`，每次只放一个相对路径，参数值用单引号包住；按传入顺序追加。当附件导致 EML 总大小超过 25 MB 时，超出部分自动上传为超大附件（HTML 邮件插入下载卡片，纯文本邮件追加下载链接），单个文件上限 3 GB |
+| `--inline '<json>'` | 否 | 高级用法：手动指定内嵌图片 CID 映射。多个 inline 图片请重复传 `--inline`，每次只放一个 JSON object，并用单引号包住：`'{"cid":"mycid","file_path":"./logo.png"}'`。`file_path` 必须是相对路径；CID 应唯一，例如随机十六进制字符串；在 body 中用 `<img src="cid:mycid">` 引用。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。不可与 `--plain-text` 同时使用 |
 | `--signature-id <id>` | 否 | 签名 ID。附加邮箱签名到正文末尾。运行 `mail +signature` 查看可用签名。与 `--no-signature` 互斥 |
 | `--no-signature` | 否 | 跳过默认签名自动追加。与 `--signature-id` 互斥，同时使用时返回参数校验错误（退出码 2） |
 | `--priority <level>` | 否 | 邮件优先级：`high`、`normal`、`low`。省略或 `normal` 时不设置优先级 |
@@ -94,7 +94,7 @@ lark-cli mail +draft-create --to alice@example.com --subject '测试' --body 'te
 
 ```bash
 # 1. 创建草稿
-lark-cli mail +draft-create --to alice@example.com --subject 'Q1 报告' --body '请查收附件中的报告。' --attach ./q1-report.pdf --format json
+lark-cli mail +draft-create --to 'alice@example.com' --subject 'Q1 报告' --body '请查收附件中的报告。' --attach './q1-report.pdf' --format json
 
 # 2. 发送草稿
 lark-cli mail user_mailbox.drafts send --params '{"user_mailbox_id":"me","draft_id":"<draft_id>"}'
@@ -107,13 +107,13 @@ lark-cli mail user_mailbox.drafts send --params '{"user_mailbox_id":"me","draft_
 ```bash
 # 推荐：直接使用相对路径，自动解析为内嵌图片
 lark-cli mail +draft-create \
-  --to alice@example.com \
+  --to 'alice@example.com' \
   --subject '通讯稿' \
   --body '<h1>你好</h1><img src="./banner.png" />'
 
 # 高级用法：手动指定 CID（CID 为唯一标识符，可用随机十六进制字符串）
 lark-cli mail +draft-create \
-  --to alice@example.com \
+  --to 'alice@example.com' \
   --subject '通讯稿' \
   --body '<h1>你好</h1><img src="cid:c7d8e9f0a1b2c3d4e5f6">' \
   --inline '[{"cid":"c7d8e9f0a1b2c3d4e5f6","file_path":"./banner.png"}]'

package/skills/lark-mail/references/lark-mail-forward.md

@@ -19,7 +19,7 @@
 
 **方式 A（推荐）** — 创建转发草稿（不带 `--confirm-send`）：
 ```bash
-lark-cli mail +forward --message-id <邮件ID> --to <收件人>
+lark-cli mail +forward --message-id <邮件ID> --to '<收件人>'
 ```
 → 返回 `draft_id`
 
@@ -38,22 +38,22 @@ lark-cli mail user_mailbox.drafts send --params '{"user_mailbox_id":"me","draft_
 
 ```bash
 # 转发邮件（默认保存为草稿）— HTML 推荐
-lark-cli mail +forward --message-id <邮件ID> --to alice@example.com --body '<p>FYI，请看下面原邮件。</p>'
+lark-cli mail +forward --message-id <邮件ID> --to 'alice@example.com' --body '<p>FYI，请看下面原邮件。</p>'
 
 # 转发并附加说明 + 抄送（草稿）
-lark-cli mail +forward --message-id <邮件ID> --to alice@example.com --cc bob@example.com --body '<b>请参考</b>'
+lark-cli mail +forward --message-id <邮件ID> --to 'alice@example.com' --cc 'bob@example.com' --body '<b>请参考</b>'
 
 # 转发时插入内嵌图片（推荐：直接用相对路径，自动解析）
-lark-cli mail +forward --message-id <邮件ID> --to alice@example.com --body '<p>详见图示：<img src="./logo.png" /></p>'
+lark-cli mail +forward --message-id <邮件ID> --to 'alice@example.com' --body '<p>详见图示：<img src="./logo.png" /></p>'
 
 # 纯文本转发（仅在内容极简时使用）
-lark-cli mail +forward --message-id <邮件ID> --to alice@example.com
+lark-cli mail +forward --message-id <邮件ID> --to 'alice@example.com'
 
 # 确认发送（用户明确确认后才可使用）
-lark-cli mail +forward --message-id <邮件ID> --to alice@example.com --confirm-send
+lark-cli mail +forward --message-id <邮件ID> --to 'alice@example.com' --confirm-send
 
 # Dry Run（仅打印请求，不发送）
-lark-cli mail +forward --message-id <邮件ID> --to alice@example.com --dry-run
+lark-cli mail +forward --message-id <邮件ID> --to 'alice@example.com' --dry-run
 ```
 
 ## 参数
@@ -61,16 +61,16 @@ lark-cli mail +forward --message-id <邮件ID> --to alice@example.com --dry-run
 | 参数 | 必填 | 说明 |
 |------|------|------|
 | `--message-id <id>` | 是 | 被转发的邮件 ID |
-| `--to <emails>` | 是 | 收件人邮箱，多个用逗号分隔 |
+| `--to '<email>'` | 是 | 收件人邮箱。多个收件人请重复传 `--to`，每次只放一个地址，参数值用单引号包住 |
 | `--body <text>` | 否 | 转发时附加的说明文字。推荐使用 HTML 获得富文本排版；也支持纯文本。根据转发正文和原邮件正文自动检测 HTML。使用 `--plain-text` 可强制纯文本模式。支持 `<img src="./local.png" />` 相对路径自动解析为内嵌图片（仅支持相对路径，不支持绝对路径）。与 `--body-file` 互斥 |
 | `--body-file <path>` | 否 | 从文件读取转发说明 HTML（相对路径，仅限 cwd 子树）。与 `--body` 互斥。文件大小上限 32 MB |
 | `--from <email>` | 否 | 发件人邮箱地址（EML From 头）。使用别名（send_as）发信时，设为别名地址并配合 `--mailbox` 指定所属邮箱。默认读取邮箱主地址 |
 | `--mailbox <email>` | 否 | 邮箱地址，指定草稿所属的邮箱（默认回退到 `--from`，再回退到 `me`）。当发件人（`--from`）与邮箱不同时使用。可通过 `accessible_mailboxes` 查询可用邮箱 |
-| `--cc <emails>` | 否 | 抄送邮箱，多个用逗号分隔 |
-| `--bcc <emails>` | 否 | 密送邮箱，多个用逗号分隔。与 `--event-*` 不兼容（见 `+send` 日程邀请约束） |
+| `--cc '<email>'` | 否 | 抄送邮箱。多个抄送请重复传 `--cc`，每次只放一个地址，参数值用单引号包住 |
+| `--bcc '<email>'` | 否 | 密送邮箱。多个密送请重复传 `--bcc`，每次只放一个地址，参数值用单引号包住。与 `--event-*` 不兼容（见 `+send` 日程邀请约束） |
 | `--plain-text` | 否 | 强制纯文本模式，忽略所有 HTML 自动检测。不可与 `--inline` 同时使用。纯文本模式下也会自动追加纯文本签名（HTML 签名经 `PlainTextFromHTML` 转换，内联图片丢弃） |
-| `--attach <paths>` | 否 | 附件文件路径，多个用逗号分隔，追加在原邮件附件之后。相对路径。当附件导致 EML 总大小超过 25 MB 时，超出部分自动上传为超大附件（HTML 邮件插入下载卡片，纯文本邮件追加下载链接），单个文件上限 3 GB |
-| `--inline <json>` | 否 | 高级用法：手动指定内嵌图片 CID 映射。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。仅在需要精确控制 CID 命名时使用此参数。格式：`'[{"cid":"mycid","file_path":"./logo.png"}]'`，在 body 中用 `<img src="cid:mycid">` 引用。不可与 `--plain-text` 同时使用 |
+| `--attach '<path>'` | 否 | 附件文件路径。多个附件请重复传 `--attach`，每次只放一个相对路径，参数值用单引号包住；按传入顺序追加在原邮件附件之后。当附件导致 EML 总大小超过 25 MB 时，超出部分自动上传为超大附件（HTML 邮件插入下载卡片，纯文本邮件追加下载链接），单个文件上限 3 GB |
+| `--inline '<json>'` | 否 | 高级用法：手动指定内嵌图片 CID 映射。多个 inline 图片请重复传 `--inline`，每次只放一个 JSON object，并用单引号包住：`'{"cid":"mycid","file_path":"./logo.png"}'`。`file_path` 必须是相对路径；CID 应唯一，例如随机十六进制字符串；在 body 中用 `<img src="cid:mycid">` 引用。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。不可与 `--plain-text` 同时使用 |
 | `--signature-id <id>` | 否 | 签名 ID。附加邮箱签名到转发正文与引用块之间。运行 `mail +signature` 查看可用签名。与 `--no-signature` 互斥 |
 | `--no-signature` | 否 | 跳过默认签名自动追加。与 `--signature-id` 互斥，同时使用时返回参数校验错误（退出码 2） |
 | `--priority <level>` | 否 | 邮件优先级：`high`、`normal`、`low`。省略或 `normal` 时不设置优先级 |
@@ -124,14 +124,14 @@ lark-cli mail +forward --message-id <邮件ID> --to alice@example.com --dry-run
 
 ### 场景 1：用户说"把这封邮件转发给 Bob"（只创建草稿）
 ```bash
-lark-cli mail +forward --message-id <邮件ID> --to bob@example.com --body '<p>FYI</p>'
+lark-cli mail +forward --message-id <邮件ID> --to 'bob@example.com' --body '<p>FYI</p>'
 ```
 → 返回 `draft_id`，告诉用户转发草稿已创建。
 
 ### 场景 2：用户说"转发给 Bob 并发送"（需要发送）
 ```bash
 # 方式 A: 创建转发草稿
-lark-cli mail +forward --message-id <邮件ID> --to bob@example.com --body '<p>FYI，请查收。</p>'
+lark-cli mail +forward --message-id <邮件ID> --to 'bob@example.com' --body '<p>FYI，请查收。</p>'
 # → 返回 draft_id
 
 # 向用户确认 "收件人 bob@example.com。如果你想先看效果，也可以先去飞书邮件里查看草稿。确认发送吗？"
@@ -140,13 +140,13 @@ lark-cli mail +forward --message-id <邮件ID> --to bob@example.com --body '<p>F
 lark-cli mail user_mailbox.drafts send --params '{"user_mailbox_id":"me","draft_id":"<draft_id>"}'
 
 # 方式 B: 用户已明确确认时，直接发送
-lark-cli mail +forward --message-id <邮件ID> --to bob@example.com --body '<p>FYI，请查收。</p>' --confirm-send
+lark-cli mail +forward --message-id <邮件ID> --to 'bob@example.com' --body '<p>FYI，请查收。</p>' --confirm-send
 ```
 
 ### 场景 3：用户说"下午 3 点转发给 Bob"（定时发送）
 ```bash
 # Step 1: 创建转发草稿
-lark-cli mail +forward --message-id <邮件ID> --to bob@example.com --body '<p>FYI，请查收。</p>'
+lark-cli mail +forward --message-id <邮件ID> --to 'bob@example.com' --body '<p>FYI，请查收。</p>'
 # → 返回 draft_id
 
 # Step 2: 向用户确认 "转发草稿已创建：收件人 bob@example.com，定时 <目标时间> 发送。确认吗？"
@@ -174,7 +174,7 @@ lark-cli mail +thread --thread-id <THREAD_ID> --html=false --format json
 #    messages 按时间升序排列，最后一条 = messages[-1].message_id
 
 # 3. 转发该消息
-lark-cli mail +forward --message-id <最后一条的message_id> --to recipient@example.com --body '请过目'
+lark-cli mail +forward --message-id <最后一条的message_id> --to 'recipient@example.com' --body '请过目'
 ```
 
 ## 实现说明

package/skills/lark-mail/references/lark-mail-reply-all.md

@@ -41,10 +41,10 @@ lark-cli mail user_mailbox.drafts send --params '{"user_mailbox_id":"me","draft_
 lark-cli mail +reply-all --message-id <邮件ID> --body '<p><b>已完成</b>，详见下方说明。</p>'
 
 # 回复全部并追加收件人/抄送（草稿）
-lark-cli mail +reply-all --message-id <邮件ID> --body '<p>同步更新</p>' --to lead@example.com --cc pm@example.com
+lark-cli mail +reply-all --message-id <邮件ID> --body '<p>同步更新</p>' --to 'lead@example.com' --cc 'pm@example.com'
 
 # 从回复名单中排除某些地址（草稿）
-lark-cli mail +reply-all --message-id <邮件ID> --body '<p>见上</p>' --remove bot@example.com,noreply@example.com
+lark-cli mail +reply-all --message-id <邮件ID> --body '<p>见上</p>' --remove 'bot@example.com' --remove 'noreply@example.com'
 
 # 回复全部时插入内嵌图片（推荐：直接用相对路径，自动解析）
 lark-cli mail +reply-all --message-id <邮件ID> --body '<p>详见图示：<img src="./logo.png" /></p>'
@@ -68,13 +68,13 @@ lark-cli mail +reply-all --message-id <邮件ID> --body '测试' --dry-run
 | `--body-file <path>` | 二选一 | 从文件读取回复正文 HTML（相对路径，仅限 cwd 子树）。与 `--body` 互斥。文件大小上限 32 MB |
 | `--from <email>` | 否 | 发件人邮箱地址（EML From 头）。使用别名（send_as）发信时，设为别名地址并配合 `--mailbox` 指定所属邮箱。默认读取邮箱主地址 |
 | `--mailbox <email>` | 否 | 邮箱地址，指定草稿所属的邮箱（默认回退到 `--from`，再回退到 `me`）。当发件人（`--from`）与邮箱不同时使用。可通过 `accessible_mailboxes` 查询可用邮箱 |
-| `--to <emails>` | 否 | 额外收件人，多个用逗号分隔（追加到自动聚合结果） |
-| `--cc <emails>` | 否 | 额外抄送，多个用逗号分隔 |
-| `--bcc <emails>` | 否 | 密送邮箱，多个用逗号分隔。与 `--event-*` 不兼容（见 `+send` 日程邀请约束） |
-| `--remove <emails>` | 否 | 从自动聚合结果中排除的邮箱，多个用逗号分隔 |
+| `--to '<email>'` | 否 | 额外收件人。多个额外收件人请重复传 `--to`，每次只放一个地址，参数值用单引号包住；追加到自动聚合结果 |
+| `--cc '<email>'` | 否 | 额外抄送。多个抄送请重复传 `--cc`，每次只放一个地址，参数值用单引号包住 |
+| `--bcc '<email>'` | 否 | 密送邮箱。多个密送请重复传 `--bcc`，每次只放一个地址，参数值用单引号包住。与 `--event-*` 不兼容（见 `+send` 日程邀请约束） |
+| `--remove '<email>'` | 否 | 从自动聚合结果中排除的邮箱。多个排除地址请重复传 `--remove`，每次只放一个地址，参数值用单引号包住；按传入顺序处理 |
 | `--plain-text` | 否 | 强制纯文本模式，忽略所有 HTML 自动检测。不可与 `--inline` 同时使用。纯文本模式下也会自动追加纯文本签名（HTML 签名经 `PlainTextFromHTML` 转换，内联图片丢弃） |
-| `--attach <paths>` | 否 | 附件文件路径，多个用逗号分隔。相对路径。当附件导致 EML 总大小超过 25 MB 时，超出部分自动上传为超大附件（HTML 邮件插入下载卡片，纯文本邮件追加下载链接），单个文件上限 3 GB |
-| `--inline <json>` | 否 | 高级用法：手动指定内嵌图片 CID 映射。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。仅在需要精确控制 CID 命名时使用此参数。格式：`'[{"cid":"mycid","file_path":"./logo.png"}]'`，在 body 中用 `<img src="cid:mycid">` 引用。不可与 `--plain-text` 同时使用 |
+| `--attach '<path>'` | 否 | 附件文件路径。多个附件请重复传 `--attach`，每次只放一个相对路径，参数值用单引号包住；按传入顺序追加。当附件导致 EML 总大小超过 25 MB 时，超出部分自动上传为超大附件（HTML 邮件插入下载卡片，纯文本邮件追加下载链接），单个文件上限 3 GB |
+| `--inline '<json>'` | 否 | 高级用法：手动指定内嵌图片 CID 映射。多个 inline 图片请重复传 `--inline`，每次只放一个 JSON object，并用单引号包住：`'{"cid":"mycid","file_path":"./logo.png"}'`。`file_path` 必须是相对路径；CID 应唯一，例如随机十六进制字符串；在 body 中用 `<img src="cid:mycid">` 引用。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。不可与 `--plain-text` 同时使用 |
 | `--signature-id <id>` | 否 | 签名 ID。附加邮箱签名到回复正文与引用块之间。运行 `mail +signature` 查看可用签名。与 `--no-signature` 互斥 |
 | `--no-signature` | 否 | 跳过默认签名自动追加。与 `--signature-id` 互斥，同时使用时返回参数校验错误（退出码 2） |
 | `--priority <level>` | 否 | 邮件优先级：`high`、`normal`、`low`。省略或 `normal` 时不设置优先级 |

package/skills/lark-mail/references/lark-mail-reply.md

@@ -45,7 +45,7 @@ lark-cli mail user_mailbox.drafts send --params '{"user_mailbox_id":"me","draft_
 lark-cli mail +reply --message-id <邮件ID> --body '<p><b>已收到</b>，稍后跟进。</p>'
 
 # 回复并追加收件人/抄送（保存为草稿）
-lark-cli mail +reply --message-id <邮件ID> --body '<p>已处理</p>' --to lead@example.com --cc colleague@example.com
+lark-cli mail +reply --message-id <邮件ID> --body '<p>已处理</p>' --to 'lead@example.com' --cc 'colleague@example.com'
 
 # 回复时插入内嵌图片（推荐：直接用相对路径，自动解析）
 lark-cli mail +reply --message-id <邮件ID> --body '<p>详见图示：<img src="./logo.png" /></p>'
@@ -72,12 +72,12 @@ lark-cli mail +reply --message-id <邮件ID> --body '<p>测试</p>' --dry-run
 | `--body-file <path>` | 二选一 | 从文件读取回复正文 HTML（相对路径，仅限 cwd 子树）。与 `--body` 互斥。文件大小上限 32 MB |
 | `--from <email>` | 否 | 发件人邮箱地址（EML From 头）。使用别名（send_as）发信时，设为别名地址并配合 `--mailbox` 指定所属邮箱。默认读取邮箱主地址 |
 | `--mailbox <email>` | 否 | 邮箱地址，指定草稿所属的邮箱（默认回退到 `--from`，再回退到 `me`）。当发件人（`--from`）与邮箱不同时使用。可通过 `accessible_mailboxes` 查询可用邮箱 |
-| `--to <emails>` | 否 | 额外收件人，多个用逗号分隔（追加到原发件人） |
-| `--cc <emails>` | 否 | 抄送邮箱，多个用逗号分隔 |
-| `--bcc <emails>` | 否 | 密送邮箱，多个用逗号分隔。与 `--event-*` 不兼容（见 `+send` 日程邀请约束） |
+| `--to '<email>'` | 否 | 额外收件人。多个额外收件人请重复传 `--to`，每次只放一个地址，参数值用单引号包住；追加到原发件人 |
+| `--cc '<email>'` | 否 | 抄送邮箱。多个抄送请重复传 `--cc`，每次只放一个地址，参数值用单引号包住 |
+| `--bcc '<email>'` | 否 | 密送邮箱。多个密送请重复传 `--bcc`，每次只放一个地址，参数值用单引号包住。与 `--event-*` 不兼容（见 `+send` 日程邀请约束） |
 | `--plain-text` | 否 | 强制纯文本模式，忽略所有 HTML 自动检测。不可与 `--inline` 同时使用。纯文本模式下也会自动追加纯文本签名（HTML 签名经 `PlainTextFromHTML` 转换，内联图片丢弃） |
-| `--attach <paths>` | 否 | 附件文件路径，多个用逗号分隔。相对路径。当附件导致 EML 总大小超过 25 MB 时，超出部分自动上传为超大附件（HTML 邮件插入下载卡片，纯文本邮件追加下载链接），单个文件上限 3 GB |
-| `--inline <json>` | 否 | 高级用法：手动指定内嵌图片 CID 映射。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。仅在需要精确控制 CID 命名时使用此参数。格式：`'[{"cid":"mycid","file_path":"./logo.png"}]'`，在 body 中用 `<img src="cid:mycid">` 引用。不可与 `--plain-text` 同时使用 |
+| `--attach '<path>'` | 否 | 附件文件路径。多个附件请重复传 `--attach`，每次只放一个相对路径，参数值用单引号包住；按传入顺序追加。当附件导致 EML 总大小超过 25 MB 时，超出部分自动上传为超大附件（HTML 邮件插入下载卡片，纯文本邮件追加下载链接），单个文件上限 3 GB |
+| `--inline '<json>'` | 否 | 高级用法：手动指定内嵌图片 CID 映射。多个 inline 图片请重复传 `--inline`，每次只放一个 JSON object，并用单引号包住：`'{"cid":"mycid","file_path":"./logo.png"}'`。`file_path` 必须是相对路径；CID 应唯一，例如随机十六进制字符串；在 body 中用 `<img src="cid:mycid">` 引用。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。不可与 `--plain-text` 同时使用 |
 | `--signature-id <id>` | 否 | 签名 ID。附加邮箱签名到回复正文与引用块之间。运行 `mail +signature` 查看可用签名。与 `--no-signature` 互斥 |
 | `--no-signature` | 否 | 跳过默认签名自动追加。与 `--signature-id` 互斥，同时使用时返回参数校验错误（退出码 2） |
 | `--priority <level>` | 否 | 邮件优先级：`high`、`normal`、`low`。省略或 `normal` 时不设置优先级 |

package/skills/lark-mail/references/lark-mail-send.md

@@ -18,7 +18,7 @@
 
 **方式 A（推荐）** — 先创建草稿，再确认发送：
 ```bash
-lark-cli mail +send --to <收件人> --subject '<主题>' --body '<正文>'
+lark-cli mail +send --to '<收件人>' --subject '<主题>' --body '<正文>'
 ```
 → 返回 `draft_id`
 
@@ -31,7 +31,7 @@ lark-cli mail user_mailbox.drafts send --params '{"user_mailbox_id":"me","draft_
 
 **方式 B（允许）** — 用户已经明确确认收件人和内容时，可直接使用 `--confirm-send` 立即发送：
 ```bash
-lark-cli mail +send --to <收件人> --subject '<主题>' --body '<正文>' --confirm-send
+lark-cli mail +send --to '<收件人>' --subject '<主题>' --body '<正文>' --confirm-send
 ```
 
 **禁止在用户未明确同意的情况下执行发送，无论是发送草稿还是直接使用 `--confirm-send`。**
@@ -40,44 +40,44 @@ lark-cli mail +send --to <收件人> --subject '<主题>' --body '<正文>' --co
 
 ```bash
 # 保存为草稿（默认行为，不发送）— HTML 格式推荐
-lark-cli mail +send --to alice@example.com --subject '周报' \
+lark-cli mail +send --to 'alice@example.com' --subject '周报' \
   --body '<p>本周进展：</p><ul><li>完成 A 模块</li><li>修复 3 个 bug</li></ul>'
 
 # 保存为草稿并抄送
-lark-cli mail +send --to alice@example.com --cc bob@example.com --subject '状态更新' --body '<b>已完成</b>'
+lark-cli mail +send --to 'alice@example.com' --cc 'bob@example.com' --subject '状态更新' --body '<b>已完成</b>'
 
 # 确认发送（仅在用户明确确认后使用）
-lark-cli mail +send --to alice@example.com --subject '周报' \
+lark-cli mail +send --to 'alice@example.com' --subject '周报' \
   --body '<p>本周进展如下...</p>' --confirm-send
 
 # 保存带附件的草稿
-lark-cli mail +send --to alice@example.com --subject '请查收' --body '<p>见附件</p>' --attach ./report.pdf,./logs.zip
+lark-cli mail +send --to 'alice@example.com' --subject '请查收' --body '<p>见附件</p>' --attach './report.pdf' --attach './logs.zip'
 
 # 保存带内嵌图片的草稿（推荐：直接用相对路径，自动解析）
-lark-cli mail +send --to alice@example.com --subject '预览图' --body '<img src="./logo.png" />'
+lark-cli mail +send --to 'alice@example.com' --subject '预览图' --body '<img src="./logo.png" />'
 
 # 纯文本邮件（仅在内容极简时使用）
-lark-cli mail +send --to alice@example.com --subject '确认' --body '收到，谢谢'
+lark-cli mail +send --to 'alice@example.com' --subject '确认' --body '收到，谢谢'
 
 # Dry Run（仅打印请求，不执行）
-lark-cli mail +send --to alice@example.com --subject '测试' --body '<p>test</p>' --dry-run
+lark-cli mail +send --to 'alice@example.com' --subject '测试' --body '<p>test</p>' --dry-run
 ```
 
 ## 参数
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--to <emails>` | 是 | 收件人邮箱，多个用逗号分隔 |
+| `--to '<email>'` | 是 | 收件人邮箱。多个收件人请重复传 `--to`，每次只放一个地址，参数值用单引号包住 |
 | `--subject <text>` | 是 | 邮件主题 |
 | `--body <text>` | 二选一 | 邮件正文。推荐使用 HTML 获得富文本排版；也支持纯文本（自动检测）。使用 `--plain-text` 可强制纯文本模式。支持 `<img src="./local.png" />` 相对路径自动解析为内嵌图片（仅支持相对路径，不支持绝对路径）。与 `--body-file` 互斥 |
 | `--body-file <path>` | 二选一 | 从文件读取邮件正文 HTML（相对路径，仅限 cwd 子树）。与 `--body` 互斥。文件大小上限 32 MB |
 | `--from <email>` | 否 | 发件人邮箱地址（EML From 头）。使用别名（send_as）发信时，设为别名地址并配合 `--mailbox` 指定所属邮箱。默认读取邮箱主地址 |
 | `--mailbox <email>` | 否 | 邮箱地址，指定草稿所属的邮箱（默认回退到 `--from`，再回退到 `me`）。当发件人（`--from`）与邮箱不同时使用。可通过 `accessible_mailboxes` 查询可用邮箱 |
-| `--cc <emails>` | 否 | 抄送邮箱，多个用逗号分隔 |
-| `--bcc <emails>` | 否 | 密送邮箱，多个用逗号分隔 |
+| `--cc '<email>'` | 否 | 抄送邮箱。多个抄送请重复传 `--cc`，每次只放一个地址，参数值用单引号包住 |
+| `--bcc '<email>'` | 否 | 密送邮箱。多个密送请重复传 `--bcc`，每次只放一个地址，参数值用单引号包住 |
 | `--plain-text` | 否 | 强制纯文本模式，忽略 HTML 自动检测。不可与 `--inline` 同时使用。纯文本模式下也会自动追加纯文本签名（HTML 签名经 `PlainTextFromHTML` 转换，内联图片丢弃） |
-| `--attach <paths>` | 否 | 附件文件路径，多个用逗号分隔。相对路径。当附件导致 EML 总大小超过 25 MB 时，超出部分自动上传为超大附件（HTML 邮件插入下载卡片，纯文本邮件追加下载链接），单个文件上限 3 GB |
-| `--inline <json>` | 否 | 高级用法：手动指定内嵌图片 CID 映射。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。仅在需要精确控制 CID 命名时使用此参数。格式：`'[{"cid":"mycid","file_path":"./logo.png"}]'`，在 body 中用 `<img src="cid:mycid">` 引用。不可与 `--plain-text` 同时使用 |
+| `--attach '<path>'` | 否 | 附件文件路径。多个附件请重复传 `--attach`，每次只放一个相对路径，参数值用单引号包住；按传入顺序追加。当附件导致 EML 总大小超过 25 MB 时，超出部分自动上传为超大附件（HTML 邮件插入下载卡片，纯文本邮件追加下载链接），单个文件上限 3 GB |
+| `--inline '<json>'` | 否 | 高级用法：手动指定内嵌图片 CID 映射。多个 inline 图片请重复传 `--inline`，每次只放一个 JSON object，并用单引号包住：`'{"cid":"mycid","file_path":"./logo.png"}'`。`file_path` 必须是相对路径；CID 应唯一，例如随机十六进制字符串；在 body 中用 `<img src="cid:mycid">` 引用。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。不可与 `--plain-text` 同时使用 |
 | `--signature-id <id>` | 否 | 签名 ID。附加邮箱签名到正文末尾。运行 `mail +signature` 查看可用签名。与 `--no-signature` 互斥 |
 | `--no-signature` | 否 | 跳过默认签名自动追加。与 `--signature-id` 互斥，同时使用时返回参数校验错误（退出码 2） |
 | `--priority <level>` | 否 | 邮件优先级：`high`、`normal`、`low`。省略或 `normal` 时不设置优先级 |
@@ -141,14 +141,14 @@ lark-cli mail +send --to alice@example.com --subject '测试' --body '<p>test</p
 
 ### 场景 1：用户说"帮我写一封邮件给 Alice"（只创建草稿）
 ```bash
-lark-cli mail +send --to alice@example.com --subject '周报' --body '<p>本周进展如下...</p>'
+lark-cli mail +send --to 'alice@example.com' --subject '周报' --body '<p>本周进展如下...</p>'
 ```
 → 返回草稿结果时，如输出中带有草稿打开链接，则一起展示给用户；如果当前输出没有链接，则静默处理。如果用户想先看效果，可去飞书邮件 UI 中打开草稿查看详情。
 
 ### 场景 2：用户说"发邮件给 Alice 说收到了"（需要发送）
 ```bash
 # 方式 A: 创建草稿
-lark-cli mail +send --to alice@example.com --subject '收到' --body '<p>已收到，谢谢！</p>'
+lark-cli mail +send --to 'alice@example.com' --subject '收到' --body '<p>已收到，谢谢！</p>'
 # → 返回 draft_id
 
 # 向用户确认 "当前收件人 alice@example.com，主题「收到」。如果你想先看效果，也可以先去飞书邮件里打开草稿查看详情。确认发送吗？"
@@ -157,13 +157,13 @@ lark-cli mail +send --to alice@example.com --subject '收到' --body '<p>已收
 lark-cli mail user_mailbox.drafts send --params '{"user_mailbox_id":"me","draft_id":"<draft_id>"}'
 
 # 方式 B: 用户已明确确认时，直接发送
-lark-cli mail +send --to alice@example.com --subject '收到' --body '<p>已收到，谢谢！</p>' --confirm-send
+lark-cli mail +send --to 'alice@example.com' --subject '收到' --body '<p>已收到，谢谢！</p>' --confirm-send
 ```
 
 ### 场景 3：用户说"下午 3 点给 Alice 发一封周报"（定时发送）
 ```bash
 # Step 1: 创建草稿（定时发送也走草稿流程）
-lark-cli mail +send --to alice@example.com --subject '周报' --body '<p>本周进展如下...</p>'
+lark-cli mail +send --to 'alice@example.com' --subject '周报' --body '<p>本周进展如下...</p>'
 # → 返回 draft_id
 
 # Step 2: 向用户确认 "邮件草稿已创建：收件人 alice@example.com，主题「周报」，定时 <目标时间> 发送。确认吗？"
@@ -210,8 +210,8 @@ lark-cli mail user_mailbox.drafts cancel_scheduled_send --params '{"user_mailbox
 ## 实现说明
 
 - 使用 EML 构建器生成完整 MIME 邮件并 base64url 编码后发送。
-- `--attach` 作为普通附件添加。相对路径。
-- `--inline` 接受 JSON 数组，每项需提供 `cid`（唯一标识符，可用随机十六进制字符串）和 `file_path`（相对路径），作为 inline part 嵌入邮件。
+- `--attach` 作为普通附件添加。多个附件请重复传 `--attach`，每次只放一个相对路径。
+- `--inline` 手动指定 inline 图片时，多个图片请重复传 `--inline`，每次只放一个 JSON object。每项需提供 `cid`（唯一标识符，可用随机十六进制字符串）和 `file_path`（相对路径），作为 inline part 嵌入邮件。
 - **超大附件**：当附件导致 EML 总大小（headers + body + inline images + attachments，base64 编码后）超过 25 MB 时，超出的文件自动通过 `medias/upload_*` API 上传到云端。HTML 邮件插入与飞书客户端一致的下载卡片；纯文本邮件追加包含文件名、大小和下载链接的文本块。单个文件上限 3 GB，总附件数量上限 250 个。
 
 ## 相关命令

package/skills/lark-mail/references/lark-mail-template-create.md

@@ -49,11 +49,12 @@ lark-cli mail +template-create --as user \
 | `--subject <text>` | 否 | 默认主题 |
 | `--template-content <html>` | 否* | 模板正文。HTML 首选；支持 `<img src="./local.png" />` 相对路径自动上传到 Drive 并改写为 `cid:` |
 | `--template-content-file <path>` | 否* | 从文件加载正文内容；与 `--template-content` 互斥 |
-| `--plain-text` | 否 | 标记为纯文本模式（`is_plain_text_mode=true`）。仍可带内嵌图片，但 `+send --template-id` 套用时会走 plain-text 正文拼接 |
-| `--to <emails>` | 否 | 默认收件人列表，逗号分隔，支持 `Name <email>` 格式 |
-| `--cc <emails>` | 否 | 默认抄送 |
-| `--bcc <emails>` | 否 | 默认密送 |
-| `--attach <paths>` | 否 | 非 inline 附件路径，逗号分隔。每个文件按 `--attach` 书写顺序上传到 Drive |
+| `--plain-text` | 否 | 标记为纯文本模式（`is_plain_text_mode=true`）。不可与 `--inline` 同时使用；`+send --template-id` 套用时会走 plain-text 正文拼接 |
+| `--to '<email>'` | 否 | 默认收件人列表。多个默认收件人请重复传 `--to`，每次只放一个地址，参数值用单引号包住。支持 `Name <email>` 格式 |
+| `--cc '<email>'` | 否 | 默认抄送。多个抄送请重复传 `--cc`，每次只放一个地址，参数值用单引号包住 |
+| `--bcc '<email>'` | 否 | 默认密送。多个密送请重复传 `--bcc`，每次只放一个地址，参数值用单引号包住 |
+| `--attach '<path>'` | 否 | 非 inline 附件路径。多个附件请重复传 `--attach`，每次只放一个相对路径，参数值用单引号包住；每个文件按传入顺序上传到 Drive |
+| `--inline '<json>'` | 否 | 手动指定 inline 图片 CID 映射。多个 inline 图片请重复传 `--inline`，每次只放一个 JSON object，并用单引号包住：`'{"cid":"mycid","file_path":"./logo.png"}'`。`file_path` 必须是相对路径；CID 应唯一，例如随机十六进制字符串；在模板正文中用 `<img src="cid:mycid">` 引用 |
 | `--mailbox <email>` | 否 | 所属邮箱，默认 `me`（当前用户主邮箱） |
 | `--dry-run` | 否 | 仅打印计划中的 API 调用链，不真实执行 |
 
@@ -82,7 +83,7 @@ lark-cli mail +template-create --as user \
 ## 顺序约束
 
 - inline 图片按正文中 `<img>` 出现顺序处理
-- 非 inline 按 `--attach` 书写顺序处理；重复路径不会去重
+- 非 inline 按 `--attach` 展开顺序处理；重复路径不会去重
 
 ## 返回值
 

package/skills/lark-mail/references/lark-mail-template-update.md

@@ -14,7 +14,7 @@
 |------|------|---------|
 | `--print-patch-template` | 打印 `--patch-file` 的 JSON 骨架 | 否（纯本地） |
 | `--inspect` | 返回当前模板完整 projection | 否（只 GET） |
-| `--set-*` / `--attach` | 扁平 flag 合并后 PUT | 是 |
+| `--set-*` / `--attach` / `--inline` | 扁平 flag 合并后 PUT | 是 |
 | `--patch-file` | 结构化 patch + 扁平 flag 合并后 PUT | 是 |
 
 ## 命令
@@ -67,10 +67,11 @@ lark-cli mail +template-update --as user --template-id 712345 \
 | `--set-template-content <html>` | 替换正文。支持 `<img src="./local.png" />` 相对路径自动上传并改写 |
 | `--set-template-content-file <path>` | 从文件加载替换正文；与 `--set-template-content` 互斥 |
 | `--set-plain-text` | 标为纯文本模式（置 true）。**不提供不会置 false**；要把 HTML 模板翻回 false，请用 `--patch-file` 的 `{"is_plain_text_mode": false}` |
-| `--set-to <emails>` | 替换默认收件人列表 |
-| `--set-cc <emails>` | 替换默认抄送 |
-| `--set-bcc <emails>` | 替换默认密送 |
-| `--attach <paths>` | 追加非 inline 附件（按书写顺序），不替换已有附件 |
+| `--set-to <emails>` | 用单次参数值替换默认收件人列表；多个地址仍在该值内用逗号分隔，传 `--set-to=""` 可清空 |
+| `--set-cc <emails>` | 用单次参数值替换默认抄送；多个地址仍在该值内用逗号分隔，传 `--set-cc=""` 可清空 |
+| `--set-bcc <emails>` | 用单次参数值替换默认密送；多个地址仍在该值内用逗号分隔，传 `--set-bcc=""` 可清空 |
+| `--attach '<path>'` | 追加非 inline 附件，不替换已有附件。多个附件请重复传 `--attach`，每次只放一个相对路径，参数值用单引号包住；按传入顺序上传 |
+| `--inline '<json>'` | 追加 inline 图片，不替换已有附件。多个 inline 图片请重复传 `--inline`，每次只放一个 JSON object，并用单引号包住：`'{"cid":"mycid","file_path":"./logo.png"}'`；`file_path` 必须是相对路径；CID 应唯一，例如随机十六进制字符串；在模板正文中用 `<img src="cid:mycid">` 引用；最终模板为纯文本模式时会被拒绝 |
 
 ### 结构化 patch
 
@@ -105,7 +106,7 @@ patch-file 字段（全部可选，未提供的字段保持当前模板原值）
 
 ## DryRun 行为
 
-- 默认：打印 `GET /user_mailboxes/:id/templates/:tid` + Drive 上传步骤（如有 `<img>` 或 `--attach`）+ `PUT` 步骤。
+- 默认：打印 `GET /user_mailboxes/:id/templates/:tid` + Drive 上传步骤（如有 `<img>`、`--attach` 或 `--inline`）+ `PUT` 步骤。
 - `--inspect`：只打印 `GET`。
 - `--print-patch-template`：打印骨架，不走任何 API。