qoder-delegate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Qoder Delegate

Qoder 任务委托

You are the orchestrator. Delegate one bounded coding task to a separate implementer - Qoder CLI - then review what it produced and land it yourself. You write the brief and own the judgment; Qoder edits the working tree in its session; you verify and commit.

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

你是协调者。将一个明确范围的编码任务委托给独立的执行者——Qoder CLI——然后审核其产出并自行完成提交。由你撰写任务简报并负责判断；Qoder在其会话中编辑工作目录；你负责验证并提交代码。

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

When NOT to use this

请勿使用此方法的场景

The task is small enough to do inline; delegation overhead is not worth it.
```
qodercli
```
is not installed or authenticated.
You want to write the code yourself or need only an interactive Qoder session.

任务规模小到可直接完成；委托的额外开销得不偿失。
未安装或未认证
```
qodercli
```
。
你希望自行编写代码，或仅需要交互式Qoder会话。

Prerequisites (check once)

前提条件（只需检查一次）

bash

command -v qodercli
qodercli --version
qodercli --list-models

If the binary is missing, install it from Qoder's official Quick Start. Authenticate with

qodercli login

, or set

QODER_PERSONAL_ACCESS_TOKEN

for automation. A successful

--list-models

confirms the current account can return its live model catalog.

bash

command -v qodercli
qodercli --version
qodercli --list-models

如果缺少该二进制文件，请从Qoder的官方快速入门页面安装。使用

qodercli login

进行认证，或设置

QODER_PERSONAL_ACCESS_TOKEN

以实现自动化。成功执行

--list-models

命令即可确认当前账户可获取实时模型目录。

Choose model and context window

选择模型与上下文窗口

Qoder's available models can change. If the human requests a model, use its exact current value from

qodercli --list-models

; never invent or pin a catalog entry. Otherwise omit

--model

and let Qoder use its current default.

--context-window <n>

is optional. Pass a positive integer only when the human requests a size or the task needs an explicit budget. Qoder applies it only to supported models; surface an unsupported model/size error instead of silently choosing another value.

Qoder的可用模型可能会变化。如果用户指定了模型，请使用

qodercli --list-models

返回的准确当前值；请勿自行编造或固定目录条目。否则省略

--model

参数，让Qoder使用当前默认模型。

--context-window <n>

为可选参数。仅当用户指定大小，或任务需要明确预算时，传入正整数。Qoder仅会将其应用于支持的模型；若模型不支持该大小，请显示错误信息，而非静默选择其他值。

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. 撰写任务简报

Qoder sees the brief plus what it can inspect in the workspace, not this chat. Include the goal, current state, what to change, what to leave untouched, the project's actual gates, and a closing report contract. Tell Qoder not to commit. Keep one task per brief. See references/writing-the-brief.md.

Qoder只能看到任务简报以及它在工作区中可检查的内容，无法看到本次对话内容。简报需包含目标、当前状态、需要修改的内容、需要保留的内容、项目的实际准入标准，以及最终报告要求。告知Qoder不要提交代码。每份简报对应一个任务。详情请查看references/writing-the-brief.md。

2. Dispatch

2. 派发任务

Use the bundled relay. It wraps Qoder's non-interactive

stream-json

mode 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

使用内置的中继工具。它封装了Qoder的非交互式

stream-json

模式，并生成

result.json

文件。

<skill-dir>

是包含此

SKILL.md

文件的安装目录。

bash

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

choose a live model: add --model "<value from qodercli --list-models>"

选择可用模型: 添加 --model "<qodercli --list-models 返回的值>"

request a supported context window: add --context-window 32768

请求支持的上下文窗口: 添加 --context-window 32768

resume the latest session: add --resume-last # delta brief only

恢复最近的会话: 添加 --resume-last # 仅需提交增量简报

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

恢复指定会话: 添加 --resume <id> # 仅需提交增量简报

see every option: node .../relay.mjs --help

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


Implementation runs default to Qoder's `auto` permission mode. The relay never bypasses permissions
unless the caller explicitly requests it, and it never commits. See
[references/dispatch-and-poll.md](references/dispatch-and-poll.md).


任务执行默认使用Qoder的`auto`权限模式。中继工具不会绕过权限，除非调用者明确要求，且它永远不会提交代码。详情请查看[references/dispatch-and-poll.md](references/dispatch-and-poll.md)。

3. Wait for completion

3. 等待任务完成

The relay blocks until Qoder exits. Run it with the orchestrator's background-command facility, or background it in the shell and wait for

result.json

. Completion means the process exited and the file contains a

status

; do not trust a progress display.

A pre-run usage error exits 2 and writes no result. Missing

qodercli

exits 127 and writes

status: "qoder_unavailable"

with installation guidance.

Native Windows relay launch is not yet verified; do not claim it until a native Windows smoke passes.

中继工具会阻塞直到Qoder退出。可以使用协调者的后台命令工具运行它，或在Shell中将其置于后台并等待

result.json

生成。任务完成意味着进程已退出，且文件中包含

status

字段；请勿依赖进度显示判断完成状态。

预运行使用错误会以退出码2终止，且不会生成结果文件。若缺少

qodercli

，会以退出码127终止，并写入

status: "qoder_unavailable"

及安装指引。

暂未验证原生Windows环境下的中继工具启动方式；在通过原生Windows冒烟测试前，请不要宣称支持该环境。

4. Review - do not trust the self-report

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

Treat Qoder's final message and gate outcomes as claims:

Re-run the project's gates yourself.
Read the diff against the brief, starting with
```
touchedFiles
```
.
Check any
```
--add-dir
```
workspaces separately; their changes are not in the primary tree report.
Run relevant guard skills if installed.
Round-trip migrations and grep for dangling references after removals or renames.

See references/review-and-land.md.

将Qoder的最终消息和准入标准验证结果视为声明：

自行重新运行项目的准入验证。
根据任务简报审核代码差异，从
```
touchedFiles
```
开始检查。
单独检查所有
```
--add-dir
```
工作区；它们的变更不会出现在主目录报告中。
若已安装相关守护工具，请运行它们。
在删除或重命名操作后，往返运行迁移脚本并搜索悬空引用。

详情请查看references/review-and-land.md。

5. Land it

5. 完成提交

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

--resume-last

--resume <id>

, then review again.

执行者负责编辑代码；协调者负责提交。仅当准入验证通过且代码差异符合要求时，再进行提交。若需要返工，请通过

--resume-last

或

--resume <id>

提交增量简报，然后重新审核。

Permission model

权限模型

Qoder print mode cannot show approval prompts. The relay defaults to

auto

, which makes non-interactive allow/deny decisions.

default

can deny actions that would require a prompt;

accept_edits

permits workspace edits but may deny shell actions;

dont_ask

fails closed;

plan

maps to

default

plus Qoder's Plan work state; and

bypass_permissions

is for explicitly trusted runs only.

Qoder falls back to

default

when a non-default mode is requested outside a trusted directory. Check

actualPermissionMode

result.json

; no requested mode replaces diff review.

Qoder打印模式无法显示授权提示。中继工具默认使用

auto

模式，该模式会自动做出非交互式的允许/拒绝决策。

default

模式可能会拒绝需要提示的操作；

accept_edits

模式允许编辑工作区，但可能拒绝Shell操作；

dont_ask

模式会默认拒绝；

plan

模式对应

default

模式加上Qoder的规划工作状态；

bypass_permissions

模式仅适用于明确信任的任务执行。

当在非受信任目录中请求非默认模式时，Qoder会 fallback 到

default

模式。请检查

result.json

中的

actualPermissionMode

字段；无论使用何种请求模式，都不能替代代码差异审核。

Authorization model

授权模型

Delegation is something the human opts into. Once they ask for it, landing verified, gate-passing work is the contract. Two limits remain: surface, do not absorb (report Qoder's design decisions and non-blocking deviations) and stop for scope changes (ask before expanding beyond the brief). See references/review-and-land.md.

任务委托是用户主动选择的操作。一旦用户要求使用该方式，提交经过验证、符合准入标准的工作成果就是约定内容。仍有两个限制：透明化而非隐瞒（报告Qoder的设计决策和非阻塞性偏差）和范围变更需确认（在超出简报范围前询问用户）。详情请查看references/review-and-land.md。

References

参考资料

references/writing-the-brief.md - brief structure, real gates, report contract, secrets, and delta briefs.
references/dispatch-and-poll.md - flags, model/context controls, artifacts, result fields, sessions, and failure recovery.
references/review-and-land.md - independent review, commit boundary, and rework.
references/multi-task-queues.md - sequential queues, constraint carry-forward, progress tracking, and final coherence.

references/writing-the-brief.md - 简报结构、实际准入标准、报告要求、保密信息及增量简报。
references/dispatch-and-poll.md - 参数、模型/上下文控制、工件、结果字段、会话及故障恢复。
references/review-and-land.md - 独立审核、提交边界及返工流程。
references/multi-task-queues.md - 顺序任务队列、约束传递、进度跟踪及最终一致性。