> 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.

# 语雀

> 配置语雀连接器，将索引限制在明确批准的知识库和附件范围内。

语雀连接器用于把已批准语雀知识库中的文档和可选附件纳入艾维斯知识检索。它以知识库路径作为范围，只读取管理员显式填写的知识库，不会自动扫描 token 可访问的全部个人或团队空间。

## 适用场景

| 场景         | 建议                                |
| ---------- | --------------------------------- |
| 产品文档问答     | 按产品知识库创建连接器，并绑定对应 Agent 或文档集。     |
| 项目 Wiki 检索 | 每个项目空间单独配置连接器，便于权限和生命周期管理。        |
| 研发规范查询     | 只同步面向目标受众发布的制度、规范和设计文档。           |
| 附件资料检索     | 仅在附件内容已获批准且格式适合解析时启用。             |
| 混合权限知识库    | 按受众拆分知识库或连接器，不依赖 Agent 提示词隔离搜索结果。 |

## 当前索引内容

语雀连接器以一个或多个 `namespace/slug` 知识库路径作为范围。最多 100 个知识库，不能重复。

| 语雀内容 | 索引行为                                             |
| ---- | ------------------------------------------------ |
| 文档页面 | 读取知识库文档清单和文档详情，将标题、正文 HTML 转换后的文本、更新时间和来源链接纳入索引。 |
| 层级节点 | 每篇文档会作为页面节点显示，便于在搜索结果中识别来源。                      |
| 附件   | 启用**包含附件**后，读取文档详情中的附件，并将可解析附件作为文档的子文档。          |

当前连接器不索引未列出的知识库、语雀团队成员权限、评论、协作记录、草稿、回收站、导出包或空间级统计。

## 前置条件

* 已准备可访问目标知识库的语雀 token。
* 已确认目标知识库路径，例如 `https://www.yuque.com/acme/product-handbook` 中的 `acme/product-handbook`。
* token 所属账号能读取目标知识库的文档详情和附件下载地址。
* 已决定是否索引附件；附件会增加同步耗时和解析失败概率。
* 已规划艾维斯访问范围。只要连接器可见，用户就可能搜索到该连接器索引的全部内容。
* 网络策略允许艾维斯后端访问 `www.yuque.com`。

## 配置数据获取入口

| 配置数据                   | 获取方式                                                                                                                                                                       |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 语雀 Token               | 登录语雀后进入 [Token 设置页](https://www.yuque.com/settings/tokens) 创建专用 token，并只授予索引所需权限。                                                                                          |
| 知识库路径 `namespace/slug` | 打开目标知识库，从 URL `https://www.yuque.com/{namespace}/{slug}` 中取 `{namespace}/{slug}`；也可在 [语雀开发者文档](https://www.yuque.com/yuque/developer/api) 中核对 repository / docs API 的路径参数。 |
| 文档详情和附件可读性             | 用同一个 token 访问语雀文档详情 API 或在知识库中打开目标文档，确认 token 所属账号能读取正文和附件下载地址。                                                                                                            |

## 在艾维斯中配置

在管理后台打开**连接器**，选择 **语雀**。先创建或选择语雀凭据，再填写知识库路径和附件开关。

| 字段       | 填写方式                                             | 说明                      |
| -------- | ------------------------------------------------ | ----------------------- |
| 语雀 Token | 粘贴专用 token                                       | 用于访问语雀 API。保存后通常不会明文展示。 |
| 语雀知识库    | 每行一个 `namespace/slug`，例如 `acme/product-handbook` | 只索引列出的知识库，最多 100 个。     |
| 包含附件     | 默认开启                                             | 将文档详情中的可解析附件作为子文档索引。    |

不要填写完整 URL、个人主页地址或只有团队名的路径。知识库路径必须包含命名空间和知识库 slug。

## 同步行为

标准管理后台创建的语雀连接器使用轮询索引，并支持 checkpoint 续跑。同步会按知识库顺序处理，每个知识库先构建稳定文档清单，再逐篇读取详情。

| 阶段   | 同步细节                            |
| ---- | ------------------------------- |
| 文档清单 | 按知识库列出文档摘要，并形成稳定清单。             |
| 文档详情 | 读取每篇文档详情，将 HTML 正文转换为可检索文本。     |
| 附件   | 附件作为文档的子文档处理；单篇文档最多处理 1000 个附件。 |
| 增量窗口 | 文档更新时间不在当前同步窗口内时会跳过。            |

附件下载地址会进行 HTTPS 安全检查；无法处理的文档或附件会记录单项失败。

## 权限边界

语雀 token 决定艾维斯能摄取哪些知识库内容，但连接器不会把语雀组织、团队、成员、知识库权限或单文档权限同步到艾维斯。

| 艾维斯访问设置 | 含义                                           |
| ------- | -------------------------------------------- |
| 私有群组    | 只有选定艾维斯群组可搜索该连接器产生的全部文档。推荐用于内部知识库。           |
| 公开      | 所有可使用该知识范围的艾维斯用户都可能搜索到索引内容。仅适用于可公开给这些用户的知识库。 |
| 自动同步权限  | 语雀当前不支持此模式。                                  |

敏感知识库应使用独立 token、独立连接器和独立艾维斯私有群组。

## 验证

1. 用一个测试知识库创建连接器，确认 token 和 `namespace/slug` 校验通过。
2. 搜索已知文档标题、正文关键词和来源链接。
3. 启用附件时，上传一个小型可解析附件并确认可被检索。
4. 搜索未列出的知识库或私人文档，确认不会返回结果。
5. 使用群组内账号和群组外账号分别测试，确认艾维斯访问边界符合预期。
6. 修改一篇测试文档后等待下一轮同步，确认增量更新可被检索。

## 常见问题排查

| 现象         | 优先检查项                                       |
| ---------- | ------------------------------------------- |
| 认证失败       | token 是否复制完整、是否过期或被撤销。                      |
| 知识库校验失败    | 路径是否为 `namespace/slug`，token 所属账号是否能打开该知识库。 |
| 文档为空或缺失    | 文档是否在目标知识库内，是否在同步窗口内更新，API 是否能返回文档详情。       |
| 附件没有进入索引   | 是否开启**包含附件**，附件下载地址是否可访问，文件类型和大小是否可解析。      |
| 未授权用户能搜到内容 | 调整艾维斯访问范围，或按知识库/受众拆分连接器。                    |

## 安全与维护建议

* 使用专用语雀 token，不复用个人高权限 token。
* 定期复核知识库列表、附件开关、token 负责人和艾维斯访问群组。
* token 疑似泄露时，立即撤销或重新生成，并更新艾维斯凭据。
* 知识库迁移、改名或权限变更后，更新连接器配置并重新验证。
* 长期不用时，先停用艾维斯连接器，再撤销语雀 token。

## 官方参考

* [语雀开发者文档](https://www.yuque.com/yuque/developer/api)

## 相关页面

* [连接器与索引](/aivis/knowledge/connectors)
* [索引设置](/aivis/knowledge/index-settings)
* [用户、群组与角色](/aivis/governance/users-and-groups)