> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # 飞书 > 连接飞书知识空间，将索引限制在已批准的 Wiki 范围，并验证文档访问权限。 使用飞书连接器可将已批准的 Wiki 内容索引到艾维斯。建议先选择一个较小的知识空间或子树，验证索引文档后，再仅在内容负责人批准的情况下扩大范围。 ## 适用场景 | 场景 | 建议 | | -------- | ----------------------------- | | 部门知识库问答 | 以知识空间或子树为单位创建连接器，并绑定对应部门群组。 | | 项目交付文档检索 | 为每个项目空间单独建连接器，便于停用、重建索引和权限复核。 | | 含附件知识库 | 仅在附件内容经过批准且部署资源足够时启用附件索引。 | | 混合敏感度知识库 | 按受众拆分连接器，不要把公开与受限文档放在同一索引范围。 | ## 索引内容 连接器会发现每个配置范围内的 Wiki 节点，并索引由飞书 Docx 文档承载的节点。标题、段落、列表、代码块、引用、任务和高亮块会保留为可搜索文本。 启用**包含附件**后，文档中受支持的图片和文件会作为子文档建立索引。由不受支持资源类型承载的 Wiki 节点会被明确记录为文档失败，而不会被静默索引。 ## 前置条件 创建连接器前，请准备一个飞书企业自建应用，并确认以下条件全部满足： 1. 应用已在目标知识空间所属租户内启用。 2. 应用身份权限覆盖读取 Wiki 空间和节点、读取 Docx 文档和块，以及在启用附件时下载云盘媒体。 3. 应用或机器人拥有每个配置知识空间的资源级访问权限。如果知识空间未以其他方式授予所需访问权，请将其添加为知识空间成员或管理员。 4. 艾维斯API 和索引 worker 可通过部署批准的 DNS 与出站网络路径访问 `open.feishu.cn`。 API 权限审批和知识空间成员权限是两项独立检查。成功获取 access token 并不能证明应用可以读取某个具体知识空间。 ## 在飞书开放平台准备应用 1. 打开飞书开放平台，进入**开发者后台**。 2. 选择目标企业后，创建**企业自建应用**。应用名称可填写 `AIvis`，应用描述可填写 `AIvis 的连接器`，图标按企业规范选择即可。 ![飞书开放平台创建企业自建应用，填写应用名称、应用描述并选择应用图标](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/2c56ebf6a86ebaecb1ec11f4613e27edc903ac072e78a9c5714e2f09c77cb23c/assets/aivis/feishu/feishu-create-app.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T120238Z&X-Amz-Expires=604800&X-Amz-Signature=042bfd7d2c7a4272a744c02a638a9462d72e69f9440fb6456381392f9bd94b07&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) 3. 进入应用左侧的**凭证与基础信息**，在**应用凭证**区域复制 `App ID` 和 `App Secret`。这两个值会分别填入艾维斯的飞书凭据字段。 ![飞书开放平台凭证与基础信息页面，应用凭证区域展示 App ID 和 App Secret](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/79e2a2be8cac98583946e2222ecac864cfa36d5ba86d2c19e37dd25a464964bd/assets/aivis/feishu/feishu-app-credentials.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T120238Z&X-Amz-Expires=604800&X-Amz-Signature=a54bb0021b0eefb40862d0fb143fba6acbbea7cb52664982d49d0f1f506b25e9&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) 4. 在**权限管理**中添加连接器所需的 Wiki、Docx 和可选云盘媒体只读权限，并按企业流程提交审批。 5. 在**版本管理与发布**中创建并发布应用版本。飞书后台显示“应用发布后，当前配置方可生效”时，未发布的权限或配置不会被连接器使用。 6. 将应用或机器人加入要索引的知识空间，或由空间管理员授予它能读取目标根节点的权限。 不要把截图、共享文档或工单中的 `App Secret` 原样转发给无关人员。若密钥已外泄，请在飞书开放平台重新生成密钥，并同步更新艾维斯凭据。 ## 创建凭据 在艾维斯管理后台中创建飞书凭据，并填写： | 字段 | 值 | | ------------- | ------------------- | | 飞书 App ID | 企业自建应用的 App ID。 | | 飞书 App Secret | 企业自建应用的 App Secret。 | 艾维斯会使用这两个值换取短期 `tenant_access_token` 并自动刷新。不要在任一凭据字段中粘贴用户 access token 或 tenant access token，也不要将 App Secret 放入 Agent 指令、对话消息或共享文档。 如果凭据校验失败，请回到飞书开放平台的**凭证与基础信息**页面重新复制 `App ID` 和 `App Secret`，并确认应用已经发布到目标企业。 ## 获取索引范围 每个连接器至少需要一个明确范围。请使用以下任一格式： ```text SPACE_ID SPACE_ID/ROOT_NODE_TOKEN ``` | 格式 | 结果 | | -------------------------- | ----------------------- | | `SPACE_ID` | 索引该知识空间内所有受支持的 Wiki 文档。 | | `SPACE_ID/ROOT_NODE_TOKEN` | 仅索引指定 Wiki 节点及其后代。 | 获取 `SPACE_ID` 时，可以打开知识空间设置并复制 URL 中显示的空间标识，也可以调用飞书知识空间列表 API，读取 `data.items[].space_id`。获取 `ROOT_NODE_TOKEN` 时，请打开作为根节点的页面，复制其 URL 中 `/wiki/` 后面的 token。 请将两个占位符替换为真实值。字面量 `root_node_token` 不是有效的子树根节点。根节点必须属于斜杠前指定的知识空间。标识符只能包含字母、数字、下划线和连字符。 ## 配置连接器 ![飞书连接器表单，填写连接器名称、知识空间范围、附件开关和文档访问权限](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/4b928071a4b68a23fb6ef9f894d792cbcfb4d573dbe4a7567ffcb019dd75aa6b/assets/aivis/feishu/feishu-connector-form.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T120238Z&X-Amz-Expires=604800&X-Amz-Signature=dff2196022b330e826b220c4283b015be9033a1257ff03e61d269d297515e133&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) 1. 打开**文档与知识**，选择**飞书**，并选择上面创建的凭据。 2. 填写**连接器名称**。这是必填项，建议使用能说明空间和用途的名称，例如 `飞书-产品知识库` 或 `飞书-项目A交付文档`。 3. 在**飞书知识空间范围**中点击**新建**，为每个已批准范围填写一个 `SPACE_ID` 或 `SPACE_ID/ROOT_NODE_TOKEN`。系统会拒绝重复范围。 4. 仅在部署获准索引嵌入图片和文件时启用**包含附件**。启用后，受支持的图片和文件附件会作为子文档进入索引。 5. 设置**文档访问权限**。选择**公开**表示当前工作区内可使用该文档集的用户都能检索内容；如果知识空间只允许部分团队访问，请选择私有或指定群组。 6. 点击**创建连接器**。保存前，艾维斯会验证每一个配置范围；验证失败时请先修正凭据、范围或飞书资源权限。 建议先用一个小范围完成首次创建和索引验证，再扩大到完整知识空间。 ## 验证索引 1. 确认连接器创建成功，且没有验证错误。 2. 运行一次索引尝试并等待完成。 3. 检查已索引文档数量和每篇文档的失败信息。不受支持的 Wiki 资源类型可能显示为明确失败。 4. 打开一篇有代表性的已索引文档，确认标题、正文、层级、来源链接和可选附件子文档正确。 5. 将生成的文档集附加到测试 Agent，并提出一个只能从已索引飞书文档中找到答案的问题，同时要求 Agent 引用来源文档。 修改应用权限、知识空间成员身份、范围值或附件设置后，请重新运行索引尝试并重复以上检查。 ## 故障排查 | 现象 | 可能原因与处理方式 | | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `Feishu credential is invalid` | 确认 App ID 与 App Secret 属于同一个已启用的企业自建应用。艾维斯会自行获取 tenant token，请勿使用复制的 access token 替代。 | | 错误码 `99991672` | 应用缺少当前 Wiki、Docx 或云盘 API 所需的 OpenAPI 权限。请为应用身份添加权限，发布或审批变更后重试。 | | 错误码 `403` 或 `91403` | 应用已能获取 token，但未被目标知识空间、节点、文档或云盘资源授权。请将应用或机器人加入对应知识空间，并确认应用版本已发布。 | | 错误码 `131006` 或 `1770032` | 应用无权访问目标空间、节点、文档或媒体。请将应用或机器人以所需角色加入知识空间，并确认它能看到配置的根节点。 | | `Feishu root node does not belong to the configured space` | 斜杠后的值来自另一个知识空间。请从当前配置知识空间内的页面复制根节点 token。 | | `Feishu API request failed` | 检查访问 `open.feishu.cn` 的出站 DNS、代理、TLS 和防火墙，并在 API 与索引 worker 日志中查找上游状态或业务错误码。如果启用了 SSRF 防护，请修复将飞书公网域名解析到私网、回环、链路本地或 Fake-IP 地址的 DNS 或代理规则。 | | 输入 `SPACE_ID/root_node_token` 后范围验证失败 | 请使用 `/wiki/ROOT_NODE_TOKEN` 页面 URL 中的真实 token 替换占位符，并移除空格或不受支持的字符。 | | 文档已索引但附件失败 | 为应用授予下载云盘媒体的权限，确认资源访问权，并在启用**包含附件**后重试。 | ## 相关页面 * [连接器与索引](/aivis/knowledge/connectors)介绍连接器运行和文档集。 * [索引设置](/aivis/knowledge/index-settings)介绍部署级索引行为。