连接器飞书
常见问题
排查飞书授权、权限、连接失效和资源库同步问题。
建议按应用配置 → 账号连接 → 数据源绑定 → 飞书资源权限 → 同步结果的顺序排查，先确认当前 EasyXAI 工作空间和飞书企业是否正确。
授权问题
| 现象 | 检查与处理 |
|---|---|
| 提示 OAuth 尚未配置，或没有可用授权客户端 | 管理员在「应用中心 → 飞书 → 自带授权应用」中添加有效凭证并启用；确认飞书已安装到当前工作空间 |
| 找不到「自带授权应用」 | 此配置入口面向工作空间管理员，请联系管理员操作 |
| 找不到应用中心 | 点击左侧「资源库」，查看侧栏下方的「扩展 → 应用中心」；当前环境未提供入口时，联系管理员确认是否开放 |
| 飞书提示重定向地址不匹配 | 核对「安全设置 → 重定向 URL」与当前部署的完整回调地址，协议、域名、路径均需一致 |
提示第三方未返回长期授权（oauth_no_refresh_token） | 确认飞书用户身份权限已开通 offline_access、版本已发布且审批通过；EasyXAI 权限范围也应包含它，然后重新发起授权 |
| 添加权限后仍然报权限不足 | 确认飞书已发布新版本；更新 EasyXAI 的完整权限清单，再让成员重新连接 |
| 提示授权已超时 | 回到 EasyXAI 重新发起连接，不要重复使用旧授权页或刷新回调页 |
| 飞书账号不能授权该应用 | 检查账号是否属于应用所在企业、是否在应用可用范围内，以及是否选择了正确的授权客户端 |
| 已配 App ID 和 App Secret，却没有连接账号 | 配置授权应用后，仍需由成员点击「连接账号 → 前往授权」完成用户授权 |
完整配置流程见配置自建应用。
为什么过一段时间需要重新连接？
飞书授权可能因为刷新凭据过期、用户撤销授权、应用权限或凭证变更而失效。offline_access 使连接能够刷新，但不代表永久有效。长时间未使用后若提示「已失效」或「需重新授权」，从已有连接的重新连接入口完成授权。
重新授权后，回到数据源确认绑定状态。失败或取消的同步任务需要重新提交。
修复原连接时请使用原来的飞书账号。若授权了另一个账号，可能生成另一条连接，原数据源和 MCP 不会因此自动切换；请重新选择要使用的账号并绑定。更多情形见更新凭据说明。
管理员轮换 App Secret 时，应同步更新 EasyXAI 的授权应用配置；如果凭据对应的 App ID 也变更，成员需要按新的应用配置重新建立授权。
资源库问题
| 现象 | 检查与处理 |
|---|---|
| 无法新建外部数据源或看不到同步按钮 | 确认有目标资源库或数据源的编辑权限 |
| 找不到外部数据源入口 | 进入目标资源库后点击「导入 → 外部数据源」 |
| 找不到 Wiki／Drive 或区域选项 | 先选择飞书，再展开创建表单中的「高级设置」，必要时向下滚动 |
| 「创建」按钮不可用 | 检查是否填写名称、选择数据来源并选中有效连接；「还没有有效账号」时需先授权或重新连接 |
| 不能选择「工作空间共享」 | 当前界面要求工作空间管理员操作，还需目标资源库或数据源的管理权限 |
| 数据源显示「待连接」 | 在该数据源中绑定当前工作空间的有效飞书连接；独立模式下每位成员都要单独绑定 |
| 能查看目录，但绑定自己的账号被拒绝 | 当前独立数据源绑定也需要编辑权限；请管理员确认数据源权限，只有查看权限不够 |
| 连接正常，但远端列表为空 | 检查选择的是 Wiki 还是 Drive；确认授权账号在飞书中能访问目标知识库或目录，再检查应用读取权限 |
| 能打开某篇文档链接，却在根目录找不到它 | 远端列表按飞书返回的知识库和云盘层级展示；可直接访问的链接不一定出现在当前根列表中，先检查所属目录和账号权限 |
| 目录可见，但预览失败 | 检查当前账号对原文的权限、文档类型，以及应用是否开通正文读取权限；目录和正文访问分别校验 |
| 另一位成员看到目录，却打不开正文 | 独立模式共享目录信息，但正文按当前成员自己的飞书授权读取；请其绑定账号并取得原文访问权限 |
| 表格或附件显示「不支持」 | 当前不支持将该条目单独选作同步起点；若已随目录展示，可通过来源链接在飞书中查看 |
| 同步中持续等待 | 目录较大或飞书限流时需要分批处理，等待状态更新；持续异常时将数据源名称、发生时间和页面错误交给管理员排查 |
| 没选满 50 项却提示任务数量超限 | 50 是选择上限；同一用户在当前工作空间最多有 10 个待处理或运行中的任务，请减少起点或等待已有任务完成 |
| 提示节点数或深度限制 | 将大型目录拆为较小的同步起点；重复提交同一个大目录不会解除限制 |
| 部分同步或同步失败 | 先检查连接状态和飞书权限，恢复后重新选择相关同步根提交；已提交任务不等于内容已同步完成 |
| 飞书删除了文档，已同步目录仍保留旧条目 | 目录不是实时视图；独立模式下某成员看不到旧条目，也不一定代表原文已删除。确认后更新同步或显式移除不再需要的同步根 |
账号正常，为什么飞书工具仍不能调用？
从应用详情连接账号只保存凭据。还需返回应用能力，在需要使用的 MCP 旁选择账号并确认「绑定成功」，再检查智能体是否添加飞书、能力是否启用。数据源绑定不能代替 MCP 绑定。
同步后为什么不能直接进行整库问答？
当前数据源同步负责整理外部资源目录，预览时按需读取正文。这个流程不会自动保存全文、建立向量索引或为 AI 开启整库检索。应用中的工具或技能是否可以读取飞书内容，需要另行检查其能力配置与授权。
删除数据源会同时删除飞书文档或账号连接吗？
不会。删除数据源清理的是 EasyXAI 中该数据源及其同步资源，飞书原文和账号连接仍保留。如果要停止账号授权，应到我的连接中单独处理，并先确认其他数据源或应用能力是否仍依赖它。
有关同步和删除范围的说明，见资源库同步。