# Lark Openapi Explorer

> 飞书/Lark 原生 OpenAPI 探索：从官方文档库中挖掘未经 CLI 封装的原生 OpenAPI 接口。当用户的需求无法被现有 lark-* skill 或 lark-cli 已注册命令满足，需要查找并调用原生飞书 OpenAPI 时使用。

- **Type:** Skill
- **Install:** `agentstack add skill-dropfan-claude-code-plugins-lark-openapi-explorer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [DropFan](https://agentstack.voostack.com/s/dropfan)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [DropFan](https://github.com/DropFan)
- **Source:** https://github.com/DropFan/claude-code-plugins/tree/master/plugins/lark/skills/lark-openapi-explorer

## Install

```sh
agentstack add skill-dropfan-claude-code-plugins-lark-openapi-explorer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> **⚙️ Cowork / Claude Desktop 执行环境说明（自动注入）**
>
> 本技能依赖本地 `lark-cli`（`@larksuite/cli`，可用 `command -v lark-cli` 定位）及其 `~/.lark-cli` 登录态（应用密钥存于 macOS keychain）。
>
> 在 Cowork 中运行任何 `lark-cli` 命令时，**必须在本地 macOS 上执行**（使用 Desktop Commander 的 `start_process` / `interact_with_process`，或其它本地 shell 工具），**不要用隔离的 Linux 沙箱** `mcp__workspace__bash`——沙箱里没有 lark-cli、也读不到 keychain。
> 执行前确保 npm 全局 bin 目录（`npm prefix -g` 输出目录下的 `bin`）在 PATH 中。
>
> （在 Claude Code 中可忽略本说明，lark-cli 在本机 shell 直接可用。）

# OpenAPI Explorer

> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 了解认证、身份切换和安全规则。

当用户的需求**无法被现有 skill 或 CLI 已注册 API 覆盖**时，使用本技能从飞书官方 markdown 文档库中逐层挖掘原生 OpenAPI 接口，然后通过 `lark-cli api` 裸调完成任务。

## 文档库结构

飞书 OpenAPI 文档以 markdown 层级组织：

```
llms.txt                          ← 顶层索引，列出所有模块文档链接
  └─ llms-.txt            ← 模块文档，包含功能概述 + 底层 API 文档链接
       └─ .md            ← 单个 API 的完整说明（方法/路径/参数/响应/错误码）
```

文档入口：

| 品牌 | 入口 URL |
|------|----------|
| 飞书 (Feishu) | `https://open.feishu.cn/llms.txt` |
| Lark | `https://open.larksuite.com/llms.txt` |

> 所有文档以**中文**编写。如果用户使用英文交流，需将文档内容翻译为英文后输出。

## 挖掘流程

严格按以下步骤逐层检索，**不要跳步或猜测 API**：

### Step 1：确认现有能力不足

```bash
# 先检查是否已有对应的 skill 或已注册 API
lark-cli  --help
```

如果已有对应命令或 shortcut，直接使用，**不需要继续挖掘**。

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

用 WebFetch 获取顶层索引，找到与需求相关的模块文档链接：

```
WebFetch https://open.feishu.cn/llms.txt
  → 提取问题："列出所有模块文档链接，找出与  相关的链接"
```

- 飞书品牌使用 `open.feishu.cn`
- Lark 品牌使用 `open.larksuite.com`
- 如不确定用户品牌，默认使用飞书

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

用 WebFetch 获取模块文档，找到具体 API 的文档链接：

```
WebFetch https://open.feishu.cn/llms-docs/zh-CN/llms-.txt
  → 提取问题："找出与  相关的 API 说明和文档链接"
```

### Step 4：获取 API 完整规范

用 WebFetch 获取具体 API 文档，提取完整的调用规范：

```
WebFetch https://open.feishu.cn/document/server-docs/.../.md
  → 提取问题："返回完整 API 规范：HTTP 方法、URL 路径、路径参数、查询参数、请求体字段（名称/类型/必填/说明）、响应字段、所需权限、错误码"
```

### Step 5：通过 CLI 调用 API

使用 `lark-cli api` 裸调：

```bash
# GET 请求
lark-cli api GET /open-apis/ --params '{"key":"value"}'

# POST 请求
lark-cli api POST /open-apis/ --data '{"key":"value"}'

# PUT 请求
lark-cli api PUT /open-apis/ --data '{"key":"value"}'

# DELETE 请求
lark-cli api DELETE /open-apis/
```

## 输出规范

向用户呈现挖掘结果时，按以下格式组织：

1. **API 名称与功能**：一句话描述
2. **HTTP 方法与路径**：`METHOD /open-apis/...`
3. **关键参数**：列出必填和常用可选参数
4. **所需权限**：scope 列表
5. **调用示例**：给出 `lark-cli api` 的完整命令
6. **注意事项**：频率限制、特殊约束等

如果用户使用英文交流，将以上所有内容翻译为英文。

## 安全规则

- **写入/删除类 API**（POST/PUT/DELETE）调用前必须确认用户意图
- 建议先用 `--dry-run` 预览请求（如支持）
- 不要猜测 API 路径或参数——必须从文档中获取确认
- 涉及敏感操作（删除群、移除成员等）时，向用户说明影响范围

## 使用场景示例

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

```bash
# Step 1: 确认 CLI 没有封装
lark-cli im --help
# → 发现没有 chat_members 相关的 create 命令

# Step 2-4: 通过文档挖掘获得 API 规范
# → POST /open-apis/im/v1/chats/:chat_id/members

# Step 5: 调用
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"}'
```

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

```bash
# Step 1: 确认 CLI 没有封装
lark-cli im --help
# → 没有 announcement 相关命令

# Step 2-4: 挖掘文档
# → PATCH /open-apis/im/v1/chats/:chat_id/announcement

# Step 5: 调用
lark-cli api PATCH /open-apis/im/v1/chats/oc_xxx/announcement \
  --data '{"revision":"0","requests":["公告内容"]}'
```

## 参考

- [lark-shared](../lark-shared/SKILL.md) — 认证和全局参数
- [lark-skill-maker](../lark-skill-maker/SKILL.md) — 如需将挖掘到的 API 固化为新 Skill

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [DropFan](https://github.com/DropFan)
- **Source:** [DropFan/claude-code-plugins](https://github.com/DropFan/claude-code-plugins)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dropfan-claude-code-plugins-lark-openapi-explorer
- Seller: https://agentstack.voostack.com/s/dropfan
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.