#AI 接入概览

Loci 通过 MCP 向 AI 客户端提供文档能力。Skill 可以进一步规定检索步骤，全局规则则让不同项目采用相同的文档查询顺序。这三者解决的问题不同，可以单独使用，也可以组合使用。

#三种能力的关系

MCP 是能力入口。没有 MCP 时，Skill 和全局规则只能描述流程，无法直接读取 Loci 文档库。只配置 MCP 也可以正常使用；此时由用户或 AI 自行决定何时调用工具。

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

#推荐配置

个人开发者可以按以下顺序接入：

1. 安装 Loci CLI，并配置一个名为 loci 的 stdio MCP。
2. 新建 AI 会话，确认客户端能够列出 Loci 工具。
3. 希望所有项目遵循同一优先级时，配置客户端的用户级全局规则。
4. 需要更详细的检索步骤时，再安装或引用 use-loci Skill。

CLI 的 stdio MCP 是推荐入口。AI 客户端会按需启动进程，不需要让桌面应用或 HTTP 服务常驻。使用桌面应用时，也可以连接它提供的本机 HTTP MCP。

同一个 AI 客户端只应保留一个名为 loci 的 MCP。不要同时注册 CLI stdio 和桌面 HTTP 入口，否则客户端会看到两组功能相同的工具。

#一次典型查询

配置完成后，AI 通常按以下流程查询文档：

1. 列出本地文档库，确认目标技术和版本。
2. 本地存在可用文档时，查看一至两层目录，了解主题结构和文档语言。
3. 直接读取明确文件，或使用准确关键词搜索，再根据完整小节回答。
4. 本地没有可用文档时，查询只读的云端公开目录。
5. 云端存在可用快照时，说明来源并询问用户是否拉取。
6. 云端没有可用快照、用户不选择拉取或拉取失败时，确认官方入口并另行询问是否抓取。
7. 只有用户拒绝官方抓取、已授权获取失败或获得的证据仍不足时，才切换到允许的其他来源。

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

#安全边界

列出本地文档库、查询云端公开目录、搜索和读取文档属于只读操作。云端拉取、新增文档源、主动同步和删除会修改本地状态。Skill 或全局规则应要求 AI 在执行写操作前取得用户授权；用户当前请求已经明确要求该操作时，无需重复确认。用户拒绝云端拉取不代表已经授权抓取官网，两个操作需要分别确认。

同一文档库被多个 AI、CLI 或桌面进程同时同步时，Loci 会复用已有任务和进度。不同文档库仍可独立执行。

#继续配置

• 配置 MCP：选择 stdio 或 HTTP，并连接常见 AI 客户端。
• 配置客户端全局规则：设置跨项目生效的文档查询顺序。
• 使用 Loci Skill：了解 Skill 的职责、触发方式和工作流。
• Codex 全局与项目规则：了解 Codex 的 override 与项目级规则。