Document scoring and acceptance formulas

Make the scoring implementation auditable by writing the formulas for quality scoring, task scores, pheromones, candidate fusion, consensus, and S07/S09 pass gates. Constraint: The user asked to turn the scoring explanation into a document under the Chinese docs line. Rejected: Leaving formulas only in chat | future reviewers need a repo artifact linked from the docs index. Confidence: high Scope-risk: narrow Directive: Keep future score changes synchronized with SCORING_AND_ACCEPTANCE_FORMULAS.zh-CN.md and the acceptance scripts. Tested: rg formula/index scan; docs secret-pattern scan; git diff --check; .venv/bin/python -B -m unittest tests.test_model_io_report_audit. Not-tested: Did not rerun live S07 because this is a documentation-only formula extraction. Co-authored-by: OmX <omx@oh-my-codex.dev>
2026-05-16 17:38:09 +08:00
parent 7518895241
commit 996d7c7c18
3 changed files with 397 additions and 3 deletions
@@ -25,6 +25,7 @@

 - `docs/AGENT_SWARM_QUALITY_STANDARD.zh-CN.md`：Agent / 蜂群 Agent 质量标准、测试标准来源、S07 外部 GitHub 代码任务分配和接手机制。
 - `docs/ACADEMIC_STANDARD_TEST_REPORT.zh-CN.md`：S01-S09 测试场景、测试过程、测试结果、算法清单和马尔可夫过程判定。
+- `docs/SCORING_AND_ACCEPTANCE_FORMULAS.zh-CN.md`：分数实现、公式、变量含义、S07/S09 和最小闭环通过判定。
 - `docs/MODEL_AGNET_IO_REPORT.zh-CN.md`：每个模型 / Agnet 的任务、输入、输出、评分和交接过程。
 - `docs/AGNET_FRAMEWORK_INPUT_OUTPUT_LOGIC.zh-CN.md`：不带代码的框架逻辑说明，只从 Agnet 输入、输出、交接和收敛解释实现过程。
 - `docs/INDUSTRY_STANDARD_AGNET_TEST_PLAN.zh-CN.md`：行业参考框架到本项目标准的映射。
@@ -4,9 +4,10 @@

 1. 先读 `MINIMAL_CLOSED_LOOP_STATUS.zh-CN.md`，确认当前仓库已完成的最小闭环、已补齐的三项边界和仍不是生产级完整交付的部分。
 2. 再读 `AGENT_SWARM_QUALITY_STANDARD.zh-CN.md` 和 `ACADEMIC_STANDARD_TEST_REPORT.zh-CN.md`，确认测试标准来自哪里、S01-S09 如何验收、测试结果是什么。
-3. 需要看真实模型 / Agnet 输入输出时，读 `MODEL_AGNET_IO_REPORT.zh-CN.md`。
-4. 需要看不带代码的框架逻辑、交接和收敛过程时，读 `AGNET_FRAMEWORK_INPUT_OUTPUT_LOGIC.zh-CN.md`。
-5. `agnet-swarm-design-principles.md`、`01-ten-day-delivery-plan.md`、`02-person-task-interface-matrix.md`、`03-minimal-validation-and-acceptance.md` 是生产级平台落地路线图，不应被误读成当前仓库已完成完整 Heicode / Manager / Agnet 平台集成。
+3. 需要看分数如何计算、如何判定通过时，读 `SCORING_AND_ACCEPTANCE_FORMULAS.zh-CN.md`。
+4. 需要看真实模型 / Agnet 输入输出时，读 `MODEL_AGNET_IO_REPORT.zh-CN.md`。
+5. 需要看不带代码的框架逻辑、交接和收敛过程时，读 `AGNET_FRAMEWORK_INPUT_OUTPUT_LOGIC.zh-CN.md`。
+6. `agnet-swarm-design-principles.md`、`01-ten-day-delivery-plan.md`、`02-person-task-interface-matrix.md`、`03-minimal-validation-and-acceptance.md` 是生产级平台落地路线图，不应被误读成当前仓库已完成完整 Heicode / Manager / Agnet 平台集成。

 当前结论：`fengqun` 仓库已经达到本仓库定义的最小化闭环验收；它不是生产级完整交付。生产级差距主要在真实 Kubernetes worker runtime、Manager / Agnet API、人类审批主线、生产权限和平台监控。

@@ -14,6 +15,7 @@

 - `AGENT_SWARM_QUALITY_STANDARD.zh-CN.md`：AQS / SW-AQS v1 主标准，说明 Agent 和蜂群 Agent 的质量项、S07 任务分配、模型交接和当前结论。
 - `ACADEMIC_STANDARD_TEST_REPORT.zh-CN.md`：S01-S09 测试场景、测试过程、测试结果、算法清单和马尔可夫过程判定。
+- `SCORING_AND_ACCEPTANCE_FORMULAS.zh-CN.md`：分数实现、公式、变量含义、S07/S09 和最小闭环通过判定。
 - `MODEL_AGNET_IO_REPORT.zh-CN.md`：从 live run 导出的模型 / Agnet 任务、输入、输出、评分和交接过程。
 - `AGNET_FRAMEWORK_INPUT_OUTPUT_LOGIC.zh-CN.md`：不带代码的框架逻辑说明，只从 Agnet 输入、输出、交接和收敛解释实现过程。
 - `INDUSTRY_STANDARD_AGNET_TEST_PLAN.zh-CN.md`：行业参考框架到本项目 Agent 质量标准的映射。
@@ -0,0 +1,391 @@
+# 分数实现与验收判定公式
+
+**对象**: `swarm-minimal` 最小蜂群原型  
+**日期**: 2026-05-16  
+**范围**: 任务分数、输出质量分、信息素分数、候选融合分数、多轮共识分数、S07/S09 验收判定  
+
+## 1. 分数层级
+
+当前项目里的“分数”不是单一模型自评，而是多层规则共同作用：
+
+| 层级 | 分数名 | 用途 |
+| --- | --- | --- |
+| L1 | 输出质量原始分 `Q` | 判断单个模型 / Agnet 输出是否满足质量门 |
+| L2 | 任务分 `task.score` | 写入 task pool，作为基础收敛候选分 |
+| L3 | 信息素分 `P_t` | 影响后续任务 claim 顺序，并作为正负反馈记录 |
+| L4 | 候选融合分 `F` | 多个有效候选融合后形成的综合分 |
+| L5 | 共识候选分 `S_j` | 多个审查 Agnet 多轮投票后的候选分 |
+| L6 | 验收布尔判定 `PASS` | 判断整个场景是否满足标准矩阵 |
+
+因此，最终不是“一个高分就通过”，而是“质量门、分数门、状态证据、artifact 证据、共识门同时通过”。
+
+## 2. 输出质量原始分
+
+每个质量检查项记为：
+
+```text
+c_i ∈ {0, 1}
+```
+
+其中：
+
+- `c_i = 1` 表示第 `i` 个质量检查通过。
+- `c_i = 0` 表示第 `i` 个质量检查失败。
+- `N` 表示当前步骤需要检查的质量项总数。
+
+输出质量原始分：
+
+```text
+Q = (Σ c_i) / N
+```
+
+质量门通过条件：
+
+```text
+quality_pass =
+  Q >= 0.72
+  ∧ critical_checks_all_passed
+```
+
+S07 外部 GitHub 代码场景中的关键检查项包括：
+
+- 当前 STEP 标记存在。
+- 前一步 STEP 标记存在。
+- 外部仓库 `fastapi/fastapi` 存在。
+- 固定 commit 存在。
+- 输出没有漂移到当前仓库。
+- 没有拒答、角色拒绝、偏题或质量失败标记。
+- 包含 FastAPI 代码语义。
+
+## 3. 任务分公式
+
+设：
+
+- `Q` 为输出质量原始分。
+- `i` 为步骤序号，从 0 开始。
+- `R(content)` 表示输出包含拒答、角色拒绝、偏题或质量失败风险。
+- `final_step` 表示当前步骤是最终 STEP-07。
+
+如果存在质量风险：
+
+```text
+task.score = 0.12
+```
+
+如果没有质量风险，但没有通过质量门：
+
+```text
+task.score = max(0.05, 0.3 + 0.35Q)
+```
+
+如果通过质量门，且当前是最终 STEP-07：
+
+```text
+task.score = 1.0
+```
+
+如果通过质量门，但不是最终步骤：
+
+```text
+task.score = min(0.98, 0.62 + 0.28Q + 0.01i)
+```
+
+解释：
+
+- `0.12` 是风险输出惩罚分，用于强制拒答、角色拒绝、偏题输出无法进入正常收敛。
+- `0.3 + 0.35Q` 让未通过质量门的输出保留可审计分数，但不会轻易成为最终结果。
+- `0.98` 是中间步骤上限，避免中间步骤压过最终验收步骤。
+- 最终 STEP-07 通过质量门后给 `1.0`，表示它满足当前最小验收规则的最终收敛路径。
+
+## 4. 信息素分数公式
+
+每个 task 有一个信息素分：
+
+```text
+P_t
+```
+
+任务创建时：
+
+```text
+P_t = 0
+```
+
+任务成功完成时：
+
+```text
+P_t ← P_t + task.score
+```
+
+任务失败时：
+
+```text
+P_t ← P_t - 1.0
+```
+
+任务 claim 时，在能力匹配且状态为 `pending` 的任务集合中选择：
+
+```text
+claim_task = argmax(P_t)
+```
+
+这表示信息素不是只用来展示分数，它会反过来影响后续 Agnet 领取任务的顺序。
+
+## 5. 基础收敛公式
+
+基础收敛只在完成任务集合中选择最高任务分：
+
+```text
+T_done = {t | status(t) = done}
+```
+
+```text
+winner = argmax_{t ∈ T_done}(task.score_t)
+```
+
+最终结果：
+
+```text
+accepted_output = winner.output
+accepted_score = winner.score
+accepted_task_id = winner.id
+```
+
+注意：S07 live 外部代码场景不是只靠这个最高分直接放行。它在基础收敛前后增加了质量门、fallback、多轮质量共识、PostgreSQL/Redis/Blob 证据检查。
+
+## 6. 候选融合分数公式
+
+候选集合：
+
+```text
+C = {c_1, c_2, ..., c_m}
+```
+
+先过滤低分和空文本候选：
+
+```text
+U = {c_i | score_i >= min_score ∧ text_i 非空}
+```
+
+按分数降序排列后，对文本逐行去重合并。融合分数采用分数自加权平均：
+
+```text
+F = (Σ score_i^2) / (Σ score_i), c_i ∈ U
+```
+
+来源证据：
+
+```text
+sources = ordered(candidate.id)
+```
+
+解释：
+
+- `score_i^2` 让高分候选权重更大。
+- 低分噪声会被 `min_score` 过滤。
+- 多个高分候选的有效结论会被保留，而不是只选一个最高分文本。
+
+## 7. 多轮共识分数公式
+
+每个候选 `j` 有共识分：
+
+```text
+S_j
+```
+
+每一轮开始先做分数蒸发：
+
+```text
+S_j ← evaporation × S_j
+```
+
+每个审查 Agnet 投票后，候选分累加：
+
+```text
+S_candidate ← S_candidate + max(0, confidence_a) × weight_a
+```
+
+其中：
+
+- `confidence_a` 是第 `a` 个 Agnet 对候选的置信度。
+- `weight_a` 是该 Agnet 的角色权重。
+
+领先候选：
+
+```text
+leader = argmax_j(S_j)
+```
+
+领先占比：
+
+```text
+leader_share = S_leader / Σ max(0, S_j)
+```
+
+领先差距：
+
+```text
+margin = S_leader - S_second
+```
+
+共识收敛条件：
+
+```text
+consensus_converged =
+  leader_share >= threshold
+  ∧ margin >= min_margin
+```
+
+S07 质量共识参数：
+
+```text
+threshold = 0.7
+min_margin = 0.25
+evaporation = 0.82
+```
+
+S09 互相质询共识参数：
+
+```text
+threshold = 0.7
+min_margin = 0.2
+evaporation = 0.85
+```
+
+## 8. S07 live 外部代码场景通过公式
+
+S07 不是只看 `accepted_score`。可简化为：
+
+```text
+S07_PASS =
+  three_distinct_models_from_discovery
+  ∧ seven_chain_steps_all_done_in_pg
+  ∧ step_markers_and_previous_links
+  ∧ all_outputs_pass_quality_gate
+  ∧ shared_state_chain_cursor_and_summaries
+  ∧ pheromone_scores_pg_and_redis
+  ∧ shared_state_converged
+  ∧ convergence_pg_and_blob
+  ∧ redis_stream_event_volume
+  ∧ contains_external_fastapi_code_review_material
+  ∧ multi_round_quality_consensus_accepts_chain
+  ∧ final_output_references_external_files
+  ∧ keeps_model_discovery_not_fixed_model
+  ∧ external_github_target_not_local_project
+```
+
+其中分数相关的关键门为：
+
+```text
+all_outputs_pass_quality_gate =
+  ∀ step, quality_pass_step = true
+```
+
+```text
+pheromone_scores_pg_and_redis =
+  ∀ task, P_task_pg > 0 ∧ P_task_redis > 0
+```
+
+```text
+convergence_pg_and_blob =
+  convergence_exists
+  ∧ completed_tasks = 7
+  ∧ accepted_score >= 0.75
+  ∧ blob_artifact_exists
+```
+
+```text
+multi_round_quality_consensus_accepts_chain =
+  consensus_converged
+  ∧ accepted_candidate = accept_external_chain
+  ∧ round_count >= 2
+```
+
+## 9. S09 下一阶段边界通过公式
+
+S09 由三项检查组成：
+
+```text
+S09_PASS =
+  scaled_autonomous_claim_pass
+  ∧ candidate_fusion_pass
+  ∧ questioning_consensus_pass
+```
+
+3/5/7 并发 claim 通过条件：
+
+```text
+scaled_autonomous_claim_pass =
+  ∀ n ∈ {3, 5, 7},
+    converged_n
+    ∧ completed_tasks_n = 2n
+    ∧ failed_tasks_n = 0
+    ∧ duplicate_claims_n = ∅
+    ∧ participating_agents_n = n
+    ∧ all_tasks_done_n
+```
+
+候选融合通过条件：
+
+```text
+candidate_fusion_pass =
+  source_candidate_ids = ("quality", "coverage")
+  ∧ expected_terms ⊆ fused.text
+  ∧ low_score_noise ∉ fused.text
+```
+
+互相质询共识通过条件：
+
+```text
+questioning_consensus_pass =
+  converged
+  ∧ accepted_candidate = approve_fused_candidate
+  ∧ round_count >= 2
+  ∧ first_round_converged = false
+  ∧ last_round_converged = true
+  ∧ every_round_has_challenges
+  ∧ every_round_has_revisions
+```
+
+## 10. 总体验收公式
+
+当前仓库最小闭环验收可以概括为：
+
+```text
+MINIMAL_CLOSED_LOOP_PASS =
+  A01_static_compile
+  ∧ A02_unit_and_deterministic_scenarios
+  ∧ A03_swarm_behavior_acceptance
+  ∧ A04_swarm_vs_traditional_benchmark
+  ∧ A05_consensus_convergence_acceptance
+  ∧ A06_next_boundary_minimal_acceptance
+  ∧ S07_live_external_github_code_reasoning
+  ∧ S08_model_io_report_audit
+  ∧ S09_next_boundary_minimal_acceptance
+```
+
+最终解释：
+
+```text
+score 高 ≠ 自动 PASS
+```
+
+真正判定是：
+
+```text
+质量门 + 分数门 + 信息素证据 + 状态证据 + artifact 证据 + 多轮共识门 全部通过 = PASS
+```
+
+## 11. 公式对应实现位置
+
+| 公式 / 机制 | 实现位置 |
+| --- | --- |
+| 输出质量原始分 `Q` | `examples/run_continuous_reasoning_acceptance.py::assess_output_quality` |
+| 任务分 `task.score` | `examples/run_continuous_reasoning_acceptance.py::score_output` |
+| 信息素更新 `P_t` | `swarm_minimal/core.py::complete_task` / `fail_task` |
+| 基础最高分收敛 | `swarm_minimal/core.py::converge` |
+| 候选融合分 `F` | `swarm_minimal/core.py::fuse_candidate_outputs` |
+| 多轮共识分 `S_j` | `swarm_minimal/core.py::ConsensusSwarm.run` |
+| 互相质询共识 | `swarm_minimal/core.py::QuestioningConsensusSwarm.run` |
+| S07 标准矩阵检查 | `examples/run_continuous_reasoning_acceptance.py::collect_report` |
+| S09 下一阶段边界检查 | `examples/run_next_boundary_acceptance.py` |