> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Lark CLI 能力地图：AI 如何操作 Lark 工作系统

**一句话结论：**`lark-cli` 不是一个聊天机器人，而是把 Lark/Feishu
workspace 暴露给 AI agent 的操作层。它让 agent 可以用稳定的 CLI、结构化
JSON、skills、raw OpenAPI 去读写
Docs、Base、Sheets、Tasks、Calendar、IM、Mail、Meetings、Approval、OKR
等工作系统。

如果把 Lark 看成企业的 work OS，`lark-cli` 就是 AI 的 hands/API
layer；它负责“能不能精准操作 Lark”，不负责“长期思考、执行代码、开
PR、维护 shell session”。后者需要 Botmux、Codex/Claude
Code、Beads/任务库和 policy 层配合。

# 0. 我读了什么

| 来源              | 内容                                                                                                                      | 用于判断什么                               |
| --------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| GitHub repo     | `larksuite/cli`，本地克隆 SHA `c0730b46bf315ecd3683165279b2590530725c72`                                                     | 真实命令、架构、skills、风险模型                  |
| 本机 CLI          | 研究初期为 `lark-cli 1.0.52`；发布排障时已升级到 `1.0.53`                                                                              | 当前可用命令清单和发布链路                        |
| 源码文件            | `cmd/root.go`, `cmd/service/service.go`, `cmd/auth/login.go`, `cmd/platform_bootstrap.go`, `extension/platform/risk.go` | command 注册、auth、identity、risk、policy |
| 官方 pricing/help | Lark plan overview、Slack pricing                                                                                        | 商业化时 Lark vs Slack 的成本/能力差异          |
| 本地 skill        | `lark-doc`, `lark-shared`, `lark-publish`                                                                               | 如何由 agent 安全读写 Lark Docs             |

***

# 1. 正确心智模型

```mermaid
flowchart LR
  Human[Human in Lark] --> Agent[AI Agent]
  Agent --> Skill[Lark Skills]
  Agent --> Shortcut[Shortcut Commands]
  Agent --> API[Generated OpenAPI Commands]
  Agent --> Raw[Raw lark-cli api]
  Skill --> LarkAPI[Lark OpenAPI]
  Shortcut --> LarkAPI
  API --> LarkAPI
  Raw --> LarkAPI
  Auth[Auth, Scope, Identity] --> LarkAPI
  Policy[Risk and Policy] --> Skill
  LarkAPI --> WorkOS[Docs, Base, IM, Mail, Calendar, Tasks, Wiki]
```

## 它是什么

- 一个 Lark/Feishu 官方维护的 command-line interface。
- 一个适合 AI agent 使用的工具层：命令可 introspect，输出可 JSON
  化，风险可标注。
- 一个 OpenAPI 封装层：常用场景有 shortcuts，长尾接口有 generated
  commands 和 raw API。
- 一个 skills 分发层：把复杂 Lark 操作封装成 agent
  可以读懂的工作流指南。

## 它不是什么

- 不是长期运行的 AI employee runtime。
- 不是 task source of truth；它能读写任务，但不会自己定义任务生命周期。
- 不是代码执行环境；它不会替代 Codex、Claude Code、GitHub Actions。
- 不是权限万能钥匙；scope、tenant、bot/user
  identity、文档权限仍然决定它能做什么。

**最重要的判断：**Lark CLI 的强点不是“能发消息”，而是它把 Lark 这个
workspace 里大量结构化对象变成 agent 可操作的
API：文档、表格、任务、日历、会议、邮件、审批、知识库、多维表格、事件流。

***

# 2. 三层命令系统

| 层级                     | 用途                                     | 例子                                                                      | AI employee 价值                 |
| ---------------------- | -------------------------------------- | ----------------------------------------------------------------------- | ------------------------------ |
| Shortcuts              | 人和 AI 最常用的高层动作，命令名通常是 `+xxx`           | `docs +create`, `task +create`, `im +messages-send`, `calendar +agenda` | 让 agent 快速完成真实工作流，不必每次拼底层 API。 |
| Generated API commands | 从 Lark OpenAPI metadata 动态生成，覆盖大量资源和方法 | `drive file ...`, `sheets spreadsheet ...`, `base app-table-record ...` | 当 shortcut 不够时，还能落到正式 API 层。   |
| Raw API                | 直接调用任意 Lark API 路径                     | `lark-cli api GET /open-apis/...`                                       | 长尾能力兜底，适合新 API 或 CLI 尚未封装的场景。  |
| Skills                 | 给 AI agent 的操作手册和安全规则                  | `lark-doc`, `lark-base`, `lark-mail`, `lark-event`                      | 减少“猜命令”和误操作，把复杂流程变成可复用套路。      |

源码里每个 service method 会带上 path、domain、risk、identity、参数
schema、文件字段、dry-run 支持等 metadata。这对 AI 很关键，因为 agent
需要知道一个动作是 `read`、`write` 还是 `high-risk-write`，以及应该用
`--as user` 还是 `--as bot`。

***

# 3. 全能力地图

下面按“企业员工工作域”整理，而不是照搬 command help。实际命令可用
`lark-cli <domain> --help` 展开。

| 工作域              | 能做什么                                                               | 代表命令/skill                                                                           | 可变成什么员工能力                                      |
| ---------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ---------------------------------------------- |
| Auth / Config    | 登录、scope 检查、identity 切换、strict mode、keychain、profile、diagnostics。  | `auth login`, `auth status`, `auth scopes`, `config strict-mode`, `doctor`           | 企业级部署前的账号、权限、scope 自检。                         |
| IM / Messenger   | 发消息、回复、搜索消息、列 chat、管理群、下载消息资源、处理 reactions、threads、feed、bookmarks。 | `im +messages-send`, `im +messages-search`, `im +chat-create`, `lark-im`             | 通知、日报、审批提醒、群里交互式 AI 员工入口。                      |
| Docs / Docx      | 创建、读取、更新文档；插入/下载媒体；搜索文档；更新 whiteboard。                             | `docs +create`, `docs +fetch`, `docs +update`, `lark-doc`                            | 把研究结果、PR 报告、会议总结、产品方案写成可读文档。                   |
| Drive            | 上传、下载、导出、导入、移动、删除、评论、权限、版本历史、文件夹和快捷方式管理。                           | `drive upload`, `drive download`, `drive +apply-permission`, `lark-drive`            | 资料归档、客户文件管理、自动生成交付物并放到正确目录。                    |
| Markdown         | 创建、拉取、覆盖、patch、diff Drive-native Markdown 文件。                      | `markdown +create`, `markdown +patch`, `markdown +diff`                              | 把 Git/docs workflow 和 Lark 文档沉淀连接起来。           |
| Wiki             | 空间、节点、成员、层级管理；创建/移动/复制/删除 wiki 节点。                                 | `wiki node-create`, `wiki node-list`, `lark-wiki`                                    | 团队知识库 IA 维护、项目文档自动归档。                          |
| Base / Bitable   | Base、表、字段、记录、视图、权限、角色、表单、dashboard、workflow、attachment、data query。 | `base record +create`, `base field +create`, `base dashboard +get-data`, `lark-base` | CRM、项目台账、任务运营、研究证据库、agent 输出的结构化 projection。   |
| Sheets           | 工作簿、sheet、行列、单元格读写、公式、样式、图片、图表、透视表、筛选、条件格式、CSV。                    | `sheets +set`, `sheets +search`, `lark-sheets`                                       | 财务/运营分析、数据整理、轻量 BI 报告。                         |
| Slides           | 创建和编辑演示文稿、读取/新增/删除/替换页面。                                           | `slides +create`, `slides +page-update`, `lark-slides`                               | 自动生成 pitch deck、客户汇报、周报 slides。                |
| Tasks            | 创建、查询、更新、完成、重开任务；子任务、关注者、评论、提醒、附件、任务清单、任务智能体。                      | `task +create`, `task +get-my-tasks`, `task +complete`, `lark-task`                  | 让 AI PM 管任务、拆任务、催办、同步执行状态。                     |
| Calendar         | 查看 agenda、创建/更新日程、参会人、会议室、忙闲、建议时间、RSVP。                            | `calendar +agenda`, `calendar +create`, `calendar +freebusy`, `lark-calendar`        | 安排会议、找空档、做 daily/weekly planning。              |
| VC / Minutes     | 搜索历史会议、查 notes/recording/events；妙记搜索、summary、todo、下载、上传音视频生成纪要。    | `vc +search`, `minutes +summary`, `lark-vc`, `lark-minutes`                          | 会议后自动出纪要、待办、风险、负责人和后续计划。                       |
| Mail             | 读邮件、搜索、写草稿、发送、回复、转发、模板、签名、triage、read receipt、watch。               | `mail +send`, `mail +draft-create`, `mail +reply`, `lark-mail`                       | 研究完自动起草邮件、BD follow-up、客服初稿、人类确认后发送。           |
| Contact          | 按姓名/邮箱解析 open\_id，查部门、邮箱、个人状态、联系方式。                                | `contact +search-user`, `lark-contact`                                               | 把“Peter/老板/某同事”解析成可操作的 Lark 身份。                |
| Approval         | 查待审批、本人发起实例、处理审批任务。                                                | `approval ...`, `lark-approval`                                                      | 员工型 agent 的 human approval gate，不让 agent 绕过决策。 |
| Attendance       | 查询自己的考勤打卡记录。                                                       | `attendance ...`, `lark-attendance`                                                  | 内部 HR/运营类自动化的只读数据源。                            |
| OKR              | 查看/编辑周期、目标、KR、对齐关系、进展记录、图片上传。                                      | `okr cycle`, `okr progress`, `lark-okr`                                              | 项目战略目标和执行状态同步。                                 |
| Event            | 订阅、消费、停止、查看事件 schema/status，以 NDJSON 方式流式读事件。                      | `event consume`, `event schema`, `lark-event`                                        | 把 Lark 事件变成自动化触发器。                             |
| Whiteboard       | 查询、导出、更新文档里的画板，支持 Mermaid/PlantUML/DSL。                            | `whiteboard +query`, `whiteboard +update`, `lark-whiteboard`                         | 自动生成架构图、流程图、路线图。                               |
| Apps / Spark     | 创建、发布和迭代 Lark 妙搭/Spark 应用。                                         | `lark-apps`                                                                          | 把 agent 产出的后台工具快速变成内部 app。                     |
| OpenAPI Explorer | 在现有 CLI/skill 不覆盖时探索原生 Lark OpenAPI。                               | `lark-openapi-explorer`                                                              | 突破封装边界，接新 API。                                 |
| Skill Maker      | 把常用 Lark API 操作封装成可复用 skill。                                       | `lark-skill-maker`                                                                   | 把一次性自动化沉淀为组织能力。                                |
| Workflows        | 组合 Calendar/Task/Meeting 等生成站会、会议周报、待办摘要。                          | `lark-workflow-standup-report`, `lark-workflow-meeting-summary`                      | 从单个工具调用升级到小流程。                                 |

***

# 4. 对 AI employee 最关键的能力

## 输入层

- `docs +fetch` 读设计文档、spec、会议材料。
- `im +messages-search` 查历史对话。
- `minutes +summary` 和 `vc +notes` 读会议结论。
- `event consume` 监听新任务、新评论、新审批。

## 状态层

- `base record` 写结构化台账、CRM、证据库。
- `task +create` / `task +update` 管执行状态。
- `calendar +agenda` 读取时间约束。
- `wiki node` 组织知识库。

## 输出层

- `docs +create` 生成研究报告/PR 报告。
- `im +messages-send` 通知人类。
- `mail +draft-create` 起草商务邮件。
- `slides +create` 生成汇报材料。

**产品判断：**&#x53EA;要 Lark CLI 权限和 workspace 结构配置好，AI employee
就可以不再停留在“回答问题”，而是进入“读上下文 - 写结构化状态 - 产出
artifact - 通知/请求审批”的闭环。

***

# 5. Auth、identity、risk 和企业安全边界

| 机制                 | 我看到的实现/行为                                                                                                              | 对产品化的含义                                                                       |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Identity           | 命令可声明支持 `user`、`bot` 或两者。使用时通过 `--as user` / `--as bot` 选择。                                                            | 员工型 agent 要区分“代表用户做事”和“以应用身份做事”。两者的权限、审计、责任不同。                                |
| Scope              | `auth login`、`auth check`、`auth scopes` 可检查 OAuth scope。读写文档、邮件、任务都依赖 scope。                                           | 多客户部署必须有 scope manifest 和最小权限策略，不能临时缺什么补什么。                                   |
| Risk               | 源码风险枚举包含 `read`、`write`、`high-risk-write`。高风险操作需要更强确认。                                                                 | 可以接到 lane/policy：read-only、test-autofix、reviewed-production、trusted-low-risk。 |
| Policy pruning     | 平台层支持通过 policy/plugin rules 裁剪命令可见性。                                                                                   | 给不同客户/项目/员工角色暴露不同工具集合。                                                        |
| Sidecar            | repo 有 sidecar demo 和 multi-tenant demo，强调 HMAC、host allowlist、identity allowlist、auth header allowlist、audit logging。 | 企业 SaaS 不能把本地 CLI 裸暴露给外部；需要受控 sidecar/proxy。                                  |
| Version management | 本次研究中 `lark-cli` 从 `1.0.52` 升级到 `1.0.53`，skills 也同步更新。                                                                 | 长期产品化需要固定版本、升级测试、skills 版本管理。                                                 |

研究期间曾遇到 user auth 过期，报错是 `need_user_authorization`，缺
`docx:document:readonly`。这个小故障很有代表性：这类系统的第一性问题不是模型能力，而是
auth、scope、tenant、审计和权限生命周期。

***

# 6. Lark vs Slack：为什么 Lark 对这个方向更合适

| 维度         | Lark                                                                                                                                                                 | Slack                                                                                                                     |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| 协作对象       | Chat、Docs、Wiki、Base、Sheets、Task、Calendar、Mail、Approval、OKR、Meetings 在一个 work OS 里。                                                                                   | 强在 messaging、channels、app ecosystem；Canvas、Workflow、AI 正在增强，但很多业务对象仍依赖外部 SaaS。                                            |
| AI 操作层     | `lark-cli` 把大量 Lark 对象直接暴露成 CLI/API/skills。                                                                                                                          | Slack 有 API、Workflow、Agentforce、Marketplace，但没有等价的官方“一套 CLI skills 覆盖整个 work OS”的形态。                                      |
| 定价公开信息     | 官方 help 显示 Starter/Basic/Pro/Enterprise。Starter 最多 20 人、100 GB storage；Pro 最多 500 人、15 TB storage、Base workflow 50,000 runs/month；Enterprise 更高。官方价格页动态且地区相关，需下单时确认。 | 官方价格页显示 Free $0；Pro $8.75/user/month monthly 或 $7.25 annual；Business+ $18 monthly 或 $15 annual；Enterprise+ contact sales。 |
| agent 产品机会 | 更适合做“员工分层、任务、文档、审批、表格、邮件、会议”打通的工作员工。                                                                                                                                 | 更适合做 chat-first 的 assistant/agent 入口；若要实现同样的管理闭环，需要额外接 Jira/Linear/Google Drive/Notion/Salesforce 等。                      |

**判断：**&#x53;lack 不是不能做，而是要补的业务对象更多。Lark
的优势是工作对象天然集中，且已经有 `lark-cli` 这条 agent
操作路径。对我们这种想做“AI employee / project manager / research
employee”的产品，Lark 是更低摩擦的起点。

***

# 7. 边界和坑

| 边界                 | 为什么重要                                                             | 建议                                                           |
| ------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------ |
| 不是长期 runtime       | CLI 调用是一次性动作，不保存推理上下文和 shell session。                             | 把 Botmux/Codex/Claude Code 放在 runtime 层。                     |
| 不是 source of truth | Lark Doc 很适合呈现，但 task lifecycle、agent state、audit log 不应只靠自然语言文档。 | 用 Beads/local DB/WAL 作为 SoT，Lark Base/Doc 作为 projection。     |
| 权限容易漂移             | OAuth scope、文档权限、bot 权限、群权限都可能变。                                  | 做 auth health check 和权限预检。                                   |
| 写操作必须有人类 gate      | 邮件发送、审批处理、任务状态、生产发布都可能产生外部影响。                                     | 使用 risk lane：read-only 默认，write 需要明确授权，高风险必须 human approval。 |
| 事件驱动需要去重           | Lark event/webhook 可能重放、乱序、重复。                                    | 每个 event 要有 idempotency key 和 audit log。                     |
| 版本和 skills 会更新     | CLI 已从 1.0.52 升到 1.0.53；skills 也会随版本变化。                           | 固定版本、记录 SHA、升级前跑 smoke tests。                                |

***

# 8. 可以直接落地的三类用法

1. **AI Developer 控制台：**&#x4ECE; Lark Doc/Task/GitHub Issue 读取任务，用
   Codex/Claude Code 写代码，生成 PR，再把结果、测试、风险、review link
   写回 Lark。
2. **Research Employee：**&#x5B9A;时读外部来源和内部 docs，把情报写进 Base
   证据库，生成 Lark Doc 报告，起草邮件或 Slack/Lark 消息等待确认。
3. **Project Manager：**&#x4ECE;会议纪要抽任务，查每个人
   agenda/任务状态，生成周报，标出 blockers，发给相关群或负责人。

这三类都需要 Lark CLI，但都不能只靠 Lark CLI。CLI
给的是“操作能力”，员工产品还需要 runtime、state、policy、measurement。

***

# 10. 来源链接

- [larksuite/cli GitHub Repository](https://github.com/larksuite/cli)