項目概述
larksuite/cli 是飛書/Lark 官方出品的命令行工具，GitHub 13.5k stars，551 次提交，活躍度極高。
核心定位：同時服務(wù)人類用戶和 AI Agent。
覆蓋飛書 18 個業(yè)務(wù)域：IM、文檔、表格、日歷、任務(wù)、審批、考勤、Wiki、郵件、OKR、視頻會議等。
技術(shù)棧
| 層面 | 選型 |
|---|---|
| 語言 | 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
|
| 系統(tǒng)鑰匙串 | zalando/go-keyring |
| 配置格式 | gopkg.in/yaml.v3 |
| 發(fā)布工具 | goreleaser |
| 分發(fā)渠道 | npm（@larksuite/cli）+ 源碼編譯 |
整體架構(gòu)
┌──────────────────────────────────────────────────────────────────┐
│ 用戶 / AI Agent │
└────────────────────────────┬─────────────────────────────────────┘
│ CLI 調(diào)用
┌────────────────────────────▼─────────────────────────────────────┐
│ main.go │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ main / main_authsidecar / main_noauthsidecar │ │
│ │ 通過 Go build tag 切換三種構(gòu)建模式 │ │
│ └──────────────────────────────────────────────────────────┘ │
└────────────────────────────┬─────────────────────────────────────┘
│
┌────────────────────────────▼─────────────────────────────────────┐
│ cmd 包（命令層） │
│ │
│ BootstrapInvocationContext() → 提前解析 --profile 全局標(biāo)志 │
│ │
│ buildInternal() 構(gòu)建三層命令樹： │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Layer 1: Shortcuts（+ 前綴，18個業(yè)務(wù)域高層封裝） │ │
│ │ Layer 2: API Commands（100+ 精選端點） │ │
│ │ Layer 3: Raw API（2500+ 原始端點，spec 驅(qū)動動態(tài)生成） │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ 內(nèi)置固定命令：config / auth / profile / doctor / │
│ schema / completion / update / events │
└────────────────────────────┬─────────────────────────────────────┘
│
┌───────────────────┼────────────────────┐
▼ ▼ ▼
┌────────────────┐ ┌────────────────┐ ┌────────────────────────┐
│ shortcuts 包 │ │ cmd/service │ │ internal/cmdpolicy │
│ 18 個業(yè)務(wù)域 │ │ 動態(tài)服務(wù)命令 │ │ 命令策略引擎 │
│ ~26 個子目錄 │ │ (spec-driven) │ │ (allow/deny/risk) │
└───────┬────────┘ └───────┬────────┘ └────────────────────────┘
│ │
▼ ▼
┌────────────────────────────────────────────────────────────────┐
│ extension 層（可插拔擴展） │
│ credential（憑證鏈）/ transport（傳輸攔截）/ │
│ contentsafety（內(nèi)容安全）/ 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"
命令行登錄后，即可使用命令行發(fā)送消息到lark
自然語言到 CLI 調(diào)用的完整鏈路
上面我們?nèi)祟惪梢允褂胏li命令行和lark進行交互，那如果是agent那，他如何根據(jù)用戶輸入的自然語言映射到對應(yīng)cli命令那？
Claudecode使用CLI架構(gòu)
┌─────────────────────────────────────────────────────────────────────────────┐
│ 用戶自然語言輸入 │
│ "幫我看下今天日歷" / "給張三發(fā)消息" / "創(chuàng)建一個文檔" │
└──────────────────────────────────┬──────────────────────────────────────────┘
│
┌──────────────────────────────────▼──────────────────────────────────────────┐
│ Claude Code（AI Agent） │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Skills 層（知識注入） │ │
│ │ │ │
│ │ npx skills add larksuite/cli → 安裝后注入到 Claude 上下文 │ │
│ │ │ │
│ │ lark-calendar │ lark-im │ lark-docs │ lark-base │ ... │ │
│ │ （日歷技能） │ （消息技能）│ （文檔技能） │ （多維表格）│ │ │
│ │ │ │
│ │ Skills 告訴 Claude： │ │
│ │ ? 哪些場景用哪條命令 │ │
│ │ ? 參數(shù)如何構(gòu)造 │ │
│ │ ? 返回值如何解讀 │ │
│ └─────────────────────────────────────────┬───────────────────────────┘ │
│ │ Claude 推理后決定調(diào)用 │
│ ┌─────────────────────────────────────────▼───────────────────────────┐ │
│ │ 工具調(diào)用層（Bash Tool） │ │
│ │ │ │
│ │ Claude 生成并執(zhí)行 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 調(diào)用（stdin/stdout）
┌────────────────────────────────────────────▼────────────────────────────────┐
│ lark-cli（本地進程） │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────────────────┐ │
│ │ --profile │ │ cmd 命令解析層 │ │
│ │ 憑證路由 │ │ Layer1: Shortcuts(+前綴) Layer2: API Commands │ │
│ └──────┬───────┘ │ Layer3: Raw API（spec 驅(qū)動，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/... │
└──────────────────────────────────────────────────────────────────────────────┘
兩個核心交互點
整個鏈路只有兩處實質(zhì)性交互：
| 交互點 | 時機 | 內(nèi)容 |
|---|---|---|
| Skills → Claude | 安裝時寫入 | 告訴 Claude 有哪些命令、何時用、參數(shù)怎么構(gòu)造 |
| Bash Tool → lark-cli | 運行時 | Claude fork 子進程，讀取 stdout JSON Envelope |
憑證鏈（用戶無感知）
config init 掃碼 → App Secret 寫入 ~/.lark-cli/config.yaml
auth login → User Token 寫入系統(tǒng) Keychain
每次 CLI 調(diào)用時 → 自動讀取，Claude 無需感知憑證細節(jié)
Claude 只需生成命令字符串，憑證由 lark-cli 內(nèi)部三段式憑證鏈（Env → Sidecar → Keychain）自動處理。
自然語言如何映射到cli命令（demo）
用戶輸入："幫我給張三發(fā)一條消息，說今天開會推遲"
Agent 內(nèi)部推理過程：
1. 意圖識別：發(fā)消息 → IM 域
2. 查 lark自定義的skill文件：IM 域有 +send-message 命令
3. 參數(shù)提?。? - 接收人 = 張三（需要先查 user_id）
- 內(nèi)容 = "今天開會推遲"
4. 參數(shù)不完整 → 先調(diào) +search-user 查張三的 user_id
5. 組裝命令：lark-cli +send-message --user-id xxx --text "今天開會推遲"
關(guān)鍵工具 --print-schema：Agent 在執(zhí)行前調(diào)用它獲取參數(shù)結(jié)構(gòu)，驗證組裝的命令是否正確：
lark-cli +send-message --print-schema
# 返回：需要哪些參數(shù)、類型、是否必填
執(zhí)行結(jié)果如何處理
執(zhí)行命令
│
▼
stdout：JSON Envelope {"ok": true, "data": {...}}
stderr：錯誤 / 警告
│
▼
Agent 解析 ok 字段
├── true → 任務(wù)完成，告知用戶
└── false → 讀 error.type
├── authorization → 提示用戶授權(quán)
├── validation → 修正參數(shù)后重試
└── confirmation → exit code 10，詢問用戶確認后加 --yes 重試
完整鏈路圖
用戶自然語言
│
▼
Agent LLM 推理
│── 讀 lark配套 SKILL.md → 知道有哪些命令
│── 意圖匹配 → 確定目標(biāo)命令
│── --print-schema → 驗證參數(shù)結(jié)構(gòu)
│── --dry-run（可選） → 無副作用預(yù)驗證
│
▼
執(zhí)行 shell 命令（lark-cli +xxx --param yyy）
│
▼
解析 JSON Envelope
│
▼
根據(jù)結(jié)果決策下一步（完成 / 重試 / 詢問用戶）
本質(zhì)
Agent 調(diào)用 CLI 與人調(diào)用 CLI 的區(qū)別只有一個：人靠記憶和文檔，Agent 靠 SKILL.md 和結(jié)構(gòu)化輸出。
CLI 的所有設(shè)計（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 安裝 |
| 通信協(xié)議 | JSON-RPC over stdio/HTTP | Shell subprocess（stdout/stderr） |
| 權(quán)限粒度 | Bot 級別（公司 App） | 用戶級別（個人 Token，可訪問私人消息、日歷） |
| 適用場景 | 團隊/企業(yè)級自動化 | 個人 AI 助理 |
| 已有配置 |
mcp.json 中的 okone-lark-mcp-server
|
lark-cli + Skills |
兩者互補而非替代：MCP Server 適合團隊共享的 Bot 操作，lark-cli 適合以用戶身份執(zhí)行個人工作流。
