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

# 飞书插件

> 在 superun 中接入飞书登录、消息、日程、任务和通讯录能力。

# 飞书插件

飞书插件是 superun 连接飞书开放平台的基础能力。启用后，你可以把飞书账号、组织架构、群消息、机器人通知、日程和任务接入到自己的产品中。

飞书能力采用“基础插件 + 子能力”的方式组织：基础插件负责保存飞书应用凭证和登录授权，子能力按业务场景逐个启用。你不需要一次接入所有能力。

***

## 可以接入哪些能力

| 能力                                             | 适合场景              | 说明                       |
| ---------------------------------------------- | ----------------- | ------------------------ |
| 飞书登录                                           | 内部系统、客户门户、企业白名单访问 | 用户用飞书账号登录你的产品，是多数飞书能力的基础 |
| [飞书消息](/superun/integrations/feishu-message)   | 群通知、机器人消息、事件订阅    | 把业务提醒、状态变化、告警推送到飞书       |
| [飞书日程](/superun/integrations/feishu-calendar)  | 会议安排、日程同步、可用时间查询  | 在产品中创建、查询或同步飞书日历事件       |
| [飞书任务](/superun/integrations/feishu-task)      | 待办创建、任务分配、状态同步    | 将产品里的工作事项同步为飞书任务         |
| [飞书通讯录](/superun/integrations/feishu-contacts) | 成员选择、部门树、组织权限     | 读取企业成员与部门信息，用于组织架构相关流程   |

***

## 接入前需要准备

* 飞书开放平台管理员权限。
* 一个企业自建应用，并取得 **App ID** 和 **App Secret**。
* 已发布的 superun 项目域名，用于配置飞书回调地址和安全域名。
* 根据要接入的子能力，在飞书后台开通对应权限，并创建新版本发布。

<Note>
  如果只接入飞书登录，通常只需要完成基础应用和登录权限配置。任务、日程等子能力会在需要时追加授权。
</Note>

***

## 子能力权限速查

| 子能力       | 需要额外开通的权限 key                                                                                   | 类型            | 说明              |
| --------- | ----------------------------------------------------------------------------------------------- | ------------- | --------------- |
| 飞书登录      | `contact:user.base:readonly`                                                                    | user          | 读取登录用户基础身份信息    |
| 飞书任务      | `task:task:read`、`task:task:write`                                                              | user          | 查询和读写飞书任务       |
| 飞书日程      | `calendar:calendar:readonly`、`calendar:calendar`                                                | user          | 读取和写入飞书日历与日程    |
| 飞书消息      | `im:message:send_as_bot`、`im:chat:readonly`                                                     | tenant        | 机器人发消息、获取机器人所在群 |
| 飞书消息看板    | `im:message:readonly`、`im:message.group_msg`、`im:message.receive_v1`                            | tenant / user | 读取群历史消息、接收新消息事件 |
| 飞书通讯录     | `contact:contact.base:readonly`、`contact:department.base:readonly`、`contact:user.base:readonly` | tenant        | 读取通讯录、部门和成员基础信息 |
| 飞书通讯录可选字段 | `contact:user.email:readonly`、`contact:user.phone:readonly`                                     | tenant        | 读取成员邮箱和手机号      |

<Warning>
  在飞书开放平台申请权限后，必须创建并发布新版本。任务、日程等 user 类型权限还需要用户重新同意授权。
</Warning>

***

## 推荐接入顺序

<Steps>
  <Step title="先启用飞书基础插件">
    在项目的「研发」→「技能库」中启用飞书插件，按提示填写飞书应用的 App ID 和 App Secret。
  </Step>

  <Step title="先跑通飞书登录">
    飞书登录会建立用户身份和授权基础。后续任务、日程等用户级能力会复用这套登录授权。
  </Step>

  <Step title="按场景启用子能力">
    根据业务需要继续启用飞书消息、日程、任务或通讯录，不需要重复配置基础凭证。
  </Step>

  <Step title="完成平台授权和测试">
    如果新开通了权限，需要在飞书开放平台发布新版本；涉及用户授权的能力，需要用户重新同意授权。
  </Step>
</Steps>

***

## 常见问题

<AccordionGroup>
  <Accordion title="已经启用了飞书登录，再启用任务或日程还需要重新配置 App ID 吗？">
    通常不需要。任务、日程、消息和通讯录会复用飞书基础插件里的应用凭证。你只需要按对应能力补充飞书后台权限，并在需要时让用户重新授权。
  </Accordion>

  <Accordion title="为什么开通权限后还是提示权限不足？">
    飞书权限变更后需要创建新版本并发布。对于任务、日程这类用户级能力，用户还需要重新同意授权，新的权限才会生效。
  </Accordion>

  <Accordion title="可以只接入某一个子能力吗？">
    可以。先启用飞书基础插件，再按业务需要启用某个子能力即可。
  </Accordion>
</AccordionGroup>

***

## 子能力说明

<CardGroup cols={2}>
  <Card title="飞书消息" icon="message" href="/superun/integrations/feishu-message">
    接入机器人通知、群消息、消息卡片和事件订阅。
  </Card>

  <Card title="飞书日程" icon="calendar-days" href="/superun/integrations/feishu-calendar">
    接入日程创建、查询、会议安排和可用时间检查。
  </Card>

  <Card title="飞书任务" icon="list-check" href="/superun/integrations/feishu-task">
    接入任务创建、负责人、状态同步和提醒流程。
  </Card>

  <Card title="飞书通讯录" icon="users" href="/superun/integrations/feishu-contacts">
    接入成员查询、部门树、组织架构和身份映射。
  </Card>
</CardGroup>