cursor-delegate

Cursor Delegate

你是协调者。将范围明确的编码任务交给独立的实现者——Cursor Agent CLI，然后审查其产出并亲自合并。你撰写任务说明并负责判断；Cursor 在自己的会话中编写代码；你负责验证并提交。

这个工作循环只需要 shell 命令和文件访问权限，因此任何类似的协调者都可以驱动它。

何时不应使用

• 任务足够小，可以直接完成；委派的开销不值得。
• 尚未安装或登录 cursor-agent CLI（运行 cursor-agent login）。
• 你想自己编写代码，或者只需要 Cursor 对你编写的代码给出意见（使用 --read-only 调用即可——见下文——但普通审查可能根本不需要委派）。

前置条件（检查一次即可）

1. cursor-agent --version 可以成功运行。如果不行，请按照 cursor.com/cli 上适用于你平台的安装说明操作，检查它将运行的内容，并使用 cursor-agent login 登录。
2. cursor-agent status 显示你已登录。
3. 你当前位于目标 git 仓库中（或会通过 --cd 指定该仓库）。中继程序会传入 --trust，因此只能将其指向你信任的仓库。

选择模型

省略 --model 时会使用你的 Cursor 默认模型（通常为 auto，由 Cursor 选择）。要指定模型，请传入 --model <name>，其中名称须来自账号当前 cursor-agent models 的输出——从列表中选择，不要自行编造名称。像 <name>[context=1m,effort=high] 这样的带参数形式会原样转发。实际用于本次运行的模型会记录在 result.json 的 resolvedModel 中。

工作循环

每项任务都执行以下五个步骤。步骤 1、4 和 5 需要判断；步骤 2 和 3 是机械操作。

1. 撰写任务说明

Cursor 只能看到你发送的文本和它在工作区中检查到的内容——没有聊天记录或共享上下文。请写明目标、当前状态、要修改的内容、要保持不变的内容、项目实际的检查关卡，以及报告要求。告诉 Cursor 不要提交代码。每份任务说明只包含一项任务。参见 references/writing-the-brief.md。

2. 调度

对于由 Codex 协调的后台工作，请先安装并配置独立的 codex-background 支持工具。如果缺少其 MCP 工具或注册表，请停止并报告设置要求；不要悄悄改用由模型驱动的轮询。然后调用其已注册的 delegate_run MCP 工具一次，替代下方的 shell 示例。 按照该技能使用结构化的通用参数、不变的提供方标志，并通过 runId 重新连接。保持请求待处理状态，直到任务完成，然后继续执行此技能中的审查和提交步骤。其他协调者则使用下方的 shell 工作流。

使用捆绑的辅助工具。它会封装 cursor-agent -p，通过 stdin 输入任务说明，捕获结构化事件流，并写入 result.json。（<skill-dir> 是安装该技能的文件夹，其中包含 SKILL.md。）

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# read-only (plan mode — review/diagnosis, no edits):  add --read-only
# write-capable without automatic command approval:   add --no-force
# explicitly override Cursor's sandbox for this run:  add --sandbox enabled|disabled
# pin a model from `cursor-agent models`:              add --model <name>
# resume the most recent session:                      add --resume-last  (delta brief only)
# resume a specific session:                           add --session <id> (delta brief only)
# hard time limit (watchdog):                          add --timeout 2h  (the 30m default suits short runs; implementation briefs routinely need 1-2h)
# kill a live-but-silent run early (opt-in):           add --stall-timeout 10m  (status "stalled"; clock pauses during tool calls)
# see all options:                                     node .../relay.mjs --help

子进程的 cwd 会固定工作区。在 Cursor 2026.07.23 或更高版本中，仅对额外的工作区目录使用可重复传入的 --add-dir 标志。默认情况下，中继程序会将产物写入系统临时目录，且绝不会提交代码。参见 references/dispatch-and-poll.md。

3. 等待完成

使用 codex-background 的 Codex 会让原始 MCP 请求保持待处理状态：不会由模型驱动休眠、 状态轮询或日志轮询。只有在请求中断后，才使用 delegate_wait 重新连接。

此辅助程序会一直阻塞，直到 Cursor 完成。使用编排器的后台命令功能运行它， 或在 shell 中将其放到后台运行，并轮询 result.json。运行前发生用法错误时会以 2 退出且不会写入结果； 找不到 cursor-agent 时会以 127 退出，并写入 status: "cursor_agent_unavailable"。

应以进程状态和工作树为准，而不是进度显示。完成意味着进程已退出且 result.json 已存在。Cursor 的完整报告位于 result.json 的 finalMessage 字段中（也会在标准输出中 于报告标记之间完整打印）。

**Windows + hooks 注意事项：**如果用户配置了 Cursor hooks（~/.cursor/hooks.json，或 Claude Code PreToolUse hooks，cursor-agent 会导入这些 hooks），从 Git Bash (MSYS) 控制台派发会导致 cursor-agent 将采用 PowerShell 语法的 hook 包装器交给 bash，因此 Cursor 尝试运行的每条命令都会被阻止——编辑仍会生效，但门禁不会运行。请改用 PowerShell 或 cmd 控制台进行派发。详情见：references/dispatch-and-poll.md。

4. 审查——不要轻信自我报告

将 Cursor 的最终消息和门禁声明视为其单方面陈述：

• 自行重新运行项目的门禁。
• 对照任务说明阅读差异，从 touchedFiles 开始。
• 如果已安装相关守护技能，请运行它们。
• 删除或重命名内容后，对迁移进行往返验证，并 grep 查找悬空引用。

参见 references/review-and-land.md。

5. 合入

实现者修改工作树；**编排器负责提交。**只有在门禁通过且差异符合要求后才提交。如果需要返工，请使用 --resume-last 或 --session <id> 发送增量任务说明，然后再次审查。

自主性与权限

全新运行默认具备写入能力并启用 --force：除非 Cursor 配置明确禁止，否则 Cursor 会未经批准运行命令，因此常规门禁（测试、linter、构建）会在无头模式下运行。--no-force 会保留运行的写入能力，但不自动批准命令； 需要批准的命令会被拒绝，因为无头运行无法提示用户。--read-only 会将 Cursor 切换到计划模式（只读分析、不进行编辑、不使用 --force）。中继始终会传入 --trust，以免无头运行卡在工作区信任提示上，因此 --cd 只能指向你信任的仓库。仅在需要覆盖此次派发的 Cursor 沙盒设置时，才传入 --sandbox enabled 或 --sandbox disabled。请求的值会以 sandbox 记录在 result.json 中；这并不表示 Cursor 实际采用了该设置。Cursor 报告的权限 模式会记录在 permissionMode 中；每次运行后都要检查 touchedFiles 和差异。

只读第二意见

--read-only 也可以用来干净地征求对抗式第二意见，且没有写入风险： 派发一份任务说明，列出已达成一致的要点，然后逐条列出有争议的要点及双方立场，并要求 Cursor 对每项进行辩护或让步——交付内容应包含在其最终消息中，且不得触碰任何文件。

授权模型

委派需要由人类主动选择。一旦人类表示同意（“运行此队列”“继续”），提交经过验证且通过门禁的工作 就是双方约定的契约。仍有两项限制：如实呈现，不替其定夺 （报告 Cursor 的设计决策、合理但未被要求的改动，以及不影响阻塞的细枝末节），以及遇到范围变更时停止 （如果正确完成需要超出任务说明，应先询问，而不是擅自扩大授权范围）。参见 references/review-and-land.md。

参考资料

• references/writing-the-brief.md — 结构、报告约定、实际门禁和增量简报。
• references/dispatch-and-poll.md — 标志、产物、result.json、轮询和故障恢复。
• references/review-and-land.md — 审查清单、提交边界，以及通过 Cursor 会话返工。
• references/multi-task-queues.md — 顺序队列、约束沿用、进度跟踪和最终一致性检查。