AgentbaseDocs
文档目录

外部数据源接入与语雀(Yuque)增量同步

本手册对应 Agentbase v2.10.0(控制台同版本)。

外部数据源(Data Sources) 是 Agentbase v2.10.0 知识库面向企业存量协同文档体系打造的自动化知识连接与增量同步引擎。通过知识库详情页的 数据源(Datasources) 页签以及 文档(Documents) 页签的「导入语雀 URL」入口,企业可将沉淀在语雀(Yuque)个人或团队空间中的产品白皮书、排障手册、标准作业程序(SOP)与架构规范无缝接入目标知识库(如 kb_enterprise_support),支持 **个人令牌(personal_yuque) 与 OAuth 2.0 授权(yuque)** 双轨认证、远端文档目录预览与按需勾选、带幂等键(idempotencyKey)的增量同步作业调度,以及同步后自动触发解析分块、向量化入库与高级派生索引(GraphRAG / RAPTOR / LLM Wiki)陈旧化标记(staleReason = data_source_sync)。


功能概述与核心场景

在企业智能客服与技术支持中心(如项目 企业智能客服与知识中台,ID:enterprise-ai-hub-210)的实际运营中,一线与二线研发团队通常在语雀知识库中日常编写和迭代技术文档,而智能体工作台(Agent Runtime)则需要消费最新就绪的知识分块。若依赖人工定期从语雀导出 Markdown 再手动上传至知识库,不仅流程繁琐,而且极易造成线上问答口径滞后。

Agentbase 外部数据源与语雀增量同步 模块围绕企业知识生命周期提供了四大核心能力:


核心概念与架构

语雀外部数据源接入、增量同步与下游索引联动架构图

flowchart TB
    subgraph ExternalYuque["1. 外部语雀知识空间 (Yuque Cloud / Enterprise)"]
        YuquePAT["个人令牌模式 (personal_yuque)\nPersonal Access Token + Repo Namespace"]
        YuqueOAuth["OAuth 2.0 授权模式 (yuque)\nOAuth2 Redirect -> Callback -> 枚举 Group & Repo"]
        SingleURL["单篇语雀文档 URL\nhttps://www.yuque.com/{group}/{book}/{slug}"]
    end

    subgraph DataSourceEngine["2. Agentbase 数据源连接与同步调度引擎 (kb_enterprise_support)"]
        DSRegistry["数据源注册表 (/datasources)\n加密保存凭证 + 绑定目标 Repo + 默认标签/subProductId"]
        DocBrowser["远端文档目录预览 (/datasources/yuque/docs)\n展示远端文档标题、Slug、更新时间与勾选范围"]
        SyncWorker["增量同步状态机 (/datasources/{dataSourceId}/sync)\nidempotencyKey 幂等校验\nqueued -> running -> completed / partial_failed / failed"]
        SyncAudit["同步运行台账 (Sync History Drawer)\naddedCount / updatedCount / skippedCount / failedCount"]
    end

    subgraph IngestionAndIndex["3. 异步解析分块与高级索引陈旧化感知 (OceanBase Shared V2)"]
        BucketStore["知识库存储桶 (kb_enterprise_docs)\n保存拉取的 Markdown 正文与内嵌图片资产"]
        ChunkEmbed["异步摄取流水线 (Ingestion Pipeline)\ntext/vlm/mineru 解析 -> 分块 -> text-embedding-v3 (1024d)"]
        StaleMark["高级索引状态感知 (/index-capabilities)\nGraphRAG / RAPTOR / Wiki 标记为 stale\n(staleReason: data_source_sync)"]
    end

    YuquePAT & YuqueOAuth --> DSRegistry
    DSRegistry --> DocBrowser --> SyncWorker
    SyncWorker --> SyncAudit
    SyncWorker -->|仅拉取新增与变更文档| BucketStore
    SingleURL -->|文档页 importYuqueUrl 直导| BucketStore
    BucketStore --> ChunkEmbed --> StaleMark

核心概念与同步状态机说明表

核心概念 / 字段关键标识 / 取值详细说明与生产行为约束
个人令牌数据源personal_yuque通过 POST /v1/knowledgebases/{kbId}/datasources/personal_yuque 创建。使用语雀个人访问令牌认证,令牌落库采用 AES-GCM 加密存储,任何查询接口均只返回脱敏掩码。
OAuth 2.0 数据源yuque先调用 GET /v1/knowledgebases/{kbId}/datasources/yuque/oauth2 获取授权跳转地址,完成回调授权与团队/知识库选择后,调用 POST /v1/knowledgebases/{kbId}/datasources/yuque 完成绑定。
单篇 URL 导入importYuqueUrl在 文档(Documents) 页签通过「导入语雀 URL」弹窗触发,适合快速引入单篇外部語雀文章,无需预先建立持久数据源连接。
同步幂等键idempotencyKey触发 POST .../datasources/{dataSourceId}/sync 时的可选请求头或请求体字段。在并发点击或网络重试场景下,相同 idempotencyKey 会复用正在运行的同步作业,防止并发重复拉取。
**同步状态:queued**排队中同步作业已创建并写入 OceanBase 任务队列表,等待后台 DataSource Worker 领取执行。
**同步状态:running**同步运行中Worker 正在请求语雀 API 拉取目录、比对远端 content_updated_at / 内容指纹,并将新增或更新的文档送入摄取队列。
**同步状态:completed**全部完成本次同步范围内的所有远端文档均已成功比对,新增与更新文档已100%投递至摄取流水线(failedCount = 0)。
**同步状态:partial_failed**部分成功大部分文档同步成功(addedCount + updatedCount > 0),但个别文档因远端权限受限、正文为空或超大附件超限而失败(failedCount > 0)。可在同步历史抽屉查看单篇失败原因。
**同步状态:failed**同步失败因语雀 Token 过期被吊销、远端知识库被删除或 SSRF 安全网络策略拦截,导致整个同步批次未能执行。
派生索引陈旧原因data_source_sync当数据源同步引发知识库内新增或更新文档分块时,系统自动将已启用的 GraphRAG、RAPTOR 与 Wiki 索引能力标记为 stale(原因码 data_source_sync)。

功能入口与权限矩阵

控制台入口 / 功能模块前端路由路径对应 REST API 端点Server SDK 方法(Node.js / Python)所需 RBAC 角色 / API Key Scope跨模块依赖关系
知识库 → 数据源列表页/console/project-default-enterprise-ai-hub-210/knowledge-base/kb-kb_enterprise_support/datasourcesGET /v1/knowledgebases/{kbId}/datasourcesknowledgeBase.listDataSources() / list_data_sources()角色:owner、admin、developer(只读成员仅可查看列表)<br/>Scope:knowledgebases.read依赖目标知识库 kb_enterprise_support 已创建
新建语雀个人令牌数据源/console/.../kb-kb_enterprise_support/datasources(点击「新建数据源 → 语雀个人令牌」)POST /v1/knowledgebases/{kbId}/datasources/personal_yuqueknowledgeBase.createPersonalYuqueDataSource()角色:owner、admin、developer<br/>Scope:knowledgebases.write依赖语雀服务端域名通过出网安全白名单校验
发起语雀 OAuth 2.0 授权并创建数据源/console/.../kb-kb_enterprise_support/datasources(点击「新建数据源 → 语雀 OAuth 2.0」)GET /v1/knowledgebases/{kbId}/datasources/yuque/oauth2<br/>POST /v1/knowledgebases/{kbId}/datasources/yuqueknowledgeBase.getYuqueOAuth2Url()<br/>knowledgeBase.createYuqueDataSource()角色:owner、admin、developer<br/>Scope:knowledgebases.write依赖平台已配置语雀 OAuth Client ID 与回调地址
预览远端语雀文档目录数据源行操作「选择同步文档 / 浏览目录」弹窗GET /v1/knowledgebases/{kbId}/datasources/yuque/docsknowledgeBase.listYuqueRemoteDocs()角色:owner、admin、developer<br/>Scope:knowledgebases.read依赖数据源凭证有效且具备远端语雀 Repo 读取权限
触发增量同步与查看同步历史数据源行操作「立即同步」与「同步记录」抽屉POST /v1/knowledgebases/{kbId}/datasources/{dataSourceId}/sync<br/>GET /v1/knowledgebases/{kbId}/datasources/{dataSourceId}knowledgeBase.syncDataSource()<br/>knowledgeBase.getDataSource()角色:owner、admin、developer<br/>Scope:knowledgebases.write同步入库依赖 kb_enterprise_docs 存储桶与 dashscope-prod 的 text-embedding-v3 模型
知识库 → 文档 → 导入语雀 URL/console/project-default-enterprise-ai-hub-210/knowledge-base/kb-kb_enterprise_support/documents(点击「导入语雀 URL」)POST /v1/knowledgebases/{kbId}/documents(传入 importYuqueUrl)knowledgeBase.importYuqueUrl()角色:owner、admin、developer<br/>Scope:knowledgebases.write直接创建文档记录并触发异步摄取(返回 HTTP 202)

功能详解与操作指南

一、「数据源绑定同步」与「文档页导入语雀 URL」的场景选型对比

在控制台中有两条路径可将语雀内容引入 kb_enterprise_support,建议按以下业务场景选型:

对比维度路径 A:知识库 → 数据源(/datasources)路径 B:知识库 → 文档 → 导入语雀 URL(importYuqueUrl)
核心定位建立长期、可重复同步的语雀知识库级管道一次性快速抓取单篇语雀文章入库
适用场景接入《智能客服 SOP 知识库》、《OceanBase 内核排障手册库》等经常更新的团队空间坐席在排障群收到一篇临时语雀复盘文档 URL,需在 1 分钟内补充进知识库
同步粒度整库全量导入、按目录勾选多篇子集、基于版本指纹的自动增量更新单次仅针对输入的单个语雀文档 URL
审计与统计独立维护 addedCount、updatedCount、skippedCount、failedCount 历史台账直接在 文档(Documents) 列表中生成单条文档摄取记录
索引联动每次增量同步有变更时自动标记 GraphRAG/RAPTOR/Wiki 为 stale (data_source_sync)视同普通文档新增(标记陈旧原因为 document_ingested)

二、方式 1:通过语雀个人令牌(personal_yuque)接入外部数据源

表单字段API 字段名标杆配置值校验规则与说明
数据源名称name企业技术支持语雀知识库 (PAT)必填,1~128 字符,用于在数据源列表中标识该连接
语雀服务地址baseUrlhttps://www.yuque.com支持公有云语雀或企业专有域名前缀;后端强制执行 HTTPS 与反 SSRF 内网地址拦截
个人访问令牌token<YUQUE_PERSONAL_ACCESS_TOKEN>必填,需在语雀「账户设置 → Token」中生成并勾选 读取知识库与文档 权限
目标知识库路径repoNamespaceob-support/kb-handbook格式为 {group_login}/{book_slug} 或语雀知识库 ID
默认层级标签defaultTags["语雀同步/技术支持", "SOP规范"]选填,该数据源同步产生的所有文档将自动继承此层级标签
默认子产品编码subProductIdob选填,自动为同步文档注入 subProductId 与 documentTag 前缀

三、方式 2:通过语雀 OAuth 2.0 授权流(yuque)接入团队知识库

对于多人协作的企业团队空间,推荐使用 OAuth 2.0 授权模式以避免绑定个人离职易失效的手工 Token:


四、触发增量同步、查看同步历史抽屉与单篇 URL 导入

1. 触发增量同步与查看统计台账

2. 在文档页直接导入单篇语雀 URL(importYuqueUrl)

3. 完整的 REST API 与 SDK 调用示例

# 1. 创建语雀个人令牌数据源 (POST /v1/knowledgebases/{kbId}/datasources/personal_yuque)
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/datasources/personal_yuque" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "企业技术支持语雀知识库 (PAT)",
    "baseUrl": "https://www.yuque.com",
    "token": "<YUQUE_PERSONAL_ACCESS_TOKEN>",
    "repoNamespace": "ob-support/kb-handbook",
    "defaultTags": ["语雀同步/技术支持"],
    "subProductId": "ob"
  }'

# 2. 获取语雀 OAuth 2.0 授权重定向链接 (GET /v1/knowledgebases/{kbId}/datasources/yuque/oauth2)
curl -X GET "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/datasources/yuque/oauth2?redirectUri=https%3A%2F%2Fappbuild-sit.oceanbase.com%2Fconsole%2Fyuque-callback" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

# 3. 预览远端语雀知识库下的文档目录列表 (GET /v1/knowledgebases/{kbId}/datasources/yuque/docs)
curl -X GET "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/datasources/yuque/docs?dataSourceId=ds_personal_yuque_01" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

# 4. 触发带幂等键的增量同步作业 (POST /v1/knowledgebases/{kbId}/datasources/{dataSourceId}/sync)
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/datasources/ds_personal_yuque_01/sync" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "syncMode": "incremental",
    "idempotencyKey": "sync_kb_support_20261022_01",
    "selectedDocSlugs": [
      "agentbase-architecture-whitepaper",
      "customer-support-sop-manual",
      "oceanbase-vector-index-troubleshooting",
      "ai-gateway-routing-billing-spec"
    ]
  }'

常见问题与排障(FAQ)

Q1:创建语雀数据源或触发同步时报错 401 Unauthorized / 403 Forbidden,状态直接变为 failed 怎么办?

Q2:为什么同步作业状态显示为 partial_failed(部分失败),该如何定位并修复失败的单篇文档?

Q3:数据源增量同步显示 completed 且 updatedCount: 2,为什么在「图谱(Graph)」或「Wiki」中还没有看到新文档的实体和百科内容?

Q4:如果我在知识库「文档」页手动编辑了某篇由语雀同步过来的文档分块,下次语雀数据源增量同步时会覆盖我的手动修改吗?


相关文档