本文基于一次真实上手飞书 CLI（lark-cli）的对话记录整理，覆盖安装、登录、常用命令、通讯录与发消息示例、权限与可见范围等核心主题。读完即可动手。

飞书 CLI 是什么

lark-cli 是飞书/Lark 开放平台的命令行工具（GitHub）。

它让人类与 AI Agent 在终端里完成应用配置、OAuth 授权，并调用文档/IM/日历/邮箱/多维表等 API。

核心特性：

• 快捷命令（以 + 标识），按资源域拆分的子命令
• 通用 api 入口，覆盖任意 REST 路径

环境要求

• 推荐：已安装 Node.js（含 npm/npx）
• 源码编译（可选）：Go 1.23+、Python 3

安装与 Skills

可在项目目录或本机终端执行，也可直接交给你的 AI 编程工具：

npm install -g @larksuite/cli
npx skills add larksuite/cli -y -g

第二条命令会将官方提供的 19 个 Agent Skills（如 lark-doc、lark-im、lark-contact 等）安装到本机，方便在Claude Code / Codex 等工具里按说明调用 CLI。

首次配置与登录

lark-cli config init
lark-cli auth login --recommend
lark-cli auth status

• config init：交互式创建/绑定开放平台应用（如 appId 等）
• auth login：--recommend 会按推荐集合申请一批常用 scope（也支持按域或单一 scope 逐步授权）
• auth status：查看当前用户是否登录、token 有效期、已授权 scope

Agent 场景提示：可在后台执行 config init --new、auth login --recommend。终端会生成授权链接，需在浏览器完成授权。

顶层命令速查（能做什么）

• config：全局配置（应用、环境等）
• auth：登录/登出、scope 校验
• doctor：配置、鉴权与连通性自检
• schema：检索 OpenAPI 方法、参数与所需 scope
• api：发起任意 REST 路径请求的通用入口
• contact：通讯录（搜用户、查用户信息）
• im：即时消息与群（发消息、搜群、拉消息等）
• docs：云文档/云空间文件
• wiki：知识库节点信息（需与 docs/drive/sheets 搭配）
• sheets：电子表格/多维表格
• calendar：日历（日程/任务）
• mail：邮箱 / 视频会议 / 妙记
• event：事件订阅（长连接等）

日常建议：优先用各域的 + 快捷命令；参数不确定时先 schema；冷门接口再走 api。

身份说明：user 与 bot

• user（用户 OAuth）：可访问个人资源类能力（如按用户权限搜索通讯录、读取自己的日历等），能力仍受应用 scope 限制。
• bot（应用机器人/tenant token）：适合以应用身份发消息等操作。

示例对比：

• contact +search-user 通常要求 user 身份
• im +messages-send 官方封装一般以 bot 发信（需开通 im:message:send_as_bot 等；且机器人需在群内或与对方可私信）

上手示例：通讯录与发消息

1）搜索同事（用户身份）

lark-cli contact +search-user --query <姓名或邮箱关键词> --page-size 50 --as user

从返回的 JSON 中取到 open_id（形如 ou_xxx）。

2）私聊发文本（机器人身份）

lark-cli im +messages-send --as bot --user-id ou_xxx --text 这是一条AI发的信息

发送前可加 --dry-run 预览。若失败，优先排查：机器人是否在群内、是否可与对方私信、scope 与可见范围是否满足。

常见疑问：「我能搜到多少联系人？」

开放平台没有「通讯录总人数」的单一字段。可用多组关键词对 +search-user 的结果去重，估算「当前应用可见范围内可搜到的人数」。若多次采样仍只有自己，多半是应用可见范围/通讯录可见性仅包含本人或范围过窄——需在开放平台调整「应用可用范围」等设置。

内置帮助

lark-cli --help
lark-cli docs --help
lark-cli im +messages-send --help

安全提示

根据 lark-cli 文档：授权后，AI/脚本可在已授权 scope 内代表你操作飞书，存在误发消息、数据泄露等风险。建议：

• 控制应用可见范围
• 按需最小化 scope
• 对危险写操作使用 --dry-run 预览

附录

• 信息整理日期：2026-03-29
• 适用对象：已能使用 npm，且在飞书开放平台创建应用并完成用户登录的读者
• 官方说明：README.zh.md

番外：飞书为 AI 准备的 19 个官方 Agent Skills

先把话讲清楚：Skills 不是魔法，是「工作手册」。若你已安装 lark-cli，大概率也执行过：

npx skills add larksuite/cli -y -g

它做的事很朴素：把飞书团队在 GitHub 开源的一整套 Skill 说明文件装到你的 Agent 目录里（Cursor / Claude Code / Codex 等会按规则读取）。

每个 Skill 就是一本带目录的操作手册：什么时候用、优先走哪条 CLI 快捷命令、遇到权限坑如何处理。真正干活的是 CLI，Skills 只是让大模型别盲猜参数，少浪费你的调用额度。

下面按「你日常在飞书里的实际路径」来梳理这 19 个 Skills：

办公主线：从「我是谁」到「把事办了」

• lark-shared：底座技能。配置、登录、scope、user/bot 切换、权限不足的处理都在这里。你说「帮我登飞书/查我授权了哪些权限」，应先走它（如 lark-cli config init、lark-cli auth login、lark-cli auth status）。它是总闸，别跳闸。
• lark-contact：找人、认人、对齐 open_id。如「帮我搜某位同事的飞书账号」。常用：contact +search-user、contact +get-user。
• lark-im：私聊、群聊、搜聊天记录、下文件。适合「给某群发通知」「把会话里的文件拉取下来」。注意大量发信场景偏 bot 身份，需考虑「谁能看见机器人」「机器人是否在群内」。
• lark-calendar：日程/忙闲/议程。「看下我今天安排」「帮我约会」「谁有空」。它是时间线总管。
• lark-task：待办与协作任务。把聊天里的「事」拎成可追踪的任务结构。
• lark-mail：邮箱读/发/搜、草稿、文件夹。重度飞书邮箱用户可借此让 AI 做「桌面邮客户端」式处理（受 scope 限制）。

内容与文件：写稿、做表、整理空间

• lark-doc：云文档的读/写/改/搜主场。比如「把这篇文章同步到我的飞书文档」，应优先走 docs +create/docs +update，而非人工复制。
• lark-wiki：知识库导航与节点关系。当材料挂在知识空间里，需先用 wiki.spaces.get_node 搞清真正的 obj_token，再决定用 doc/drive/sheet 哪套 API。
• lark-drive：云空间文件、评论、权限。适合「把这个文件上传到云空间指定目录」。
• lark-sheets：传统电子表格。做数据搬运、批量读写、导出表格。
• lark-base：多维表格（Base）。用于项目台账、内容排期、资源库等；别与 sheets 混淆。
• lark-whiteboard：画板/图表 DSL。可在云文档里落一块白板，让 AI 按 DSL 画流程图/导图。注意已有画板内容需走专门更新链路，不能当作纯文本覆盖。

会议与信息回收：开完会别只留在记忆里

• lark-vc：视频会议记录与纪要产物检索。「这周我开过哪些会」「某场会的要点在哪」。
• lark-minutes：妙记（Minutes）元数据与 AI 产物。拿到妙记链接后，可拉标题、摘要、章节、待办等。
• lark-workflow-meeting-summary：会议纪要工作流。将一段时间内的会议汇总为结构化报告，适合做复盘。
• lark-workflow-standup-report：「站立会式」摘要。把日程与待办拼成「今天要干啥」的一页纸，对个人创作者也像日更工作台。

高阶玩家：事件流、原生 API、自己造 Skill

• lark-event：事件订阅（WebSocket）。用于实时监听消息/变更，替代轮询。
• lark-openapi-explorer：官方 OpenAPI 深度检索。当现有 Skills 和 CLI 子命令无法覆盖时，指导 Agent 查更底层接口；配合 lark-cli schema/lark-cli api 使用。
• lark-skill-maker：自定义 Skill 脚手架。将公司内部流程（如「固定三张表 + 两段审批」）沉淀成可复用的 skill。

我的自媒体工具台账

• 写稿前：calendar + task 把「截稿/拍摄/发布」钉在时间线上
• 写稿中：doc/wiki 沉淀素材到知识库，而非散落在聊天
• 发稿后：im 把关键链接丢回协作群，drive 归档素材包
• 复盘周：workflow-meeting-summary/workflow-standup-report 一键梳理「这周到底忙了啥」