# 飞书集成参考

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

### 1. 应用创建
- 飞书开放平台 open.feishu.cn → 创建企业自建应用
- 获取 App ID + App Secret
- 保存到 ~/.hermes/.env: FEISHU_APP_ID, FEISHU_APP_SECRET

### 2. 权限开通
必需 scope:
- `drive:drive:readonly` — 云空间
- `wiki:wiki:readonly` — 知识库
- `bitable:app:readonly` — 多维表格
- `approval:approval:readonly` — 审批（注意不是 approval:instance:readonly）

### 3. OAuth 重定向
- 安全设置 → 重定向URL → `http://127.0.0.1:8765/feishu/callback`
- 注意末尾无斜杠，无多余字符

### 4. 获取 tenant_access_token
```bash
curl -s -X POST 'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal' \
  -H 'Content-Type: application/json' \
  -d '{"app_id":"$APP_ID","app_secret":"$APP_SECRET"}'
```

### 5. 构造授权链接
```
https://open.feishu.cn/open-apis/authen/v1/authorize?app_id=$APP_ID&redirect_uri=$REDIRECT_URI&state=abc123&scope=wiki:wiki:readonly+drive:drive:readonly+bitable:app:readonly+approval:approval:readonly
```
用户浏览器打开 → 授权 → 复制地址栏 `code=` 参数

### 6. 换取 user_access_token
使用 tenant_access_token + authorization_code → user_access_token
保存到：~/.hermes/.feishu_user_token, ~/.hermes/.feishu_refresh_token

### 7. API 调用示例
```bash
USER_TOKEN=$(cat ~/.hermes/.feishu_user_token)
# 知识库
curl -s 'https://open.feishu.cn/open-apis/wiki/v2/spaces' -H "Authorization: Bearer $USER_TOKEN"
# 云空间
curl -s 'https://open.feishu.cn/open-apis/drive/v1/files' -H "Authorization: Bearer $USER_TOKEN"
```

**已验证能力**：个人云盘文件列表、知识库列表
**未覆盖**：飞书项目(project.feishu.cn) — 独立API体系，需MCP Server或Meegle CLI单独接入

## Meegle CLI 接入（飞书项目）

安装：`npm install -g @lark-project/meegle --registry=https://registry.npmmirror.com`

Device Code 授权（auth-guard 流程见 skill references/auth-guard.md）：
1. `meegle auth status --format json` — 检查
2. `meegle auth login --device-code --phase init --host project.feishu.cn --format json` — 获取验证码
3. 用户访问 verification_uri_complete 授权
4. 轮询 `meegle auth login --device-code --phase poll`

⚠️ Device Code 实际测试中授权页面可能需要飞书管理员审批

## MCP Server 接入（飞书项目）

飞书项目帮助中心 → 功能入口 → 获取 MCP 域名和 X-Mcp-Token
```bash
hermes mcp add feishu-project --url "https://xxx.feishu.cn/mcp_server/v1" --header "X-Mcp-Token: xxx"
```

## 错误码速查

| 错误码 | 含义 | 解决 |
|--------|------|------|
| 20043 | 重定向URI不匹配 | 精确配置回调URL，检查末尾斜杠 |
| 99991672 | 权限不足 | 开通对应scope |
| 99991679 | 未授权 | 重新OAuth授权 |
| 20014 | Token无效 | 重新获取tenant_access_token |