Cursor客户端解剖（六）工具循环：终端、MCP、Rules、Skills

发表于 分类于

系列：Cursor客户端解剖系列学习笔记
上一篇：（五）Chat、Composer 与 Agent

工具不是提示词里的口头约定

学习材料依据包内 agent.v1.*ToolCall protobuf：工具是强类型消息，不是「请你自己注意要用工具」这种软约束。

循环骨架：

1
2
3
4
模型（服务端或 Private Inference）输出 ToolCall
    → 本地 Agent Exec 执行（可审批 / sandbox）
    → 工具结果回传
    → 模型继续，直到结束

协议上还能看到钩子：PreToolUse / PostToolUse / BeforeSubmitPrompt——执行前后、提交前可拦截。

本地工具清单（节选）

仓库只读

工具 作用
ReadToolCall 读文件（path/offset/limit）
GrepToolCall 精确搜索
GlobToolCall / LsToolCall 找文件 / 列目录
SemSearchToolCall 语义检索
ReadLintsToolCall 读诊断

改代码 / 改环境（常需审批）

工具 作用
EditToolCall / Write 族 / DeleteToolCall 改删文件
ApplyAgentDiffToolCall 应用 Agent diff
ShellToolCall 跑命令（含 sandbox_policy、timeout、后台等）
AwaitToolCall / WriteShellStdinToolCall 后台任务协作

与用户交互 / 规划

AskQuestionToolCall · UpdateTodosToolCall · CreatePlanToolCall · SwitchModeToolCall · TaskToolCall · ReflectToolCall …

外部世界

工具 更可能在哪
WebSearchToolCall 服务端编排
McpToolCall / GetMcpToolsToolCall 本地 MCP 进程
ComputerUseToolCall 本地/云桌面
PR / SCM 族 混合

MCP：工具变成可插拔服务

包内落点：

  • 扩展 cursor-mcp（workspace，onStartupFinished + onUri）
  • Utility：mcpProcess
  • cursor-browser-automation：通过 MCP Provider 暴露浏览器自动化
  • 依赖锁定 @modelcontextprotocol/sdk（版本钉死）

精髓：

IDE 内工具 ≠ 写死在 Agent 代码里的 if/else。
MCP 把工具变成可插拔服务；浏览器自动化也套同一形态，心智统一。

Rules / Skills：进 prompt 的积木

本地收集、塞进 RunRequest 的约束类积木包括：

  1. Rules 类型：Global / FileGlobs / ManuallyAttached / AgentFetched
    文件：.cursor/rules/**/*.mdc、AGENTS.md、CLAUDE.md、.cursorrules
  2. Skills（AgentSkill）
  3. custom_system_prompt 字段

包内优先级文案大意：

系统提示 > AGENTS.md / rules / skills > 普通用户偏好（冲突时听 system）

Rules 偏常驻宪法；Skills 偏情境手册。和「工具强类型」一样，它们是产品化上下文，不是聊天里临时说一句。

权限与隔离：副作用管线

两层值得分开看：

  1. 执行时审批 / sandbox
    Shell 等工具带策略字段；Exec 描述强调 permissions & approvals。

  2. 落盘隔离

    • cursor-shadow-workspace：registerShadow*Provider
    • cursor-worktree-textmate：给 .cursor/worktrees TextMate 高亮，不激活语言服务器

精髓：Agent 写代码的危险不在「会不会写」，在「写到哪」。影子世界 + 弱语言服务 = 可实验、少干扰、可控回滚。

另有文件化契约：

  • .cursor/environment.json
  • .cursor/permissions.json（由 cursor-always-local 等贡献 schema）

可进仓库、可审查、可同步——和 ignore 规则同一哲学。

可观测性不是事后补丁

  • 大量 cursorTracing
  • cursor-ndjson-ingest：本地 HTTP 吃 NDJSON → .cursor/debug.log
  • cursor-socket 提供失败注入类开发者命令

Agent 系统难测；从第一天就留 日志摄入 + 故障注入 口子。

小结

工具循环在包内的三句话：

  1. ToolCall 强类型 + 双向流，模型想、本地做
  2. MCP 把扩展工具标准化
  3. Rules/Skills/permissions/ignore 把边界文件化

下一篇把这些模块串成一次完整任务时序。