# 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`） | 自动路由下所有代理仍共享一个邮箱目录 |

## 使用方法

```bash
# 应用到真实安装（幂等，自动 .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 中替换安装

```bash
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  # 集成测试
```