lark-cli 把飞书文档、幻灯片、云盘、画板等协作资源封装成 Agent 可稳定调用的结构化对象，让创建、编辑、导入、授权、分享和错误恢复都能通过统一 CLI 完成。

“Build Anything” 不是让 Agent 生成更多本地文件，而是让 Agent 直接生成可以交付、可以协作、可以继续迭代的工作成果。Markdown 适合写草稿和短文，HTML 适合表达视觉，Word 和 PPT 适合人手动精修；但 Agent 真正需要的，是一个既有结构语义、又能落进协作网络的对象模型。

lark-cli 的优雅之处就在这里：它没有让 Agent 去模拟人点鼠标、拖文本框、调字号，而是把文档和幻灯片变成可以被程序精确操作的云端对象。Agent 写出来的内容不是躺在本地磁盘上的半成品，而是一份带 URL、权限、评论、版本和搜索能力的飞书原生资源。

先看能力地图：它不是文档转换器

lark-cli 是飞书官方开源 CLI。README 里明确写了它面向人和 AI Agent，覆盖 Messenger、Docs、Base、Sheets、Slides、Calendar、Mail、Tasks、Meetings、Markdown 等核心域，提供 200+ 命令和 AI Agent Skills（README.md#L9-L21）。

它的命令系统分三层。最上层是 + 开头的 Shortcut，面向完整任务和 Agent 友好调用；中间层是从开放平台元数据生成的 API Commands，和平台 endpoint 一一映射；最底层是 Raw API，可以直接调用 2500+ 个开放平台接口（README.md#L196-L221）。

对内容生产来说，最关键的是这些能力：

• docs +create/+update：创建和增量编辑新版文档，默认 XML，也支持 Markdown 导入（shortcuts/doc/docs_create_v2.go#L14-L21、shortcuts/doc/docs_update_v2.go#L14-L35）
• slides +create/+replace-slide：创建演示文稿，并以 slide/block 粒度局部替换内容（shortcuts/slides/slides_create.go#L24-L43、shortcuts/slides/slides_replace_slide.go#L22-L46）
• drive +import：把 .md、.html、.docx、.pptx 等本地文件导入成飞书原生云文档或幻灯片（shortcuts/drive/drive_import_common.go#L33-L48）
• whiteboard +update/+query：用 Mermaid、PlantUML 或画板 DSL 更新和读取画板，适合把结构关系、流程和布局做成可视化表达（shortcuts/whiteboard/whiteboard_update.go#L19-L39、shortcuts/whiteboard/whiteboard_query.go#L58-L70）

这些命令不是散装工具，而是统一注册到同一套 Shortcut 运行时里，复用同一套认证、输出、错误和执行协议（shortcuts/register.go#L59-L87）。

飞书文档和 HTML 都是在帮 Markdown 加速理解

Agent 写 Markdown 的问题很清楚：它足够稳定，但信息呈现太线性。读者需要自己在纯文本里还原层级、重点、关系和节奏；一旦内容变成长报告、产品方案或技术设计，理解成本就会显著上升。

HTML 的价值正在这里。它通过字体、色块、卡片、分栏、图片、动效和交互，把 Markdown 里的结构关系变成更容易扫读和理解的视觉层。它不是简单"变好看"，而是在帮读者更快抓住重点。

飞书文档与 HTML 在这一点上是一曲同工。它同样能把 Markdown 从线性文本变成更容易理解的表达：标题层级、引用块、高亮块、表格、图片、画板、布局和基础文档样式，都能降低阅读阻力。复杂关系可以放进画板，局部视觉内容可以用 HTML 导入或嵌入式材料承载，最终读者看到的不是一坨 Markdown，而是一份有视觉层次的协作文档。

差异不在"谁更能提升第一眼理解"，而在"谁更适合作为 Agent 的最终交付对象"。HTML 更像表现层，适合把内容做成页面；飞书文档既能承担表现层，又天然带评论、@提及、权限、版本、搜索和后续编辑入口。它把"加速理解"和"进入协作"合在了同一个对象里。

这也是 lark-cli 相比单纯 “Markdown + HTML” 更有想象力的地方：它不是否定 HTML 的理解加速能力，而是把这种能力接到飞书原生对象上。创建即落云盘，生成即带链接，修改走 API，版本和权限天然归平台管理。

文档：Agent 写的是 block，不是页面像素

docs +create 和 docs +update 是 Agent 写文档的主入口。内容格式默认是 XML，也可以导入 Markdown。关键差异在于：DocxXML 描述的是文档语义，而不是视觉效果。

一个标题不再是 <div style="font-size:20px;font-weight:bold">，而是 <heading level="1">；一段引用不是靠边框样式模拟，而是 <quote>；一个任务项不是 HTML 里的 checkbox，而是文档里的任务 block。Agent 写的是"这是什么"，不是"它看起来像什么"。

这直接带来三个收益：

• 精确编辑：每个 block 有稳定位置和类型，docs +update 支持 append、prepend、replace，Agent 可以只改某个段落、某个列表、某个标题后的内容，不必整篇重写
• 原生解析：提取大纲看 heading，统计待办看 todo，生成目录看层级字段，不需要从 HTML class 和样式里猜结构
• 平台表达：图片、代码块、表格、画板、文件、群名片等组件是飞书文档原生能力，不需要用 CSS 伪装

这不是说 Markdown 没价值。简单文本草稿仍然可以用 Markdown 生成，再通过 docs +create --doc-format markdown 或 drive +import 进入文档。但只要需求变成"可协作、可迭代、可直接发出去"，XML 和飞书文档对象就比 HTML 更适合 Agent。

幻灯片：从整页重画到 block 级维护

PPT 是 Agent 自动化最容易翻车的场景。传统方式让 Agent 操作 PowerPoint COM 对象或 python-pptx，本质仍然是在模拟人类拖拽画布：插文本框、设字号、调坐标、对齐元素。生成一页还勉强，后续修改往往要整页重画。

lark-cli 的幻灯片能力走的是另一条路：SML（Slides Markup Language）XML + block 级操作。

slides +create 用 XML 字符串数组创建演示文稿，每个元素对应一页幻灯片。XML 描述页面结构：有哪些 shape、文本、图片、坐标和内容。Agent 操作的是结构化元素，不是 UI 里的像素。

更关键的是 slides +replace-slide。它支持 block_replace 和 block_insert，可以只替换某页标题、只插入一段说明、只修改某个图形的文字，其他元素保持不动。对 Agent 来说，这意味着 PPT 从"一次性生成品"变成了"可增量维护的结构化演示文稿"。

Shortcut 还把底层 API 的隐性坑提前填平。替换 block 时，后端要求 replacement 根元素带 id="<block_id>"，且每个 <shape> 必须带 <content/>；这些规则一旦遗漏，常见结果就是笼统的 3350001。slides +replace-slide 会自动注入 block id、补全 <content/>，并在错误时给出更具体的排查方向。Agent 拿到的不是脆弱 API，而是更接近"正确操作原语"的命令。

云盘：创建即交付，链接就是最新版

Agent 生成本地 .md、.docx 或 .pptx，只是完成了内容生产，还没有完成交付。文件还要上传、分享、授权；别人修改后，本地版本和云端版本又会分叉。协作不是文件格式的一部分，而是额外流程。

lark-cli 把这一步内置到创建动作里。docs +create、slides +create 和 drive +import 返回的是飞书云空间里的对象 URL。用户打开的就是同一份实时资源，评论、@提及、建议编辑、版本历史都在这份对象上流转。

权限边界也被处理得更适合 Agent。Bot 创建资源时，默认只有 bot 自己能访问；lark-cli 会尽力把当前 CLI 用户授予新资源的 full_access（可管理）权限，避免返回一个用户打不开的死链。这个通用逻辑在 AutoGrantCurrentUserDrivePermission 里实现（shortcuts/common/permission_grant.go#L24-L44），文档、幻灯片和导入流程都会复用类似处理（shortcuts/doc/docs_create_v2.go#L81-L95、shortcuts/slides/slides_create.go#L207-L219、shortcuts/drive/drive_import.go#L153-L157）。

云盘对象还有一个本地文件没有的价值：可发现。它可以被 drive +search 搜到，可以加入知识库，可以出现在最近访问，可以被其他文档引用。Agent 产物不再是某个目录里的孤立文件，而是组织知识网络里的一个节点。

错误契约：失败也能被 Agent 接住

Agent 能不能稳定使用 CLI，不只取决于成功路径是否顺滑，还取决于失败路径是否可恢复。

lark-cli 的错误不是随手打印字符串，而是类型化错误契约。errs/ERROR_CONTRACT.md 明确规定：每个错误属于一个 Category，每个 typed error 都有稳定 Subtype，Category + Subtype 是调用方可以分支判断的 wire-stable 标识（errs/ERROR_CONTRACT.md#L11-L20）。

错误输出也是结构化 JSON。error.type、error.subtype、error.code 是稳定字段，message 给人看，hint 给出恢复建议，missing_scopes、console_url 这类扩展字段告诉 Agent 下一步该怎么补权限（errs/ERROR_CONTRACT.md#L34-L68）。

这和"错误日志写清楚一点"不是一回事。普通 CLI 把错误交给人判断；lark-cli 把错误变成 Agent 可以读取、分类、重试和修复的协议。缺 scope 就知道缺哪个 scope，授权失败就知道去哪个 console_url，参数不合法就知道哪个 param 出问题。失败不再是人工介入点，而是工作流里的可恢复状态。

范式迁移：从文件生成到对象编排

传统 Office 的底层假设是：文档是给人操作的本地文件。打开软件、点菜单、调整格式、保存文件、再发给别人。这个范式对人很自然，但对 Agent 很不友好。Agent 不擅长拖动文本框，也不擅长靠视觉反馈微调排版。

lark-cli 代表的是另一种假设：文档、幻灯片、表格、画板、日历和消息，都是可以通过 API 编排的协作对象。Agent 负责内容结构、任务意图和跨系统动作；平台负责渲染、权限、版本、搜索和协作。

这个变化带来四个结果：

• 从 GUI 操作到 API 操作：Agent 不需要打开软件点按钮，而是直接调用任务级命令
• 从本地文件到云端对象：产物从创建起就有 URL、身份、权限、版本和协作入口
• 从整体重写到增量编辑：文档按 block 改，幻灯片按 slide/block 改，最小修改不会打乱整份内容
• 从人工排错到结构化恢复：错误本身携带机器可读的分类、原因和下一步动作

这不是要取代传统 Office。人需要精细排版、创意设计和最终审美判断时，GUI 仍然有价值。但当任务是"让 Agent 自动生成可交付、可协作、可迭代的文档或 PPT"，传统文件范式已经不够了。

结语：Agent 时代的 Office 不该只是另一种文件格式

“Build Anything with lark-cli” 最有意思的地方，不是它能生成文档，也不是它能生成 PPT，而是它把办公系统里的基础对象变成了 Agent 可以稳定调用的能力。

Markdown、HTML、Word、PPT 都是格式；飞书文档、幻灯片、云盘、画板是协作对象。格式解决"内容怎么表示"，对象解决"内容怎么被创建、修改、分享、授权、评论、追踪和再次利用"。

lark-cli 的设计价值就在于把这两件事接起来：上层给 Agent 任务级 Shortcut，中层给平台资源 API，底层给 Raw API 兜底；成功时返回可交付对象，失败时返回可恢复错误。这样 Agent 才不只是会写文件，而是真的能在办公系统里 Build Anything。