飞书

飞书集成是一个内置单例应用：App ID 与 App Secret 由管理员保存一次，登录、通讯录同步、通知、知识同步和 Agent 会话共享同一套凭据。所有功能都必须显式开启；启用集成本身不等于开启任何功能，飞书登录尤其如此。Agent 会话只负责接收私聊消息和投递回复，执行由 Clouisle 的 Agent 运行体系完成。

配置入口

打开站点设置 > 集成 > 飞书（/site-settings/integrations/feishu）。页面按标签页组织：

App Secret、Verification Token 和 Encrypt Key 都加密保存在服务端，页面只显示是否已配置，不回显明文；密钥输入框留空表示保留已保存的值。功能开关在集成本身启用之前不可操作。

权限配置

在飞书开放平台开启机器人能力，并授予下列应用身份权限。

一键导入（推荐）

逐条勾选容易漏，尤其是通讯录与知识同步那部分。飞书开放平台支持批量导入，可以直接粘贴一份 JSON：

1. 打开飞书开放平台 → 你的应用 → 权限管理 → 批量处理 → 导入。
2. 粘贴下面的 JSON，点击下一步，确认新增权限。导入只新增权限，不影响已申请或已开通的权限。
3. 回到版本管理与发布，创建并发布新版本，完成管理员审批。

{
  "scopes": {
    "tenant": [
      "bitable:app",
      "bitable:app:readonly",
      "contact:contact.base:readonly",
      "contact:department.base:readonly",
      "contact:department.organize:readonly",
      "contact:user.base:readonly",
      "contact:user.email:readonly",
      "contact:user.employee_id:readonly",
      "docx:document:readonly",
      "im:message.group_at_msg.include_bot:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "tenant:tenant:readonly",
      "wiki:space:retrieve",
      "wiki:wiki",
      "wiki:wiki:readonly"
    ],
    "user": []
  }
}

这份清单覆盖登录、通讯录同步、通知、Agent 会话与知识同步所需权限；只启用其中一部分功能时，多出的权限不会被使用，也不会产生额外数据访问。不打算同步飞书知识库的话，可以删掉 bitable:*、docx:document:readonly、wiki:*，保存时不会被拒绝。

各权限的用途

导入上面 JSON 后，可用下表核对。下表只列 Agent 会话相关的几项；登录、通讯录与知识同步的权限要求写在各自章节。

新增权限后必须发布新的应用版本并完成所需的管理员审批；仅勾选权限不代表已生效。使用飞书的消息查询接口查看原始消息时还需要 im:message:readonly；下载资源走消息资源接口。缺少上传权限时文字回复可能正常，但产物无法发送。

登录

飞书网页登录是用户登录功能的显式选项，复用通讯录同步的应用凭据，不需要第二个身份源。

1. 在飞书开放平台为应用登记重定向地址：https://<backend-host>/api/v1/sso/callback/feishu。飞书子页会显示本站的精确值，可直接复制。
2. 确认权限配置已导入并发布；登录需要的 contact:user.base:readonly、contact:user.email:readonly 与 contact:user.employee_id:readonly 都在其中。
3. 在站点设置 > 安全开启全局 SSO；再在飞书子页打开用户登录，可选设置按钮文案。
4. 登录页只有在全局 SSO 已开启、飞书集成已启用且用户登录已打开时才显示飞书按钮。

外部身份以飞书账号的 union_id 为主、缺失时使用 open_id，因此在同一开发者账号下更换应用不会破坏已有连接。没有邮箱的飞书账号会自动生成占位地址（形如 feishu-<哈希>@accounts.clouisle.example）；生成该地址需要 contact:user.employee_id:readonly，缺少该权限时这类账号的首次登录会被拒绝，而不是创建一个占位身份。

绑定已有账号

已登录的 Clouisle 用户可以在头像菜单 > 个人资料 > 账户安全 > 已连接账户选择关联飞书。关联会保留当前账号、密码、邮箱、权限与登录会话，不创建新账号，也不按邮箱自动匹配。

• 关联入口只在全局 SSO 与飞书登录都已开启时出现。
• 已绑定到其他账号的飞书身份会被拒绝，不会转移归属。
• 通过此方式关联的账号会被通讯录同步排除：后续同步不会创建重复账号、覆盖本地资料或添加部门团队关系。

通讯录同步

通讯录同步是手动、单向的：Clouisle 从选定飞书部门创建或更新本地账号与团队，不回写飞书，也不会因为飞书成员离职或停用而停用本地账号。

1. 按权限配置导入权限并发布应用版本；通讯录同步需要的 contact:* 与 tenant:tenant:readonly 已包含在其中。
2. 在飞书后台配置通讯录权限范围，范围必须同时包含要同步的部门和部门成员。
3. 在飞书子页启用集成、打开通讯录同步并保存 App ID/Secret。
4. 浏览部门树，勾选部门并保存范围。顶层公司节点代表根部门（ID 0），选中即整个组织；选中其他部门只包含该部门及其下级。树中只显示应用可见的部门。
5. 选择同步所选部门成员。结果会报告新增、更新、跳过的账号数，以及新建团队数。

新账号没有本地密码，使用配置的默认角色和默认团队关系；飞书未返回邮箱时使用自动生成的占位地址。.example 是保留域名，永不可投递。重复同步按已保存的飞书用户 ID 匹配并更新，不会按邮箱自动合并；邮箱冲突的账号会被跳过。每个选中的飞书部门对应一个 Clouisle 团队，成员可同时属于多个部门团队。

知识同步

飞书知识同步把 Wiki 空间内容导入 Clouisle 知识库。它使用应用自己的身份读取内容，不使用登录用户的身份，并且仅超级管理员可见、可操作；普通集成设置权限不会看到该标签页。

1. 保存并启用飞书应用，并按权限配置导入权限。已包含 Wiki、Docx 与多维表格读取；如需下载图片或附件，还要在飞书后台补 drive:drive.metadata:readonly（文件元数据）与 docs:document.media:download（媒体下载）。
2. 除权限声明外，还必须为应用授予所选空间和文档的资源访问权限；只有权限声明没有资源权限仍会读取失败。
3. 在目标团队创建知识库。添加来源时选择可见的 Wiki 空间与目标知识库，并设置同步间隔：1–43200 分钟，默认 60。未显式选择 embedding 模型时使用系统默认模型，该模型必须存在且已启用。
4. 启用自动同步或选择立即同步。自动同步按设置的间隔在平台后台运行，无需额外操作。页面展示每个来源的状态、上次同步时间、结果计数、错误和转换警告。

权限边界： 导入的是团队知识，不是飞书用户权限的镜像。导入后由本地团队/知识库权限控制读取、检索、引用和共享；确认目标受众后再启用同步。撤权只会在后续同步检测到时才在本地生效。

导入的文档在本地只读：不能编辑分块、删除或重新处理。每次运行先扫描整个空间再移除缺失文档；内容变化会在成功处理后替换本地索引并保留文档 ID，未变化则不重复嵌入。下载失败、扫描不完整或处理失败会保留上一版本；确认访问被拒绝时才删除对应本地副本。停用来源会停止同步但保留已导入文档；删除来源会移除其导入的文档与索引，不影响其他本地上传。

不支持的来源类型和文件格式会跳过而不是失败，并在结果中记为跳过/不支持；没有真实失败的运行仍算成功，并清除上次错误。

通知

飞书通知是独立于 Agent 会话的通知功能，需要：

1. 飞书集成已启用，且通知已打开；
2. 已保存 App ID 与 App Secret；
3. 接收人拥有通过通讯录同步建立的飞书身份绑定；仅网页登录或手动关联不会创建该绑定。

满足后，手动通知和自动通知都可以把飞书选为外部渠道。飞书以私聊消息发送 Markdown 渲染的标题、正文与站内链接。未绑定或已停用的接收人不会收到消息；部分成功会显示成功数与总数，全部失败时按通知的重试策略重试。投递结果在通知详情中查看，与消息集成的投递记录是两套数据，见通知与外部渠道。

管理员可在消息通知标签页检查连接、搜索已绑定飞书的启用用户并发送测试消息。

Agent 会话

飞书 Agent 会话让用户私聊机器人，与自己选择的已发布 Agent 对话。消息进入 Clouisle 的 Agent 运行体系；飞书里没有第二套 Agent 循环。仅接受私聊（p2p）文本、文件、图片和富文本（post）；群聊消息和机器人自己发送的消息会被忽略。

事件接收方式

订阅事件前先按权限配置一次性导入权限并发布版本；下面只讲接收方式本身。

两种方式都在飞书开放平台一侧完成订阅配置：

长连接由平台后台自动维护，保存接收方式后立即生效。关闭智能体对话或切回 HTTP 回调会停止接收；更换应用凭据后会自动重连。

身份、个人开关与 Agent 选择

入站消息在读取发送者、Agent 或回执状态之前先完成身份校验；重复的消息会被去重。消息必须绑定到一个已映射且启用的 Clouisle 用户，以及该用户选择的、有权限使用的已发布 Agent。没有选择时，机器人返回设置/命令指引，不会创建 Agent 运行。

用户在个人设置 > 飞书中保存回复用的 Agent 并打开启用智能体对话：

• 共享通道可用时个人开关才能打开；新用户默认关闭。
• 打开开关要求通道可用、已绑定飞书身份，并已保存一个有权访问的 Agent。
• 关闭只暂停新消息接收、排队处理和未发送回复，不删除选择、历史或待处理状态；已开始的工作可能完成。重新打开后继续处理。
• 个人设置与 /use 共用同一份偏好；变更只影响之后的消息。
• /use 不能绕过已关闭的个人开关；必须先在个人设置中重新启用。

回复、卡片、附件与产物

最终回复以飞书交互卡片发送，正文是一个 Markdown 元素。长文本会按飞书限制分片（单条上限 3500 字符），不会截断多字节字符。

生成产物只投递本次运行最终结果中、作用域正好是该会话与该 Agent 团队的产物。发送时接收人仍须拥有该会话，Agent 仍须有授权，否则不会上传产物。

用户发送的附件通过飞书的消息资源接口下载，保存为会话私有的文件，并挂到当前的聊天请求上。所选 Agent 必须开启附件；文件数量、大小与扩展名限制仍然生效。下载或校验失败会返回明确回复，不会静默丢弃。附件不能回答待处理的结构化提问。

命令

普通文本会在 Agent 等待用户回答时作为答案恢复该运行。命令优先于排队消息；/new 在当前任务未结束时不会立即重置，需等待或先停止。切换 Agent 不会重路由已经接受的消息。

常见错误与排障

相关文档

• 投递记录 — 飞书回复与产物的投递状态、原始错误
• 通知与外部渠道 — 通知渠道配置与发送状态
• 消息集成总览 — 管理与个人边界、能力矩阵
• 站点设置 — 集成页在站点设置中的位置
• 消息集成 API — 飞书配置、目录/知识同步、回调与个人偏好端点
• SSO API — 集成实例与登录端点
• 管理 API — 投递记录的查询参数与字段
• 角色与权限 — 集成权限的两个域