qoder-delegate

Qoder 委派

你是编排者。将一项范围明确的编码任务委派给独立的实现者——Qoder CLI——然后审查其成果并亲自落地。你撰写任务说明并负责判断；Qoder 在自己的会话中编辑工作树；你负责验证并提交。

此流程只需要 shell 和文件访问，因此任何同类编排者都可以执行。

以下情况请勿使用

• 任务小到可以直接完成；委派带来的额外开销不值得。
• 未安装或未完成身份验证 qodercli。
• 你想自己编写代码，或者只需要交互式 Qoder 会话。

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

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

如果缺少该二进制文件，请从 Qoder 的官方快速入门安装。使用 qodercli login 完成身份验证，或者为自动化设置 QODER_PERSONAL_ACCESS_TOKEN。成功运行 --list-models，即可确认当前账户能够获取实时模型目录。

选择模型和上下文窗口

Qoder 可用的模型可能会变化。如果用户指定了模型，请使用 qodercli --list-models 返回的当前确切值；切勿编造模型目录条目，也不要固定使用某个条目。否则省略 --model，让 Qoder 使用当前默认值。

--context-window <n> 是可选参数。仅在用户要求指定大小或任务需要明确的预算时，才传入正整数。Qoder 仅对支持的模型应用该参数；如果模型或大小不受支持，应明确报告错误，而不是静默改用其他值。

流程

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

1. 撰写任务说明

Qoder 能看到任务说明以及它可以在工作区中检查的内容，而看不到这段聊天。请说明目标、当前状态、需要修改的内容、保持不变的内容、项目的实际检查门槛，以及最终报告的要求。告知 Qoder 不要提交。每份任务说明只包含一项任务。参见references/writing-the-brief.md。

2. 派发

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

使用随附的中继程序。它会封装 Qoder 的非交互式 stream-json 模式，并写入 result.json。 <skill-dir> 是包含此 SKILL.md 的已安装文件夹。

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# choose a live model:                 add --model "<value from qodercli --list-models>"
# request a supported context window: add --context-window 32768
# resume the latest session:          add --resume-last  # delta brief only
# resume a specific session:          add --resume <id>  # delta brief only
# see every option:                   node .../relay.mjs --help

实现任务默认以 Qoder 的 auto 权限模式运行。除非调用方明确要求，否则中继程序绝不会绕过权限，也绝不会提交。参见references/dispatch-and-poll.md。

3. 等待完成

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

中继程序会一直阻塞，直到 Qoder 退出。请使用编排者提供的后台命令功能运行它，或者在 shell 中将其放到后台并等待 result.json。只有进程已退出且文件包含 status，才表示任务完成；不要相信进度显示。

原生 Windows 中继程序的启动方式尚未验证；在原生 Windows 烟雾测试通过前，不要声称已验证。

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

将 Qoder 的最终消息和门禁结果视为声明：

• 自行重新运行项目的门禁。
• 对照需求说明阅读差异，从 touchedFiles 开始。
• 单独检查任何 --add-dir 工作区；其中的更改不会出现在主树报告中。
• 如果已安装相关的防护技能，请运行它们。
• 对迁移进行往返测试，并在移除或重命名后搜索是否存在悬空引用。

请参阅 references/review-and-land.md。

5. 合并

由实现者编辑；由协调者提交。只有在门禁通过且差异内容符合要求后才提交。如果需要返工，请使用 --resume-last 或 --resume <id> 发送增量需求说明，然后再次审查。

权限模型

Qoder 打印模式无法显示审批提示。中继默认使用 auto，以非交互方式允许或拒绝操作。default 可能会拒绝需要提示的操作；accept_edits 允许编辑工作区，但可能会拒绝 Shell 操作；dont_ask 会以安全失败方式处理；plan 等同于 default 加上 Qoder 的 Plan 工作状态；而 bypass_permissions 仅适用于明确受信任的运行。

如果在非受信任目录中请求非默认模式，Qoder 会回退到 default。请检查 result.json 中的 actualPermissionMode；无论请求哪种模式，都不能取代差异审查。

授权模型

委派需要由人工主动选择。用户提出委派后，交付经过验证且通过门禁的工作就是约定内容。仍有两项限制：呈现，而非包揽（报告 Qoder 的设计决策和非阻塞偏差）以及遇到范围变更时暂停（在超出需求说明之前先征求同意）。请参阅 references/review-and-land.md。

参考资料

• references/writing-the-brief.md - 需求说明结构、实际门禁、报告约定、密钥和增量需求说明。
• references/dispatch-and-poll.md - 标志、模型／上下文控制、产物、结果字段、会话和故障恢复。
• references/review-and-land.md - 独立审查、提交边界和返工。
• references/multi-task-queues.md - 顺序队列、约束延续、进度跟踪和最终一致性。