Lark

lark-cli 全功能指南

本 skill 合并了全部 23 个飞书子 skill，统一入口。 使用前必须先完成 配置初始化 和 认证（见 § 0）。

§ 0. 共享基础（所有域通用）

配置初始化

首次使用需运行 lark-cli config init 完成应用配置。

以 background 方式发起配置，读取输出中的授权链接发给用户：

# 发起配置（阻塞直到用户打开链接并完成操作或过期）
lark-cli config init --new

身份类型

两种身份类型，通过 --as 切换：

身份选择原则：

• Bot 看不到用户资源：无法访问用户的日历、云空间文档、邮箱等个人资源
• Bot 无法代表用户操作：发消息以应用名义发送，创建文档归属 bot
• Bot 权限：只需在飞书开发者后台开通 scope，无需 auth login
• User 权限：后台开通 scope + 用户通过 auth login 授权，两层都要满足

权限不足处理

错误响应关键字段：permission_violations（缺失 scope）、console_url（后台链接）、hint（修复命令）

Bot 身份：将 console_url 发给用户去后台开通 scope。禁止对 bot 执行 auth login。

User 身份：

lark-cli auth login --domain <domain>           # 按业务域授权
lark-cli auth login --scope "<missing_scope>"   # 按具体 scope 授权（推荐）

auth login 必须指定范围（--domain 或 --scope）。多次 login 的 scope 会累积（增量授权）。

Agent 代理认证（推荐）：以 background 方式执行，将授权链接发给用户：

lark-cli auth login --scope "calendar:calendar:readonly"

更新检查

命令执行后，如输出包含 _notice.update 字段，完成当前请求后提议更新：

lark-cli update --check --json

如果用户明确要求更新 CLI，执行：

lark-cli update --json

Lark 相关 Skills 不通过 npx skills add 或外部 Skills CLI 管理；需要更新 / 导入 / 分发时，必须回到 ~/project/my-skills 使用 skills-manager。更新完成后提醒用户退出并重新打开 AI Agent 以加载最新 Skills。

安全规则

• 禁止输出密钥（appSecret、accessToken）到终端明文
• 写入/删除操作前必须确认用户意图
• 用 --dry-run 预览危险请求

§ 1. 域路由总表

§ 2. 消息（IM）

CRITICAL — 操作前必读 § 0 共享基础

核心概念

• Message：单条消息，message_id（om_xxx）。支持类型：text、post、image、file、audio、video、sticker、interactive（card）等
• Chat：群聊或 P2P 会话，chat_id（oc_xxx）
• Thread：消息的回复线程，thread_id（om_xxx 或 omt_xxx）

Chat (oc_xxx)
├── Message (om_xxx)
│   ├── Thread（回复线程）
│   ├── Reaction（表情）
│   └── Resource（图片/文件/视频/音频）
└── Member（用户/bot）

身份注意

• --as user → user_access_token，以授权用户身份操作
• --as bot → tenant_access_token，以应用 bot 身份操作
• 同一 API 两种身份结果差异大，注意 chat 成员资格、可见范围等

Bot 身份获取消息时发件人名称可能不解析：原因是 bot 应用可见范围未覆盖发送者。解决：在开发者后台调整应用可见范围，或改用 --as user。

Shortcuts（推荐优先使用）

lark-cli im +<verb> [flags]

API Resources

lark-cli schema im.<resource>.<method>    # 必须先查参数结构
lark-cli im <resource> <method> [flags]  # 调用 API

权限表

§ 3. 日历（Calendar）

CRITICAL — 操作前必读 § 0 共享基础 CRITICAL — 所有 Shortcut 执行前，必须先用 Read 工具读取对应说明文档，禁止直接盲目调用。 CRITICAL — 涉及【预约日程/会议】或【查询/搜索会议室】→ 第一步必须读 references/calendar/lark-calendar-schedule-meeting.md。 CRITICAL — 口语"帮我约个日历"/"查一下今天的日历" → 实际是日程操作，映射为 +create/+agenda。 CRITICAL — 查询过去时间的会议（"昨天的会""上周的会"）→ 优先走 § 13 VC 搜会议记录。查询日历/日程或未来时间安排 → 使用本域。 CRITICAL — 删除/修改日程后，二次查询验证需等待至少 2 秒（不要告知用户等待）。

时间推断规范：

• 周一是一周第一天，周日是最后一天
• "今天/明天"时间范围覆盖整天
• 不能预约已完全过去的时间（跨越当前时间的除外）

核心概念

• Calendar：日程容器。每用户有主日历（primary），也可创建/订阅共享日历
• Event：日程。支持单次和重复日程（RFC5545 iCalendar 标准）
• Instance：日程的具体时间实例（重复日程展开后每条）
• Attendee：参与者（用户/群/会议室/外部邮箱），各有独立 RSVP 状态
• Room：会议室（是日程的 resource attendee，不能单独预定）
• Time Slot：确定的连续时间段，如 14:00~15:00

核心场景

预约日程/会议、查询/搜索可用会议室

阻塞要求： 有"预约日程/会议"或"查询/搜索可用会议室"意图 → 立即停止，先完整读取 references/calendar/lark-calendar-schedule-meeting.md，未读前禁止执行任何操作。

• 有明确时间 → 先 +room-find，再 +freebusy
• 时间模糊/无时间 → 先 +suggestion 拿候选时间块，再 +room-find
• 用户"查会议室"但未提供明确时间 → 禁止直接调用 +room-find，必须先 +suggestion
• 选定时间/会议室方案前必须展示给用户确认，禁止擅自决定

Shortcuts

lark-cli calendar +<verb> [flags]

API Resources

lark-cli schema calendar.<resource>.<method>
lark-cli calendar <resource> <method> [flags]

calendars: create/delete/get/list/patch/primary/search event.attendees: batch_delete/create/list events: create/delete/get/instance_view/patch/search/share_info freebusys: list

权限表

注意：日期/时间戳转换必须调用系统命令（如 date），不要心算。

§ 4. 云文档（Doc）

CRITICAL — 操作前必读 § 0 共享基础 ⚠️ API 版本：所有 docs +create、docs +fetch、docs +update 必须携带 --api-version v2。 CRITICAL — 文档中出现 <sheet>、<bitable>、<cite file-type="sheets|bitable"> 标签时，必须主动提取 token 并切到对应技能（§ 7 Sheets / § 6 Base）下钻读取。

执行操作前必读：

1. 读取文档（docs +fetch） → 读 references/doc/lark-doc-fetch.md
2. 创建/编辑文档内容 → 读 references/doc/lark-doc-xml.md（Markdown 时改读 references/doc/lark-doc-md.md）；从零创建时加读 references/doc/style/lark-doc-create-workflow.md；编辑已有时加读 references/doc/style/lark-doc-update-workflow.md

# 常用示例
lark-cli docs +fetch  --api-version v2 --doc "文档URL或token"
lark-cli docs +create --api-version v2 --content '<title>标题</title><p>内容</p>'
lark-cli docs +update --api-version v2 --doc "文档URL或token" --command append --content '<p>内容</p>'

嵌入对象路由

下游路由

• 拿到 spreadsheet URL/token → 切 § 7 Sheets
• 拿到 bitable URL/token → 切 § 6 Base
• 搜索云空间文档 → 优先用 drive +search（§ 5 Drive）

Shortcuts

§ 5. 云空间（Drive）

CRITICAL — 操作前必读 § 0 共享基础 分流规则： 把本地文件导入成 Base/多维表格 → drive +import --type bitable（先导入，再切 § 6 Base 做内部操作）。

快速决策

• 搜文档/Wiki/电子表格/多维表格/云空间对象 → drive +search（扁平 flag，无需手写 JSON）
• 导入本地 .xlsx/.csv/.base 为 Base → drive +import --type bitable
• 导入本地 .md/.docx/.html 为在线文档 → drive +import --type docx
• 导入本地 .xlsx/.csv 为电子表格 → drive +import --type sheet
• 新建文件夹 → drive +create-folder
• 上传到知识库节点下 → drive +upload --wiki-token <wiki_token>
• 修改文件标题（docx/sheet/bitable/file/folder/wiki）→ drive files patch --data '{"new_title":"..."}'

Wiki 链接特殊处理

/wiki/<token> 背后可能是不同类型文档，不能直接用作 file_token：

# 先查实际类型和真实 token
lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}'
# 返回 node.obj_type（docx/sheet/bitable/slides 等）和 node.obj_token（真实 token）

Shortcuts

§ 6. 多维表格（Base）

CRITICAL — 操作前必读 § 0 共享基础 CRITICAL — 执行任何 base 命令前必须先读对应命令的 reference 文档，再调用命令。 分流规则： 本地文件导入 Base → 第一步是 drive +import --type bitable，导入完成后再用 base +... 做内部操作。

触发条件

• 操作飞书多维表格 / Base
• 建表/改表/查表/字段管理/记录读写/视图配置
• 公式字段、lookup 字段、派生指标、跨表计算
• 临时统计、聚合分析、比较排序
• Workflow/dashboard/表单/角色权限管理
• 用户给出 /base/{token} 或解析为 bitable 的 /wiki/{token} 链接

模块地图

所有 base 命令格式：lark-cli base +<verb>
执行前必须先读对应 reference，禁止直接调用。

lark-cli schema base.<resource>.<method>   # 查参数结构
lark-cli base <resource> <method> [flags] # 调用 API

§ 7. 电子表格（Sheets）

CRITICAL — 操作前必读 § 0 共享基础 CRITICAL — 执行 sheets 命令前必须先读对应 reference 文档。

操作前先用 lark-cli schema sheets.<resource>.<method> 查参数结构。

所有 sheets reference 文档在 references/sheets/，按功能分类：

• 基本操作：create/get/update/append/find — 查 lark-cli sheets --help
• 导出：+export-csv、+export-xlsx
• 数据类型：references/sheets/ 下各 .md 文件

lark-cli schema sheets.<resource>.<method>
lark-cli sheets <resource> <method> [flags]

§ 8. 演示文稿（Slides）

CRITICAL — 操作前必读 § 0 共享基础

Shortcuts

所有 slides reference 文档在 references/slides/。
使用 +replace-slide 前必须读 references/slides/lark-slides-replace-slide.md。

lark-cli schema slides.<resource>.<method>
lark-cli slides <resource> <method> [flags]

§ 9. 任务（Task）

CRITICAL — 操作前必读 § 0 共享基础

搜索 vs 列取决策：

• 有明确查询关键字 → +search
• 无关键字，只有范围条件（"我关注的/由我创建/分配给我"）→ 优先 +get-related-tasks 或 +get-my-tasks
• 不要把时间范围词（"今年以来"）误当 query 参数
• 用户提到"todo"（待办）→ 优先理解为 task

创建/更新注意：

1. 设置 repeat_rule 或 reminder 之前必须先设置 due
2. 同时设置 start 和 due 时，开始时间 ≤ 截止时间
3. bot 身份无法跨租户添加任务成员

Task GUID：API 中的 guid 是全局唯一标识，不是客户端展示的任务编号（t104121）。从 applink 取 guid 参数。

输出要求：同时输出任务的 url 字段，便于用户点击跳转。

Shortcuts

lark-cli task +<verb> [flags]

权限表（部分）

§ 10. 邮件（Mail）

CRITICAL — 操作前必读 § 0 共享基础

所有 mail reference 文档在 references/mail/，执行对应操作前先读相应文档。

lark-cli schema mail.<resource>.<method>
lark-cli mail <resource> <method> [flags]

§ 11. 知识库（Wiki）

CRITICAL — 操作前必读 § 0 共享基础

成员管理限制：

• --as bot + 部门 → 不支持，直接说明路径不可行，不要试错
• bot 路径无法完成时不要静默切换到 user；若用户明确要求 bot，必须说明无法完成

快速决策：

• 用户给 wiki URL（.../wiki/<token>），后续要查/加/删成员 → 先 wiki spaces get_node 获取 space_id
• 删除知识空间只有名称/URL → 必须先解析出真实 space_id，展示候选让用户确认后再执行
• 命中 0 条 → 停下询问，不要改名重试
• "我的文档库/My Document Library/个人知识库" → Wiki personal library，不是 Drive 根目录

成员添加流程：先把"人/群/部门"解析成正确 member_id 再调用：

• 用户 → contact +search-user 获取 open_id（member_type=openid）
• 群 → im +chat-search 获取 chat_id（member_type=openchat）
• 部门（user 身份）→ 搜索 open_department_id（member_type=opendepartmentid）

Shortcuts

API Resources

spaces: create/get/get_node/list members: create/delete/list nodes: copy/create/list

权限表

§ 12. 通讯录（Contact）

CRITICAL — 操作前必读 § 0 共享基础

Shortcuts

§ 13. 视频会议（VC）

CRITICAL — 操作前必读 § 0 共享基础

路由规则：

• 查询已结束的会议（历史日期/昨天/上周/今天已开的会）→ 使用本域
• 查询未来的会议日程/日历 → 使用 § 3 Calendar

核心概念

• Meeting：视频会议实例，meeting_id 标识
• Note：会议纪要，含 AI 总结、待办、章节（note_doc_token）
• VerbatimDoc：逐字稿，含说话人和时间戳（verbatim_doc_token）
• MeetingNotes：用户绑定的纪要文档（meeting_notes，仅 --calendar-event-ids 路径返回）
• Minutes：来自录制产物的妙记，minute_token 标识 → 详见 § 17 Minutes

核心场景

搜索会议记录：仅支持已结束会议，支持关键词/时间段/参与人/组织者/会议室筛选，注意分页。

整理会议纪要：

• 默认给纪要文档和逐字稿链接即可，无需读取内容
• 用户明确要总结/待办/章节时才读文档
• 读 note_doc_token 时，第一个 <whiteboard> 标签是封面图，应一并下载展示

# 读纪要内容
lark-cli docs +fetch --api-version v2 --doc <note_doc_token> --doc-format markdown
# 下载封面图
lark-cli docs +media-download --type whiteboard --token <whiteboard_token> --output ./minutes/<minute_token>/cover

产物目录规范：同一会议所有下载产物统一放 ./minutes/{minute_token}/

用户意图区分：

• "纪要/总结/纪要内容" → 同时返回 note_doc_token + meeting_notes（如有）
• "逐字稿/完整记录/谁说了什么" → verbatim_doc_token
• 意图不明确 → 展示所有文档链接让用户选择

Shortcuts

§ 14. 事件订阅（Event）

前置条件： 先读 § 0 共享基础。

Shortcuts

§ 15. OKR

CRITICAL — 操作前必读 § 0 共享基础 强烈建议 操作 OKR 前先读 references/okr/lark-okr-entities.md 了解业务实体。

Shortcuts

格式说明

• ContentBlock 富文本格式 — Objective/KeyResult/Notes 字段使用的富文本格式

API Resources

lark-cli schema okr.<resource>.<method>
lark-cli okr <resource> <method> [flags]

alignments: delete/get categories: list cycles: list/objectives_position/objectives_weight cycle.objectives: create/list

注意：cycles.objectives_position 必须同时修改当前周期下所有目标的位置，且不允许重叠；cycles.objectives_weight 所有权重值之和必须等于 1。

§ 16. 画板（Whiteboard）

CRITICAL — 操作前必读 § 0 共享基础

用于查看/导出/编辑飞书文档中的画板，支持预览图、原始节点结构、DSL/PlantUML/Mermaid 格式。 ⚠️ 若 skill 列表中同时存在旧的 lark-whiteboard-cli，忽略它，使用本 skill；如需清理旧 skill，走 skills-manager，不要使用外部 Skills CLI。

前置检查：

lark-cli --version                                # 确认 lark-cli 可用
lark-cli whiteboard --help                       # 确认 whiteboard 命令可用

快速决策

强制规范（通过 stdin 更新）：数据来源于本地文件时 必须 使用 --source - --input_format <格式>

Shortcuts

获取 board_token

§ 17. 妙记（Minutes）

CRITICAL — 操作前必读 § 0 共享基础

飞书妙记 URL 格式：http(s)://<host>/minutes/<minute-token>

核心概念

• 妙记（Minutes）：视频会议录制产物或用户上传音视频，minute_token 标识
• minute_token：从 URL 末尾提取，如遇 ?xxx 参数截取路径最后一段

能力边界

路由规则

• "我的妙记/某关键词/某段时间内的妙记" → minutes +search
• 同时提到"会议/开会/某场会" → 优先走 § 13 VC 先定位会议，再通过 vc +recording 获取 minute_token
• "这个妙记的逐字稿/总结/待办/章节" → vc +notes --minute-tokens

Shortcuts

未显式指定路径时，文件默认落到 ./minutes/{minute_token}/<server-filename>

§ 18. 考勤（Attendance）

CRITICAL — 操作前必读 § 0 共享基础

默认参数（必须自动填充，禁止询问用户）

lark-cli schema attendance.user_tasks.query   # 查参数结构
lark-cli attendance user_tasks query --data '{"user_ids":[],"...":"..."}'

权限表

§ 19. 审批（Approval）

CRITICAL — 操作前必读 § 0 共享基础

lark-cli schema approval.<resource>.<method>
lark-cli approval <resource> <method> [flags]

API Resources

instances: get/cancel/cc/initiated tasks: remind/approve/reject/transfer/query

权限表

§ 20. OpenAPI Explorer

前置条件： 先读 § 0 共享基础。

当现有 skill 或 CLI 已注册命令无法覆盖用户需求时，用本域从飞书官方文档库挖掘原生 API。

文档库

llms.txt                    ← 顶层索引（所有模块文档链接）
  └─ llms-<module>.txt      ← 模块文档（功能概述 + API 文档链接）
       └─ <api-doc>.md      ← 单个 API（方法/路径/参数/响应/错误码）

挖掘流程

Step 1：确认现有能力不足

lark-cli <service> --help   # 检查是否已有对应命令

如果已有对应命令或 shortcut → 直接使用，不继续挖掘。

Step 2：顶层索引定位模块 用 WebFetch 获取 llms.txt，找到相关模块文档链接。

Step 3：模块文档找 API 用 WebFetch 获取模块文档，找到相关 API 文档链接。

Step 4：读取 API 文档 获取完整的方法、路径、参数、权限信息。

Step 5：调用 API

lark-cli api GET /open-apis/<path> --params '{"key":"value"}'
lark-cli api POST /open-apis/<path> --data '{"key":"value"}'

§ 21. 自定义 Skill 创建

CLI 核心能力

lark-cli <service> <resource> <method>          # 已注册 API
lark-cli <service> +<verb>                      # Shortcut
lark-cli api <METHOD> <path> [--data/--params]  # 任意 OpenAPI
lark-cli schema <service.resource.method>       # 查参数定义

优先级：Shortcut > 已注册 API > api 裸调。

调研 API

lark-cli <service> --help                                           # 查已有资源和 Shortcut
lark-cli schema <service.resource.method>                           # 查参数
lark-cli api GET /open-apis/vc/v1/rooms --params '{"page_size":"50"}'  # 未注册 API 直接调用

未注册 API → 先用 § 20 OpenAPI Explorer 从官方文档挖掘。

SKILL.md 模板

---
name: lark-<name>
version: 1.0.0
description: "..."
metadata:
  requires:
    bins: ["lark-cli"]
  cliHelp: "lark-cli <service> --help"
---

# <name>

**CRITICAL — 开始前 MUST 先用 Read 工具读取 [§ 0 共享基础](../lark/SKILL.md#-0-共享基础所有域通用)**

## Shortcuts
...

§ 22. 工作流：会议纪要汇总

仅支持 user 身份。

lark-cli auth login --domain vc         # 基础（查询+纪要）
lark-cli auth login --domain vc,drive   # 含读取纪要文档正文/生成文档

工作流

{时间范围} ─► vc +search ──► 会议列表 (meeting_ids)
                   │
                   ▼
               vc +notes ──► 纪要文档 tokens
                   │
                   ▼
               drive metas batch_query 纪要元数据
                   │
                   ▼
               结构化报告

步骤

Step 1：确定时间范围（默认过去 7 天）

日期转换必须调用系统命令（如 date），不要心算。

"今天"→当天，"这周"→本周一～now，"上周"→上周一～上周日，"这个月"→1日～now

Step 2：查询会议记录

lark-cli vc +search --start "<YYYY-MM-DD>" --end "<YYYY-MM-DD>" --format json --page-size 30

• --end 包含当天（查"今天"时 start 和 end 都填今天）
• 搜索范围最大 1 个月，更长时拆分多次查询
• 有 page_token 时继续翻页，收集所有 id（meeting_id）

Step 3：获取纪要文档

lark-cli vc +notes --meeting-ids "<meeting_id1>,<meeting_id2>"

Step 4：获取纪要元数据

lark-cli schema drive.metas.batch_query
lark-cli drive metas batch_query ...  # 最多 10 个文档

Step 5：汇总输出 按时间排序，输出会议标题、时间、参与人、纪要链接，合并同一天的会议。

§ 23. 工作流：日程待办摘要

仅支持 user 身份。

lark-cli auth login --domain calendar,task

工作流

{date} ─┬─► calendar +agenda ──► 日程列表
        └─► task +get-my-tasks ──► 未完成待办列表
                    │
                    ▼
              AI 汇总（冲突检测 + 排序）──► 摘要

步骤

Step 1：获取日程

# 今天（默认）
lark-cli calendar +agenda

# 指定日期（必须 ISO 8601，不支持 "tomorrow" 等自然语言）
lark-cli calendar +agenda --start "2026-03-26T00:00:00+08:00" --end "2026-03-26T23:59:59+08:00"

--start/--end 只支持 ISO 8601 或 Unix timestamp，不支持 "tomorrow"，需 AI 根据当前日期自行计算。

Step 2：获取未完成待办

lark-cli task +get-my-tasks              # 默认最多 20 条
lark-cli task +get-my-tasks --due-end "2026-03-26T23:59:59+08:00"  # 截止时间过滤

Step 3：AI 汇总

1. 时间戳转本地时区可读时间
2. 冲突检测：同一时间段有多个日程时标注
3. 按时间排序
4. 格式：先日程（含地点/参会人），再待办（含截止时间/优先级）