1. 前情提要
日常生活中，我写文档的频率并不算低。无论是苦哈哈地赶大作业，还是美滋滋地更新公众号推文，我都先用飞书文档打草稿，然后再转换为其他的格式（抵不住飞书好用审美又在线啊）。
飞书很好用，AI 也很好用。我就在想，能不能将飞书和 AI 结合起来，这样就会有更好的写作体验了。内容我来掌管，排版就交给AI了，解放双手说是 :D 。AI 看起来还挺适合做这些工作的。
一番调研之后发现 lark-cli 正好能做这件事——它是飞书开放平台的命令行工具，配合 Skills 体系可以让 AI Agent 直接调用飞书 API。行动！
整条链路长这样：
自然语言指令 -> AI Agent (opencode) -> lark-doc Skill -> lark-cli -> 飞书 API -> 飞书文档我使用的是 opencode，它可以接入不同家的大模型，支持 MCP 调用子 Agent，自动切换合适的模型，也可以根据自己的意愿配置和手动切换。市面上还有一些插件，如 oh-my-openagent、superpowers 等，我还是更偏爱不用插件（大道至简
主要有这三个：
- opencode：AI Agent 运行时，负责理解用户意图、调度工具
- lark-cli：飞书 CLI 工具，把飞书 API 封装成命令行指令
- Skills：lark-cli 的扩展机制，把命令按场景打包成可被 Agent 加载的模块
让我们来打通这个工作流。
2. 环境搭建
飞书开发者后台
所有飞书 API 调用都需要一个应用身份。去 飞书开发者后台 创建一个自建应用，拿到 App ID 和 App Secret。
然后在「权限管理」页面开通 scope。文档操作至少需要：
docx:document— 文档读写drive:drive— 云空间访问
安装与配置
sudo npm install -g @larksuite/clinpx @larksuite/cli@latest install用户身份授权
lark-cli 有两种身份：
| 身份 | 获取方式 | 适用场景 |
|---|---|---|
| bot | 自动，只需要 App ID/Secret | 应用级操作 |
| user | 需要用户手动授权 | 访问个人资源（文档、日历等） |
创建文档是用户资源操作，需要 user 身份：
lark-cli auth login --domain docs --recommend这个命令会输出一个验证链接，浏览器打开完成授权。可以用 lark-cli auth status 确认授权状态。
3. 接入 Agent
CLI 跑通只是第一步。真正的价值在于让 AI Agent 来驱动它。
lark-cli 的 Skills 体系是专门为 AI Agent 设计的。每个 Skill 是一个 Markdown 文件，描述了命令用法、参数格式、执行前必须读取的参考文件。
在我的环境里，Skills 目录在 ~/.agents/skills/ 下。安装 Skills：
npx skills add larksuite/cli -g -y安装完成后目录结构：
~/.agents/skills/ lark-shared/SKILL.md # 共享规则（认证、权限、安全） lark-doc/SKILL.md # 文档操作 lark-doc/references/ # 命令参考、格式规范、样式指南Agent 启动后会扫描这些文件，知道有哪些命令可用。不需要额外配置，Skills 目录路径正确即可。
4. 端到端测试
环境搭好之后，我先手动跑了条命令验证 CLI 是否可用：
lark-cli docs +create --title "CLI测试文档" --markdown "# Hello World!"确认 CLI 通了之后，我才让 Agent 接手。对 Agent 说了两句话：
- “帮我创建一篇飞书文档”
- “请给这个文档合理排版，并绘制图表”
Agent 识别出”创建飞书文档”属于 lark-doc Skill，然后加载它。Skill 的第一条指令就是：
执行操作前，MUST 先读以下文件，缺一不可
Agent 并行读取了 4 个参考文件：
| 文件 | 作用 |
|---|---|
lark-shared/SKILL.md | 认证规则、bot/user 身份差异、安全约束 |
lark-doc-create.md | docs +create 的参数格式、返回值结构 |
lark-doc-md.md | Markdown 转义规则 |
lark-doc-create-workflow.md | 从零创作的工作流 |
读完之后，Agent 根据我给的内容，用 Markdown 格式创建了初始文档。返回成功，拿到了 document_id 和 URL。
我追加了排版和图表需求。Agent 判断：排版需要 callout、table、grid、whiteboard 这些组件——Markdown 格式不支持这些，必须切到 XML。
于是 Agent 又读了 4 个参考文件：
| 文件 | 作用 |
|---|---|
lark-doc-xml.md | XML 标签语法 |
lark-doc-style.md | 排版规范：开头必须 callout、连续文本不超 3 段、颜色语义 |
lark-doc-update.md | docs +update 的 8 种指令 |
lark-doc-update-workflow.md | 改写工作流 |
5. 能力总结
lark-cli Skills 强制要求 Agent 执行前读参考文件。每次操作前要先 read 再 execute，增加了延迟，但确保了命令格式正确。没有这个机制，Agent 很可能用错参数或者选错格式。
格式分工
| 格式 | 能力 | 适用场景 |
|---|---|---|
| Markdown | 纯文本 + 基础格式 | 快速创建简单文档 |
| XML | 完整 block 结构 + 富组件 | 结构化排版、图表 |
创建文档时用 Markdown 快速建骨架；需要排版时切到 XML 做结构化。这条路径在实际测试中跑得很顺。
排版组件
飞书文档的 block 结构通过 XML 标签表达，支持的组件比 Markdown 丰富得多：
<callout>— 高亮框，可以选 emoji、背景色、边框色<grid>+<column>— 分栏布局，自定义列宽比例<table>— 带表头背景色、单元格合并的表格<whiteboard type="mermaid">— 直接内嵌 mermaid 流程图、时序图、思维导图<checkbox>— 待办清单<span text-color="green">— 文字颜色标记
用 XML 排版的好处是：结构和样式分离，Agent 只需要构造正确的标签，飞书负责渲染。
6. 最后
搭建完成后，用一句自然语言就能让 Agent 完成从创建到排版的全流程。以后写什么文档，可以让 Agent 出一版结构化初稿，再在飞书里微调。不需要手动复制粘贴，不需要手动调排版，AI 来做这些重复性工作，俺来把控内容质量，美滋滋啊美滋滋~