lark-cli:企业 SaaS 走向 AI 化时,值得对照的一份范本

lark-cli:企业 SaaS 走向 AI 化时,值得对照的一份范本

如果你正琢磨:怎么让既有产品能力被 AI(或 Agent)稳定调用,而不是只靠对接文档和运气拼 prompt——lark-cli 在飞书场景里走通的分层与约定,值得认真读一遍。


前言:lark-cli这个项目到底是干什么的?

想象一个场景:你让 AI 助手帮你做一件事——"帮我在飞书日历上,查一下明天下午的会议安排"。

最容易想到的,往往是「让 AI 直接去调飞书 Open API」:端点怎么选、权限怎么配、参数怎么传、返回里哪一段才是有效信息……全要在一次对话里凑齐、读对——链路一长,任何一环都可能写偏、读错。

lark-cli 做的事情很简单:它充当了 AI 和飞书之间的"翻译官"。 翻译官不止负责把请求译成飞书 API,还事先定好「该怎么说」:子命令、参数、输出格式都有约定。AI 助手要做的,就是按这套约定,把用户意图整理成一串可执行的 lark-cli ... 命令。

用户  ───自然语言───→  AI助手  ───按翻译官约定组织命令───→  lark-cli  ───转成 API 请求───→  飞书服务器
                                                       ↑
                                                      "翻译官"

比如用户想查日程,AI 在搞清意图后,会按约定发起 lark-cli calendar +agenda(查看日历日程),lark-cli 就会自动:

  1. 搞清楚用哪个账号
  2. 拿到正确的权限令牌
  3. 调用正确的飞书 API
  4. 把返回结果整理成 AI 能直接读的结构化数据
  5. 如果出错,告诉 AI 该怎么修

💡 换个角度看:为什么这是一个"AI Agent 时代"的范本?

越来越多的企业在问同一个问题:我们已有的 SaaS 服务,怎么才能让 AI Agent 直接调用?

答案就在 lark-cli 的设计里。它不是在"重造"飞书的 API,而是在飞书 API 之上包了一层 AI 友好的壳。这个"壳"解决了三个最关键的问题:

  1. 翻译问题
    :AI 先按 lark-cli 暴露的命令口径组织输入;lark-cli 再把这条命令翻译成正确的飞书 API 调用
  2. 容错问题
    :出错了不止告诉你"出错了",还告诉你怎么修——AI 可以自己修
  3. 安全问题
    :AI Agent 可能被恶意 Prompt 操控,所以每一层都要防注入、防越权

如果你有一个 SaaS 产品,想把它的能力开放给 AI Agent,这篇文档就是你的"参考答案"。


一、整体结构:Skills(AI 说明书)+ CLI(执行引擎)

lark-cli 不是一个普通的命令行工具——它是一个双组件系统,由两部分配合工作:

  • **Skills(AI 技能包)**:一套 Markdown 文档(SKILL.md),安装在 AI Agent 内部。它们教导 AI 飞书的业务知识、API 使用方式、工作流程、约束规则和最佳实践。Skills 回答的核心问题是:"AI 怎么知道该调哪个命令?怎么组合多个命令完成一个复杂任务?"
  • **CLI(命令行工具)**:编译好的 Go 可执行文件,真正负责执行操作——调用飞书 API、处理认证、格式化输出、多层安全过滤。

Skills 和 CLI 的关系,就像"驾驶员培训手册"和"汽车":

  • 光给 AI 一个 CLI 工具(就像给人一辆车但不教他怎么开),AI 不知道该调什么命令
  • 光有 Skills 没有 CLI(就像有驾驶手册但没有车),也到不了目的地
  • 两者配合
    :Skills 告诉 AI "遇到 X 场景就调用 Y 命令,如果出错就执行 Z 修复",CLI 负责执行
┌──────────────────────────────────────────────────┐
│           AI Agent(Claude Code 等)              │
│                                                  │
│  ┌────────────────────────────────────────────┐  │
│  │  Skills 层(25+ 个业务域技能包)            │  │
│  │                                            │  │
│  │  lark-shared    认证、权限、安全规则        │  │
│  │  lark-calendar  日历日程操作工作流          │  │
│  │  lark-im        消息收发工作流              │  │
│  │  lark-doc       文档协作工作流              │  │
│  │  lark-task      任务管理工作流              │  │
│  │  lark-vc        视频会议工作流              │  │
│  │  ... 等 25+ 个业务域                       │  │
│  │                                            │  │
│  │  每个 Skill 包含:                          │  │
│  │  • 业务域知识(核心概念、资源关系)          │  │
│  │  • 工作流程(场景A→步骤1→步骤2→...)        │  │
│  │  • 约束规则(如日历API一次只能查40天)       │  │
│  │  • 错误恢复策略                             │  │
│  │  • Shortcut 推荐(优先使用 +agenda 等)     │  │
│  └────────────┬───────────────────────────────┘  │
│               │ Skills 指导 AI 调用正确的命令     │
└───────────────┼──────────────────────────────────┘
                │
                ▼
┌──────────────────────────────────────────────────┐
│          lark-cli CLI 二进制文件                  │
│                                                  │
│  ┌────────────────────────────────────────────┐  │
│  │  快捷命令层 (Shortcuts)                    │  │
│  │  +agenda, +create, +search-user ...       │  │
│  │  "说人话就行,一个加号搞定"                 │  │
│  ├────────────────────────────────────────────┤  │
│  │  API 命令层                                │  │
│  │  calendar events list, im messages send... │  │
│  │  "按服务域和资源分类,结构化调用"            │  │
│  ├────────────────────────────────────────────┤  │
│  │  原始 API 层                               │  │
│  │  lark-cli api GET /open-apis/...           │  │
│  │  "100% 覆盖,任何 API 都能调"              │  │
│  ├────────────────────────────────────────────┤  │
│  │  基础设施层 (internal/)                    │  │
│  │  认证、输出格式、安全过滤、配置管理、HTTP    │  │
│  │  "所有命令共享的底层能力"                   │  │
│  └────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘

为什么要这样设计?

打个比方:你去餐厅吃饭。

  • Skills = 菜谱 + 营养指南
    。告诉你"这道菜用什么食材、怎么搭配最好、有什么忌口要注意"。AI 靠 Skills 来判断"用户说'明天下午的会'应该走日历流程还是会议流程"、"飞书日历 API 一次只能查 40 天,如果用户要查 3 个月的日程需要自动分段查询"——这些业务知识不在 CLI 代码里,而在 Skills 里。
  • 快捷命令 = 套餐
    ("给我来份今天的推荐午餐"),快、简单
  • API 命令 = 菜单点菜
    ("宫保鸡丁一份,少辣"),有一定自由度
  • 原始 API = 直接跟厨师说怎么做
    ("鸡胸肉切丁,花生炒香……"),完全自由但复杂

Skills 是整个系统的"智能分发层"——它决定了 AI 在什么场景下使用哪一层命令。 没有 Skills,AI 就像一个拿着全套工具箱但不知道哪个工具该用在哪里的新手;有了 Skills,AI 就像一个经验丰富的老师傅,知道在不同情况下选用最合适的工具。

🤖 AI Agent 视角:为什么 Skills + 分层命令设计对 AI Agent 特别重要?

大多数 CLI 工具只提供"命令",不提供"知识"。但 AI Agent 需要在 token 有限、上下文有限的情况下,快速判断该调哪个命令、传什么参数、怎么处理异常。Skills 解决了这个"冷启动"问题:

  • Skills 层 → AI 的领域知识库
    ("遇到这种情况应该怎么处理"——这是最关键的一层,也是大多数 SaaS 工具缺失的一层)
  • 快捷命令层 → AI 的首选执行入口
    (像函数调用一样简单,一个命令对应一个语义意图)
  • API 命令层 → AI 的备选入口
    (按领域分类,结构化,需要时降级到这里)

  • 原始 API 层 → AI 的最后手段
    (任何 API 都能调,不受快捷命令覆盖范围限制)

这种设计保证了一个关键特性:AI Agent 永远不会被"这个功能快捷命令不支持"卡住——Skills 教它如何根据场景降级到更底层的命令,继续完成任务。


二、一个命令的完整旅程

让我们跟踪一个真实命令从头到尾发生了什么:

用户(或 AI)输入:

lark-cli calendar +agenda --start "2026-05-12"

旅程开始:

注意:在用户输入命令之前,AI Agent 已经按 Skills 的指导完成了决策。Skills 是这场旅程的"起点"。

第0步:AI 决策(Skills 指导)
  用户对 AI Agent 说:"帮我看看明天下午有什么安排"
  → AI Agent 读取已安装的 lark-calendar Skill
  → Skill 告诉 AI:"查看日程用 lark-cli calendar +agenda,时间参数用 --start"
  → AI 决策:执行 lark-cli calendar +agenda --start "2026-05-12"
  (如果没有 Skill,AI 需要自己摸索该调什么命令、传什么参数——很可能出错)

第1步:接待处(启动程序)
  "有人来了,让我看看他要什么"
  → 解析命令:calendar +agenda,参数是 start=2026-05-12

第2步:身份验证(管理员)
  "你是谁?你有什么权限?"
  → 读取本地配置:哦,是张三的飞书账号
  → 检查钥匙串:token 还在这,没过期 ✓
  → 检查权限:你有 calendar:read 权限 ✓

第3步:翻译请求(翻译官)
  "你要查明天的日程 → 我需要调用飞书的 instance_view API"
  → 路径:/open-apis/calendar/v4/calendars/primary/events/instance_view
  → 参数:start_time=..., end_time=...

第4步:发送请求(快递员)
  "带上你的 token(通行证),去飞书服务器取数据"
  → HTTP 请求 → 飞书服务器 → 返回日程列表

第5步:处理结果(整理师)
  "飞书返回了一堆原始数据,让我把它整理好"
  → 去掉已取消的日程
  → 把时间戳转成可读的日期时间
  → 去重排序

第6步:格式化输出(包装师)
  "好了,给你包成标准格式"
  → { "ok": true, "data": [...…
— 以上为试看内容(约 40%),开通会员后阅读全文 —