工作树与集成交付

最后复核：2026-10-29 证据来源：工作树入口、交付预检与 PR 绑定回归、集成事故、用户确认的存量生效判据及 0.51.0 发版复盘。

开工与职责

代码任务使用 scripts/agent_worktree.py create --agent <当前智能体> --task <任务> 的本机隔离工作树，主目录只负责集成；不使用 Claude 内置工作树机制，不跨机器复制目录。 创建、暂存、提交、集成与回收按 peach-shell-commands 取得所需权限。编辑前核对 git rev-parse --show-toplevel、注册状态和文件归属，目录存在不代表工作树有效。

单域局部任务由协调者直接完成；只有独立并行或隔离能缩短总耗时时才委派，默认最多一个工作者。只传目标、相关文件、边界与验收，不转交完整对话。状态只在完成、阻塞或至少五分钟检查点读取，不重复工作者已完成的搜索与验证。 跨对话消息只处理具体依赖，须有用户授权；不唤醒已结束对话只为报进度。工作者不自行集成、真实写入、把候选升级、修改迁移或 ADR、重启生产；协调者负责完整交付。

验证与集成

1. 在当前工作树准备独立 venv，按 docs/TESTING.md 安装锁定依赖，不复制 venv 或修改正在服务的环境。
2. 行为修改先列失败路径与影响域，通过正式入口定向验证；新增或改名测试核对域登记，不能以文件存在代替覆盖。
3. 最后交付提交完成后先运行 agent_worktree.py preflight，再运行一次 auto；未知影响、实际依赖和共享设施用 full。预检不签发测试记录。环境、编码、源码定位、记录复用和补测契约统一见 docs/TESTING.md，不逐域循环重复公共用例。
4. ready 前纳入当前 master 并验证最终内容；主线前移后交 auto 复用有效记录，不默认重跑全量。提交、声明与记录齐全后取得 ready 的实际结果。
5. 协调者执行 integrate --branch <分支>；入口核对开放 PR 的提交与工作者 HEAD、目标分支一致。等成功退出并核对主线提交，再做适用重启和运行核验。锁忙交入口等待，不手工 merge 绕过，不把分支交接当成验收完成。

主检出 master 的直接提交与手工 merge 由 hook 拒收。发布先完成 docs/TESTING.md「每次发版检查」的依赖升级批次，再通过 scripts/release_tag.py 定版、打标签与发布；更新清单不代表升级完成。发布时机采用 release_due.py 及集成入口的同一判据，不额外重复检查。

推送后核对分支头 SHA 与工作流运行，使用 gh run watch --exit-status 等待结果并继续已授权的合入；不拿旧 PR 状态或 Release 成功代替 Test。失败先取日志和制品，同提交本地通过只能说明尚未复现，重试只限失败作业并保留首败原因；不同失败反复出现时先定位，不循环重试到绿。

发版候选固定提交、清单和已验收产物。其他普通提交继续留在主线，不因主线前移重新选发布头；必须纳入的修复由发布入口重定候选并补验实际影响。标签存在、Release 创建、制品公开和镜像推送分别核验后才更新反馈发布状态。

修复的升级生效范围

• 替换代码或资源并正常刷新、重启即可生效的修复，跑对应行为回归，不强制增加迁移或新装、升级双轨检查。
• 既有数据、配置、断点、缓存或派生产物需要转换、补修、失效或重算时，复用相应机制，用临时旧样本验证并保留人工资料与个人记录。
• 刮削解析、匹配或文字处理修复须核对旧快照；旧结果会挡住修复时，在升级补修中按受影响来源和规则定向失效，验证已有回执用户仍能重采，不清空正常缓存。
• 安装器、依赖分发、数据目录或升级协议变化再验证对应制品；源码或单元回归不代替制品验收。

多分支一起合入

由一个协调会话统一测试与集成；工作树或工作者数量不决定 PR 数，按交付范围归并，同一目标先汇入一个交付分支再提 PR。先协调各任务停止本批测试、ready、integrate 与重试，核对最终提交，保留无关任务。 在专用集成工作树按无冲突、有冲突、自己的顺序合入最终提交。源码冲突只在双方保留项已明确且能全部保留时解，否则中止本次冲突合并，交原任务更新分支。 web/dist 冲突保留集成侧，源码合齐后统一构建。最后提交声明整批 README 影响，跑一轮 auto 再 ready、integrate。 全站尺寸、字号、命名或控件语义变化须检查全部相关浏览器用例；小改按影响选测。时序超时先用 agent_worktree.py processes 排查本任务重叠运行，不在相同失败状态反复全量。

暂存与提交

• 逐文件暂存后核对 git diff --cached --name-status 与任务边界，不使用目录、glob、git add . 或 git add -A。实现与对应测试原子提交。
• 一个提交只做一件能单独描述的事，长任务做完一项提交一项；web/dist 与对应源码同一提交，不另拆。
• 主题为 type(scope): 中文描述，类型以 scripts/commit_subject.py 为准。
• 本机提交者自己的交付提交带 Co-Authored-By: 工具 (实际模型版本) <厂商 noreply>，名单见 scripts/co_author.py；接力作者并列，人类共同作者保留姓名与邮箱。
• 采纳社区补丁时保留原作者为提交作者，写 Source-PR、Original-Commit，不替贡献者补 AI 署名；只有智能体改写或补充了代码时，才加它自己的署名。
• 最后提交写唯一 README-Impact，需要时带 README-Reviewed，按 docs/README_MAINTENANCE.md 核对中英文。所有 trailer 连续放末尾同一块，块内无空行，块前空一行。

回收与顶层归置

用 prune 预演，prune --apply 仅回收入口判定安全的目录。脏文件、锁定活动树、忽略的 build 文件或占用进程均保留；不能因分支已合入就解锁或删除。检查失败不绕过门槛。 residue、failed、holders、swept 以入口结果解释：只按 PID 清理本任务残留，未登记目录只自动删空目录，有文件留待确认。完成回收后核对注册列表与目录状态。 项目父目录只放 peach-app、peach-data、peach-sync、peach-worktrees 与 attic；归档按用途放 attic 子目录，不新增 peach 前缀落点。归档中的账本、复核产物与可能含凭据的工具状态仍受保护，删除单独授权。