飞书 CLI 技术架构：三层调用设计，安全可控的 AI Agent 自动化
2026/7/17大约 5 分钟
如何设计一个安全可控的飞书 CLI？
三层调用架构，从快捷命令到全 API 覆盖
输入防注入、终端输出净化、OS 原生密钥链存储
AI Agent 友好的 JSON 契约，大幅提升调用成功率
来源：飞书官方 CLI，larksuite 团队维护
技术架构全景
三层调用架构，按需选择粒度
┌─────────────────────────────────────────────────────────┐
│ 三层调用架构 │
├─────────────────────────────────────────────────────────┤
│ │
│ 整体架构： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 🤖 人类用户 / AI Agent │ │
│ │ ↓ │ │
│ │ 🎨 lark-cli（飞书官方 CLI 工具） │ │
│ │ ↓ │ │
│ │ 三层调用架构： │ │
│ │ ┌─────────────────────────────────────────┐ │ │
│ │ │ │ │ │
│ │ │ 第 1 层：快捷命令（Shortcuts） │ │ │
│ │ │ · 以 + 为前缀 │ │ │
│ │ │ · 人类与 AI 友好化封装 │ │ │
│ │ │ · 智能默认值 │ │ │
│ │ │ · 表格输出 │ │ │
│ │ │ · dry-run 预览 │ │ │
│ │ │ │ │ │
│ │ │ 第 2 层：API 命令（API Commands） │ │ │
│ │ │ · 从飞书 OAPI 元数据自动生成 │ │ │
│ │ │ · 经过评测与准入筛选 │ │ │
│ │ │ · 100+ 精选命令 │ │ │
│ │ │ · 与平台端点一一对应 │ │ │
│ │ │ │ │ │
│ │ │ 第 3 层：通用 API 调用（Raw API） │ │ │
│ │ │ · 直接调用任意飞书开放平台端点 │ │ │
│ │ │ · 覆盖 2500+ API │ │ │
│ │ │ · 完全自定义 │ │ │
│ │ │ · 最大灵活性 │ │ │
│ │ │ │ │ │
│ │ └─────────────────────────────────────────┘ │ │
│ │ ↓ │ │
│ │ 🔌 飞书开放平台 API（2500+ API） │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ 选择建议： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ · 日常使用 → 快捷命令（Shortcuts） │ │
│ │ · 精确控制 → API 命令（API Commands） │ │
│ │ · 完全自定义 → 通用 API 调用（Raw API） │ │
│ │ · Agent 调用 → 快捷命令优先（Shortcuts） │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘第 1 层：快捷命令
人类与 AI 友好化封装
┌─────────────────────────────────────────────────────────┐
│ 第 1 层：快捷命令（Shortcuts） │
├─────────────────────────────────────────────────────────┤
│ │
│ 特点： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ · 以 + 为前缀 │ │
│ │ · 对人类与 AI 友好化封装 │ │
│ │ · 内置智能默认值 │ │
│ │ · 表格输出 │ │
│ │ · dry-run 预览 │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ 命令示例： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ # 日历议程 │ │
│ │ lark-cli calendar +agenda │ │
│ │ │ │
│ │ # 发送消息 │ │
│ │ lark-cli im +messages-send \ │ │"
│ │ --chat-id "oc_xxx" --text "Hello" │ │
│ │ │ │
│ │ # 创建文档 │ │
│ │ lark-cli docs +create \ │ │
│ │ --doc-format markdown \ │ │
│ │ --content $'<title>周报</title>\n# 本周进展' │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ 查看所有快捷命令： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ lark-cli <service> --help │ │
│ │ │ │
│ │ # 示例： │ │
│ │ lark-cli calendar --help │ │
│ │ lark-cli im --help │ │
│ │ lark-cli docs --help │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ 适用场景： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ · 快速操作 │ │
│ │ · 日常使用 │ │
│ │ · Agent 调用 │ │
│ │ · 需要智能默认值 │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘第 2 层：API 命令
从飞书 OAPI 元数据自动生成
┌─────────────────────────────────────────────────────────┐
│ 第 2 层：API 命令（API Commands） │
├─────────────────────────────────────────────────────────┤
│ │
│ 特点： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ · 从飞书 OAPI 元数据自动生成 │ │
│ │ · 经过评测与准入筛选 │ │
│ │ · 100+ 精选命令 │ │
│ │ · 与平台端点一一对应 │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ 命令示例： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ # 列出所有日历 │ │
│ │ lark-cli calendar calendars list │ │
│ │ │ │
│ │ # 查看日程实例 │ │
│ │ lark-cli calendar events instance_view \ │ │
│ │ --params '{ │ │
│ │ "calendar_id": "primary", │ │
│ │ "start_time": "1700000000", │ │
│ │ "end_time": "1700086400" │ │
│ │ }' │ │
│ │ │ │
│ │ # 列出所有消息 │ │
│ │ lark-cli im messages list │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ 适用场景： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ · 需要更多参数控制 │ │
│ │ · 需要精确控制 │ │
│ │ · API 对接 │ │
│ │ · 需要完整参数列表 │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘第 3 层：通用 API 调用
覆盖 2500+ API
┌─────────────────────────────────────────────────────────┐
│ 第 3 层：通用 API 调用（Raw API） │
├─────────────────────────────────────────────────────────┤
│ │
│ 特点： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ · 直接调用任意飞书开放平台端点 │ │
│ │ · 覆盖 2500+ API │ │
│ │ · 完全自定义 │ │
│ │ · 最大灵活性 │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ 命令示例： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ # GET 请求 │ │
│ │ lark-cli api GET \ │ │
│ │ /open-apis/calendar/v4/calendars │ │
│ │ │ │
│ │ # POST 请求 │ │
│ │ lark-cli api POST \ │ │
│ │ /open-apis/im/v1/messages \ │ │
│ │ --params '{ │ │
│ │ "receive_id_type": "chat_id" │ │
│ │ }' \ │ │
│ │ --data '{ │ │
│ │ "receive_id": "oc_xxx", │ │
│ │ "msg_type": "text", │ │
│ │ "content": "{\"text\":\"Hello\"}" │ │
│ │ }' │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ 适用场景： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ · 需要调用未封装的 API │ │
│ │ · 需要完全自定义 │ │
│ │ · 高级用法 │ │
│ │ · 需要最大灵活性 │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘安全机制
多层默认安全保护
┌─────────────────────────────────────────────────────────┐
│ 安全机制 │
├─────────────────────────────────────────────────────────┤
│ │
│ 风险提示： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 本工具可供 AI Agent 调用以自动化操作飞书/Lark │ │
│ │ 开放平台，存在模型幻觉、执行不可控、 │ │
│ │ 提示词注入等固有风险。 │ │
│ │ │ │
│ │ 授权飞书权限后，AI Agent 将以您的用户身份 │ │
│ │ 在授权范围内执行操作，可能导致敏感数据泄露、 │ │
│ │ 越权操作等高风险后果。 │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ 多层默认安全保护： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 第 1 层：输入防注入 │ │
│ │ · 防止 SQL 注入 │ │
│ │ · 防止命令注入 │ │
│ │ · 防止路径遍历 │ │
│ │ · 防止 XSS 攻击 │ │
│ │ │ │
│ │ 第 2 层：终端输出净化 │ │
│ │ · 防止敏感信息泄露 │ │
│ │ · 防止 ANSI 转义序列攻击 │ │
│ │ · 防止日志注入 │ │
│ │ · 净化错误消息 │ │
│ │ │ │
│ │ 第 3 层：OS 原生密钥链存储凭证 │ │
│ │ · 使用 OS 原生密钥链（Keychain/Secret Service） │ │
│ │ · 凭证加密存储 │ │
│ │ · 防止凭证泄露 │ │
│ │ · 自动凭证管理 │ │
│ │ │ │
│ │ 第 4 层：身份切换 │ │
│ │ · 支持以用户或机器人身份执行 │ │
│ │ · 明确身份区分 │ │
│ │ · 防止身份混淆 │ │
│ │ · 审计日志 │ │
│ │ │ │
│ │ 第 5 层：权限管理 │ │
│ │ · 细粒度权限控制 │ │
│ │ · 推荐权限集合 │ │
│ │ · 权限审计 │ │
│ │ · 最小权限原则 │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ 安全建议： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 1. 不要主动修改任何默认安全配置 │ │
│ │ 2. 将对接本工具的飞书机器人作为 │ │
│ │ 私人对话助手使用 │ │
│ │ 3. 请勿将其拉入群聊或允许其他用户 │ │
│ │ 与其交互，以避免权限被滥用或数据泄露 │ │
│ │ 4. 充分知悉全部使用风险 │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘AI Agent 友好的 JSON 契约
大幅提升 Agent 调用成功率
┌─────────────────────────────────────────────────────────┐
│ AI Agent 友好的 JSON 契约 │
├─────────────────────────────────────────────────────────┤
│ │
│ 统一的 JSON 契约： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 成功信封（stdout，exit 0）： │ │
│ │ { │ │
│ │ "ok": true, │ │
│ │ "identity": "user", │ │
│ │ "data": { │ │
│ │ "guid": "...", │ │
│ │ ... │ │
│ │ }, │ │
│ │ "meta": { │ │
│ │ "count": 1 │ │
│ │ } │ │
│ │ } │ │
│ │ │ │
│ │ 错误信封（stderr，exit 1）： │ │
│ │ { │ │
│ │ "ok": false, │ │
│ │ "identity": "user", │ │
│ │ "error": { │ │
│ │ "type": "api", │ │
│ │ "subtype": "...", │ │
│ │ "code": 99991679, │ │
│ │ "message": "...", │ │
│ │ "hint": "..." │ │
│ │ } │ │
│ │ } │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ 判断命令是否成功： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 检查 ok == true（或进程退出码） │ │
│ │ 不要用 code == 0 │ │
│ │ │ │
│ │ 与原始 OpenAPI 响应的区别： │ │
│ │ · 原始：{"code": 0, "msg": "ok", ...} │ │
│ │ · lark-cli：{"ok": true, "data": {...}} │ │
│ │ · code 只出现在 error 信封中 │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ 多种输出格式： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ --format json # 完整 JSON 响应（默认） │ │
│ │ --format pretty # 人性化格式输出 │ │
│ │ --format table # 易读表格 │ │
│ │ --format ndjson # 换行分隔 JSON（管道处理） │ │
│ │ --format csv # 逗号分隔值 │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ Agent 调用示例： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ # Bash │ │
│ │ response=$(lark-cli calendar +agenda) │ │
│ │ ok=$(echo $response | jq -r '.ok') │ │
│ │ if [ "$ok" == "true" ]; then │ │
│ │ echo "Success!" │ │
│ │ fi │ │
│ │ │ │
│ │ # Python │ │
│ │ import subprocess │ │
│ │ import json │ │
│ │ │ │
│ │ result = subprocess.run( │ │
│ │ ['lark-cli', 'calendar', '+agenda'], │ │
│ │ capture_output=True, │ │
│ │ text=True │ │
│ │ ) │ │
│ │ response = json.loads(result.stdout) │ │
│ │ if response['ok']: │ │
│ │ print("Success!", response['data']) │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘核心思想
三层调用架构，安全可控的 AI Agent 自动化
┌─────────────────────────────────────────────────────────┐
│ 核心思想 │
├─────────────────────────────────────────────────────────┤
│ │
│ lark-cli 的技术架构： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 三层调用架构，按需选择粒度： │ │
│ │ · 第 1 层：快捷命令（Shortcuts） │ │
│ │ · 第 2 层：API 命令（API Commands） │ │
│ │ · 第 3 层：通用 API 调用（Raw API） │ │
│ │ │ │
│ │ 多层默认安全保护： │ │
│ │ · 输入防注入 │ │
│ │ · 终端输出净化 │ │
│ │ · OS 原生密钥链存储凭证 │ │
│ │ · 身份切换 │ │
│ │ · 权限管理 │ │
│ │ │ │
│ │ AI Agent 友好的 JSON 契约： │ │
│ │ · 统一的成功/错误信封 │ │
│ │ · 明确的退出码 │ │
│ │ · 多种输出格式 │ │
│ │ · 大幅提升 Agent 调用成功率 │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ 这就是 lark-cli 的核心价值： │
│ ┌─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 飞书 CLI 技术架构！ │ │
│ │ │ │
│ │ 三层调用架构，安全可控的 AI Agent 自动化！ │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘收尾金句
- 如何设计一个安全可控的飞书 CLI？
- 三层调用架构，从快捷命令到全 API 覆盖
- 输入防注入、终端输出净化、OS 原生密钥链存储
- AI Agent 友好的 JSON 契约，大幅提升调用成功率
飞书 CLI 技术架构：三层调用设计，安全可控的 AI Agent 自动化！