#本地文档库

本页介绍如何在本机创建文档源、同步网页，以及浏览已保存的 Markdown 文档。source 命令管理由本机创建和抓取的文档源；document 命令可以浏览全部本地文档，包括从云端下载的副本。

#创建和管理文档源

#loci source add [url]

从任意一个公开文档页创建本地文档源。只提供 URL 时，CLI 会直接使用推荐默认值，不再逐项询问。URL 是抓取入口，不必是网站首页。

示例：

loci source add https://rspress.rs/guide/introduction.html

该示例会创建名为 rspress 的文档源，采用以下默认值：

创建成功后默认立即执行一次前台同步，因此脚本与交互终端的语义一致。只运行 loci source add 时，CLI 会在交互终端中打开向导：先输入 URL，再确认自动生成的名称、抓取方式、页面上限和收录范围。提交前会展示配置摘要，并询问是否立即开始第一次同步。需要先批量建库时使用 --no-sync；希望当前终端立即返回时使用 --background，随后通过 source runs 和 source logs 审查结果。

CLI 会记住上一次成功创建时的抓取方式、页面上限、收录路径层级和首次同步选择。下次向导会直接填入这些安全偏好；显式命令参数始终优先。密码、删除目标和危险确认不会被记住。

#GitHub 仓库 Markdown

公开 github.com/<owner>/<repo> 仓库会自动切换为 GitHub 文档源，不需要手动选择类型。名称默认使用仓库名，--page-limit 表示最多收录的 Markdown 数量；网页抓取方式、路径范围和并发设置不参与 GitHub 同步。

Loci 会先读取默认分支与当前提交 SHA，再把 ZIP 流式写入临时文件，只逐项解压 .md 文件。文件名直接作为标题，仓库相对路径作为知识库目录。相对图片改写为固定提交的 raw.githubusercontent.com 地址，相对链接改写为固定提交的 GitHub Blob 地址；不会下载图片到本地。

全局 ZIP 和 Markdown 默认上限分别为 200 MB 与 100 MB，单个 Markdown 最多 5 MB。可以通过 loci config set github-archive-limit-mb 和 loci config set github-markdown-limit-mb 修改全局值，也可以通过 --archive-limit 与 --markdown-limit 覆盖单个仓库。提交没有变化时跳过 ZIP 下载；某个提交超限后，在对应上限提高前也不会反复下载。

每次成功同步会以新快照替换旧文档，因此仓库中已经删除的 Markdown 会从本地知识库和全文索引中删除。下载、解析或安全校验失败时保留旧快照。当前只支持公开仓库和默认分支，不支持凭据、私有仓库、Git LFS、Git clone、子目录范围、MDX 或 Markdown 内原始 HTML/组件属性的链接改写。

#loci source sync [source]

以前台方式同步一个本地文档源，并显示已处理、成功和失败的页面数。[source] 可以是名称、完整 ID 或唯一短 ID；在交互终端中省略时可以从列表选择。

#GitHub Pages 与 GitLab Pages

Loci 会将 *.github.io 和 *.gitlab.io 识别为已知静态 Pages 域名。HTTP 抓取会按本次页面上限整批请求已发现页面，不采用普通站点的 HTTP 并发覆盖和批次间隔。有效 llms.txt 列出的页面也使用相同策略。

该规则只识别上述托管域名，不推断 GitHub Pages 或 GitLab Pages 的自定义域名。平台返回 HTTP 429 时，Loci 仍会执行通用重试，并优先遵守 Retry-After。

browser 模式会在同步开始时检查无头浏览器；auto 模式会在确实需要比较 HTTP 与浏览器页面时检查。交互终端可以确认并自动安装，脚本环境则需要提前运行 loci browser install。

同一进程内重复请求同一个文档源时，Loci 会复用正在运行的抓取和进度。桌面应用或另一个 Loci 进程已经同步该文档源时，当前命令会连接对应的持久抓取记录，并继续显示进度。不同文档源可以独立同步；失败或取消完成后可以重新执行。

示例：

loci source sync rspress

#loci source list

列出全部本地文档源，包括页面数、内容大小、抓取方式、收录范围和短 ID。云端下载的副本不会显示在此列表中。

示例：

loci source list

#loci source update [source]

修改已有文档源的名称、入口 URL、抓取方式、页面上限、收录范围、并发覆盖值或 GitHub 大小覆盖值，不改变桌面端的定时同步计划。只要提供任一修改选项，CLI 就只更新该字段，不会继续询问其他字段。完全省略修改选项时，交互终端会进入编辑向导。

示例：

loci source update rspress --page-limit 300

交互式更新同样从 URL 开始，只展示可用的收录路径，并在保存前列出实际变化。修改 URL 时会提示现有文档需要重新同步，并可选择保存后立即同步。

#loci source runs [source]

显示最近抓取记录，包括来源、开始时间、发现页面数、成功数、失败数、短运行 ID 和错误信息。交互终端省略 [source] 时先选择文档源；脚本环境省略时显示所有文档源，显式 --all 也会显示全部记录。

示例：

loci source runs rspress

#loci source logs [run]

查看一次抓取的汇总和页面级失败明细，包括失败 URL、原因、HTTP 状态码和是否可重试。[run] 可以使用 source runs 中显示的短运行 ID；交互终端省略时会先选择文档源和最近一次运行。

loci source logs a1b2c3d4

#loci schedule set [source] [cron]

设置本地文档源的五段 Linux Cron 更新计划。省略 Cron 时在交互终端选择常用预设；传 manual 可以关闭计划。

loci schedule set rspress '0 2 * * *'
loci schedule list

计划只有在桌面端运行，或显式启动 CLI 前台计划运行器时才会执行：

loci schedule run

计划运行器同时负责已开启的云端副本每日同步，按 Ctrl+C 停止。桌面端和 CLI 通过共享锁 保证同一时间只有一个计划宿主。

#loci source delete [source]

删除一个本地文档源及其全部文档。CLI 默认会再次确认；只有在脚本中确认目标无误时才应使用 --yes 跳过确认。

示例：

loci source delete rspress

#浏览和读取文档

#loci document list [source]

列出已保存的文档，包括标题、文档源、语言、更新时间和短 ID。省略 [source] 时列出所有本地文档；提供文档源名称或短 ID 时只列出该库的内容。

示例：

loci document list rspress

#loci document tree [source]

按 URL 路径显示某个文档库的目录树。在交互终端中省略 [source] 时可以从本地文档库列表中选择。

示例：

loci document tree rspress

#loci document search [query]

在文档标题和 Markdown 正文中搜索关键词。省略 [query] 时，CLI 会在交互终端中请求输入。

示例：

loci document search "部署配置"

#loci document read [document]

输出一篇文档的完整 Markdown 内容和来源 URL。[document] 可以是短 ID、标题或完整 URL；在交互终端中省略时可以从文档列表选择。

示例：

loci document read a1b2c3d4

省略文档参数时会打开可搜索选择器，可以按标题、文档源或 URL 路径筛选全部文档。

需要使用 Server 上预先发布的公开文档时，查看云端文档库。