> ## 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 連接飛書開放平台的基礎能力。啟用後，你可以把飛書帳號、組織架構、群訊息、機器人通知、日程和任務接入到自己的產品中。

飛書能力採用「基礎插件 + 子能力」的方式組織：基礎插件負責保存飛書應用憑證和登入授權，子能力按業務場景逐個啟用。你不需要一次接入所有能力。

***

## 可以接入哪些能力

| 能力                                                     | 適合場景              | 說明                       |
| ------------------------------------------------------ | ----------------- | ------------------------ |
| 飛書登入                                                   | 內部系統、客戶門戶、企業白名單訪問 | 用戶用飛書帳號登入你的產品，是多數飛書能力的基礎 |
| [飛書訊息](/zh-Hant/superun/integrations/feishu-message)   | 群通知、機器人訊息、事件訂閱    | 把業務提醒、狀態變化、告警推送到飛書       |
| [飛書日程](/zh-Hant/superun/integrations/feishu-calendar)  | 會議安排、日程同步、可用時間查詢  | 在產品中建立、查詢或同步飛書日曆事件       |
| [飛書任務](/zh-Hant/superun/integrations/feishu-task)      | 待辦建立、任務分配、狀態同步    | 將產品裡的工作事項同步為飛書任務         |
| [飛書通訊錄](/zh-Hant/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="/zh-Hant/superun/integrations/feishu-message">
    接入機器人通知、群訊息、訊息卡片和事件訂閱。
  </Card>

  <Card title="飛書日程" icon="calendar-days" href="/zh-Hant/superun/integrations/feishu-calendar">
    接入日程建立、查詢、會議安排和可用時間檢查。
  </Card>

  <Card title="飛書任務" icon="list-check" href="/zh-Hant/superun/integrations/feishu-task">
    接入任務建立、負責人、狀態同步和提醒流程。
  </Card>

  <Card title="飛書通訊錄" icon="users" href="/zh-Hant/superun/integrations/feishu-contacts">
    接入成員查詢、部門樹、組織架構和身份映射。
  </Card>
</CardGroup>