> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 端到端：把专家接进飞书

> 从接入到能读写飞书文档的完整链路，含两套授权体系的区别与踩坑点

这篇把专家接到飞书里，让团队在日常聊天窗口里直接用，并且能读写你的飞书文档和多维表格。

飞书接入最容易卡住的地方不是配置，而是**两套授权是分开的**：接入让机器人能收发消息，`/auth` 才让它能碰你的文档。很多人配完接入就以为完事了，结果一让它读文档就报权限错误，然后回去反复检查接入配置——那里是好的，问题在另一套授权上。这篇会把这条分界线讲清楚。

## 你会得到什么

* 飞书里一个能对话的机器人，单聊群聊都可用
* 授权之后，专家能读写**你**有权限的飞书文档、多维表格、知识库
* 可以在飞书里直接说一句话建定时任务，结果推回同一个会话

## 关键认知：两套授权

|       | 应用授权（接入时配）   | 用户授权（`/auth` 命令）      |
| ----- | ------------ | --------------------- |
| 回答的问题 | 这个机器人能不能收发消息 | 这个机器人能不能代表**我**访问我的资源 |
| 配置者   | 飞书管理员        | 每个使用者自己               |
| 覆盖范围  | 整个企业         | 只有执行 `/auth` 的那个人     |
| 缺了会怎样 | 机器人完全不响应     | 能聊天，但读文档报权限错误         |
| 有效期   | 长期           | 有过期时间，过期需重新 `/auth`   |

<Warning>
  用户授权是**逐人**的。你自己 `/auth` 过之后一切正常，不代表同事也能用——他必须自己执行一次。这是最常见的「在我这儿是好的」类型的困惑。
</Warning>

## 第一部分：接入

### 方式 A：扫码（推荐）

<Steps>
  <Step title="进入渠道接入">
    在专家 Studio 的「渠道接入」里选飞书。
  </Step>

  <Step title="扫码">
    用**飞书管理员账号**扫描二维码。普通成员账号扫不出来——这是第一个卡点。
  </Step>

  <Step title="确认授权">
    确认后自动创建飞书应用并配好权限与回调地址。
  </Step>

  <Step title="在飞书里找到机器人">
    搜索机器人名称，发一句「你好」测试。
  </Step>
</Steps>

### 方式 B：手动配置

需要精细控制权限范围，或想复用已有飞书应用时走这条：

<Steps>
  <Step title="创建企业自建应用">
    在[飞书开放平台](https://open.feishu.cn)创建。
  </Step>

  <Step title="开启机器人能力">
    在「机器人」能力里启用。
  </Step>

  <Step title="配置事件订阅">
    回调地址从袋袋的接入面板里复制。**地址填错是「机器人不回复」的头号原因**，配完在飞书侧点一次验证。
  </Step>

  <Step title="添加权限">
    至少需要消息收发；要读通讯录、文档、多维表格的，对应权限一并加上。
  </Step>

  <Step title="回填凭证">
    把 App ID 和 App Secret 填进袋袋接入面板。
  </Step>

  <Step title="发布并等审核">
    企业自建应用需要发布版本并通过审核。**审核没过之前机器人不会响应**，这是第二个卡点，而且现象和配置错误一模一样。
  </Step>
</Steps>

### 验收接入

在飞书里给机器人发「你好」。收到回复即接入成功。没回复时按这个顺序查：应用是否已发布通过审核 → 回调地址是否正确 → 群聊里是否 @ 了机器人。

## 第二部分：用户授权

### 执行 /auth

<Steps>
  <Step title="发送命令">
    在与机器人的飞书对话里发 `/auth`。
  </Step>

  <Step title="点开链接">
    机器人回一条带授权链接的消息。
  </Step>

  <Step title="确认范围">
    在飞书 OAuth 页面确认授权范围，点同意。
  </Step>

  <Step title="回到对话">
    授权生效，可以让它读文档了。
  </Step>
</Steps>

### 验收授权

找一份你有权限的飞书文档，把链接发给机器人：

```text theme={null}
读一下这份文档的内容，用三句话总结：
https://xxx.feishu.cn/docx/xxxxxxxx
```

能读出内容即授权成功。报权限错误说明授权没生效或已过期，重新 `/auth`。

<Note>
  授权后专家的访问范围**等于你自己的访问范围**——你看不到的文档它也看不到。它不会因为被授权就获得超出你权限的访问能力。
</Note>

## 第三部分：能做什么

授权后可用的能力分三块。注意这些工具**只在飞书渠道的对话里可用**，在网页端和同一个专家聊天时它们不会出现。

### 文档

| 能做   | 说明                |
| ---- | ----------------- |
| 读    | 读出文档纯文本           |
| 建    | 新建文档，可指定文件夹       |
| 追加   | 在文末追加内容           |
| 整体重写 | **会先清空再写**，原内容不保留 |

<Warning>
  「整体重写」是清空后重写，不是智能合并。对一份有人在维护的文档说「更新一下第三节」，有可能得到「整份文档只剩第三节」。要改局部就明确说「在文末追加」，或者先让它读出来、你确认新版全文之后再让它写。
</Warning>

### 多维表格

支持查询和修改记录、以及表结构相关的操作。典型用法是把对话里得到的结论直接写进表：

```text theme={null}
把刚才整理的这 8 条客户反馈，逐条写入这个多维表格：
https://xxx.feishu.cn/base/xxxxxxxx

字段对应：反馈内容 → 「描述」，紧急程度 → 「优先级」，来源 → 「渠道」
写之前先读一下表头，确认字段名对得上再写。
```

「先读表头再写」这句要带上。字段名对不上时的默认行为可能是跳过那一列，你会得到一批缺字段的记录。

### 在飞书里建定时任务

飞书渠道有个容易被忽略的能力：可以直接在聊天里创建**袋袋的**定时任务（不是飞书日程）：

```text theme={null}
每天早上 9 点把昨天的客户反馈汇总发给我
```

这条任务会记录来源是飞书，所以到点执行后结果会推回这个飞书会话。任务本身在袋袋网页端可以查看和管理。周期同样只有 `no-repeat` / `daily` / `weekly` / `monthly` 四种，详见 [每日简报](/zh/documentation/guides/daily-briefing)。

## 群聊里的行为

* 群里必须 **@机器人** 它才响应，不会对群内所有消息插话
* 群成员各自的 `/auth` 互相独立，A 授权过不代表 B 也能读文档
* 回复以多气泡形式发送，工具执行时会有状态提示（如「正在搜索…」）
* 超长回复自动分段

## 边界与失败态

| 现象            | 原因                    | 处理                  |
| ------------- | --------------------- | ------------------- |
| 机器人完全不回复      | 应用未发布/未过审、回调地址错、群里没 @ | 按接入验收里的顺序逐项排查       |
| 能聊天但读文档报权限错   | 没做用户授权，或授权过期          | 发 `/auth` 重新授权      |
| 我能用同事不能用      | 用户授权是逐人的              | 让同事自己执行 `/auth`     |
| 读不到某份文档       | 你本人对该文档就没有权限          | 先在飞书里拿到访问权限         |
| 文档内容被清空了      | 用了整体重写而非追加            | 从飞书文档历史版本恢复；以后明确说追加 |
| 多维表格写入缺字段     | 字段名对不上被跳过             | 先读表头确认字段名，再写        |
| 网页端聊天时找不到飞书工具 | 这些工具只在飞书渠道激活          | 回到飞书对话里操作           |
| 授权链接点开报错      | 链接有时效                 | 重新发 `/auth` 拿新链接    |

## 相关页面

<CardGroup cols={2}>
  <Card title="飞书渠道" icon="comment" href="/zh/documentation/channels/feishu">
    渠道配置的完整说明
  </Card>

  <Card title="飞书工具" icon="screwdriver-wrench" href="/zh/documentation/plugins/feishu-tools">
    三个工具的全部 action 与参数
  </Card>

  <Card title="知识库连接" icon="book" href="/zh/documentation/capabilities/knowledge-connectors">
    另一条读飞书内容的路径
  </Card>

  <Card title="渠道总览" icon="layer-group" href="/zh/documentation/channels/overview">
    其他 IM 平台
  </Card>
</CardGroup>