@yandy0725/pi-lark 0.1.0

package/skills/lark-markdown/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: lark-markdown
+version: 1.2.1
+description: "飞书 Markdown：查看、创建、上传、编辑和比较 Markdown 文件。当用户需要创建或编辑 Markdown 文件、读取、修改、局部 patch 或比较差异时使用。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli markdown --help"
+---
+
+# markdown (v1)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+
+## 快速决策
+
+- 身份：Markdown 文件通常属于用户云空间资源，优先使用 `--as user`。如为自动化场景，或应用已创建并持有目标文件权限，可按场景使用 `--as bot`。首次以 `user` 身份访问前执行 `lark-cli auth login`
+- `markdown +create` / `+overwrite` 失败时，先判断是不是身份和权限问题：`bot` 更常见的是 app scope 或目标目录 ACL，`user` 更常见的是用户授权或用户 ACL；不要不加判断地来回切身份重试。
+
+- 用户要**上传、创建一个原生 `.md` 文件**，使用 `lark-cli markdown +create`
+- 用户要**比较原生 `.md` 文件的历史版本差异**，或比较远端 Markdown 与本地草稿，使用 `lark-cli markdown +diff`
+- 用户要**读取 Drive 里某个 `.md` 文件内容**，使用 `lark-cli markdown +fetch`
+- 用户要对 Markdown 文件做**局部文本替换 / 正则替换**，优先使用 `lark-cli markdown +patch`
+- 用户要**覆盖更新 Drive 里某个 `.md` 文件内容**，使用 `lark-cli markdown +overwrite`
+- 用户要先拿 Markdown 文件的历史版本号，再做比较/下载/回滚，先用 [`lark-drive`](../lark-drive/SKILL.md) 的 `lark-cli drive +version-history`
+- 用户要把本地 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)
+- `markdown +create` / `+overwrite` 命中 `missing scope`、`permission denied`、`not found`、`version limit` 时，默认停止重试并按报错 hint 处理；只有 `rate limit` 或临时网络错误才做有限重试。
+
+## 核心边界
+
+- 本 skill 处理的是 **Drive 中作为普通文件存储的 Markdown**，不是 docx 文档
+- `--name` 和本地 `--file` 文件名都必须显式带 `.md` 后缀；不满足时 shortcut 会直接报错
+- `--content` 支持：
+  - 直接传字符串
+  - `@file` 从本地文件读取内容
+  - `-` 从 stdin 读取内容
+- `markdown +patch` 的内部语义是：**先完整下载 Markdown，再本地替换，再整文件覆盖上传**
+- `markdown +patch` 不是服务端原子 patch；它是 CLI 侧编排出来的局部更新能力
+- `markdown +patch` 当前只支持**单组** `--pattern` / `--content`
+- `markdown +patch` 替换后的最终内容**不能为空**；CLI 会拒绝上传空文件，因为 Drive 不支持零字节 Markdown，且空文件通常是误操作
+- `--file` 只接受本地 `.md` 文件路径
+
+正则替换时要特别注意 `--pattern` 的转义：
+
+```bash
+# BAD: 未转义正则特殊字符，可能匹配到错误位置
+lark-cli markdown +patch --file-token boxcnxxxx --regex --pattern "version (1.0)" --content "version (2.0)"
+
+# GOOD: 显式转义括号和点号
+lark-cli markdown +patch --file-token boxcnxxxx --regex --pattern "version \\(1\\.0\\)" --content "version (2.0)"
+```
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用操作的高级封装（`lark-cli markdown +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+create`](references/lark-markdown-create.md) | Create a Markdown file in Drive |
+| [`+diff`](references/lark-markdown-diff.md) | Compare two remote Markdown versions, or compare remote Markdown against a local file |
+| [`+fetch`](references/lark-markdown-fetch.md) | Fetch a Markdown file from Drive |
+| [`+patch`](references/lark-markdown-patch.md) | Patch a Markdown file in Drive via fetch-local-replace-overwrite |
+| [`+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/skills/lark-markdown/references/lark-markdown-create.md

@@ -0,0 +1,94 @@
+# markdown +create
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+在 Drive 中创建一个原生 Markdown 文件（`.md`），支持创建到普通 Drive 文件夹或 Wiki 节点下。
+
+## 命令
+
+```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
+
+# 创建到指定 wiki 节点
+lark-cli markdown +create \
+  --wiki-token wikcn_xxx \
+  --file ./README.md
+
+# 预览底层请求
+lark-cli markdown +create \
+  --name README.md \
+  --content '# Hello' \
+  --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--folder-token` | 否 | 目标 Drive 文件夹 token；与 `--wiki-token` 互斥；省略时创建到根目录 |
+| `--wiki-token` | 否 | 目标 wiki 节点 token；与 `--folder-token` 互斥；传入后自动映射为 `parent_type=wiki` |
+| `--name` | 条件必填 | 文件名，**必须显式带 `.md` 后缀**；使用 `--content` 时必填；使用 `--file` 时可省略，默认取本地文件名 |
+| `--content` | 条件必填 | Markdown 内容；与 `--file` 互斥；支持直接传字符串、`@file`、`-`（stdin） |
+| `--file` | 条件必填 | 本地 `.md` 文件路径；与 `--content` 互斥 |
+
+## 关键约束
+
+- `--content` 与 `--file` 必须二选一
+- `--folder-token` 与 `--wiki-token` 互斥
+- `--name` 必须带 `.md` 后缀
+- `--file` 指向的本地文件名也必须带 `.md` 后缀
+- 传 `--wiki-token` 时，返回值中不会附带 `/file/<token>` URL，因为 wiki 承载文件没有稳定的独立 file URL
+
+## 返回值
+
+```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/skills/lark-markdown/references/lark-markdown-diff.md

@@ -0,0 +1,156 @@
+# markdown +diff
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+比较 Drive 中原生 Markdown 的两个历史版本，或比较远端 Markdown 与本地 `.md` 草稿。需要历史版本号时，先用 [`drive +version-history`](../../lark-drive/references/lark-drive-version-history.md) 获取 `version`，不要使用 `tag`。
+
+## 命令
+
+```bash
+# 比较两个远端版本
+lark-cli markdown +diff \
+  --file-token boxcnxxxx \
+  --from-version 7633658129540910621 \
+  --to-version 7633658129540910628
+
+# 比较历史版本与远端最新版本
+lark-cli markdown +diff \
+  --file-token boxcnxxxx \
+  --from-version 7633658129540910621
+
+# 比较远端最新版本与本地草稿
+lark-cli markdown +diff \
+  --file-token boxcnxxxx \
+  --file ./draft.md \
+  --format pretty
+
+# 比较指定远端版本与本地草稿
+lark-cli markdown +diff \
+  --file-token boxcnxxxx \
+  --from-version 7633658129540910621 \
+  --file ./draft.md
+
+# 预览底层请求
+lark-cli markdown +diff \
+  --file-token boxcnxxxx \
+  --from-version 7633658129540910621 \
+  --to-version 7633658129540910628 \
+  --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | 目标 Markdown 文件 token |
+| `--from-version` | 否 | 基准远端版本；不传 `--file` 时必填，传 `--file` 时省略表示“远端最新 vs 本地文件” |
+| `--to-version` | 否 | 目标远端版本；要求同时传 `--from-version`，且不能与 `--file` 一起使用。省略时表示远端最新版本 |
+| `--file` | 否 | 本地 `.md` 文件路径；传入后进入“远端 vs 本地”比较模式 |
+| `--context-lines` | 否 | unified diff 每个 hunk 前后保留的上下文行数，默认 `3` |
+| `--format` | 否 | 仅支持 `json`（默认）和 `pretty` |
+
+## 关键行为
+
+- `--file` 存在时：
+  - 省略 `--from-version` = 比较“远端最新版本 vs 本地文件”
+  - 传入 `--from-version` = 比较“指定远端版本 vs 本地文件”
+- `--to-version` 只能用于“远端版本 vs 远端版本”，不能与 `--file` 同时出现
+- `--format pretty` 输出带颜色的 unified diff；`--format json` 返回结构化摘要和完整 diff 文本
+- 无差异时：
+  - `json` 输出里 `changed=false`
+  - `pretty` 输出固定为 `No differences.`
+
+## 返回值
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "changed": true,
+    "mode": "remote_vs_remote",
+    "file_token": "boxcnxxxx",
+    "from_version": "7633658129540910621",
+    "to_version": "7633658129540910628",
+    "from_label": "a/boxcnxxxx@version:7633658129540910621",
+    "to_label": "b/boxcnxxxx@version:7633658129540910628",
+    "added_lines": 3,
+    "deleted_lines": 2,
+    "context_lines": 3,
+    "hunks": [
+      {
+        "header": "@@ -1,6 +1,7 @@",
+        "old_start": 1,
+        "old_lines": 6,
+        "new_start": 1,
+        "new_lines": 7
+      }
+    ],
+    "diff": "--- a/boxcnxxxx@version:7633658129540910621\n+++ b/boxcnxxxx@version:7633658129540910628\n@@ -1,2 +1,2 @@\n..."
+  }
+}
+```
+
+完整字段说明：
+
+| 字段 | 层级 | 含义 |
+|------|------|------|
+| `ok` | 顶层 | CLI 通用成功标记；`true` 表示命令执行成功 |
+| `identity` | 顶层 | 本次执行使用的身份，通常是 `user` 或 `bot` |
+| `data` | 顶层 | 本次 diff 的业务结果对象 |
+| `changed` | `data` | 是否存在差异；`true` 表示两侧内容不同，`false` 表示完全一致 |
+| `mode` | `data` | 比较模式；`remote_vs_remote` = 远端对远端，`remote_vs_local` = 远端对本地 |
+| `file_token` | `data` | 被比较的远端 Markdown 文件 token |
+| `from_version` | `data` | 基准远端版本号；远端最新 vs 本地时可能为空字符串 |
+| `to_version` | `data` | 目标远端版本号；当目标侧是远端最新版本或本地文件时通常为空字符串 |
+| `from_label` | `data` | unified diff 基准侧标签名，会直接出现在 `diff` 文本的 `---` 头部 |
+| `to_label` | `data` | unified diff 目标侧标签名，会直接出现在 `diff` 文本的 `+++` 头部 |
+| `added_lines` | `data` | 新增行数统计 |
+| `deleted_lines` | `data` | 删除行数统计 |
+| `context_lines` | `data` | 每个 hunk 前后保留的上下文行数，对应传入的 `--context-lines` |
+| `hunks` | `data` | 结构化的变更块摘要数组；每个元素对应 patch 里的一个 `@@ ... @@` 段 |
+| `diff` | `data` | 完整 unified diff 文本；最适合直接阅读或保存 |
+| `local_file` | `data` | 仅在 `remote_vs_local` 模式下出现；值就是传给 `--file` 的本地 Markdown 路径 |
+
+标签字段补充：
+
+- `from_label` / `to_label` 只用于标识 diff 两侧，不代表额外 API 字段
+- `from_label` 表示基准侧，`to_label` 表示目标侧
+- 远端版本通常形如 `a/<file_token>@version:<version>`、`b/<file_token>@version:<version>`
+- 当目标侧是远端最新版本时，`to_label` 形如 `b/<file_token>@latest`
+- 当目标侧是本地文件时，`to_label` 形如 `b/./draft.md`
+
+`hunks` 子字段说明：
+
+| 字段 | 含义 |
+|------|------|
+| `header` | 原始 hunk 头，例如 `@@ -3,1 +3,1 @@` |
+| `old_start` | 旧内容从第几行开始 |
+| `old_lines` | 旧内容这段覆盖多少行 |
+| `new_start` | 新内容从第几行开始 |
+| `new_lines` | 新内容这段覆盖多少行 |
+
+补充说明：
+
+- `hunks` 适合 agent 或脚本快速定位变更范围；完整逐行内容仍以 `diff` 字段为准
+- `changed=false` 时，`hunks` 通常为空数组，`diff` 通常为空字符串；如果使用 `--format pretty`，终端输出会是 `No differences.`
+
+远端 vs 本地时会额外返回：
+
+```json
+{
+  "local_file": "./draft.md"
+}
+```
+
+- `local_file`
+  - 只有传了 `--file`、进入“远端 vs 本地”模式时才会返回
+  - 值就是本次命令实际比较的本地 Markdown 路径，也就是你传给 `--file` 的那个路径
+  - 它表示“目标侧本地文件”，不是临时下载文件，也不是远端文件名
+  - 如果没有这个字段，说明本次是“远端版本 vs 远端版本”
+
+## 参考
+
+- [lark-markdown](../SKILL.md) — Markdown 域总览
+- [lark-drive-version-history](../../lark-drive/references/lark-drive-version-history.md) — 获取可用于 diff 的历史版本号
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/skills/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/skills/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) — 认证和全局参数

package/skills/lark-markdown/references/lark-markdown-patch.md

@@ -0,0 +1,160 @@
+# markdown +patch
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+对 Drive 中已有的原生 Markdown 文件做局部文本替换，并返回是否实际写入了新版本。
+
+## 命令
+
+```bash
+# 字面量替换
+lark-cli markdown +patch \
+  --file-token boxcnxxxx \
+  --pattern 'hello markdown' \
+  --content 'hello patched'
+
+# 正则替换（RE2）
+lark-cli markdown +patch \
+  --file-token boxcnxxxx \
+  --regex \
+  --pattern 'hello (.+)' \
+  --content 'hi $1'
+
+# 正则 pattern 含特殊字符时要显式转义
+lark-cli markdown +patch \
+  --file-token boxcnxxxx \
+  --regex \
+  --pattern 'version \\(1\\.0\\)' \
+  --content 'version (2.0)'
+
+# 删除匹配内容
+lark-cli markdown +patch \
+  --file-token boxcnxxxx \
+  --pattern ' debug' \
+  --content ''
+
+# --pattern / --content 也支持 @file
+lark-cli markdown +patch \
+  --file-token boxcnxxxx \
+  --pattern @./pattern.txt \
+  --content @./replacement.md
+
+# 从 stdin 读取 replacement
+printf 'hi patched\n' | \
+  lark-cli markdown +patch \
+    --file-token boxcnxxxx \
+    --pattern 'hello markdown' \
+    --content -
+
+# 预览底层编排
+lark-cli markdown +patch \
+  --file-token boxcnxxxx \
+  --pattern 'hello markdown' \
+  --content 'hello patched' \
+  --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | 目标 Markdown 文件 token |
+| `--pattern` | 是 | 要匹配的文本；默认按字面量处理；支持直接传字符串、`@file`、`-`（stdin） |
+| `--content` | 是 | 替换后的内容；支持直接传字符串、`@file`、`-`（stdin）；允许空字符串 `''`，表示删除匹配内容 |
+| `--regex` | 否 | 将 `--pattern` 按 Go RE2 正则解释；`--content` 支持 `$1` 这类分组替换；如果需要字面 `$`，请写成 `$$` |
+
+## 关键约束
+
+- 当前只支持**单组** `--pattern` / `--content`
+- `--pattern` 必须显式传入且不能为空字符串
+- `--content` 必须显式传入，但允许为空字符串
+- 未加 `--regex` 时，行为等价于对整份 Markdown 文本执行 `strings.ReplaceAll`
+- 加了 `--regex` 时，行为等价于对整份 Markdown 文本执行 RE2 全量替换；`--content` 里的 `$1`、`${name}` 会按 Go regexp replacement template 解释，字面 `$` 请写成 `$$`
+- 替换后的最终 Markdown 不能为空；如果 patch 结果是空字符串，CLI 会直接报错，不会上传空文件，因为 Drive 不支持零字节 Markdown，且空文件通常是误操作
+- `0` 命中时命令仍然成功返回，但不会上传新版本
+
+## Good / Bad
+
+```bash
+# BAD: pattern 含正则特殊字符但未转义，容易匹配错误位置
+lark-cli markdown +patch \
+  --file-token boxcnxxxx \
+  --regex \
+  --pattern 'version (1.0)' \
+  --content 'version (2.0)'
+
+# GOOD: 显式转义括号和点号
+lark-cli markdown +patch \
+  --file-token boxcnxxxx \
+  --regex \
+  --pattern 'version \\(1\\.0\\)' \
+  --content 'version (2.0)'
+```
+
+## 实现边界
+
+- 该命令的内部语义是：**download -> local replace -> overwrite upload**
+- 它不是服务端原子 patch；如果有人在你下载后、上传前更新了同一文件，本次 patch 仍可能覆盖那次中间修改
+- 它不会返回详细匹配位置，只返回命中数量
+- `--dry-run` 会同时展示两种可能的上传路径：`upload_all`（小文件）和 `upload_prepare/upload_part/upload_finish`（大文件分片上传）
+
+## 返回值
+
+命中并写入新版本：
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "updated": true,
+    "mode": "literal",
+    "match_count": 1,
+    "version": "7639217385152646325",
+    "size_bytes_before": 39,
+    "size_bytes_after": 41
+  }
+}
+```
+
+未命中：
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "updated": false,
+    "mode": "literal",
+    "match_count": 0,
+    "version": "",
+    "size_bytes_before": 41,
+    "size_bytes_after": 41
+  }
+}
+```
+
+其中：
+
+- `updated` 表示本次是否真的上传了新版本
+- `mode` 为 `literal` 或 `regex`
+- `match_count` 是匹配次数
+- `version` 只有在 `updated=true` 时才会有值
+- `size_bytes_before` / `size_bytes_after` 分别是替换前后的 Markdown 大小
+
+## 适用场景
+
+- 只需要替换一小段 Markdown 文本，而不想自己手动 `fetch -> edit -> overwrite`
+- 需要基于正则做简单批量替换
+- 需要判断“这次是否真的改到了内容”
+
+## 不适用场景
+
+- 需要 rename / move / delete / permission / comment 管理：切到 [`lark-drive`](../../lark-drive/SKILL.md)
+- 需要多组 patch 一次完成：当前不支持，改为多次调用 `markdown +patch`
+- 需要真正原子更新：当前能力不提供
+
+## 参考
+
+- [lark-markdown](../SKILL.md) — Markdown 域总览
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数