agent-orchestration git:20261016.5f6e7d3A

Immutable. This exact content never changes and is served at /api/v1/blob/070ec388c97ce625.

---
name: agent-orchestration
description: "当任务包含大量相似工作、长时间管线或需要并行陪跑与异常修复时，组织主 Codex、原生子 agent 或 Claude Code/Atria 中层监督者，以及确定性底层执行者；控制权限、资源、证据和接管边界。"
---

# Agent 调度与持续陪跑

## 适用目标

- 用于把大批任务分成可独立验收的管线，由少量持续会话监督多轮执行，提高吞吐并节约主 agent 的上下文与 token。
- 中层可选运行时允许的原生子 agent，或以 Atria-Dawn 为后端的 Claude Code。用户说明当前 Atria 可免费使用；调用前仍应核对服务条件，并计入延迟、CPU/内存和并发成本。
- 不为一次性小任务强行建立三层结构；先判断确定性代码、单个 agent 或现有任务调度器能否直接完成。

## 三层职责

| 层次 | 负责什么 | 必须保留的边界 |
| --- | --- | --- |
| 顶层：用户与主 agent | 明确目标、拆分与分配 owner、定义验收、核实关键证据、处理跨管线决策、向用户汇报；异常超出中层能力时接管。 | 不把中层报告直接当作完成证明，也不长期只转发状态。 |
| 中层：原生子 agent 或外部 Claude Code | 以长期会话陪跑一组管线，监控状态变化、定位异常、准备精准修复、运行聚焦检查并交接。可并发，但每条共享资源只设一个写入 owner。 | 有任务级自由度，但不得自行扩大写入范围、修改 live 状态或批准自己的候选补丁。 |
| 底层：管线与执行 agent | 按固定流程执行、产生实体与验证结果；可由确定性代码或自由度较低的 agent 实现。 | 中层接入不隐式改变原有模型、provider、session、预算或门禁。 |

例如处理 100 个独立事项，可分为 10 组，每组由一个长期中层会话维护 10 条管线，完成一批后再接下一批。**10 个中层不是默认并发数**：只有任务确实独立、权限清晰、机器和服务均能承受时才逐步扩容。中层会话及其简短状态摘要应跨批复用，避免每轮重新读取历史。

## 分配与验收

1. 顶层先给每个中层明确目标、输入、独占 owner、可写路径、禁止事项、完成证据、聚焦检查、交付时限和接管条件。先读目标仓库自己的 `AGENTS.md` 等规则。
2. 默认让中层在独立候选目录或 worktree 修改；同一共享文件只指定一个修改者。需要动 live 管线、共享配置、任务启停、发布、预算或认证时，须有对应具体对象和动作的授权。
3. 中层交付最小补丁、复现和实际测试结果、证据路径及剩余风险。`candidate_ready`、模型判断或“建议重跑”都不是部署或任务完成。
4. 顶层复核 diff、来源和门禁，必要时亲自执行接线与最终验收；底层按原有真实执行、校验及发布证据计数。不得伪造完成标记或用报告替代实体检查。
5. 同一原因连续误判或失败、约 15 分钟没有可执行候选、权限反复受阻、范围扩张、owner 冲突或触及未验证能力时，中层交接事实与阻塞，顶层缩小任务或直接接手，不无界重试。

## 模型与资源边界

- Atria-Dawn 按用户提供的接入约束是纯文本模型、上下文上限 512k；**不要发送图片、截图、PDF 图像或视觉工具结果**。视觉材料先由可读图的工具处理，再仅传必要的文字观察与证据路径；表格、日志和源码也应有界。
- 上下文容量不是输入目标。优先传任务摘要、精确路径、近期变化和短日志；接近上限时压缩成可核查摘要或新会话，保留真实证据文件。
- 起步只开 1 个外部陪跑；有独立任务且资源宽裕时再增加。普通开发机可把 2 个外部 Claude 调用作为保守默认上限，更多须按实际 CPU 配额、可用内存、已有 agent 与管线负载逐步验证。
- 新调用的参考暂停门槛：1 分钟 load 达实际可用 CPU 的 70%，或可用内存低于 `max(4 GiB, 总内存的 25%)`。这是起步阈值，容器配额和已有重型进程优先于宿主总核数。
- Atria 可能有明显延迟。设置合理超时和退避；慢响应不能靠叠加并发解决。`nice` 只改优先级，不提供 CPU 硬上限；重型扫描、复制、构建或训练交给有资源隔离的执行环境。

## Claude Code 接入

- 仅对子进程临时注入 `ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL`；不改 shell 启动文件、全局 Claude 登录或现有 provider。凭据放仓库外、权限受限的私有配置，示例只用 `[API_KEY]` 等占位符。
- 调用前读取 [Claude Code 与 Atria](references/01_claude_code_atria.md)：按本机 `claude --help` 核对参数、做文本探针和小范围工具验证，再启动真实任务。需要长期监控时再读 [持续陪跑](references/02_long_running_supervision.md)。
- “goal 模式”表示一个持续目标和可恢复会话，不能凭名称猜测 CLI 开关；优先使用已验证的会话续接与监督循环。

## 文件导航

| 序号 | 文件内容概览 | 关键词 | 触发时机 | 文件路径 |
| --- | --- | --- | --- | --- |
| 01 | 说明 Claude Code 使用 Atria-Dawn 的临时环境注入、私有凭据读取、文本探针、工具白名单和按 session ID 续接；给出不写入真实 key 的 Python 调用骨架，并排除图片输入和全局配置改动。 | Claude Code, Atria-Dawn, ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_MODEL, claude --help, --allowedTools, --resume, 纯文本, 凭据 | 首次连接 Atria 前必须读取；更换 Claude Code 版本或认证方式前必须读取；开放读写工具或续接会话前必须读取 | [references/01_claude_code_atria.md](references/01_claude_code_atria.md) |
| 02 | 规定长时间监督循环的有界快照、变化触发、独立锁、owner/session/进程状态、停止与恢复、资源回压和异常交接；提供中层交付字段与顶层接管条件，避免重复提交或将候选报告冒充完成。 | 监督循环, goal, snapshot, heartbeat, STOP, lock, PID, session ID, 退避, CPU, 内存, owner, candidate_ready | 启动持续陪跑前必须读取；扩并发或设计异常恢复前必须读取；重启监督进程、接管候选或判定管线完成前必须读取 | [references/02_long_running_supervision.md](references/02_long_running_supervision.md) |