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 calendar +agenda(查看日历日程),lark-cli 就会自动:
搞清楚用哪个账号 拿到正确的权限令牌 调用正确的飞书 API 把返回结果整理成 AI 能直接读的结构化数据 如果出错,告诉 AI 该怎么修
💡 换个角度看:为什么这是一个"AI Agent 时代"的范本?
越来越多的企业在问同一个问题:我们已有的 SaaS 服务,怎么才能让 AI Agent 直接调用?
答案就在 lark-cli 的设计里。它不是在"重造"飞书的 API,而是在飞书 API 之上包了一层 AI 友好的壳。这个"壳"解决了三个最关键的问题:
- 翻译问题
:AI 先按 lark-cli 暴露的命令口径组织输入;lark-cli 再把这条命令翻译成正确的飞书 API 调用 - 容错问题
:出错了不止告诉你"出错了",还告诉你怎么修——AI 可以自己修 - 安全问题
: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)输入:
旅程开始:
注意:在用户输入命令之前,AI Agent 已经按 Skills 的指导完成了决策。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": [...… |