Files
Agent-Workbench/docs/research/CURSOR-MECHANISMS.md
2026-10-29 11:23:43 +08:00

10 KiB
Raw Permalink Blame History

Cursor 3.16.29 的本地工具执行与恢复机制

2026-10-29(Asia/Shanghai)。本报告服务于统一的本地 Agent 工作台,重点追踪当前工具集、执行事件、待执行工具恢复、MCP 钩子、文本改动构造和工作进程复用。所有结论来自已安装的客户端分发代码;没有运行 Cursor、下载后的 Agent 或用户项目,也没有读取用户设置、凭据或会话数据库。

目标与证据身份

本机 Cursor 版本为 3.16.29,product commit 为 6246455961129c32969845e00aa25d87ae926ec0,product 日期为 2026-08-18T01:26:26.285Z。元数据及每个关键方法的原文件 SHA256、UTF-16 范围、字节范围和片段散列均保存在 evidence-index.json。

分发文件 大小 SHA256
cursor-agent-exec/dist/main.js 10,415,138 B ff3295964b51bc1d6446818d13660e26cca6b34ee183de6283505926b9885884
cursor-agent-worker/dist/main.js 1,305,265 B 4255db956ce2f9193f65293dbd3806c60a6fd6571f7020b35cb28c1c5c513b63

REA 首次对原始 worker 的 package.json 和 dist/main.js 做静态分析,成功解析语法,但语义保留触及节点/unknown 上限。随后从原文件 AST 中选取 9 个精确代码切片,按分发代码的位置保存映射并分别分析;9 个切片都无语法解析失败。切片没有执行,外部绑定、封闭作用域和动态对象关系仍保留为未知。

原始 worker 的 REA parent Evidence 为 ev_cebd28a6fee5c6940fee6249054cd080fca28e135e6083a3951c4a0a29d13b51;7 个主要切片为 ev_789fa6618de0da72e2fde82f30aedcba8777533a0ed8c36397673fdd3792f7fe;分发器和 patch 切片为 ev_df7c229808fe5aa5f80a0f44fbb8c87861c3eb3593ad942d20589ada8853513d。完整记录在本地 REA-CURSOR-EVIDENCE.json。该文件约 63 MB,包含分析记录;证据包的顶层 unknowns: 0 是独立残余未知登记数,不能解释成内部语义没有未知。

可核验的执行与恢复链

下面是已观察的源码调用与参数关系。已继续读取 xJ 原函数(617595–623947),确认它调用具体工具的 execute 并转换异常;具体工具实例及最终系统执行器的外部绑定未完整解析,因此这条链是静态代码机制,不能称为实际端到端运行验证。

flowchart LR
    Resume["X5:取出待执行消息"] --> Context["当前工具集与可选执行契约"]
    Context --> Dispatch["a1:按工具名分发"]
    Dispatch --> Adapter["xJ:调用工具 execute 并转换异常"]
    Dispatch -. "传入交互记录器" .-> Events["AL:started / completed / 结果记录"]
    Adapter --> Result["role=tool 结果消息"]
    Result --> Append["追加提示消息,继续 runTurnLoop"]

表中范围是原 main.js 的 UTF-16 代码单元偏移,起点含、终点不含,不是文件行号。对应字节范围由索引脚本根据同一文件计算。

机制 原源码位置 已观察的关键行为
当前工具上下文 M4.buildToolExecutionContext,1676093–1678229 要求 stateHandler.mode 已设置;按资源、会话、MCP、仓库、模式、文件锁等生成工具;建立工具名映射、权限指令和 AL 交互记录器。
请求分发 a1,1509098–1514586;M4.executeToolCall,1681136–1681532;xJ,617595–623947 在工具映射中解析名字;不存在时返回带 toolCallId 的 role: tool 错误结果;xJ 调用工具 execute,区分取消、后端不可达、超时、参数错误、拒绝等错误分类。
执行生命周期 AL.executeToolCall,639604–641562 先记录时间并发送 started;绑定 abortSignal;执行回调后给结果附完成时间,发送 completed,再写入 toolCallRecorder。
待执行工具恢复 X5.executePendingToolCalls,1759140–1762063 从 stateHandler 取原始 pending messages;要求最后 turn 是 Agent turn、最后消息是 assistant;生成当前工具集,处理契约后执行工具,把结果追加到提示消息。
MCP 钩子 Ie.execute,3056776–3062194 执行 preToolUse、beforeMCPExecution;明确处理 deny;允许钩子调整输入;执行后发送 afterMCPExecution、postToolUse 或 postToolUseFailure。
文本 patch cte.apply_patch,2032889–2033584 按 orig_index 排序 chunks,组合保留行和插入行,产生 newLines 与带上下文的 citations。该方法本身没有磁盘写入。
工作进程复用 worker 的 nde,1294925–1302681 检查身份、安装和 worker spec;复用现有 daemon 前请求 worker ID;失配或不可达时进入重建分支;持久化 pid/install/spec 文件与日志路径。
健康与清理 worker 的 Vle,1292832–1293973;Ile,1289442–1290330 经本地 pipe/socket 请求 worker ID,验证 HTTP 状态与返回 JSON;清理逻辑按 workspace/owner 范围收集 worker 名称。

执行记录保留了部分参数和时间状态

AL 保存 latestToolCallsById、参数需保留的 callId 集合和开始时间。applyDeltaToLatestToolCall(635010–635335)只对相应 editToolCall 追加 streamContentDelta;emitToolCallError(638641–639241)可把保存的参数合回错误结果,然后发送 completed 与记录。这表明 UI 状态、流式参数和最终结果被分别处理。

这里观察到的是 recorder 方法调用。recorder 的完整磁盘实现、崩溃时落盘顺序、跨进程事务与 exactly-once 保证尚未验证。

恢复时的契约不是强制存在

X5 会读取 providerOptions.cursor.pendingToolExecutionContracts。有契约时,恢复逻辑筛选 allowedToolNames / admittedEffectiveToolNames,对已找到的契约和工具调用 v1 验证,失败时生成拒绝结果。缺失契约时会回退当前静态工具集。因此可以提炼“恢复应重建当前能力”的思想,不能据此声称原版每次恢复都重新向用户授权或始终禁止旧写操作重放。

REA 对 executePendingToolCalls 属性的 callers 查询返回了两个种子匹配,状态为 ambiguous、coverage 为 partial,Evidence 为 ev_9869e34990c183da28cafa47f75a72bb843018002e1fad4c1144285d11de5f71。本报告的局部调用关系同时依据具体源码位置,没有把这个歧义查询描述为完整语义追踪。

MCP 钩子也有明确的条件分支

smartModeApprovalOnly 会直接调用 innerExecutor。普通分支中 preToolUse 的 deny 会返回 permissionDenied;preToolUse 抛错是否拒绝取决于 hasFailClosedHooksForStep。随后 beforeMCPExecution 的 deny 也有拒绝分支。postToolUse 可以调整返回内容。这是可配置的执行包装机制;本局部分析没有验证系统沙箱或所有工具的授权执行。

Worker 身份与当前工作区绑定

nde 复用进程时同时比较 CLI installId、worker spec、worker ID 和本地 API 可达性。源码有 Windows named pipe 与其他平台 socket 分支,并把用户/工作区相关的稳定标识交给 worker;Ile 清理时使用 ownerHash 元数据筛选。进程启动使用 windowsHide,记录退出事件与 pid/install 文件清理。这为“前端关闭后继续执行、前端重新连接已有工作进程”提供了客户端机制依据,但我们没有实际运行它。

提炼为自己的产品:六条独立设计原则

以下是工作台的建议设计,不是从 Cursor 还原的产品源码或已验证的原版行为。

  1. 每次执行冻结一份工具能力表。 Tool registry 明确记录工具名、输入 schema、只读/写入性质、版本和当前权限;恢复时重新生成能力表并比较执行契约。
  2. 把执行事件与聊天文本分开存储。 同一 toolCallId 关联 queued、started、output、completed、failed、interrupted 事件,附起止时间;重连 UI 从事件流重建状态。
  3. 恢复策略按操作类型区分。 可重新运行只读查询;写文件或执行命令留下 pending/interrupted 状态与效果记录,由明确策略决定继续。不要把所有 pending 工具默认为可安全重放。
  4. 先形成可审核的改动,再写文件。 独立设计 Proposal 保存目标路径、基准文件散列、改动与 diff;应用前验证基准,应用后记录结果。基准散列与审核流程是我们的设计选择;已分析的 cte 方法只构造文本与引用范围。
  5. 执行包装层提供统一前后事件。 授权、参数验证、钩子、取消、结果转换和审计采用明确顺序;错误策略在设置中有确定语义,避免把失败后的“继续执行”当作隐含默认。
  6. UI 与任务进程可独立重连。 用 workspace + owner 的工作进程身份、握手与健康检查连接已有执行器,单独持久化会话与事件;重启 UI 不应重复启动同一个任务。

首版可以采用 Session → Turn → ToolCall → Event → Proposal 五种独立数据对象。工作进程有明确协议:connect、start、cancel、readEvents、resume;恢复记录保存最近持久化事件和未完成调用,继续任务前重新核对当前项目与工具契约。

范围与未决项

已回答当前工具上下文、事件记录、待执行工具恢复、MCP 包装分支、纯文本 patch 和 worker 复用的局部实现。文件写入的最终适配器、会话数据库格式、回滚事务、用户交互 UI、远端模型调度与权限分类服务未完成端到端追踪。本报告没有断言恢复完整原源码,也没有把静态解析当作系统行为实测。

本地分析切片与完整 Evidence 用于研究定位;统一产品应引用结论和证据索引,并独立编写实现,发行包无需包含这些第三方代码切片。

复现资料

  • inspect-component.cjs:从相同分发文件生成 AST 方法/位置索引及有限关键词定位。
  • extract-slices.cjs:抽取选定 AST 范围,记录原工件散列、字节位置和必要声明包装。
  • build-evidence-index.cjs:验证原文件未改变,计算关键方法字节范围及散列。
  • slices/slice-manifest.json 与 additional-slices/slice-manifest.json:原范围到分析切片的映射。
  • REA 使用 analyze_javascript_application、detail: summary、精确 source_paths 分析;完整 Evidence 已导出。