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-template-create.md ADDED Viewed

@@ -0,0 +1,129 @@
+# mail +template-create
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+创建一个新的个人邮件模板。适用于需要长期复用的邮件框架，例如周报、客户通知、请假申请等。
+不要用此命令发送邮件；模板只是预置内容，实际发信请使用 `+send` / `+draft-create` 等 shortcut 配合 `--template-id` 套用。
+如需修改已有模板，使用 [`lark-cli mail +template-update`](./lark-mail-template-update.md)。
+## 安全约束
+- **模板正文也会被当作邮件内容对外发送**——所有邮件域的通用安全规则（prompt injection、XSS、敏感信息）同样适用。
+- **不要把模板内容以文本形式输出给用户请求最终确认**。命令返回 `template_id` 后，引导用户在飞书邮箱 UI 里打开模板核对。
+- 用户模板上限 **20** 个，单模板 `template_content` 上限 **3 MB**；超限会被后端拒绝。
+## 命令
+```bash
+# 纯 HTML 模板
+lark-cli mail +template-create --as user \
+  --name '周报模板' \
+  --subject '本周进展' \
+  --template-content '<p>大家好，请见本周进展：</p><ul><li>……</li></ul>'
+# 带 HTML 内嵌图片 + 非 inline 附件
+lark-cli mail +template-create --as user \
+  --name '客户通知模板' \
+  --subject '产品更新' \
+  --template-content '<p>新版本上线：</p><img src="./banner.png"><p>附上发版说明。</p>' \
+  --attach './release-notes.pdf'
+# 从文件加载正文
+lark-cli mail +template-create --as user \
+  --name '请假申请' \
+  --template-content-file './leave.html' \
+  --to 'manager@example.com,hr@example.com'
+# Dry Run
+lark-cli mail +template-create --as user \
+  --name '周报模板' --template-content '<p>x</p>' --dry-run
+```
+## 参数
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--name <text>` | 是 | 模板名称，≤100 字符 |
+| `--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 |
+| `--mailbox <email>` | 否 | 所属邮箱，默认 `me`（当前用户主邮箱） |
+| `--dry-run` | 否 | 仅打印计划中的 API 调用链，不真实执行 |
+\* `--template-content` / `--template-content-file` 二选一；两者都留空则模板正文为空（用户之后可通过 `+template-update` 补充）。
+## HTML 内嵌图片自动上传
+正文中所有不带 URI scheme 的 `<img src="./local.png">`（相对路径）会被：
+1. 上传到 Drive（≤20 MB 走 `medias/upload_all`；>20 MB 走 `upload_prepare + upload_part + upload_finish`）
+2. 生成 UUIDv4 CID
+3. HTML 改写为 `<img src="cid:<uuid>">`
+4. 在 `attachments[]` 追加 `{id: <file_key>, cid, is_inline: true, filename, attachment_type}`
+带 URI scheme 的 `<img src="https://...">` 或 `<img src="cid:...">` 跳过上传。
+## SMALL vs LARGE 附件
+附件分为 SMALL（`attachment_type=1`，内嵌到 EML）和 LARGE（`attachment_type=2`，由服务端渲染成下载链接）。切换阈值：
+- **本地单文件大小**：≤20 MB 用 `upload_all`，>20 MB 分块上传（与 SMALL/LARGE 无关，只影响 Drive 上传路径）。
+- **累计 EML 投影**：`subject + to + cc + bcc + template_content + base64 附件体积`；同批次累计超过 **25 MB** 后，剩余的非 inline 附件标 `LARGE`，inline 图片不能切换到 LARGE（HTML `cid:` 引用要求 MIME part 存在）。
+两套判定相互独立。
+## 顺序约束
+- inline 图片按正文中 `<img>` 出现顺序处理
+- 非 inline 按 `--attach` 书写顺序处理；重复路径不会去重
+## 返回值
+成功返回：
+```json
+{
+  "template": {
+    "template_id": "712345",
+    "name": "周报模板",
+    "subject": "本周进展",
+    "template_content": "<p>...</p>",
+    "is_plain_text_mode": false,
+    "tos": [{"mail_address": "alice@example.com"}],
+    "attachments": [...],
+    "create_time": "1714000000000"
+  }
+}
+```
+- `template_id` 为十进制字符串。后续套用模板时 `--template-id <template_id>`。
+## 错误码速查
+| errno | HTTP | 触发 |
+|-------|------|------|
+| `15080201 InvalidTemplateName` | 400 | `name` 为空或超 100 字符 |
+| `15080202 TemplateNumberLimit` | 400 | 已达 20 模板上限 |
+| `15080203 TemplateContentSizeLimit` | 400 | 单模板 > 3 MB |
+| `15080206 TemplateTotalSizeLimit` | 400 | 所有模板总大小 > 50 MB |
+| `15080207 InvalidTemplateParam` | 400 | 其他参数错误 |
+## 所需 scope
+`mail:user_mailbox.message:modify`
+## 相关
+- 更新模板：[`+template-update`](./lark-mail-template-update.md)
+- 套用模板发信：在 `+send` / `+draft-create` / `+reply` / `+reply-all` / `+forward` 中使用 `--template-id`
+- 原生 API：
+  - `lark-cli mail user_mailbox.templates list --params '{"user_mailbox_id":"me"}'` — 列出模板
+  - `lark-cli mail user_mailbox.templates get --params '{"user_mailbox_id":"me","template_id":"<id>"}'` — 获取完整模板
+  - `lark-cli mail user_mailbox.templates delete --params '{"user_mailbox_id":"me","template_id":"<id>"}'` — 删除

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

@@ -0,0 +1,150 @@
+# mail +template-update
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+更新已有的个人邮件模板（全量替换式更新）。支持 `--inspect` 只读 projection、`--print-patch-template` 打印 patch 骨架、`--patch-file` 结构化 patch、以及扁平的 `--set-*` flag。
+> **⚠️ 后端无乐观锁 → last-write-wins**。并发更新可能丢失最近的改动；CLI 在每次成功更新时会在 stderr 打印一条 warning 提示。
+如需创建新模板，使用 [`lark-cli mail +template-create`](./lark-mail-template-create.md)。
+## 工作模式
+| 入口 | 行为 | 是否写库 |
+|------|------|---------|
+| `--print-patch-template` | 打印 `--patch-file` 的 JSON 骨架 | 否（纯本地） |
+| `--inspect` | 返回当前模板完整 projection | 否（只 GET） |
+| `--set-*` / `--attach` | 扁平 flag 合并后 PUT | 是 |
+| `--patch-file` | 结构化 patch + 扁平 flag 合并后 PUT | 是 |
+## 命令
+```bash
+# 查看当前状态（不修改）
+lark-cli mail +template-update --as user --template-id 712345 --inspect
+# 打印 patch 骨架并保存
+lark-cli mail +template-update --as user --print-patch-template > /tmp/tpl-patch.json
+# 用扁平 flag 改 subject + cc
+lark-cli mail +template-update --as user --template-id 712345 \
+  --set-subject '每周五发布' \
+  --set-cc 'manager@example.com'
+# 用 patch 文件做结构化更新（支持 is_plain_text_mode 翻回 false 等 tri-state 场景）
+lark-cli mail +template-update --as user --template-id 712345 \
+  --patch-file /tmp/tpl-patch.json
+# 追加新附件
+lark-cli mail +template-update --as user --template-id 712345 \
+  --attach './appendix.pdf'
+```
+## 参数
+### 定位
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--template-id <id>` | 是* | 模板 ID，十进制整数字符串 |
+| `--mailbox <email>` | 否 | 所属邮箱，默认 `me` |
+\* `--print-patch-template` 场景下可省略。
+### 只读 / 输出
+| 参数 | 说明 |
+|------|------|
+| `--inspect` | 只 GET，不修改；返回完整模板 projection |
+| `--print-patch-template` | 打印 patch 骨架（不访问网络），保存后作为 `--patch-file` 的起点 |
+### 扁平 set-* flag（直接指定新值）
+| 参数 | 说明 |
+|------|------|
+| `--set-name <text>` | 替换名称，≤100 字符 |
+| `--set-subject <text>` | 替换默认主题 |
+| `--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 附件（按书写顺序），不替换已有附件 |
+### 结构化 patch
+| 参数 | 说明 |
+|------|------|
+| `--patch-file <path>` | JSON patch 文件。结构同 `--print-patch-template` 输出；任何 **非空字段**覆盖当前模板对应字段 |
+patch-file 字段（全部可选，未提供的字段保持当前模板原值）：
+```json
+{
+  "name": "string (≤100 chars, optional)",
+  "subject": "string (optional)",
+  "template_content": "string (HTML 或纯文本；本地 <img src> 会自动上传)",
+  "is_plain_text_mode": "bool (optional) — 显式 true/false 都生效",
+  "tos": [{"mail_address": "...", "name": "..."}],
+  "ccs": [{"mail_address": "...", "name": "..."}],
+  "bccs": [{"mail_address": "...", "name": "..."}]
+}
+```
+## 合并策略
+1. `GET` 当前模板完整内容
+2. 先应用扁平 `--set-*` flag（非空即覆盖）
+3. 再应用 `--patch-file`（非空字段覆盖）——patch-file 优先级高于扁平 flag
+4. 重新扫描新正文中的 `<img>` 本地路径，上传到 Drive 并改写为 `cid:`
+5. `--attach` 追加的新附件以新的 `emlProjectedSize` 独立计算 SMALL/LARGE
+6. 附件按 `(id, cid)` 去重后 `PUT` 整个模板
+> **所有原有附件保留**：只追加 `--attach` 新附件；如需删除已有附件，目前只能通过 `--patch-file` 的 `template_content` 改写正文去除相应 `<img>` 引用，或使用原生 API 整块重写。
+## DryRun 行为
+- 默认：打印 `GET /user_mailboxes/:id/templates/:tid` + Drive 上传步骤（如有 `<img>` 或 `--attach`）+ `PUT` 步骤。
+- `--inspect`：只打印 `GET`。
+- `--print-patch-template`：打印骨架，不走任何 API。
+## 返回值
+成功返回：
+```json
+{
+  "template": {
+    "template_id": "712345",
+    "name": "周报模板",
+    "subject": "每周五发布",
+    "template_content": "...",
+    "is_plain_text_mode": false,
+    "tos": [...],
+    "attachments": [...],
+    "create_time": "1714000000000"
+  }
+}
+```
+`--inspect` 返回同样结构；`--print-patch-template` 返回 patch JSON 骨架。
+## 错误码速查
+| errno | HTTP | 触发 |
+|-------|------|------|
+| `15080201 InvalidTemplateName` | 400 | `--set-name` 为空或超 100 字符 |
+| `15080203 TemplateContentSizeLimit` | 400 | 更新后 `template_content` > 3 MB |
+| `15080204 InvalidTemplateID` | 404 | `template_id` 不存在或不属于当前用户 |
+| `15080207 InvalidTemplateParam` | 400 | 其他参数错误（含 `template_id` 无法 parseInt） |
+## 所需 scope
+`mail:user_mailbox.message:modify`, `mail:user_mailbox:readonly`
+## 相关
+- 创建模板：[`+template-create`](./lark-mail-template-create.md)
+- 套用模板发信：在 `+send` / `+draft-create` / `+reply` / `+reply-all` / `+forward` 中使用 `--template-id`
+- 删除模板（原生 API）：`lark-cli mail user_mailbox.templates delete --params '{"user_mailbox_id":"me","template_id":"<id>"}'`

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

@@ -0,0 +1,54 @@
+# mail templates
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+邮件模板指飞书 OAPI 的个人邮件模板系统（用户邮箱里的"我的模板"），可在飞书客户端管理。它不同于仓库 [`../assets/templates/`](../assets/templates/) 下的静态 HTML 模板库；静态 HTML 模板只是在写单封邮件时可复制参考的本地素材。
+## 何时使用
+- 创建 / 更新长期复用的邮件框架：用 `+template-create` / `+template-update`。
+- 使用已有模板发信：在 `+send` / `+draft-create` / `+reply` / `+reply-all` / `+forward` 中传 `--template-id <id>`。
+- 列表 / 获取 / 删除个人模板：走原生 API `user_mailbox.templates {list|get|delete}`。
+## 管理模板
+- [`+template-create`](lark-mail-template-create.md) — 创建新模板。`--name` 必填；正文通过 `--template-content` 或 `--template-content-file` 二选一；支持 HTML 内嵌图片自动上传到 Drive。
+- [`+template-update`](lark-mail-template-update.md) — 全量替换式更新（**后端无乐观锁，last-write-wins**）。支持 `--inspect`（只读 projection）/ `--print-patch-template`（patch 骨架）/ `--patch-file`（结构化 patch）/ 扁平 `--set-*` flag。
+## 套用模板
+`+send` / `+draft-create` / `+reply` / `+reply-all` / `+forward` 均支持 `--template-id <id>`。`--template-id` 必须是**十进制整数字符串**。
+### 创建模板后立即发信 checklist
+1. `+template-create --as user --name <name> --subject <subject> --template-content <html>`，捕获真实 `template_id`。
+2. 用户要求发送时不要停在模板或草稿：`+send --as user --to <email> --template-id <template_id> --confirm-send`；只有需要覆盖模板主题时再传 `--subject`。
+3. 返回 `message_id` 后调用 `user_mailbox.messages send_status` 汇报投递状态。
+## 合并规则
+| # | 场景 | 合并策略 |
+|---|------|----------|
+| Q1 to/cc/bcc | 全部 5 个 shortcut | 用户 `--to/--cc/--bcc` 先覆盖草稿原有值，再与模板 tos/ccs/bccs **无去重追加** |
+| Q2 subject | `+send` / `+draft-create` | 用户 `--subject` > 草稿 subject > 模板 subject |
+|  | `+reply` / `+reply-all` / `+forward` | 用户 `--subject` 覆盖自动 Re:/Fw:；否则保持 Re:/Fw: + 原邮件 subject。**模板 subject 被忽略**（保留会话线索） |
+| Q3 body | `+send` / `+draft-create` | 空草稿 body → 用模板；非空 HTML → `draftBody + <br><br> + tplContent`；非空 plain-text → `\n\n` 拼接 |
+|  | `+reply` / `+reply-all` / `+forward` | 模板内容注入 `<blockquote>` 之前；无 blockquote 则追加；plain-text 模板走 emlbuilder plain-text 追加 |
+| Q4 附件 | 全部 5 个 shortcut | 模板 inline（SMALL）由 CLI 走 `user_mailbox.template.attachments.download_url` 下载后以 MIME part 注入；SMALL 非 inline 同样注入；LARGE（`attachment_type=2`）不下载，只把 `file_key` 放到 `X-Lms-Large-Attachment-Ids` header 让服务端渲染下载卡片 |
+| Q5 cid 冲突 | inline 图片 | cid 由 UUID v4 生成（碰撞概率 ~ 2^-122），不显式检测 |
+**Warning**：`+reply` / `+reply-all` + 模板且模板自带 tos/ccs/bccs 时，CLI 在 stderr 打印：`warning: template to/cc/bcc are appended without de-duplication; you may see repeated recipients. Use --to/--cc/--bcc to override, or run +template-update to clear template addresses.`
+## Size 约束
+- 单模板 `template_content` <= 3 MB。
+- `body + inline + SMALL` 累计 <= 25 MB。
+- 超过 25 MB 后，该批次剩余非 inline 附件切换为 LARGE；inline 不能切换。
+## 原生 API
+```bash
+lark-cli mail user_mailbox.templates list --params '{"user_mailbox_id":"me"}'
+lark-cli mail user_mailbox.templates get --params '{"user_mailbox_id":"me","template_id":"<id>"}'
+lark-cli mail user_mailbox.templates delete --params '{"user_mailbox_id":"me","template_id":"<id>"}'
+```

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

@@ -0,0 +1,111 @@
+# mail +thread
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+读取指定会话中的所有邮件，按发送时间升序排列。每条邮件结构与 `+message` 相同。
+在实现上，每个 `messages[]` 项与 `mail +message` 的构建方式一致：安全元数据字段直接透传，正文/附件辅助字段由 shortcut 派生。每条邮件使用统一的 `attachments[]` 列表，涵盖普通附件和内嵌图片。
+本 skill 对应 shortcut `lark-cli mail +thread`，内部调用：
+- `GET /open-apis/mail/v1/user_mailboxes/{mailbox}/threads/{thread_id}` — 获取会话中所有邮件的完整内容
+## 命令
+```bash
+# 读取完整会话
+lark-cli mail +thread --thread-id <thread-id>
+# 仅纯文本正文（更小的负载，适合 AI 处理）
+lark-cli mail +thread --thread-id <thread-id> --html=false
+# 指定邮箱
+lark-cli mail +thread --mailbox user@example.com --thread-id <thread-id>
+# JSON 输出
+lark-cli mail +thread --thread-id <thread-id> --format json
+# Dry Run
+lark-cli mail +thread --thread-id <thread-id> --dry-run
+```
+## 参数
+| 参数 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `--thread-id <id>` | 是 | — | 会话 ID（`thread_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
+{
+  "thread_id":     "会话 ID",
+  "message_count": 2,
+  "messages": [
+    { "...与 +message 输出结构相同（最早的在前）..." },
+    { "......" }
+  ]
+}
+```
+顶层字段：
+| 字段 | 说明 |
+|------|------|
+| `thread_id` | `--thread-id` 请求的会话 ID |
+| `message_count` | 成功获取的邮件数量 |
+| `messages` | 按 `internal_date` 升序排列的邮件列表（最早的在前） |
+每个 `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 输出可直接使用**，可直接读取，无需额外编码转换。
+- JSON 输出中 `messages[].body_html` 里的 `<` / `>` 可能显示为 `\u003c` / `\u003e`（JSON 安全转义，内容不变，`jq -r` 可还原）。
+- `mail +thread` 不再在读取会话时获取附件/图片下载 URL。如后续步骤需要 URL，请针对特定的 `message_id` 和 `attachment_ids` 调用原生附件 URL API。
+- 与 `+message` 一样，普通附件和内嵌图片都出现在 `messages[].attachments[]` 中，使用同一个 `user_mailbox.message.attachments download_url` API。
+- 查看某条邮件的原始 HTML：
+```bash
+lark-cli mail +thread --thread-id <thread_id> --format json | jq -r '.data.messages[0].body_html'
+```
+## 典型场景
+### 查看会话时间线 → 生成摘要
+```bash
+# 1. 从某封邮件获取 thread_id
+lark-cli mail +message --message-id <id> --html=false --format json | jq '.data.thread_id'
+# 2. 读取完整会话（仅纯文本）
+lark-cli mail +thread --thread-id <thread_id> --html=false --format json
+# 3. 让 LLM 分析 messages[].body_plain_text 并生成会话摘要
+```
+### 回复会话中最新一封邮件
+```bash
+# 获取最新一封邮件的 message_id
+lark-cli mail +thread --thread-id <thread_id> --html=false --format json | \
+  jq '.data.messages[-1].message_id'
+# 回复
+lark-cli mail +reply --message-id <last_message_id> --body "..."
+```
+## 相关命令
+- `lark-cli mail +message` — 读取单封邮件
+- `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` — 列出收件箱邮件（获取 `thread_id`）

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

@@ -0,0 +1,131 @@
+# mail +triage
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+查看收件箱邮件摘要（date / from / subject / message_id），用于快速浏览和决定读哪封邮件。
+## 用法
+```bash
+# 默认：收件箱邮件（默认 20 条，默认table 格式）
+lark-cli mail +triage
+# 查看收件箱未读
+lark-cli mail +triage --filter '{"folder":"inbox","is_unread":true}'
+# 全文搜索
+lark-cli mail +triage --query "合同审批"
+# 按发件人 / 主题搜索
+lark-cli mail +triage --filter '{"from":["boss@example.com"],"subject":"季度报告"}'
+# 按时间范围搜索（如"上周的邮件"）
+lark-cli mail +triage --query "项目评审" --filter '{"time_range":{"start_time":"2026-03-16T00:00:00+08:00","end_time":"2026-03-22T23:59:59+08:00"}}'
+# 指定文件夹
+lark-cli mail +triage --filter '{"folder":"sent"}'
+# 系统标签（可通过 folder 或 label 传入，搜索时自动转为 folder）
+lark-cli mail +triage --filter '{"folder":"flagged"}'
+lark-cli mail +triage --filter '{"label":"important"}'
+lark-cli mail +triage --filter '{"label":"重要邮件"}'
+# json/data 格式可配合 jq 处理
+lark-cli mail +triage --format json | jq '.messages[].subject'
+# 分页：先取 10 条，再用 page_token 翻页
+lark-cli mail +triage --max 10 --format json
+# 输出中包含 page_token，传入下一次请求
+lark-cli mail +triage --page-token 'list:FfccvoqPd...' --max 10 --format json
+# --page-size 是 --max 的别名
+lark-cli mail +triage --page-size 10
+```
+## 参数
+| 参数 | 默认 | 说明 |
+|------|------|------|
+| `--filter <json>` | — | 筛选条件（见下方字段说明） |
+| `--query <text>` | — | 全文搜索关键词 |
+| `--format <mode>` | `table` | `table` / `json` / `data`（`json` 和 `data` 均输出含分页信息的对象） |
+| `--max <n>` | `20` | 最大返回条数（1-400），内部自动分页拉取 |
+| `--page-size <n>` | — | `--max` 的别名，两者含义相同；同时指定时 `--page-size` 优先 |
+| `--page-token <token>` | — | 上一次响应返回的分页令牌，传入后从该位置继续拉取。令牌带 `search:` 或 `list:` 前缀，标识来源路径，不可混用 |
+| `--labels` | — | table 格式时额外显示 labels 列 |
+| `--mailbox <id>` | `me` | 邮箱地址 |
+### `--filter` 支持的字段
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `folder` | string | 文件夹名称筛选。系统文件夹固定值：`inbox`/`sent`/`draft`/`trash`/`spam`/`archive`/`priority`/`flagged`/`other`/`scheduled`，也支持自定义文件夹名称。子文件夹需用 `parent_name/child_name` 格式，可通过 folder list 接口查看 |
+| `folder_id` | string | 文件夹 ID，优先级高于 `folder`。系统值：`INBOX`/`SENT`/`DRAFT`/`TRASH`/`SPAM`/`ARCHIVED`，自定义文件夹为数字 ID |
+| `label` | string | 自定义标签名称筛选。子标签需用 `parent_name/child_name` 格式，可通过 label list 接口查看 |
+| `label_id` | string | 标签 ID，优先级高于 `label`。自定义标签为数字 ID |
+| `is_unread` | boolean | 是否未读 |
+| `from` | string[] | 发件人 |
+| `to` | string[] | 收件人 |
+| `subject` | string | 主题关键词 |
+| `has_attachment` | boolean | 是否有附件 |
+| `time_range` | object | 时间范围 `{"start_time":"2026-01-01T00:00:00+08:00","end_time":"..."}` |
+> **系统标签说明**：`IMPORTANT`/`FLAGGED`/`OTHER` 可通过 `folder` 或 `label` 传入（也支持中文别名 `重要邮件`/`已加旗标`/`其他邮件`、搜索名 `priority`/`flagged`/`other`）。搜索时自动转为 folder 字段，列表时自动转为 label_id。label list 接口不返回这三个系统标签。
+>
+> **⚠️ 注意**：查询未读请用 `"is_unread":true`。
+可运行 `mail +triage --print-filter-schema` 查看完整字段说明。
+## 输出
+### `--format json` / `--format data`
+两者输出格式相同，均为含分页信息的对象：
+```json
+{
+  "messages": [
+    {
+      "message_id": "SEU2...",
+      "mailbox_id": "me",
+      "date": "Fri, 21 Mar 2026 11:40:00 +0800",
+      "from": "Alice <alice@example.com>",
+      "subject": "Weekly update",
+      "labels": "INBOX,UNREAD"
+    }
+  ],
+  "mailbox_id": "me",
+  "count": 20,
+  "has_more": true,
+  "page_token": "list:FfccvoqPd_loLhtcRx8cx..."
+}
+```
+- `mailbox_id`：当前邮箱标识，用于传递给 `mail +message --mailbox` 以保持公共邮箱上下文
+- `has_more`：是否还有下一页
+- `page_token`：传入 `--page-token` 可获取下一页；为空字符串表示已到末尾
+- token 前缀 `search:` / `list:` 标识来源 API 路径，不可混用
+### `table` 格式
+`page_token` 信息输出在 stderr，自动携带 `--query`/`--filter`/`--mailbox` 参数方便续页：
+```text
+15 message(s)
+next page: mail +triage --query '合同审批' --page-token 'search:abc123...'
+tip: read full content: single message use mail +message --message-id <id>; multiple messages use mail +messages --message-ids <id1>,<id2>,<id3>
+```
+公共邮箱场景下，`--mailbox` 会自动出现在续页和 tip 中：
+```text
+next page: mail +triage --mailbox 'shared@example.com' --query '合同审批' --page-token 'search:abc123...'
+tip: read full content: single message use mail +message --mailbox 'shared@example.com' --message-id <id>; multiple messages use mail +messages --mailbox 'shared@example.com' --message-ids <id1>,<id2>,<id3>
+```
+### 搜索分页注意事项
+搜索路径（使用 `--query` 或 `from`/`to`/`subject` 等 filter）的分页结果在**同一翻页链内**保持一致（无重复、无丢失）。但不同 `--max` 值发起的独立搜索可能返回不同排序，这是搜索 API 的固有行为。列表路径（仅 `folder`/`label` 筛选）无此限制。
+## 参考
+- [lark-mail](../SKILL.md) — 邮箱域总览
+- [lark-mail-watch](lark-mail-watch.md) — 实时监听新邮件

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

@@ -0,0 +1,94 @@
+# mail +watch
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+实时监听新邮件事件（`mail.user_mailbox.event.message_received_v1`）。
+**权限要求：** 应用需要 `mail:event`、`mail:user_mailbox.message:readonly` 权限，以及字段权限 `mail:user_mailbox.message.address:read`、`mail:user_mailbox.message.subject:read`、`mail:user_mailbox.message.body:read`，且机器人需订阅事件 `mail.user_mailbox.event.message_received_v1`。按需权限（缺失时会提示申请）：使用 `--folders` / `--folder-ids` 筛选自定义文件夹时需要 `mail:user_mailbox.folder:read`；使用 `--labels` / `--label-ids` 筛选自定义标签时需要 `mail:user_mailbox.message:modify`。
+## 命令
+```bash
+# 默认：表格输出 message 元数据
+lark-cli mail +watch
+# 仅输出 message 数据（jq 友好）
+lark-cli mail +watch --msg-format metadata --format data
+# 输出精简元数据（message_id / thread_id / folder_id / label_ids / internal_date / message_state）
+lark-cli mail +watch --msg-format minimal --format data
+# 输出纯文本全文
+lark-cli mail +watch --msg-format plain_text_full --format data
+# 输出完整 message（含正文相关字段）
+lark-cli mail +watch --msg-format full --format data
+# 输出原始事件体
+lark-cli mail +watch --msg-format event --format data
+# 监听指定邮箱
+lark-cli mail +watch --mailbox alice@company.com
+# 按文件夹/标签过滤（客户端过滤，支持名称或 ID）
+lark-cli mail +watch --folders '["收件箱项目"]' --label-ids '["FLAGGED"]'
+# 写入文件
+lark-cli mail +watch --msg-format metadata --output-dir ./mail-events
+# 查看各 --msg-format 的输出字段说明（解析前先运行）
+lark-cli mail +watch --print-output-schema
+```
+## 参数
+| 参数 | 默认 | 说明 |
+|------|------|------|
+| `--mailbox <id>` | `me` | 订阅目标邮箱 |
+| `--msg-format <mode>` | `metadata` | 输出模式：`metadata` / `minimal` / `plain_text_full` / `full` / `event` |
+| `--format <mode>` | `table` | 输出样式：`table` / `json` / `data` |
+| `--folder-ids <json-array>` | — | 文件夹 ID 过滤，如 `["INBOX","SENT"]` |
+| `--folders <json-array>` | — | 文件夹名称过滤（与 `--folder-ids` 取并集） |
+| `--label-ids <json-array>` | — | 标签 ID 过滤，如 `["FLAGGED","IMPORTANT"]` |
+| `--labels <json-array>` | — | 标签名称过滤（与 `--label-ids` 取并集） |
+> **过滤逻辑：** `--folder-ids`/`--folders` 与 `--label-ids`/`--labels` 之间是 **AND** 关系，即邮件必须**同时**匹配指定的文件夹和标签才会输出。同类参数内部是 **OR** 关系（匹配其中任一即可）。新收到的邮件通常只有系统标签（如 `UNREAD`、`IMPORTANT`），不会自动带有自定义标签。
+| `--output-dir <dir>` | — | 每条事件写入单独 JSON 文件 |
+| `--print-output-schema` | — | 打印各 `--msg-format` 的输出字段说明（解析输出前先运行此命令） |
+| `--dry-run` | — | 仅预览订阅请求，不实际连接 |
+## --msg-format 输出结构（--format json）
+每条事件输出为一行 NDJSON。
+**`metadata`**（默认，适合分拣/通知）
+```json
+{"ok":true,"data":{"message":{"message_id":"...","thread_id":"...","subject":"...","head_from":{"name":"Alice","mail_address":"alice@example.com"},"to":[{"name":"Bob","mail_address":"bob@example.com"}],"folder_id":"INBOX","label_ids":["IMPORTANT"],"internal_date":"1742800000000","message_state":1,"body_preview":"Please find attached..."}}}
+```
+**`minimal`**（仅 ID 和状态，适合追踪已读/文件夹变更）
+```json
+{"ok":true,"data":{"message":{"message_id":"...","thread_id":"...","folder_id":"INBOX","label_ids":["IMPORTANT"],"internal_date":"1742800000000","message_state":1}}}
+```
+**`plain_text_full`**（metadata 全部字段 + 完整纯文本正文）
+```json
+{"ok":true,"data":{"message":{"message_id":"...","subject":"...","head_from":{...},"folder_id":"INBOX","label_ids":[...],"body_preview":"...","body_plain_text":"<base64url>"}}}
+```
+**`event`**（原始 WebSocket 事件，不发起 API 请求，适合调试）
+```json
+{"ok":true,"data":{"header":{"event_id":"abc123","event_type":"mail.user_mailbox.event.message_received_v1","create_time":"1742800000000"},"event":{"message_id":"...","mail_address":"user@example.com"}}}
+```
+**`full`**（全部字段，含 HTML 正文和附件）
+```json
+{"ok":true,"data":{"message":{"message_id":"...","subject":"...","head_from":{...},"body_preview":"...","body_plain_text":"<base64url>","body_html":"<base64url>","attachments":[{"name":"report.pdf","size":102400}]}}}
+```
+## 参考
+- [lark-mail](../SKILL.md) — 邮箱域总览
+- [lark-mail-triage](lark-mail-triage.md) — 邮件摘要列表
+- [lark-event-subscribe](../../lark-event/references/lark-event-subscribe.md) — 通用事件订阅