# 多子代理并行开发的经验记录(2026-09-27/28,v0.1 → v0.2.1)

供后续派活时直接引用。每条:现象 → 代价 → 规则。

## 工作区与提交
1. 多个子代理共用一个工作树,`deno fmt`/`biome --write` 全仓跑会改到别人未提交的文件 → 三次发生,合并时要人工核对 → **规则**:只对自己改动的路径跑格式化;禁止全仓 `--write`。
2. `git add -A` 或在别人暂存后 `git commit` 会把别人的改动带进自己的提交 → 一次文案改动被并进文档提交 → **规则**:只 `git add <自己的路径>`;提交前 `git status` 核对。
3. 跨模块的共享文件(`routes.ts`、`nav.ts`、`layout.tsx`、`api.ts`、`modules/index.ts`、测试表清单)是冲突热点 → **规则**:指定唯一 owner,其他人只用 Edit 追加一行且先重读;或先由一路把骨架/契约提交再并行。
4. 大改动用独立 worktree + 分支 + 独立测试库(C2-A 做法)最干净;合并由协调者做 → **规则**:改动面大或需要长时间的路,默认 worktree;迁移编号在合并时重排。
5. 子代理"越界"改了范围外文件很常见(为了让测试过)→ **规则**:prompt 里明确"越界改动要在汇报里列出",协调者合并时逐条看。

## 测试与 CI
6. 多路同时对共享开发库跑 PG 测试会互相删 schema("schema 不存在")→ 根因是迁移器扫全库 schema(W10 修),但并发仍会拖慢和偶发 → **规则**:每个测试文件唯一 schema + 只看目标 schema;并行子代理各自起临时 PG 容器(端口 5544x)跑 ci。
7. 全量 ci 从 75s 涨到 450s(PG 测试串行化 + 数量增长)→ **规则**:子代理只跑相关包/文件测试,全量 ci 由协调者或收尾那一路跑;考虑把 e2e 拆成单独任务。
8. 编译产物与源码运行不一致:`deno compile --exclude-unused-npm` 漏掉 MCP SDK 子路径模块,ci 全绿但镜像启动即崩 → **规则**:ci 必须包含"编译产物启动自检";打 tag 前先起一次容器。
9. 隔离 worktree 里 ci 全绿 ≠ main 全绿(别人未提交/未合入)→ **规则**:合并后协调者再跑一次全量 ci 才打 tag。

## 设计与文档
10. 并行实现前没先统一类型/契约,三路各映射一套(W1 的 domain/contracts/agent 三套能力定义)→ 多花一轮 W2-0 打底 → **规则**:先打底(契约 + 模块骨架 + 映射包),再并行。
11. 前端按"未提交的后端契约"猜着写(FE-5 引用 fe3-web 分支文件、W3-3 本地镜像 schema)→ 集成时返工 → **规则**:契约先行 20 分钟内提交;前端只依赖已合入的 contracts。
12. 用户品味类要求(文案、IA)要尽早定规范并机器检查(token 守卫、标点脚本、术语表)→ 后补代价大(两轮 660 处 + 828 处)→ **规则**:新页面开发前先读 glossary 与 human-copy 规范,ci 里 `check:copy --strict`。
13. 每个子代理的结论必须落文档(runbook / porting 账本 / plan),协调者不依赖子代理对话记录续活 → **规则**:prompt 末尾固定要求"更新对应 runbook 与状态标注"。

## 参考实现的使用
14. "照抄 MP"要精确到函数级对照与差分测试(标题识别 216 例、过滤规则 2112 例、缓存语义),否则会"自己发明" → **规则**:移植类任务必须交付 porting 账本 + 差分快照,偏离只允许记录在案的类别。
15. 上游许可要先核(MovieClaw 只有 v0.27.0 及之前是 MIT;MP 站点定义加密;@openworkflow/dashboard 是 Proprietary)→ **规则**:引入任何上游资产前先出许可结论。

## 部署与真机接入(2026-09-28/29 补充)
16. `deno compile` 产物与源码运行不一致(重复依赖导致嵌入错误副本)→ **规则**:ci 必含编译产物启动自检;打 tag 前跑一次容器。
17. `docker compose up --build` 会重建所有带 build 的服务(camofox 要下 632MB)→ **规则**:只重建改动的服务 `--build app`;大镜像本地构建一次后用 `image:` 引用。
18. 容器访问宿主代理:代理只监听 127.0.0.1、ufw 挡容器→宿主、compose 自动分配 192.168.x 网段不在放行范围 → **规则**:socat 中继绑 docker0 地址 + 固定 `UMT_SUBNET` 在放行网段内;防火墙改动由用户执行(自动模式拒绝削弱安全的操作)。
19. 在用户的栈上做真机验证要"只读 + 事后清理",凭据只放 git 忽略的 `.local/`;子代理误清用户配置(Brave Key)要在集成时恢复 → **规则**:prompt 明确"不要改用户已有配置",验证造的数据/设置逐项还原。
20. 视觉/桌面类能力必须先做 P0 门槛验证(同会话、HTTPS 前提)再投入实现 → 本轮 P0 通过后 8 人日估算的工作一晚完成。
21. 多个子代理共用一个工作区和 git 暂存区并行提交:一路用 plumbing(自建 index / commit-tree)从旧快照提交,把另一路刚提交的文件回退;另一路 `git commit` 时暂存区里是别人的半截状态,又把前一路整体撤掉;文档提交顺带带走了别人暂存的代码(v0.2 收尾 `901b01d` / `28974d1` / `ac47867`,见 08-v0.2-closeout「INT-2 集成记录」)→ **规则**:并行子代理一律各自独立 worktree + 分支(`git worktree add ../wt-<任务> -b <任务>`),只在自己的 worktree 里 `git add` / 提交,不用 plumbing 改共享 index;协调者按顺序合并到 main(迁移编号在合并时定),合并后跑全量 ci。共享工作区里只允许一路写。
22. 清理脚本 `--apply` 前没看 dry-run 清单(子代理的 dry-run 只在测试库跑过)→ 在用户库删了 92 个"孤立单元",其中含 TMDB 季集账本单元,需回刷恢复 → **规则**:任何对真实库的删除类脚本,先对真实库跑 dry-run 并由协调者逐类目过目再 `--apply`,即使用户授权"直接干";删除判定必须按来源区分(临时 vs 元数据来源),默认只删临时数据。
23. **主工作区跑过 `deno install` 后先 `git status`**:宿主机 `deno install` 会把 `deno.lock` 改写(删掉一批 npm 条目),而镜像构建 `COPY . .` 带着工作区里的锁文件跑 `deno install --frozen`,直接失败。构建前 `git checkout deno.lock`(或确认工作区干净)再 `docker compose build`。(v0.3.2 发布时遇到)
24. **主工作区不留常驻进程**:子代理在主工作区起的 `deno task dev`(--watch)结束后没停,挂了两三天,每次改文件都重写 `deno.lock`(即 #23 的根因)。派活时要求子代理结束前 `pkill` 自己起的 dev 进程;协调者发布前 `pgrep -a deno` 看一眼。

## 发布与检查(2026-10-02 补充)
25. v0.3.8～v0.3.13 六个版本都由未提交工作区构建部署,发布记录写"检查通过",实际 agent / db / contracts 测试与类型检查一直是红的:`deno task test` 在第一个失败的包就停、后面的包根本没跑;连不上库时数据库用例静默跳过也算通过;开发库落后 9 个迁移没人发现 → **规则**:发布只走 `deno task release`(工作区不干净直接拒绝,tag 即镜像版本);检查只认 `deno task test:all` 的汇总(逐包跑完、连不上库即失败);拉代码后 `deno task dev:up`。
26. 用 `deno task lint | tail -1 && git commit` 做提交前检查:管道的退出码是 `tail` 的,lint 失败照样提交,`b61335e` 因此带进了一批格式问题 → **规则**:检查命令不接管道,输出重定向到文件再看退出码(`cmd > log 2>&1; echo $?`)。