知识源

知识源是智能体了解您的业务的方式。本页涵盖每种类型的知识源、 导入管道，以及点击"添加"后的预期情况。

知识源类型

类型	用途	我们摄取的内容
url	一个特定页面	爬取 + 提取主要内容 + 分块 + 嵌入
sitemap	整个网站一次性	读取站点地图，为每个 URL 分发一个 CrawlPageJob
feed	RSS / Atom 博客	与站点地图相同，但读取 <item> 条目
text	FAQ、代码片段、任何可以粘贴的内容	跳过爬取，直接分块 + 嵌入
notion	Notion 页面或数据库	OAuth 到 Notion，通过 API 获取，将每个页面视为文档
google_doc	Google Docs（Workspace）	OAuth，通过 Drive API 获取，作为文档导入
auto	访客访问的页面	由 /v1/widget/init 中的 AutoIndexPageVisit 自动排队

添加知识源

打开 /app/agents/{id}/sources。添加知识源 模态框在一个表单中处理所有类型。幕后流程：

1. 验证。URL 必须是 http/https；私有主机（10.x、192.168.x、127.x、::1）被阻止以防止 SSRF。
2. 创建知识源记录，状态为 status = pending。
3. 分发作业 — url/sitemap/feed 使用 CrawlSourceJob；连接的知识源使用 IngestNotionPageJob/IngestGoogleDocJob；粘贴的文本使用 IndexTextSourceJob。
4. 作业在 crawl 队列上运行，获取内容，创建 Document 记录，然后在 index 队列上分发 IndexDocumentJob。
5. 状态变化 从 pending → crawling → done（或 failed 并带有可在 UI 中阅读的错误消息）。

自动发现

在知识源页面，发现 按钮接受一个域名并探测可爬取的页面， 无需您列出它们。我们会：

• 读取 robots.txt 获取站点地图声明。
• 当存在时直接探测站点地图。
• 尝试一组常见路径：/about、/pricing、/features、/products、/faq、/docs、/help、/support、/contact。
• 返回可检查的列表。勾选要导入的内容，点击 添加选中项。

爬虫策略

爬虫由提供商驱动。按优先顺序：

1. Cloudflare Browser Rendering ——首选。完整 JS 渲染，快速，无 SSRF 风险，因为出口在 Cloudflare 上。当设置 CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN 时使用。
2. Browserless ——当设置 BROWSERLESS_TOKEN 时的备选。在不同供应商上的相同 headless-Chrome 行为。
3. 纯 HTTP ——服务器渲染网站的最后手段。无 JS 执行。免费。

一旦获得 HTML，ReadabilityExtractor 会剥离导航、页脚、 广告等，留下文章正文。低于 200 字符或被检测为 404 的页面会被丢弃。

分块和嵌入

提取器的文本进入 Chunker，这是一个递归分割器， 优先选择语义边界：

1. 在 markdown 标题上分割，然后在空行（段落）上分割。
2. 贪婪地打包段落到目标大小（约 2000 字符 / 约 500 token）。
3. 如果段落太大，回退到句子边界。
4. 字符窗口作为绝对的最后手段。
5. 在块之间添加小重叠，以便跨块事实保持可链接。

每个块以批处理方式嵌入（默认每次调用 100 个块），并使用元数据 upsert 到向量存储中：agent_id、document_id、 chunk_id、url、workspace_id、 source_id、lang。

重新索引和预览

从知识源列表中，每行都有：

• 重新索引 ——重新运行爬取 + 分块 + 嵌入管道。
• 预览 ——显示提取的文档和示例块，以便您发现错误的提取（例如，导航栏污染了文本）。
• 删除 ——移除知识源、其文档、其块以及相应的向量点。

Notion 和 Google Docs

两者都使用 OAuth。从 /app/integrations 连接一次； token 在静止时加密。连接后，知识源模态框允许您直接选择页面或文档。

重新同步是手动的（每个知识源的 重新索引 按钮）——我们 不会按计划轮询您的 Notion / Drive。如果您更改了 Notion 页面， 请点击该知识源上的重新索引。

"我的智能体不知道我刚刚上传的文件"

Cloudflare Vectorize 在元数据过滤查询上具有最终一致性——即使在 upsert 返回 200 OK 之后，针对该向量的 agent_id 过滤查询 通常在最初的 30 到 60 秒 内返回 0 次命中，因为元数据 索引正在跨边缘区域传播。

实际影响：新上传的文件在知识源页面立即显示为 status=indexed，但在传播窗口关闭之前，智能体无法回答 有关它的问题。上传成功横幅会提醒管理员这一点。如果一分钟后智能体仍 然不返回相关块，请打开知识源的 预览 以确认提取的 文本不为空——这是解析器端的问题，而不是向量端的问题。

首次创建 Cloudflare Vectorize 索引后的第一次上传也存在同样的问题—— 索引本身在有任何查询返回结果之前有约 2 分钟的配置延迟，即使是未过滤的查询。

存储和保留

• Postgres ——知识源、文档、块（文本 + 元数据）。
• 向量存储 ——嵌入。配置时使用 Cloudflare Vectorize，否则使用 Qdrant。
• R2 / 对象存储 ——上传时的原始工件（PDF、图像）。

删除知识源会级联：文档、块和向量点都在一个事务中消失。 知识源上没有软删除。