# Use Loci > 使用 Loci MCP 发现、获取、同步、搜索和阅读技术文档，并协调其他文档来源。回答依赖准确技术文档的问题时使用；必须按本地库、云端公开目录、用户确认后的官方文档抓取顺序执行，在用户拒绝、获取失败或所得证据仍不足后才切换其他来源。 - Skill: `bosens-china/use-loci` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add bosens-china/use-loci` - Raw SKILL.md: https://api.skillmd.com/api/skills/bosens-china/use-loci/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: bosens-China (https://skillmd.com/u/bosens-china) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/bosens-china/use-loci --- # 使用 Loci 优先使用 Loci 中用户指定的技术文档回答问题。先理解文档库结构，再按需读取相关文件和小节，避免一次加载整个文档库。 ## MCP 入口选择 - Agent 配置中只保留一个名为 `loci` 的 MCP 入口。 - 本地 CLI MCP 可用时，优先使用 CLI 提供的 stdio 入口；不可用时再使用桌面端 HTTP 入口。 - 同时发现 CLI 与桌面端入口时，不要对两套重复工具执行相同操作。 - 入口使用的传输方式不影响下面的工具名、检索流程和安全边界。 ## 与其他文档 Skill 共存 当前任务可能同时匹配 Context7 或其他第三方文档 Skill。允许客户端加载和读取这些 Skill，但匹配或加载不代表可以立即执行它们的查询步骤。除非用户明确指定某个来源，否则由客户端适用的全局或项目规则统一决定文档来源顺序。 完成 Loci 获取流程前，不调用其他文档来源：先查询本地库，再查询只读云端目录；云端存在可用快照时询问是否拉取；云端没有可用快照、用户不选择拉取或拉取失败时，确认官方入口并另行询问是否抓取。等待用户决定期间，不调用 Context7 或其他替代来源。 本地或云端未命中本身不构成切换条件。只有 Loci 不可用、无法确认官方入口且用户没有指定可用来源、用户拒绝官方抓取、已经提供官方抓取选项后所有已授权获取路径仍失败或没有文件，或者获得的 Loci 证据经过合理检索后仍不足时，才使用其他来源。切换前说明满足了哪一项条件；用户明确指定 Context7 等来源时，直接遵循当前请求。 ## 基本流程 1. 从用户问题和当前项目中识别相关技术及其版本。 2. 调用 `loci_list_libraries` 查询是否已有对应文档库。 3. 本地存在且 `pages > 0` 时，查看浅层目录树并记录返回的 `languages`，再直接读取目标文件或搜索正文。 4. 本地匹配项为 0 页时，把它视为不可用：正在同步则查询状态；空闲或失败则在用户已授权同步时重试。重试后仍为 0 页时继续云端或官网流程。 5. 没有可用本地文档库时，调用 `loci_list_cloud_libraries` 查询云端公开目录。 6. 云端存在 `pages > 0` 的匹配项时，取得用户确认后调用 `loci_pull_cloud_library`；0 页候选、没有匹配项、查询或拉取失败、用户不选择拉取时，确认官方入口后取得用户同意，再调用 `loci_add_library` 创建并首次抓取。 7. 需要搜索时，把概念性关键词转换为目录树 `languages` 对应的语言，再调用 `loci_search_files`。 8. 根据目录或搜索结果调用 `loci_read_files` 阅读相关文件或完整小节。 9. 根据读取结果回答，附上相关 `source_url`，并区分文档事实与 Agent 推断。 ## 目录与搜索 把目录树作为理解文档库结构和搜索语言的主要入口。获得本地文档库后，先调用 `loci_get_library_tree` 查看一至两层，读取顶层 `languages` 并了解主题、模块、版本和相邻文件，再决定直接读取还是搜索。`readable=true` 的文件节点还会返回该文件的 `language`。 - 目录已经暴露明确目标文件时，直接批量读取少量相关文件。 - 用户给出明确的 API、配置项、命令或错误信息时，可以并行调用 `loci_get_library_tree` 和 `loci_search_files`。 - 仅凭目录无法确认目标文件时，使用搜索定位文件及小节。 搜索时优先使用 API 名称、配置键、组件名、命令和错误信息等准确关键词。`loci_search_files` 的 `queries` 使用数组，一次传入 1–10 组互补的查询，结果按查询分组返回。`library_ids` 也可以是多个文档库 ID，两个数组可以组合使用。首次未命中时尝试少量同义词、全称或缩写，不要立即遍历整个文档库。 ### 搜索语言 - 把 `loci_get_library_tree` 返回的顶层 `languages` 作为搜索语言依据，不要为了探测语言而额外读取代表文件。例如包含 `zh` 或 `zh-CN` 时，使用“响应式原理”、“依赖追踪”等中文概念，不要只搜索英文翻译词。 - API 名称、类名、函数名、配置键、CLI 命令和错误原文保持原样，不做翻译。 - 需要查找多个相关表述时，把文档语言对应的关键词放入同一个 `queries` 数组，例如 `{"queries":["响应式原理","依赖追踪","副作用"]}`。 - `languages` 只包含 `und` 或文件 `language` 与正文不符时，根据目录标题判断语言，必要时在 `queries` 中同时提交可能的文档语言和英文关键词。 ## 阅读策略 - 从目录中确定目标文件时，直接读取该文件。 - 搜索命中后，使用返回的 `section_id` 读取完整小节；细节重要时不要只根据搜索摘要回答。 - 仅在问题涉及多个概念时批量读取多个文件。 - 返回内容不完整时才使用 `next_offset` 继续读取。 - 获得足够证据后停止检索，并区分文档事实与 Agent 推断。 ## 获取缺失的文档库 查询云端公开目录是只读操作，不需要用户确认。使用技术名称、官方域名或项目名调用 `loci_list_cloud_libraries`： - 找到 `pages > 0` 的匹配项时，说明云端文档库名称、来源 URL 和页面数，取得用户确认后调用 `loci_pull_cloud_library`。拉取会访问网络并修改本地数据库。 - 忽略 0 页云端候选；不要把“存在空库”当作已经获得文档。 - 有多个可能匹配项时，先根据官方来源和项目版本缩小范围；无法确定时让用户选择。 - 云端没有可用匹配项、查询或拉取失败、拉取后仍无文件，或用户不选择拉取时，查找项目或厂商的官方文档入口，核对域名归属，说明名称和 URL，并在用户确认后调用 `loci_add_library` 创建文档库并首次抓取。 - 用户拒绝云端拉取不等于同意抓取官网；这是另一个修改本地状态的选择，需要单独确认。 - 获取完成后使用返回的本地文档库 ID 进入目录、搜索和阅读流程。 用户已经明确要求拉取、添加或抓取某个具体文档源时，视为已经确认对应操作，不要重复询问。无法确认来源是否官方时，不要添加，先请用户决定。 已有本地库包含文件时，即使云端不可访问也继续使用本地内容，并说明它可能不是最新版本。云端更新或拉取失败不得删除可用本地内容。 ## 抓取与同步确认 把云端拉取、新增抓取和主动同步视为会修改本地状态并访问外部服务的操作。调用 `loci_pull_cloud_library`、`loci_add_library` 或 `loci_sync_libraries` 前，说明目标并取得用户确认；用户当前请求已经明确要求对应操作时，无需再次确认。 `loci_sync_libraries` 只用于已经存在的网页文档库；不存在的文档库必须通过云端拉取或添加官方入口获取。不要为每个问题同步文档库，仅在用户要求最新信息、文档库长期没有成功更新、本地结果明显缺失或可能与官网不一致时建议同步。 用户已授权同步，但另一个工具或 Agent 可能已经启动任务时，先调用 `loci_get_sync_status`。状态为 `syncing` 时跟随已有任务，不要并行启动第二份抓取；确实需要在当前调用中等待时，对同一文档库调用 `loci_sync_libraries` 并设置 `wait_for_completion: true`。Loci 会复用当前 MCP 宿主中的任务，跨进程调用则由文档源锁阻止重复写入。 ## 版本与冲突 - 先确认当前项目实际使用的依赖或工具版本。 - 优先选择与项目版本匹配的文档。 - 把 `updated_at` 作为本地缓存的新鲜度信息，不把它视为内容适用于当前版本的证明。 - 多个本地文档冲突时，比较版本、目录位置和 `source_url`。 - 无法消除冲突时，搜索在线官网实时核验，并向用户说明冲突。 ## 边界 - 最终 `source_url` 的域名与已经确认的官方域名一致时，可以将内容视为官方来源。 - 对 `github.io`、Read the Docs 等共享托管域名，同时核对组织、仓库或路径归属。 - 不把官方来源等同于版本适用或内容最新，仍检查项目版本和同步时间。 - 有官方文档时，不主动添加第三方镜像。 - 未经用户确认，不新增或主动同步文档库。 - 只添加无需登录即可访问的公开 HTTP/HTTPS 文档；不要尝试提供账号、Cookie、Token、验证码或 Cloudflare 绕过方案。 - 不添加依赖 Fragment 区分页面的 Hash Router 文档站。 - 一个文件或小节已经足够时，不读取整个文档库。 - 不宣称使用官方文档可以完全消除错误或幻觉。