当前位置：首页 > news >正文

larksuite-cliskill

news 2026/6/24 4:09:24

项目概述
源码地址：https://github.com/larksuite/cli

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 内部推理过程：

意图识别：发消息 → IM 域
查 lark自定义的skill文件：IM 域有 +send-message 命令
参数提取：
- 接收人 = 张三（需要先查 user_id）
- 内容 = “今天开会推迟”
参数不完整 → 先调 +search-user 查张三的 user_id
组装命令：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 适合以用户身份执行个人工作流。

查看全文

http://www.gsyq.cn/news/1582462.html