@wagemule/daemon 0.1.2 → 0.1.4

package/dist/skills/larksuite/lark-mail/references/lark-mail-decline-receipt.md

@@ -0,0 +1,115 @@
+# mail +decline-receipt
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+关闭收到邮件的已读回执请求 banner，**但不向发件人发送回执**。**本命令仅在对方邮件请求了已读回执（`READ_RECEIPT_REQUEST` 标签，系统 ID `-607`）时使用**。对齐飞书客户端上已读回执 banner 右侧的"不发送"按钮。
+
+本 skill 对应 shortcut：`lark-cli mail +decline-receipt`。
+
+## 使用时机
+
+决策分支：拉信看到 `READ_RECEIPT_REQUEST` 标签 → **必须先问用户**：
+
+- 用户愿意告知对方"已读" → `+send-receipt`
+- 用户不愿意告知但想消掉提示 → `+decline-receipt`（本命令）
+- 用户既不想回执也不关心 banner → 什么都不做
+
+## 命令
+
+```bash
+# 标准用法
+lark-cli mail +decline-receipt --message-id <message-id>
+
+# 指定邮箱（公共邮箱场景）
+lark-cli mail +decline-receipt --mailbox shared@example.com --message-id <message-id>
+
+# Dry Run（不真改）
+lark-cli mail +decline-receipt --message-id <message-id> --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 默认 | 说明 |
+|------|------|------|------|
+| `--message-id <id>` | 是 | — | 请求了已读回执的原邮件 message ID |
+| `--mailbox <email>` | 否 | `me` | 邮件归属的邮箱 |
+| `--dry-run` | 否 | — | 仅打印请求，不执行 |
+
+> 注意本命令没有 `--yes` —— 它只是移除一个本地 label，不对外发信，Risk 级别是 `write` 而非 `high-risk-write`。
+
+## 行为细节
+
+- 先 `fetchFullMessage` 拉一遍原邮件校验：若 `label_ids` 中不含 `READ_RECEIPT_REQUEST`（也不含数字 `-607`），直接返回 `already_cleared: true`，**不发请求**，幂等。
+- 标签存在时调 `PUT /user_mailboxes/<mailbox>/messages/<id>/modify`（`user_mailbox.message.modify`），body `{"remove_label_ids":["READ_RECEIPT_REQUEST"]}`。
+- **不发任何外发邮件**：等价于飞书客户端"不发送"按钮——只清除本地标签，发件人不会收到任何通知。
+
+## 返回值
+
+标签已清除（无副作用）：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "message_id":             "原邮件 message ID",
+    "decline_receipt_for_id": "原邮件 message ID",
+    "declined":               false,
+    "already_cleared":        true
+  }
+}
+```
+
+本次真正移除了标签：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "message_id":             "原邮件 message ID",
+    "decline_receipt_for_id": "原邮件 message ID",
+    "declined":               true
+  }
+}
+```
+
+## 典型场景
+
+### 场景 1：用户选择不发回执
+
+```bash
+# 1. 拉信
+lark-cli mail +message --message-id msg-1 --format json | jq '.data.label_ids'
+# → ["UNREAD", "READ_RECEIPT_REQUEST"]
+
+# 2. 向用户提示：
+#    "这封来自 alice@example.com 的邮件请求已读回执。主题：《周报》。
+#     要不要回一封告诉对方你已阅读？
+#     也可以选择：不发送回执，但关闭这条提示。"
+
+# 3. 用户选了"不发送" → 
+lark-cli mail +decline-receipt --message-id msg-1
+```
+
+### 场景 2：幂等重跑
+
+```bash
+# 第一次移除标签
+lark-cli mail +decline-receipt --message-id msg-1
+# → {"declined": true}
+
+# 再跑一次 —— 不会报错，也不会再发 modify 请求
+lark-cli mail +decline-receipt --message-id msg-1
+# → {"declined": false, "already_cleared": true}
+```
+
+## 不要这样做
+
+- ❌ 替用户自动 decline —— 违反隐私规则的对称面：不回执的"沉默"也属于用户选择
+- ❌ 拿 `+decline-receipt` 当"标记已读"——它只移 `READ_RECEIPT_REQUEST` 一个标签，不改 `UNREAD`
+- ❌ 在没有 `READ_RECEIPT_REQUEST` 标签的邮件上调用 —— 虽然幂等返回 `already_cleared`，但多发一次 GET 无意义
+
+## 相关命令
+
+- `lark-cli mail +send-receipt` — 同意回执（发一封系统样式的已读回执邮件）
+- `lark-cli mail +message` — 拉单封邮件（在 `label_ids` 里检查 `READ_RECEIPT_REQUEST`）
+- `lark-cli mail +send --request-receipt` — 反向：**请求**别人回执

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

@@ -0,0 +1,123 @@
+# mail +draft-create
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+从零创建一封全新的邮件草稿。适用于已知收件人、主题和正文的场景。
+
+不要用此命令处理回复或转发场景。回复和转发应使用对应的专用 shortcut（它们默认也是创建草稿而不发送）。
+
+如需修改已有草稿，不要使用此命令，请使用 `lark-cli mail +draft-edit`。
+
+## 安全约束
+
+此命令创建草稿——**不会**发送邮件。用户可以在飞书邮件 UI 中打开草稿查看详情，确认后再进入后续操作。因此：
+
+- **不要把邮件内容以文本形式输出再请求确认。** 当用户要求"起草"/"草拟"邮件时，直接调用 `+draft-create` 在飞书邮箱中创建草稿，并引导用户去飞书邮件里打开草稿。
+- **收件人未指定时省略 `--to`** — 草稿将不带收件人创建，用户之后可自行添加。
+- **仅在用户请求确实有歧义时才需确认**（例如内容有多种可能的理解方式）。
+- **发送**草稿是单独的操作，需要用户明确确认。
+- **产出草稿时要返回打开链接** — 只要当前结果是草稿而不是直接发信，就要给用户展示草稿打开链接。当前应以创建、编辑、发送链路返回的链接信息为准，不要指望 `user_mailbox.drafts get` 返回打开链接。如果当前命令输出里有草稿链接，一并返回；如果没有链接，则静默处理，也不要伪造 URL。
+
+## 命令
+
+```bash
+# 创建 HTML 草稿（推荐）
+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 '收到，谢谢'
+
+# Dry Run（仅打印请求，不执行）
+lark-cli mail +draft-create --to alice@example.com --subject '测试' --body 'test' --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--to <emails>` | 否 | 完整收件人列表，多个用逗号分隔。支持 `Alice <alice@example.com>` 格式。省略时草稿不带收件人（之后可通过 `+draft-edit` 添加） |
+| `--subject <text>` | 是 | 草稿主题 |
+| `--body <text>` | 是 | 邮件正文。推荐使用 HTML 获得富文本排版；也支持纯文本（自动检测）。使用 `--plain-text` 可强制纯文本模式。支持 `<img src="./local.png" />` 相对路径自动解析为内嵌图片（仅支持相对路径，不支持绝对路径） |
+| `--from <email>` | 否 | 发件人邮箱地址（EML From 头）。使用别名（send_as）发信时，设为别名地址并配合 `--mailbox` 指定所属邮箱。省略时使用邮箱主地址 |
+| `--mailbox <email>` | 否 | 邮箱地址，指定草稿所属的邮箱（默认回退到 `--from`，再回退到 `me`）。当发件人（`--from`）与邮箱不同时使用，如通过别名或 send_as 地址发信。可通过 `accessible_mailboxes` 查询可用邮箱 |
+| `--cc <emails>` | 否 | 完整抄送列表，多个用逗号分隔 |
+| `--bcc <emails>` | 否 | 完整密送列表，多个用逗号分隔。与 `--event-*` 不兼容（见 `+send` 日程邀请约束） |
+| `--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` 时不设置优先级 |
+| `--request-receipt` | 否 | 请求已读回执（RFC 3798 Message Disposition Notification）。在草稿 EML 里写 `Disposition-Notification-To: <sender>` 头，发送时生效。收件人的邮件客户端可能弹出提示、自动发送或忽略——送达不保证 |
+| `--event-summary <text>` | 否 | 日程标题。设置此参数即在邮件中嵌入日程邀请。需同时设置 `--event-start` 和 `--event-end` |
+| `--event-start <time>` | 条件必填 | 日程开始时间（ISO 8601） |
+| `--event-end <time>` | 条件必填 | 日程结束时间（ISO 8601） |
+| `--event-location <text>` | 否 | 日程地点 |
+
+> **日程约束**：`--event-*` 与 `--send-time` 不可同时使用；`--to` 和 `--cc` 收件人自动成为日程参与者（ATTENDEE），`--bcc` 收件人不计入参与者。
+
+| `--format <mode>` | 否 | 输出格式：`json`（默认）/ `pretty` / `table` / `ndjson` / `csv` |
+| `--dry-run` | 否 | 仅打印请求，不执行 |
+
+## 返回值
+
+成功时：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "draft_id": "草稿ID"
+  }
+}
+```
+
+可选字段：
+
+- `reference`：草稿打开链接。**仅在当前创建链路实际返回时才会出现**。
+
+如果创建结果里带有 `reference`，应把草稿打开链接与 `draft_id` 一起返回给用户；如果当前没有链接，则静默处理。
+
+## 典型场景
+
+### 撰写新邮件 → 创建草稿 → 预览 → 发送
+
+```bash
+# 1. 创建草稿
+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>"}'
+```
+
+### 创建带内嵌图片的 HTML 草稿
+
+> **推荐方式：** 直接在 `--body` HTML 中使用 `<img src="./logo.png" />`（相对路径），系统会自动创建内嵌 MIME 部分并替换为 `cid:` 引用。仅支持相对路径（如 `./logo.png`），不支持绝对路径（如 `/tmp/logo.png`）。
+
+```bash
+# 推荐：直接使用相对路径，自动解析为内嵌图片
+lark-cli mail +draft-create \
+  --to alice@example.com \
+  --subject '通讯稿' \
+  --body '<h1>你好</h1><img src="./banner.png" />'
+
+# 高级用法：手动指定 CID（CID 为唯一标识符，可用随机十六进制字符串）
+lark-cli mail +draft-create \
+  --to alice@example.com \
+  --subject '通讯稿' \
+  --body '<h1>你好</h1><img src="cid:c7d8e9f0a1b2c3d4e5f6">' \
+  --inline '[{"cid":"c7d8e9f0a1b2c3d4e5f6","file_path":"./banner.png"}]'
+```
+
+## 相关命令
+
+- `lark-cli mail +draft-edit` — 编辑已有草稿
+- `lark-cli mail user_mailbox.drafts send` — 发送已有草稿
+- `lark-cli mail user_mailbox.drafts get` — 获取草稿内容
+- `lark-cli mail +reply` / `+reply-all` / `+forward` — 创建回复/转发草稿（默认），或加 `--confirm-send` 发送

package/dist/skills/larksuite/lark-mail/references/lark-mail-draft-edit.md

@@ -0,0 +1,400 @@
+# mail +draft-edit
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+编辑已有的邮件草稿。命令会读取当前原始 EML，应用最小化补丁，然后将更新后的草稿写回。
+
+简单元数据编辑使用直接参数：
+- `--set-subject`
+- `--set-to`
+- `--set-cc`
+- `--set-bcc`
+
+**正文编辑和其他高级操作必须通过 `--patch-file`**。没有 `--set-body` flag。
+
+### 正文编辑：两个 op 的选择
+
+正文编辑通过 `--patch-file` 传入，有两个 op 可选：
+
+| 情况 | op | 行为 |
+|------|-----|------|
+| 普通草稿（无引用区） | `set_body` | 替换用户撰写内容 |
+| 回复/转发草稿，编辑用户撰写部分 | `set_reply_body` | 替换用户撰写部分，自动重新拼接引用区。传入的 value 只包含新的用户撰写内容，**不要包含引用区** |
+| 回复/转发草稿，编辑引用区内容 | `set_body` | 传入含完整引用区的 HTML 进行替换 |
+| 用户明确要去掉引用区 | `set_body` | 不包含引用区即可 |
+
+**判断方法：** 运行 `--inspect`，若返回 `has_quoted_content: true`，说明草稿包含引用区（由 `+reply` 或 `+forward` 生成）。
+
+**关键区别：**
+- `set_reply_body` 的 value = **纯用户撰写内容**（不含引用区），引用区会自动重新拼接
+- `set_body` 的 value = 可含可不含引用区
+
+**系统托管元素自动保留（两个 op 通用）：** 签名块（`lark-mail-signature`）和超大附件卡片（`large-file-area-*`）不属于用户撰写内容，是由 `insert_signature` / `add_attachment` 等 op 管理的草稿级元素。`set_body` 和 `set_reply_body` 都会自动保留它们（普通附件 MIME part 也一样不受正文编辑影响）。若 value 里显式包含相应元素，则尊重用户的显式指定，不再自动注入。删除签名/附件请用对应的专用 op（`remove_signature` / `remove_attachment`）。
+
+### 正文编辑：plain+HTML 耦合草稿
+
+当草稿同时包含 `text/plain` 和 `text/html` 部分时，它们构成耦合对。`set_body` 和 `set_reply_body` 均更新 HTML 正文并自动重新生成纯文本摘要。此时务必传入 HTML 作为输入，因为原始主正文为 `text/html`。
+
+## 安全约束
+
+此命令会更新真实草稿。调用前须与用户确认：
+1. 草稿 ID
+2. 最终收件人范围（To/Cc/Bcc）
+3. 最终主题和正文
+4. 是否需要附件、内嵌图片或其他高级编辑
+
+## 命令
+
+```bash
+# 编辑草稿元数据（主题、收件人）
+lark-cli mail +draft-edit --draft-id <draft-id> --set-subject '更新后的主题' --set-to alice@example.com,bob@example.com
+
+# 编辑草稿正文（必须通过 patch-file）
+lark-cli mail +draft-edit --draft-id <draft-id> --patch-file ./patch.json
+
+# 查看草稿（只读）— 返回包含 has_quoted_content、attachments_summary 和 inline_summary 的投影
+lark-cli mail +draft-edit --draft-id <draft-id> --inspect
+
+# 打印补丁模板
+lark-cli mail +draft-edit --print-patch-template
+
+# Dry Run（仅打印请求，不执行）
+lark-cli mail +draft-edit --draft-id <draft-id> --set-subject '测试' --dry-run
+```
+
+## 通用参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--mailbox <email>` | 否 | 邮箱地址，指定草稿所属的邮箱（默认回退到 `--from`，再回退到 `me`）。优先于 `--from`。可通过 `accessible_mailboxes` 查询可用邮箱 |
+| `--draft-id <id>` | 是 | 目标草稿 ID。仅当单独使用 `--print-patch-template` 时可省略 |
+| `--set-subject <text>` | 否 | 用此值替换主题 |
+| `--set-to <emails>` | 否 | 用此处提供的地址替换整个 To 收件人列表 |
+| `--set-cc <emails>` | 否 | 用此处提供的地址替换整个 Cc 抄送列表 |
+| `--set-bcc <emails>` | 否 | 用此处提供的地址替换整个 Bcc 密送列表 |
+| `--set-priority <level>` | 否 | 设置邮件优先级：`high`、`normal`、`low`。设为 `normal` 会清除已有优先级 |
+| `--set-event-summary <text>` | 否 | 设置日程标题。需同时设置 `--set-event-start` 和 `--set-event-end` |
+| `--set-event-start <time>` | 条件必填 | 设置日程开始时间（ISO 8601） |
+| `--set-event-end <time>` | 条件必填 | 设置日程结束时间（ISO 8601） |
+| `--set-event-location <text>` | 否 | 设置日程地点 |
+| `--remove-event` | 否 | 移除草稿中的日程邀请。与 `--set-event-*` 互斥 |
+| `--patch-file <path>` | 否 | 所有正文编辑、增量收件人编辑、邮件头编辑、附件变更和内嵌图片变更的入口。相对路径。先运行 `--print-patch-template` 查看 JSON 结构 |
+| `--print-patch-template` | 否 | 打印 `--patch-file` 的 JSON 模板和支持的操作。建议在生成补丁文件前先运行此命令。不会读取或写入草稿 |
+| `--inspect` | 否 | 查看草稿但不修改。返回包含 `has_quoted_content`（是否有引用区）、`attachments_summary`（普通附件，含 `part_id`/`cid`/`filename`）、`large_attachments_summary`（超大附件，含 `token`/`filename`/`size_bytes`）和 `inline_summary` 的草稿投影 |
+| `--request-receipt` | 否 | 在草稿上追加 `Disposition-Notification-To: <草稿的 From 地址>` 头，请求已读回执（RFC 3798）。本质上是在 patch 中注入一个 `set_header` op；已有的 DNT 值会被覆盖。可以与其他 `--set-*` / `--patch-file` 编辑组合，也可以单独使用 |
+| `--format <mode>` | 否 | 输出格式：`json`（默认）/ `pretty` / `table` / `ndjson` / `csv` |
+| `--dry-run` | 否 | 仅打印请求，不执行 |
+
+## `--patch-file` 格式
+
+推荐工作流：
+
+1. 运行 `--inspect` 查看草稿当前状态（是否有引用区、附件等）
+2. 运行 `--print-patch-template` 查看 JSON 结构
+3. 生成符合该结构的补丁文件
+4. 运行 `--patch-file`
+
+`--patch-file` 接受项目专用的类型化补丁 JSON 格式，不是 RFC 6902 JSON Patch。
+
+顶层结构：
+
+```json
+{
+  "ops": [
+    { "op": "set_subject", "value": "更新后的主题" }
+  ],
+  "options": {
+    "rewrite_entire_draft": false,
+    "allow_protected_header_edits": false
+  }
+}
+```
+
+`options` 字段：
+
+- `rewrite_entire_draft`：默认 `false`。仅当编辑需要合成或重组正文部分（例如添加缺失的主正文部分）时设为 `true`。普通的主题、收件人、正文、附件和内嵌图片编辑保持 `false`。
+- `allow_protected_header_edits`：默认 `false`。仅当用户明确要编辑受保护的邮件头并了解可能的会话归档或投递风险时设为 `true`。正常使用保持 `false`。
+
+### 主题与正文
+
+`set_subject`
+
+```json
+{ "op": "set_subject", "value": "更新后的主题" }
+```
+
+`set_body` — 替换用户撰写内容
+
+```json
+{ "op": "set_body", "value": "<p>全新的正文内容</p>" }
+```
+
+> **注意：** `set_body` 不自动保留引用区（用户要保留引用区可以在 value 里自带，或改用 `set_reply_body`）。系统托管元素（签名、超大附件卡片、普通附件）会自动保留。
+
+`set_reply_body` — 替换用户撰写内容，自动保留引用区
+
+```json
+{ "op": "set_reply_body", "value": "<p>新的回复内容</p>" }
+```
+
+> **value 只传用户撰写的内容，不要包含引用区。** 引用区会自动从原草稿中提取并重新拼接到 value 后面。签名、超大附件卡片、普通附件也会自动保留。
+>
+> 如果用户要修改引用区里的内容（如修正引用中的错误），必须用 `set_body` 全量传入完整 HTML（含修改后的引用区）。
+>
+> 如果草稿无引用区，`set_reply_body` 行为与 `set_body` 相同。
+
+### 收件人
+
+`set_recipients`
+
+```json
+{ "op": "set_recipients", "field": "to", "addresses": [{ "address": "alice@example.com", "name": "Alice" }] }
+```
+
+`add_recipient`
+
+```json
+{ "op": "add_recipient", "field": "cc", "address": "alice@example.com", "name": "Alice" }
+```
+
+`remove_recipient`
+
+```json
+{ "op": "remove_recipient", "field": "cc", "address": "alice@example.com" }
+```
+
+### 邮件头
+
+`set_header`
+
+```json
+{ "op": "set_header", "name": "X-Custom", "value": "abc" }
+```
+
+`remove_header`
+
+```json
+{ "op": "remove_header", "name": "X-Custom" }
+```
+
+### 附件与内嵌图片
+
+**如何获取定位字段：** 不同类型附件有不同的定位字段，都从 `--inspect` 获取：
+
+- **普通附件**：`part_id` 或 `cid`（来自 `projection.attachments_summary`）
+- **超大附件**：`token`（来自 `projection.large_attachments_summary`）
+- **内嵌图片**：`part_id` 或 `cid`（来自 `projection.inline_summary`）
+
+这些值来自草稿的 MIME 结构与 header 解析，与公开 API 的附件 ID **不同**。
+
+```bash
+lark-cli mail +draft-edit --draft-id <draft_id> --inspect
+```
+
+`add_attachment` — 统一入口，不区分普通/超大。当累计附件导致 EML 总大小超过 25 MB 时，超出部分自动作为超大附件处理，单个文件上限 3 GB。
+
+```json
+{ "op": "add_attachment", "path": "./report.pdf" }
+```
+
+`remove_attachment` — 统一入口。`target` 接受 `part_id` / `cid`（普通附件）或 `token`（超大附件）。优先级：`part_id` > `cid` > `token`。
+
+```json
+{ "op": "remove_attachment", "target": { "part_id": "1.3" } }     // 普通附件，按 part_id
+{ "op": "remove_attachment", "target": { "cid": "logo" } }         // 普通附件，按 CID
+{ "op": "remove_attachment", "target": { "token": "12101..." } }  // 超大附件，按 file token
+```
+
+`add_inline`
+
+```json
+{ "op": "add_inline", "path": "./logo.png", "cid": "logo" }
+```
+
+> **推荐方式：** 直接在 `set_body`/`set_reply_body` 的 HTML 中使用 `<img src="./logo.png" />`（相对路径），系统会自动创建 MIME 内嵌部分、生成 CID 并替换为 `cid:` 引用。仅支持相对路径（如 `./logo.png`），不支持绝对路径。删除或替换 `<img>` 标签时，对应的 MIME 部分会自动清理。详见[在正文中插入内嵌图片](#在正文中插入内嵌图片)。
+>
+> `add_inline` 仅在需要精确控制 CID 命名时使用。使用时仍需在 HTML 正文中加入 `<img src="cid:...">` 引用。
+
+`replace_inline`
+
+```json
+{ "op": "replace_inline", "target": { "part_id": "1.2" }, "path": "./new-logo.png", "filename": "new-logo.png", "content_type": "image/png" }
+{ "op": "replace_inline", "target": { "cid": "logo" }, "path": "./new-logo.png" }
+```
+
+`replace_inline` 中 `filename` 和 `content_type` 为可选。省略时保留原内嵌部分的文件名和内容类型。`target` 接受 `part_id` 或 `cid`。
+
+`remove_inline`
+
+```json
+{ "op": "remove_inline", "target": { "part_id": "1.2" } }
+{ "op": "remove_inline", "target": { "cid": "logo" } }
+```
+
+`insert_signature`
+
+```json
+{ "op": "insert_signature", "signature_id": "<签名ID>" }
+```
+
+插入签名到正文末尾（引用块之前）。如已有签名则先移除再插入。运行 `mail +signature` 获取可用签名 ID。签名中的模板变量会自动替换，内联图片自动下载嵌入。
+
+`remove_signature`
+
+```json
+{ "op": "remove_signature" }
+```
+
+移除草稿中的现有签名（含签名前的空行间距）。如签名包含内联图片且正文不再引用这些图片，对应的 MIME part 也会一并移除。
+
+注意事项：
+
+- `ops` 按顺序执行
+- `target` 接受 `part_id` 或 `cid`；优先级：`part_id` > `cid`
+- **所有文件路径（`--patch-file` 及 ops 中的 `path`）必须为相对路径**
+- **正文编辑没有 flag，必须通过 `--patch-file`**
+- **`set_body` 替换用户撰写内容** — 不保留旧的引用区（用户要保留需在 value 里带上，或改用 `set_reply_body`）；自动保留签名、超大附件卡片、普通附件
+- **`set_reply_body` 替换用户撰写内容** — 自动保留引用区、签名、超大附件卡片、普通附件；value 只传用户撰写的部分，不要包含引用区/签名/附件卡片；如果用户要修改引用区内容，用 `set_body` 并在 value 里带上修改后的引用区
+- **删除签名 / 附件**不能通过 `set_body` 清空实现 — 必须用对应的专用 op：`remove_signature`、`remove_attachment`（按 `part_id` / `cid` / `token` 定位）
+- 通过 `--inspect` 返回的 `has_quoted_content` 字段可判断草稿是否包含引用区
+- 通过 `--inspect` 返回的 `has_signature` / `signature_id` 字段可判断草稿是否包含签名
+
+## 返回值
+
+成功时：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "draft_id": "草稿ID",
+    "warning": "This edit flow has no optimistic locking. If the same draft is changed concurrently, the last writer wins."
+  }
+}
+```
+
+可选字段：
+
+- `reference`：草稿打开链接。**仅在当前编辑链路实际返回时才会出现**。
+
+如果更新结果里带有 `reference`，应把草稿打开链接与 `draft_id` 一起返回给用户；如果当前没有链接，则静默处理。
+
+## 典型场景
+
+### 获取草稿 → 编辑 → 发送
+
+```bash
+# 1. 查看草稿当前状态
+lark-cli mail +draft-edit --draft-id <draft_id> --inspect
+
+# 2. 编辑草稿（元数据用 flag，正文用 patch-file）
+cat > ./patch.json << 'EOF'
+{ "ops": [{ "op": "set_body", "value": "<p>更新后的内容</p>" }] }
+EOF
+lark-cli mail +draft-edit --draft-id <draft_id> --set-subject '最终版本' --patch-file ./patch.json
+
+# 3. 发送草稿
+lark-cli mail user_mailbox.drafts send --params '{"user_mailbox_id":"me","draft_id":"<draft_id>"}'
+```
+
+### 编辑回复/转发草稿的正文
+
+回复或转发草稿的正文包含引用区（原邮件引用块）。编辑时需使用 `set_reply_body` 保留引用区。
+
+```bash
+# 1. 查看草稿，确认是否有引用区
+lark-cli mail +draft-edit --draft-id <draft_id> --inspect
+# 返回包含：
+#   has_quoted_content: true  ← 说明有引用区，应使用 set_reply_body
+#   body_html_summary: "<div>原有回复内容</div>..."
+
+# 2. 使用 set_reply_body 编辑正文（value 只传用户撰写内容，不含引用区）
+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`，引用区将被覆盖丢失。如果用户明确要去掉引用区或修改引用区内容，则应使用 `set_body`。
+
+### 从草稿中移除附件
+
+`remove_attachment` 统一处理普通附件和超大附件；根据 `--inspect` 输出选择对应的定位字段。
+
+```bash
+# 1. 查看草稿以获取附件定位信息
+lark-cli mail +draft-edit --draft-id <draft_id> --inspect
+# 返回包含：
+#   projection.attachments_summary (普通附件):
+#     [{"part_id":"1.3","filename":"report.pdf","content_type":"application/pdf"}]
+#   projection.large_attachments_summary (超大附件):
+#     [{"token":"12101...","filename":"video.mov","size_bytes":314572800}]
+
+# 2. 编写补丁文件。普通附件用 part_id（或 cid），超大附件用 token
+cat > ./patch.json << 'EOF'
+{
+  "ops": [
+    { "op": "remove_attachment", "target": { "part_id": "1.3" } },
+    { "op": "remove_attachment", "target": { "token": "12101..." } }
+  ]
+}
+EOF
+
+# 3. 应用补丁
+lark-cli mail +draft-edit --draft-id <draft_id> --patch-file ./patch.json
+```
+
+### 在正文中插入内嵌图片
+
+直接在 `set_body`/`set_reply_body` 的 HTML 中使用相对路径即可（如 `./logo.png`，不支持绝对路径）。系统会自动创建 MIME 内嵌部分并替换为 `cid:` 引用。
+
+```bash
+# 1. 查看草稿以获取当前 HTML 正文
+lark-cli mail +draft-edit --draft-id <draft_id> --inspect
+
+# 2. 编写补丁 — 直接使用相对路径（注意：回复草稿用 set_reply_body，普通草稿用 set_body）
+cat > ./patch.json << 'EOF'
+{
+  "ops": [
+    { "op": "set_body", "value": "<div>内容<img src=\"./logo.png\" /><img src=\"./photo.jpg\" /></div>" }
+  ]
+}
+EOF
+
+# 3. 应用补丁
+lark-cli mail +draft-edit --draft-id <draft_id> --patch-file ./patch.json
+```
+
+内嵌图片的增删改通过 HTML 正文自动联动：
+- **添加**：在 HTML 中写 `<img src="./image.png" />`，自动创建 MIME 部分
+- **删除**：从 HTML 中移除 `<img>` 标签，对应 MIME 部分自动清理
+- **替换**：将 `src` 改为新的相对路径，旧 MIME 部分自动移除、新部分自动创建
+
+> **高级用法：** 需要精确控制 CID 命名时，仍可使用 `add_inline` 手动添加 MIME 部分，并在 HTML 中用 `<img src="cid:your-cid">` 引用。
+
+### 使用 patch-file 进行高级编辑
+
+```bash
+# 1. 查看补丁模板
+lark-cli mail +draft-edit --print-patch-template
+
+# 2. 编写补丁文件（例如添加一个抄送并移除一个附件）
+cat > ./patch.json << 'EOF'
+{
+  "ops": [
+    { "op": "add_recipient", "field": "cc", "address": "carol@example.com", "name": "Carol" },
+    { "op": "remove_attachment", "target": { "part_id": "1.3" } }
+  ],
+  "options": {}
+}
+EOF
+
+# 3. 应用补丁
+lark-cli mail +draft-edit --draft-id <draft_id> --patch-file ./patch.json
+```
+
+## 相关命令
+
+- `lark-cli mail +draft-create` — 创建新草稿
+- `lark-cli mail user_mailbox.drafts get` — 获取草稿原始内容
+- `lark-cli mail user_mailbox.drafts send` — 发送已有草稿