项目概述
larksuite/cli 是飞书/Lark 官方出品的命令行工具，GitHub 13.5k stars，551 次提交，活跃度极高。
核心定位：同时服务人类用户和 AI Agent。
覆盖飞书 18 个业务域：IM、文档、表格、日历、任务、审批、考勤、Wiki、邮件、OKR、视频会议等。
技术栈
| 层面 | 选型 |
|---|---|
| 语言 | Go 1.23（占比 97.5%） |
| CLI 框架 |
spf13/cobra + spf13/pflag
|
| 飞书 SDK | larksuite/oapi-sdk-go/v3 |
| TUI 交互 |
charmbracelet/huh（表单）、charmbracelet/lipgloss（样式） |
| JSON 查询 |
tidwall/gjson、itchyny/gojq
|
| 系统钥匙串 | zalando/go-keyring |
| 配置格式 | gopkg.in/yaml.v3 |
| 发布工具 | goreleaser |
| 分发渠道 | npm（@larksuite/cli）+ 源码编译 |
整体架构
┌──────────────────────────────────────────────────────────────────┐
│ 用户 / AI Agent │
└────────────────────────────┬─────────────────────────────────────┘
│ CLI 调用
┌────────────────────────────▼─────────────────────────────────────┐
│ main.go │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ main / main_authsidecar / main_noauthsidecar │ │
│ │ 通过 Go build tag 切换三种构建模式 │ │
│ └──────────────────────────────────────────────────────────┘ │
└────────────────────────────┬─────────────────────────────────────┘
│
┌────────────────────────────▼─────────────────────────────────────┐
│ cmd 包（命令层） │
│ │
│ BootstrapInvocationContext() → 提前解析 --profile 全局标志 │
│ │
│ buildInternal() 构建三层命令树： │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Layer 1: Shortcuts（+ 前缀，18个业务域高层封装） │ │
│ │ Layer 2: API Commands（100+ 精选端点） │ │
│ │ Layer 3: Raw API（2500+ 原始端点，spec 驱动动态生成） │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ 内置固定命令：config / auth / profile / doctor / │
│ schema / completion / update / events │
└────────────────────────────┬─────────────────────────────────────┘
│
┌───────────────────┼────────────────────┐
▼ ▼ ▼
┌────────────────┐ ┌────────────────┐ ┌────────────────────────┐
│ shortcuts 包 │ │ cmd/service │ │ internal/cmdpolicy │
│ 18 个业务域 │ │ 动态服务命令 │ │ 命令策略引擎 │
│ ~26 个子目录 │ │ (spec-driven) │ │ (allow/deny/risk) │
└───────┬────────┘ └───────┬────────┘ └────────────────────────┘
│ │
▼ ▼
┌────────────────────────────────────────────────────────────────┐
│ extension 层（可插拔扩展） │
│ credential（凭证链）/ transport（传输拦截）/ │
│ contentsafety（内容安全）/ fileio / platform │
└────────────────────────────┬───────────────────────────────────┘
│
┌────────────────────────────▼───────────────────────────────────┐
│ internal 核心工具包 │
│ auth（OAuth/Device Flow）/ core（config/secret/workspace）/ │
│ output（JSON envelope 输出）/ errs（类型化错误体系） │
│ keychain / transport / i18n / vfs / registry │
└────────────────────────────┬───────────────────────────────────┘
│
┌────────────────────────────▼───────────────────────────────────┐
│ larksuite/oapi-sdk-go（飞书官方 Go SDK） │
└────────────────────────────────────────────────────────────────┘
使用
# Interactive login (TUI guides domain and permission level selection)
lark-cli auth login
# Identity switching: execute commands as user or bot
lark-cli calendar +agenda --as user
lark-cli im +messages-send --as bot --chat-id "oc_xxx" --text "Hello"
命令行登录后，即可使用命令行发送消息到lark
自然语言到 CLI 调用的完整链路
上面我们人类可以使用cli命令行和lark进行交互，那如果是agent那，他如何根据用户输入的自然语言映射到对应cli命令那？
Claudecode使用CLI架构
┌─────────────────────────────────────────────────────────────────────────────┐
│ 用户自然语言输入 │
│ "帮我看下今天日历" / "给张三发消息" / "创建一个文档" │
└──────────────────────────────────┬──────────────────────────────────────────┘
│
┌──────────────────────────────────▼──────────────────────────────────────────┐
│ Claude Code（AI Agent） │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Skills 层（知识注入） │ │
│ │ │ │
│ │ npx skills add larksuite/cli → 安装后注入到 Claude 上下文 │ │
│ │ │ │
│ │ lark-calendar │ lark-im │ lark-docs │ lark-base │ ... │ │
│ │ （日历技能） │ （消息技能）│ （文档技能） │ （多维表格）│ │ │
│ │ │ │
│ │ Skills 告诉 Claude： │ │
│ │ • 哪些场景用哪条命令 │ │
│ │ • 参数如何构造 │ │
│ │ • 返回值如何解读 │ │
│ └─────────────────────────────────────────┬───────────────────────────┘ │
│ │ Claude 推理后决定调用 │
│ ┌─────────────────────────────────────────▼───────────────────────────┐ │
│ │ 工具调用层（Bash Tool） │ │
│ │ │ │
│ │ Claude 生成并执行 Shell 命令： │ │
│ │ lark-cli calendar +agenda │ │
│ │ lark-cli im send-message --chat-id oc_xxx --text "..." │ │
│ │ lark-cli docs +create --title "xxx" │ │
│ │ lark-cli --profile bot-A base +search-records ... │ │
│ └─────────────────────────────────────────┬───────────────────────────┘ │
└────────────────────────────────────────────│────────────────────────────────┘
│ subprocess 调用（stdin/stdout）
┌────────────────────────────────────────────▼────────────────────────────────┐
│ lark-cli（本地进程） │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────────────────┐ │
│ │ --profile │ │ cmd 命令解析层 │ │
│ │ 凭证路由 │ │ Layer1: Shortcuts(+前缀) Layer2: API Commands │ │
│ └──────┬───────┘ │ Layer3: Raw API（spec 驱动，2500+ 端点） │ │
│ │ └──────────────────────┬───────────────────────────┘ │
│ │ │ │
│ ┌──────▼───────────────────────────────────▼───────────────────────────┐ │
│ │ internal 核心：auth / config / keychain │ │
│ │ 读取本地凭证（config init 写入的 App Secret） │ │
│ └──────────────────────────────────────┬─────────────────────────────┘ │
└─────────────────────────────────────────│───────────────────────────────────┘
│ HTTPS + OAuth Token
┌─────────────────────────────────────────▼───────────────────────────────────┐
│ 飞书开放平台 API（open.feishu.cn） │
│ │
│ /open-apis/calendar/v4/... /open-apis/im/v1/... /open-apis/docx/... │
└──────────────────────────────────────────────────────────────────────────────┘
两个核心交互点
整个链路只有两处实质性交互：
| 交互点 | 时机 | 内容 |
|---|---|---|
| Skills → Claude | 安装时写入 | 告诉 Claude 有哪些命令、何时用、参数怎么构造 |
| Bash Tool → lark-cli | 运行时 | Claude fork 子进程，读取 stdout JSON Envelope |
凭证链（用户无感知）
config init 扫码 → App Secret 写入 ~/.lark-cli/config.yaml
auth login → User Token 写入系统 Keychain
每次 CLI 调用时 → 自动读取，Claude 无需感知凭证细节
Claude 只需生成命令字符串，凭证由 lark-cli 内部三段式凭证链（Env → Sidecar → Keychain）自动处理。
自然语言如何映射到cli命令（demo）
用户输入："帮我给张三发一条消息，说今天开会推迟"
Agent 内部推理过程：
1. 意图识别：发消息 → IM 域
2. 查 lark自定义的skill文件：IM 域有 +send-message 命令
3. 参数提取：
- 接收人 = 张三（需要先查 user_id）
- 内容 = "今天开会推迟"
4. 参数不完整 → 先调 +search-user 查张三的 user_id
5. 组装命令：lark-cli +send-message --user-id xxx --text "今天开会推迟"
关键工具 --print-schema：Agent 在执行前调用它获取参数结构，验证组装的命令是否正确：
lark-cli +send-message --print-schema
# 返回：需要哪些参数、类型、是否必填
执行结果如何处理
执行命令
│
▼
stdout：JSON Envelope {"ok": true, "data": {...}}
stderr：错误 / 警告
│
▼
Agent 解析 ok 字段
├── true → 任务完成，告知用户
└── false → 读 error.type
├── authorization → 提示用户授权
├── validation → 修正参数后重试
└── confirmation → exit code 10，询问用户确认后加 --yes 重试
完整链路图
用户自然语言
│
▼
Agent LLM 推理
│── 读 lark配套 SKILL.md → 知道有哪些命令
│── 意图匹配 → 确定目标命令
│── --print-schema → 验证参数结构
│── --dry-run（可选） → 无副作用预验证
│
▼
执行 shell 命令（lark-cli +xxx --param yyy）
│
▼
解析 JSON Envelope
│
▼
根据结果决策下一步（完成 / 重试 / 询问用户）
本质
Agent 调用 CLI 与人调用 CLI 的区别只有一个：人靠记忆和文档，Agent 靠 SKILL.md 和结构化输出。
CLI 的所有设计（SKILL.md、--print-schema、--dry-run、JSON Envelope、类型化错误码、exit code 语义）都是为了让这个推理过程更可靠、更少 token 消耗、更少出错。
与 MCP Server 模式的对比
lark-cli 采用 Skills + Bash Tool 模式，而非 MCP Server 模式。两种模式的核心差异：
| 维度 | MCP Server 模式 | lark-cli Skills 模式 |
|---|---|---|
| 配置方式 |
mcp.json 中声明 |
npx skills add 安装 |
| 通信协议 | JSON-RPC over stdio/HTTP | Shell subprocess（stdout/stderr） |
| 权限粒度 | Bot 级别（公司 App） | 用户级别（个人 Token，可访问私人消息、日历） |
| 适用场景 | 团队/企业级自动化 | 个人 AI 助理 |
| 已有配置 |
mcp.json 中的 okone-lark-mcp-server
|
lark-cli + Skills |
两者互补而非替代：MCP Server 适合团队共享的 Bot 操作，lark-cli 适合以用户身份执行个人工作流。
