让 AI Agent 真正用起来飞书：lark-cli 实战指南

最近我在折腾一个挺有意思的方向：让 AI Agent 真正“用”起来飞书，而不是停在“发个群机器人消息”这种程度。起因很简单——团队的多维表格里堆了几百条需求和缺陷记录，每次要做周报、筛重复、同步状态，要么人工在网页里点半天，要么写一堆临时脚本去调开放接口，非常啰嗦。后来开始用 lark-cli 把飞书的常用能力收敛到命令行里，再把我正在用的 AI Coding Agent 接进去，整个研发协作的体验一下子就不一样了。

这篇文章我想把这套思路完整拆开：lark-cli 到底是什么、它补上了飞书开放平台的哪块短板、怎么把它变成 AI Agent 的一只手，以及我在真实项目中踩过的权限、错误码、越权这些坑。如果你正在做办公自动化，或者想把飞书多维表格、消息机器人、云文档能力接进自己的 Agent 工作流，这篇文章应该能帮你省下不少试错时间。

1. 先说结论：lark-cli 是飞书能力的“本地指挥官”

很多人第一次听到 lark-cli，会下意识问一句：飞书不是有网页、有客户端吗，我要命令行干什么？

这问题问得挺好。我们得先搞明白，飞书开放平台本身是提供了完整 HTTP API 的，理论上你直接用代码去请求 open.feishu.cn 的接口也能实现自动化。但实际写起来你会发现痛点非常明显：每次调用都要处理 tenant_access_token 或者 user_access_token 的申请和刷新，要拼接复杂的请求体，要把返回的错误码翻译成人话，还要在不同脚本里反复复制粘贴那段鉴权代码。我的感觉是，开放 API 是给“程序”用的，而 lark-cli 是给“人和智能体”用的——它把繁琐的鉴权、接口调用、结果格式化全部包装成了一条条短命令。

lark-cli 解决的核心问题有三层：

• 身份统一管理。你不再需要在每个脚本里配置 app_id、app_secret，也不用考虑 token 过期后怎么续期。CLI 会在本地维护一份凭证状态，调用任何子命令之前自动处理鉴权逻辑。
• 高频操作命令化。发群消息、查多维表格记录、建云文档、拉通讯录，这些日常频率最高的动作全部收敛成 lark bitable search、lark im send、lark docs create 这类短命令，拿 shell 就能直接跑。
• 给智能体提供统一入口。AI Agent 最擅长的是“理解意图 + 调用工具”，而命令行天然就是工具的最佳载体。Agent 不需要去记飞书 API 的文档，只需要知道 lark-cli 有哪些子命令、参数是什么，就能完成大量办公操作。

这里要特别说明一句：飞书官方和社区生态里，叫 lark-cli 的封装可能不止一个，不同团队维护的版本命令风格也有差异。但这不影响我们的讨论，因为这一类工具的设计哲学是共通的——把“飞书能力”从网页点击变成可编程的本地指令，让脚本、定时任务和 AI Agent 都能平等地调用。

2. lark-cli 的核心能力地图：它到底能操作飞书的哪些东西

我在实际使用中把 lark-cli 的能力分成了五块：认证与身份、即时消息、多维表格、云文档、通讯录与搜索。每一块背后对应的是飞书开放平台的成熟能力，CLI 只是把这些能力重新做了一层“人话包装”。

2.1 认证与身份：免登录背后的机制

热搜词里很多人搜“飞书免登录”“飞书网页应用免登录 vue”，说明大家对这个机制特别感兴趣。实际上，办公软件与自建系统的身份打通，从来不是“真的不用登录”，而是把登录动作交给了更底层的凭证体系。

在 lark-cli 的场景里，它支持两种凭证模式。一种是以应用身份调用，CLI 拿 app_id + app_secret 换 tenant_access_token，代表这个应用去操作飞书，适合机器人和后台任务；另一种是以用户身份调用，走 OAuth 流程换取 user_access_token，适合“代某个用户去创建文档、发消息”的场景，操作会带上用户身份，在审计和权限上更规范。

如果你是自己本地调试，我建议优先用应用身份，省事；如果要上线给团队用，就得做用户授权流程。很多初接触的人在这里容易混淆：“为什么我用应用身份发的消息，在群里不显示发送人头像？”因为那本质上是“某个应用机器人”发的，不是“你”发的。搞清楚这套关系，后面排查很多诡异问题都会顺畅很多。

CLI 一般会把这些 token 缓存在本地配置目录，比如 ~/.lark-cli/config.json，不同的子命令会共享这份状态。这也是它比散装脚本干净的地方：凭证只有一个来源