SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场feishu-cli-schema

feishu-cli-schema

编程与开发

查看项目

更新于 10-16 01:57

技能介绍

用途

feishu-cli-schema 是 feishu-cli 中的本地 OpenAPI 浏览命令，用于查询飞书 OpenAPI 方法的路径、HTTP 动词、参数、所需权限（scope）与官方文档链接。它与 feishu-cli api 命令组合，形成“查接口 → 补权限 → 调接口”的完整工作流。

主要能力

schema：本地浏览

采用三段式路径格式 <service>.<resource>.<method>：

  • service：业务域，如 im / docs / drive / bitable / calendar / vc / mail / wiki / approval / sheets / slides / task / attendance / minutes。
  • resource：资源，可含点号，按最长前缀匹配，如 messages / events / records / chat.members。
  • method：动作，如 create / get / list / update / delete / patch。

按路径深度自动分发：

  • 无参数 → 列出所有 service；
  • <service> → 列出该 service 下所有 resource.method；
  • <service>.<resource> → 列出该 resource 下的所有 method；
  • <service>.<resource>.<method> → 显示 method 详情，含 path / 参数 / scope / docUrl。

数据来源为编译期 embed 的 internal/registry/meta_data.json（约 690KB），与 auth check 等模块共用同一份元数据。当前覆盖 12 个 service：approval / attendance / calendar / drive / im / mail / minutes / sheets / slides / task / vc / wiki。

api：通用透传调用（v1.29+）

feishu-cli api <method> <path> 可直接调用任意飞书 OpenAPI 端点，自动鉴权并翻译错误码，覆盖 2500+ 未封装 API。

使用方式

schema 命令示例

列出所有 service：

feishu-cli schema
# 等价：
feishu-cli schema list

列出某 service 的所有方法：

feishu-cli schema im
feishu-cli schema list --service im
feishu-cli schema list --service im --format json

列出 resource 下的方法：

feishu-cli schema im.messages
feishu-cli schema im.chat.members

查具体 method 详情：

feishu-cli schema im.messages.delete
feishu-cli schema im.messages.delete --format json

pretty 输出包含：HTTP verb 与完整 URL path、方法描述、Parameters（path / query / required 标记 + 类型 + 描述 + example）、Request Body（POST/PUT/PATCH/DELETE 才显示）、Response Body、Identity（tenant/user，指明支持的 Token 类型）、Scopes（所需权限点）、Docs（官方文档链接）。

关键 flag

  • --format pretty（默认）：人类可读，表格 + 缩进字段树，适合终端阅读。
  • --format json：原始 JSON（不转义 HTML），适合 AI Agent 解析、脚本拼装。
  • --service <name>：仅 schema list 子命令使用，过滤 service，等价于 schema <service>。

完整工作流（schema 查 + api 调）

# Step 1: schema 查 path + scope + token 类型
feishu-cli schema im.chats.create
# 输出: POST /open-apis/im/v1/chats
#       Identity: tenant (bot)
#       Scopes:   im:chat

# Step 2: scope 不够时补
feishu-cli auth check --scope "im:chat"
feishu-cli auth login --scope "im:chat"

# Step 3: 直接调
feishu-cli api POST /open-apis/im/v1/chats \
  --data '{"name":"测试群","description":"by feishu-cli api"}' \
  --as bot

feishu-cli api 关键 flag

  • --params '<json>'：Query 参数。
  • --data '<json>'：Body（POST/PUT/PATCH）。
  • --data-file <path>：Body 从文件读（- 表示 stdin）。
  • --as bot|user|auto：强制身份；auto = user 优先回退 bot。
  • --dry-run：仅打印请求，不实际调。
  • --format json|pretty|table|ndjson|csv：响应渲染格式。
  • --jq '<expr>'：内置 gojq 过滤响应。
  • --raw：原样输出。
  • --include-headers：stderr 打印响应头。
  • --output <file> / -o：写入文件而非 stdout。
  • --timeout <seconds>：自定义超时（默认 30s）。

内置错误码翻译（v1.29+）

feishu-cli api 收到业务错误时会自动打印中文解决方案，覆盖如：99991661/99991663/99991668/99991672/99991679/99991677（Token 失效或权限不足）、99991400（限流）、230001/230002/230020（scope 不足）、232033（外部群权限不足）、232011（Bot/用户不在群）、232006（chat_id 无效）、232025（App 未启用 Bot 能力）等。

URL 智能处理

自动剥除 https://open.feishu.cn / larksuite.com / larkoffice.com 前缀，自动补 /open-apis/ 前缀，自动拆解内嵌 query string，自动忽略 #fragment。

适用场景

  • 查找飞书是否提供某个 API。
  • 调用前查参数与 scope 要求。
  • AI Agent 拿 JSON 推断调用方式。
  • 直接透传调用未封装的 OpenAPI 端点。

限制

  • 路径过深会报错，如 schema im.messages.delete.foo 会提示多余片段。
  • 路径不存在会分级提示可用候选名。
  • resource 含点号时按最长前缀匹配，如 im.chat.members.create 匹配 resource = chat.members、method = create。
  • schema 命令只读，不发 HTTP 请求，不消耗配额。
  • 覆盖范围限 12 个 service，未含 docx / bitable(base) / contact / authen / board / okr / tenant / application 等业务域；未列出即本地元数据未收录，需查飞书 OpenAPI Explorer 在线最新版。
  • JSON 输出不转义 HTML，< / > / & 保留原样。
  • 若尚未安装 feishu-cli，需前往 riba2534/feishu-cli 获取安装方式。