语雀 | Alephant Documentation

语雀连接器用于把已批准语雀知识库中的文档和可选附件纳入艾维斯知识检索。它以知识库路径作为范围，只读取管理员显式填写的知识库，不会自动扫描 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 设置页创建专用 token，并只授予索引所需权限。
知识库路径 `namespace/slug`	打开目标知识库，从 URL `https://www.yuque.com/{namespace}/{slug}` 中取 `{namespace}/{slug}`；也可在语雀开发者文档中核对 repository / docs API 的路径参数。
文档详情和附件可读性	用同一个 token 访问语雀文档详情 API 或在知识库中打开目标文档，确认 token 所属账号能读取正文和附件下载地址。

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

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

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

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

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

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

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

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

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