cursor-delegate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cursor Delegate

Cursor 委托功能

You are the orchestrator. Hand a bounded coding task to a separate implementer — the Cursor Agent CLI — then review what it produced and land it yourself. You write the brief and own the judgment; Cursor does the typing in its own session; you verify and commit.

The loop needs only a shell command and file access, so any comparable orchestrator can drive it.

你作为协调者，将明确界定的编码任务交给独立的实现工具——Cursor Agent CLI，之后审查其产出并自行完成提交。由你编写任务简报并负责判断；Cursor在独立会话中完成代码编写；你负责验证并提交。

该流程仅需Shell命令和文件访问权限，因此任何类似的协调工具都可驱动它。

When NOT to use this

何时不使用此功能

The task is small enough to do inline; delegation overhead is not worth it.
The
```
cursor-agent
```
CLI is not installed or authenticated (run
```
cursor-agent login
```
).
You want to write the code yourself, or you only need Cursor's opinion on code you wrote (a
```
--read-only
```
dispatch covers that — see below — but a plain review may not need delegation at all).

任务足够小，可以直接完成；委托的开销得不偿失。
```
cursor-agent
```
CLI未安装或未完成认证（运行
```
cursor-agent login
```
进行认证）。
你希望自行编写代码，或仅需Cursor对你编写的代码提供意见（
```
--read-only
```
调度可满足此需求——详见下文——但普通审查可能根本不需要委托）。

Prerequisites (check once)

前置条件（一次性检查）

```
cursor-agent --version
```
succeeds. If not, follow the installer for your platform at cursor.com/cli, inspect what it will run, and authenticate with
```
cursor-agent login
```
.
```
cursor-agent status
```
shows you logged in.
You are in (or will point
```
--cd
```
at) the target git repository. The relay passes
```
--trust
```
, so point it only at repositories you trust.

运行
```
cursor-agent --version
```
成功。若失败，请遵循对应平台的安装指引访问cursor.com/cli，检查即将运行的内容，并通过
```
cursor-agent login
```
完成认证。
```
cursor-agent status
```
显示已登录状态。
你处于（或将通过
```
--cd
```
指定）目标Git仓库目录。中继会传递
```
--trust
```
参数，因此仅可指向你信任的仓库。

Choose the model

选择模型

Omitting

--model

uses your Cursor default (usually

auto

— Cursor picks). To pin one, pass

--model <name>

with a name from the account's live

cursor-agent models

output — select from that list rather than inventing a name. Parameterized forms like

<name>[context=1m,effort=high]

are forwarded as-is. The model that actually served the run is recorded as

resolvedModel

result.json

省略

--model

参数将使用你的Cursor默认模型（通常为

auto

——由Cursor自动选择）。若要固定模型，需传递

--model <name>

参数，其中模型名称需来自账户当前

cursor-agent models

输出的列表——请从该列表中选择，而非自行编造名称。类似

<name>[context=1m,effort=high]

的参数化格式将直接传递。实际运行所使用的模型会记录在

result.json

的

resolvedModel

字段中。

The loop

流程步骤

Run these five steps per task. Steps 1, 4, and 5 require judgment; 2 and 3 are mechanical.

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

1. Write the brief

1. 编写任务简报

Cursor sees only the text you send plus what it can inspect in the workspace — no chat history or shared context. Include the goal, current state, what to change, what to leave untouched, the project's actual gates, and a report contract. Tell Cursor not to commit. Keep one task per brief. See references/writing-the-brief.md.

Cursor仅能看到你发送的文本以及它可在工作区中检查的内容——无聊天历史或共享上下文。简报需包含目标、当前状态、需修改内容、需保留内容、项目的实际校验规则，以及报告要求。告知Cursor无需提交。每个简报对应一个任务。详见references/writing-the-brief.md。

2. Dispatch

2. 调度任务

Use the bundled helper. It wraps

cursor-agent -p

, feeds the brief on stdin, captures the structured event stream, and writes

result.json

. (

<skill-dir>

is the installed folder containing this

SKILL.md

bash

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo

使用内置的辅助工具。它封装了

cursor-agent -p

，将简报通过标准输入传入，捕获结构化事件流，并写入

result.json

。（

<skill-dir>

是包含此

SKILL.md

的安装目录。）

bash

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo

read-only (plan mode — review/diagnosis, no edits): add --read-only

只读模式（规划模式——仅审查/诊断，不编辑）：添加 --read-only

write-capable without automatic command approval: add --no-force

可写入但不自动批准命令：添加 --no-force

pin a model from

cursor-agent models

: add --model <name>

固定来自

cursor-agent models

的模型：添加 --model <name>

resume the most recent session: add --resume-last (delta brief only)

恢复最近的会话：添加 --resume-last （仅需增量简报）

resume a specific session: add --session <id> (delta brief only)

恢复特定会话：添加 --session <id> （仅需增量简报）

hard time limit (watchdog): add --timeout 2h (the 30m default suits short runs; implementation briefs routinely need 1-2h)

硬超时限制（监控）：添加 --timeout 2h （默认30分钟适合短任务；实现类简报通常需要1-2小时）

see all options: node .../relay.mjs --help

查看所有选项：node .../relay.mjs --help


The child process's cwd pins the workspace. On Cursor `2026.07.23` or newer, use repeatable
`--add-dir` flags only for extra workspace directories. The relay writes artifacts under the system
temp dir by default and never commits. See
[references/dispatch-and-poll.md](references/dispatch-and-poll.md).


子进程的当前工作目录固定为工作区。对于Cursor `2026.07.23`或更新版本，仅需为额外工作区目录使用可重复的`--add-dir`标志。中继默认将工件写入系统临时目录，且绝不会自动提交。详见[references/dispatch-and-poll.md](references/dispatch-and-poll.md)。

3. Wait for completion

3. 等待完成

The helper blocks until Cursor finishes. Run it with the orchestrator's background-command facility, or background it in the shell and poll for

result.json

. A pre-run usage error exits 2 and writes no result; a missing

cursor-agent

exits 127 and writes

status: "cursor_agent_unavailable"

Trust process state and the working tree over a progress display. Completion means the process exited and

result.json

exists. Cursor's full report is the

finalMessage

field in

result.json

(also printed in full on stdout between the report markers).

Windows + hooks caveat: if the user has Cursor hooks configured (

~/.cursor/hooks.json

, or Claude Code

PreToolUse

hooks, which cursor-agent imports), dispatching from a Git Bash (MSYS) console makes cursor-agent feed PowerShell-syntax hook wrappers to bash, so every command Cursor tries to run is blocked — edits still land, gates do not run. Dispatch from a PowerShell or cmd console instead. Details: references/dispatch-and-poll.md.

辅助工具会阻塞直到Cursor完成任务。可以通过协调者的后台命令功能运行它，或在Shell中将其后台运行并轮询

result.json

。预运行使用错误会以状态码2退出且不写入结果；若

cursor-agent

缺失则以状态码127退出并写入

status: "cursor_agent_unavailable"

。

优先信任进程状态和工作树，而非进度显示。完成意味着进程已退出且

result.json

已存在。Cursor的完整报告位于

result.json

的

finalMessage

字段中（也会在报告标记之间完整打印到标准输出）。

Windows + 钩子注意事项： 如果用户配置了Cursor钩子（

~/.cursor/hooks.json

，或Claude Code的

PreToolUse

钩子，cursor-agent会导入这些钩子），从Git Bash（MSYS）控制台调度任务会导致cursor-agent将PowerShell语法的钩子包装器传入bash，因此Cursor尝试运行的每个命令都会被阻塞——编辑仍会生效，但校验规则无法运行。请改为从PowerShell或cmd控制台调度任务。详情：references/dispatch-and-poll.md。

4. Review — do not trust the self-report

4. 审查——不要信任自报告

Treat Cursor's final message and gate claims as claims:

Re-run the project's gates yourself.
Read the diff against the brief, starting with
```
touchedFiles
```
.
Run relevant guard skills if installed.
Round-trip migrations and grep for dangling references after removals or renames.

See references/review-and-land.md.

将Cursor的最终消息和校验规则执行声明视为待验证的说法：

自行重新运行项目的校验规则。
对照任务简报阅读代码差异，从
```
touchedFiles
```
开始。
若已安装相关防护技能，运行它们。
在删除或重命名后，往返迁移并搜索悬空引用。

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

5. Land it

5. 完成提交

The implementer edits the working tree; the orchestrator commits. Commit only after the gates pass and the diff holds. If rework is needed, send a delta brief with

--resume-last

--session <id>

, then review again.

实现工具会修改工作树；协调者负责提交。仅在校验规则通过且代码差异符合要求后再提交。若需要返工，使用

--resume-last

或

--session <id>

发送增量简报，然后再次审查。

Autonomy and permissions

自主性与权限

A fresh run defaults to write-capable with
--force
: Cursor runs commands without approval unless your Cursor config explicitly denies them, so ordinary gates (tests, linters, builds) run headlessly.

--no-force

keeps the run write-capable but withholds automatic command approval; commands that require approval are refused because a headless run cannot prompt.

--read-only

switches to Cursor's plan mode (read-only analysis, no edits, no

--force

). The relay always passes

--trust

to keep headless runs from stalling on the workspace-trust prompt, which is why

--cd

must only ever point at repositories you trust. The permission mode Cursor actually applied is recorded as

permissionMode

result.json

; inspect

touchedFiles

and the diff after every run.

新运行默认处于可写入且带
--force
模式：除非你的Cursor配置明确禁止，否则Cursor会无需批准直接运行命令，因此常规校验规则（测试、代码检查、构建）会在无交互状态下运行。
--no-force
保持运行的可写入状态，但不自动批准命令；需要批准的命令会被拒绝，因为无交互运行无法提示。
--read-only
会切换到Cursor的规划模式（只读分析，不编辑，无

--force

）。中继始终传递

--trust

参数，以避免无交互运行因工作区信任提示而停滞，这也是为什么

--cd

必须仅指向你信任的仓库。Cursor实际应用的权限模式会记录在

result.json

的

permissionMode

字段中；每次运行后请检查

touchedFiles

和代码差异。

Read-only second opinions

只读模式获取第二意见

--read-only

doubles as a clean way to get an adversarial second opinion with no write risk: dispatch a brief that lists the agreed points, then each contested point with both positions, and ask Cursor to defend or concede each — deliverable in its final message, touching no files.

--read-only

还可作为一种安全获取反向第二意见的方式，无写入风险：调度一份简报，列出已达成一致的要点，然后逐个列出有争议的要点及双方立场，并要求Cursor为每个要点辩护或让步——最终消息中会给出结果，且不会修改任何文件。

Authorization model

授权模型

Delegation is something the human opts into. Once they have ("run this queue", "proceed"), committing verified, gate-passing work is the agreed contract. Two limits remain: surface, don't absorb (report Cursor's design decisions, defensible-but-unasked turns, and non-blocking nitpicks) and stop for scope changes (if correct completion needs going beyond the brief, ask instead of expanding the mandate). See references/review-and-land.md.

委托是用户主动选择的操作。一旦用户选择（如“运行此队列”、“继续”），提交已验证且通过校验规则的工作是约定的职责。仍有两个限制：披露而非隐瞒（报告Cursor的设计决策、合理但未要求的变更，以及非阻塞性的小问题）和范围变更时停止（若正确完成任务需要超出简报范围，需先询问用户而非自行扩大任务范围）。详见references/review-and-land.md。

References

参考资料

references/writing-the-brief.md — structure, report contract, real gates, and delta briefs.
references/dispatch-and-poll.md — flags, artifacts,
```
result.json
```
, polling, and failure recovery.
references/review-and-land.md — review checklist, commit boundary, and rework through Cursor sessions.
references/multi-task-queues.md — sequential queues, constraint carry-forward, progress tracking, and the final coherence pass.

references/writing-the-brief.md — 结构、报告要求、实际校验规则和增量简报。
references/dispatch-and-poll.md — 标志、工件、
```
result.json
```
、轮询和故障恢复。
references/review-and-land.md — 审查清单、提交边界和通过Cursor会话进行返工。
references/multi-task-queues.md — 顺序队列、约束传递、进度跟踪和最终一致性检查。