aider-delegate

Aider Delegate

你是编排者。将范围明确的编码任务交给单独的实现者——Aider，然后审查其产出并亲自提交。你撰写任务说明并负责判断；Aider 在自己的运行过程中编写代码；你负责验证并提交。

整个流程只需要一条 shell 命令和文件访问权限，因此任何类似的编排者都能驱动它。

了解 Aider 的关键一点

Aider 默认会提交更改。 它的两个默认设置会破坏这项技能旨在生成的可审查差异：

• --auto-commits（默认值为 True）——Aider 每次交互后都会提交自己的编辑。
• --dirty-commits（默认值为 True）——Aider 开始编辑前，会提交你先前已有的未提交工作。

中继程序始终会传入 --no-auto-commits 和 --no-dirty-commits，且无法通过它进行配置。如果你绕过中继程序，直接手动运行 aider，务必自行传入这两个参数，否则工作会以你从未审查过的提交形式落地。中继程序还会传入 --no-gitignore，因为 Aider 启动时否则会将 .aider* 写入 .gitignore，弄脏你正准备查看的工作树。

何时不应使用

• 任务足够小，可以直接完成；委派带来的额外开销不值得。
• 尚未安装 aider CLI，或未为其配置模型。
• 你希望实现者自行管理提交。Aider 可以这样做，但这项技能会刻意关闭该功能——差异就是交付物。

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

1. 安装 Aider——python -m pip install aider-chat，或使用 Aider 安装文档中的独立安装程序。
2. 配置模型。Aider 会从环境变量（OPENAI_API_KEY、ANTHROPIC_API_KEY，等等）或自身配置中读取服务提供方密钥；参见 Aider 的模型文档。
3. 确认 aider --version 能成功运行。
4. 在目标 git 仓库中工作，或通过 --cd 指定该仓库。

选择模型

如果省略 --model，Aider 会使用自身已配置的模型。传入 --model <name> 可选择其他模型。

本地和可自托管模型

Aider 可以连接任何兼容 OpenAI 的端点，因此也可以使用这项技能，将任务委派给运行在用户自有硬件上的模型，例如 llama.cpp 的 server、Ollama、vLLM、LM Studio，或任何提供相同 API 的服务。将 --model 与 --api-base 配合使用：

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo \
  --model openai/<served-model-name> --api-base http://127.0.0.1:<port>/v1

与托管服务提供方相比，有三点不同：

• 必须使用 openai/ 前缀。 这会告知 Aider 使用 OpenAI 协议与端点通信；前缀后的部分是服务报告的名称，而不是服务提供方目录中的名称。
• 仍需使用占位密钥。 导出任意非空的 OPENAI_API_KEY。即使服务忽略其值，客户端库也要求提供该标头。
• 要求使用更小的编辑格式。 本地模型通常无法处理 Aider 默认的 diff 格式，因为该格式要求精确的搜索／替换块。使用 --edit-format whole 以 token 换取可靠性；通过 --file 控制任务说明的范围，避免重写整个文件的成本过高。

如果本地端点未运行，表现会像是挂起，而不是报错：Aider 会持续重试连接，直到中继程序的 --timeout 看门狗触发并报告 status: "timeout"。派发较长的任务说明前，请确认服务已启动。

保持离线

无需注册账号或服务提供商：Aider 通过 pip 安装，端点由你掌控，OPENAI_API_KEY 只需非空即可。中继会固定那些原本可能自行访问网络的标志：--no-check-update、--no-analytics（Aider 自身的默认值是 random，会自行选择加入部分会话），以及 --no-detect-urls。如果不设置此标志，Aider 会主动抓取任务说明中的任意 URL，而 --yes-always 会静默接受这一操作。

--no-suggest-shell-commands 会关闭剩余的网络访问途径，避免运行过程中未经询问便访问网络。中继无法控制的是任务说明本身：如果其中的指令要求 Aider 安装软件包或调用 API，这些操作仍会执行；而 --auto-lint 会运行仓库自身的工具。这里所说的离线，是指派发流程中的任何环节都不会自行联网，并不意味着沙箱会阻止联网。

工作循环

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

1. 编写任务说明

Aider 只能看到你发送的文本和其编辑范围内的文件，不会看到聊天历史或共享上下文。请写明目标、当前状态、要修改的内容、要保持不变的内容、项目实际的门槛，以及报告约定。每份任务说明只处理一项任务。参见 references/writing-the-brief.md。

2. 派发

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

使用随附的辅助工具。它会封装 Aider 的无头 --message-file 模式、捕获运行过程，并写入 result.json。（<skill-dir> 是已安装且包含此 SKILL.md 的文件夹。）

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# choose a model:                        add --model <name>
# point at an OpenAI-compatible server:  add --api-base <url>
# scope the edit surface:                add --file <path> (repeatable), --read <path> for context only
# dry run, no files modified:            add --read-only
# continue the previous chat:            add --resume-last  (delta brief only)
# hard time limit (watchdog):            add --timeout 2h  (the 30m default suits short runs; implementation briefs routinely need 1-2h)
# see all options:                       node .../relay.mjs --help

子进程的 cwd 会固定工作区。任务说明通过 --message-file 传递，因此不会出现在 argv 中：它既不会出现在主机进程列表里，也不会受操作系统参数长度上限的影响。默认情况下，中继会将产物写入系统临时目录，且绝不会提交更改。参见 references/dispatch-and-poll.md。

3. 等待完成

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

辅助工具会阻塞等待 Aider 结束。请使用编排器的后台命令功能运行它，或者在 shell 中将其放到后台，并轮询 result.json。运行前的用法错误会以状态码 2 退出且不会写入结果；找不到 aider 时会以状态码 127 退出，并写入 status: "aider_unavailable"。

判断是否完成时，应以进程状态和工作树为准，而不是进度显示。进程已退出且 result.json 已存在，即表示完成。Aider 的报告位于 result.json 的 finalMessage 字段中（stdout 上的报告标记之间也会完整打印该报告）。

即使 Aider 尚未连接到模型，它也会以状态码 0 退出，因此中继会扫描此次运行，查找 Aider 自身的端点和身份验证错误；如果找到，则报告 status: "failed"。如果 failed 状态中的 error 提到了端点，请将其视为配置问题，而非编码失败。

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

将 Aider 的最终消息和门禁声明视为待核实的说法：

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

Aider 默认启用 --auto-lint，因此它可能已经运行了代码检查工具，并修复了自身报告的问题。这是 Aider 的代码检查，不是你的门禁——仍需运行自己的门禁。请参阅 references/review-and-land.md。

5. 合入

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

自主性与权限

中继会传入 --yes-always，这是 Aider 对自动确认所有提示的称呼，因为无头运行无法回应提示。请事先了解这代表同意什么。 自动确认适用于 Aider 原本会提出的所有提示，而 Aider 的提示不只涉及文件编辑：在默认设置下，它还会提议运行自己建议的 shell 命令，而 --yes-always 会在无人审阅这些命令的情况下接受它们。因此，中继固定使用 --no-suggest-shell-commands，以移除这条路径。

剩下的并不是沙箱，这里也不会假装如此。Aider 没有权限模式，也没有隔离机制：在文件范围内，它可以自由编辑；而 --auto-lint（默认启用）会运行仓库配置的任何代码检查工具。任务说明若要求 Aider 运行某条命令，该命令仍会被运行。委派即是授权；如果必须确保某次运行无法触及主机，请在容器或一次性工作树中运行，因为此中继中的任何标志都无法做到这一点。

文件选择并非安全边界。 --file、--read 和 --subtree-only 决定 Aider 在聊天上下文中包含哪些内容，这是范围和令牌成本方面的选择。它们不会限制 Aider 可以访问的内容。请参阅 references/writing-the-brief.md。

--read-only 对应 Aider 的 --dry-run，后者会在不修改文件的情况下执行运行。中继不会独立核实这一声明——它会报告 git status --porcelain 的结果，并在 --read-only 运行后工作树仍有更改时发出警告。保证来自 touchedFiles 和差异，而不是某个标志。

恢复运行

Aider 没有会话 ID。它以保存在仓库中的聊天历史文件（.aider.chat.history.md）作为恢复单位，因此 --resume-last 对应 Aider 的 --restore-chat-history，而 --history-file 用于指定某个历史文件。由于该历史文件保存在仓库中，恢复运行以工作树为单位，而非以用户为单位：同一项目的两个克隆不会共享历史记录。

授权模型

是否委派由人类自行决定。一旦人类选择委派（“运行此队列”“继续”），提交已验证且通过门禁的工作便是双方约定的契约。仍有两条限制：明确说明，不要自行吸收（报告 Aider 的设计决策、合理但未受要求的改动，以及不阻碍进展的小问题）；范围变更时停止（如果正确完成任务需要超出任务说明，请先询问，不要擅自扩大授权范围）。请参阅 references/review-and-land.md。

参考资料

• references/writing-the-brief.md - 任务说明结构、报告约定、实际门禁、文件范围和增量任务说明。
• references/dispatch-and-poll.md - 标志、产物、result.json、轮询和失败恢复。
• references/review-and-land.md - 审查清单、提交边界，以及通过 Aider 聊天历史进行返工。
• references/multi-task-queues.md - 顺序队列、约束延续、进度跟踪和最终一致性检查。