bosens-China 使用 Loci
优先使用 Loci 中用户指定的技术文档回答问题。先理解文档库结构，再按需读取相关文件和小节，避免一次加载整个文档库。
MCP 入口选择
- Agent 配置中只保留一个名为
loci的 MCP 入口。 - 本地 CLI MCP 可用时，优先使用 CLI 提供的 stdio 入口；不可用时再使用桌面端 HTTP 入口。
- 同时发现 CLI 与桌面端入口时，不要对两套重复工具执行相同操作。
- 入口使用的传输方式不影响下面的工具名、检索流程和安全边界。
与其他文档 Skill 共存
当前任务可能同时匹配 Context7 或其他第三方文档 Skill。允许客户端加载和读取这些 Skill，但匹配或加载不代表可以立即执行它们的查询步骤。除非用户明确指定某个来源，否则由客户端适用的全局或项目规则统一决定文档来源顺序。
完成 Loci 获取流程前，不调用其他文档来源：先查询本地库，再查询只读云端目录；云端存在可用快照时询问是否拉取；云端没有可用快照、用户不选择拉取或拉取失败时，确认官方入口并另行询问是否抓取。等待用户决定期间，不调用 Context7 或其他替代来源。
本地或云端未命中本身不构成切换条件。只有 Loci 不可用、无法确认官方入口且用户没有指定可用来源、用户拒绝官方抓取、已经提供官方抓取选项后所有已授权获取路径仍失败或没有文件，或者获得的 Loci 证据经过合理检索后仍不足时，才使用其他来源。切换前说明满足了哪一项条件；用户明确指定 Context7 等来源时，直接遵循当前请求。
基本流程
- 从用户问题和当前项目中识别相关技术及其版本。
- 调用
loci_list_libraries查询是否已有对应文档库。 - 本地存在且
pages > 0时，查看浅层目录树并记录返回的languages，再直接读取目标文件或搜索正文。 - 本地匹配项为 0 页时，把它视为不可用：正在同步则查询状态；空闲或失败则在用户已授权同步时重试。重试后仍为 0 页时继续云端或官网流程。
- 没有可用本地文档库时，调用
loci_list_cloud_libraries查询云端公开目录。 - 云端存在
pages > 0的匹配项时，取得用户确认后调用loci_pull_cloud_library；0 页候选、没有匹配项、查询或拉取失败、用户不选择拉取时，确认官方入口后取得用户同意，再调用loci_add_library创建并首次抓取。 - 需要搜索时，把概念性关键词转换为目录树
languages对应的语言，再调用loci_search_files。 - 根据目录或搜索结果调用
loci_read_files阅读相关文件或完整小节。 - 根据读取结果回答，附上相关
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 文档站。
- 一个文件或小节已经足够时，不读取整个文档库。
- 不宣称使用官方文档可以完全消除错误或幻觉。