@wagemule/daemon 0.1.0 → 0.1.3

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

@@ -0,0 +1,216 @@
+# mail +send
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+发送新邮件，支持：
+- 纯文本或 HTML 正文
+- 抄送/密送
+- 本地文件附件（`--attach`）
+- 内嵌图片（`--inline`，CID 可用随机字符串）
+
+本 skill 对应 shortcut：`lark-cli mail +send`。
+
+## CRITICAL — 发送工作流（必须遵循）
+
+此命令默认**只保存草稿**，不会发送邮件。需要发送时，有两种合规方式：
+
+**方式 A（推荐）** — 先创建草稿，再确认发送：
+```bash
+lark-cli mail +send --to <收件人> --subject '<主题>' --body '<正文>'
+```
+→ 返回 `draft_id`
+
+向用户展示邮件摘要（收件人、主题、正文预览）；如果用户想先看效果，可引导其去飞书邮件里打开该草稿查看详情。
+
+用户明确同意后，发送该草稿：
+```bash
+lark-cli mail user_mailbox.drafts send --params '{"user_mailbox_id":"me","draft_id":"<Step 1 返回的 draft_id>"}'
+```
+
+**方式 B（允许）** — 用户已经明确确认收件人和内容时，可直接使用 `--confirm-send` 立即发送：
+```bash
+lark-cli mail +send --to <收件人> --subject '<主题>' --body '<正文>' --confirm-send
+```
+
+**禁止在用户未明确同意的情况下执行发送，无论是发送草稿还是直接使用 `--confirm-send`。**
+
+## 命令
+
+```bash
+# 保存为草稿（默认行为，不发送）— HTML 格式推荐
+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 --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 '<img src="./logo.png" />'
+
+# 纯文本邮件（仅在内容极简时使用）
+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
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--to <emails>` | 是 | 收件人邮箱，多个用逗号分隔 |
+| `--subject <text>` | 是 | 邮件主题 |
+| `--body <text>` | 是 | 邮件正文。推荐使用 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>` | 否 | 附件文件路径，多个用逗号分隔。相对路径。当附件导致 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` 同时使用 |
+| `--signature-id <id>` | 否 | 签名 ID。附加邮箱签名到正文末尾。运行 `mail +signature` 查看可用签名。不可与 `--plain-text` 同时使用 |
+| `--priority <level>` | 否 | 邮件优先级：`high`、`normal`、`low`。省略或 `normal` 时不设置优先级 |
+| `--event-summary <text>` | 否 | 日程标题。设置此参数即在邮件中嵌入日程邀请（text/calendar）。需同时设置 `--event-start` 和 `--event-end` |
+| `--event-start <time>` | 条件必填 | 日程开始时间（ISO 8601，如 `2026-04-20T14:00+08:00`） |
+| `--event-end <time>` | 条件必填 | 日程结束时间（ISO 8601） |
+| `--event-location <text>` | 否 | 日程地点 |
+| `--confirm-send` | 否 | 确认发送邮件（默认只保存草稿）。仅在用户明确确认收件人和内容后使用 |
+| `--send-time <timestamp>` | 否 | 定时发送时间，Unix 时间戳（秒）。需至少为当前时间 + 5 分钟。配合 `--confirm-send` 使用可定时发送邮件 |
+| `--request-receipt` | 否 | 请求已读回执（RFC 3798 Message Disposition Notification）。在出站 EML 里写 `Disposition-Notification-To: <sender>` 头。收件人的邮件客户端**可能**弹出提示询问是否回执、可能自动发送、也可能忽略——送达不保证 |
+| `--dry-run` | 否 | 仅打印请求，不执行 |
+
+### 日程邀请约束
+
+使用 `--event-*` 时需满足以下条件：
+
+- `--event-summary`、`--event-start`、`--event-end` 必须同时出现或同时不出现
+- 与 `--send-time` 互斥，不可同时使用（日程邀请必须立即发送，否则收件人可能在日程开始后才收到）
+- 不可与 `--bcc` 同时使用：日程参会人（ATTENDEE）仅来自 To 和 Cc，Bcc 收件人不在参会人列表中、无法 RSVP，且该组合将导致邮件发送失败。需要邀请某人参加日程请用 `--to` 或 `--cc`；如只想告知而不邀请，请单独发一封无日程的邮件
+
+## 返回值
+
+**草稿模式（默认）：**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "draft_id": "草稿ID",
+    "tip": "draft saved. To send: lark-cli mail user_mailbox.drafts send --params '{...}'"
+  }
+}
+```
+
+草稿模式下，只要结果不是直接发信而是产出了草稿，就应给用户展示草稿打开链接。当前应以 `create` / `edit` / `send` 链路返回的链接信息为准，不要把 `user_mailbox.drafts get` 当作拿草稿打开链接的来源。如果返回中带有 `reference`，应把链接与 `draft_id` 一并返回；当前没有链接时，静默处理，不要伪造链接。
+
+**发送模式（`--confirm-send`）：**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "message_id": "邮件ID",
+    "thread_id": "会话ID"
+  }
+}
+```
+
+可选字段：
+
+- `automation_send_disable_reason`：发送被邮箱自动化设置拦截时返回的原因
+- `automation_send_disable_reference`：发送被拦截时的草稿打开链接
+
+字段语义：
+
+- 若返回中包含 `automation_send_disable_reason` / `automation_send_disable_reference`，说明邮件未真正发出，而是被邮箱设置拦截。此时应直接向用户展示原因和草稿打开链接，不要继续假设已经发送成功
+
+## 典型场景
+
+### 场景 1：用户说"帮我写一封邮件给 Alice"（只创建草稿）
+```bash
+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>'
+# → 返回 draft_id
+
+# 向用户确认 "当前收件人 alice@example.com，主题「收到」。如果你想先看效果，也可以先去飞书邮件里打开草稿查看详情。确认发送吗？"
+
+# 用户确认后发送
+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
+```
+
+### 场景 3：用户说"下午 3 点给 Alice 发一封周报"（定时发送）
+```bash
+# Step 1: 创建草稿（定时发送也走草稿流程）
+lark-cli mail +send --to alice@example.com --subject '周报' --body '<p>本周进展如下...</p>'
+# → 返回 draft_id
+
+# Step 2: 向用户确认 "邮件草稿已创建：收件人 alice@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>"}'
+```
+→ 取消成功后邮件恢复为草稿状态，用户可重新编辑或在之后重新发送。
+
+## 发送后跟进
+
+邮件发送后，分两种情况处理：
+
+- 若返回中有 `automation_send_disable_reason` / `automation_send_disable_reference`：说明发送被邮箱设置拦截，应直接告诉用户原因并提供草稿打开链接，**不要**调用 `send_status`
+
+### 立即发送（无 `--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=审批拒绝。向用户简要报告各收件人投递结果，异常状态需重点提示。
+
+### 定时发送（指定了 `--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>"}'
+```
+
+**取消后邮件会变回草稿**，可继续编辑或在之后重新发送。
+
+## 实现说明
+
+- 使用 EML 构建器生成完整 MIME 邮件并 base64url 编码后发送。
+- `--attach` 作为普通附件添加。相对路径。
+- `--inline` 接受 JSON 数组，每项需提供 `cid`（唯一标识符，可用随机十六进制字符串）和 `file_path`（相对路径），作为 inline part 嵌入邮件。
+- **超大附件**：当附件导致 EML 总大小（headers + body + inline images + attachments，base64 编码后）超过 25 MB 时，超出的文件自动通过 `medias/upload_*` API 上传到云端。HTML 邮件插入与飞书客户端一致的下载卡片；纯文本邮件追加包含文件名、大小和下载链接的文本块。单个文件上限 3 GB，总附件数量上限 250 个。
+
+## 相关命令
+
+- `lark-cli mail +reply` — 回复邮件
+- `lark-cli mail +reply-all` — 回复全部
+- `lark-cli mail +forward` — 转发邮件
+- `lark-cli mail user_mailbox.messages list` — 列出邮件

package/dist/skills/larksuite/lark-mail/references/lark-mail-share-to-chat.md

@@ -0,0 +1,87 @@
+# mail +share-to-chat
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+将邮件以卡片形式分享到飞书 IM 会话（群聊或个人对话）。内部两步完成：创建分享凭证 → 发送卡片到 IM。
+
+**依赖 Scope：** `mail:user_mailbox.message:readonly`、`im:message`、`im:message.send_as_user`
+
+## 命令
+
+```bash
+# 分享单封邮件到群聊（默认 receive-id-type=chat_id）
+lark-cli mail +share-to-chat --message-id <邮件ID> --receive-id oc_xxx
+
+# 分享整个会话到群聊
+lark-cli mail +share-to-chat --thread-id <会话ID> --receive-id oc_xxx
+
+# 通过邮箱分享给个人
+lark-cli mail +share-to-chat --message-id <邮件ID> --receive-id user@example.com --receive-id-type email
+
+# Dry Run
+lark-cli mail +share-to-chat --message-id <邮件ID> --receive-id oc_xxx --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--message-id <id>` | 否（二选一） | 要分享的邮件 ID，与 `--thread-id` 互斥 |
+| `--thread-id <id>` | 否（二选一） | 要分享的邮件会话 ID，与 `--message-id` 互斥 |
+| `--receive-id <id>` | 是 | 目标接收者 ID，类型由 `--receive-id-type` 决定 |
+| `--receive-id-type <type>` | 否 | 接收者 ID 类型（默认 `chat_id`）。可选：`chat_id` / `open_id` / `user_id` / `union_id` / `email` |
+| `--mailbox <email>` | 否 | 邮箱地址（默认 `me`） |
+| `--dry-run` | 否 | 仅打印请求，不执行 |
+
+## 返回值
+
+```json
+{
+  "ok": true,
+  "data": {
+    "card_id": "550e8400-e29b-41d4-a716-446655440000",
+    "im_message_id": "om_dc13264520392913993dd051dba21dcf"
+  }
+}
+```
+
+## 典型场景
+
+### 场景 1：用户说"帮我把这封邮件分享到项目群"
+
+```bash
+# Step 1: 搜索群聊获取 chat_id
+lark-cli im +chat-search --query "项目群"
+# → 获取 chat_id: oc_xxx
+
+# Step 2: 分享邮件
+lark-cli mail +share-to-chat --message-id <邮件ID> --receive-id oc_xxx
+```
+
+### 场景 2：分享整个邮件会话
+
+```bash
+lark-cli mail +share-to-chat --thread-id <会话ID> --receive-id oc_xxx
+```
+
+### 场景 3：通过邮箱分享给个人
+
+```bash
+lark-cli mail +share-to-chat --message-id <邮件ID> --receive-id alice@example.com --receive-id-type email
+```
+
+## 常见错误
+
+| 症状 | 原因 | 解决 |
+|------|------|------|
+| `either --message-id or --thread-id is required` | 两个参数都未传 | 传入其中一个 |
+| `--message-id and --thread-id are mutually exclusive` | 两个参数同时传 | 只传一个 |
+| 403 `user not in chat` | 用户不在目标会话中 | 确认用户是群成员 |
+| 404 `message not found` | 邮件 ID 无效 | 确认邮件 ID 正确 |
+| 403 `permission not granted` | 缺少 `im:message` 或 `im:message.send_as_user` scope | 重新授权：`lark-cli auth login --scope "im:message,im:message.send_as_user"` |
+
+## 相关命令
+
+- `lark-cli im +chat-search` — 搜索群聊获取 chat_id
+- `lark-cli mail +message` — 查看邮件内容
+- `lark-cli mail +thread` — 查看邮件会话

package/dist/skills/larksuite/lark-mail/references/lark-mail-signature.md

@@ -0,0 +1,98 @@
+# mail +signature
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+查看邮箱签名列表或详情。返回签名的类型、默认使用情况、内容预览等信息。TENANT（企业）签名的模板变量会被自动替换为实际值。
+
+本 skill 对应 shortcut：`lark-cli mail +signature`。
+
+## 命令
+
+```bash
+# 列出所有签名
+lark-cli mail +signature
+
+# 查看某个签名的详情（渲染后的内容预览、模板变量值、图片信息）
+lark-cli mail +signature --detail <signature_id>
+
+# 指定邮箱
+lark-cli mail +signature --from shared@example.com
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--from <email>` | 否 | 邮箱地址（默认 `me`） |
+| `--detail <id>` | 否 | 签名 ID，查看详情。省略则列出所有签名 |
+
+## 返回值
+
+**列表模式：**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "signatures": [
+      {
+        "id": "<签名ID>",
+        "name": "个人签名",
+        "type": "USER",
+        "content_preview": "这是我的签名内容 [image] 超链接哈哈"
+      },
+      {
+        "id": "<签名ID>",
+        "name": "企业签名",
+        "type": "TENANT",
+        "is_send_default": true,
+        "is_reply_default": true,
+        "content_preview": "企业签名 姓名：陈煌 部门：研发团队"
+      }
+    ]
+  }
+}
+```
+
+**详情模式（`--detail`）：**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "id": "<签名ID>",
+    "name": "企业签名",
+    "type": "TENANT",
+    "is_send_default": true,
+    "is_reply_default": true,
+    "images": [
+      {"cid": "76CEB29E-...", "file_key": "121011...", "image_name": "image.png"}
+    ],
+    "template_vars": {"B-NAME": "陈煌", "B-DEPARTMENT": "研发团队"},
+    "content_preview": "企业签名 姓名：陈煌 部门：研发团队"
+  }
+}
+```
+
+## 字段说明
+
+| 字段 | 说明 |
+|------|------|
+| `type` | `USER`（用户签名，可编辑）或 `TENANT`（企业签名，管理员模板控制） |
+| `is_send_default` | 是否为新邮件的默认签名 |
+| `is_reply_default` | 是否为回复/转发的默认签名 |
+| `images` | 签名内联图片元数据（仅详情模式） |
+| `template_vars` | TENANT 签名的模板变量已替换值（仅详情模式） |
+| `content_preview` | 签名内容的纯文本预览（`<img>` 显示为 `[image]`，最长 200 字符） |
+
+## 与 compose shortcut 配合
+
+获取签名 ID 后，可在发送/回复/转发时附加签名：
+
+```bash
+# 查看签名列表获取 ID
+lark-cli mail +signature
+
+# 在发送邮件时附加签名
+lark-cli mail +send --to alice@example.com --subject '你好' --body '<p>内容</p>' --signature-id <签名ID>
+```

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

@@ -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/dist/skills/larksuite/lark-mail/references/lark-mail-template-update.md

@@ -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>"}'`