# 派活 ## 准备工单 在 `.team/tasks/T-xx/task.md` 写工单，第一行是一句能当标题的话（如 `# 核实 scheduler 的 bootstrap Secret`）。把需要的背景随任务交给 worker，不要求它重读主持人的对话历史： - 目标与完成标准，已有结论/实验，哪些问题仍待解决。 - 工作目录（绝对路径）、允许修改的路径或"只读"、需要保持的接口。 - 共用工作树时附上派发前的 `git status --porcelain` 输出作为基线。基线里有未提交、且本任务允许修改的文件（如上一阶段已验收的产物）时，先复制到 `.team/tasks/T-xx/baseline/`，审阅时用它对比改动。 - 产物路径和长度要求。 - 验收方式及已知基线：能机器检查就给命令；调研/审查则写明需要哪些依据，由主持人核查。 不要用 `git status` 或"文件非空"的成功证明代码/报告正确。完整测试较重时选与改动相关的检查。 ## 批次清单 同一交付目标下需要汇总的多项任务按一批管理，例如一次 CR 的多个审查维度。单个任务、互不相关的独立交付无需建批；用户明确要求分项交付时遵从其要求。协商沿用讨论目录，不另建批次。 第一次派发前写 `.team/batches/B-xx/batch.md`，列出全部计划项。清单只由主持人维护： ```markdown # 批次 B-xx - 交付目标：本批共同要交付的结果 - 基线与范围：审查的提交/diff 或其他输入范围 - 批次状态：进行中 - 最终交付：未交付 | 计划项 | 目标 | 工单 / agent ID | 结果路径 | 审阅结论与依据 | 处置 / 下一步 | | --- | --- | --- | --- | --- | --- | | A | 检查逻辑 | 未派发 | 未回执 | 未审阅 | 待派发 | | B | 检查测试覆盖 | 未派发 | 未回执 | 未审阅 | 待派发 | ``` - "批次状态"取"进行中 / 已结束"，有待办就保持进行中。"最终交付"取"未交付 / 已交付 / 部分交付 / 阻塞"，附报告路径或结论摘要。 - 每张工单写明清单的绝对路径、对应计划项及"worker 不修改清单"，使主持人在上下文压缩后能从文件恢复整批状态。 - 追加任务先加入清单再派发。预期成员以清单为准，不以已回来的回执数量判断是否收齐。 ## 派发 在同一条消息里发出多个 Agent 调用即为并行。每个调用： - `description`：3～5 个词的任务名。 - `prompt`： ``` 你是 worker。工单：。交付约定：。先读这两个文件再开始。 ``` 其余内容都在工单里，不在 prompt 里重复。 - 改代码且项目是 git 仓库时加 `isolation: "worktree"`，见下节。 - 记下返回的 agent ID，批次任务填进清单。 ## 隔离与整合 **worktree（并行改代码的默认选择）** - worktree 建在会话启动目录所在的仓库上。要隔离的仓库不是这个仓库时，改用共用工作树。 - worktree 从当前提交创建，不带主工作树里未提交的改动。任务依赖未提交改动时，二选一：请用户先提交，或改用共用工作树并分好文件。主持人不擅自提交。 - 回收时 worker 的改动留在 worktree 里，未提交。主持人在 worktree 中执行 `git add -A` 后，把 `git diff --cached --binary HEAD` 的输出存为 `.team/tasks/T-xx/change.patch`，先审阅这份 patch。 - 审阅通过后在主工作树先运行 `git apply --check `，通过再运行 `git apply `，改动保持未提交、留给用户检查。主工作树有未提交改动时 `--3way` 会失败，所以不用它。check 不通过就停下报告冲突的文件，不强行解决他人的改动。 - worktree 里的 `git status` 只含该 worker 的改动，范围检查是准确的。 - 统一交付后用 `git worktree remove` 移除本批创建的 worktree，patch 文件保留作为记录。用户要求保留时跳过。 **共用工作树** - 适用于非 git 项目、依赖未提交改动的任务，以及只读任务。 - 先分配文件责任，同一文件不交给两个并行 worker。 - 范围检查是事后核对，分不清改动是谁做的：拿基线比对，先排除他人的同时改动，再判断是否越界。 ## 回答提问 worker 以 `[question]` 结束时，任务暂停等答复，不算回执： 1. 读 `question-N.md`。批次任务把该项标为"待答复"。 2. 能从工单、已审阅产物、仓库或资料确定答案的，主持人直接答，并写明依据。 3. 涉及用户偏好、授权，或主持人掌握的信息不足以判断时，用 AskUserQuestion 问用户：选项取自 worker 的候选答案，worker 的建议放第一位并标"(推荐)"，description 写对交付的影响。同时有多个 worker 要问用户时，合并到一次 AskUserQuestion（最多 4 个问题）。 4. 写 `answer-N.md`：答案、来源（主持人判断及依据 / 用户回答）、对工单的修改。 5. SendMessage 给原 agent ID：`读 后继续 T-xx，按原契约回执`。 提问不计入返工轮次。同一任务提问超过 3 次，说明工单背景不足或拆分不当，主持人考虑重写工单或接手。 ## 回收与返工 subagent 完成会自动通知，通知只是线索： 1. 读 `reply.md` 和 `verify.log`。worker 报告"未能写入回执文件"时，主持人把内容代存到 `reply.md`。 2. 按风险查看关键 diff、证据，必要时独立重跑验收。`accept=none` 不等于失败，只是没有机器验收；`accept=ok` 也不能代替对结论的判断。 3. 批次任务把审阅结论、依据和下一步更新到清单对应的计划项。 需要返工时： - 先写 `.team/tasks/T-xx/followup-N.md`，写明具体失败条件与期望；批次任务先把该项改为"待返工"。 - 用 SendMessage 发给原 agent ID：`请读 ，按原契约更新 reply.md`。SendMessage 不可用或原 agent 已结束时，派一个新 worker，prompt 同时给出 task.md 和 followup 的路径。 - 依赖任务完成后让 worker 补充内容（如补上派发时还不存在的功能说明）用同样的方式发 followup，但不是缺陷，不计返工轮次。 - 返工沿用两轮上限，换一条消息不重新计数；到上限后说明剩余问题。旧的 done 回执不能证明返工完成，要核对本轮产物。 - 原 worker 无法继续时，可为同一计划项改派新工单，在清单里保留旧 ID 和替代关系。每项最多改派一次；再次失败由主持人接手或记录缺口。 ## 统一交付 收到结果、审阅完成、明确处置是三件事。不能因为先回来的几份都通过就提前结束整批。 - **未收齐或未审完**：继续推进能做的事；只剩等待时结束 turn。普通回执只更新清单，不逐份向用户报告；用户问进度、出现需要用户处理的阻塞或重大风险时再说明。 - **失败或阻塞**：审阅原因，再决定在范围内返工、主持人接手，或记为缺口。不默认当成功，也不把能自行处理的问题交给用户拍板。 - **收尾前逐项核对**：每个计划项都有明确处置及依据（采纳、不采纳、接手完成、记为缺口），没有待派发、待审阅或进行中的返工。存在缺口只能按部分/阻塞交付说明。 - **交付**：结合各项证据形成主持人自己的判断。CR 类按问题去重、核验冲突、按影响排序，保留来源及覆盖缺口，不依次拼接 worker 报告。更新清单的"最终交付"，无待办时把批次状态改为已结束。 - **迟到或重复的结果**：按任务 ID 识别。已交付后仍审阅新结果，影响原判断时给出明确修订。