From 2f4e2c301907669d84a4c4a8ddbf1e4247bffefc Mon Sep 17 00:00:00 2001
From: fangshuyu-768 <shuyufang768@outlook.com>
Date: Fri, 5 Jun 2026 12:34:56 +0800
Subject: [PATCH] docs: improve lark-markdown skill guidance (#1279)

---
 skills/lark-markdown/SKILL.md                 | 18 ++++++++++---
 .../references/lark-markdown-patch.md         | 27 ++++++++++++++++++-
 2 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/skills/lark-markdown/SKILL.md b/skills/lark-markdown/SKILL.md
index 881d1e4f..d9f0779e 100644
--- a/skills/lark-markdown/SKILL.md
+++ b/skills/lark-markdown/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: lark-markdown
-version: 1.2.0
-description: "飞书 Markdown：查看、创建、上传、编辑和比较 Markdown 文件。当用户需要创建或编辑 Markdown 文件、读取、修改、局部 patch 或比较差异时使用。"
+version: 1.2.1
+description: "飞书 Markdown：查看、创建、上传、编辑和比较 Markdown 文件。当用户需要创建或编辑 Markdown 文件、读取、修改、局部 patch 或比较差异时使用。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -14,6 +14,8 @@ metadata:
 
 ## 快速决策
 
+- 身份：Markdown 文件通常属于用户云空间资源，优先使用 `--as user`。如为自动化场景，或应用已创建并持有目标文件权限，可按场景使用 `--as bot`。首次以 `user` 身份访问前执行 `lark-cli auth login`
+
 - 用户要**上传、创建一个原生 `.md` 文件**，使用 `lark-cli markdown +create`
 - 用户要**比较原生 `.md` 文件的历史版本差异**，或比较远端 Markdown 与本地草稿，使用 `lark-cli markdown +diff`
 - 用户要**读取 Drive 里某个 `.md` 文件内容**，使用 `lark-cli markdown +fetch`
@@ -34,9 +36,19 @@ metadata:
 - `markdown +patch` 的内部语义是：**先完整下载 Markdown，再本地替换，再整文件覆盖上传**
 - `markdown +patch` 不是服务端原子 patch；它是 CLI 侧编排出来的局部更新能力
 - `markdown +patch` 当前只支持**单组** `--pattern` / `--content`
-- `markdown +patch` 替换后的最终内容**不能为空**；如果替换后整篇 Markdown 变成空字符串，CLI 会直接报错，不会上传空文件
+- `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 的操作优先使用。
diff --git a/skills/lark-markdown/references/lark-markdown-patch.md b/skills/lark-markdown/references/lark-markdown-patch.md
index 5a618cc5..7c6c28e7 100644
--- a/skills/lark-markdown/references/lark-markdown-patch.md
+++ b/skills/lark-markdown/references/lark-markdown-patch.md
@@ -20,6 +20,13 @@ lark-cli markdown +patch \
   --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 \
@@ -63,9 +70,27 @@ lark-cli markdown +patch \
 - `--content` 必须显式传入，但允许为空字符串
 - 未加 `--regex` 时，行为等价于对整份 Markdown 文本执行 `strings.ReplaceAll`
 - 加了 `--regex` 时，行为等价于对整份 Markdown 文本执行 RE2 全量替换；`--content` 里的 `$1`、`${name}` 会按 Go regexp replacement template 解释，字面 `$` 请写成 `$$`
-- 替换后的最终 Markdown 不能为空；如果 patch 结果是空字符串，CLI 会直接报错，不会上传空文件
+- 替换后的最终 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**