Agentswarm/docs/swarm/convergence-protocol.md

蜂群收敛协议（共识 / 冲突消解 / 终止函数）

状态：已无条件接入 refresh_swarm_run_status（去中心化重构，无开关）。每次 run 终态都产 ConvergenceReport 存 run.metadata["convergence"]，并把 termination_reason 附到 timeline.updated。当前为解释性——产出 termination_reason/共识/冲突，但不覆盖 run.status（今天 next_status 与报告对 completed/failed 一致）；authoritative 状态覆盖为后续。

对应 Issue #12：「蜂群收敛机制缺失：缺少共识、冲突消解与终止函数，无法解释 Swarm 为什么结束」。

实现：orchestrator/convergence.py（纯计算，无 I/O）+ main.py: compute_convergence_report（装配 run_state，shadow 落库）；单测 scripts/test-convergence.py + 集成测试 scripts/test-swarm-convergence.py。计划见 decentralized-rework-plan.md。

0. 问题：今天「为什么结束」是不可解释的

当前一次 run 走到终态，唯一判定在 orchestrator/main.py:refresh_swarm_run_status：

• 所有已知任务到达终态后，next_status = "failed"（任一任务 FAILED）否则 "completed"；
• 可选地（仅 ENABLE_REVIEW_LOOP）先跑主控评审，被拒则重开任务再 finalize。

也就是说，今天的终止 = 「所有任务做完 + （可选）评审通过」，没有：

• 共识模型：没有任何「多少产出处于一致状态」的度量；
• 一等公民的冲突检测 / 消解：两个 Agent 对同一文件写出不同内容、依赖未满足却标记完成等，均无显式识别；
• 可机读的终止原因：completed / failed 无法区分「质量达标」「预算耗尽」「轮次上限」「被风险阻断」。

本协议补齐上述三者。已无条件接入（无开关），但当前作为解释层：产出报告 + termination_reason 存 run，不覆盖 run 的终态语义（规则 #9：authoritative 覆盖为后续）。

1. 设计原则

• 纯函数、可测：evaluate_convergence(run_state) 不做任何 I/O，不修改 run；调用方（main.py: compute_convergence_report）负责持久化。
• 无条件（无开关）：refresh_swarm_run_status 每次终态都计算报告——本仓即 swarm 运行时，无 ENABLE_* 门控。
• 不伪造信号（规则 #9）：无质量评分 ≠ 通过；无测试信号 ≠ 失败；无预算 ≠ 充足。缺信号一律退出判定，不补 0、不补 100。
• 解释优先于干预：本版只解释「为什么结束」，不自动改写终态、不自动 merge 冲突产物。

2. 数据结构（orchestrator/convergence.py）

@dataclass
class ConvergenceReport:
    status: ConvergenceStatus              # running / converged / failed / blocked
    termination_reason: TerminationReason | None  # 终态必有，running 时为 None
    consensus_score: float                 # [0,100]，无冲突牵连的已完成产出占比
    conflicts: list[Conflict]              # 全部检出冲突
    resolved_conflicts: list[Conflict]     # 已消解
    unresolved_risks: list[dict]           # 阻断性风险 + 未消解硬冲突
    budget_state: dict                     # 预算限额 / 消耗 / exhausted
    quality_state: dict                    # fixture 评分 / 阈值 / reached

2.1 终止原因枚举（TerminationReason）

值	含义	触发输入
quality_reached	质量 / 验收门达标	quality.test_pass_rate ≥ acceptance_threshold（默认 1.0）
budget_exhausted	token / 成本 / 时长预算耗尽	usage ≥ budget 任一限额
max_rounds_reached	评审 / 重做轮次达上限	review_cycles ≥ max_review_cycles
risk_blocked	被未消解阻断性风险终止	输入阻断风险或未消解硬冲突
tasks_completed	诚实回退：仅「所有任务做完」	以上均不适用——即今天唯一真实信号

tasks_completed 明确对应「现状」：当没有质量评分、预算、轮次或风险信号时，我们能说的只有「任务都做完了」，不冒充更强的解释。

2.2 冲突类型（ConflictType）

类型	检测器	判据
artifact_mismatch	detect_artifact_mismatch	两个已完成任务对同一 files_modified 路径记录了不同 file_hashes/file_contents 指纹
test_failure	detect_test_failures	任务结果 tests_passed is False 或 test_pass_rate < 1
review_disagreement	detect_review_disagreement	主控评审 accepted=False（沿用 master_agent.review_and_decide 的 verdict 形状）
dependency_inconsistency	detect_dependency_inconsistency	任务已完成，但其 depends_on 依赖在同 run 内未完成

3. 终止函数判定顺序

evaluate_convergence(run_state) 依次判断，先匹配先返回：

1. 无任务 / 任一任务处于 pending|assigned|in_progress → RUNNING（无 reason）。
2. 存在阻断风险或未消解硬冲突 → BLOCKED + risk_blocked。
3. 仅有 blocked 任务（无阻断风险） → RUNNING（与 refresh_swarm_run_status 中「blocked 但有活跃子任务保持 running」对齐）。
4. 任一任务 failed → FAILED，原因取（预算耗尽→budget_exhausted；否则轮次到顶→max_rounds_reached；否则 tasks_completed）。
5. 全部完成且预算耗尽 → CONVERGED + budget_exhausted。
6. 全部完成且轮次到顶 → CONVERGED + max_rounds_reached。
7. 全部完成且质量达标 → CONVERGED + quality_reached。
8. 其余（全部完成） → CONVERGED + tasks_completed（诚实回退）。

不变式：任何终态（converged/failed/blocked）必带且仅带一个 termination_reason；running 必为 None。单测逐条断言。

3.1 共识分（compute_consensus_score）

consensus = 100 × (未被任何冲突牵连的已完成任务数 / 已完成任务总数)

无已完成任务 → 0.0。这是一个可解释的真实代理量（仅来自任务状态 + 检出冲突），不是模型主观打分。

3.2 消解（resolve_conflicts）——保守首版

• artifact_mismatch：仅当评审 accepted=True（评审隐式选定了胜出版本）才标记 resolved；否则 unresolved。
• review_disagreement：verdict 给出可操作 retry_tasks 时标记 resolved（蜂群可通过重开任务行动）；空泛拒绝无可操作项 → unresolved。
• test_failure / dependency_inconsistency：视为硬阻断，本版不自动消解，留给重做循环或人工。

每个冲突就地写回 resolved 与 resolution（消解方式或无法消解的原因）。

4. 事件载荷构造器

按 SwarmRuntime.emit_event(run, event_type, payload=...) 约定，每个构造器返回 (event_type, payload)，payload 为 JSON 安全 dict：

函数	event_type	用途
event_convergence_started	convergence.started	收敛评估开始
event_conflict_detected	conflict.detected	每检出一个冲突
event_conflict_resolved	conflict.resolved	每消解一个冲突
event_consensus_updated	consensus.updated	当前共识分与冲突计数
event_convergence_reached	convergence.reached	终态成功，附 termination_reason
event_convergence_failed	convergence.failed	终态失败/阻断，附 termination_reason

⚠️ 上述六个 event_type 尚未登记进 Manager 事件契约（heicode agent_callback.go）。在订阅或回调消费前，必须先按下方集成说明走 Manager 侧契约登记，否则属于未登记事件。

5. 测试

..\.venv\Scripts\python.exe scripts\test-convergence.py

模块级、无 WS/Redis/模型。覆盖：两个冲突产物 → 检出 artifact_mismatch + review_disagreement；review_disagreement 可消解、artifact_mismatch 未消解；产出带具体 termination_reason 的 ConvergenceReport；断言每个终态都带 termination_reason；断言至少一个冲突「检出 + 消解」闭环；以及五个终止原因各自的终态用例。全部 PASS。

6. 接入现状与诚实差距（规则 #9）

已接入（main.py: compute_convergence_report + refresh_swarm_run_status，无开关）：每次 run 终态装配 run_state（tasks/budget/usage/quality/review_cycles）→ evaluate_convergence → 报告存 run.metadata["convergence"]，termination_reason 附到 timeline.updated 载荷。

诚实差距：

• 解释性，非权威：报告不覆盖 run.status（今天 next_status 与报告对 completed/failed 一致）。authoritative 模式（如 BLOCKED→置 run blocked）改变 Manager 面终态语义，须先过 scripts/test-runtime-contract.py + 契约评审——列为后续。
• 质量/预算/风险输入有条件：quality 依赖 Group B fixture 评分（绑定 fixture 时）；budget/usage 需 run 提供；risks 需上游注入。缺失时相应原因不触发，回退 tasks_completed（不伪造）。
• 消解为保守首版：不做自动 merge / 自动选胜，硬冲突留待重做或人工。
• 收敛事件不进 Manager 流：六个 convergence.*/conflict.*/consensus.* 事件构建器已实现但不经 emit_event 外发（未在 Manager agent_callback.go 注册；与 swarm.health 同策略，避免向订阅全部的回调投递未登记事件）。登记后方可启用 Manager 侧发送。termination_reason 以新增可选字段附在 timeline.updated，对旧消费方向后兼容。