pi-swarm-fix — mailbox & roleName 修复工作区

对 @gjczone/pi-swarm@0.9.5（npm dist 产物，上游源码私有不可得）的修复与测试。 用途：让 pi-swarm 的自组织讨论（mailbox 模式）可靠可用。

修复的缺陷（4 个补丁）

补丁	文件	缺陷	后果（修复前实测）
P1	dist/shared/profiles.js	deriveAgentName 对共享 profile 一律返回同名 → 所有代理共用同一 roleName	邮箱 task 目录只有一个 → 多轮询器竞态 → 10 次重复投递 / 消息丢失（archive-81 研讨实测）
P2	dist/swarm/coordinator.js	SwarmCoordinator 完全没有 mailbox	非阻塞模式无法自组织讨论；主管中断即讨论夭折
P3	dist/shared/spawner.js	注入的邮箱说明不给 roleName 和文件路径	代理靠猜路径 → 写进无关 run 目录，消息静默丢失（协调器实测 3/3 写错位置）
P4	dist/swarm/tool.js + coordinator.js	auto-route 匹配到文件代理后 roleName 不更新（Profile: auditor 但 Role: general-1）	自动路由下所有代理仍共享一个邮箱目录

使用方法

# 应用到真实安装（幂等，自动 .bak 备份；--revert 还原）
./scripts/apply-patch.sh

# 单元测试（node:test，13 项）
node --test

# 集成测试（起 headless pi 新进程加载补丁代码）
./scripts/int-test-a-unique-rolenames.sh        # 阻塞 Swarm：唯一 roleName + 无重复投递
./scripts/int-test-b-coordinator-mailbox.sh     # Coordinator + mailbox

注意：已运行的 pi 进程内存中仍是旧代码，需重启 pi 或起新进程。

集成测试证据（2026-08-08，headless pi + deepseek-v4-flash）

测试	场景	结果
A	阻塞 Swarm，共享 profile，3 代理 + mailbox	✅ general-1/2/3 目录唯一；3 条消息全投递；"重复"仅为广播扇出（root+每收件箱各 1 份），零竞态重复、零丢失
B	SwarmCoordinator + mailbox: true（P2 新能力）	✅ 3 代理完成；3 条消息；每收件箱恰 3 条；messageId 唯一
C	auto-route + 4 个文件代理（P4）	✅ auditor-1 / designer-2 / judge-3 / integrator-4，Profile 与 Role 一致
D	回归：不带 mailbox 的 Swarm / Coordinator	✅ 均 completed，原功能无损
E	真实两轮讨论（读→回应）	✅ 3 条初始观点 + 3 条交叉回应，每收件箱精确收到 6 条

修复前对照（archive-81 研讨 run）：12 次投递仅 2 条唯一消息（10 次重复）；1 个代理只见到 1 位成员；协调器代理 3/3 把消息写进错误目录。

发布状态（2026-08-08 已发布 ✅）

• npm：pi-swarm-fix@0.9.6 → https://www.npmjs.com/package/pi-swarm-fix
• GitHub：https://github.com/ZCasual/pi-swarm-fix
• 联系作者：CBAT-W/tmp/email-to-gjczone.md（gjczone/pi-swarm 为私有仓库，无法直接 PR，需邮件联系）
• 本地补丁始终可用：./scripts/apply-patch.sh（幂等，升级后重跑即可）

在 pi 中替换安装

pi uninstall npm:@gjczone/pi-swarm          # 先移除原版（避免工具重复注册）
pi install npm:pi-swarm-fix                 # 安装修复版

注意：本机 npm registry 配置为 npmmirror 镜像，新包同步可能有几分钟延迟； 若安装时 404，等待同步或临时用官方源。

结构

dist/                  # 0.9.5 npm 产物 + 修复
patches/               # 0001-0004 补丁（git diff 格式）
tests/                 # 单元测试（node:test）
scripts/apply-patch.sh # 同步补丁到真实安装
scripts/int-test-*.sh  # 集成测试