页面发现与抓取优先级

Loci 接受任意一个公开文档页面作为入口。同步开始后，它会先判断文档源类型，再选择结构化程度最高的发现方式。只要高优先级来源有效，后续方式便不会执行。

识别顺序

Loci 按以下顺序处理文档源：

优先级	识别结果	处理方式
1	公开 GitHub 仓库	下载默认分支的 ZIP 快照，提取 Markdown。
2	有效的 `llms.txt`	将清单作为权威来源，只抓取清单列出的页面。
3	GitHub Pages 或 GitLab Pages	跳过 OpenAPI 探测，直接进入静态网页流程。
4	OpenAPI 或 Swagger 文档	探测同站 JSON 规范，将接口信息整理为 Markdown。
5	普通文档站	结合 Sitemap、已知页面和页面链接递归发现内容。

例如，入口同时提供 llms.txt 和 Sitemap 时，Loci 只使用 llms.txt。接口文档入口没有命中有效 OpenAPI JSON 时，Loci 会继续按普通网页处理，不会因为探测失败而终止同步。

公开 GitHub 仓库

当入口符合 github.com/<owner>/<repo> 时，Loci 会把它识别为仓库文档源。仓库路径的识别优先于站点探测。

Loci 会执行以下操作：

读取公开仓库的默认分支和当前提交。
流式下载该提交的 ZIP 快照。
按仓库相对路径提取 .md 文件。
使用文件名作为标题，并保留原有目录层级。
通过 Markdown AST 改写相对链接和图片地址。

相对图片会指向固定提交的 raw.githubusercontent.com 地址，相对文档链接会指向固定提交的 GitHub Blob 页面。Loci 不会下载图片，也不会改写代码块中的相似文本。

仓库同步使用快照替换语义。成功同步后，仓库中已经删除的 Markdown 会从本地知识库移除；下载、解析或安全校验失败时，旧快照保持不变。

当前只支持公开仓库和默认分支，不支持私有仓库、Git LFS、Git clone、子目录范围和 MDX。页面上限表示最多收录的 Markdown 数量，ZIP、Markdown 总量和单文件大小还受独立安全上限约束。

llms.txt

非 GitHub 仓库会优先请求站点根目录的 /llms.txt。只有清单中存在同 hostname、位于收录范围内的有效链接时，Loci 才会采用该来源。

Loci 只读取 Markdown 列表项中的链接，说明文字中的普通链接不会被当作文档。站点级清单可以继续指向库级 llms.txt，嵌套清单最多展开三层，并自动跳过循环引用。

命中后，llms.txt 成为本次同步的权威清单：

只抓取清单列出的页面，不读取 Sitemap，也不递归跟随页面链接。
清单页面通过 HTTP 直接获取，不启动浏览器。
返回 Markdown 时只执行换行和首尾空白规范化。
明确返回 HTML 时仍会提取正文，再转换为 Markdown。
按清单顺序收录，达到页面上限后停止加入后续条目。

Loci 当前不读取 llms-full.txt，也不会跟随跨 hostname 的清单链接。

静态 Pages

Loci 会将 *.github.io 和 *.gitlab.io 识别为已知静态 Pages 域名。有效 llms.txt 仍然优先；没有命中清单时，这类站点跳过 OpenAPI 探测，直接进入普通网页流程。

已发现的静态页面会按本次页面上限整批并发请求，不采用普通站点的批次间隔和并发覆盖。HTTP 429 仍遵循通用重试规则，并优先使用服务器返回的 Retry-After。

这项识别只适用于平台域名。Loci 不会根据内容推断 GitHub Pages 或 GitLab Pages 的自定义域名。

OpenAPI 与 Swagger

OpenAPI 探测只在入口 URL 具有常见接口文档特征时运行，例如：

Swagger UI、Knife4j 或 ReDoc 页面；
FastAPI 的 /docs 或 /redoc；
doc.html、swagger-ui.html；
OpenAPI、Swagger 或 api-docs 规范地址。

Loci 会并发请求入口 URL 和以下同站候选路径：

/openapi.json
/v3/api-docs/swagger-config
/v3/api-docs
/swagger-resources
/v2/api-docs

返回成功并不代表探测命中。JSON 必须包含有效的 OpenAPI 3 或 Swagger 2 结构；Swagger 分组配置还会继续解析同 hostname 的规范地址。跨站配置会被忽略。

命中后，Loci 将每份规范整理成一篇 Markdown，内容包括基本信息、服务地址、认证方式、接口、参数、请求体、响应和数据模型。规范是权威来源，因此不会再抓取接口文档 UI 或递归发现网页。

普通网页

前面的来源均未命中时，Loci 会抓取普通网页。发现顺序如下：

入口页面和以前已经收录的页面；
站点根目录的 /sitemap.xml；
已抓取页面中的链接。

以前收录的页面会优先刷新。页面上限用于限制新发现的 URL；达到上限后，Loci 不再加入新链接，但会完成已经入队的页面。

页面必须与文档源使用相同 hostname，并位于配置的收录路径内。Loci 会去除查询参数和 Fragment，再按规范化 URL 去重。重定向到范围外的页面不会保存。

提取正文时，Loci 优先使用 <main>，其次使用 <article> 和 <body>。脚本、样式、导航栏、页头、页尾和侧栏会在转换 Markdown 前移除。

自动选择 HTTP 或浏览器

抓取方式为 auto 时，Loci 只在第一个页面并行比较 HTTP 和浏览器结果。两份内容足够接近，且浏览器没有提供明显增益时，后续页面使用 HTTP；否则使用浏览器。显式选择 http 或 browser 时不会执行比较。

选择完成后，同步期间发现的页面统一使用该方式。Sitemap 始终通过 HTTP 获取。

范围、删除与静态资源

收录范围由 hostname、路径和页面上限共同决定。路径按完整路径段匹配，例如 /guide 不会误收录 /guides。该范围同时约束 llms.txt、Sitemap、页面链接和重定向结果。

页面明确返回 HTTP 404 或 410 时，成功同步会删除对应的旧文档。某个 URL 只是从 Sitemap、llms.txt 或页面链接中消失时，普通网页同步不会据此自动删除；主动缩小收录范围时，范围外页面会立即移除。GitHub 仓库采用完整快照，因此遵循前文的快照替换规则。

图片、视频、字体和其他二进制资源不会作为独立文档保存。网页正文中的资源引用会保留在 Markdown 中；GitHub Markdown 的相对资源地址会改写为固定提交地址。

继续阅读

通过桌面应用添加文档源，请查看桌面应用快速上手。
通过命令行调整范围、数量和抓取方式，请查看本地文档库。

#页面发现与抓取优先级

#识别顺序

#公开 GitHub 仓库

#llms.txt

#静态 Pages

#OpenAPI 与 Swagger

#普通网页

#自动选择 HTTP 或浏览器

#范围、删除与静态资源

#继续阅读