# 飞书应用配置指南

逐步配置飞书机器人。

## 第一步：创建应用

1. 进入 **飞书开放平台开发者控制台**：[open.feishu.cn/app](https://open.feishu.cn/app)
2. 点击 **「创建自定义应用」**
3. 填写：
    - **名称**：如 "Claude Code"
    - **描述**：如 "飞书 Claude Code 桥接机器人"
    - **图标**：选一个图标和颜色
4. 点击 **创建**

## 第二步：记录凭证

1. 在应用主页，进入左侧 **「凭证与基础信息」**
2. 复制 **App ID**（如 `cli_xxxx`）和 **App Secret**
3. 填入 `.env` 的 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET`，或写入 `bots.json`

## 第三步：添加机器人能力

1. 左侧找到 **「添加功能」**（功能模块下）
2. 找到 **「机器人」**，点击 **「+ 添加」**
3. 这会启用机器人功能，并在侧边栏增加「机器人」菜单

## 第四步：配置权限

1. 左侧进入 **「权限管理」**（开发配置下）
2. 点击 **「添加权限」** 蓝色按钮
3. 在弹窗中搜索并添加以下权限：
    - **`im:message`** — 读取和发送私聊及群聊消息
    - **`im:message:readonly`** — 读取私聊及群聊消息
    - **`im:resource`** — 上传图片和文件（用于发送输出文件）
    - **`im:chat:readonly`** — 读取群信息（用于 2 人群检测）
4. 点击 **「添加」**

!!! note "高级功能的可选权限"
    如需知识库同步和文档阅读功能，还需添加：

    - **`docx:document:readonly`** — 读取飞书文档
    - **`wiki:wiki`** — 读写知识库页面
    - **`docx:document`** — 创建/编辑文档（知识库同步需要）
    - **`drive:drive`** — 访问云文档

## 第五步：配置事件

!!! warning "服务必须先启动"
    「长连接」模式需要服务正在运行才能保存。先启动服务（`npm run dev`），再配置此步。

1. 左侧进入 **「事件与回调」**
2. 点击 **订阅方式** 旁的编辑图标
3. 选择 **「使用长连接接收事件」**（推荐）
4. 点击 **保存** — 飞书会验证 WebSocket 连接
5. 点击 **「添加事件」**（现在可用了）
6. 搜索 `im.message.receive`
7. 勾选 **「接收消息」**（`im.message.receive_v1`）
8. 点击 **确认**
9. 弹窗提示建议的权限时，点击 **「添加」**

## 第六步：发布应用

1. 点击顶部的 **「创建版本」**（或进入版本管理与发布）
2. 填写：
    - **版本号**：如 "1.0.0"
    - **更新说明**：如 "初始发布"
3. 默认功能应包含手机端和桌面端的「机器人」
4. 点击 **保存**，然后在确认弹窗中点击 **发布**
5. 如果组织允许小应用自动审批，会立即上线

## 第七步：测试

1. 打开飞书
2. 搜索你的机器人名字（如 "Claude Code"）
3. 发送一条测试消息
4. 机器人应该回复一个流式卡片，展示 Claude 的响应