飞书 CLI

飞书 CLI

首次使用：先安装、再配置和授权

按实际状态执行未完成的步骤；已有可用 CLI 和有效登录时直接复用。以下安装操作必须发生在 Agent 实际运行工具的主机、容器或沙盒 中。

正确识别软件包与命令

项目	值
平台聚合技能	lark-cli，技能版本跟随官方 CLI，本包版本为 1.0.98
官方 npm 软件包	@larksuite/cli
安装后可执行命令	lark-cli
已安装 CLI 软件版本	通过 lark-cli --version 核对当前运行环境中的实际版本

不要根据可执行名猜 npm 包名：不要安装无 scope 的 lark-cli，不要尝试 @larksuite/lark-cli 或 @lark-open/cli。

本技能包不附带 CLI 可执行程序。聚合入口没有把待安装的 lark-cli 设置为加载前的硬依赖，以便缺少程序时仍能加载本安装指引。这不代表业务调用已经就绪，必须完成下面的实际检查。

第一步：检查运行环境和已有安装

node --version
npm --version
lark-cli --version

• CLI 可执行时复用已有安装，继续检查授权；不要重复安装或无请求升级。
• 找不到 CLI 时继续第二步，不要仅因缺少命令就拒绝读取技能或要求用户猜安装链接。
• 命令存在但启动失败时，保留实际错误，区分 PATH、平台架构、二进制下载和 Node.js 引擎不兼容。
• 缺少 Node.js/npm 时，先识别系统和已有的 nvm/fnm/Volta 等环境管理器，使用已有管理器或系统支持的方法安装 Node.js LTS，来源以 Node.js 官方指引 为准。完成后重新检查，不能把在其他机器上安装当作当前 Agent 已可用。
• 用户要求安装时完成当前权限范围内的安装；仅要求排查时先报告检查结果。进度以真实命令结果为准，不编造安装成功或授权完成状态。

第二步：安装官方 CLI 软件

先核对官方包身份、命令名和当前引擎要求，再安装：

npm view @larksuite/cli@latest name version bin engines repository.url --json
npm install -g @larksuite/cli@latest
lark-cli --version

确认包名是 @larksuite/cli，bin 包含 lark-cli，仓库指向 larksuite/cli。如果查询失败，排查 npm registry 和网络，不要换装名称相似的个人包。根据当前官方引擎要求判断 Node.js 是否兼容，不把某个历史版本当作固定标准。

本平台已包含 28 个业务模块，直接安装 npm 软件即可。无需再执行 npx skills add larksuite/cli 安装一批独立技能。官方的 npx @larksuite/cli@latest install 是综合安装向导，还会处理 Skills、配置和授权；需要完整向导时再使用，避免重复安装业务技能。

失败现象	下一步
npm 返回 EACCES / EPERM	检查当前用户、npm 全局前缀与写权限，按实际权限问题处理，不自动使用 sudo 或管理员权限
npm 成功但 CLI 找不到	运行 npm prefix -g；Linux/macOS 检查 <prefix>/bin，Windows 检查 <prefix> 是否在 Agent 工具进程的 PATH 中
Node.js 引擎不兼容	按 npm 元数据和实际错误升级 Node.js，再验证 node、npm、CLI
网络超时或二进制下载失败	区分 npm 包下载与 CLI 二进制下载，按实际错误和官方安装排错指引处理，只重试失败步骤
包查询返回 404	核对准确包名及 npm registry，查阅 官方仓库 的安装文档，不猜包名

第三步：配置应用并登录授权

CLI 可执行后，读取 共享规则，再检查：

lark-cli auth status

先确认目标业务使用 user 还是 bot 身份：用户身份检查用户登录授权；应用身份检查应用凭证和应用权限，不强制用户完成个人登录。具体身份与权限规则以共享指南为准。

• 已有有效配置和登录时直接复用；缺少某项业务权限时仅补充该项授权，不重新创建应用。
• 尚未配置应用时，读取 首次配置指南，按官方引导运行 lark-cli config init --new。保留已有配置，只有确需新建配置时才用 --new。
• 目标业务采用用户身份且应用已配置、用户尚未登录时，运行 lark-cli auth login --recommend，或按目标业务所需权限授权。
• 配置或登录需要等待用户操作时，以后台进程或交互会话运行，及时向用户展示命令实际返回的链接，按共享规则展示二维码。URL 原样转交，不改写参数或编造链接。不要求用户把 App Secret 粘贴到聊天中，不输出访问令牌和完整凭证文件。
• 用户完成操作后继续原有等待流程，并再次运行 lark-cli auth status 验证；过期后只重启失败的授权步骤，不反复重装 CLI、清空凭证或创建应用。

按未完成步骤依次执行，不能把这些交互命令无条件串行阻塞在一个调用中：

# 尚未配置时使用，具体流程遵循首次配置指南
lark-cli config init --new

# 已配置、尚未登录时使用，权限以实际任务为准
lark-cli auth login --recommend

# 用户完成授权后检查
lark-cli auth status

第四步：明确当前状态，再使用业务模块

实际检查结果	向用户说明
CLI 不可执行	技能文件已安装，CLI 依赖尚未安装或无法启动；继续安装或排错
CLI 可执行但应用未配置	CLI 已安装，待完成应用配置
用户身份已配置但未登录或授权过期	CLI 已配置，待完成用户登录授权
登录有效但业务权限不足	说明实际缺少的权限，按业务指南补充授权
CLI 可执行、当前身份所需凭证/授权有效且业务权限满足	按下方路由执行用户请求

再次尝试时重新检查实际状态，从失败步骤继续。仅安装 npm 软件或仅看到技能文件，不能描述为已完成飞书授权。

安装与授权依据：飞书官方文档。技能版本跟随官方 CLI 软件版本，本包对应 1.0.98；运行环境中实际安装的 CLI 版本通过 lark-cli --version 检查。

业务路由入口

你是飞书/Lark 能力的聚合路由层。你的职责是先判断用户要使用哪个 lark-* 子能力，再读取并遵循对应子能力的说明。

lark-cli 不直接承载具体 API 操作步骤。除非对应子能力已被读取，否则不要仅根据本文件拼命令、猜参数或执行复杂操作。

所有子能力统一收纳在当前技能根目录。选择 lark-foo 后，直接读取 lark-foo/SKILL.md；不要再次调用 Skill(lark-foo)，也不要使用 Find/Glob 遍历或探测整个技能目录。

使用流程

1. 根据用户意图从下方路由表选择一个或多个子能力；即使用户尚未提供链接、ID 或具体工作表，也先选择能力，再由子能力询问缺失信息。
2. 直接读取 <skill-name>/SKILL.md 加载所选子能力，不要把收纳后的子能力当作独立 skill 再次调用。
3. 仅使用本文件列出的路由与对应子能力入口，不要遍历或探测其他技能目录。
4. 如果目标能力未列出，返回无法路由的明确提示。
5. 仅读取当前已选子能力明确要求的前置文件。
6. 按目标子能力的说明执行；认证、租户、身份、权限和通用排障优先遵循 lark-shared。

多步任务可以组合多个子能力，但每一步都应由具体子能力驱动。例如“查联系人并发消息”先用 lark-contact 解析身份，再用 lark-im 发消息。

能力路由

根据用户意图从以下条目选择对应子能力；如果一个任务涉及多个能力，按实际操作顺序逐步读取并使用对应子能力。

• lark-approval：读取 lark-approval。
• lark-apps：读取 lark-apps。
• lark-attendance：读取 lark-attendance。
• lark-base：读取 lark-base。
• lark-calendar：读取 lark-calendar。
• lark-contact：读取 lark-contact。
• lark-doc：读取 lark-doc。
• lark-drive：读取 lark-drive。
• lark-event：读取 lark-event。
• lark-im：读取 lark-im。
• lark-mail：读取 lark-mail。
• lark-markdown：读取 lark-markdown。
• lark-meeting：读取 lark-meeting。
• lark-minutes：读取 lark-minutes。
• lark-note：读取 lark-note。
• lark-okr：读取 lark-okr。
• lark-openapi-explorer：读取 lark-openapi-explorer。
• lark-shared：读取 lark-shared。
• lark-sheets：读取 lark-sheets。
• lark-skill-maker：读取 lark-skill-maker。
• lark-slides：读取 lark-slides。
• lark-task：读取 lark-task。
• lark-vc：读取 lark-vc。
• lark-vc-agent：读取 lark-vc-agent。
• lark-whiteboard：读取 lark-whiteboard。
• lark-wiki：读取 lark-wiki。
• lark-workflow-meeting-summary：读取 lark-workflow-meeting-summary。
• lark-workflow-standup-report：读取 lark-workflow-standup-report。