use-loci
Skill0 starsChanged 5 days agoMITView on GitHub
使用 Loci MCP 发现、获取、同步、搜索和阅读技术文档,并协调其他文档来源。回答依赖准确技术文档的问题时使用;必须按本地库、云端公开目录、用户确认后的官方文档抓取顺序执行,在用户拒绝、获取失败或所得证据仍不足后才切换其他来源。
In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- apply-yliu-frontend-practicesSkill
- build-mcp-appSkill
- build-mcpbSkill
- build-mcp-serverSkill
- chinese-article-writingSkill
- claude-md-improverSkill
- file-line-auditSkill
- frontend-designSkill
- git-step-commitSkill
- integrate-ai-i18nSkill
- manage-prd-docsSkill
- modernize-ecmascriptSkill
- publish-npm-packagesSkill
- skill-creatorSkill
- skill-developmentSkill
- use-ai-i18n-mcpSkill
The file
Files
使用 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 文档站。
- 一个文件或小节已经足够时,不读取整个文档库。
- 不宣称使用官方文档可以完全消除错误或幻觉。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

