# 飞书项目 (Meegle) 接入流程

> 2026-07-09 实际踩坑记录

## 背景

宝锐生物使用飞书项目 (`project.feishu.cn/xsguanli`) 管理销售活动和CRM数据。
目标：通过 API 直接读取飞书项目数据（客户、活动、审批），替代手动Excel导出。

## 完整接入流水线

### 第一层：飞书 OAuth 用户授权

```bash
# 1. 飞书开放平台创建应用 → 获取 App ID + App Secret
#    https://open.feishu.cn

# 2. 存入环境变量
echo "FEISHU_APP_ID=cli_xxx" >> ~/.hermes/.env
echo "FEISHU_APP_SECRET=xxx" >> ~/.hermes/.env

# 3. 获取 tenant_access_token
curl -X POST 'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal' \
  -d '{"app_id":"...","app_secret":"..."}'

# 4. OAuth 用户授权 (重要: 必须用户授权才能访问用户空间数据)
#    配置重定向 URL → 浏览器授权 → 获取 code → 交换 user_access_token
```

### 第二层：飞书项目 MCP Server

飞书项目是独立API体系，需通过 MCP Server 接入：

```bash
# 启用 MCP（飞书项目后台 → 功能入口）
# 获取 MCP 域名 + X-Mcp-Token

hermes mcp add feishu-project \
  --url "https://xxx.feishu.cn/mcp_server/v1" \
  --header "X-Mcp-Token: abc123..."
```

### 第三层：Meegle CLI（已实现）

```bash
# 安装（中国网络用 npmmirror）
npm install -g @lark-project/meegle --registry=https://registry.npmmirror.com

# Device Code 授权
meegle auth login --device-code --host project.feishu.cn

# 验证
meegle auth status --format json

# 查询空间
meegle project search --project-key xsguanli
```

## 关键发现

| 飞书产品 | API 域 | 认证方式 | 状态 |
|---------|--------|---------|------|
| 云文档/云盘 | open.feishu.cn | App Token + OAuth | ✅ 可用 |
| 审批 | open.feishu.cn | App Token + OAuth | ✅ 可用 |
| 知识库 | open.feishu.cn | App Token + OAuth (需要wiki scope) | ⚠️ 需管理员审批 |
| 飞书项目 | project.feishu.cn | MCP Server 或 Meegle CLI | ✅ 可用 |
| 多维表格 | open.feishu.cn | App Token + OAuth | ✅ 可用 |

## 常见坑

1. **wiki scope 始终审批不过** → 绕过：用 OAuth 用户token 或 MCP
2. **飞书项目不是普通云空间** → 不能通过 drive API 访问，必须用 Project API/MCP
3. **tenant_access_token 看不到用户数据** → 必须 OAuth 用户授权获取 user_access_token
4. **npm 安装超时（中国网络）** → `--registry=https://registry.npmmirror.com`
5. **Device Code 轮询超时** → 用户需在30分钟内完成浏览器授权