feishu-cli-schema

Lark OpenAPI の閲覧＋呼び出しスキル

2 つのコマンドを組み合わせて使います。

• feishu-cli schema —— OpenAPI メソッドの path／動詞／パラメーター／scope／ドキュメントリンクをローカルで検索します（完全にローカルで動作し、Token／ネットワークは不要です）
• feishu-cli api —— 任意の Lark OpenAPI エンドポイントを直接呼び出します（v1.29+、認証とエラーコードの翻訳を自動処理し、ラッパーのない 2500+ のエンドポイントにも対応）

一般的なワークフロー：schema list 发现 → schema get 看参数 + scope → feishu-cli auth check/login で scope を補完 → feishu-cli api で呼び出します。

feishu-cli：まだインストールしていない場合は、riba2534/feishu-cli でインストール方法を確認してください。

---

基本概念

パス形式：<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

パスの深さに応じて自動的に振り分けられます。

• schema に引数を指定しない → すべての service を一覧表示します
• schema <service> → その service 配下のすべての resource.method を一覧表示します
• schema <service>.<resource> → resource 配下のすべての method を一覧表示します
• schema <service>.<resource>.<method> → method の詳細を表示します（path／パラメーター／scope／docUrl を含む）

データソース

コンパイル時に internal/registry/meta_data.json（約 690KB）を embed します。auth check などのモジュールと同じメタデータを共有しています。現在、12 個の service をカバーしています：approval / attendance / calendar / drive / im / mail / minutes / sheets / slides / task / vc / wiki。

---

コマンド早見表

1. すべての service を一覧表示する

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

出力テーブル：name | version | resources 数 | title。

2. ある service のすべてのメソッドを一覧表示する

feishu-cli schema im                       # 列出 im 域全部 resource.method
feishu-cli schema list --service im        # 等价（推荐用 list，语义更清楚）
feishu-cli schema list --service im --format json

pretty 出力では resource ごとにグループ化され、HTTP verb + method 名 + description が表示されます。json 出力では、AI エージェントが後続処理しやすいよう、フラットな {service, resource, method, path, httpMethod, description} リストが表示されます。

3. resource 配下のメソッドを一覧表示する

feishu-cli schema im.messages              # messages 资源下所有 method
feishu-cli schema im.chat.members          # 含点号的 resource（最长前缀匹配）

4. 特定の method の詳細を確認する

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

pretty 出力には次の情報が含まれます。

• HTTP verb + 完全な URL path（/open-apis/im/v1/messages/{message_id}）
• メソッドの説明
• Parameters（path／query／required のマーク、型、説明、example を含む）
• Request Body（POST/PUT/PATCH/DELETE の場合のみ表示され、ネストされたフィールドを含む）
• Response Body
• Identity：tenant (bot) / user（対応する Token の種類を示します）
• Scopes：呼び出しに必要な権限
• Docs：Lark オープンプラットフォームの公式ドキュメントへのリンク

---

主な flag

flag	役割	用途
--format pretty（デフォルト）	表とインデント付きフィールドツリーで人間が読みやすく表示します	ターミナルでの閲覧
--format json	生の JSON（HTML をエスケープしません）	AI エージェントによる解析、スクリプトでの組み立て
--service <name>	schema list サブコマンド専用で、service を絞り込みます	schema <service> と同等

---

よくある使い方

1. Lark に特定の API があるか探す

feishu-cli schema list --service drive | grep -i comment

2. 呼び出し前にパラメーターを確認する

feishu-cli schema im.chats.create
# 然后用 feishu-cli api 或 feishu-cli chat create 调用

3. AI エージェントが JSON を取得して呼び出し方を推測する

feishu-cli schema sheets.spreadsheets.create --format json

4. メソッドに必要な scope を確認する

feishu-cli schema vc.meeting.get
# 看 Identity / Scopes 行即可

---

🔥 最強の組み合わせ：schema で検索 → api で呼び出し（v1.29+）

feishu-cli api <method> <path> は v1.29+ の汎用 OpenAPI 透過呼び出しコマンドです。schema と組み合わせることで、完全なワークフローを構成できます。

完全なワークフロー

# 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: 直接调（无需写代码 / 无需 curl）
feishu-cli api POST /open-apis/im/v1/chats \
  --data '{"name":"测试群","description":"by feishu-cli api"}' \
  --as bot

feishu-cli api の主な flag

Flag	用途
--params '<json>'	Query パラメーター
--data '<json>'	Body（POST/PUT/PATCH）
--data-file <path>	Body をファイルから読み込みます（- は stdin を示します）
--as bot|user|auto	使用する ID を指定します。auto = user を優先し、失敗した場合は bot にフォールバックします
--dry-run	リクエストを表示するだけで、実際には呼び出しません
--format json|pretty|table|ndjson|csv	レスポンスの表示形式（指定すると組み込みレンダラーを使用し、デフォルトの pretty を上書きします）
--jq '<expr>'	組み込みの gojq でレスポンスをフィルタリングします（外部 jq は不要です）
--raw	加工せずに出力します（デフォルトは pretty JSON）
--include-headers	レスポンスヘッダーを stderr に出力します
--output <file> / -o	stdout ではなくファイルに書き込みます（-o によるバイナリダウンロードと --format／--jq は併用できません。feishu-cli-api skill を参照してください）
--timeout <seconds>	タイムアウトを指定します（デフォルトは 30s）

組み込みエラーコード翻訳（v1.29+）

feishu-cli api は Lark の業務エラーを受け取ると、解決方法を中国語で自動表示します。対象は次のとおりです。

• 99991661/99991663/99991668/99991672/99991679/99991677 → Token の有効期限切れ、または権限不足
• 99991400 → レート制限
• 230001/230002/230020 → scope 不足。auth check --scope を案内します
• 232033 → 外部グループの権限不足（外部共有用 App への切り替えを案内します）
• 232011 → Bot／ユーザーがグループに参加していません
• 232006 → chat_id が無効です
• 232025 → App で Bot 機能が有効になっていません

URL のスマート処理

• https://open.feishu.cn / larksuite.com / larkoffice.com のプレフィックスを自動で除去します
• /open-apis/ プレフィックスを自動で補完します
• URL に埋め込まれた ?query=string を自動で query パラメーターに分割します
• #fragment を自動で無視します

# 这几种等价：
feishu-cli api GET /open-apis/authen/v1/user_info --as user
feishu-cli api GET /authen/v1/user_info --as user
feishu-cli api GET https://open.feishu.cn/open-apis/authen/v1/user_info --as user
feishu-cli api GET 'https://xxx.feishu.cn/open-apis/authen/v1/user_info?foo=bar#hash' --as user

feishu-cli-shared skill との関係

他のツール（curl/Python）で Token を再利用し、このコマンドを経由しない場合は、feishu-cli auth token --as user/bot で Token 文字列をエクスポートしてください（feishu-cli-auth skill を参照してください）。

---

踩坑

1. 路径过深会报错：schema im.messages.delete.foo → 路径过深: ...（多余片段: foo）。多写一层不会被静默吞掉。
2. 路径不存在分级提示：未知 service / resource / method 都会列出该层的所有可用候选名，便于纠正。
3. resource 含点号用最长前缀匹配：im.chat.members.create 会匹配 resource = chat.members、method = create，不必担心拆错。
4. 只读不调 API：本命令永远不发起 HTTP 请求，不消耗任何配额，没有 token 过期顾虑。要真正调用见下方"何时转其他技能"。
5. 覆盖范围 = 12 service：当前覆盖 approval / attendance / calendar / drive / im / mail / minutes / sheets / slides / task / vc / wiki；未含 docx / bitable(base) / contact / authen / board / okr / tenant / application 等业务域；如果 schema list 里没列出，说明本地元数据未收录，请去飞书 OpenAPI Explorer 查在线最新版（或本项目对应的专用 feishu-cli <模块> 命令通常都已封装好）。
6. JSON 输出不转义 HTML：< / > / & 保留原样，便于直接吞进 jq / yq 管道。

---

何时转其他技能

需求	该用什么
调 API 而且本项目有对应业务命令	feishu-cli <模块> 对应命令（msg / doc / bitable / drive…）—— 体验更好
调 API 但没对应业务命令 / 想直接走 OpenAPI	本 skill 介绍的 feishu-cli api <method> <path>（v1.29+）
给 curl/Python 拿 token	feishu-cli auth token --as user/bot（详见 feishu-cli-auth skill）
查在线最新 schema、本地没收录	飞书 OpenAPI Explorer
调"埋藏 API"（飞书文档站未收录）	见 feishu-cli-toolkit/references/embedded-api-discovery.md，已知 6 个埋藏 API
申请 scope / 登录拿 User Token	/feishu-cli-auth（auth check --scope 预检、auth login --domain --recommend 按业务域申请）
发消息/文档/卡片等具体业务	/feishu-cli-msg / /feishu-cli-read / /feishu-cli-card 等专用技能