lark-markdown :插件完整指南,功能、安装与实战应用
lark-markdown :插件完整指南,功能、安装与实战应用


lark-markdown 是飞书官方 CLI（lark-cli）内置的一个 AI Agent Skill，专门用于管理飞书云盘（Drive）中的原生 Markdown 文件。它让你可以通过命令行直接创建、读取、修改、打补丁和比较飞书云盘里的 .md 文件，全程无需打开飞书网页或客户端。

需要特别说明的是，lark-markdown 处理的是 Drive 中作为普通文件存储的 Markdown，不是飞书在线文档（docx）。如果你想把本地 Markdown 导入成飞书在线文档，那是另一个 Skill（lark-drive）的事情。

一、lark-markdown 有哪些核心功能？

lark-markdown 提供了五个核心操作命令，覆盖了 Markdown 文件在云盘中的完整生命周期管理。

创建文件（+create）

在飞书云盘的普通文件夹或 Wiki 节点下创建一个原生的 .md 文件。创建时可以直接传入内容字符串，也可以从本地文件读取内容上传。

读取文件（+fetch）

读取飞书云盘里某个 .md 文件的内容。支持直接输出到终端，也可以保存到本地文件。

覆盖更新（+overwrite）

用新内容或本地文件完整覆盖云盘里已有的 .md 文件。这是一个全量替换操作，会直接覆盖原有内容。

局部补丁（+patch）

对云盘中的 Markdown 文件做局部文本替换，支持字面量替换和 RE2 正则替换。它的内部逻辑是：先把文件完整下载到本地，完成替换后再整文件覆盖上传。当前版本只支持单组 --pattern / --content 替换。替换后的内容不能为空，否则 CLI 会直接报错。

版本比较（+diff）

比较同一个 Markdown 文件的两个历史版本差异，或者比较远端文件与本地草稿的差异。在覆盖重要文件之前先用 diff 预览差异，是个很好的习惯。

二、怎么安装 lark-markdown？

方式一：通过 npx 命令安装（推荐）

在项目根目录执行以下命令：

bash
npx skills add https://github.com/larksuite/cli --skill lark-markdown

安装过程中 CLI 会提示你选择目标 AI 编程环境（Claude Code、Cursor、Windsurf、Codex 等），选择你正在用的就行。安装完成后，技能会自动配置到对应的环境中。

方式二：通过 skillstore 安装

bash
npx skillstore add larksuite/lark-markdown

前置条件

使用 lark-markdown 之前，需要先完成飞书 CLI 的认证配置。首次使用前执行：

bash
lark-cli auth login

Markdown 文件通常属于用户云空间资源，优先使用 --as user 身份操作。如果是自动化场景，可以使用 --as bot，前提是应用已创建并持有目标文件权限。

三、lark-markdown 适合谁用？用在什么场景？

场景一：开发者的文档版本管理

技术团队习惯用 Markdown 写文档、写 README、写技术方案。把这些文档放到飞书云盘里统一管理，用 lark-markdown 通过命令行进行版本控制——创建、覆盖、比较差异，全部在终端完成，不用在飞书界面里点点点。

场景二：AI 助手的文档自动化

lark-markdown 本质上是一个 AI Agent Skill，可以被 Claude Code、Codex 等 AI 助手直接调用。你可以对 AI 说“帮我把这份技术方案上传到飞书云盘”，AI 会自动调用 lark-markdown 完成创建和上传。

场景三：文档的批量更新与维护

当需要批量更新云盘中的多个 Markdown 文档时（比如统一修改版本号、替换过期的链接地址），用 +patch 配合脚本可以一次性完成，比手动打开每个文档编辑高效得多。

场景四：文档审阅前的差异对比

在覆盖更新一个重要的 Markdown 文档之前，先用 +diff 比较本地草稿和远端版本的差异，确认无误后再执行覆盖。这个流程对团队协作场景尤其有用。

四、实战案例：用 lark-markdown 完成一次文档更新

假设你的团队在飞书云盘里维护了一份技术文档 README.md，现在需要更新内容。

第一步，获取文件 Token

在飞书云盘中打开目标文件，从 URL 中获取 file-token（通常是一串以 boxcn 开头的字符）。

第二步，读取当前内容

bash
lark-cli markdown +fetch --file-token boxcnxxxxxx

确认当前内容后，决定如何更新。

第三步，更新内容

方式一：用本地文件覆盖

bash
lark-cli markdown +overwrite --file-token boxcnxxxxxx --file ./README.md

方式二：局部替换（把旧版本号换成新版本号）

bash
lark-cli markdown +patch --file-token boxcnxxxxxx --pattern "v1.0.0" --content "v1.1.0"

第四步（可选）：比较差异再覆盖

覆盖之前先比较一下本地草稿和远端版本的差异：

bash
lark-cli markdown +diff --file-token boxcnxxxxxx --local ./README.md

确认差异符合预期后，再执行覆盖操作。

整个过程从读取到更新，只需要几条命令，全程在终端完成。

五、lark-markdown 不做什么？

lark-markdown 的职责边界非常清晰，以下几点是它明确不负责的：

  • 不负责将 Markdown 导入为飞书在线文档（docx） —— 那是 lark-drive +import --type docx 的事。

  • 不负责文件搜索、移动、删除 —— 这些云空间管理操作请使用 lark-drive。

  • 不负责权限管理和评论 —— 同样是 lark-drive 的职责范围。

  • 不处理 docx 文档 —— 本 Skill 只处理 Drive 中作为普通文件存储的 .md 文件。

另外，+patch 操作不是服务端原子更新，而是 CLI 侧编排出来的局部更新能力。文件名必须显式带 .md 后缀，否则会直接报错。

六、写在最后

lark-markdown 把飞书云盘中 Markdown 文件的管理能力从图形界面搬到了命令行。对于习惯命令行的开发者、需要自动化文档管理的团队、以及希望用 AI 助手处理文档事务的用户来说，这是一个轻量但实用的工具。