接入 Agent

Loci 为 Agent 提供本地技术文档的查询能力。MCP 用于直接调用工具,use-loci Skill 用于选择通道并执行检索流程,全局规则用于在每个项目中保持相同的来源优先级。

能力分工

能力解决的问题是否必需推荐用途
MCP让 Agent 发现和调用 Loci 工具。可选支持 MCP 的客户端首选,调用最直接。
use-loci Skill选择 MCP 或 CLI 通道,并组合检索步骤和安全边界。可选需要稳定技术文档工作流,或客户端只支持 Skill。
全局规则为 Agent 设置跨项目持续生效的文档查询顺序。可选规定 Loci 与其他文档来源的优先级。

MCP 和 loci mcp call 提供相同的 Loci 能力,只是调用方式不同。只配置 MCP 也可以正常使用;只有 Skill 时,Agent 会先判断 MCP 工具是否存在。普通读取可以直接使用 MCP;长时间抓取还要求 Agent 能同时使用 MCP 原生 Progress 和 Cancellation,缺少任一能力时会在启动前改走 CLI。全局规则本身不会安装 CLI。

Skill 与全局规则不互相依赖。Skill 根据任务匹配按需加载,适合封装具体工作流;全局规则在 Agent 会话中持续生效,适合表达稳定优先级。两者同时存在时,由全局规则统一规定文档来源顺序;Skill 被匹配或加载不代表其中的查询工具可以立即执行。

选择接入方式

  • 客户端支持 MCP:安装 Loci CLI,并配置一个名为 loci 的 stdio MCP。
  • 客户端只支持 Skill:安装 use-loci。Skill 会在技术文档任务中检测 MCP;缺少工具时,它会在取得许可后安装 CLI,并通过 loci mcp call 直接调用工具。
  • 希望每个项目遵循同一来源优先级:在前两种方式的基础上,再配置用户级全局规则。

CLI stdio 是唯一的本机 MCP 入口。客户端会按需启动进程,无需维护常驻服务或固定端口。同一个客户端只应保留一个名为 loci 的 MCP。

推荐配置

推荐直接使用全局一键接入:

npm install --global @boses/cli
loci agent setup codex
loci agent status codex

loci agent setup 会交互选择 Agent,统一预览后配置用户级 MCP、安装全局 use-loci 并写入全局规则;不带子命令的 loci agent 进入同一个向导。本机 loci ui 的“Agent”页面提供相同的状态、接入和移除能力。已接入卡片的“检查更新”会复用幂等接入流程:没有变化时提示已是最新,发现旧配置并实际写入时才提示更新完成。

一键接入优先使用客户端自己的配置命令,但命令正常退出不等于配置已经生效。Loci 会继续检查用户级 MCP 配置;没有检测到标准 loci 连接时,自动回退到安全合并配置文件,最终状态以重新读取后的 MCP、Skill 和 Rules 为准。

Agent、CI 和其他非交互调用应使用完整命令,不依赖交互偏好或隐式默认:

loci agent setup codex --yes
loci agent status codex --json
loci agent remove codex --yes

Codex、Cursor、VS Code、Claude Code 和 Google Antigravity 都可以完整自动接入。Cursor 的规则写入本机 ~/.cursor/rules/loci.mdc,不会读取、修改或同步云端 User Rules。

需要只执行其中一项或管理项目级 Skill 时,继续使用 configure、print-config、rules 或 skills 子命令。其他客户端的 MCP 写入方式请查看通过 MCP 接入,Skill 的安装目录和管理命令请查看使用 use-loci Skill,全局规则的客户端差异请查看配置全局规则。

一键移除只删除能确认由 Loci 管理的 loci MCP、Skill 目录和规则区块;配置被修改或所有权不明时会保留文件并报告冲突。Cursor 专用规则文件只剩 Loci 标准 frontmatter 时会一并删除,云端 User Rules 始终不在 Loci 管理范围内。

一次典型查询

配置完成后,Agent 会先判断任务需要的证据深度。新版亮点、产品动态和初步选型等轻量调研先搜索官方资料,证据充分后结束,不强制查询 Loci 或建库,也不限制只能搜索一次。新闻、价格、人物或公司信息、购物旅行、法律医疗和普通网页内容直接使用对应来源。需要详细技术依据的任务通常按以下流程执行:

  1. 列出本地文档库,确认目标技术和版本。
  2. 本地存在可用文档时,查看一至两层目录,了解主题结构和文档语言。
  3. 直接读取明确文件,或使用准确关键词搜索,再根据完整小节回答。
  4. 本地没有可用文档时,查询只读的云端公开目录。
  5. 云端存在范围和新鲜度适合的公开快照时,按需拉取。
  6. 没有适合的快照时,核实官方入口并按需获取。少量页面优先指定页获取,跨章节工作、系统学习或明确收录需求再考虑更广抓取;缺库本身不构成整站抓取理由。
  7. Loci 不可用、获取失败、证据不足或获取成本与任务不相称时,可以使用 Context7、官方网页或其他文档来源,无需先提供抓取确认选项。

查看目录后再搜索,可以减少无关结果。API 名称、配置键、命令和错误原文应保持原样;概念性关键词则使用文档本身的语言。

写操作边界

列出本地文档库、查询云端公开目录、搜索和读取文档属于只读操作。任务所需的公开云端拉取、官方抓取、指定页获取和必要本地刷新默认允许,无需逐次确认;较大获取前简要说明来源和范围。已知官方 URL 不在自动范围时,可以用 loci_fetch_pages 加入该页,不扩大整个文档库的路径范围。正常刷新沿用 404/410 删除旧正文、临时失败保留正文的语义。

删除、刻意覆盖、已有来源配置变更、跨库移动及远端管理或发布仍需明确授权,已有授权覆盖同一操作时不重复询问。收窄范围或修改排除规则会在保存时立即删除不匹配的正文和搜索索引,必须说明这个影响。遵守用户对获取方式的明确限制,不以其他方式绕过拒绝。同一文档库被多个 Agent 或 CLI 进程同时同步时,Loci 会复用已有任务和进度;不同文档库仍可独立执行。

继续阅读