Lark Markdown

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-cli drive +version-history
• 用户要把本地 Markdown 导入成在线新版文档（docx），不要用本 skill，改用 `lark-drive` 的 lark-cli drive +import --type docx
• 用户要对 Markdown 文件做rename / move / delete / 搜索 / 权限 / 评论等云空间（云盘/云存储）操作，不要留在本 skill，切到 `lark-drive`
• 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 的转义：

# 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 的操作优先使用。

参考

• lark-shared — 认证和全局参数
• lark-drive — Drive 文件管理、导入 docx、move/delete/search 等

markdown +create

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

在 Drive 中创建一个原生 Markdown 文件（.md），支持创建到普通 Drive 文件夹或 Wiki 节点下。

命令

# 直接用行内内容创建
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

参数

关键约束

• --content 与 --file 必须二选一
• --folder-token 与 --wiki-token 互斥
• --name 必须带 .md 后缀
• --file 指向的本地文件名也必须带 .md 后缀
• 传 --wiki-token 时，返回值中不会附带 /file/<token> URL，因为 wiki 承载文件没有稳定的独立 file URL

返回值

{
  "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 — Markdown 域总览
• lark-shared — 认证和全局参数

markdown +diff

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

比较 Drive 中原生 Markdown 的两个历史版本，或比较远端 Markdown 与本地 .md 草稿。需要历史版本号时，先用 `drive +version-history` 获取 version，不要使用 tag。

命令

# 比较两个远端版本
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 存在时：
• 省略 --from-version = 比较“远端最新版本 vs 本地文件”
• 传入 --from-version = 比较“指定远端版本 vs 本地文件”
• --to-version 只能用于“远端版本 vs 远端版本”，不能与 --file 同时出现
• --format pretty 输出带颜色的 unified diff；--format json 返回结构化摘要和完整 diff 文本
• 无差异时：
• json 输出里 changed=false
• pretty 输出固定为 No differences.

返回值

{
  "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..."
  }
}

完整字段说明：

标签字段补充：

• 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 子字段说明：

补充说明：

• hunks 适合 agent 或脚本快速定位变更范围；完整逐行内容仍以 diff 字段为准
• changed=false 时，hunks 通常为空数组，diff 通常为空字符串；如果使用 --format pretty，终端输出会是 No differences.

远端 vs 本地时会额外返回：

{
  "local_file": "./draft.md"
}

• local_file
• 只有传了 --file、进入“远端 vs 本地”模式时才会返回
• 值就是本次命令实际比较的本地 Markdown 路径，也就是你传给 --file 的那个路径
• 它表示“目标侧本地文件”，不是临时下载文件，也不是远端文件名
• 如果没有这个字段，说明本次是“远端版本 vs 远端版本”

参考

• lark-markdown — Markdown 域总览
• lark-drive-version-history — 获取可用于 diff 的历史版本号
• lark-shared — 认证和全局参数

markdown +fetch

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

读取 Drive 中原生 Markdown 文件的内容；也支持把内容保存到本地。

命令

# 直接返回 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

参数

返回值

不传 --output：

{
  "ok": true,
  "identity": "user",
  "data": {
    "file_token": "boxcnxxxx",
    "file_name": "README.md",
    "content": "# Hello\n",
    "size_bytes": 8
  }
}

传入 --output：

{
  "ok": true,
  "identity": "user",
  "data": {
    "file_token": "boxcnxxxx",
    "file_name": "README.md",
    "saved_path": "/abs/path/README.md",
    "size_bytes": 8
  }
}

参考

• lark-markdown — Markdown 域总览
• lark-shared — 认证和全局参数

markdown +overwrite

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

覆盖更新 Drive 中已有的原生 Markdown 文件，并返回覆盖后的新版本号。

命令

# 用行内内容覆盖
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

参数

关键约束

• --content 与 --file 必须二选一
• 如果传了 --name，直接使用它作为覆盖后的文件名
• 如果没传 --name 且使用 --content，默认保留远端原文件名
• 如果没传 --name 且使用 --file，默认使用本地文件名
• --file 指向的本地文件名必须带 .md 后缀
• 覆盖成功后 必须 返回 version

返回值

{
  "ok": true,
  "identity": "user",
  "data": {
    "file_token": "boxcnxxxx",
    "file_name": "README.md",
    "version": "7633658129540910621",
    "size_bytes": 2048
  }
}

其中：

• version 是覆盖写入后的新版本号
• size_bytes 是本次覆盖后的内容大小

参考

• lark-markdown — Markdown 域总览
• lark-shared — 认证和全局参数

markdown +patch

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

对 Drive 中已有的原生 Markdown 文件做局部文本替换，并返回是否实际写入了新版本。

命令

# 字面量替换
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

参数

关键约束

• 当前只支持单组 --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

# 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（大文件分片上传）

返回值

命中并写入新版本：

{
  "ok": true,
  "identity": "user",
  "data": {
    "updated": true,
    "mode": "literal",
    "match_count": 1,
    "version": "7639217385152646325",
    "size_bytes_before": 39,
    "size_bytes_after": 41
  }
}

未命中：

{
  "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`
• 需要多组 patch 一次完成：当前不支持，改为多次调用 markdown +patch
• 需要真正原子更新：当前能力不提供

参考

• lark-markdown — Markdown 域总览
• lark-shared — 认证和全局参数