并行子 Agent 编排（TRAE × Atom Code）

> 环境声明：本文件只描述 TRAE 环境（TRAE SOLO CN 编排 + 本地 atomcode headless CLI 执行）。
> 下文所有路径、数值、工具语义均在本环境实测标定（2026-09-27）。
>
> 其他环境的说明已分离到独立文档：references/env-workbuddy.md 描述 WorkBuddy × Atom Code 环境（上游来源环境）。
> 两个环境的数值不可互相套用——并发上限、耗时量级、MCP 可用性、技能目录都不同。跨环境使用前请先按第七节重新标定。

一、TRAE 环境事实（实测于 2026-09-27）

二、子 Agent 类型选型（决定能否接入 atomcode）

TRAE 的 Agent 工具可选 subagent_type，不同类型的工具集与权限不同，选错就无法调用 atomcode：

Explore 实测结论（2026-09-27 探针实验）：Explore 子 Agent 没有 Shell，只有 RunCommand；其角色被限定为只读模式，系统指令明确禁止创建任何文件、禁止 mkdir、禁止运行会产生文件变更的命令。探针要求它执行 atomcode 生成 5 个文件，它如实拒绝执行，产物 0 个。

> 推论：不要把 Explore 用于任何 atomcode 产出型任务。它只能做只读侦察（ls/grep/git log 类）。需要并行产出时用 general_purpose_task。

其他子 Agent 语义（TRAE 特有）：

• 子 Agent 是一次性的：每次 Agent 调用只返回单条消息；需要续跑用 SendMessage（resume）而非重新派生。
• Agent 支持 run_in_background，但编排场景下通常应同块并发、同步等待，便于统一核验产物。
• 子 Agent 拿不到主 Agent 的上下文（本环境已复核），prompt 必须完全自包含。

三、atomcode 接入形态：Bash 直调是唯一可行路径

本环境不存在封装好的 MCP 工具，且 atomcode 本身也不提供 server 模式，因此一律走 Bash 直调。

首选（也是唯一）方案：

/Users/pengyufeng/.local/bin/atomcode -C "<work_dir>" --ephemeral -y -p "<完整任务描述>"

已实测确认的有效参数：

不存在 --max-turns，传了会报错。

• 任务描述超过约 3500 字符时，先写入 <work_dir>/task.txt，再传 --prompt-file "<work_dir>/task.txt"，执行后删除该文件。
• 需要结构化证据（便于主 Agent 解析）时加 --output-format jsonl。

四、何时使用

一个复杂任务可拆成多个互不相关、各自可独立收尾的子任务，且打算交给 Atom Code 执行时。典型场景：多目标代码生成、逐模块改造、批量数据处理、多端口/多文件并行校验、多方案候选实现。

若执行层不是 Atom Code，本 skill 的通用章节（目录隔离、资源独占、证据要求、并行验证）仍可参考，但数值部分必须重新标定。

五、硬约束

六、并发与耗时实测标定（TRAE，2026-09-27）

统一任务：在当前目录生成 50 个文本文件（f001.txt–f050.txt），单次约 1 次模型往返。

先分清两种加速比口径（重要）

• 同轮加速比 = Σ(本轮各任务时长) / 本轮墙钟。同一轮内测量，内部自洽，是评价并发效率的正确指标。
• 跨轮对比 = 串行对照轮总时长 / 并发轮墙钟。受后端延迟漂移污染（同一任务单次耗时可在 19–98 s 间波动），只能作粗略参考。

实测数据

五条结论（务必按此调整预期）

1. 并发真实成立：3 路经 TRAE 子 Agent 时，三个 worker 的启动时间戳跨度仅 1.23 s，运行区间两两重叠；2 路原子并发启动跨度 0 ms。
2. 执行层并发效率随并发数提升，未观察到饱和：1.54× → 2.67× → 3.44×（2/3/4 路）。4 路是本次测到的最大级别，全部成功，上限未测出。
3. 但"最慢 worker 决定总时长"：3 路经 TRAE 编排那一轮里，两个 worker 只用 32 s，第三个用了 98.4 s，总墙钟被它拖到 99.6 s（同轮加速比仅 1.63×，明显低于原子并发的 2.67×）。并发数越高，单个慢 worker 对总墙钟的支配越强。
4. 单任务耗时方差极大（19–98 s，约 5×）：同一任务、同一机器，仅因调用时机不同就相差数倍。主导因素是后端模型服务延迟，不是本地并发或 CPU。因此不要照搬任何"按任务类型给固定超时"的表格。
5. 子 Agent 自报耗时不可信：时间、条数这类数据只认落盘证据，不认自报。

七、重新标定（换机器 / 换模型 / 换 CLI 时）

本技能附带可执行脚本，把下述步骤自动化：

~/.trae-cn/skills/subagent-orchestration-cn/scripts/calibrate_concurrency.sh <N> ["任务描述"]
# 例：./calibrate_concurrency.sh 3

脚本会跑 N 路 atomcode 并发，输出每个 worker 的 t0/t1/时长/退出码、启动跨度、总墙钟、串行理论、同轮加速比，并给出区间重叠判定（真并行 / 非并行），退出码 0=真并行、1=非并行。

手工标定步骤：

1. 单跑一个典型任务，重复 3 次取中位数记录墙钟 T（单次不可信，方差太大）。
2. 按 2 → 3 → 4 逐级跑脚本加压，每级用区间重叠判定是否真并行。
3. 记录每级同轮加速比；出现"区间不重叠"或"调用失败"的级别即为该环境的实际上限。
4. 并发数取"上限"与"加速比边际收益明显下降点"中的较小者。

八、执行流程

1. 拆分：把总任务拆成互相独立、可独立验收的子任务，逐条写清交付物（具体到文件名与验收标准）。
2. 分配：为每个子任务指定唯一的绝对 work_dir（建议带任务名或时间戳），并明确独占端口。
3. 并发启动：在同一个消息块内发出全部 Agent 调用，它们会并发执行；数量 ≤ 3。
4. 收集：等全部返回后，核验产物隔离（各目录只含约定文件）。
5. 收尾：检查端口监听（lsof -nP -i :PORT）、残留进程（pgrep -fl <关键词>）、临时文件，确认无残留。

九、具体编排示例

主 Agent 侧，在同一个消息块内发出多个调用（以下为结构示意，subagent_type 必须为 general_purpose_task）：

Agent(description="worker w1", subagent_type="general_purpose_task",
      prompt="<自包含任务描述，见下>")
Agent(description="worker w2", subagent_type="general_purpose_task",
      prompt="<自包含任务描述，见下>")
Agent(description="worker w3", subagent_type="general_purpose_task",
      prompt="<自包含任务描述，见下>")

子 Agent prompt 必须自包含——子 Agent 拿不到主 Agent 的上下文。一个实测可用的最小骨架：

你是并行编排的第 N 号 worker。只做本任务，不要读写其他 worker 的目录。

专属工作目录（只允许在此目录内操作）：/abs/path/wN

步骤：
1. 用 Shell 执行：python3 -c "import time;print(int(time.time()*1000))" > /abs/path/wN/t0
2. 用 Shell 执行（核心任务）：
   /Users/pengyufeng/.local/bin/atomcode -C "/abs/path/wN" --ephemeral -y -p "<完整任务描述>"
   （调用 Shell 时把 timeout 显式设为 300000 ms）
3. 用 Shell 执行：python3 -c "import time;print(int(time.time()*1000))" > /abs/path/wN/t1
4. 用 Shell 执行：ls /abs/path/wN | wc -l

汇报（3 行以内）：t0=<数字> / t1=<数字> / 文件数=<数字>

完整模板见 references/prompt-templates.md。

十、超时设置建议（按实测校准）

本环境实测单任务 19–98 s，TRAE Shell 工具默认超时 120 s（2 min），对最坏情况余量不足。

不要为省事设成 30 s 级——实测最坏值已达 98 s。

十一、验证并行是否真的发生

需要给出可证伪结论时，用时间戳区间法（不要凭"同一消息块发出"就断言并行）：

1. 要求每个子 Agent 在开始与结束时各写一次时间戳：
   bash python3 -c "import time;print(int(time.time()*1000))" > "<work_dir>/t0" # 开始 python3 -c "import time;print(int(time.time()*1000))" > "<work_dir>/t1" # 结束
2. 读取各 t0/t1，判断区间是否重叠：串行则区间严格首尾相接；并行则重叠。
3. 辅助判据：总墙钟 ≈ 单次耗时（并行）还是 ≈ 各次之和（串行）。

> macOS 的 date 不支持 %3N，会原样输出字面量 3N，精度只有秒。需要毫秒必须用上面的 python3 -c "import time..."。或直接用 scripts/calibrate_concurrency.sh。

十二、子 Agent 行为基线（TRAE 实测）

本环境已复核/证伪的行为：

十三、常见坑

• 子 Agent 类型选错：用 Explore 调 atomcode 会被只读限制拒绝，且它自报"工具链已配置好、只是我被限制"——容易误判为环境问题。
• 汇报格式不严格：要求的结构化输出可能被改写成自然语言，解析要容错。
• 任务描述里的事实断言必须为真：发出前先 cat/ls 核实，否则子 Agent 会照着不存在的目标执行，你拿到错误产物 + 一份诚实的投诉。
• 交付范围会扩容：用显式边界写死；收尾按文件模式全盘扫，不只扫 work_dir。
• 数量与校验值易冲突：写校验条件时先自洽。
• 并发任务若各自拉起服务，必须指定不同端口，并要求验证完立即停止。
• 忽略"成功"里的隐性降级（子 Agent 自述改用本地工具兜底），要追问是否走了备选路径。
• 子 Agent 常报告"目标目录不存在"并自行创建；给出明确指令并事后核对实际路径。
• 单个慢 worker 会拖垮总墙钟：编排后若总时长远超预期，先查是不是某一个 worker 的耗时离群，而不是怀疑并发失效。

十四、TRAE 环境适配要点

1. 技能必须扁平化安装。TRAE 只扫描 <技能根>/<技能目录>/SKILL.md 这一层，skillhub install --dir ~/.trae-cn/skills 产生的 @命名空间/<slug>/ 嵌套结构不会被加载。安装后须把内容复制为 ~/.trae-cn/skills/<slug>/。
   - 佐证：@user_b833da3a/solo-architect（frontmatter 合法）自 2026-08-30 安装后从未出现在任何会话的可用技能列表。
2. 技能列表按会话加载，新装/改动技能需新开会话才生效。
3. 子 Agent 派生方式：TRAE 用 Agent 工具 + subagent_type，编排并行任务必须选 general_purpose_task（详见第二节）。
4. 子 Agent 是一次性的：每次 Agent 调用返回单条消息；需要续跑用 SendMessage（resume）而非重新派生。
5. 支持后台执行：Agent 的 run_in_background 可让子 Agent 后台跑；但编排场景下通常应同块并发、同步等待，便于统一核验产物。
6. 无 MCP 备选路径：本环境无 run_coding_task，不要引用它。

十五、文档与工具

十六、速查清单

• [ ] 子任务独立且可独立验收
• [ ] 每个子任务有唯一 work_dir（绝对、唯一）
• [ ] subagent_type 用 general_purpose_task（不是 Explore）
• [ ] 编排并发数 ≤ 3（Explore 类受平台硬约束 ≤ 3）
• [ ] 子 Agent prompt 完全自包含（子 Agent 看不到主 Agent 上下文）
• [ ] 走 Bash 直调 atomcode（-C ... --ephemeral -y -p ...），不引用不存在的 MCP
• [ ] 已用绝对路径指定 atomcode，且未传不存在的参数（如 --max-turns）
• [ ] 子 Agent 内调 atomcode 的 Shell 命令 timeout 设为 300000 ms
• [ ] 子 Agent 已被告知独立目录与独占资源
• [ ] 子 Agent 需汇报关键证据（时间/条数只认落盘，不认自报）
• [ ] 任务描述中的事实断言已逐一核实
• [ ] 交付范围已显式写死（只输出哪些、不得新建哪些文件）
• [ ] 汇报格式解析已容错（子 Agent 可能改写格式）
• [ ] 已核验产物隔离与资源残留（按文件模式全盘扫，不只扫 work_dir）
• [ ] 加速比按同轮口径评估；总时长异常时先查单个慢 worker