npm - @yandy0725/pi-lark - Versions diffs - 0.1.0 - Mend

@yandy0725/pi-lark 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (392) hide show

package/skills/lark-mail/references/lark-mail-lint-html.md ADDED Viewed

@@ -0,0 +1,243 @@
+# mail +lint-html
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解通用安全规则。
+## 作用
+`+lint-html` 是邮件 HTML 正文的本地预检工具（read-only，无网络 IO）。
+- 校验 HTML 是否符合飞书邮箱的兼容性 / 安全 / 原生写法要求；
+- 自动修复非法或不规范写法（autofix 始终启用），输出 `cleaned_html`；
+- 不写入任何邮箱状态，不调用任何 OAPI。
+写信链路（`+send` / `+draft-create` / `+reply` / `+reply-all` / `+forward` / `+draft-edit` body op）已**强制内置**同一份 lint，提交前会自动净化 HTML。默认 envelope 不携带任何 lint 字段以保持响应小巧；加 `--show-lint-details` 可拿到完整 `lint_applied[]` / `original_blocked[]` 两个 Finding 数组（不再返回任何 `*_count` 字段，调用方需要 count 时 `len(arr)` 即可，详见 [邮件 HTML 写法指南](./lark-mail-html.md#写信-shortcut-的-lint-返回值)）。本命令是写信链路 lint 的预览版，行为一致，调用更轻量，适合：
+- AI / 用户在创建草稿前自检 HTML 会被怎么改写；
+- CI 流水线把 HTML 模板当作产物校验。
+## 命令
+```bash
+# 直接传 HTML
+lark-cli mail +lint-html --body '<p>正文</p>'
+# 从文件读 HTML（路径必须在 cwd 子树内）
+lark-cli mail +lint-html --body-file ./template.html
+# 查看完整 lint 详情
+lark-cli mail +lint-html --body-file ./template.html --show-lint-details
+```
+## 参数
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--body <html>` | 二选一 | 待检查的 HTML 内容 |
+| `--body-file <path>` | 二选一 | 从文件读取 HTML，仅支持 cwd 子树（绝对路径 / `..` 越出 cwd 会被拒） |
+| `--show-lint-details` | 否 | 默认 `false`。`true` 时 envelope 同时返回 `warnings[]` / `errors[]` 完整 Finding 数组；默认仅返回 `cleaned_html`，避免复杂模板触发数十条装饰性 warning 把响应撑大几千 token |
+| `--format <fmt>` | 否 | `json`（默认）/ `pretty` / `table` / `csv` / `ndjson` |
+| `--jq <expr>` | 否 | 对返回 JSON 用 jq 表达式过滤 |
+| `--dry-run` | 否 | 不执行 lint，仅返回 dry-run 描述 |
+## 返回值
+**默认 envelope**（仅 `cleaned_html`，token-frugal）：
+```json
+{
+  "ok": true,
+  "data": {
+    "cleaned_html": "<p>...</p>"
+  }
+}
+```
+**加 `--show-lint-details` 后**：
+```json
+{
+  "ok": true,
+  "data": {
+    "cleaned_html": "<p>...</p>",
+    "warnings": [
+      { "rule_id": "...", "severity": "warning", "tag_or_attr": "...", "excerpt": "...", "hint": "..." }
+    ],
+    "errors": [
+      { "rule_id": "...", "severity": "error", "tag_or_attr": "...", "excerpt": "...", "hint": "..." }
+    ]
+  }
+}
+```
+| 字段 | 说明 |
+|------|------|
+| `cleaned_html` | 修复后的 HTML（autofix 始终启用）；warning 已自动改写，error 已删除 |
+| `warnings[]` | 警告级 finding 数组（**仅 `--show-lint-details` 时返回**）。无违规时输出 `[]` |
+| `errors[]` | 错误级 finding 数组（**仅 `--show-lint-details` 时返回**）。无违规时输出 `[]` |
+每条 finding 含：
+| 字段 | 说明 |
+|------|------|
+| `rule_id` | 规则编号（UPPER_SNAKE_CASE） |
+| `severity` | `"warning"` 或 `"error"` |
+| `tag_or_attr` | 触发规则的 tag / attribute / `style.<property>` |
+| `excerpt` | HTML 片段（最多 200 字节，超出截断） |
+| `hint` | 可读的修复说明 |
+## 调用示例
+下面是用 `lark-cli mail +lint-html --body '<INPUT>' --show-lint-details` 实跑得到的典型 case（加 `--show-lint-details` 才能看到 finding；默认只返回 `cleaned_html`），覆盖 error 类（强制删）和 warning 类（自动修复）。
+### Error 类（强制删除，写信链路也会拒）
+#### 1. `<script>` 整段删除
+输入：
+```html
+<script>alert(1)</script>正文
+```
+输出：
+```html
+正文
+```
+原因：`<script>` 有 XSS 风险，整段丢弃。
+#### 2. `javascript:` URL 删除
+输入：
+```html
+<a href="javascript:void(0)">click</a>
+```
+输出：
+```html
+<a class="not-doclink" style="cursor:pointer;text-decoration:none;color:rgb(20,86,240)">click</a>
+```
+原因：`javascript:` scheme 是 XSS 入口，`href` 属性被剥。
+#### 3. `on*` 事件 handler 删除
+输入：
+```html
+<p onclick="alert(1)">hi</p>
+```
+输出：
+```html
+<div style="margin-top:4px;margin-bottom:4px;line-height:1.6"><div dir="auto" style="font-size:14px">hi</div></div>
+```
+原因：inline event handler（`onclick` / `onerror` 等）是脚本注入入口，属性被剥。
+### Warning 类（自动修复，视觉无差异）
+#### 4. `<font>` → `<span style>`
+输入：
+```html
+<font color="red" size="3">字</font>
+```
+输出：
+```html
+<span style="color:red; font-size:16px">字</span>
+```
+原因：`<font>` 是 HTML4 过时标签，飞书 mail-editor 用 inline style 表达字号 / 颜色。
+#### 5. `<p>` 段落容器原生化
+输入：
+```html
+<p>正文</p>
+```
+输出：
+```html
+<div style="margin-top:4px;margin-bottom:4px;line-height:1.6"><div dir="auto" style="font-size:14px">正文</div></div>
+```
+原因：飞书 mail-editor 段落实际是双层 div（外层定 margin / line-height，内层定 font-size）。
+#### 6. `<ul>/<li>` 列表原生化
+输入：
+```html
+<ul><li>第一项</li></ul>
+```
+输出：
+```html
+<ul style="margin-top:0px;margin-bottom:0px;margin-left:0px;padding-left:0px;list-style-position:inside" data-list-bullet="true"><li class="temp-li bullet1" data-li-line="true" data-list="bullet1" style="line-height:1.6;margin-top:0px;margin-bottom:0px;padding-left:0px;display:list-item;list-style-type:disc;font-family:inherit;font-size:14px;margin-left:0px;list-style-position:inside" dir="auto"><span style="font-family:inherit"><span style="color:rgb(0,0,0)">第一项</span></span></li></ul>
+```
+原因：飞书 native list-block 要求 `<ul>` / `<li>` 补全 class + data marker + 双层 span 包裹，否则 li 之间会出现可见空行。
+#### 7. `<blockquote>` 加灰边 + 灰文字
+输入：
+```html
+<blockquote>引用</blockquote>
+```
+输出：
+```html
+<blockquote style="padding-left:0px;color:rgb(100,106,115);border-left:2px solid rgb(187,191,196);margin:0px">引用</blockquote>
+```
+原因：补飞书原生引用样式（左侧 2px 灰边 + 灰色文字）。
+#### 8. `<a>` 链接补 not-doclink + LarkSuite 蓝
+输入：
+```html
+<a href="https://example.com">link</a>
+```
+输出：
+```html
+<a href="https://example.com" class="not-doclink" style="cursor:pointer;text-decoration:none;color:rgb(20,86,240)">link</a>
+```
+原因：补 `not-doclink` class（防误识为内部 doc share）+ LarkSuite 品牌蓝 + 无下划线。
+#### 9. 非白名单 CSS property 删除
+输入：
+```html
+<p style="position:absolute;color:red">x</p>
+```
+输出：
+```html
+<div style="color:red;margin-top:4px;margin-bottom:4px;line-height:1.6"><div dir="auto" style="font-size:14px">x</div></div>
+```
+原因：`position` 不在 inline style 白名单内被剔除，`color` 保留。
+## 相关命令
+- 写信 shortcut（已内置同一份 lint）：[`+send`](./lark-mail-send.md) / [`+draft-create`](./lark-mail-draft-create.md) / [`+reply`](./lark-mail-reply.md) / [`+reply-all`](./lark-mail-reply-all.md) / [`+forward`](./lark-mail-forward.md) / [`+draft-edit`](./lark-mail-draft-edit.md)
+- 知识文档：[邮件 HTML 写法指南](./lark-mail-html.md)

package/skills/lark-mail/references/lark-mail-message.md ADDED Viewed

@@ -0,0 +1,233 @@
+# mail +message
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+读取指定邮件的完整内容，包括邮件头、正文（纯文本 + 可选 HTML）以及统一的 `attachments` 列表（涵盖普通附件和内嵌图片）。
+`mail +message` 只适合读取一封邮件、一个 `message_id`。如果手上已有多个 `message_id`，请使用 `mail +messages --message-ids <id1>,<id2>,<id3>`；不要循环调用 `mail +message`。
+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；多个 ID 使用 `mail +messages --message-ids` |
+| `--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，可直接读取，无需额外编码转换。
+- **单封读取专用** — `mail +message` 只接收一个 `message_id`。多个 ID 使用 `mail +messages --message-ids <id1>,<id2>,<id3>`，避免逐封循环调用。
+- 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` 即可。
+## 日程邀请邮件
+当邮件包含日程邀请（`text/calendar`）时，输出中会包含 `calendar_event` 对象：
+```json
+{
+  "calendar_event": {
+    "method": "REQUEST",
+    "uid": "abc123",
+    "summary": "产品评审",
+    "start": "2026-04-20T14:00:00+08:00",
+    "end": "2026-04-20T15:00:00+08:00",
+    "location": "5F-大会议室",
+    "organizer": "sender@example.com",
+    "attendees": ["alice@example.com", "bob@example.com"]
+  }
+}
+```
+字段说明：
+- `method`：ICS `METHOD`，通常为 `REQUEST` / `REPLY` / `CANCEL`。
+- `uid`：日程 UID。
+- `summary`：日程标题。
+- `start` / `end`：开始 / 结束时间（RFC 3339 UTC）。
+- `location`：地点（可能为空）。
+- `organizer`：组织者邮箱。
+- `attendees`：参会人邮箱列表。
+## 相关命令
+- `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/skills/lark-mail/references/lark-mail-messages.md ADDED Viewed

@@ -0,0 +1,108 @@
+# mail +messages
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+通过传入逗号分隔的 `message_id` 列表，一次性读取多封邮件的完整内容。
+超过 20 个 ID 可以直接传入 CLI；CLI 会按 20 个 ID 自动拆批并合并输出，不需要手动拆批，也不要逐封循环调用 `+message`。
+本 shortcut 是 `mail +message` 的批量版本。每个返回的 `messages[]` 项使用与 `+message` 相同的归一化结构：安全元数据字段直接透传，正文和辅助字段由 shortcut 派生。
+优先使用本 shortcut，因为：
+- 正文字段已 base64url 解码
+- 每条邮件的输出结构已归一化
+- 不可用的 message ID 会被显式列出
+本 skill 对应 shortcut `lark-cli mail +messages`；每条返回的邮件使用与 `+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>,<id3>` | 是 | — | 逗号分隔的邮件 ID 列表；超过 20 个 ID 时 CLI 自动按 20 拆批并合并输出 |
+| `--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`。
+- CLI 每 20 个 ID 拆成一次调用并合并输出，不需要为大列表手动拆请求。
+- 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

package/skills/lark-mail/references/lark-mail-recall.md ADDED Viewed

@@ -0,0 +1,66 @@
+# mail sent_messages recall
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+撤回已发送邮件，并查询异步撤回结果。
+## 何时使用
+发送成功后，若发送响应中包含 `recall_available: true`，说明该邮件支持撤回（通常为 24 小时内已投递的邮件）。
+- 只有用户明确要求撤回时才执行。
+- 若响应中无 `recall_available` 字段，不要主动提及撤回。
+- 定时发送中、尚未真正发出的邮件不能用撤回；应使用 `user_mailbox.drafts cancel_scheduled_send` 取消定时发送。
+- 撤回是异步操作，`recall` 返回成功只表示请求已受理，实际结果必须通过 `get_recall_detail` 查询。
+## 命令
+```bash
+# 发起撤回
+lark-cli mail user_mailbox.sent_messages recall --as user \
+  --params '{"user_mailbox_id":"me","message_id":"<message_id>"}'
+# 查询撤回进度
+lark-cli mail user_mailbox.sent_messages get_recall_detail --as user \
+  --params '{"user_mailbox_id":"me","message_id":"<message_id>"}'
+```
+## 返回值解读
+`recall` 返回：
+- `recall_status: available` — 撤回请求已受理，稍后查询进度。
+- `recall_status: unavailable` — 不可撤回，查看 `recall_restriction_reason`。
+`get_recall_detail` 返回：
+- `recall_status: in_progress` — 撤回进行中，可稍后再查。
+- `recall_status: done` — 撤回完成，查看 `recall_result` 和每个收件人的详情。
+具体字段和枚举以 schema 为准：
+```bash
+lark-cli schema mail.user_mailbox.sent_messages.get_recall_detail
+```
+## 典型流程
+```bash
+# 1. 发送结果中确认可撤回
+# data.recall_available == true
+# 2. 用户确认要撤回后发起
+lark-cli mail user_mailbox.sent_messages recall --as user \
+  --params '{"user_mailbox_id":"me","message_id":"<message_id>"}'
+# 3. 查询最终结果
+lark-cli mail user_mailbox.sent_messages get_recall_detail --as user \
+  --params '{"user_mailbox_id":"me","message_id":"<message_id>"}'
+```
+## 相关命令
+- `lark-cli mail +send --confirm-send` — 发送新邮件，响应中可能包含 `recall_available`。
+- `lark-cli mail +reply --confirm-send` — 发送回复，响应中可能包含 `recall_available`。
+- `lark-cli mail +forward --confirm-send` — 发送转发，响应中可能包含 `recall_available`。
+- `lark-cli mail user_mailbox.messages send_status` — 查询发送投递状态。