# 飞书 API 接入指南（宝锐定制 · 2026-07-08 实测）

## 认证模式

飞书 OpenAPI 有**两种认证Token**，能力完全不同：

| Token类型 | 获取方式 | 能访问什么 | 适用场景 |
|-----------|---------|-----------|---------|
| `tenant_access_token` | App ID + App Secret → `/auth/v3/tenant_access_token/internal` | **仅**应用自己的文件/文件夹 | 应用内部数据 |
| `user_access_token` | OAuth2.0 code换token → `/authen/v1/oidc/access_token` | 用户本人能看的所有数据 | **读飞书空间/文档/表格** ✅ |

⚠️ 如果要读公司的飞书空间（知识库、云文档、多维表格），**必须**用 `user_access_token`。

## 凭证配置

```bash
# ~/.hermes/.env
FEISHU_APP_ID=cli_aac5af01fd625bdd
FEISHU_APP_SECRET=FxAZsdQWVRuPOIK8byWDccwNTan7AadN
```

## OAuth 用户授权流程（实操验证通过）

### Step 1: 配置重定向URL
飞书开放平台(open.feishu.cn) → 安全设置 → 重定向URL → 精确添加（无末尾空格/斜杠）：
```
http://127.0.0.1:8765/feishu/callback
```

### Step 2: 用户浏览器授权
```
https://open.feishu.cn/open-apis/authen/v1/authorize?app_id={APP_ID}&redirect_uri=http%3A%2F%2F127.0.0.1%3A8765%2Ffeishu%2Fcallback&state=abc123&scope=wiki:wiki:readonly+drive:drive:readonly+bitable:app:readonly+approval:approval:readonly
```

### Step 3: 提取 code → 换 user_access_token
```bash
TENANT_TOKEN=$(curl -s ...获取)
CODE="从回调URL提取"

curl -s -X POST 'https://open.feishu.cn/open-apis/authen/v1/oidc/access_token' \
  -H "Authorization: Bearer $TENANT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"grant_type\":\"authorization_code\",\"code\":\"$CODE\"}"

# → {"code":0, "data":{"access_token":"...", "expires_in":7200}}
```

### Step 4: 缓存 + 使用
```bash
echo "$ACCESS_TOKEN" > ~/.hermes/.feishu_user_token

# 读知识库
curl -H "Authorization: Bearer $(cat ~/.hermes/.feishu_user_token)" \
  "https://open.feishu.cn/open-apis/wiki/v2/spaces"

# 读云盘文件
curl -H "Authorization: Bearer $(cat ~/.hermes/.feishu_user_token)" \
  "https://open.feishu.cn/open-apis/drive/v1/files"
```

## 权限开通经验

| 权限 | 方式 | 坑 |
|------|------|-----|
| `drive:drive:readonly` | 一键开通 | ✅ 但 tenant_token 只能看应用自己的文件夹（空）；user_token 可看用户云盘 |
| `wiki:wiki:readonly` | **需管理员审批** | ❌ tenant_token 多次开通仍报99991672；user_token 绕过 |
| `bitable:app:readonly` | 一键开通 | ⚠️ 用户无个人多维表格时返回空 |
| `approval:approval:readonly` | 一键开通 | ✅（scope名需精确写对，不是`approval:instance:readonly`） |
| `contact:user:readonly` | 一键开通 | ⚠️ 返回字段可能为空 |

## 常见错误码

| 错误码 | 含义 | 解决 |
|--------|------|------|
| 99991672 | scope未开通 | 改用 user_access_token 绕过，或等管理员审批 |
| 20043 | 重定向URI不匹配 | 检查是否精确添加，无末尾空格/斜杠 |
| 20014 | access_token无效 | 检查是否使用了正确的token类型 |
| 404 | API路径不存在 | 检查路径和HTTP方法 |

## 实测 API 结果（user_token）

| API | 结果 | 说明 |
|-----|------|------|
| `/wiki/v2/spaces` | ✅ 返回1个（示例知识库） | 团队共享空间未出现在此接口 |
| `/drive/v1/files` | ✅ 返回15个文件 | 用户个人云盘：会议速递、每日摘要等 |
| `/drive/explorer/v2/root_folder/meta` | ✅ | 根文件夹token获取正常 |
| `/bitable/v1/apps` | ❌ 空列表 | 用户无个人多维表格 |
| `/search/v1/search` | ❌ 404 | 搜索API路径可能错误 |
| `/contact/v3/users` | ⚠️ 空字段 | 权限可能不足 |

## 下一步

1. 用户分享「销售管理」空间链接 → 从URL提取ID → 直接API读取
2. 或实现 token 自动刷新脚本（2h过期）
3. 飞书项目(Project)空间 → 需测试 `/project/v1/` API