Back to Details

lark-openapi-explorer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenAPI Explorer

OpenAPI Explorer

前置条件： 先阅读 
../lark-shared/SKILL.md
 了解认证、身份切换和安全规则。
当用户的需求无法被现有 skill 或 CLI 已注册 API 覆盖时，使用本技能从飞书官方 markdown 文档库中逐层挖掘原生 OpenAPI 接口，然后通过 
lark-cli api
裸调完成任务。
Prerequisites: First read 
../lark-shared/SKILL.md
 to understand authentication, identity switching and security rules.
When users' requirements cannot be covered by existing skills or registered APIs in CLI, use this skill to layer-by-layer explore native OpenAPI interfaces from Feishu's official markdown document library, then complete tasks by directly calling them via 
lark-cli api
.

文档库结构

Document Library Structure

飞书 OpenAPI 文档以 markdown 层级组织：
llms.txt                          ← 顶层索引，列出所有模块文档链接
  └─ llms-<module>.txt            ← 模块文档，包含功能概述 + 底层 API 文档链接
       └─ <api-doc>.md            ← 单个 API 的完整说明（方法/路径/参数/响应/错误码）
文档入口：
品牌入口 URL
飞书 (Feishu)
https://open.feishu.cn/llms.txt
Lark
https://open.larksuite.com/llms.txt
所有文档以中文编写。如果用户使用英文交流，需将文档内容翻译为英文后输出。
Feishu OpenAPI documents are organized in a markdown hierarchy:
llms.txt                          ← Top-level index, listing links to all module documents
  └─ llms-<module>.txt            ← Module document, including function overview + links to underlying API documents
       └─ <api-doc>.md            ← Complete description of a single API (method/path/parameters/response/error codes)
Document Entry Points:
BrandEntry URL
Feishu
https://open.feishu.cn/llms.txt
Lark
https://open.larksuite.com/llms.txt
All documents are written in Chinese. If users communicate in English, translate the document content to English before outputting.

挖掘流程

Exploration Process

严格按以下步骤逐层检索，不要跳步或猜测 API：
Strictly follow the steps below to retrieve layer by layer, do not skip steps or guess APIs:

Step 1：确认现有能力不足

Step 1: Confirm Existing Capabilities Are Insufficient

bash
undefined
bash
undefined

先检查是否已有对应的 skill 或已注册 API

First check if there is a corresponding skill or registered API

lark-cli <可能的service> --help

如果已有对应命令或 shortcut，直接使用，**不需要继续挖掘**。
lark-cli <possible-service> --help

If there is a corresponding command or shortcut, use it directly, **no need to continue exploration**.

Step 2：从顶层索引定位模块

Step 2: Locate Modules from Top-level Index

用 WebFetch 获取顶层索引，找到与需求相关的模块文档链接：
WebFetch https://open.feishu.cn/llms.txt
  → 提取问题："列出所有模块文档链接，找出与 <用户需求关键词> 相关的链接"
  • 飞书品牌使用 
    open.feishu.cn
  • Lark 品牌使用 
    open.larksuite.com
  • 如不确定用户品牌，默认使用飞书
Use WebFetch to get the top-level index, find links to module documents related to the requirements:
WebFetch https://open.feishu.cn/llms.txt
  → Extraction question: "List all module document links and find those related to <user requirement keywords>"
  • Use 
    open.feishu.cn
    for Feishu brand
  • Use 
    open.larksuite.com
    for Lark brand
  • Default to Feishu if the user's brand is uncertain

Step 3：从模块文档定位具体 API

Step 3: Locate Specific APIs from Module Documents

用 WebFetch 获取模块文档，找到具体 API 的文档链接：
WebFetch https://open.feishu.cn/llms-docs/zh-CN/llms-<module>.txt
  → 提取问题："找出与 <用户需求> 相关的 API 说明和文档链接"
Use WebFetch to get the module document, find the document link of the specific API:
WebFetch https://open.feishu.cn/llms-docs/zh-CN/llms-<module>.txt
  → Extraction question: "Find API descriptions and document links related to <user requirement>"

Step 4：获取 API 完整规范

Step 4: Obtain Complete API Specifications

用 WebFetch 获取具体 API 文档，提取完整的调用规范：
WebFetch https://open.feishu.cn/document/server-docs/.../<api>.md
  → 提取问题："返回完整 API 规范：HTTP 方法、URL 路径、路径参数、查询参数、请求体字段（名称/类型/必填/说明）、响应字段、所需权限、错误码"
Use WebFetch to get the specific API document, extract the complete calling specifications:
WebFetch https://open.feishu.cn/document/server-docs/.../<api>.md
  → Extraction question: "Return complete API specifications: HTTP method, URL path, path parameters, query parameters, request body fields (name/type/required/description), response fields, required permissions, error codes"

Step 5：通过 CLI 调用 API

Step 5: Call APIs via CLI

使用 
lark-cli api
裸调：
bash
undefined
Use 
lark-cli api
for direct calls:
bash
undefined

GET 请求

GET request

lark-cli api GET /open-apis/<path> --params '{"key":"value"}'
lark-cli api GET /open-apis/<path> --params '{"key":"value"}'

POST 请求

POST request

lark-cli api POST /open-apis/<path> --data '{"key":"value"}'
lark-cli api POST /open-apis/<path> --data '{"key":"value"}'

PUT 请求

PUT request

lark-cli api PUT /open-apis/<path> --data '{"key":"value"}'
lark-cli api PUT /open-apis/<path> --data '{"key":"value"}'

DELETE 请求

DELETE request

lark-cli api DELETE /open-apis/<path>
undefined
lark-cli api DELETE /open-apis/<path>
undefined

输出规范

Output Specifications

向用户呈现挖掘结果时，按以下格式组织：
  1. API 名称与功能：一句话描述
  2. HTTP 方法与路径：
    METHOD /open-apis/...
  3. 关键参数：列出必填和常用可选参数
  4. 所需权限：scope 列表
  5. 调用示例：给出 
    lark-cli api
    的完整命令
  6. 注意事项：频率限制、特殊约束等
如果用户使用英文交流，将以上所有内容翻译为英文。
When presenting exploration results to users, organize them in the following format:
  1. API Name & Function: One-sentence description
  2. HTTP Method & Path: 
    METHOD /open-apis/...
  3. Key Parameters: List required and commonly used optional parameters
  4. Required Permissions: List of scopes
  5. Call Example: Provide the complete 
    lark-cli api
    command
  6. Notes: Rate limits, special constraints, etc.
If users communicate in English, translate all the above content to English.

安全规则

Security Rules

  • 写入/删除类 API（POST/PUT/DELETE）调用前必须确认用户意图
  • 建议先用 
    --dry-run
    预览请求（如支持）
  • 不要猜测 API 路径或参数——必须从文档中获取确认
  • 涉及敏感操作（删除群、移除成员等）时，向用户说明影响范围
  • Write/Delete APIs (POST/PUT/DELETE): Must confirm the user's intent before calling
  • It is recommended to use 
    --dry-run
    to preview the request first (if supported)
  • Do not guess API paths or parameters — must obtain confirmation from documents
  • When involving sensitive operations (such as deleting groups, removing members, etc.), explain the scope of impact to the user

使用场景示例

Usage Scenario Examples

场景 1：用户需要拉人进群（未被 CLI 封装）

Scenario 1: User needs to add someone to a group (not encapsulated by CLI)

bash
undefined
bash
undefined

Step 1: 确认 CLI 没有封装

Step 1: Confirm CLI has no encapsulation

lark-cli im --help
lark-cli im --help

→ 发现没有 chat_members 相关的 create 命令

→ Found no create command related to chat_members

Step 2-4: 通过文档挖掘获得 API 规范

Step 2-4: Obtain API specifications via document exploration

→ POST /open-apis/im/v1/chats/:chat_id/members

→ POST /open-apis/im/v1/chats/:chat_id/members

Step 5: 调用

Step 5: Call the API

lark-cli api POST /open-apis/im/v1/chats/oc_xxx/members
--data '{"id_list":["ou_xxx","ou_yyy"]}'
--params '{"member_id_type":"open_id"}'
undefined
lark-cli api POST /open-apis/im/v1/chats/oc_xxx/members
--data '{"id_list":["ou_xxx","ou_yyy"]}'
--params '{"member_id_type":"open_id"}'
undefined

场景 2：用户需要设置群公告

Scenario 2: User needs to set group announcements

bash
undefined
bash
undefined

Step 1: 确认 CLI 没有封装

Step 1: Confirm CLI has no encapsulation

lark-cli im --help
lark-cli im --help

→ 没有 announcement 相关命令

→ No commands related to announcement

Step 2-4: 挖掘文档

Step 2-4: Explore documents

→ PATCH /open-apis/im/v1/chats/:chat_id/announcement

→ PATCH /open-apis/im/v1/chats/:chat_id/announcement

Step 5: 调用

Step 5: Call the API

lark-cli api PATCH /open-apis/im/v1/chats/oc_xxx/announcement
--data '{"revision":"0","requests":["<html>公告内容</html>"]}'
undefined
lark-cli api PATCH /open-apis/im/v1/chats/oc_xxx/announcement
--data '{"revision":"0","requests":["<html>Announcement content</html>"]}'
undefined

参考

References

  • lark-shared — 认证和全局参数
  • lark-skill-maker — 如需将挖掘到的 API 固化为新 Skill
  • lark-shared — Authentication and global parameters
  • lark-skill-maker — If you need to solidify the explored API into a new Skill