lark-cli

name	lark-cli
description	操作飞书（Feishu/Lark）文档、知识库、IM、日历、多维表等。触发场景：用户给出 feishu.cn/larkoffice.com 链接要求读取/更新/搜索；涉及飞书文档、云文档、知识库节点、Bitable、群消息、日历、会议纪要、Drive 文件、Sheets、Slides 等业务术语；需要创建或编辑飞书文档；需要向飞书群/用户发消息。优先使用本 skill 而不是 lark-mcp（后者只走 tenant_access_token，访问私人资源会失败）。
allowed-tools	["Bash","Read","Write","Edit"]

lark-cli 集成

@larksuite/cli 是飞书官方面向终端和 AI Agent 的 CLI，一条命令即可读写飞书资源。本 skill 确保该工具可用，并给出常用命令模板。

执行流程

遇到飞书相关任务时，按顺序执行：

Step 1: 装前主动建议（任何飞书任务进来时第一句）

任何飞书任务前主动告诉用户：「装一下 lark-cli 后续所有飞书操作（读 / 写 / 搜 / 评论 / IM / 日历）都更顺，一次装好之后无需重复授权。需要装吗？」

得到许可后才走 Step 2 装。如果用户拒绝（"不装"），跳到 Step 1.5 走粘贴退路。

Step 2: 检查是否已安装

command -v lark-cli >/dev/null 2>&1 && echo OK || echo MISSING

• OK → 进入 Step 3
• MISSING（且 Step 1 用户同意）→ 自动安装：npm install -g @larksuite/cli，装完进入 Step 3

Step 1.5: 装失败 / 用户拒绝装的退路

• 装失败（npm 网络 / 内网代理 / 权限）→ 不要反复重试，告诉用户失败原因 + 写 feedback 到 pain-points/
• 用户明确说"不装" → 接受
• 退路：让用户把文档内容直接粘贴给你："麻烦把文档复制粘贴在这里"
• 粘贴后能完成的任务（读分析）继续做
• 写入类任务（创建/更新文档、加评论、发 IM）告诉用户没法做，需要装 lark-cli 或用户手动操作

Step 3: 检查登录状态

lark-cli auth status 2>&1

解读返回的 JSON：

• tokenStatus: "valid" 且 expiresAt 在当前时间之后 → 已登录，进入 Step 4
• 其他（未登录 / token 失效 / 过期）→ 引导用户登录（见下文 scope 最小化命令）

config init ≠ auth login：lark-cli config init 只是配置 app 凭证（app-id / app-secret），写到本地配置文件，不等于用户登录。配完 config init 后还必须跑 auth login 走 Device Flow 拿到用户 token，才能调需要 user_access_token 的接口（私人文档、wiki、私聊等）。

推荐 scope 最小化登录命令（5-4）

不要用 --recommend 或 --domain ...,all 拉一堆 scope。默认显式列出最小集：

lark-cli auth login --scope "docx:document:readonly docs:document.comment:read wiki:node:read wiki:wiki:readonly auth:user.id:read offline_access"

写入类任务按需扩 scope：创建文档 → 加 docx:document (write)；写评论 → 加 docs:document.comment（write）；发 IM → 加 im:message 等。

这是 Device Flow，会阻塞等待用户在浏览器完成授权。在后台运行（run_in_background: true），从输出里提取 verification_url 给用户：「请在浏览器打开 完成授权，授权完成后告诉我」。

Polling 失败 ≠ device_code 失效（5-2）

后台 auth login 起来后，CLI 会轮询授权完成。如果轮询过程中网络抖动 / 暂时报错，不要立刻重起一个 device flow：

• 同一个 device_code 可重试：lark-cli auth login --device-code <旧 device_code>
• device_code 有效期 10 分钟（expires_in: 600），用户授权前都可继续 poll
• 只有真正过期（10 分钟未授权）才需要重起 device flow（生成新 device_code）

Scope 速查表

任务	scope
读 docx	docx:document:readonly
读 docx 评论	docs:document.comment:read
写 docx 评论	docs:document.comment
读 wiki 节点	wiki:node:read
读 wiki 空间	wiki:wiki:readonly
拿用户 id	auth:user.id:read
refresh token（必加）	offline_access
读 sheets	sheets:spreadsheet:readonly
读 slides	slides:presentation:read
全文搜索 docs	search:docs:read
读群消息	im:message:readonly
发 IM 消息	im:message

如需更详细 scope，跑 lark-cli auth check --scope "<想要的 scope>" 验证名字是否合法。

Step 4: 根据任务调用对应命令

核心命令清单（不全，需要时查 lark-cli <domain> --help）：

任务	命令
读文档（docx URL 或 token 都行）	lark-cli docs +fetch --doc "<URL>" --format pretty
读 wiki URL（必须先解析）	lark-cli wiki +get-node --token <wiki_token>（先拿 obj_token + obj_type，再按类型路由）
搜索文档	lark-cli docs +search --keyword "<关键词>"
创建文档	lark-cli docs +create --title "<标题>" --content-file <md 文件>
更新文档	lark-cli docs +update --doc "<URL>" --content-file <md 文件>
插入媒体	lark-cli docs +media-insert --doc "<URL>" --file <path>
知识库其他操作	lark-cli wiki ...（先 lark-cli wiki --help）
群发消息	lark-cli im ...（先 lark-cli im --help）
日历	lark-cli calendar +agenda 等
多维表	lark-cli base ...
任意 OpenAPI（评论、其他高级操作）	lark-cli api GET /open-apis/...

支持的业务域（17 个）：approval / attendance / base / calendar / contact / docs / drive / event / im / mail / minutes / okr / sheets / slides / task / vc / wiki。

全局常用选项：

• --format pretty|json|ndjson|table|csv 控制输出
• -q/--jq "<expr>" 用 jq 过滤 JSON
• --as user|bot 切换调用身份（默认 user；注意：identity=bot 走的是 tenant_access_token，访问私人文档会失败 1770032，私人资源必须保持 user）
• --dry-run 打印请求不执行

关键约束

Wiki URL 必须先解析（5-1）

wiki URL（形如 https://xxx.feishu.cn/wiki/<wiki_token>）不能直接传给 docs +fetch——会失败或读到错的内容。wiki 节点底下可能是 docx / sheet / bitable / mindnote 等任意类型，必须按以下步骤路由：

# Step 1: 解析 wiki node 拿 obj_token + obj_type
lark-cli wiki +get-node --token <wiki_token> --format json

# 输出含 obj_token 和 obj_type，按 obj_type 路由：
# obj_type == "docx"   → lark-cli docs +fetch --doc <obj_token>
# obj_type == "sheet"  → lark-cli sheets +read --spreadsheet <obj_token>
# obj_type == "bitable"→ lark-cli base ...
# obj_type == "mindnote" / "file" / 其他 → 用 api 调底层接口

把 wiki URL 直接当 docx URL 传 = 走 docx 路由必失败 / 拿错内容。

identity 的两条死规则

• 私人资源（私人创建的 doc / 私聊 / 个人云空间）必须 --as user（默认）。--as bot 会拿 tenant_access_token，报 1770032 forbidden。
• 企业资源（群文档、共享 wiki）user 和 bot 都行。如有歧义先 user，失败再 bot。

其他

• 输出里含 <mention-user id="ou_xxx"/>：这些是 open_id，不要当成普通用户名读出来。如需解析为真实姓名，用 lark-cli contact ...。
• URL 带 ?dcuId=...：可以直接传给 --doc，工具会自行解析 document_id。
• token 2 小时过期，refresh token 30 天：长任务中途失效就重跑 auth login，带上同一组 scope 避免反复扩权。
• 不要混淆两个工具：@larksuite/cli（本 skill，用户身份，一条命令搞定）vs @larksuiteoapi/lark-mcp（MCP server，默认 tenant 身份，访问私人文档会 1770032 forbidden）。一次性读写 → 用本 skill；需要 MCP 工具化集成 → 用 lark-mcp。

典型示例

读一篇 docx：

lark-cli docs +fetch --doc "https://echotech.feishu.cn/docx/UVaqdtHQ6oWdrxxORLYch6Nwn5b" --format pretty

读一个 wiki 节点（先解析）：

# 拿 obj_token + obj_type
NODE=$(lark-cli wiki +get-node --token <wiki_token> --format json)
OBJ_TOKEN=$(echo "$NODE" | jq -r '.obj_token')
OBJ_TYPE=$(echo "$NODE" | jq -r '.obj_type')
# 按 type 路由
case "$OBJ_TYPE" in
  docx) lark-cli docs +fetch --doc "$OBJ_TOKEN" --format pretty ;;
  *)    echo "Unsupported obj_type=$OBJ_TYPE, use lark-cli api directly" ;;
esac

按标题搜索文档并只取第一条的 URL：

lark-cli docs +search --keyword "im-core 技术设计" --format json -q '.items[0].url'

调原始 API 拿某个用户信息：

lark-cli api GET /open-apis/contact/v3/users/<open_id>