Cursor客户端解剖（三）上下文引擎：索引与检索

发表于 分类于

系列：Cursor客户端解剖系列学习笔记
上一篇：（二）整体架构鸟瞰

包内落点：cursor-retrieval

清单里写得很直白：

Handles indexing and retrieval for Cursor

关键证据（package.json）：

  • extensionKind: ["workspace"] —— 索引跟着工作区走
  • activationEvents: ["onStartupFinished"]
  • Proposed API：textSearchProvider2、cursorTracing、cursorNoDeps 等
  • 贡献语言关联：把 .cursorignore、.cursorindexingignore 当成 ignore 语法文件
  • 开发者命令：cursor.grepClient.debug、cursor.codebaseTelemetry.triggerSnapshot

另有一个几乎空壳的 cursor-file-service（main: null），描述也是 indexing/retrieval——有时能力在 core，扩展只占位/声明。

精髓：把「模型能看什么」做成产品边界

很多人以为上下文只是 prompt 里多贴几段代码。Cursor 的做法是：

可索引边界文件化，而不是口头约定。

.cursorignore / .cursorindexingignore 进入语言贡献点，意味着：

  1. 编辑器认识这些文件（高亮/编辑体验）
  2. 检索管线可以把它们当一等配置读取
  3. 团队可以把「别索引密钥目录 / 别扫构建产物」推进仓库

这和后面的 .cursor/permissions.json、.cursor/environment.json 是同一设计肌肉：Agent 相关边界尽量变成可审查的文件契约。

一次任务里，检索处在哪一段

能力流里，上下文组装发生在「意图入口之后、编排之前」：

1
2
3
4
Intent UI（Composer / Glass）
    → Context Service（cursor-retrieval + ignore 规则）
    → Orchestrator（agent-host）
    → Executor（agent-exec）

本地还会收集更多非向量上下文（详见第七篇）：

  • .cursor/rules、AGENTS.md、CLAUDE.md、.cursorrules
  • Skills、MCP 工具清单
  • 打开文件、选区、git 状态等

检索负责的是「仓库里哪段代码相关」；Rules/Skills 负责的是「行为约束与手册」。两者都进 RunRequest，但职责不同。

工具协议里的检索面孔

在 agent.v1.*ToolCall 一侧，和上下文相关的本地工具包括：

工具 作用
ReadToolCall 读文件
GrepToolCall 精确搜索
GlobToolCall / LsToolCall 按名/目录探索
SemSearchToolCall 语义检索
ReadLintsToolCall 读诊断

注意：语义搜索的执行面在本地索引；embedding/排序是否上云，视配置与隐私模式，学习材料把它标成混合能力。

口诀仍然成立：

决策与生成在云（或私有推理）；副作用（读盘/搜盘）在执行环境。

为什么检索必须独立成扩展

  1. 故障域：索引挂了，编辑器 UI 还应活着
  2. 生命周期：跟 workspace 走，远程窗口/本地窗口放置清晰
  3. 演进：检索算法、ignore 规则、debug 命令可以单独迭代
  4. 权限心智：用户更容易理解「检索扩展」而不是「神秘 core 黑盒扫盘」

大扩展 cursor-retrieval 的 dist 也是巨型 bundle，美化收益低；学设计时读清单贡献点，比硬抠压缩 JS 更划算。

小结

上下文引擎在包内的产品化结论：

  1. 检索是 workspace 扩展，不是 Chat 临时逻辑
  2. ignore 规则是一等配置
  3. 精确搜 + 语义搜 + 读文件，都是强类型工具，不是提示词里的口头约定

下一篇拆 Agent 三件套：Host / Exec / Worker —— 编排与执行为什么必须分开。