配置 Agent 全局规则

MCP 让 Agent 调用 Loci 工具,全局规则则规定什么时候优先使用这些工具。Loci 为支持本机用户级文件的客户端一键写入规则;Cursor 使用 ~/.cursor/rules/loci.mdc,不读取、修改或同步云端 User Rules。

职责边界

Agent 先判断当前任务需要多深的证据。新版亮点、产品动态、初步选型等轻量调研可以直接搜索,优先官方发布说明,不必先查询 Loci 或建库。一次搜索足够就结束;关键结论缺依据或结果冲突时继续核验,不限制只能搜索一次。

具体 API、配置、调试和迁移影响等详细技术问题优先复用匹配版本的 Loci 文档。本地缺失时,可查询云端公开目录,按需拉取匹配快照或抓取官方资料。综合证据深度、新鲜度、获取成本和复用价值决定范围:少量已知页面优先指定页获取,跨章节工作、系统学习或明确收录需求再考虑更广抓取;缺库本身不构成整站抓取理由。Loci 不可用、获取失败、证据不足或入库成本与任务不相称时,可转向 Context7、官方网页或其他文档来源。

任务所需的公开云端拉取、官方抓取、指定页获取和必要的本地刷新默认允许,无需逐次确认;较大获取前简要说明来源和范围。删除、刻意覆盖、已有来源配置变更、跨库移动及远端管理或发布仍需明确授权,已有授权覆盖同一操作时不重复询问。收窄范围或修改排除规则会立即删除不匹配内容,必须说明影响;正常刷新沿用 404/410 删除旧正文、临时失败保留正文的语义。

Loci 不是通用网页搜索的前置步骤。新闻与时效事件、价格、人物或公司信息、购物、旅行、法律、医疗以及普通网页内容等任务,应从一开始就使用适合该领域的网页或专业来源。仅仅提到软件、公司或网页,不代表任务属于技术文档范围。

客户端对照

客户端MCP 配置用户级全局规则项目级规则
Codexloci agent setup codex~/.codex/AGENTS.md项目根目录或子目录的 AGENTS.md
Cursorloci agent setup cursor~/.cursor/rules/loci.mdc项目根目录或子目录的 AGENTS.md
VS Codeloci agent setup vscode~/.copilot/instructions/loci.instructions.mdAGENTS.md、.github/copilot-instructions.md
Claude Codeloci agent setup claude-code~/.claude/CLAUDE.mdCLAUDE.md 或 .claude/CLAUDE.md
Google Antigravityloci agent setup antigravity~/.gemini/GEMINI.md.agents/rules/
Kimi Codeloci agent print-config,手动复制~/.kimi-code/AGENTS.md由 Kimi Code 配置决定
其他客户端loci agent print-config,手动复制由目标客户端决定由目标客户端决定

同一个客户端只保留一个名为 loci 的 stdio MCP。

使用 CLI 写入

运行对应命令:

loci agent rules codex
loci agent rules cursor
loci agent rules vscode
loci agent rules claude-code
loci agent rules antigravity

交互终端会先展示客户端和目标路径。可信的自动化环境可以添加 --yes:

loci agent rules codex --yes

Cursor 命令创建带 MDC frontmatter 的本机规则文件。该文件不会同步到 Cursor 账号,也不会修改 Customize → Rules → User Rules 中的云端内容。Kimi Code 或其他没有纳入一键接入的客户端,仍可复制客户端中立规则并粘贴到自己的用户级入口。

受管区块

Loci 写入的内容使用固定标记。中间内容由 Loci 自动生成,不需要手动复制:

<!-- loci:start -->

...
<!-- loci:end -->

首次配置会创建文件或追加区块。再次配置只更新标记之间的内容,并保留区块之外的个人设置。标记缺失、重复或顺序错误时,Loci 会停止写入,请先手动修复文件。Cursor 的专用文件还必须包含合法 MDC frontmatter 和 alwaysApply: true。

重复运行同一命令是安全的。Codex 已经使用 Context7 时,Loci 也会按下文说明整理规则优先级。

验证与移除

配置完成后,新建 AI 会话,使客户端重新加载全局规则。确认客户端能够列出 Loci MCP 工具,再询问:

请说明技术文档的查询顺序,以及什么情况下切换到其他来源。

预期回答会先判断研究深度:轻量调研直接搜索,详细技术问题优先复用 Loci,并按需获取公开资料,无需逐次询问确认。如果回答仍强制所有问题先建库或逐次确认抓取,请重新运行规则写入命令更新受管区块,并检查标记是否完整;Cursor 还应检查 ~/.cursor/rules/loci.mdc 的 frontmatter。

还可以询问“搜索今天的行业新闻是否需要先查询 Loci”。预期回答应直接使用网页新闻来源,不查询或抓取 Loci。

询问“调研某框架最新版本有哪些亮点”时,预期先搜索官方发布说明,证据充分后直接回答,不自动抓取整个文档站。询问具体 API 或迁移行为时,预期优先查阅匹配版本的详细文档。

需要同时移除 MCP、全局 Skill 和规则时,运行 loci agent remove <client>。命令只删除包括 <!-- loci:start --> 和 <!-- loci:end --> 在内的 Loci 受管区块,保留文件中的其他内容;标记异常时拒绝修改。Cursor 专用文件只剩 Loci 创建的标准 frontmatter 时会删除整文件,云端 User Rules 不会被修改。

各客户端注意事项

Codex

先配置 MCP,再写入全局规则:

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

默认目标是 ~/.codex/AGENTS.md。如果 ~/.codex/AGENTS.override.md 已存在,Codex 会忽略同目录的普通文件,因此 Loci 会改为写入 override 文件。

写入时,Loci 会检测成对的 Context7 标记和旧版 loci-context7 标记,并替换为“Loci 优先、Context7 兜底”的组合规则。无法安全识别边界时,Loci 会停止修改并提示手动整理。项目级 AGENTS.md、Context7 Skill 和其他个人规则不会被修改。

仓库根目录的 AGENTS.md 适合保存团队共享的构建、测试和代码规范。子目录可以继续放置 AGENTS.md 或 AGENTS.override.md,为局部模块提供更具体的规则。Codex 会依次合并用户级文件、项目根目录和当前工作目录路径上的规则;更靠近当前目录的内容优先级更高。

新建 Codex 会话后,可以运行以下命令检查结果:

codex --ask-for-approval never "说明技术文档的查询流程,以及什么情况下切换到其他来源。"

预期回答会先判断研究深度,轻量调研直接搜索,详细技术问题优先查阅 Loci。任务所需的公开资料获取默认允许;Loci 不可用、获取失败、证据不足或获取成本不相称时,可以切换到其他来源,不强制先抓完整站。

Cursor

Cursor 2.1 及以上版本会把用户主目录下的 .cursor/rules 纳入 Agent 上下文。Loci 创建 ~/.cursor/rules/loci.mdc,写入 alwaysApply: true 和受管区块;重复配置保持幂等。如果已有专用文件缺少合法 frontmatter 或没有启用 alwaysApply: true,Loci 会报告冲突而不是猜测修改。

该入口只面向本机 Cursor Agent,不同步账号,也不覆盖云端 User Rules。Cursor 当前从工作区向父目录发现主目录规则,项目位于用户主目录之外时可能无法加载;Cloud Agent、Tab、Inline Edit 和 Bugbot 也不在本机规则承诺范围内。项目根目录和任意子目录仍可放置 AGENTS.md,用于项目级或目录级约束。

检测到 ~/.cursor/rules/context7.mdc 或 Cursor Context7 Skill 时,Loci 会在自己的规则中加入“Loci 优先、Context7 兜底”的协调说明,但不会修改第三方文件。

VS Code

Loci 创建专用的 loci.instructions.md,并写入 applyTo: "**",使规则在所有工作区自动应用。VS Code 仍可通过 Settings Sync 同步用户指令文件。

Claude Code 与 Antigravity

Claude Code 的 ~/.claude/CLAUDE.md 和 Antigravity 的 ~/.gemini/GEMINI.md 都会跨项目加载。Loci 只管理其中自己的标记区块。

官方资料