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

package/server/assets/skills/lark-tools/cli-skills/lark-mail/references/lark-mail-forward.md

@@ -0,0 +1,208 @@
+# mail +forward
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+转发指定邮件，自动处理：
+- 主题前缀 `Fwd: `（已含前缀时不重复）
+- 自动拼接标准 “Forwarded message” 区块（From/Date/Subject/To + 原文）
+- 支持纯文本和 HTML 转发
+
+> **默认草稿**：`+forward` 默认保存为草稿，不会立即发送。如需立即发送，添加 `--confirm-send` 参数（仅在用户明确确认后使用）。
+
+本 skill 对应 shortcut：`lark-cli mail +forward`。
+
+## CRITICAL — 发送工作流（必须遵循）
+
+此命令默认**只保存草稿**，不会发送邮件。转发会将原邮件内容发送给新收件人，需要发送时**必须**按以下步骤操作：
+
+**Step 1** — 创建转发草稿（不带 `--confirm-send`）：
+```bash
+lark-cli mail +forward --message-id <邮件ID> --to <收件人>
+```
+→ 返回 `draft_id`
+
+**Step 2** — 向用户展示转发摘要（被转发邮件、收件人、附加说明），请求确认发送
+
+**Step 3** — 用户明确同意后，发送该草稿：
+```bash
+lark-cli mail user_mailbox.drafts send --params '{"user_mailbox_id":"me","draft_id":"<Step 1 返回的 draft_id>"}'
+```
+
+**禁止跳过 Step 1 直接使用 `--confirm-send`。禁止在用户未明确同意的情况下执行 Step 3。**
+
+## 命令
+
+```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 --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
+
+# 确认发送（用户明确确认后才可使用）
+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
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--message-id <id>` | 是 | 被转发的邮件 ID |
+| `--to <emails>` | 是 | 收件人邮箱，多个用逗号分隔 |
+| `--body <text>` | 否 | 转发时附加的说明文字。推荐使用 HTML 获得富文本排版；也支持纯文本。根据转发正文和原邮件正文自动检测 HTML。使用 `--plain-text` 可强制纯文本模式。支持 `<img src="./local.png" />` 相对路径自动解析为内嵌图片（仅支持相对路径，不支持绝对路径） |
+| `--from <email>` | 否 | 发件人邮箱地址（EML From 头）。使用别名（send_as）发信时，设为别名地址并配合 `--mailbox` 指定所属邮箱。默认读取邮箱主地址 |
+| `--mailbox <email>` | 否 | 邮箱地址，指定草稿所属的邮箱（默认回退到 `--from`，再回退到 `me`）。当发件人（`--from`）与邮箱不同时使用。可通过 `accessible_mailboxes` 查询可用邮箱 |
+| `--cc <emails>` | 否 | 抄送邮箱，多个用逗号分隔 |
+| `--bcc <emails>` | 否 | 密送邮箱，多个用逗号分隔 |
+| `--plain-text` | 否 | 强制纯文本模式，忽略所有 HTML 自动检测。不可与 `--inline` 同时使用 |
+| `--attach <paths>` | 否 | 附件文件路径，多个用逗号分隔，追加在原邮件附件之后。相对路径 |
+| `--inline <json>` | 否 | 高级用法：手动指定内嵌图片 CID 映射。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。仅在需要精确控制 CID 命名时使用此参数。格式：`'[{"cid":"mycid","file_path":"./logo.png"}]'`，在 body 中用 `<img src="cid:mycid">` 引用。不可与 `--plain-text` 同时使用 |
+| `--signature-id <id>` | 否 | 签名 ID。附加邮箱签名到转发正文与引用块之间。运行 `mail +signature` 查看可用签名。不可与 `--plain-text` 同时使用 |
+| `--confirm-send` | 否 | 确认发送转发（默认只保存草稿）。仅在用户明确确认后使用 |
+| `--send-time <timestamp>` | 否 | 定时发送时间，Unix 时间戳（秒）。需至少为当前时间 + 5 分钟。配合 `--confirm-send` 使用可定时发送邮件 |
+| `--dry-run` | 否 | 仅打印请求，不执行 |
+
+## 返回值
+
+默认（草稿模式）：
+```json
+{
+  "ok": true,
+  "data": {
+    "draft_id": "草稿ID",
+    "tip": "draft saved. To send: lark-cli mail user_mailbox.drafts send --params '{...}'"
+  }
+}
+```
+
+`--confirm-send` 模式：
+```json
+{
+  "ok": true,
+  "data": {
+    "message_id": "邮件ID",
+    "thread_id":  "会话ID"
+  }
+}
+```
+
+## 典型场景
+
+### 场景 1：用户说"把这封邮件转发给 Bob"（只创建草稿）
+```bash
+lark-cli mail +forward --message-id <邮件ID> --to bob@example.com --body '<p>FYI</p>'
+```
+→ 返回 `draft_id`，告诉用户转发草稿已创建。
+
+### 场景 2：用户说"转发给 Bob 并发送"（需要发送）
+```bash
+# Step 1: 创建转发草稿
+lark-cli mail +forward --message-id <邮件ID> --to bob@example.com --body '<p>FYI，请查收。</p>'
+# → 返回 draft_id
+
+# Step 2: 向用户确认 "转发草稿已创建：收件人 bob@example.com。确认发送吗？"
+
+# Step 3: 用户确认后发送
+lark-cli mail user_mailbox.drafts send --params '{"user_mailbox_id":"me","draft_id":"<draft_id>"}'
+```
+
+### 场景 3：用户说"下午 3 点转发给 Bob"（定时发送）
+```bash
+# Step 1: 创建转发草稿
+lark-cli mail +forward --message-id <邮件ID> --to bob@example.com --body '<p>FYI，请查收。</p>'
+# → 返回 draft_id
+
+# Step 2: 向用户确认 "转发草稿已创建：收件人 bob@example.com，定时 <目标时间> 发送。确认吗？"
+
+# Step 3: 用户确认后定时发送（send_time 为 Unix 时间戳，需至少当前时间 + 5 分钟）
+lark-cli mail user_mailbox.drafts send --params '{"user_mailbox_id":"me","draft_id":"<draft_id>"}' --data '{"send_time":"<unix_timestamp>"}'
+```
+
+### 场景 4：用户说"等等，先不转发了"（取消定时发送）
+```bash
+# 取消定时发送（取消后邮件变回草稿）
+lark-cli mail user_mailbox.drafts cancel_scheduled_send --params '{"user_mailbox_id":"me","draft_id":"<draft_id>"}'
+```
+→ 取消成功后邮件恢复为草稿状态，用户可重新编辑或在之后重新发送。
+
+## 转发整个会话
+
+`+forward` 操作的是单封邮件（`--message-id`），但转发整个会话时应 forward **会话中最后一条消息**，因为邮件客户端会将完整的回复链嵌套在最新一条中。典型流程：
+
+```bash
+# 1. 用 +triage 或 +thread 找到会话
+lark-cli mail +thread --thread-id <THREAD_ID> --html=false --format json
+
+# 2. 取最后一条消息的 message_id
+#    messages 按时间升序排列，最后一条 = messages[-1].message_id
+
+# 3. 转发该消息
+lark-cli mail +forward --message-id <最后一条的message_id> --to recipient@example.com --body '请过目'
+```
+
+## 实现说明
+
+- 自动拉取原邮件后构建转发内容。
+- 纯文本模式下会生成标准转发头块并附上原文文本。
+- HTML 模式下会生成结构化转发块并尽量保留原 HTML 正文。
+
+## 发送后跟进
+
+转发发送成功后：
+
+**1. 确认投递状态**（仅立即发送 — 无 `--send-time` 时必须）
+
+用返回的 `message_id` 查询投递状态：
+
+```bash
+lark-cli mail user_mailbox.messages send_status --params '{"user_mailbox_id":"me","message_id":"<发送返回的 message_id>"}'
+```
+
+状态码：1=正在投递, 2=投递失败重试, 3=退信, 4=投递成功, 5=待审批, 6=审批拒绝。向用户简要报告投递结果，异常状态需重点提示。
+
+**1b. 定时发送（指定了 `--send-time`）**
+
+定时发送不会立即产生 `message_id`，因此 `send_status` 在定时发送成功后会返回"待发送"状态，**不建议在定时发送后立即查询**。可在预定发送时间后再查询。
+
+如需取消定时发送：
+
+```bash
+lark-cli mail user_mailbox.drafts cancel_scheduled_send --params '{"user_mailbox_id":"me","draft_id":"<draft_id>"}'
+```
+
+**取消后邮件会变回草稿**，可继续编辑或在之后重新发送。
+
+**2. 标记已读**（可选）— 询问用户是否需要将原邮件标记为已读。如果用户同意：
+
+```bash
+lark-cli mail user_mailbox.messages batch_modify_message --params '{"user_mailbox_id":"me"}' --data '{"message_ids":["<原邮件ID>"],"remove_label_ids":["UNREAD"]}'
+```
+
+## 编辑转发草稿
+
+`+forward` 创建的草稿正文包含引用区（原邮件的引用块）。如果需要编辑转发草稿的正文，**必须通过 `--patch-file` 使用 `set_reply_body` op**，它仅替换用户撰写部分，自动保留引用区。value 只传新的用户撰写内容，不要包含引用区。
+
+```bash
+# 编辑转发草稿正文（自动保留引用区）
+cat > ./patch.json << 'EOF'
+{ "ops": [{ "op": "set_reply_body", "value": "<p>修改后的转发附言</p>" }] }
+EOF
+lark-cli mail +draft-edit --draft-id <draft_id> --patch-file ./patch.json
+```
+
+如果用户要修改引用区内容或去掉引用区，则使用 `set_body` 全量替换。
+
+## 相关命令
+
+- `lark-cli mail +send` — 发送新邮件
+- `lark-cli mail +reply` — 回复邮件
+- `lark-cli mail user_mailbox.messages get` — 查看邮件详情

package/server/assets/skills/lark-tools/cli-skills/lark-mail/references/lark-mail-message.md

@@ -0,0 +1,201 @@
+# mail +message
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+读取指定邮件的完整内容，包括邮件头、正文（纯文本 + 可选 HTML）以及统一的 `attachments` 列表（涵盖普通附件和内嵌图片）。
+
+CLI 分两阶段构建最终 JSON：
+- 安全的邮件元数据字段直接透传
+- 正文、附件和辅助字段由 shortcut 派生
+
+本 skill 对应 shortcut `lark-cli mail +message`，内部步骤：
+1. `GET /open-apis/mail/v1/user_mailboxes/{mailbox}/messages/{message_id}` — 获取完整邮件内容
+
+## 命令
+
+```bash
+# 读取一封邮件（默认包含 HTML 正文）
+lark-cli mail +message --message-id <message-id>
+
+# 仅纯文本正文（更小的负载，适合 AI 处理）
+lark-cli mail +message --message-id <message-id> --html=false
+
+# 指定邮箱
+lark-cli mail +message --mailbox user@example.com --message-id <message-id>
+
+# JSON 输出（脚本友好）
+lark-cli mail +message --message-id <message-id> --format json
+
+# Dry Run
+lark-cli mail +message --message-id <message-id> --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `--message-id <id>` | 是 | — | 邮件 ID |
+| `--mailbox <email>` | 否 | 当前用户 | 邮箱地址（`user_mailbox_id`） |
+| `--html` | 否 | true | 是否返回 HTML 正文（`false` 仅返回纯文本，减少带宽） |
+| `--format <mode>` | 否 | json | 输出格式：`json`（默认）/ `pretty` / `table` / `ndjson` / `csv` |
+| `--dry-run` | 否 | — | 仅打印请求，不执行 |
+
+## 返回值
+
+成功时返回 `{"ok": true, "data": ...}` 结构，`data` 字段包含：
+
+```json
+{
+  "message_id":               "邮件 ID",
+  "thread_id":                "会话 ID",
+  "smtp_message_id":          "RFC 2822 Message-ID",
+  "subject":                  "邮件主题",
+  "head_from":                {"mail_address": "alice@example.com", "name": "Alice"},
+  "to":                       [{"mail_address": "bob@example.com", "name": "Bob"}],
+  "cc":                       [{"mail_address": "carol@example.com", "name": "Carol"}],
+  "bcc":                      [],
+  "date":                     "Thu, 19 Mar 2026 16:33:02 +0800",
+  "in_reply_to":              "<original@domain>",
+  "reply_to":                 "reply-to@domain",
+  "reply_to_smtp_message_id": "reply-to@domain",
+  "references":               ["<a@domain>", "<b@domain>"],
+  "internal_date":            "1748000000000",
+  "date_formatted":           "2026-03-19 16:33",
+  "message_state":            1,
+  "message_state_text":       "received",
+  "folder_id":                "INBOX",
+  "label_ids":                ["UNREAD"],
+  "priority_type":            "1",
+  "priority_type_text":       "high",
+  "security_level": {
+    "is_risk": true,
+    "risk_banner_level": "DANGER",
+    "risk_banner_reason": "UNAUTH_EXTERNAL",
+    "is_header_from_external": true,
+    "via_domain": "example.com",
+    "spam_banner_type": "USER_RULE",
+    "spam_user_rule_id": "76180000000025388",
+    "spam_banner_info": "blocked.example.com"
+  },
+  "body_plain_text":          "Hi Bob, ...",
+  "body_preview":             "Hi Bob, ...",
+  "body_html":                "<html>...</html>",
+  "attachments": [
+    {
+      "id":              "att_xxx",
+      "filename":        "report.pdf",
+      "attachment_type": 1,
+      "is_inline":       false
+    },
+    {
+      "id":           "att_yyy",
+      "filename":     "logo.png",
+      "content_type": "image/png",
+      "is_inline":    true,
+      "cid":          "logo@cid"
+    }
+  ]
+}
+```
+
+### 字段说明
+
+> 注意：使用 `--format json` 获取结构化输出。所有 JSON 输出统一包裹在 `{"ok": true, "data": ...}` 结构中。
+
+| 字段 | 说明 |
+|------|------|
+| `message_id` | 邮件 ID |
+| `thread_id` | 会话 ID |
+| `subject` | 邮件主题 |
+| `head_from` | 发件人对象：`{mail_address, name}` |
+| `to` | 收件人列表：`[{mail_address, name}]` |
+| `cc` | 抄送列表：`[{mail_address, name}]` |
+| `bcc` | 密送列表：`[{mail_address, name}]` |
+| `date` | EML 中的时间（毫秒） |
+| `date_formatted` | 可读的发送时间，如 `"2026-03-19 16:33"` |
+| `smtp_message_id` | 符合 RFC 2822 的 SMTP Message-ID |
+| `in_reply_to` | In-Reply-To 邮件头 |
+| `references` | References 邮件头，祖先 SMTP message ID 列表 |
+| `internal_date` | 创建/接收/发送时间（毫秒） |
+| `message_state` | 邮件状态：`1` = 已接收，`2` = 已发送，`3` = 草稿 |
+| `message_state_text` | `"unknown"` / `"received"` / `"sent"` / `"draft"` |
+| `folder_id` | 文件夹 ID。值：`INBOX`、`SENT`、`SPAM`、`ARCHIVED`、`STRANGER`，或自定义文件夹 ID |
+| `label_ids` | 标签 ID 列表 |
+| `priority_type` | 优先级值：`0` = 无优先级，`1` = 高，`3` = 普通，`5` = 低 |
+| `priority_type_text` | `"unknown"` / `"high"` / `"normal"` / `"low"` |
+| `draft_id` | 草稿 ID，可通过列出草稿 API 获取 |
+| `reply_to` | Reply-To 邮件头 |
+| `reply_to_smtp_message_id` | Reply-To SMTP Message-ID |
+| `body_plain_text` | **LLM 阅读推荐的正文字段**；已 base64url 解码并清理 ANSI 转义 |
+| `body_preview` | 纯文本正文前 100 字符，用于快速预览 |
+| `body_html` | 原始 HTML 正文；`--html=false` 时省略 |
+| `attachments` | 普通附件和内嵌图片的统一列表 |
+| `attachments[].id` | 附件 ID（用于下载 URL API） |
+| `attachments[].filename` | 附件文件名 |
+| `attachments[].content_type` | 附件 MIME 类型 |
+| `attachments[].attachment_type` | 附件类型：`1` = 普通附件，`2` = 超大附件 |
+| `attachments[].is_inline` | `true` = 内嵌图片，`false` = 普通附件 |
+| `attachments[].cid` | 内嵌图片的 Content-ID（对应 HTML 正文中 `<img src="cid:...">` 的引用） |
+
+### security_level
+
+当服务端有该邮件的风险元数据时返回。
+
+| 字段 | 说明 |
+|------|------|
+| `is_risk` | 布尔值。`true` 表示邮件被标记为有风险 |
+| `risk_banner_level` | 风险等级。值：`WARNING`、`DANGER`、`INFO` |
+| `risk_banner_reason` | 风险原因。值：`NO_REASON`、`IMPERSONATE_DOMAIN`（相似域名仿冒）、`IMPERSONATE_KP_NAME`（关键人物姓名仿冒）、`UNAUTH_EXTERNAL`（未认证的外部域名）、`MALICIOUS_URL`、`MALICIOUS_ATTACHMENT`、`PHISHING`、`IMPERSONATE_PARTNER`（合作伙伴仿冒）、`EXTERNAL_ENCRYPTION_ATTACHMENT`（外部加密附件） |
+| `is_header_from_external` | 布尔值。`true` 表示发件人来自外部域名 |
+| `via_domain` | 当邮件代发或伪造时显示的 SPF/DKIM 域名，如 `"larksuite.com"` |
+| `spam_banner_type` | 垃圾邮件原因。值：`USER_REPORT`（用户举报）、`USER_BLOCK`（被用户屏蔽）、`ANTI_SPAM`（系统判定为垃圾邮件）、`USER_RULE`（匹配收件箱规则）、`BLOCK_DOMIN`（域名被用户屏蔽）、`BLOCK_ADDRESS`（地址被用户屏蔽） |
+| `spam_user_rule_id` | 匹配的收件箱规则 ID |
+| `spam_banner_info` | 匹配用户黑名单的地址或域名，如 `"larksuite.com"` |
+
+## 注意事项
+
+- **JSON 输出可直接使用** — 默认输出合法 UTF-8 JSON，可直接读取，无需额外编码转换。
+- JSON 输出中 `body_html` 里的 `<` / `>` 可能显示为 `\u003c` / `\u003e`（JSON 安全转义，内容不变，`jq -r` 可还原）。
+- `mail +message` 默认不再获取附件/图片下载 URL。这样可以保持邮件详情读取更轻量，调用方可按需单独请求 URL。
+- 查看原始 HTML：
+
+```bash
+# jq -r 自动处理 JSON 转义，输出原始 HTML
+lark-cli mail +message --message-id <id> --format json | jq -r '.data.body_html'
+```
+
+## 典型场景
+
+### 读取邮件 → 摘要 → 回复
+
+```bash
+# 1. 读取邮件（仅纯文本，更小负载）
+lark-cli mail +message --message-id <id> --html=false --format json
+
+# 2. 让 LLM 分析 body_plain_text 并起草回复
+
+# 3. 发送回复
+lark-cli mail +reply --message-id <id> --body "..."
+```
+
+### 按需获取附件或内嵌图片下载 URL
+
+```bash
+# 1. 读取邮件，从 .data.attachments[] 中获取附件 ID
+lark-cli mail +message --message-id <id> --format json
+
+# 2. 仅为需要的 ID 获取下载 URL
+lark-cli schema mail.user_mailbox.message.attachments.download_url
+lark-cli mail user_mailbox.message.attachments download_url \
+  --params '{"user_mailbox_id":"me","message_id":"<id>","attachment_ids":["att_xxx","att_yyy"]}'
+```
+
+普通附件和内嵌图片使用同一个 `user_mailbox.message.attachments download_url` 原生 API（无 shortcut 封装），传入 `attachments[].id` 即可。
+
+## 相关命令
+
+- `lark-cli mail +thread` — 读取会话中所有邮件
+- `lark-cli mail +reply` — 回复邮件
+- `lark-cli mail +forward` — 转发邮件
+- `lark-cli mail user_mailbox.message.attachments download_url` — 按需获取邮件附件/图片下载 URL
+- `lark-cli mail user_mailbox.messages list` — 列出收件箱邮件（获取 `message_id`）

package/server/assets/skills/lark-tools/cli-skills/lark-mail/references/lark-mail-messages.md

@@ -0,0 +1,108 @@
+# mail +messages
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+通过传入逗号分隔的 `message_id` 列表，一次性读取多封邮件的完整内容。
+
+本 shortcut 是 `mail +message` 的批量版本。每个返回的 `messages[]` 项使用与 `+message` 相同的归一化结构：安全元数据字段直接透传，正文和辅助字段由 shortcut 派生。
+
+优先使用本 shortcut 而非原生 `mail user_mailbox.messages batch_get` API，因为：
+- 正文字段已 base64url 解码
+- 每条邮件的输出结构已归一化
+- 不可用的 message ID 会被显式列出
+
+本 skill 对应 shortcut `lark-cli mail +messages`，内部步骤：
+1. `POST /open-apis/mail/v1/user_mailboxes/{mailbox}/messages/batch_get` — 批量获取邮件
+2. 对每条返回的邮件使用与 `+message` 相同的规则归一化输出
+
+## 命令
+
+```bash
+# 读取多封邮件（默认包含 HTML 正文）
+lark-cli mail +messages --message-ids <id1>,<id2>,<id3>
+
+# 仅纯文本正文（更小的负载，适合 AI 处理）
+lark-cli mail +messages --message-ids <id1>,<id2>,<id3> --html=false
+
+# 指定邮箱
+lark-cli mail +messages --mailbox user@example.com --message-ids <id1>,<id2>
+
+# JSON 输出
+lark-cli mail +messages --message-ids <id1>,<id2> --format json
+
+# Dry Run
+lark-cli mail +messages --message-ids <id1>,<id2> --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `--message-ids <id1,id2,...>` | 是 | — | 逗号分隔的邮件 ID 列表 |
+| `--mailbox <email>` | 否 | 当前用户 | 邮箱地址（`user_mailbox_id`） |
+| `--html` | 否 | true | 是否返回 HTML 正文（`false` 仅返回纯文本，减少带宽） |
+| `--format <mode>` | 否 | json | 输出格式：`json`（默认）/ `pretty` / `table` / `ndjson` / `csv` |
+| `--dry-run` | 否 | — | 仅打印请求，不执行 |
+
+## 返回值
+
+成功时返回 `{"ok": true, "data": ...}` 结构，`data` 字段包含：
+
+```json
+{
+  "messages": [
+    { "...与 +message 输出结构相同..." }
+  ],
+  "total": 1,
+  "unavailable_message_ids": ["msg-2"]
+}
+```
+
+顶层字段：
+
+| 字段 | 说明 |
+|------|------|
+| `messages` | 返回的邮件列表，顺序与请求的 `--message-ids` 一致，排除 API 未返回的 ID |
+| `total` | 成功返回的邮件数量 |
+| `unavailable_message_ids` | 请求了但 Mail API 未返回详情的 ID 列表 |
+
+每个 `messages[]` 项使用与 [`mail +message`](./lark-mail-message.md#返回值) 相同的结构。完整字段列表参见 [`+message` 字段说明](./lark-mail-message.md#字段说明) 和 [`+message` security_level](./lark-mail-message.md#security_level)。
+
+> 注意：使用 `--format json` 获取结构化输出。所有 JSON 输出统一包裹在 `{"ok": true, "data": ...}` 结构中。
+
+## 注意事项
+
+- **JSON 输出可直接使用**，可直接读取，无需额外编码转换。
+- 只需读取一封邮件时请使用 `+message`。
+- `--message-ids` 无硬性上限；shortcut 内部会自动将大列表拆分为多次批量 API 调用。
+- JSON 输出中 `messages[].body_html` 里的 `<` / `>` 可能显示为 `\u003c` / `\u003e`（JSON 安全转义，内容不变，`jq -r` 可还原）。
+- `mail +messages` 仅返回附件元数据。如后续步骤需要下载 URL，请针对特定的 `message_id` 和 `attachment_ids` 调用原生附件 URL API。
+- 与 `+message` 一样，普通附件和内嵌图片都出现在 `messages[].attachments[]` 中，使用同一个 `user_mailbox.message.attachments download_url` API。
+
+## 典型场景
+
+### 批量摘要多封已知邮件
+
+```bash
+# 一次性读取多封邮件
+lark-cli mail +messages --message-ids <id1>,<id2>,<id3> --html=false --format json
+
+# 让 LLM 分析 .data.messages[].body_plain_text 并生成分组摘要
+```
+
+### 对比多封邮件内容后决策
+
+```bash
+# 获取多封邮件的归一化输出
+lark-cli mail +messages --message-ids <id1>,<id2> --html=false --format json
+
+# 检查 subject/from/body_preview 或 body_plain_text，对比意图和下一步操作
+```
+
+## 相关命令
+
+- `lark-cli mail +message` — 读取单封邮件
+- `lark-cli mail +thread` — 读取会话中所有邮件
+- `lark-cli mail +reply` — 回复邮件
+- `lark-cli mail +forward` — 转发邮件
+- `lark-cli mail user_mailbox.message.attachments download_url` — 按需获取邮件附件/图片下载 URL