飞书官方开源 lark-cli：11个业务域 + 200命令 + 19个Agent Skills，让 AI Agent 接管你的飞书

🚩 2026 年「术哥无界」系列实战文档 X 篇原创计划 第 66 篇，AI 星探「2026」系列第 7 篇 大家好，欢迎来到 术哥无界 | ShugeX ｜ 运维有术。 我是术哥，一名专注于 AI 编程、AI 智能体、Agent Skills、MCP、云原生、AIOps、Milvus 向量数据库的技术实践者与开源布道者！

Talk is cheap, let's explore。无界探索，有术而行。

lark-cli 产品信息图

你在用飞书做自动化集成时，可能遇到过这些情况：

• 调飞书API，先啃几百页文档，再写一堆样板代码
• 想让AI Agent帮你处理飞书上的事，发现没有现成的工具链
• 每次都要处理OAuth认证、token刷新、错误重试这些琐事
• 命令行工具要么功能太弱，要么参数设计反人类

这些问题的根源是同一个：飞书开放平台缺少一个既对人类友好、又对AI Agent友好的命令行工具。

lark-cli 用三层命令架构 + 19个开箱即用的Agent Skills解决了这个问题——人类可以一条命令发消息、查日程；AI Agent可以直接调用Skills，自动处理日历、邮件、任务等业务场景。

根据官方GitHub仓库的介绍，lark-cli是飞书/Lark开放平台官方命令行工具，明确设计为built for humans and AI Agents。这不是事后加的"AI适配"，而是从第一行代码就面向Agent场景设计。

1. 为什么选 lark-cli？

先说一个反常识的结论：lark-cli是首个明确为AI Agent设计的飞书开放平台工具。

这不是营销话术。翻看官方文档和Skills设计，你会发现几个有意思的设计决策：

第一，所有命令都经过Agent实测验证。 官方README里直接写了：200+精选命令，都是经过评测和准入筛选的。什么叫"精选"？就是AI Agent实际跑过，参数友好度、错误处理、输出格式都做了优化。

第二，19个开箱即用的Agent Skills。 不是让你自己写prompt去调用API，而是直接给你封装好的Skills——lark-calendar管日程、lark-im管消息、lark-mail管邮件。AI Agent加载这些Skills后，就知道怎么预约会议、怎么发消息、怎么查日程。

第三，三层调用架构，适应不同场景。 简单场景用Shortcuts（+agenda、+messages-send），复杂场景用API Commands，极端场景直接Raw API调用2500+端点。这种分层设计，既照顾了人类的易用性，也满足了Agent的精确控制需求。

第四，开源零门槛。 MIT协议，GitHub直接clone就能用。对比某些厂商的工具链，要么不开源，要么许可证限制商业使用，lark-cli这点确实友好。

说到底，lark-cli的核心价值不是"又多了一个CLI工具"，而是填补了飞书生态在"AI Agent友好工具"上的空白。

2. 功能概览

lark-cli覆盖了飞书11大核心业务域，官方README里列得清清楚楚：

这些不是空头支票。官方文档里每个业务域都有对应的Shortcut命令，比如日历的+agenda、+create、+freebusy，消息的+messages-send、+chat-create。

数字层面：11个业务域、200+精选命令、19个AI Agent Skills、2500+ Raw API覆盖。这套数字不是凑出来的，而是官方从飞书开放平台数千个API里精选出来的。

3. 安装与快速开始

3.1 环境要求

lark-cli支持三大平台：macOS、Linux、Windows。如果选择源码构建，需要Go v1.23+和Python 3。

3.2 人类用户安装流程

官方推荐的安装方式是NPM：

# 安装 CLI
npm install -g @larksuite/cli

# 安装 CLI SKILL（必需）
npx skills add larksuite/cli -y -g

第二步很关键——安装Skills是必需的，不是可选的。官方文档明确写了：Skills提供了AI Agent所需的上下文和命令封装。

源码构建的方式也有：

git clone https://github.com/larksuite/cli.git
cd cli
make install

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

3.3 AI Agent辅助安装流程

这里有个有意思的设计：lark-cli专门为Agent场景优化了安装流程。

配置应用凭证（Agent执行）：

lark-cli config init --new

这条命令会输出一个授权链接。Agent把这个链接发给用户，用户在浏览器里完成飞书应用配置。Agent不需要知道appId和appSecret，只需要等用户完成配置。

登录授权（Agent执行）：

lark-cli auth login --recommend

同样输出授权链接，用户在浏览器里完成OAuth授权。Agent用--no-wait参数可以立即返回，不阻塞等待用户操作。

这种设计的好处是：敏感凭证不需要经过Agent，降低了安全风险。

AI Agent 使用 lark-cli 的完整流程

3.4 验证安装

lark-cli auth status

如果看到认证信息，说明安装成功。

4. Agent Skills深度解析

lark-cli内置的19个AI Agent Skills，是整个工具链的核心。官方文档给每个Skill都写了详细的SKILL.md，包括触发条件、命令列表、权限要求、安全规则。

4.1 lark-shared：基础能力层

lark-shared是所有其他Skill的基础依赖，负责：

• 应用配置：读取和管理飞书应用凭证
• 认证登录：处理OAuth流程
• 身份切换：Bot vs User双重身份
• 权限管理：检查和提示缺失的scope
• 安全规则：写入操作前的确认机制

官方文档要求：所有其他Skill的SKILL.md开头都要引用lark-shared，确保基础能力先加载。

4.2 lark-im：即时通讯完整能力

lark-im的核心概念：

• Message：单条消息，ID格式om_xxx
• Chat：群聊或P2P对话，ID格式oc_xxx
• Thread：消息回复线程
• Reaction：表情回复

关键Shortcut命令：

这里有个细节：Bot身份发消息时，发送者名称可能无法解析，取决于应用的可见范围。官方建议需要完整联系人信息时，用--as user切换到用户身份。

4.3 lark-calendar：智能日程管理

lark-calendar的设计哲学很有意思：辅助决策而非替代。

官方Skills文档里明确要求：

做智能助理，提供辅助决策，而不是表单填写机或替用户做主。

具体体现在时间建议工作流：

1. 用户说了明确时间点 → 查询忙闲状态 → 有冲突就提示
2. 用户说了时间区间 → 获取多个推荐方案 → 用户选择后执行
3. 用户没说时间 → 推断合理区间 → 提供推荐方案

智能默认值的设计：

• 参会人：未明确指定时，默认仅为用户自己
• 标题：根据对话上下文自动生成
• 时长：基于会议类型推断（"评审/汇报"→60分钟）

模糊语义消解与记忆构建：针对用户的个性化时间表达（如"上班后"、"下班前"），官方要求：

• 严禁主观臆断
• 主动澄清明确意图
• 沉淀为长期偏好
• 实现"下次即懂"

这个设计思路很值得学习：不是硬编码规则，而是通过对话构建个性化记忆。

4.4 lark-skill-maker：自定义Skill扩展

如果内置Skills不够用，官方提供了lark-skill-maker来创建自定义Skill。

Skill结构模板：

---
name: lark-<name>
version: 1.0.0
description: "<功能描述>。当用户需要<触发场景>时使用。"
metadata:
  requires:
    bins: ["lark-cli"]
---

# <标题>

> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)。

## 命令
...

## 权限
...

关键设计原则：

• description决定触发：必须包含功能关键词+"当用户需要...时使用"
• 认证说明：明确所需scope
• 安全确认：写入操作前确认用户意图

4.5 Skills设计理念总结

从官方文档中可以提炼出几个核心理念：

1. Agent-Native：从第一行代码就面向Agent场景设计，不是事后适配
2. 辅助决策：提供智能建议，让用户做最终决定
3. 渐进式记忆：通过对话沉淀个性化偏好
4. 安全优先：敏感操作需要确认，凭证不经过Agent

Agent Skills 分层结构

5. 认证体系深度剖析

lark-cli实现了Bot vs User双重身份体系，这是理解整个工具链的关键。

5.1 Bot vs User的区别

身份选择原则：

• Bot看不到用户资源：无法访问用户的日历、云空间文档、邮箱等个人资源
• Bot无法代表用户操作：发消息以应用名义发送，创建文档归属bot
• Bot权限只需后台配置：无需auth login
• User权限需要两层满足：后台开通scope + 用户授权

Bot vs User 身份体系对比

5.2 OAuth登录流程

lark-cli提供了多种登录方式：

# 交互式登录（TUI引导选择业务域和权限级别）
lark-cli auth login

# 按域筛选
lark-cli auth login --domain calendar,task

# 推荐的自动审批scopes
lark-cli auth login --recommend

# 精确scope
lark-cli auth login --scope "calendar:calendar:readonly"

# Agent模式：立即返回验证URL，不阻塞
lark-cli auth login --domain calendar --no-wait

--recommend的设计很贴心：官方精选了一组自动审批的scopes，减少了用户手动勾选的麻烦。

5.3 权限管理（Scope）

权限不足的处理机制，Bot和User不同：

Bot身份：

• 将错误中的console_url提供给用户
• 引导去飞书开发者后台开通scope
• 禁止对bot执行auth login

User身份：

lark-cli auth login --domain <domain>           # 按业务域授权
lark-cli auth login --scope "<missing_scope>"   # 按具体scope授权（推荐）

规则：

• auth login必须指定范围（--domain或--scope）
• 多次login的scope会累积（增量授权）

5.4 安全规则与最佳实践

官方文档列出了多层安全防护：

1. 输入防注入：防止恶意参数注入
2. 终端输出净化：敏感信息不出现在终端
3. OS原生密钥链存储：使用系统级安全存储凭证
4. Dry-run预览：危险操作前可预览

官方风险提示（原文引用）：

本工具可供AI Agent调用以自动化操作飞书/Lark开放平台，存在模型幻觉、执行不可控、提示词注入等固有风险。授权飞书权限后，AI Agent将以您的用户身份在授权范围内执行操作，可能导致敏感数据泄露、越权操作等高风险后果。

官方建议：

• 不要主动修改任何默认安全配置
• 将对接本工具的飞书机器人作为私人对话助手使用
• 请勿将其拉入群聊或允许其他用户与其交互

这个风险提示写得相当坦诚，没有回避Agent场景的固有风险。

6. 三层命令调用架构

lark-cli的三层命令架构，是整个工具链灵活性设计的关键。

6.1 Shortcuts（快捷命令）

前缀：以+开头

设计目标：对人类与AI友好化封装，内置智能默认值、表格输出和dry-run预览。

示例：

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

# 发送消息
lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"

# 创建文档
lark-cli docs +create --title "周报" --markdown "# 本周进展\n- 完成了X功能"

设计特点：

• 智能默认值减少参数填写
• 结构化输出便于AI解析
• 支持--dry-run预览效果

Shortcuts适合日常高频操作，参数少、逻辑简单。

6.2 API Commands（API命令）

来源：从飞书OAPI元数据自动生成

筛选机制：经过评测与准入筛选，100+精选命令与平台端点一一对应

示例：

# 列出日历
lark-cli calendar calendars list

# 查看日程实例
lark-cli calendar events instance_view --params '{"calendar_id":"primary","start_time":"1700000000","end_time":"1700086400"}'

生成机制：

• 基于飞书官方OAPI元数据自动生成
• 通过评测与质量准入筛选
• 与平台API保持同步

API Commands适合需要精确控制参数的场景，比Shortcuts更灵活，比Raw API更友好。

6.3 Raw API Calls（原始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\"}"}'

适用场景：

• CLI尚未封装的新API
• 需要完全控制参数的场景
• 快速验证API行为

Raw API是兜底方案，覆盖所有飞书开放平台能力。

6.4 架构设计原理

三层架构的设计哲学：

• Shortcuts：解决80%的常见场景，追求易用性
• API Commands：解决19%的复杂场景，平衡易用性和灵活性
• Raw API：解决1%的极端场景，追求完全控制

这种分层设计，让lark-cli既能服务想快速上手的普通用户，也能满足需要精确控制的高级用户。

三层命令调用架构

输出格式也做了分层设计：

--format json      # 完整JSON响应（默认）
--format pretty    # 人性化格式输出
--format table     # 易读表格
--format ndjson    # 换行分隔JSON（适合管道处理）
--format csv       # 逗号分隔值

分页控制：

--page-all                  # 自动翻页获取所有数据
--page-limit 5              # 最多获取5页
--page-delay 500            # 每页请求间隔500ms

Schema自省：

lark-cli schema                                    # 列出所有服务
lark-cli schema calendar.events.instance_view      # 查看特定API参数结构

这些功能对AI Agent特别友好——Schema自省让Agent可以动态发现API结构，不需要硬编码。

总结

lark-cli的核心价值可以概括为一句话：让人类和AI Agent都能在终端中高效操作飞书。

从调研素材来看，几个关键设计决策值得学习：

• Agent-Native设计：从第一行代码就面向Agent场景，不是事后适配
• 三层架构：Shortcuts/API Commands/Raw API分层，适应不同场景
• 双重身份体系：Bot vs User分离，权限边界清晰
• 辅助决策哲学：提供智能建议，让用户做最终决定
• 安全优先：多层防护+明确风险提示

如果你的工作流重度依赖飞书，或者想用AI Agent自动化处理飞书上的事务，lark-cli值得尝试。

好啦，谢谢你观看我的文章，如果喜欢可以点赞转发给需要的朋友，我们下一期再见！敬请期待！