diff --git a/README.md b/README.md index d11ce8d..2d51f3d 100644 --- a/README.md +++ b/README.md @@ -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`:行业参考框架到本项目标准的映射。 diff --git a/docs/README.md b/docs/README.md index 27be8fe..cf6957b 100644 --- a/docs/README.md +++ b/docs/README.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 质量标准的映射。 diff --git a/docs/SCORING_AND_ACCEPTANCE_FORMULAS.zh-CN.md b/docs/SCORING_AND_ACCEPTANCE_FORMULAS.zh-CN.md new file mode 100644 index 0000000..add6a0b --- /dev/null +++ b/docs/SCORING_AND_ACCEPTANCE_FORMULAS.zh-CN.md @@ -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` |