xiaomingx/mimofan/parallel-agent-lock-guard

并行 Agent 锁竞争规避（parallel-agent-lock-guard）

目的

多 agent 并行开发时，多个进程会抢同一份共享可变状态（cargo registry、git index、npm 全局 cache、共享文件），触发 file lock 串行化甚至死等。本 skill 提供分层隔离方案与可落地配置，让并行 agent 互不阻塞。

何时使用

• 用户启动/规划多 agent 并行开发框架（monorepo、code harness agent、Claude Code 多 agent 插件）。
• 出现 Blocking waiting for file lock on package cache、git index.lock 冲突、文件被覆盖/读到半成品。
• 用户问"并行 agent 锁竞争怎么解决""并行构建如何隔离""如何避免下次锁竞争"。

锁竞争分类（4 类，按频率）

最佳实践（5 层，MECE）

A. 进程级——下载与编译分离

• 所有写 registry/cache 的操作（cargo fetch / npm install / cargo install）作为全局一次性预热，跑在 agent 并行启动之前。
• 并行阶段所有 agent 用 --offline / --locked / --frozen，只读 cache，不碰写锁。
• install 类工具（cargo-audit 等）禁止与 build 并行，要么预装进基础镜像，要么放串行 phase。

B. 仓库级——git worktree 隔离工作副本

• 每个 agent 一个独立 worktree，彻底隔离 index.lock / refs，互不干扰。

C. 文件级——按域分片所有权 + 写队列

• monorepo 按 crate/package 给 agent 分配目录所有权，不交叉写。
• 任何必须写共享资源（git push、写汇总文件）的操作走 harness 的单一串行队列。

D. 缓存级——sccache 是解药不是问题

• sccache 原生并发安全。配置 SCCACHE_DIR 持久化可放大命中、避免重复编译，反而缓解竞争。

E. 调度级——重试退避

• 编译类 job 加重试退避（如 3 次重试 + 30s sleep），吸收瞬时锁等待。

可执行配置

1. 预热 + 离线只读：运行 bash scripts/warm-cargo-parallel.sh <project_dir>（等价于 cargo fetch --locked），之后各 agent 用：

``bash CARGO_TARGET_DIR=./target-agent-$AGENT_ID \ CARGO_NET_OFFLINE=true \ cargo build --locked --offline --target $TARGET ``

1. git worktree 隔离：

``bash git worktree add -b agent/$AGENT_ID ../agent-$AGENT_ID main cd ../agent-$AGENT_ID # 独立 index/working tree，零锁竞争 ``

1. 彻底隔离（备选）：为每个 agent 设独立 CARGO_HOME——registry cache 完全不共享，代价是重复下载，仅在无法预热时用。
2. sccache 持久化：确保 SCCACHE_DIR 在 agent 间共享且持久（mimofan 已配置 ~/.cargo/config.toml 并关闭 incremental）。
3. install 串行化：cargo-audit / 其他 cargo install 工具移到串行 phase 末或预装。

针对 mimofan 的具体约定

• 项目是 cargo workspace（resolver=2、edition=2024），多 crate 用 .workspace=true 复用中央依赖。
• 已配 sccache，实测命中 ~96%，二次重建仅重编 1 crate——保持 SCCACHE_DIR 持久以延续收益。
• 真实案例：agent-mimofan 曾并行 cargo build + cargo install cargo-audit，互相阻塞 ~13min 于 package cache 锁。规避=build 前先 cargo fetch --locked，install/工具串行或预装。
• 依赖多版本分叉（starlark / portable-pty 等传递依赖）属 semver 分叉，不是锁竞争，不在本 skill范围；勿为消除重复而强制统一版本。

工作流（落地步骤）

1. 并行启动前：在该仓库跑 bash scripts/warm-cargo-parallel.sh <project_dir>（= cargo fetch --locked）完成 registry 预热。
2. 给每个 agent 分配独立 git worktree + 独立 CARGO_TARGET_DIR。
3. 并行阶段：各 agent CARGO_NET_OFFLINE=true cargo build --locked --offline --target <t>。
4. install 类工具移到串行 phase 或预装进基础镜像。
5. 写共享资源（git push、汇总文件）走 harness 单一串行队列。

反模式（不要做）

• 不在并行区跑 cargo install / cargo update（写 Cargo.lock + registry）。
• 不让多 agent 共享同一 worktree 做 git 写。
• 不要为"消除重复依赖版本"而强制统一版本——那是传递依赖分叉，风险高、非锁竞争。