时光里的沙漏最近我在折腾一个挺有意思的方向：让 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 都能平等地调用。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
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，不同的子命令会共享这份状态。这也是它比散装脚本干净的地方：凭证只有一个来源，需要轮换时改一处就够了。
2.2 即时消息：把一个群变成程序输出口
我在 lark-cli 里用得最频繁的功能就是发消息。无论是 CI/CD 流水线的构建结果、监控系统的告警，还是 Agent 跑完某个任务的总结，都可以通过一条命令直接送达指定的群或个人。
典型用法是这样的：
bash复制lark im send --receiver "oc_xxxx" --msg_type text --content "构建成功：v1.2.3 已发布到预发环境"
有些版本的 CLI 还支持富文本、交互卡片和@指定人。卡片消息尤其适合给 Agent 用——可以把状态、结论、下一步动作都结构化地展示出来，比纯文本清晰得多。
另一个很实用的点是：飞书的 webhook 机器人只能单向“往群里推消息”，而 lark-cli 用的是开放平台 API，所以你能拿到完整的发送回执，判断消息到底有没有发出去、被谁接收了。别小看这个差别，做自动化任务时，“我要确认它真的发出去了”很重要。
2.3 多维表格：自建轻量业务系统的最佳入口
多维表格是飞书生态里最受欢迎的能力，没有之一。它是表格，但更接近一个轻量数据库：有字段类型、有视图、有自动化流程。很多团队用多维表格管需求、管客户、管排期、管工单，本质上是在飞书里搭了一套业务系统。
lark-cli 对多维表格的操作是重头戏。比如我要把表格里的“待处理”记录全部捞出来：
bash复制lark bitable search --app_token "bascnxxxx" --table_id "tblxxxx" \
--filter '{"conditions":[{"field_name":"状态","operator":"is","value":["待处理"]}]}' \
--fields "标题,负责人,优先级,截止日期"
也可以批量新增记录、更新字段状态、删除过期数据。这些操作如果手写 HTTP 请求，每个都要查一遍接口文档；而 CLI 把参数规则固定下来，你只需要记住字段类型是文本、日期还是人员，就能比较顺畅地写出来。
多维表格在 Agent 场景里还有一个不可替代的价值：它是结构化的记忆库。Agent 的对话上下文窗口有限，但多维表格可以无限增长。你完全可以让 Agent 把每轮任务的关键结论写入表格，下次直接查询表格来“回忆”之前做过什么。
2.4 云文档与文件：从“写文档”到“组织知识”
云文档操作对很多自动化场景来说很刚需。比如每天早晨自动生成一份前一天的销售数据日报，存成飞书文档，并把链接发到管理群；再比如周报场景，让 Agent 去读取多维表格数据，生成结构化文档。
lark-cli 能做的事情包括创建文档、追加内容块、读取文档纯文本、上传文件到云空间等。我在实践中发现，读取文档给 Agent 喂上下文是特别常见的使用方式。我们可以把团队沉淀的需求文档、复盘文档、技术方案全部放在飞书里，Agent 真正要做事之前，先用 CLI 把这些文档内容拉下来，作为参考上下文，这对回答的准确性帮助非常大。
2.5 通讯录与搜索：让 Agent 知道你该找谁
最后一个能力是通讯录的读取和组织架构查询。自动化任务里经常会碰到“这个问题该拉谁处理”“哪个组的负责人是谁”之类的需求。通过 CLI 查询通讯录，Agent 就能自己找到合适的人，然后往对应的群里发消息或者@人。
搜索能力也很实用。你可以在 CLI 里输入关键词，直接搜飞书上的消息、文档、多维表格记录，而不需要切到客户端页面去翻。这个能力相当于给 Agent 装了一个“全公司信息检索”的接口。
3. 把 lark-cli 接进 AI Agent：工具调用的三条路线
聊完能力地图，接下来是最关键的问题：AI Agent 到底怎么调用 lark-cli？
我目前实践下来有三条成熟路线，不同路线适合不同人群。
3.1 路线一：让 Agent 通过 Shell 工具直接调用命令
这是最直接的方式。无论是 Claude 的 computer use 模式、还是 Codex CLI/Cursor 这类 AI coding agent，都天然支持让模型执行 shell 命令。你只需要把 lark-cli 的用法说明（比如子命令列表和参数示例）作为系统提示词的一部分喂给 Agent，它在需要操作飞书时，就会自己拼接命令并执行。
比如我对 AI Agent 说：“把多维表格里所有状态为待处理且优先级为紧急的需求整理成一段文字，发到产品群。”Agent 会先调用 lark bitable search 查出记录，再调用 lark im send 把结果发进群。整个过程你我都不用写一行 Python 逻辑。
这里有一个经验：命令帮助信息要给足。我会在 Agent 的 workspace 里放一个 lark-cli-help.md，把常用命令的完整示例复制进去，让 Agent 在拿不准参数时先翻文档。别指望模型能凭空记住所有 CLI 参数，这不符合大模型的工作方式。
3.2 路线二：用 Python/Rust 等语言封装成 function calling 工具
如果你用的是 OpenAI function calling 或者各类 Agent 框架，更优雅的方式是把 CLI 封装成一个个函数描述。Agent 根据用户意图选择函数，然后由你的代码去执行真正的 CLI 命令。
这个方案的收益是可以严格控制参数。模型只负责传参，不直接拼接 shell 命令，能规避一部分提示注入和安全风险。而且你可以把返回结果做后处理：比如把多维表格返回的 JSON 压缩成更简洁的文本，减少模型上下文占用。
3.3 路线三：对外暴露成 HTTP / MCP 服务，供远程 Agent 调用
当 Agent 和飞书操作不在同一台机器上，或者有多个 Agent 需要共享一套飞书能力时，我会把 lark-cli 再包一层，对外暴露本地 HTTP 服务，让其他进程通过 REST API 间接调用。
近两年 MCP 协议很火，把 lark-cli 包成 MCP 工具服务器也是可行的方向。这样做的好处是标准统一，支持 MCP 的 Agent 客户端可以自动发现工具列表，不需要额外配置。Coze、Dify 这类低代码 Agent 平台也都在拥抱类似思路。理论上你可以在 Coze 里建一个 Bot，让它通过内部服务去操作企业飞书，实现类似“智能体会用办公软件”的效果。
3.4 选型参考：三条路线怎么选
| 路线 | 适合人群 | 优点 | 需要注意的坑 |
|---|---|---|---|
| Shell 直接调用 | AI coding agent 重度用户、本地开发 | 接入快、灵活 | 没做好权限隔离时风险较大 |
| Function calling 封装 | 做企业级 Agent 应用 | 参数可控、防注入 | 需要写胶水代码 |
| HTTP / MCP 服务化 | 多 Agent 共享能力、需要跨进程 | 易扩展、统一鉴权 | 要额外考虑 Nginx、防火墙等问题 |
我个人的建议是：自己本地玩就选路线一，秒级接入；正经在公司里做工具链选路线二或三，安全可控比省事重要。
4. 一个真实可落地的完整链路：AI Agent 自动分析日志并告警到飞书
光讲概念没有用，我来分享一个我最近实际跑通的场景，把这个项目从需求、实现到踩坑的全部过程复现出来，你跟着做也能跑通。
4.1 业务需求与整体设计
业务背景是这样的：我们有一套 ES（Elasticsearch）日志集群，日常运维需要关注其中的 ERROR 日志。以前是人工去 Kibana 查，效率低，而且没法实时盯。我的目标是：搭一条自动化链路，每隔几分钟去 ES 里查一次最近 5 分钟的错误日志数量，如果超过阈值，就让 AI Agent 做一次粗浅的智能分析，把结论和建议发到飞书运维群。
整体链路设计：
- 用 Python 脚本去 ES 的 REST API 拉取新增错误日志。
- 把日志文本交给大模型做意图分类和根因预判。
- 让 Agent 调用 lark-cli 发告警卡片到飞书群。
- 同时把这次告警记录写入多维表格，方便后续统计和复盘。
4.2 从零开始到跑通：每一步都做了什么
第一步，先准备一个飞书自建应用。到飞书开放平台创建应用后，开启“机器人”能力，并申请 im:message:send_as_bot 和 bitable:app:readwrite 这两个权限。这一步很多人会漏，但其实权限申请比代码本身更容易出问题——权限没开对，调用接口的时候就会被 2700002 这类错误码拦住。
第二步，用 lark-cli 做连通性测试。我习惯先发一条最简单的文本消息，确认应用、权限、群 ID 都是通的：
bash复制lark im send --receiver "oc_xxxxx" --msg_type text --content "告警链路连通性测试"
如果这条命令能正常返回，再去做复杂的多维表格查询和写入。
第三步，写 ES 查询脚本。核心代码并不复杂，就是请求 ES 的 _search 接口，传入时间范围和过滤条件，拿到聚合结果：
python复制import requests
from datetime import datetime, timedelta
es_url = "http://your-es-host:9200/logs-*/_search"
query = {
"query": {
"bool": {
"filter": [
{"range": {"@timestamp": {"gte": f"now-5m"}}},
{"match_phrase": {"level": "ERROR"}}
]
}
},
"size": 20,
"sort": [{"@timestamp": "desc"}]
}
resp = requests.get(es_url, json=query, auth=("elastic", "your-password"))
data = resp.json()
hits = data["hits"]["hits"]
print(f"最近5分钟错误日志 {len(hits)} 条")
第四步，把日志数据交给 AI 做分析。这里我用的是一个本地运行的模型服务，把原始错误堆栈丢进去，让它输出“错误类型”“可能影响范围”“处理建议”三个字段。模型返回的 JSON 结构可以约定死，方便后面解析。
第五步，由 AI Agent 把分析结果发送到飞书群。Agent 在这一步会调起 lark-cli：
bash复制lark im send --receiver "oc_xxxxx" --msg_type interactive \
--content '{"config":{"wide_screen_mode":true},"header":{"template":"red","title":{"content":"线上日志异常告警"}},"elements":[{"tag":"div","text":{"content":"近5分钟新增错误日志 187 条，主要集中于订单服务超时。"}},{"tag":"action","actions":[{"tag":"button","text":{"content":"查看详情"},"url":"https://kibana.example.com"}]}]}'
飞书卡片消息用 JSON 结构拼，看起来复杂，其实都是文档里写好的卡片模板。这里特别想提醒一句：卡片消息的字段名和普通 JSON 有区别，少一个 tag 或多一个多余字段，发送就会报参数错误。第一次调试时建议先用最简单的一段纯文本验证链路，通了你再去美化卡片。
第六步，把告警写入多维表格。Agent 接下来执行：
bash复制lark bitable create --app_token "bascnxxxx" --table_id "tblxxxx" \
--fields '{"时间":"2026-02-10 10:30:00","来源":"订单服务","标题":"连接池耗尽","状态":"待处理"}'
多维表格的字段类型会影响写入格式。比如“时间”字段如果是日期类型，你传字符串一般也能被自动转换；但“人员”字段必须传用户的 open_id 或 user_id，传中文名大概率会报错。建议把一次成功写入的 JSON 字段保存下来，之后照着复用。
4.3 告警链路中出过的三个真实问题
第一个问题：错误码 2700002。这个错误我在不同项目里都遇见过，不同语境下含义可能不同，但绝大部分情况都和“权限不足”或“凭证无效”有关。排查思路分三步：先看是不是 tenant_access_token 没刷新；再看应用是否开通了对应权限；最后看请求参数里的资源 ID 是否属于当前应用。
第二个问题：消息发不出去了，但没有报错。排查发现是飞书针对同一内容在短时间内的发送频率做了限制。告警类场景最容易触发这个限制，尤其是你的 Agent 连续用同一段文本发测试消息的时候。解决办法是丰富消息内容或者降级发送频率，别把告警脚本写成每秒钟打一次的循环。
第三个问题：ES 里查出来的日志带有很多转义符和堆栈噪音，直接丢给模型后分析结果一塌糊涂。后来我在预处理里做了清洗：去掉无意义的线程名、时间戳前缀，截断超长异常堆栈，只保留前 20 行。模型的分析质量瞬间提升了。这个经验其实也适合所有 Agent 项目——不是模型不够聪明，是你喂给它的原始数据太脏。
5. 权限与护栏：让 Agent 安全地用飞书，而不是乱用飞书
给人体分配权限时，大家都很谨慎；但给 Agent 分配权限时，很多人反而不当回事。这其实是个巨大的隐患。AI Agent 不是人，它可能在一次意外的提示注入后执行你完全没预期到的操作；也可能因为对业务不熟，批量把某张表的状态全部改错。
5.1 最小权限原则是底线
在自建应用配置里，飞书会区分很多不同的权限项。比如 im:message、bitable:app、docx:document，你不需要一次性全开。按需开、用完再评估、定期清理，这是基本操作。我见过最夸张的情况是，同事给自己搭建的内部工具开了“管理员权限”，也就是应用能读企业内所有文档和数据。一旦这个应用被 Agent 误操作，风险极大。
5.2 人机协同：关键动作必须二次确认
对于“发送到全员群”“批量更新多维表格”“删除记录”这类破坏性或影响面大的操作，我一定会在 Agent 的工作流里留一个人工确认步骤。实现方式不复杂：Agent 先执行只读操作，把将要变更的内容整理出来，以卡片消息发到某个审批群里，然后等待一个“确认执行”的关键词，才继续执行写操作。这个“先预览、后执行”的模式，在初期使用 Agent 时尤其值得保留。
5.3 不要把 secret 留在 Agent 的工作目录里
AI Coding Agent 在生成代码时，极有可能把你配置文件里的 app_secret 一起带到代码里，然后被提交到仓库。为此我做了两件事：一是在 .gitignore 里强制忽略所有 *.json 的本地凭证文件；二是在环境变量层面注入凭证，让 lark-cli 从环境变量读取而不是从命令行参数读取。能用环境变量就别用配置文件，能配置权限就别用管理员密钥。
5.4 给 Agent 做命令白名单
如果你走的是 Function Calling 路线，对 Agent 暴露哪些函数不是由模型自己决定的，而是由你写代码时决定的。所以我的建议是：绝对不要开放“执行任意 shell 命令”给 Agent，而是只暴露 search_records、send_message、create_doc 这样的具体函数。Agent 只能在你的预设里跳舞，这并不影响它的智能，反而能让结果更可控。
6. 办公软件与 Agent 的结合会往哪里去
最后聊一点趋势层面的个人观察。这几年 Agent 相关的话题越来越热，“ai agent 2026 发展趋势”这类热搜词也反映了大家对这个方向的强烈好奇。我认为和办公软件结合会是 Agent 最快落地、最容易产出价值的场景之一，因为办公软件本身就承载着企业里最密集的文档流、审批流和信息流。
现在的 AI Coding Agent 已经能自己读代码、改代码、运行测试了。同样的模式完全可以迁移到“办公操作”里：Agent 读取飞书文档里的需求说明，自己判断这个需求涉及哪些数据和群组，再基于多维表格的结构化数据去执行任务，最后把结果写回文档并向相关人员汇报。这套范式一旦跑通，很多偏“信息搬运”性质的工作就会被大幅提效。
另一个方向是 Agent 之间的协作。未来可能不再是“一个人 + 一个 Agent”的单机模式，而是多个 Agent 各自负责不同的系统——有的盯日志，有的管理值班表，有的负责知识库更新——它们通过飞书群作为信息交换中枢，互相发消息、同步状态。lark-cli 这类工具会在里面扮演“统一接口层”的角色，让每个 Agent 都能用最标准的方式读写飞书的数据。
低代码平台的作用也会越来越大。像多维表格自带的自动化流程、Coze 这类平台搭出的 Bot，本质上是在降低“人指挥 Agent 干活”的门槛。CLI 在底层提供能力，可视化平台提供交互体验，两者是互补关系。
我在实际项目里最深的体感是：工具和 API 越丰富，Agent 能发挥的空间就越大；但反过来说，能不能把 Agent 的权限边界、数据边界定义清楚，才是决定项目成败的关键。技术从来不是瓶颈，治理和规范才是。
如果你也想在自己的工作流里尝试这条路线，我建议不要一上来就铺大摊子。先选一个你每周会重复五遍以上的飞书操作，比如整理多维表格、发日报、同步会议纪要，用 lark-cli 把它做成一条命令，再接进 Agent 试一试。等手感成熟了，再逐步扩大它的行动半径。这个过程不会太复杂，但跑通一个完整的小闭环带来的成就感，以及后续节省的时间，绝对值回你投入的周末。