> **迁移注记（2026-09-13）**：本文件自 protocol-compiler 迁入灵枢大脑仓；蜂群子系统现为 `swarm/` 包（大脑核心内部能力）。

# 蜂群多智能体 · 功能说明 v0.6

> 对应 `swarm/rust_runtime/src/swarm.rs`（蜂群协调器）+ `swarm/rust_runtime/src/health.rs`（健康评分）+ `swarm/rust_swarm.py`（Python 封装）。
> 荣 2026-09-12 启动「多智能体高并发」长期任务；B3 裁定甲案（自研传输层 Gossip + 评分自算，可复算路线）。底座不换，纯 std 零外部依赖。
> 修订 v0.6.1（2026-09-13）：integrity 因子接通真实验签统计（不再硬编码）；§五上手示例重写为五步照抄可跑。

## 一、架构总览

```
run_swarm(exe, cfg, rounds, wal_path)
  ├─ WAL 重放（有快照→续跑；无快照→从轮 1；坏尾 HMAC 守卫截断）
  ├─ 拓扑角色推导（derive_role）
  ├─ 每轮（BSP 超步）：
  │    compute：轮内实例并行（thread::scope，一实例一线程一管道）
  │    apply  ：屏障后按声明序处理——信任提交/ACK/路由产出（确定性保持）
  │    落盘   ：事件行 flush → 轮末快照行 sync_all（快照永不先于其写入落盘）
  └─ 聚合报告：信任 T_avg/T_min/T_variance/T_alignment + health 四因子 + gossip 对账 + watermarks
```

实例 = `protocol_vm --serve` 子进程（进程隔离，stdio 管道）；**符号表不跨轮持久**，跨轮数据只能走消息（消息传递纯净性——无共享内存）。

## 二、七项能力

| 能力 | 入口/字段 | 语义 |
|---|---|---|
| 1. 断点恢复 | 自动（WAL 同路径重入） | 轮末快照 = 提交点；快照后未提交轮次整体回滚重跑；已完成 ≥ 目标 → 幂等聚合；坏尾（半行/篡改）HMAC 守卫截断 |
| 2. 并行超步 | 自动 | 轮内实例并行执行，join 即屏障；事件序/WAL 序与串行版逐位一致 |
| 3. 健康评分 | 报告 `health` | `score = 0.4×成功率 + 0.2×在线率 + 0.2×(1−威胁率) + 0.2×integrity`；integrity = 验签通过率 × gossip 覆盖率 |
| 4. Gossip 广播 | `Route.to = "*"` | fan-out 至除源外全部实例；`gossip_consistent` = 全目标实收水位相等（对账） |
| 5. 拓扑 | `Config.topology` | `hierarchical`（首实例 queen）/ `centralized`（coordinator）/ `mesh`（全 peer）；缺省保持用户 role |
| 6. 版本化信箱 | 报告 `watermarks`/`global_seq` | 每条投递带全局单调 seq；ACK 携带消费水位（在 HMAC 签名串内）；恢复场景 seq 不断档 |
| 7. 实例容错 | 自动 | 管道断裂 → 同线程重建进程重跑该轮（轮次号幂等）；重试仍败 → dead 退场（outcomes 记 None，蜂群继续） |

## 三、配置（swarm.json）

```json
{
  "algo": "rust_swarm-0.1",
  "shared_secret": "共享密钥（HMAC-SHA256 签名）",
  "rounds": 5,
  "topology": "hierarchical",
  "instances": [
    {"id": "实例甲", "role": "记录", "trust": 0.1}
  ],
  "routes": [
    {"from": "实例甲", "event_type": "信任同步", "to": "实例乙", "payload": "@trust", "level": 0}
  ]
}
```

- `payload` 中 `@trust` 占位运行时替换为源实例终态信任值
- `to: "*"` = gossip 广播（除源外全部实例）
- 生成：`make_swarm_config(instances, routes, rounds, shared_secret, topology="")`

## 四、报告字段（report_json）

| 字段 | 内容 |
|---|---|
| `rounds` / `instances` / `events` / `acks` | 规模计数 |
| `trust` | `T_avg` / `T_min` / `T_variance` / `T_alignment`（0-1 夹取，error 终态沿用上轮） |
| `final_states` | 每实例最后轮终态（含 `trust` 与 `symbols`） |
| `health` | 每实例 `{score, success_rate, uptime_rate, threat_rate, integrity_rate}` |
| `gossip` / `gossip_consistent` | gossip 水位表与对账结果 |
| `watermarks` / `global_seq` | 实例消费水位与全局消息 seq |
| `topology` / `roles` | 生效拓扑与角色表 |

WAL（events.jsonl）行格式：`{"ts","from","to","type","round","level","hmac","payload"}`，其中 `type="__snapshot__"` 为轮末快照行。验签：`verify_wal_signatures(wal, secret)`（快照行验签但不计入事件数）。

## 五、Python API（swarm/rust_swarm.py）

最小可运行五步（与 `tests/test_swarm_health.py` 同构，照抄即可跑）：

```python
from swarm.rust_codegen import generate_rust_project
from swarm.rust_swarm import (make_swarm_config, run_swarm,
                              verify_wal_signatures)

SOURCE = """问曰：如何验证信任？
答曰：信任值大于0.7。
术曰：
1。道 新信任路径；
2。德 0.3；
3。若 信任值 大于 0.2，则 德 0.5；
4。止。
"""

gen = generate_rust_project(SOURCE, "proj")      # ① 生成 Rust 项目（proj 目录由本步创建）
cfg = make_swarm_config(                          # ② 蜂群配置（rounds 在此声明）
    instances=[{"id": "实例甲", "role": "记录", "trust": 0.1},
               {"id": "实例乙", "role": "验证", "trust": 0.2}],
    routes=[{"from": "实例甲", "event_type": "信任同步", "to": "实例乙",
             "payload": "@trust", "level": 0}],
    rounds=3, shared_secret="密钥", topology="hierarchical")
rr = run_swarm("proj", cfg, wal_path="events.jsonl")  # ③ 运行：rr["ok"]/["report"]/["wal"]
v = verify_wal_signatures(rr["wal"], "密钥")          # ④ WAL 验签：v["all_valid"] / v["total"]
# ⑤ 增量重跑：同 config + 同 wal_path 重入即自动续跑（应用层无需感知）
```

`run_swarm` 完整签名：`run_swarm(project_dir, config, wal_path="events.jsonl",
timeout=120, pbc_path=None, exe=None)`——`project_dir` 必须是 ① 的产物目录；
`exe`/`pbc_path` 仅独立形态（`cargo build --release --no-default-features`）需要，
生成项目形态（默认 `embed`）两者均可省略。另有两个 Python 参照实现可供对照：
`aggregate_trust_python`（信任聚合）、`aggregate_health_python`（健康四因子）。

### 命令行面（v0.6.1 插件化内核 · swarm/swarm_cli.py）

为各类 harness 提供统一入口——Bash 即可调用，stdout 恒为**单行 JSON**（机器面），
过程细节走 stderr：

```bash
python -m swarm.swarm_cli run --config swarm.json --out report.json   # 执行（重入=续跑/幂等聚合）
python -m swarm.swarm_cli verify --wal swarm_proj/events.jsonl --secret 密钥
```

`swarm.json`：`{"source": "术数源码或 @file 引用", "instances": [...],
"routes": [...], "rounds": 3, "shared_secret": "...", "topology": "..."}`。
安全模型：实例 = 确定性 VM 子进程（纯 std 无网络/无文件 I/O）、HMAC 全事件
签名 + `verify` 用 Python hashlib 独立复核、同 project+wal 重入断点续跑。

## 六、验收与基准

- 八套回归 107 项全绿 + Rust lib 单测 4 项 + clippy 零警告（明细见《使用报告 20260913》）
- 基准可复跑：`tests/bench_swarm_parallel.py`（加速比）、`tests/bench_swarm_scale.py`（规模/吞吐）

## 七、许可与边界

- 本模块为零依赖自研（D-005），外部仓（langgraph/ruflo 等）仅对照研读，无代码复制
- 已声明局限见《使用报告 20260913》§五