快速摘要

飞书团队于 2026 年 3 月 28 日正式在 GitHub 开源了 lark-cli，这是一款用 Go 语言编写的命令行工具，核心目标是让人类和 AI Agent 都能在终端中操作飞书的全部核心功能。它覆盖了消息、文档、多维表格、电子表格、日历、邮箱、任务、会议等 11 大业务域，提供 200 多条精选命令和 19 个 AI Agent Skills，采用 MIT 开源协议。通过三层调用架构（快捷命令 → API 命令 → 通用 API 调用），开发者和 AI 编程助手可以在终端中直接完成以前必须打开飞书 App 才能做的事情。 往下看有更详细的架构原理、安装配置步骤、安全设计分析和实际应用场景拆解。

---

为什么大厂都在做 CLI？AI Agent 时代的底层逻辑

2026 年以来，一个非常明显的趋势是：科技公司纷纷为自家产品推出命令行工具。Google 开源了 gws 来操作 Google Workspace，Anthropic 有 Claude Code，OpenAI 推出了 Codex CLI——几乎所有想接入 AI Agent 生态的产品都在做 CLI。

这背后的逻辑并不复杂。CLI（Command Line Interface，命令行界面）是一个纯文字、纯指令的交互环境，没有按钮，没有弹窗，用户输入一条指令，系统返回一个结果。这种交互模式天然适合 AI Agent 使用——AI 本身就是基于文本处理信息的，命令行对 AI 来说就像母语一样自然。

我之前在黑龙江节点云计算科技公司考人工智能训练师的时候，课程里有一个重要的知识模块就是讲 AI Agent 的工具调用能力。当时老师反复强调一个观点：AI 光能"聊"还不够，它必须要有"手"，能够真正去操作外部系统。现在看飞书做的这件事，恰好就是在给 AI 一双能操作企业办公系统的"手"。

图形界面（GUI）是为人类设计的，CLI 是为程序和 AI 设计的。一个产品同时提供这两种形态，意味着它在同时服务两类"用户"——人和机器。飞书开源 lark-cli，本质上是把自己从一个"给人用的 App"，升级成了一个"人和 AI 都能用的操作平台"。

从更宏观的行业视角来看，这其实是一次软件交互范式的回归与进化。CLI 比 GUI 早了二十多年，在 Windows 时代逐渐退出普通用户的视野。但 AI Agent 时代的到来，让 CLI 重新站上了舞台中央。原因很简单：AI Agent 要真正帮人干活，就必须具备操控外部系统的能力。你让 AI 帮你订会议室，它需要能访问日历系统；你让它帮你整理客户数据，它需要能读写表格；你让它帮你跟进项目进展，它需要能发消息建任务。所有这些操作，通过 CLI 接口来完成是最直接、最高效的方式。

---

lark-cli 到底是什么

lark-cli 是飞书开放平台的官方命令行工具，由字节跳动飞书团队开发和维护，使用 Go 语言编写。项目的 GitHub 仓库地址是：

https://github.com/larksuite/cli

它的核心功能可以用一句话概括：把飞书开放平台的 2500 多个 API 接口封装成终端命令，让开发者和 AI Agent 通过命令行就能完成几乎所有飞书操作。

从技术参数来看，lark-cli 的覆盖范围相当全面。11 个核心业务域包括：

• 日历：查看日程、创建会议、邀请参会人、查询忙闲状态、推荐会议时间
• 即时通讯：发送和回复消息、创建管理群聊、查看聊天记录、搜索消息、下载媒体文件
• 云文档：创建、读取、更新、搜索文档，支持 Markdown 与飞书文档格式的双向转换
• 云空间：上传下载文件、搜索文档与知识库、管理文件评论和权限
• 多维表格：读写记录、管理字段和视图、支持批量数据操作
• 电子表格：读写单元格数据、管理工作表
• 邮箱：发送和管理邮件
• 任务：创建、更新、完成任务，管理任务列表
• 会议：预约和管理视频会议
• 通讯录：查找用户、搜索部门成员
• 审批：查看和处理审批流程

这不是一个"半成品"式的开源项目，而是把飞书的核心能力几乎完整地搬到了命令行里。

---

三层调用架构：从小白到极客的全覆盖

lark-cli 在设计上最值得称道的地方是它的三层调用架构。不同技术水平的用户、不同场景的需求，都能找到适合自己的调用方式。这三层从上到下分别是快捷命令（Shortcuts）、API 命令和通用 API 调用。

第一层：Shortcuts（快捷命令）

这是最上层的封装，以 + 号作为前缀标识。它面向人类用户和 AI Agent 做了大量优化，内置了智能默认值，输出结果默认是易读的表格格式，还支持 --dry-run 参数来预览操作效果而不实际执行。

几个典型的快捷命令长这样：

# 查看今天的日程安排
lark-cli calendar +agenda

# 给指定群聊发送一条消息
lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"

# 创建一篇飞书文档，直接用 Markdown 写入内容
lark-cli docs +create --title "周报" --markdown "# 本周进展\n- 完成了 X 功能"

对于大多数日常操作场景，快捷命令基本就够用了。参数少、默认值合理，不需要翻文档就能上手。

第二层：API 命令

这一层是从飞书开放平台的 OpenAPI 元数据自动生成的，100 多条精选命令与飞书平台的 API 端点一一对应。它的参数更加精确和完整，适合 AI Agent 进行结构化调用，也适合需要精细控制的开发者。

# 列出所有日历
lark-cli calendar calendars list

# 查看指定日历中某个时间段的事件
lark-cli calendar events instance_view \
  --params '{"calendar_id":"primary","start_time":"1700000000"}'

AI Agent 在实际工作中主要使用的就是这一层。因为每条命令的参数结构清晰、返回数据格式统一，AI 可以非常准确地构造调用参数并解析返回结果。

第三层：通用 API 调用

这是最底层、最灵活的调用方式，可以直接访问飞书开放平台的任意 API 端点，覆盖完整的 2500 多个接口。当上面两层的封装不能满足你的需求时，这一层可以让你做任何飞书 API 支持的操作。

# 发起一个 GET 请求，获取日历列表
lark-cli api GET /open-apis/calendar/v4/calendars

# 发起一个 POST 请求，给指定群聊发送消息
lark-cli api POST /open-apis/im/v1/messages \
  --params '{"receive_id_type":"chat_id"}' \
  --body '{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"Hello\"}"}'

简单来说：日常用第一层，AI Agent 主要用第二层，做深度定制或对接冷门接口就用第三层。这种分层设计让不同角色的用户都能找到舒适区，而不是被迫在"过于简单"和"过于复杂"之间二选一。

---

19 个 AI Agent Skills：给 AI 的"说明书"

Skills 是 lark-cli 中一个非常关键的概念，也是这个项目区别于普通 CLI 工具的核心设计。

什么是 Skill？简单来说，它是一份写给 AI Agent 看的"操作说明书"。每个 Skill 对应一个业务域，里面详细描述了这个域下有哪些命令、每条命令的参数是什么、什么场景下应该用什么参数、出错了怎么处理。

举个直观的例子来理解 Skill 的作用。如果没有 Skill 文件，AI Agent 也可以通过 --help 参数自行摸索如何使用 lark-cli，但这就像你拿到一个没有说明书的新设备，要靠自己一个按钮一个按钮地试。有了 Skill 文件，AI Agent 一启动就知道全局有哪些能力、该怎么用，成功率会高得多。

用一个形象的比喻来说：CLI 是 AI 的"手"，Skill 是 AI 的"肌肉记忆"。

lark-cli 提供的 19 个 Skills 覆盖了前面提到的 11 大业务域，其中有一个特殊的 Skill 叫 lark-cli-meta，它负责应用配置、认证登录、身份切换、权限管理和安全规则，所有其他 Skill 启动时都会自动加载它。

这些 Skills 的设计兼容了目前主流的 AI 编程工具，包括 Claude Code、Cursor、Codex 等。安装 Skill 之后，这些 AI 工具就能直接理解和使用 lark-cli 的全部能力，不需要额外做任何适配。

具体来看，每个 Skill 文件内部的结构大致包含以下几个部分：该业务域支持的所有命令列表、每条命令的参数说明和使用示例、常见错误的处理建议、以及该域下操作的最佳实践。比如日历 Skill 会告诉 AI：查询日程用 +agenda，创建事件用 +events-create，如果需要跨时区协调就先查每个人的忙闲状态再推荐时间段。AI Agent 读取这些 Skill 文件后，就像获得了一本按业务域分类的操作手册，面对用户的自然语言指令时可以快速找到对应的命令组合。

值得一提的是，Skill 文件本身也是开源的，存放在项目仓库的 skills 目录下。如果你觉得某个 Skill 的描述不够清晰或者缺少某些场景的指导，可以直接提 PR 来改进它。项目还提供了 skill-template 模板目录，如果你想为 lark-cli 贡献全新的 Skill（比如针对某个特定行业的工作流封装），可以基于模板来开发。

---

从零开始：手把手安装配置教程

接下来是实际操作的部分。lark-cli 的安装分为两种方式：npm 安装（推荐给大多数用户和 AI Agent）和源码编译（适合想深度定制或参与开发的开发者）。

环境要求

运行 lark-cli 需要 Node.js 环境（包含 npm 和 npx），版本要求 16 以上。如果你选择源码编译，还需要 Go v1.23 以上版本和 Python 3。

方式一：npm 安装（推荐）

# 第一步：全局安装 lark-cli
npm install -g @larksuite/cli

# 第二步：安装 AI Agent Skills（这一步是必需的）
npx skills add larksuite/cli -y -g

方式二：源码编译

# 克隆仓库
git clone https://github.com/larksuite/cli.git
cd cli

# 编译并安装
make install

# 同样需要安装 Skills
npx skills add larksuite/cli -y -g

配置应用凭证

安装完成后，需要创建一个飞书应用并配置凭证。这个过程是交互式的，命令行会一步步引导你完成：

# 启动配置向导（只需要做一次）
lark-cli config init

执行这条命令后，CLI 会引导你完成以下几步：在飞书开放平台创建一个应用（如果还没有的话），获取 App ID 和 App Secret，并保存到本地配置中。如果你已经有飞书应用，也可以直接输入已有的凭证。

登录授权

配置好应用凭证之后，需要通过 OAuth 流程完成登录授权：

# 使用推荐权限范围登录（自动选择常用权限，减少手动筛选）
lark-cli auth login --recommend

执行后，CLI 会输出一个授权链接，你需要在浏览器中打开这个链接并完成授权确认。授权成功后，CLI 会自动获取并存储访问令牌。

--recommend 参数会自动选择日历、消息、文档、多维表格、通讯录等常用业务域的权限，省去逐项选择的麻烦。如果你只需要特定权限，也可以精确指定：

# 只申请日历只读权限
lark-cli auth login --scope "calendar:calendar:readonly"

# 只申请日历和任务域的权限
lark-cli auth login --domain calendar,task

验证安装

一切配置完成后，运行以下命令确认状态：

# 查看当前认证状态
lark-cli auth status

# 试试查看今天的日程
lark-cli calendar +agenda

如果能正常输出结果，说明安装配置全部完成。

AI Agent 场景下的特殊配置

如果你是为 AI Agent（如 Claude Code、Codex）配置 lark-cli，流程大体相同，但有一个关键区别：lark-cli config init 和 lark-cli auth login 这两个命令在 AI Agent 环境中需要在后台运行。命令会输出一个授权 URL，AI Agent 需要把这个链接发给你，由你在浏览器中完成确认，命令会自动检测到授权完成并退出。

安装完成后，一定要重启你的 AI 工具（Claude Code、Cursor 等），这样 Skills 才能被正确加载。

---

AI Agent 是如何使用 lark-cli 的：一个完整的调用链路

理解了架构和安装之后，我们来看一个 AI Agent 实际使用 lark-cli 的完整过程。

假设你对 Claude Code 说："帮我查一下今天的日程，如果下午有空就创建一个 3 点的会议，邀请张三和李四。"

AI Agent 在背后执行的步骤大致如下：

第一步，意图识别。AI 解析你的自然语言，识别出两个操作意图：查询日程、条件创建会议。

第二步，查询日程。AI 调用 lark-cli calendar +agenda 获取今天的所有日程安排，返回结果是结构化的表格数据。

第三步，分析结果。AI 分析返回的日程数据，判断下午 3 点是否有空。

第四步，创建会议。如果下午有空，AI 调用 lark-cli calendar +events-create --title "会议" --start "2026-03-30 15:00" 创建会议，并添加参会人。

第五步，反馈结果。AI 把执行结果用自然语言告诉你，比如"已创建今天下午 3 点的会议，张三和李四已收到邀请。"

整个过程中，AI Agent 通过 Skill 文件知道该用哪些命令、传什么参数，通过 CLI 执行操作，通过结构化输出解析结果。你只需要说一句话，剩下的全部自动完成。

---

容易被忽视的亮点：错误处理与输出控制

很多 CLI 工具在"能用"的层面做得不错，但在"好用"的层面还差一截。lark-cli 在几个细节上做了比较用心的设计，这些细节直接影响 AI Agent 使用时的成功率。

结构化错误信息。 当命令执行出错时，lark-cli 不是简单地返回一个 HTTP 状态码或一句笼统的错误描述，而是明确告诉 AI 三件事：哪个参数有问题、具体错在哪里、下一步应该执行什么命令来修复。比如权限不够时，返回信息会附带 lark-cli auth login --scope "calendar:calendar:readonly" 这样的修复命令。AI 拿到这个信息后可以自主重试和纠错，不需要人工干预。

多种输出格式。 lark-cli 支持 json、csv、table 等多种输出格式。对人类来说 table 格式更直观，对 AI Agent 来说 json 格式更容易解析。可以通过 lark-cli config set format table 设置默认格式，也可以在单条命令中指定。

分页与过滤。 AI Agent 的上下文窗口是有限的，如果一个命令返回上万条记录，上下文很快就会被撑满。lark-cli 提供了 --page-limit 分页参数和各种过滤参数，让 AI 只获取它需要的那部分数据。

dry-run 预览模式。 在执行写操作（发消息、创建文档、修改数据等）之前，加上 --dry-run 参数可以先预览将要执行的操作，确认无误后再真正执行。这个功能在 AI Agent 场景下特别重要——你可以让 AI 先列出它打算做什么，你确认之后再放行。

---

安全设计：Agent 操作办公系统的风险与防护

让 AI Agent 直接操作企业级办公系统，安全问题是不可回避的。lark-cli 在安全方面做了多层防护设计。

输入注入防护。 在 AI Agent 场景下，用户输入可能被恶意构造成 prompt injection（提示注入），试图让 AI 执行预期之外的操作。lark-cli 在命令解析层面做了输入过滤和校验，防止恶意指令被当作合法参数执行。

终端输出净化。 CLI 的输出内容经过处理，避免在终端中泄露敏感信息（如完整的 access token、用户隐私数据等）。这一点在 AI Agent 场景下尤为重要，因为 AI 的上下文对话可能被记录或展示。

凭证安全存储。 lark-cli 使用操作系统原生的密钥链（Keychain）来存储认证凭证，而不是明文写入配置文件。在 macOS 上使用 Keychain，在 Linux 上使用对应的安全存储机制。

操作确认机制。 对于敏感操作（如删除数据、发送消息等），CLI 默认会要求确认，避免误操作造成不可逆的影响。

权限最小化原则。 项目文档明确建议：将 Agent 使用的飞书 Bot 限定在私人对话中，不要将其添加到群聊。这条建议的出发点是降低权限滥用的风险边界——Bot 在群聊中可能接触到更多不相关的数据，而在私人对话中操作范围更加可控。

除了这些内置的安全机制之外，在实际部署时还有一些安全实践建议值得注意。首先，应用凭证（App ID 和 App Secret）不要硬编码在脚本或配置文件中，也不要提交到 Git 仓库。lark-cli 使用系统密钥链存储凭证，这已经比明文存储好很多，但在 CI/CD 环境中还需要配合环境变量或专门的密钥管理服务来使用。其次，在生产环境中使用 lark-cli 时，建议按照最小权限原则来申请 OAuth 权限范围——只申请你确实需要的业务域权限，不要图省事一次性开通所有权限。最后，定期轮换 access token 也是一个好习惯，特别是在多人共享同一个飞书应用的场景下。

---

CLI 与 MCP 的关系：两种 Agent 接口各有什么不同

如果你关注 AI Agent 生态，可能会注意到飞书同时还有一个 MCP（Model Context Protocol）服务端项目 lark-openapi-mcp。那么 CLI 和 MCP 是什么关系？什么时候该用哪个？

两者的定位并不冲突。CLI 适合在终端环境中使用，天然支持管道操作（pipe），可以和 shell 命令自由组合。举个例子：

# 查出下周和张三有关的所有会议数量
lark-cli calendar agenda --next-week | grep "张三" | wc -l

一行命令就能完成"查询 + 过滤 + 统计"的复合操作。如果用 MCP 实现同样的功能，需要预先定义一个专门的工具，灵活度差不少。

但 MCP 有自己的适用场景。在不支持终端命令执行的环境中（比如 Cursor 桌面端、Claude 桌面客户端），MCP 是唯一的选择。两者各有所长：能访问终端的场景用 CLI 更轻量灵活，不能访问终端的场景靠 MCP。

目前飞书官方已经表示后续会推出内置全部 CLI 能力的 OpenClaw 官方插件，届时两种调用方式将进一步打通。

---

实际应用场景：lark-cli 能做什么

了解了原理和配置之后，来看几个贴近实际工作的使用场景，帮助你理解 lark-cli 的实际价值。

场景一：会议结束后的自动化跟进

开完一个项目讨论会，你可以对 AI 说："把会议里提到的所有待办都整理出来，该建文档的建文档，该建任务的建任务，然后通知到项目群。"

AI 会依次执行：读取飞书妙记中的会议纪要 → 提取待办事项 → 用 lark-cli docs +create 创建文档 → 用 lark-cli task 相关命令创建任务并指派给对应的人 → 用 lark-cli im +messages-send 把结果通知到群里。整个过程可以先用 --dry-run 预览确认，没问题再正式执行。

场景二：跨时区会议协调

你需要约一个五人跨时区的会议，直接告诉 AI："看看下周大家什么时候都有空。" AI 会查询每个人的日历和时区信息，综合分析后推荐几个所有人都在合理工作时间段内的选项，你选一个就行。

场景三：Markdown 文档无缝发布

在 Claude Code 或其他编程工具中用 Markdown 写好技术文档或周报，一条命令就可以转换成格式完整的飞书文档。lark-cli 的 Markdown 转换支持 40 多种块类型，标题、列表、代码块、表格、引用都能保留，甚至 Mermaid 和 PlantUML 图表也可以自动转换为飞书画板中可编辑的矢量图。

这里有一个技术细节值得展开说说。飞书文档和 Markdown 的互相转换看似简单，但实现起来有不少复杂性。飞书文档底层使用的是自定义的 Block 结构，每种内容类型（标题、段落、代码块、表格等）都是一个独立的 Block，嵌套关系也比 Markdown 复杂得多。lark-cli 内部采用了三阶段并发管道架构来处理这个转换过程：先解析 Markdown 的 AST（抽象语法树），然后并发地把每个节点转换成对应的飞书 Block，最后组装成完整的文档结构并通过 API 上传。根据社区用户的反馈，这套管道在实测中可以一次性处理 10000 行以上、包含 127 个图表的大型文档，不会出现超时或崩溃。

同时这个转换是双向的——你也可以把飞书文档导出为 Markdown 格式，方便在本地编辑器或 Git 仓库中管理。对于习惯用 Markdown 写文档的技术团队来说，这个功能几乎打通了本地写作和飞书发布之间的"最后一公里"。

场景四：批量消息与数据处理

需要给部门里特定一组人发送个性化通知？让 AI 读取多维表格中的人员名单和对应内容，通过 CLI 批量发送定制化消息。或者从多维表格中批量导出数据、检查字段完整性、给相关人员发提醒——这些重复性的工作都可以交给 AI 通过 CLI 自动完成。

场景五：CI/CD 流程集成

在持续集成/持续部署流水线中集成 lark-cli，可以实现构建成功或失败时自动向飞书群发送通知，把部署日志的关键信息同步给团队成员，不需要额外开发 webhook 或 Bot。

---

身份切换：用户身份与 Bot 身份

lark-cli 支持在两种身份之间灵活切换：用户身份（user）和机器人身份（bot）。这个设计在实际使用中非常实用。

# 以用户身份查看自己的日程
lark-cli calendar +agenda --as user

# 以机器人身份发送消息
lark-cli im +messages-send --as bot --chat-id "oc_xxx" --text "Hello"

用户身份可以执行只有特定用户才有权限的操作（比如查看自己的日历），Bot 身份则适合做群通知、自动回复等不绑定具体个人的操作。

---

技术实现细节补充

从源码结构来看，lark-cli 的项目组织比较清晰。cmd 目录是命令入口，internal 目录包含核心逻辑，shortcuts 目录存放快捷命令的定义，skills 目录就是前面说的 AI Agent Skills，skill-template 提供了 Skill 的开发模板——如果你想为 lark-cli 贡献新的 Skill，可以基于这个模板来写。

在构建和发布方面，项目使用 goreleaser 来管理多平台的编译和发布，支持 macOS（darwin）、Linux 和 Windows 三个操作系统，以及 x64 和 arm64 两种处理器架构。通过 npm 分发的安装包实际上会在安装时（postinstall 脚本）自动下载对应平台的预编译二进制文件。

---

几个实用的小技巧

在实际使用 lark-cli 的过程中，有一些小技巧可以让你的体验更顺畅：

所有命令都支持 --help 参数查看详细的使用说明。比如 lark-cli im +messages-send --help 会列出发消息命令的全部参数和用法示例。当你不确定某个命令怎么用的时候，--help 是最快的查询方式。

如果你经常使用表格格式查看输出，可以把它设为默认：lark-cli config set format table。这样每次执行查询类命令时，返回结果都会以更易读的表格形式展示，不需要每次都加 --format table 参数。

遇到权限问题时不要慌，lark-cli 的错误信息通常会告诉你缺少什么权限以及如何补充。最常见的解决方式是重新执行一次带有具体 scope 的登录命令，比如 lark-cli auth login --scope "calendar:calendar:readonly"。

对于国际版 Lark 用户，lark-cli 同样支持。在 config init 配置阶段选择国际版应用即可，CLI 会自动切换到对应的 API 端点。

---

写在最后

飞书开源 lark-cli 这件事，从技术角度看是把一整套企业办公系统的操作能力重新抽象成了 CLI 接口；从趋势角度看，它代表了一种正在成为主流的软件形态——GUI 服务人类，CLI 服务 AI，同一个产品，两种形态，同时存在。

对于开发者和技术人员来说，lark-cli 降低了飞书集成开发的门槛，不需要自己封装 API 调用逻辑，直接用命令行就能完成大多数操作。对于正在探索 AI Agent 应用落地的团队来说，它提供了一个现成的、经过实测的 Agent 操作接口，可以快速搭建"对话即操作"的工作流。

这个项目采用 MIT 协议开源，没有使用门槛，安装也只需要三步。如果你日常工作中使用飞书，并且对 AI Agent 自动化办公感兴趣，值得花几分钟把它跑起来试试。

项目地址：https://github.com/larksuite/cli