@wagemule/daemon 0.1.2 → 0.1.4

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

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

@@ -0,0 +1,122 @@
+
+# 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...",
+      "date": "Fri, 21 Mar 2026 11:40:00 +0800",
+      "from": "Alice <alice@example.com>",
+      "subject": "Weekly update",
+      "labels": "INBOX,UNREAD"
+    }
+  ],
+  "count": 20,
+  "has_more": true,
+  "page_token": "list:FfccvoqPd_loLhtcRx8cx..."
+}
+```
+
+- `has_more`：是否还有下一页
+- `page_token`：传入 `--page-token` 可获取下一页；为空字符串表示已到末尾
+- token 前缀 `search:` / `list:` 标识来源 API 路径，不可混用
+
+### `table` 格式
+
+`page_token` 信息输出在 stderr，自动携带 `--query`/`--filter` 参数方便续页：
+```text
+15 message(s)
+next page: mail +triage --query '合同审批' --page-token 'search:abc123...'
+tip: use mail +message --message-id <id> to read full content
+```
+
+### 搜索分页注意事项
+
+搜索路径（使用 `--query` 或 `from`/`to`/`subject` 等 filter）的分页结果在**同一翻页链内**保持一致（无重复、无丢失）。但不同 `--max` 值发起的独立搜索可能返回不同排序，这是搜索 API 的固有行为。列表路径（仅 `folder`/`label` 筛选）无此限制。
+
+## 参考
+
+- [lark-mail](../SKILL.md) — 邮箱域总览
+- [lark-mail-watch](lark-mail-watch.md) — 实时监听新邮件

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

@@ -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) — 通用事件订阅

package/dist/skills/larksuite/lark-markdown/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: lark-markdown
+version: 1.0.0
+description: "飞书 Markdown：查看、创建、上传和编辑 Markdown 文件。当用户需要创建或编辑 Markdown 文件、读取或修改时使用。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli markdown --help"
+---
+
+# markdown (v1)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+
+## 快速决策
+
+- 用户要**上传、创建一个原生 `.md` 文件**，使用 `lark-cli markdown +create`
+- 用户要**读取 Drive 里某个 `.md` 文件内容**，使用 `lark-cli markdown +fetch`
+- 用户要**覆盖更新 Drive 里某个 `.md` 文件内容**，使用 `lark-cli markdown +overwrite`
+- 用户要把本地 Markdown **导入成在线新版文档（docx）**，不要用本 skill，改用 [`lark-drive`](../lark-drive/SKILL.md) 的 `lark-cli drive +import --type docx`
+- 用户要对 Markdown 文件做**rename / move / delete / 搜索 / 权限 / 评论**等云空间操作，不要留在本 skill，切到 [`lark-drive`](../lark-drive/SKILL.md)
+
+## 核心边界
+
+- 本 skill 处理的是 **Drive 中作为普通文件存储的 Markdown**，不是 docx 文档
+- `--name` 和本地 `--file` 文件名都必须显式带 `.md` 后缀；不满足时 shortcut 会直接报错
+- `--content` 支持：
+  - 直接传字符串
+  - `@file` 从本地文件读取内容
+  - `-` 从 stdin 读取内容
+- `--file` 只接受本地 `.md` 文件路径
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用操作的高级封装（`lark-cli markdown +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+create`](references/lark-markdown-create.md) | Create a Markdown file in Drive |
+| [`+fetch`](references/lark-markdown-fetch.md) | Fetch a Markdown file from Drive |
+| [`+overwrite`](references/lark-markdown-overwrite.md) | Overwrite an existing Markdown file in Drive |
+
+## 参考
+
+- [lark-shared](../lark-shared/SKILL.md) — 认证和全局参数
+- [lark-drive](../lark-drive/SKILL.md) — Drive 文件管理、导入 docx、move/delete/search 等

package/dist/skills/larksuite/lark-markdown/references/lark-markdown-create.md

@@ -0,0 +1,86 @@
+# markdown +create
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+在 Drive 中创建一个原生 Markdown 文件（`.md`）。
+
+## 命令
+
+```bash
+# 直接用行内内容创建
+lark-cli markdown +create \
+  --name README.md \
+  --content '# Hello'
+
+# 从本地 .md 文件创建
+lark-cli markdown +create \
+  --file ./README.md
+
+# 从本地文件读取内容，但仍走 --content
+lark-cli markdown +create \
+  --name README.md \
+  --content @./README.md
+
+# 从 stdin 读取内容
+printf '# Hello\n\nfrom stdin\n' | \
+  lark-cli markdown +create \
+    --name README.md \
+    --content -
+
+# 创建到指定文件夹
+lark-cli markdown +create \
+  --folder-token fldcn_xxx \
+  --file ./README.md
+
+# 预览底层请求
+lark-cli markdown +create \
+  --name README.md \
+  --content '# Hello' \
+  --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--folder-token` | 否 | 目标 Drive 文件夹 token；省略时创建到根目录 |
+| `--name` | 条件必填 | 文件名，**必须显式带 `.md` 后缀**；使用 `--content` 时必填；使用 `--file` 时可省略，默认取本地文件名 |
+| `--content` | 条件必填 | Markdown 内容；与 `--file` 互斥；支持直接传字符串、`@file`、`-`（stdin） |
+| `--file` | 条件必填 | 本地 `.md` 文件路径；与 `--content` 互斥 |
+
+## 关键约束
+
+- `--content` 与 `--file` 必须二选一
+- `--name` 必须带 `.md` 后缀
+- `--file` 指向的本地文件名也必须带 `.md` 后缀
+
+## 返回值
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "file_token": "boxcnxxxx",
+    "file_name": "README.md",
+    "size_bytes": 1234
+  }
+}
+```
+
+> [!IMPORTANT]
+> 如果 Markdown 文件是**以应用身份（bot）创建**的，如 `lark-cli markdown +create --as bot`，在创建成功后，CLI 会**尝试为当前 CLI 用户自动授予该文件的 `full_access`（可管理权限）**。
+>
+> 以应用身份创建时，结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
+> - `status = granted`：当前 CLI 用户已获得该文件的可管理权限
+> - `status = skipped`：本地没有可用的当前用户 `open_id`，因此不会自动授权；可提示用户先完成 `lark-cli auth login`，再让 AI / agent 继续使用应用身份（bot）授予当前用户权限
+> - `status = failed`：Markdown 文件已创建成功，但自动授权用户失败；会带上失败原因，并提示稍后重试或继续使用 bot 身份处理该文件
+>
+> `permission_grant.perm = full_access` 表示该资源已授予“可管理权限”。
+>
+> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
+
+## 参考
+
+- [lark-markdown](../SKILL.md) — Markdown 域总览
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/dist/skills/larksuite/lark-markdown/references/lark-markdown-fetch.md

@@ -0,0 +1,79 @@
+# markdown +fetch
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+读取 Drive 中原生 Markdown 文件的内容；也支持把内容保存到本地。
+
+## 命令
+
+```bash
+# 直接返回 Markdown 文本
+lark-cli markdown +fetch --file-token boxcnxxxx
+
+# 保存到本地
+lark-cli markdown +fetch \
+  --file-token boxcnxxxx \
+  --output ./README.md
+
+# 传目录时，使用远端文件名保存到该目录下
+lark-cli markdown +fetch \
+  --file-token boxcnxxxx \
+  --output ./downloads/
+
+# 覆盖已存在文件
+lark-cli markdown +fetch \
+  --file-token boxcnxxxx \
+  --output ./README.md \
+  --overwrite
+
+# 预览底层请求
+lark-cli markdown +fetch \
+  --file-token boxcnxxxx \
+  --output ./README.md \
+  --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | 目标 Markdown 文件 token |
+| `--output` | 否 | 本地保存路径；既可传具体文件名，也可传目录路径。传目录时使用远端文件名保存；省略时直接返回 Markdown 内容 |
+| `--overwrite` | 否 | 覆盖已存在的本地输出文件；仅在传入 `--output` 时生效 |
+
+## 返回值
+
+不传 `--output`：
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "file_token": "boxcnxxxx",
+    "file_name": "README.md",
+    "content": "# Hello\n",
+    "size_bytes": 8
+  }
+}
+```
+
+传入 `--output`：
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "file_token": "boxcnxxxx",
+    "file_name": "README.md",
+    "saved_path": "/abs/path/README.md",
+    "size_bytes": 8
+  }
+}
+```
+
+## 参考
+
+- [lark-markdown](../SKILL.md) — Markdown 域总览
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/dist/skills/larksuite/lark-markdown/references/lark-markdown-overwrite.md

@@ -0,0 +1,85 @@
+# markdown +overwrite
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+覆盖更新 Drive 中已有的原生 Markdown 文件，并返回覆盖后的新版本号。
+
+## 命令
+
+```bash
+# 用行内内容覆盖
+lark-cli markdown +overwrite \
+  --file-token boxcnxxxx \
+  --content '# Updated'
+
+# 用本地 .md 文件覆盖
+lark-cli markdown +overwrite \
+  --file-token boxcnxxxx \
+  --file ./README.md
+
+# 覆盖内容时顺便显式指定新文件名
+lark-cli markdown +overwrite \
+  --file-token boxcnxxxx \
+  --name NEW-README.md \
+  --content '# Updated'
+
+# 用 --content 从本地文件读取
+lark-cli markdown +overwrite \
+  --file-token boxcnxxxx \
+  --content @./README.md
+
+# 用 stdin 覆盖
+printf '# Updated\n' | \
+  lark-cli markdown +overwrite \
+    --file-token boxcnxxxx \
+    --content -
+
+# 预览底层请求
+lark-cli markdown +overwrite \
+  --file-token boxcnxxxx \
+  --content '# Updated' \
+  --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | 目标 Markdown 文件 token |
+| `--name` | 否 | 显式指定覆盖后的文件名；必须带 `.md` 后缀。传入时优先使用它 |
+| `--content` | 条件必填 | 新 Markdown 内容；与 `--file` 互斥；支持直接传字符串、`@file`、`-`（stdin） |
+| `--file` | 条件必填 | 本地 `.md` 文件路径；与 `--content` 互斥 |
+
+## 关键约束
+
+- `--content` 与 `--file` 必须二选一
+- 如果传了 `--name`，直接使用它作为覆盖后的文件名
+- 如果没传 `--name` 且使用 `--content`，默认保留远端原文件名
+- 如果没传 `--name` 且使用 `--file`，默认使用本地文件名
+- `--file` 指向的本地文件名必须带 `.md` 后缀
+- 覆盖成功后 **必须** 返回 `version`
+
+## 返回值
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "file_token": "boxcnxxxx",
+    "file_name": "README.md",
+    "version": "7633658129540910621",
+    "size_bytes": 2048
+  }
+}
+```
+
+其中：
+
+- `version` 是覆盖写入后的新版本号
+- `size_bytes` 是本次覆盖后的内容大小
+
+## 参考
+
+- [lark-markdown](../SKILL.md) — Markdown 域总览
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数