本地文档库
本页介绍如何创建、同步和浏览本机文档库。source 命令管理公开网站或仓库,document 命令用于浏览已保存的 Markdown。
创建文档源
loci source add [url]
将任意公开文档页作为入口。只提供 URL 即可自动生成名称,以 auto 模式、1,000 页上限和整站范围开始,并立即执行首次同步。需要缩小范围时传入显式选项;不再读取最近一次创建的参数,也不逐项询问默认设置。省略 URL 时只询问入口 URL。
常用选项如下:
--background 与 --no-sync 不能同时使用。CLI 会在执行前直接拒绝这组冲突参数。
例如,只收录指南并排除中文、德文和法文目录:
需要调整 GitHub 大小上限时,请查看基础命令与运行设置。
GitHub 仓库
公开 github.com/<owner>/<repo> 仓库可以直接作为文档源:
Loci 会保留仓库 Markdown/MDX 的目录结构,并保持相对文档和图片链接可用。当前只支持公开仓库的默认分支;不支持私有仓库、Git LFS、Git clone 和子目录范围。
同步和更新文档源
loci source sync [source]
同步一个本地文档源,并显示成功和失败的页面数:
auto 模式在浏览器已安装时比较 HTTP 与浏览器结果;未安装时直接使用 HTTP,不执行浏览器页面探测,也不会提示安装。明确需要 JavaScript 渲染时可选择 browser,脚本环境请先执行:
前台同步也会先写入持久任务队列再等待结果。重复同步同一文档源时,Loci 会复用正在运行的任务;即使后台服务或另一个 MCP 入口先认领,CLI 也会读取同一份进度与最终结果。失败或取消后,可以再次执行同步。
loci task
抓取任务具有稳定 ID,并持久保存每个页面的完成事件、正文大小和恢复检查点。可以在另一个终端筛选、跟随和控制:
交互终端可以省略单任务命令的任务 ID,再从最近任务中选择;脚本、管道和 Agent 等非交互调用必须显式提供任务 ID 和 --yes。task follow 会从持久事件按序读取逐页进度,轮询较慢或重新运行命令不会影响后台抓取。跟随时按 Ctrl+C 只退出当前显示并保留任务。
暂停停止领取新页面;恢复复用原任务 ID。结束会保留已经抓取的正文、保存剩余 URL 并允许下次继续;取消会停止后续抓取并清除检查点,已经实时写入的成功页面继续保留,首次任务取消且文档库仍为空时同时删库。pause-all 和 resume-all 省略 hostname 时作用于全部域名。task logs 查看按日期、类别、级别和 hostname 筛选的结构化操作记录。
loci source list
列出本地文档源,包括页面数、内容大小、页面获取方式和收录范围:
loci source update [source]
修改文档源名称、入口 URL、页面获取方式、页面上限或收录范围。完全省略修改选项时,CLI 会进入编辑向导:
update 同样支持 --archive-limit 和 --markdown-limit。省略大小覆盖值时保留当前来源设置;创建时省略则继承共享设置。页面执行参数由底层管理。
切换来源类型、把 URL 切换到其他 hostname,或把 GitHub 来源切换到另一仓库,会立即清空现有正文。收窄范围或新增、修改排除规则会在保存事务中立即删除不再匹配的正文和搜索索引,不会等到下次同步。交互向导会在保存前再次警告;显式传入更新选项表示脚本已经确认对应影响。保存后建议立即同步。
loci source history [source] 与 loci source run-details [run]
使用 source history 查看最近的同步记录;使用 source run-details 排查某次同步的页面失败原因:
source run-details 中的 [run] 是 source history 输出的短 ID。如需查看所有文档源的记录,使用 --all:
交互终端可以省略文档源并从列表中选择。非交互终端必须指定文档源,或显式传入 --all 查看全部记录。
设置定时更新
loci schedule set [source] [cron]
为本地文档源设置五段 Linux Cron 更新计划。传入 off 可以关闭计划:
使用默认数据目录时,保存启用的计划会立即确保无 HTTP 的用户级常驻 worker 可用。Web 会话与 worker 可以同时运行,之后无需保持终端或浏览器打开;机器恢复或服务重新启用后,错过的多个时间点最多合并补跑一次。设置 LOCI_DATA_DIR 时只会为该目录启动当前登录会话中的独立 detached worker,不会安装对应的登录或重启自启动定义;需要长期运行时应由容器或进程管理器执行同一环境下的 loci service run。旧脚本中的 manual 仍可作为 off 的兼容别名。
服务状态和停用方式请查看后台服务与 Web UI。计划列表为空时,CLI 会提示先创建文档源或使用 schedule set 配置计划。
删除文档源
loci source delete [source]
删除一个本地文档源及其全部文档。CLI 默认会再次确认:
浏览和读取文档
loci document list [source]
列出已保存的文档:
loci document tree [source]
按 URL 路径显示文档库目录:
loci document search [query]
在文档标题和正文中搜索关键词:
loci document read [document]
读取一篇文档的 Markdown 内容和来源 URL。[document] 可以是短 ID、标题或完整 URL:
loci document move <documents...>
把一篇或多篇本地文档移动到一个新文档库。目标名称、URL、范围和抓取参数都显式给出;默认会删除移动后已经为空的原文档库,使用 --keep-empty-sources 保留。操作会二次确认,脚本调用必须传 --yes:
相同 --operation-id 和相同输入可以安全重试;同一操作 ID 对应不同输入会被拒绝。全文索引与正文归属在同一 SQLite 事务中更新。
需要使用 Server 上预先发布的公开文档时,请查看云端文档库。