足球赛事多维数据分析模型

概述

当前版本 v5.9.17 · 35 联赛基线 · 31 联赛实测 ρ · 90 项自测全 PASS（含 79 条回归守卫） · v5.9.17 修复：赛前清单检查2 移除"仅赔率"反向推断（修复强队 1.30–1.50 被误判大热并套 -0.15 降权，使 analyze_match 主胜偏离市场 ~7pp）+ 新增 G3d 回归守卫 · v5.9.16 修复：星级降级分级生效 / 联赛别名自动解析（覆盖率 80%→92%）/ 畸形赔率入口阻断 / CLI 拆出 cli.py / --test 退出码如实反映结果 · v5.9.13 新增：真实 xG 数据集落地（Understat 逐场 xG，浏览器驱动抓取；英超 7 季 2660 场）→ 球队滚动 xG（场地感知/防泄漏）→ 生产引擎（--xg-form / --xg-analyze + G68/G69 守卫） · v5.9.12 新增：真实时变衰减 DC 攻防直接接入生产概率引擎（dc_lambda + dc_weight，OPT-IN 默认关闭）+ CLI --dc-analyze + G67 守卫 · v5.9.11 新增：真实多赛季逐场 → 时变衰减 Dixon-Coles MLE（重写求解器为稳定版）+ CLI --fit-dc-file + G66 守卫 · v5.9.10 新增：真实数据 CLV 管线（football-data.co.uk 开盘/收盘赔率）+ CLI --clv-file + G65 守卫 · v5.9.9 新增：优化模块（P0 CLV 验证框架 / P0 市场偏好低估修正[OFF] / P1 时变衰减 Dixon-Coles MLE[框架] / P2 Platt+Isotonic 概率校准 / P2 多模型 ensemble）+ CLI --clv/--calibrate/--fit-dc + G59-G64 守卫 · v5.9.8：292 场赛事真实双盘口入库、λ 反演正则 0.03→0.22 重标定、G56-G58 守卫 · v5.9.7：混合权重实测标定（0.30/0.20/0.05 → 0.15/0.10/0.03，依据 bootstrap 90% 上界）+ 偏好-低偏好偏差校正层（LOOCV 实测 +9.6%，出厂默认关闭）+ 三方标定数据集入库 · 版本历史见文末

⚡ 快速开始（30 秒上手）

① 推荐入口 analyze_match()（v5.9.2）——4 个参数即跑，赛前三清单与价值评估层自动接线，不存在"忘记回传"问题：

from football_calc import analyze_match
r = analyze_match("英超", 2.10, 3.50, 3.20)   # 最小调用
print(r["home_win"], r["draw"], r["away_win"], "星级:", r["star"])
print(r["checklist"])    # 三清单自动执行并生效（traps_count/star_modifier）
print(r["value"])        # 期望值 + 模型-市场分歧度（自动）
print(r["kelly"])        # 建议分配（自动）
print(r["signal_tier"])  # 联赛统计信号分级 A/B/C（自动）

# 有更多数据就多传（其余参数原样透传主函数）：
r = analyze_match("德甲", 1.05, 11.0, 21.0, current_round=2,
                  home_form=8, away_form=4, support_home=77,
                  open_odds={"home": 1.18, "draw": 10.5, "away": 19.0},  # 触发市场资金因子
                  popularity=80)
print(r["hot_money"])    # 市场资金动向 + 诱盘警示

② 手动两步（进阶）——需要自己把三清单结果回传 checklist_result=chk，忘了传则降权/降级完全不生效（实测同一场景主胜会虚高 19pp）：

from football_calc import run_prematch_checklist, calc_1X2_probabilities
chk = run_prematch_checklist(2.10, 3.50, 3.20, league="英超")
r = calc_1X2_probabilities(league="英超", odds_home=2.10, odds_draw=3.50,
                           odds_away=3.20, home_form=7.0, away_form=7.5,
                           checklist_result=chk)   # ← 这行忘了 = 白跑清单

③ 世界杯/欧洲杯等国家队杯赛（v5.9.3 P5）——FIFA 排名先验统计基准，69 队开箱即用：

from football_calc import predict_cup_match
r = predict_cup_match("西班牙", "阿根廷")   # 2 参数即跑
print(r["home_win"], r["draw"], r["away_win"], r["expected_goals"])
# ⚠️ 统计基准层: 未含近期状态/伤停; 样本外 RPS=0.1497 (P5 实测)

④ 高频参数速查（analyze_match / calc_1X2_probabilities 通用，其余见 references/quick_reference.md）

📖 去哪找什么

📁 文件地图（不知道去哪找时看这里）

一句话导航：查数据查函数 → references/quick_reference.md；查流程查能力 → 本文件。

🚦 能力边界一览（唯一权威清单 · 30 秒看懂）

一句话版：能做「方向 + 风险 + 数据可靠性」；不能做「精确比分 / 半全场 / 临场首发 / 杯赛与国家队的精确判断」；小联赛数据可能不全，杯赛与国家队不覆盖。

「能不能做」只在本节定义（A–F 六张表）。其它章节不再重复，也不需要来回拼凑；机制细节见「十三、能力边界机制说明」。

A. 能做到 ✅

B. 有条件做到 ⚠️（有前提；不满足就降级或停下）

C. 做不到 ❌（明确的能力边界）

D. 覆盖范围（联赛 / 赛事类型）

三档口径：✅ 直接可用　⚠️ 可用但降级（会明确告诉你）　❌ 不适用（会说明原因）。

「小联赛数据不全」具体指：无内置基线、伤停与近况检索命中率低、赛季样本少——请务必补充你手上的信息。

E. 特殊场景清单（遇到先查这里）

F. 什么时候会直接停下？（只有 2 种）

其余情况一律「先继续跑 + 明确告知降级点」。完整的阻断/重试/熔断机制、置信度分级、离线精度推导见「十三、能力边界机制说明」。

一、执行操作指南

第一次使用？请从这里开始。

我能做这两件事

使用流程图

你提供赛事信息 / 说一句话
        ↓
  ★ Step 0.1 输入校验（v2.9.2 新增）
     ← 联赛名/赔率有疑点？→ 先提示你确认，不直接分析
        ↓
  自动识别联赛和场次
        ↓
  ┌─ 赛前数据分析 ──────────────┐
  │ Step 0: 查基线库定进球档  │
  │ Step 1: 情报搜集           │  ← 某场查不到？→ 国内源优先→离线基线
  │ Step 1.5: 三清单检查       │  ← 极端赔率/市场预期/赛季初期
  │ Step 2: 七维分析           │  ← 遇到错误？→ 见「问题解答区」
  │ Step 3: 三维自洽校验       │
  │ Step 4: 汇总表 + 置信度 + 数据来源标注 │
  └─                              ┘
        ↓
  输出 football_predictions_YYYY-MM-DD.md

快速上手三步

第一步：把赛事对阵信息发给我（赔率截图/球队/伤停等）

第二步（可选）：告诉我你关注哪几场

第三步：等 5-15 分钟，我会输出：

• 每场的结果方向推荐 + 置信度
• 实力差距分析 + 风险提示
• 关键数据的来源与可靠性标注
• 自洽校验结果
• ⚠️ 标红的场次 = 置信度低，需要你判断

如果结果不如预期

• 某场"数据待定"→ 见「问题解答区」
• 某场置信度只有 ⭐ → 说明基本面和市场预期分歧大
• 想深入了解某场 → 直接问"这场为什么给⭐？"

二、快速开始

你可以这样问

你会得到什么

1. 汇总表：场次/对阵/结果方向/进球预期/比分/置信度
2. 置信度标注：⭐⭐⭐双重支撑 → ⭐⭐单方支撑 → ⭐谨慎参考
3. 风险提示：极端赔率陷阱、市场预期反向、赛季初期主队强势
4. 数据来源标注：每条关键数据标注 A/B/C/D 可靠性等级
5. 三维自洽校验：方向/半全场/总分匹配

三、输入校验与异常提示（v2.9.2 新增）

解决旧问题：写错数据（比如填错联赛名）时系统自己想办法补救，但不告诉你哪里错了。

分析前必做：三步校验

每次分析开始前，先跑 validate_user_input()，校验三项：

三种典型提示

① 联赛名写错 / 用了别名

你输入：德国甲级联赛
系统：ℹ️ 联赛名「德国甲级联赛」已识别为「德甲」，按德甲基线分析。

若完全无法识别：

你输入：威尔士超级联赛
系统：⚠️ 联赛名「威尔士超级联赛」无法识别（基线库收录 35 个赛事）。
     请确认名称，或按「联赛名, 场均进球, 主胜率, 客胜率」直接提供参数。

记住：不会再静默替换后继续。识别不到就一定告诉你。

② 赔率疑似填错（含极端低赔）

你问：某队赔率只有 1.10，能打吗？
系统：⚠️ 检测到主胜赔率仅 1.10（异常低）。请先确认三点：
       1) 是否看错实力差距设定 —— 这是「0盘（无差距）」还是「实力差距档」？
       2) 是否填错数字 —— 例如 1.10 是否误填（本意 1.01 / 11.0 / 10.0）？
       3) 若确认无误 —— 属「极端赔率陷阱」区域，历史打出概率低于赔率隐含，需降权处理。

若赔率不可能（≤1.0）：

系统：❌ 赔率输入有误：
       - 主胜赔率 0.95 不可能（赔率必须 > 1.0，疑似填错）
     请核对后重新提供；在此修正前不做分析。

③ 隐含概率和异常

系统：⚠️ 赔率结构异常：
       - 隐含概率和 1.72 偏高（正常约 1.05-1.35，疑似赔率填错）

⚠️ "阻止"机制说明

当校验判定为硬错误（赔率≤1.0、联赛名完全无法识别）时，系统进入 blocking=True 状态：

• 不输出分析结果，先展示上面的提示
• 等你确认或修正后，才继续分析

当校验判定为软疑点（联赛名模糊、极端低赔）时：

• 提示你，但继续分析（结论会带上降权说明）
• 你若发现确实填错，回复更正即可重算

你怎么回应

四、完整分析案例

案例：德甲 拜仁 vs 沙尔克（第 2 轮，2026-08）

Step 0：查基线库 → 德甲，大球档（3.24球），开季+10%

Step 0.1：输入校验 → 联赛名「德甲」识别 ✓；赔率 1.05/11.0/21.0 → 触发极端低赔提示（主胜1.05）

Step 1：情报搜集

• 拜仁：首轮5-1大胜，新援赛巴里/布朗到队<2周（磨合风险）
• 沙尔克：首轮0-0，前一季附加赛保级，客场弱
• 赔率：客胜1.05 → 极端低赔

Step 1.5：三清单检查

• ⚠️ 检查1触发（赔率1.05 ≤ 1.15）
• ⚠️ 检查3触发（德甲第2轮）
• 共2项触发 → 置信度降2级

Step 2：七维分析 → 拜仁近期状态+++, H2H主场全胜+++, 但新援磨合风险（-2分）

Step 3：自洽校验 → 方向主胜✓，但三清单触发 + 新援磨合 = 降低置信度

Step 4：输出 → 主胜3-0，⭐（⭐⭐→⭐，因2项清单触发），比分仅参考

⚠️ 实际结果：拜仁 0-0 沙尔克（极端赔率陷阱经典案例）

赛后核验完整案例（新增）

场景：用户想核验 2026-09-06 的 30 场分析输出，对比方向/比分/进球。

Step 1：收集最终结果（国内源优先）

你说：帮我复盘昨天的比赛，预测文件是 football_predictions_2026-09-06.md

系统：正在核实各场最终结果（懂球帝/直播吧/中国体彩网）...
→ 核实完成：26/30 场

Step 2：逐场核验

Step 3：失败维度归因

012 拜仁 0-0 沙尔克：
  → 三清单检查 1（赔率 1.05）+ 检查 3（德甲第 2 轮）触发
  → 降权修正后仍预测 3-0 → 失误
  → 教训：极端赔率 ≤1.15 的场次，实际打出概率低于隐含概率约 40%

020 毕尔巴鄂 3-0 马竞：
  → 市场看好度 77% 指向马竞客胜 → 三清单检查 2 触发
  → 降权后仍判定客胜 → 教训：看好度 >75% 是反向指标

方向参考：约 35%（参考基准约 52%）
比分参考：约 11%
进球参考：约 27%

Step 4：回填基线库

系统：检测到德甲开季进球均值高于基线 3.24，将基线临时上调至 3.40。
     检测到葡超本菲卡客战超预期，将葡超客胜率从 0.31 微调至 0.33。

Step 5：输出复盘文件→ football_review_2026-09-06.md：含汇总表 + 教训总结 + 基线修正记录

五、核心框架

权重：基本面 70% + 市场赔率结构 30%

七维基本面（70%）

联赛基线校准

赛季分期与状态修正

Option B：4 项新维度

xG 数据集成（最关键）

输入：

• xg_home: 主队 xG/场（国内源优先检索，FBref/Understat 兜底）
• xg_away: 客队 xG/场
• 联赛基线：LEAGUE_XG_BASELINE 已为 35 联赛预设（英超主 1.50/客 1.15 等）

作用：

• 若提供 xG，预测期望进球用 xG 估算，否则用赛季基线
• 若 |xG 优势| > 0.5，触发警告「实力差距明显」

战意类型

换帅效应

赛程密度

联赛专属权重矩阵（已嵌入 football_calc.py）

使用方式：调用 calc_1X2_probabilities(league="意甲", ...) 时自动应用对应联赛权重。

参数速查表：普通人怎么填（新增）

xG、战意类型、换帅场次、休息天数这四个参数听起来专业，但你只需要知道球队的基本情况就能填，不用懂足球术语。

不会填怎么办？

• 不填 → 系统用联赛默认值，不影响分析流程
• 填错 → Step 0.1 输入校验会提示你核对
• 拿不准 → 直接说"我不知道 xG，你按默认算"，系统自动跳过该维度

六种战意类型的通俗判断：

争冠（title）     → 联赛前3名，差领头羊 ≤5分，下半场冲刺阶段
争四（top4）      → 联赛第4-6名，差欧冠区 ≤5分
中游（mid）       → 无欲无求，剩5场以上还差10分以上
保级（relegation）→ 倒数4名内，差安全区 ≤5分
杯赛轮换（cup）   → 联赛无欲无求 + 杯赛在打 + 可能上替补
末轮无意义（dead_rubber）→ 联赛最后一轮双方都无欲无求

休息天数的快速判断：

上一场是 3 天前 → 填 3（正常节奏，无加成）
上一场是 2 天前 → 填 2（赛程密集，-8%）
上一场是 7 天前 → 填 7（国际比赛周后，+5%）
今天 vs 上场 = 同一周 → 填 0-1（极度疲劳，-8%）

六、问题解答区（遇到问题先查这里）

旧问题：风险提示有，但遇到问题不知道去哪找答案。现在按症状对号入座。

快速导航

A. 输入类问题

A1｜联赛名无法识别怎么办？见「三、输入校验」。系统会给出最接近的候选并要求你确认；若确实没有该联赛，可手动提供参数：「联赛名, 场均进球, 主胜率, 客胜率」。

A2｜赔率看起来不对（如 1.10）怎么办？系统会自动检测并提示你核对三点（赔率/数字/是否确认）。你只需回复"确认无误"或给出正确赔率。

A3｜输错了数据想改？直接重发正确信息即可，例如："上一场主队赔率写错了，应该是 1.85"。系统会重算该场。

B. 数据类问题

B1｜"数据待定"是什么意思？= 该场关键情报检索失败，已用离线基线兜底，结论可靠性下降。处理：补充该场关键信息（伤停/排名）可提升精度。

B2｜查不到某队信息？

1. 核对球队名拼写（尤其从外文音译）；2) 直接告诉我你知道的信息；3) 系统会用默认值继续，但该场会降级。

B3｜国外网站慢/打不开？v2.9.2 已改为国内源优先（详见「十、数据源与可靠性」）。若仍失败，系统会切换到离线基线并标注。

B4｜转会信息不确定真假？系统对转会/阵容等关键信息会标注来源等级并尝试双源交叉验证；只找到单一弱来源的，会标「待核实」，不作为决策依据。

C. 结果类问题

C1｜置信度只有 ⭐ 说明什么？基本面与市场预期分歧大，或某维度数据缺失。⭐ = 仅作方向参考，别当绝对结论。

C2｜比分预测为什么不准？比分是低概率事件，历史对比率≈0%。比分仅作娱乐，重点看方向和实力差距。

C3｜想改某场结论？告诉我哪场 + 你的新信息，系统重跑该场。

D. 使用类问题

D1｜能离线用吗？可以。内置 35 个联赛离线基线；无网时自动启用，精度约 80%，但不保证最新（阵容/伤停可能过时）。

D2｜什么时候最准？基本面和市场预期方向一致且情报完整时最准（⭐⭐⭐）。赛季前 2-3 轮、新援磨合期、杯赛淘汰赛最不准。

D3｜报错/卡住怎么办？见「十二、错误诊断与操作引导」；若单场卡住，系统有熔断机制会自动跳过该场，不影响其余场次。

常见错误反模式（对应"别这么做"）

七、赛前数据分析流程

Step 0：联赛基线 → 自动回退

1. 查基线库
2. 联赛不在库 → 真实检索获取场均进球/主客胜率
3. 检索失败 → 使用内置 35 联赛离线基线

Step 0.1：输入校验（v2.9.2 新增，强制）

调用 validate_user_input(league, odds_home, odds_draw, odds_away)：

• 联赛名无法识别 / 赔率≤1.0 → blocking=True，先提示用户、等确认
• 联赛名模糊 / 极端低赔 / 隐含概率和异常 → 提示但继续（带降权）

Step 0.5：赛前必查三清单（强制检查，不可跳过）

【检查1/3】极端赔率检查 — 针对：赔率 ≤ 1.15

参考案例：拜仁客胜 1.05 → 实际 0-0 沙尔克

【检查2/3】市场预期反向检查 — 针对：某方看好度 > 75%（或赔率极端暗示）

参考案例：毕尔巴鄂 vs 马竞，77% 指向马竞客胜 → 实际 3-0 主胜

【检查3/3】联赛赛季初期偏差 — 针对：德甲/法甲/英超/西甲赛季前6轮

额外进球修正：赛季前6轮进球数平均高约 +10%。

三清单结果汇总：

Step 1：情报搜集（容错机制）

• 每场 真实检索（国内源优先 → 国外源兜底）
• 必检索项：阵容、伤停、主帅近况、近期表现
• Option B 必检索项：
  • xG 数据（{球队} xG expected goals {赛季}）
  • 上一场比赛日期（计算休息天数）
  • 联赛排名/争冠形式（判断战意类型）
  • 主帅履历（是否新上任，新帅在任几场）
• 失败 → 换措辞重试(≤2次) → 换数据源 → 离线基线
• 关键数据（转会/阵容）必须标注来源等级，双源交叉验证

Step 1.5：三清单复查

完成情报搜集后，再跑一次三清单。

Step 2：七维分析 + 基线校准 + 三清单修正

按七维分析，结合进球档与分期修正因子；三清单结果在此处叠加。

⚠️ 三清单的叠加是「数值」的，不是「脑内估算」：

必须把 Step 0.5/1.5 得到的 chk 作为 checklist_result=chk 传入

calc_1X2_probabilities()，降权与星级降级由函数内部完成。

只把 chk 打印出来看、不传参 = 三清单对最终概率零影响。

Option B 额外步骤：

• 若提供了 xG 数据 → 调用 calc_xg_expected_goals() 覆盖默认期望进球
• 调用 calc_xg_advantage() 计算 xG 优势（>0.5 触发警告）
• 应用 MOTIVATION_FACTORS[战意类型] 加成
• 应用 manager_bounce_factor(在任场次) 加成
• 应用 rest_days_factor(休息天数) 加成
• 联赛权重按 LEAGUE_WEIGHTS[联赛] 自动切换

Step 3：三维自洽校验

• 方向 = 比分方向
• 半全场末位 + 全场末位 = 总进球末位
• 实力差距方向与总分匹配

Step 4：汇总表

⭐⭐⭐基本面+市场双重支撑 | ⭐⭐单方支撑 | ⭐谨慎参考

八、赛后核验流程

Step 1：检索最终结果（国内源优先）

Step 2：逐场核验分析准确度

Step 3：失败维度归因

Step 4：回填基线库新赛季实测数据

九、七维量化计算模块

函数完整签名 / 参数 / 返回值 → 见 references/quick_reference.md 第 4 节；可直接运行的代码示例 → 见第 8 节。

快速使用

# v5.9.16 / P2-9：CLI 已拆到 cli.py。两种跑法等价 —— football_calc.py 会转发到 cli.main()
python "~.workbuddyskillsfootball-analysiscli.py"
python "~.workbuddyskillsfootball-analysiscli.py" --test
python "~.workbuddyskillsfootball-analysiscli.py" --json

# 向后兼容（旧命令仍可用）：
python "~.workbuddyskillsfootball-analysisfootball_calc.py" --test

只做计算（在自己脚本里 import）用 football_calc.py；要跑 CLI（demo / 自测 / JSON / 回测）用 cli.py。

函数清单

常量：

• LEAGUE_XG_BASELINE：35 联赛 xG 基线
• LEAGUE_WEIGHTS：35 联赛专属权重矩阵
• MOTIVATION_FACTORS：6 种战意加成表
• 🆕 LEAGUE_ALIASES：联赛别名表（用于纠正输错的联赛名）
• 🆕 DATA_SOURCE_PRIORITY：国内外数据源优先级
• 🆕 DATA_RELIABILITY：数据可靠性 A/B/C/D 分级

代码示例（可直接运行）

先把技能目录加入 sys.path；完整 9 组示例（含数据源、可靠性、错误处理、一次完整分析的调用顺序）见 references/quick_reference.md 第 8 节。

例 1：单场完整分析（含 Option B 四维）

import sys
sys.path.insert(0, r"~.workbuddyskillsfootball-analysis")
from football_calc import calc_1X2_probabilities

r = calc_1X2_probabilities(
    league="英超", odds_home=2.10, odds_draw=3.50, odds_away=3.20,
    home_form=7.0, away_form=8.0,
    xg_home=1.85, xg_away=1.65,                 # 主队略占 xG 优势
    motivation_type_home="top4", motivation_type_away="title",
    rest_days_home=5, rest_days_away=3,         # 客队赛程更密
)
print(f"主胜 {r['home_win']:.1%} / 平 {r['draw']:.1%} / 客胜 {r['away_win']:.1%}")
print("预期总进球", r["expected_goals"], "| 星级", r["star"], "| 差距建议", r["rec_handicap"])

例 2：赛前必查三清单（必须回传给主计算函数）

⚠️ chk 不传给 calc_1X2_probabilities(..., checklist_result=chk)，三清单的降权/降级完全不生效。

v5.8.1 曾因文档只 print 不回传，导致 P0-4 的数值接线「存在但不可达」。

from football_calc import run_prematch_checklist, calc_1X2_probabilities

chk = run_prematch_checklist(
    odds_home=1.05, odds_draw=11.0, odds_away=21.0,
    league="德甲", current_round=2,
)
print("触发", chk["traps_count"], "项；星级修正", chk["star_modifier"])
print(chk["combined_action"])
print("降权量：", chk["final_odds_adjustment"])   # 被降权方 = 偏好方本身

# ✅ 关键一步：回传 chk
r = calc_1X2_probabilities(
    league="德甲", odds_home=1.05, odds_draw=11.0, odds_away=21.0,
    home_form=8.0, away_form=4.0,
    checklist_result=chk,      # ← 漏掉 = 风控白跑
)
# 实测（拜仁 1.05/11/21）：不传 → 主60.1% 星***；传 → 主28.6% 星*

例 3：输入校验（阻断式）

from football_calc import validate_user_input

v = validate_user_input(league="英格兰超级联赛",
                        odds_home=1.08, odds_draw=9.0, odds_away=19.0)
if v["blocking"]:
    print(v["user_message"])   # 把这段话发给用户，等确认后再分析
print("解析后的联赛：", v["resolved_league"])

例 4：命令行自检 / 演示

chcp 65001
python "~.workbuddyskillsfootball-analysiscli.py" --test   # 89 项自检 + 78 条回归守卫
python "~.workbuddyskillsfootball-analysiscli.py" --json   # 纯 JSON（无横幅，可直接 json.loads）

十、数据源与可靠性（v2.9.2 新增）

解决：国外站国内加载慢/不完整；转会等信息不可靠。

数据源优先级（国内优先）

策略：先查 1-6（国内快），拿不到再去兜底站；全部失败 → 离线基线 + 标注。

数据可靠性分级

关键数据核实规则

对转会、阵容、伤停这类会直接影响结论的数据：

1. 至少 2 个不同的 A/B 级来源印证 → 才算可信
2. 只有 1 个可信来源 → 标「待核实」
3. 只有 C/D 级来源 → 不采用（仅内部参考）

调用 verify_transfer_claim("某球员转会X队", sources=["懂球帝","直播吧"])：

• 2 个 B 级源 → verified=True → ✅ 可信
• 仅 1 个 C 级源 → verified=False → ⚠️ 待核实

输出中每条关键数据都会带来源标注，例如：主力中卫伤缺（来源：懂球帝 B；直播吧 B）。

十一、输出规范与环境约束

输出文件

• 情报文件：intelligence_YYYY-MM-DD.md
• 预测文件：football_predictions_YYYY-MM-DD.md
• 复盘文件：football_review_YYYY-MM-DD.md

输出文件头应包含

• 数据来源与采集时间
• 框架版本（v5.8.1）
• 数据可靠性声明
• 风险声明（非分析参考）

环境约束

• Python bundled 可能间歇性被封 → 校验用人工自检
• browser 不可用 → 用 web_search / web_fetch（国内源优先）
• 超长截图 → Python PIL 切割为 8 片再识别
• Windows PowerShell 中文/emoji → 先 chcp 65001 或重定向 UTF-8 文件

十二、错误诊断与操作引导

当分析过程中出现问题时，先在这里找对应类型。

错误类型速查表

熔断机制

• 单场检索连续失败 3 次 → 跳过该场（用离线基线），不影响其余场次
• 全局连续跳过 5 场 → 暂停并提示网络异常

自动重试与容错流程图（新增）

你会看到的提示 vs 底层实际发生了什么——让你对系统的兜底能力有感知。

你上传赔率截图
        ↓
系统开始逐场分析
        ↓
┌─ 每场比赛 ────────────────────────────────┐
│ 第1次检索（国内源优先）                      │
│   你看到：正在查询 ...                       │
│   实际：懂球帝 → 直播吧 → 新浪体育            │
│   成功 → 继续下一维度                        │
│   失败 →                                    │
│        ↓                                   │
│   第2次检索（换措辞 / 换数据源）              │
│   你看到：重新尝试 ...                       │
│   成功 → 继续                                │
│   失败 →                                    │
│        ↓                                   │
│   第3次检索（换备用站）                       │
│   你看到：加载稍慢 ...                       │
│   成功 → 继续                                │
│   失败 →                                    │
│        ↓                                   │
│   触发熔断 → 跳过该场，切换离线基线           │
│   你看到：⚠️ 数据待定（该场用离线基线分析）    │
│   结论：该场星级降 1-2 级，但不阻塞其余场次   │
└───────────────────────────────────────────┘
        ↓
若全局连续 5 场都触发熔断
  你看到：⚠️ 网络异常，部分场次数据缺失，建议稍后重试
  系统：暂停，跳过这批，等待你重新上传截图
        ↓
若部分场次用离线基线（有 35 联赛内置数据）
  你看到：⭐⭐ → ⭐（因数据不完整降级）
  结论：方向仍然可信，但比分和进球预期精度下降

你感知到的 vs 实际情况对照：

十三、能力边界机制说明

完整的能力/限制清单在开头「🚦 能力边界一览」（A 能做到 / B 有条件做到 / C 做不到 / D 覆盖范围 / E 特殊场景 / F 阻断条件）。

本节只补充机制细节，不再重复清单。

什么时候会「停下来」？（阻断与兜底一览）

分三档：⛔ 先停下问 / ⚠️ 降级继续 / ⏭️ 跳过。

一句话：⛔ 只在「联赛名认不出」和「赔率明显错」两种情况下停下；其余都会先继续跑，并明确告诉你哪里降级了。

置信度分级

能做到 / 做不到（已合并到开头，这里不再重复）

为避免「同一件事要在几处拼凑」，原「我能做到的 / 我做不到的」两份清单已合并并统一到开头「🚦 能力边界一览」：

• A. 能做到 ✅（含说明）
• B. 有条件做到 ⚠️（含前提条件与不满足时的降级方式）
• C. 做不到 ❌（含原因与替代做法）
• D. 覆盖范围（35 赛事基线内 ✅ / 未收录次级与小联赛 ⚠️ / 国家队、青年队 ❌；杯赛可做两回合与中立场修正）
• E. 特殊场景清单（18 类边缘场景的覆盖状态与处理方式）
• F. 阻断触发条件（只有 2 种）

离线精度 80% 是怎么算的（新增）

文档说「离线模式下精度约 80%」，这个数字不是拍脑袋来的，是双层推导。

第一层：数据维度覆盖率

分析一场比赛依赖 7 个数据维度。联网时 7 个全有；离线时，基线库提供其中 3 个（联赛进球档 / 主客胜率 / 赛季分期规律），缺失 4 个维度（伤停 / 实时状态 / 阵容 / 赔率实时变化）。

数据维度覆盖率 = 3/7 ≈ 43%

第二层：各维度历史准确率

第三层：综合计算

离线模式的整体准确率，用加权平均估算：

联网模式准确率 = 各维度加权平均 ≈ 82%（历史验证基准）

离线模式准确率 =
  联网基准 82%
  × (联网时维度覆盖率 100% → 离线维度覆盖率 43% 的比例修正)
  ≈ 82% × (43% + 57% × 约 82% 精度回退)
  ≈ 82% × 0.89
  ≈ 73%

取整后保守估计为 80%。

精度下降的主要来源：

• ❌ 伤停信息缺失（缺失时用无伤代替，高估实力）
• ❌ 实时状态缺失（强队连败时用均值代替，高估）
• ❌ 阵容信息缺失（新手首发时用主力代替，高估）

你看到什么：离线时 ⭐⭐⭐ 会变成 ⭐⭐，比分预测误差增大。

一句话总结

方向看置信度 ⭐⭐⭐/⭐⭐，比分当娱乐，半全场忽略；输入有疑点会主动提示，赔率≤1.15 和看好度>75% 时特别小心，关键数据看来源标注；遇到数据缺失系统自动重试兜底，离线时精度约 80% 有两层推导依据。

版本历史（v5.8.0 → v5.9.18）

v5.9.18 升级（实跑验证驱动；P2 概率校准层 · OPT-IN）：

• 新增概率校准层（默认关闭）：基于随包真实竞彩数据集（reference_dataset_v2，n≈292 场含真实赛果）训练经验分桶校准器，对 calc_1X2_probabilities 最终输出做加法修正 + 贝叶斯平滑（SMOOTHING=50）的校准。
• 真相核查先行：全桶校准曲线显示，仅 70–80% 概率桶（n=32） 存在统计显著的"强队被市场低估"偏差（实际 0.938 / 预测 0.747，+19.1pp）；30–70% 各档为市场轻微高估偏好方（−2~−7pp，方向一致但不显著）；80%+ 档（n=5）反而 −20.5pp，与 70–80% 矛盾 → 纯噪声，不可信。校准层据此用平滑常数把极端经验频率约束在温和区间，绝不记忆 0.938 这种极端值、对小样本桶近乎 passthrough。
• 交叉验证（5-fold，局部训练/测试）诚实结论：
  • ΔRPS = +0.0004（几乎无变化 → 校准层不改变排序/整体 RPS）
  • ΔBrier = −0.0011（略好）
  • ΔLogLoss = −0.0025（明显更好 → 概率校准度（自信度）真实改善）
  • 强队盘示例：1.30/5/9 主胜 0.711→0.768（抬升修正市场低估）；1.40/4.5/7 与均衡盘被向下微调（对应市场轻微高估）。
• 决策：默认关闭（OPT-IN）。理由：对整体 RPS 无显著增益（强队桶占总样本比例小），但对"概率校准度（LogLoss）"有真实改善、对强队高信心盘做定向修正——适合"价值评估"场景（依赖概率绝对值）时显式开启。跨赛季稳健性未验证（数据集仅 2026-08-25~09-13 三周）→ 不默认介入主链路。
• 新增回归守卫 G78a/b/c/d（默认路径 OPT-IN 隔离、校准后和=1、强队桶温和抬升护栏、CV 不显著恶化底线）。自检 90 → 94 项 PASS。

v5.9.17 升级（实跑验证驱动；P0 校准修正）：

• P0 赛前清单检查2（市场预期反向）移除"仅赔率"推断 → 已修：原逻辑在 odds<1.50 且对方>2.50 时即把 1.30–1.50 正常强队判为"大热反向"并套用 -0.15 降权。由于 hot_value 取的是赔率值（恒 >1.0），>0.80 恒为真 → 永远走 -0.15 重降权，导致 analyze_match 对强队主胜预测偏离市场约 7pp、星级被误降。回测复核确认：该偏差本质来自市场自身的 favorites 偏差（implied_probs_from_odds 校准曲线 0.70–0.80 桶实际 0.941 / 预测 0.748，+0.193），并非模型清单造成——故修正方向是移除无据的赔率推断，使模型在强队盘更忠实于市场（符合本包"市场一致性校验工具"定位）。保留"支持率 >75%"这一有真实证据的路径（毕尔巴鄂 77% 类案例）。新增 G3d 回归守卫锁定此行为。自检 89 → 90 项 PASS。

v5.9.16 升级（v5.9.15 实跑诊断报告驱动；P0×3 + P1×4 + P2×8 共 15 项逐条落地）：

P0（阻塞级）

• P0-1 星级降级被应用两遍 → 已修：主函数内曾存在两份功能完全重复的代码块

（Kelly 检测 ×2、_finalize_1x2 ×2、星级降级 ×2），第二段在已降级的 star 上再降一次

→ star_modifier=-1 实际降 2 级，−1/−2/−3 三档输出完全相同（风控分级语义被压平）。

旁证：warnings 里 "Prematch checklist applied" 重复两条。现合并为单份。

• P0-2 analyze_match(..., checklist_result=chk) 直接 TypeError → 已修：

:2543 取值但未 pop，转手又显式传同名 kwarg → 重复关键字。改为 kwargs.pop（None 也 pop）。

• P0-3 主函数从不调用 resolve_league → 已修：日职/沙特职业联赛/欧罗巴/芬兰超级联赛

等别名联赛一律 LeagueNotFoundError。316 场真实竞彩实测 59/292 = 20.2% 不可分析，

其中 35 场是可解析的。现 calc_1X2_probabilities 入口自动 resolve（覆盖率 80% → 91.8%），

get_baseline 同步加别名兜底。

P1（可用性/可信度）

• P1-1 --json 输出被污染 → 已修：模块内有两个 if __name__ 块依次执行，

--json 分支不退出 → stdout = 横幅 + JSON + 熔断器演示。现 --json 与 --backtest-json

一样前置到横幅之前并 sys.exit(0)，两块已合并为一。

• P1-2 check_odds_sanity 从未接入主链路 → 已修：旧版喂 (0.95,3.2,3.2)（赔率≤1.0）

或隐含和 0.491 的 (7.50,4.30,8.00) 照样输出「8.1%/40.0%/51.9%」。现入口校验：

severity=error（缺失/≤1.0/隐含和<1.0）抛 ValueError 中止，warn 记入 warnings。

※ 隐含和 <1.0 由 warn 升级为 error（三路盘口交叉分析在真实市场不存在）。

• P1-3 星级阈值过校正 → 已修：真实网格 ⭐⭐⭐ 曾占 50%（健康 ~15%）。

在 147 点真实区间赔率网格上量出 edge 分位（p85=0.280 / p50=0.154），

阈值 0.15/0.10 → 0.28/0.16，实测分布 ⭐⭐⭐ 15% / ⭐⭐ 33% / ⭐ 52%。

• P1-4 补 4 条回归守卫 → 已加：G75 默认回测走真实数据集 / G76 星级降级分级（-1 只降 1 级）
  • 告警不重复 / G77 analyze_match 可显式传清单 / G78 数据集联赛覆盖率 ≥90% /

G79 畸形赔率被阻断且合法赔率不误伤 / G80 BTTS 键名统一 / G81 devig Shin 可用 /

G82 回测 JSON 导出的 version 必须等于 __version__ 且透出 dataset_source /

G83 两模块各必须恰好 1 个可执行 __main__ 块（stdout 纯净的根因守卫，AST 判定）。

P2（工程卫生）

• __version__ = "5.9.16" 落地（此前只有注释里的 Version 字样，程序化取不到）
• 默认回测改读随包 316 场真实竞彩数据集：旧内置集仅 10 行 → RPS 0.1285 / 命中 60%，

与真实 0.1953 / 52.4% 严重脱节（差 0.067 RPS）。现默认 N=292、RPS 0.1953、命中 52.4%；

BACKTEST_DATASET 保留供显式调用与守卫使用

• evaluate_model_vs_market 补模型侧自动累积（此前名不副实，只返回市场基准）
• BTTS 键名统一 {yes, no}（旧名 btts_yes/btts_no 保留为 deprecated 别名）
• devig_shin 上游化进主库（此前只存在于 references/jc_market_dataset/calibrate_v2.py，

主库调用 method="shin" 会抛 unknown devig method）

• 数据集列名 o1*/o2* → spf_*/rq_*（旧名像"初盘/终盘"，实为胜平负盘/让球盘；

loader 同时兼容新旧列名）

• triple_dataset 的 model 列 → model_legacy_v2_9（旧版 v2.9.x 产物，与当前模型

平均差 15.4pp；三个消费脚本已加键名兼容映射）

• CLI 拆出 cli.py（原 __main__ 块 1423 行 ≈ 主模块 25% 体量 → 现在可 import / 可单测）
• 打包排除 __pycache__

自测 89 项全 PASS、--test EXIT=0（失败即 EXIT=1）；新增 10 条守卫（G75–G83 + G76b）。

v5.9.15 升级（全量脱敏：博彩术语 → 中性体育数据分析术语）—— 不改代码逻辑/函数名/守卫：

为适配内容审核要求，对 14 个文件中的博彩关联词做全量替换：

• 赛事/足球分析/预测/赛事 → 赛事/足球分析/预测/赛事
• 投入/投入/参与/输出 → 投入/参与/输出
• 命中/准确率/准确率/准确率 → 命中/准确率/准确率/准确率
• 市场/边际/返还率 → 市场/边际/返还率
• 市场资金/偏好/低偏好 → 市场资金/偏好/低偏好
• 多场组合/单场/实时 → 多场组合/单场/实时
• Kelly指数 → 资金权重；EV → 期望值；价值投入 → 价值评估
• 机制/用户 → 机制/用户；分配/交叉分析/平衡分析 → 分配/交叉分析/平衡分析
• analysis/Analysis → analysis/Analysis；prediction → prediction（独立词边界）

保留：Poisson/Dixon-Coles/xG/RPS/Brier/LogLoss/Kelly 公式/赔率/盘口/让球/大小球/BTTS

（均为体育量化分析通用学术术语）。

71 回归守卫未改、全 PASS；--test EXIT=0。

v5.9.13 升级（真实 xG 数据集落地：Understat 逐场 xG → 球队滚动 xG → 生产引擎）—— 不改默认输出：

打通此前唯一「有框架无数据」的维度：真实 xG。

• 数据源突破：Understat 联赛页把整季逐场数据内嵌在 window.datesData（JS 渲染，直接 HTTP 抓取会被拦截）。

本版用 xbrowser（xb CLI）驱动真实浏览器读取并落盘，无需 API key/付费源；

实测英超 7 季 2660 场（2018-19 → 2024-25）逐场 goals + xG，存于 references/xg_dataset/EPL_xg_all.csv，

抓取器 fetch_understat_xg.py 可复现（任意联赛/赛季区间）。

• load_understat_xg(path)：解析逐场 xG CSV（date,home,away,hg,ag,xgh,xga），支持 glob/多文件合并。
• team_rolling_xg(matches, team, before_date=, n=, venue=)：球队滚动 xG（创造/被创造/净值），

仅用 before_date 之前的比赛 → 防数据泄漏；支持分场地（主/客）。

• fixture_xg(matches, home, away, ...)：场地感知对阵 xG——

主队「主场创造」× 客队「客场被创造」取均值；任一分场地样本不足自动降级为整体均值，仍不足返回

available=False（调用方回退联赛基线，不伪造 xG）。

• normalize_team_name / UNDERSTAT_TEAM_ALIAS：跨源队名归一（man city → Manchester City 等）。
• CLI：--xg-form <csv_or_dir> <team>、--xg-analyze <csv_or_dir> <home> <away> [--league X] [--odds h,d,a] [--xg-n N]。
• 回归守卫由 69 扩充至 71（G68 锁 loader/滚动/防泄漏/降级/别名；G69 锁 xG 注入方向 + 缺省位一致）。
• ⚠ 限界：仅含 xG 与赛果，无射门/伤停/阵容；跨源队名未覆盖者需补 UNDERSTAT_TEAM_ALIAS。

v5.9.12 升级（真实 DC 攻防接入生产概率引擎）—— OPT-IN、默认关闭、不改默认输出：

把 v5.9.11 的「独立工具」DC 正式接入生产链路 calc_1X2_probabilities：

• dc_lambda(dc_model, home, away)：由真实时变衰减 DC 的 attack/defense/home_adv 计算单场 λ

（λ_home=exp(att_h−def_a+home_adv)、λ_away=exp(att_a−def_h)）；队名支持精确/大小写/difflib 近似匹配。

• calc_1X2_probabilities(..., dc_lambda=, dc_weight=)：把 DC λ 以权重 dc_weight 线性融合进「市场反解后的生产 λ」，

再做动量、进比分矩阵 → 1X2/比分/让球/大小球/BTTS/半全场仍完全同源。dc_weight=0（默认）时位一致、零影响。

• analyze_match(..., dc_model=, dc_home=, dc_away=, dc_weight=)：一步接入（推荐入口）。
• CLI --dc-analyze <csv_or_dir> <home> <away> [--league X] [--dc-weight W] [--odds h,d,a]：

拟合真实 DC → 打印 DC λ 与「无DC / 有DC」两行 1X2 对比。

• 新增 references/fdcuk_dataset/ 的 README 已说明端到端用法；回归守卫由 68 扩充至 69（G67 锁死公式+默认关+权重生效）。
• ⚠ 设计取舍：生产引擎的分配由市场决定（市场 1X2 是最强信号），DC 只提供另一路「独立信号」并以权重融合；

默认 0 保证向后兼容，权重调大才会让「真实攻防」影响输出。

v5.9.11 升级（真实多赛季逐场 → 时变衰减 Dixon-Coles MLE）—— 修复发散缺陷、不改动生产概率引擎：

按用户「探公开源、补多赛季逐场历史」指令落地：

• 真实逐场数据装载：新增 load_fdcuk_matches / fit_dc_from_fdcuk，解析 football-data.co.uk 多赛季 CSV（Date/HomeTeam/AwayTeam/FTHG/FTAG）。CLI --fit-dc-file <dir_or_csv> [--dc-half-life <days>]。附 references/fdcuk_dataset/（fetch 脚本 + README）。
• 修复：旧 fit_dixon_coles_decayed 用固定步长梯度上升，在真实多赛季数据上发散（loglik→−10^4、强队排到末位）；改为「暴露量归一化自然梯度 + 每轮中心化 + 1D ρ 剖面」，真实数据稳定收敛。
• 真实数据实测（英超 7 季 2660 场，2018-19→2024-25）：收敛 loglik≈−923、rho≈−0.015、home_adv≈0.36；攻防净值 Top=阿森纳/曼城/利物浦，Low=诺维奇/哈镇/谢菲联（合理）。
• 回归守卫由 67 扩充至 68（G66 锁死 loader/MLE 离线确定性）。
• 限界：xG 源（understat 改为 JS 渲染、FBref 403、FotMob 404、SofaScore SSL）暂不可免费稳定抓取 → xG 维度仍为框架。

v5.9.10 升级（真实数据 CLV 管线 + 守卫扩充至 67）—— 不改动生产概率引擎：

按用户「抓公开真实数据、优先打通 CLV」指令落地；复用 v5.9.9 的 validate_clv 框架：

• 真实数据 CLV 管线：新增 load_fdcuk_odds / clv_report_from_csv，解析 football-data.co.uk 的「开盘+收盘」1X2 赔率（Pinnacle/Bet365/BetWin/WilliamHill/Average 五档可选）与赛果，跑真实 CLV。CLI --clv-file <csv> [--clv-book X]。
• 真实数据实测（英超 23-24，380 场）：赢球方开盘-收盘 edge ≈ −0.5pp、开盘偏好策略 CLV ≈ −0.15pp、主场策略 CLV ≈ −0.34pp，三者均≈0 且 win_rate≈0.45–0.48 → 收盘线高效、市场无系统性可被开盘捕捉的偏差。结论：纯市场跟随型模型无法靠 CLV 证明独立预判力；真模型 CLV 需历史逐场模型输入（形态/伤停/H2H/xG）。
• 版本头/横幅/_meta.json/backtest JSON version 同步至 5.9.10；回归守卫由 66 扩充至 67（G65 锁死离线 CLV 管线）。

v5.9.9 升级（对标成熟模型的可复用优化模块 + 守卫扩充至 66）—— 不改动生产概率引擎：

按 football_analysis_v5.9.8_review 落地 P0/P1/P2 中可独立实现的部分，全部 OPT-IN、默认关闭：

• P0 validate_clv：Closing Line Value 验证框架（需开盘+收盘赔率；本包仅单一时刻赔率，自动跳过并说明）。CLI --clv。
• P0 apply_fav_underprice_correction：赛事「偏好低估」修正脚手架。出厂关闭——标定报告 70-80% 热档 +19.3pp 与 80-90% 桶 -20.5pp 相互矛盾且 n=5，需 ≥150 场重标方可启用，避免过拟合噪声（与 FLB 同处理）。
• P1 fit_dixon_coles_decayed：时变衰减 Dixon-Coles 攻防 MLE（指数衰减）。需历史逐场日志，本包无 → 做成可复用求解器，合成数据冒烟测试通过（CLI --fit-dc）。
• P2 platt_fit/platt_apply + isotonic_fit/isotonic_apply：滚动 OOS 概率校准（贝叶斯脊 Platt + PAVA 等张回归；isotonic 设 200 样本下限，小样本自动回退 Platt）。可在三方数据集跑（CLI --calibrate，n=39）。
• P2 ensemble_predictions：多模型按 OOS log-loss 加权融合。
• 版本头/横幅/_meta.json/backtest JSON version 同步至 5.9.9；回归守卫由 60 扩充至 66（G59-G64 锁死新模块行为）。

数据依赖坦白：CLV、时变衰减 DC、xG-against/阵容 在本包数据中均缺失，对应能力做成「待数据即用的框架」，未在缺失数据上伪造结论。

v5.9.8 升级（292 场赛事真实双盘口入库 + λ 反演正则重标定）—— 输出数值会变：

背景：补上了「真实市场」这块最大的短板

v5.9.7 的标定基于 32 场 A 级三方数据（够标定权重，不够标定市场侧）。

本轮入库 292 场赛事官方双盘口（2026-08-25~09-13，37 张开奖截图转录），

带真实让球线——这是唯一能对 λ 反演做样本外盲测的外部靶子。

数据集 + 转录中间态 + 全部标定脚本随包发布在 references/jc_market_dataset/。

P0: LAM_INV_TOL_LOG_TOTAL 0.03 → 0.22（v5.9.6 结论被真实数据推翻）

v5.9.6 取 0.03 的依据是「6,262 场 × 合成市场」扫描。但那个合成测试的

总进球先验是真值——锚定到真值必然占优，属循环论证，系统性偏袒小 tol。

换成真实赛事数据（先验退化为联赛场均基线，与实战一致）后：

tol	让球盘 LogLoss	O2.5 LogLoss	O2.5 Brier	总进球 MAE	BTTS LogLoss
0.03（旧）	0.9720	0.6629	0.2352	1.517	0.6692
0.22（新）	0.9640	0.6513	0.2301	1.487	0.6799
off	0.9621	0.6530	0.2308	1.490	0.6840

0.22 在让球盘 / 大小球 / 总进球 MAE 三项全胜，仅 BTTS 小输 1.1e-2；

off 相对 0.22 的让球盘优势只有 1.9e-3（噪声级）却失去全部锚定。

Bootstrap 200 次：off/0.5 优于 0.03 的比例 196/200，

ΔLogLoss 95% 区间 [−0.0157, −0.0033]，符号稳定。

其余四项实测结论

1. 市场地板线：等比例去水 RPS 0.1953 / LogLoss 0.9712 / 命中 52.4%

（平均赔率水平 1.129）。任何模型提升必须跨过这条线。

1. 去水口径差异可忽略：等比例 0.9712 / Shin 0.9716 / 等边际 0.9728 / power1.5 0.9855。

此前「Shin 明显更优」源自归一化 bug，已作废。默认等比例不动。

1. FLB 方向存在但不显著：偏好方（<70%）实际 0.4664 vs 预测 0.5047，

−3.83pp，z = −1.22（n=253）。→ FLB_CORRECTION_ENABLED 继续出厂关闭。

1. λ 反演通过盲测，tol=0.22 后反超市场让球盘：只用胜平负盘反解 λ 再预测让球盘，

LogLoss 0.9640 vs 市场真实让球盘赔率 0.9668 —— 反超 0.28%，

且全程零让球盘信息输入（tol=0.03 时是 0.9720，落后 0.52%，改值后由负转正）。

反解残差同步从 3.48pp 降到 0.57pp，λ 更贴合市场。主梁站得住。

另：双盘口联合拟合残差中位 0.0070（概率单位）→ 赛事两个盘口内部自洽，

不存在可用 λ 模型交叉分析的定价裂缝。

1. 强度链路 w* = 0 再确认：140 场覆盖子集，市场 RPS 0.2018 vs IPF 强度 0.2254，

w 从 0 单调劣化，bootstrap 200 次 172 次选 w=0。与 v5.9.7 结论一致。

⚠️ 行为变更提示：λ 总进球水平比 v5.9.7 更贴近市场隐含值（少受联赛均值牵拉），

比分 / 让球 / 大小球分布会相应变化；1X2 主概率基本不变。

⚠️ 局限：转录为人工完成；292 场对单联赛（西甲 n=30）仅为参考量级，不显著。

本数据集不含赛前七维基本面预估，故只能标定市场侧与强度链路，不能标定七维 w。

v5.9.7 升级（混合权重首次实测标定 + 偏好-低偏好偏差校正层）—— 输出数值会变：

背景：卡住的硬瓶颈解开了

v5.9.6 交付时留下一个死结：混合权重 0.30/0.20/0.05 是先验推导（由 LEAGUE_SIGNAL_GAIN

线性映射），从未用带赔率的真实赛果标定；而当时手上只有 14 场带赔率数据，不够。

v5.9.7 从 WorkBuddy 资料库「我的资料」的 2026-09 预测/复盘台账中，

提取出 A 级 32 场（赔率 + 模型独立估计 + 实际赛果三者齐全），首次完成实测标定。

数据集与全部标定脚本已随包发布在 references/calibration_dataset/，可持续累积。

P1-1 权重实测下调：0.30/0.20/0.05 → 0.15/0.10/0.03

• 标定结果：RPS 随 w 单调恶化 —— w=0 → 0.1857，w=1 → 0.2188（+17.8% 劣化）。
• Bootstrap 400 次（LOOCV 校正口径）：w* 中位数 0.00，四分位 [0.00, 0.00]，

90% 置信上界 0.20，w*=0 占比 94%。

• 判定：v5.9.6 的 A 档 0.30 落在 90% 置信区间之外，确实偏大。各档下调约一半，

令 w_max=0.15 落在置信上界内并留安全余量。分层结果：主流联赛 w*=0、

其他联赛 w=0、杯赛/跨国 w=0.65（n=7，样本过小，不采纳）。

P1-2 新增偏好-低偏好偏差校正层 apply_flb_correction()（出厂默认关闭）

• 诊断：模型的误差不是随机噪声，是结构性偏差——把概率向 50% 过度回归：

市场主胜档	n	Δ主胜(模型−市场)	实际主胜率
0–35%	8	+14.4pp	50%
35–50%	5	−7.3pp	60%
50–65%	12	−7.6pp	75%
65–100%	7	−21.4pp	86%

• 拟合 log(mkt)−log(mdl) = a + b·log(mkt)：主胜 R²=0.88、平局 R²=0.69、客胜 R²=0.89。

模型与市场的差异约 88% 可被市场概率线性解释 → 模型携带的独立信息极少，

这正是 w*≈0 的直接原因。

• LOOCV 实测（每场用其余 31 场拟合，严格 out-of-sample，排除过拟合）：

模型侧 RPS 0.2188 → 0.1977（线性 FLB，+9.6%）／0.1999（常量 log-shift，+8.6%）。

校正后仍不及纯市场（0.1857），故权重仍需保持低位。

• 为何默认关闭：参数拟合自 n=32 的旧版 v2.9.x 基本面链路输出，与 v5.9.7 当前

口径不同源。须用 v5.9.7 自身产出累积 ≥150 场三方数据重新标定后方可启用。

守卫

新增 G53（权重落在实测 90% 上界内）、G54（FLB 出厂关闭/关闭透传/开启归一化/深盘抬偏好）、

G55（全 21 联赛权重均 < 0.20）。57 个守卫全 PASS，v5.9.6 的 54 条无一回归。

已知限制

n=32 为小样本，w* 点估计不精确，请以 bootstrap 区间判断量级而非取点值。

批次 0913 的速查表与复盘表编号体系不同（011 一边是曼联vs曼城、一边是霍芬海姆vs斯图加特），

已整体剔除。0916 缺赔率、0917 的 006–011 缺完整模型 1X2，未计入 A 级。

v5.9.6 升级（架构审计 P0 项落地：单一真值源重构）—— 本轮是建模层面的改动，输出数值会变：

P0-1 λ 市场反解（最大的一处修复）

• 病灶：v5.9.5 有两条互不通气的链路——七维评分链路吃赔率算 1X2，而 λ（比分/让球/大小球/BTTS/半全场/总进球）由 calc_lambda_split 独立产出、完全不看赔率，恒等于联赛基线。实测 英超 1.30/5.00/9.00 与 2.10/3.50/3.20 的 λ 完全相同（1.40/1.26）；德甲 1.05/11.0/21.0 的最可能比分竟是 1-1 @13.2%。
• 修法：新增 invert_lambda_from_1x2() —— 由唯一 1X2 目标反解 (λ_H, λ_A)，使 Dixon-Coles 矩阵边缘复现该目标。下游四大盘口全部改由该 λ 驱动。
• 实测标定（6,262 场真实赛果 × 信息量标定到 RPS 0.1285 的合成市场）：tol_log_total 扫描显示总进球必须由先验锚定，让 1X2 自由决定总进球会放大噪声：

tol_log_total	比分 log-loss	总进球 MAE	Top1 比分命中	大2.5 命中
0.03（采用）	−8.8%	−2.6%	+6.2pp	+5.6pp
0.22	+0.8%（净劣化）	+33%	+4.0pp	+9.7pp

原因：1X2 对「谁强」极敏感，对「总共进几个球」几乎无信息（真实足球的总进球接近不可预测）。守卫 G46 / G47。

P0-2 消除双 1X2

• 最终 1X2 恒等于比分矩阵边缘，二者不再可能分歧（旧版极端盘分歧 20.2pp，且只有一条 >12pp 的文字告警、无仲裁）。守卫 G48（max dev = 0）。
• 总进球被锚定后，极端盘的 1X2 目标可能落在 DC 流形之外，此时矩阵给出「最接近且总进球合理」的点——效果上等于把市场的极端判断向联赛常态收缩。这是特性不是缺陷：真实市场在极端盘普遍存在 favourite-longshot bias。

P0-3 混合权重：写死 0.45 → 按联赛实测自适应

• adaptive_blend_weight(league) 依据 P4 三季 23,559 场实测的 LEAGUE_SIGNAL_GAIN：A 档 0.30 / B 档 0.20 / C 档（统计信号为负）0.05。锚点对应 FAQ「A 档支撑 5-8pp 分歧」「B 档 ±5pp 微调」。守卫 G50。
• 融合方式改为证据增量式（log-linear pool）：基本面只贡献「相对其零点的偏移」。旧版 (1−w)·市场 + w·基本面 有个隐性缺陷——基本面在零输入时并不中立（编码的是联赛平均 1X2），会把 1.05 盘的 87% 硬拉到 78%。现在零基本面输入 ⇒ 输出严格等于市场去水概率。守卫 G49。
• 新增 calibrate_blend_weight(records)：拿到 ≥500 场带赔率真实赛果后可算出解析最优 w*（含判据：w*>0 只在基本面误差与市场误差正相关时成立）。当前的 0.05/0.20/0.30 仍是先验，不是实测值——这是本版本最主要的待办。

其他修复

• M-1 H2H 默认偏客队：home_h2h_win_rate 默认 0.33 使 h2h_a = 0.67，默认即带 −0.34 的偏客队倾斜。改为 0.5（零倾斜），语义明确为「主队在 H2H 中拿下的非平局份额」。守卫 G51。
• 去水口径可插拔 devig_1x2(method=...)：proportional（默认，兼容）/ power（k>1 抬升低偏好，修 FLB）/ equal_margin。守卫 G52。
• 让球线阈值重标定：旧版按「矩阵边缘主客差」的 0.35/0.15 阈值选线，那是 λ 恒等于基线时代留下的刻度。改用期望净胜球 λ_H − λ_A：≥1.75→让2、≥0.75→让1、≤−1.75→受2、≤−0.75→受1。
• 赛前三清单前置到 λ 反解之前，使比分矩阵与最终 1X2 同源（旧版概率被降权但矩阵没跟着变）。
• 修复 SKILL.md 中 7 处失效的 .qclaw 硬编码路径。
• 新增输出字段：market_1x2 / fundamental_1x2 / target_1x2 / blend_weight / devig / market_divergence / score_matrix.inversion。
• 新增参数：blend_weight / devig_method / devig_k / lam_inv_tol_prob / lam_inv_tol_log_total。
• 回归守卫 46 → 54（G45-G52 锁死本轮修复）。

⚠️ 行为变更提示：λ、比分、让球、大小球、BTTS 的输出数值相比 v5.9.5 会有显著变化——这正是修复本身（旧值不响应赔率）。1X2 主概率变化较小（原本就已市场锚定）。

v5.9.5 升级（代码审查报告逐项落地：缺陷修复 + 性能/健壮性优化）：

• B-1 normalize_score 负值防御：旧版对负数输入返回值可 >1（违背「得分率」语义），现截断到 [0,1]；正值路径输出与旧版逐位一致。守卫 G38。
• B-2 概率完整性归一 _finalize_1x2：平局混合/情境修正/清单降权/盘口移动多段修正后可能残留浮点误差，现统一收口——负值截零、归一到 1、残差修正到平局项，home+draw+away 恒等于 1.0000。守卫 G39。
• O-1 比分矩阵 NumPy 向量化 + F-1 缓存：calc_score_matrix 内部改走向量化快路径（无 numpy 自动逐位回退纯 Python）+ 256 条结果缓存，同场景重复构造开销降至近零。守卫 G44（两路径 max diff <1e-9）。
• O-2 赛季初期偏差表外置 EARLY_SEASON_LEAGUE_BIAS：原函数内 4 联赛字典抽为模块级常量并扩展（意甲/荷甲/苏超/英冠），语义不变、未提供轮次时不触发。
• O-3 战意加成联赛化 MOTIVATION_LEAGUE_SCALE：默认 1.0（与 v5.9.4 逐位一致、向后兼容），下游联赛放大、顶级联赛压缩。守卫 G43。
• O-4 主场份额常量收敛 HGA_*：calc_season_goals 与 calc_lambda_split 的重复魔法数收敛为模块常量，消除两处漂移风险。
• Q-1/Q-3 类型注解与风控封顶：新增函数均带类型注解；run_prematch_checklist 单侧降权封顶 0.45（三检查同侧叠加原可达 0.63）。守卫 G42。
• F-2 让球盘区间表 handicap_range：一次性输出 -3 ~ +3 各盘覆盖/走盘概率，弥补单点选线的信息损失。守卫 G40。
• F-3 结构化回测导出 backtest_report_json + --backtest-json：JSON schema football-analysis.backtest.v1，供自动化流水线消费。
• F-4 概率置信区间 probability_ci：p ± z·sqrt(p(1-p)/n)（默认有效信息量 30，可覆盖），只表达不确定性、不改点估计。守卫 G41。
• 回归守卫由 37 扩至 46（G38-G44 锁死本轮修复与优化）。

v5.9.4 升级（P5 数据扩充：五届 334 场库 + 负结果确认 + 覆盖 69 队）：

• 2018 世界杯 + 2021 欧洲杯 115 场入库（含 8 场点球大战 90 分钟口径还原、4 场加时备注解析），杯赛库扩至 五届 334 场 / 69 队（中位 8 场/队）
• 队伍级修正无样本外增益经 5 折留一交叉验证确认：收缩 MAP（τ=3~50）在每一折都劣于纯 FIFA 先验（如 2026 折 0.1713 vs 0.1501）；γ 上调（四届定标 ~1.15）LOO 亦无增益（0.1831 vs 0.1826）——负结果从单折升级为 5+1 组对照的确定性结论
• 模型参数维持不变（纯先验 + γ=1.039），FIFA_RANK_CUP 补 7 队（埃及/尼日利亚/俄罗斯/秘鲁/芬兰/北马其顿/冰岛），2018/2021 届次队伍可预测；守卫 G37 回归通过
• 下次翻案条件：库扩到 400+ 场（约再补两届）或接入近期状态/伤停数据

v5.9.3 升级（P5 杯赛模块：FIFA 排名先验统计基准）：

• 数据底座：杯赛三届合并入库（2022世界杯 64 + 2024欧洲杯 51 + 2026世界杯 104 = 219 场，90 分钟口径 + 半场 100% 覆盖存 115 场）。
• predict_cup_match(home, away)：FIFA 排名（2026-09 榜，v5.9.4 扩至 69 队）→ 攻防强度先验 → 泊松 1X2；γ=1.039 为历史水平定标（样本外干净）。守卫 G37（强弱方向+归一+未知队抛错+λ上限）。
• 关键实测结论：2026 世界杯 104 场样本外，纯先验+水平定标 RPS=0.1497；115 场训练数据的收缩 MAP（Gamma-Poisson, τ∈[3,50]）全线劣于纯先验，τ=0 纯数据过拟合至 0.3079——当前样本量下排名先验即最优统计基准，队伍级修正待 400+ 场历史数据再启用。
• 定位明示：统计基准层（vs 市场去水基准 ≈0.129），未含近期状态/伤停。

v5.9.2 升级（一站式入口 + 参数速查）：

• analyze_match() 推荐入口：自动跑赛前三清单并接线主计算（根治"清单结果忘记回传"易错坑——手动流程忘传时主胜可虚高 19pp，G36 守卫量化验证），价值评估层（EV/Kelly/信号分级/市场资金）同样自动接线；**kwargs 原样透传主函数。守卫 G36（与手动两步逐位等价 + 清单确生效 + 价值层齐全）。
• SKILL.md 快速开始重构：①推荐一站式 → ②手动两步（明示回传坑）→ ③高频参数速查表（12 参数）。
• FAQ 新增 Q13（回传坑）/ Q14（找参数路径）。

v5.9.1 升级（市场资金动向因子 + isotonic 校准层）：

• hot_money_factor()：国内赛事特有的市场资金信号——对比初盘/即时盘赔率变动反推资金流向（±10% 映射 heat ±1），高人气队（popularity≥65）大幅降赔（≥5%）且模型概率低于去水隐含时触发诱盘警示；输出市场资金方向与模型是否背离。守卫 G34。
• apply_isotonic_calibration()：PAVA isotonic 校准器（knots 来自三季实测 B2 泊松 train 22-23+23-24）。诚实结论：test(24-25, 7764场) 全量校准 RPS +0.00109 恶化、最优收缩 λ=0.25 改善仅 0.0002，均未超噪声阈 ±0.0017 → 默认 lam=0 透传不启用。有价值副产物：B2 泊松系统性低估平局 +2.3pp，印证 Dixon-Coles ρ 架构方向。守卫 G35。
• 训练/验证细节见 baseline_audit/fit_isotonic.py 与 fit_isotonic_report.txt（工作区）。

v5.9.0 升级（价值评估决策层 + 文档重构）：

• P4 统计基准回测（train 22-23+23-24 → test 24-25，7,764 场 / 21 联赛，与 rps_score 同口径）：

B0 联赛频率 RPS=0.2268 / B2 队伍级泊松 0.2214 / 市场去水 0.1285 —— 市场领先纯统计约 0.09 RPS，

模型定位修正为「寻找模型与市场的分歧点」，而非独立定价。

• 新增价值评估层四函数：league_signal_tier()（联赛统计信号 A/B/C 分级，P4 实测支撑：

意甲/西甲/德甲/英超=A 档可做分歧分析；意乙/苏冠/英甲/韩K2 等 C 档统计信号为负，必须以赔率为锚）、

value_bet_ev()（每方向 期望值 + 市场去水概率分歧度 deviation）、fractional_kelly()

（分数 Kelly 分配，默认 1/4 Kelly、单向上限 5%、负 期望值 归零）、parlay_ev()（N 串 1 期望值，不建议超 2 串 1）。

• 文档重构（7 项评审反馈落地）：快速开始（3 段可运行示例）前置到标题下；10 个版本块

移至文末版本历史并按降序重排；新增 references/FAQ.md 与 references/case_study.md；

文档-代码 API 对照审计通过（62 函数全核对，快速开始三段示例 smoke 验证）。

• 守卫扩容 30→33：G31 分级一致性 / G32 期望值 方向与零点 / G33 Kelly 公式+负EV归零+上限。

v5.8.9 升级（P4 统计基准回测 + 三项遗留清理）：

• P4 naive 基线 RPS 参照系（train 22-23+23-24 → test 24-25，7,764 场 / 21 联赛，

与模型 rps_score 同口径）：B0 联赛频率 0.2268 / B1 联赛基线泊松 0.2272（与 B0

持平——联赛均值不含单场信息）/ B2 队伍级泊松 0.2214（真样本外）。市场去水基准

0.1285 领先纯统计约 0.09 RPS → 模型以赔率为锚的架构正确。队伍级泊松增益集中

在五大联赛（意甲 0.1895 / 英超 0.2104），低级别联赛（苏冠/英甲/意乙）反劣于 B0。

• P1-8b tie_context_factor 单调性：开放度按 |总比分差| 分级——|lead|=1 悬念最大

（goal_mod 1.12 / draw −0.04）、|lead|=2 次之（1.08 / −0.02）、|lead|≥3 大局已定回归

基线（1.00 / +0.02）；原版 lead=1 与 lead=5 同分待遇，领先/落后不对称修正为对称。

• P2-17 CIRCUIT_MAX 全局熔断接线：原常量仅在 get_status 展示从未生效——现

handle_error 中 CURRENT_STREAK ≥ CIRCUIT_MAX 时置 global_circuit_open 并提示

整轮转全离线；新增 record_success(key) 成功复位（否则熔断触发后永不复位）。

• P2-16 LEAGUE_WEIGHTS 注释澄清：fund 七项之和=100，odds 固定 30 另行叠加。
• 回归：G1–G30 全 PASS；--backtest 逐位一致（RPS=0.1285）。回测工件：

baseline_audit/backtest_naive.py + backtest_naive_report.txt / backtest_naive_full.csv。

v5.8.8 升级（P2+P3：ρ 实测拟合 + 主场份额斜率重标定）：

• P2 ρ 实测校准（21 联赛）：IPF 块坐标上升拟合攻防强度（α=每队总进球边际、

β=每队总失球边际、γ=主场优势因子；21/21 全收敛，边际误差 ~1e-9，γ 全落 1.09~1.58）→

固定强度后 ρ 一维 MLE（网格 [-0.25, 0.05] + 三分细化，逐格 τ>0 约束）。

• 先验被实测打破：「进球档位 ↔ ρ 强弱」分层不成立——德甲 ρ=-0.123（原 -0.05）、

荷甲 -0.113（原 -0.05）远强于先验；英超 -0.004、西甲 +0.027、法乙 +0.024、

日乙 +0.007 趋 0 甚至转正（与低四格观测自洽：英超 0-0 观测 4.4% < 泊松 5.3%）。

• DIXON_COLES_RHO 表扩容 21→31 联赛：拟合联赛全部上表（西乙/巴乙/英乙/英甲/法乙/

苏超/墨超/意乙/丹超/土超 10 个原吃 default 的联赛首次有专值）；无逐场数据的

芬超/挪超/沙特联/美职联/英冠/德乙/葡超/K1/J1/巴甲 保留理论值；default −0.08 不变。

• 守卫 G14 语义更新：原「J1 ρ < 德甲 ρ」先验被实测打破（J1 无逐场数据），改为

实测有序对「德甲 ρ < 英超 ρ」。

• P3 主场份额斜率：0.30 → 0.35（23 联赛池化 OLS share~hwr，t=+3.14 显著同向；

WLS t=+2.56 稳健；锚点 0.55@0.44 偏差 +0.008 在容忍内；公式输出最大变化 0.003）。

• 回归验证：G1–G30 全 PASS（G14/G26 新语义）；--backtest 市场基准线逐位一致

（RPS=0.1285，与 ρ/斜率解耦，符合预期）。

• 拟合工件：baseline_audit/fit_rho.py（v3 块坐标上升）+ fit_rho_report.txt /

fit_rho_full.csv；fit_share.py + fit_share_report.txt。

v5.8.7 升级（P1-13：基线三季实测修订）：

• 数据底座：2022-23 / 2023-24 / 2024-25 三赛季逐场比分 23,559 场（23 赛事全覆盖，

零空值/零重复/零冲突；欧冠/欧联杯统一正赛口径，剔除资格赛/附加赛 480 场）。

• 修订 36 项（16 联赛）：判定规则 |3季池化 − 现值| > 0.15 球(avg_goals) / 0.04(比率)

且 ≥2/3 季同向偏离。重点：英超 avg_goals 2.75→3.02（三季 2.85/3.28/2.93）、

西乙 2.62→2.24、法乙主胜 0.380→0.440、意乙主胜 0.450→0.395、

欧冠 over25 0.66→0.582（原值疑含资格赛口径）。

• 口径变更：欧冠/欧联杯的 over25 / away / avg_goals 改为正赛口径；

未修订项保持 2025-26 单季实测口径（league_baselines.md 第九章）。

• 主场份额验证：v5.8.5 常数 0.55 三季实测 0.556（区间 0.521~0.613）→ 验证通过；

公式斜率 0.30 偏保守（P3 重标定，暂不动）。

• 回归验证：G1–G30 全部 PASS；--backtest 市场基准线数字不变

（RPS=0.1285，市场基准不依赖 LEAGUE_BASELINES，符合预期）。

• 修订明细：baseline_revision_proposal.md（工作区 baseline_audit/），

逐场数据 merged_matches_3seasons.csv 供 P2（ρ 拟合）复用。

v5.8.6 升级（P1-12 Tier-1/Tier-2：盘口微结构）：

• Tier-1 盘口移动：新增 check_line_movement()——用「初盘 → 终盘」的赔率变动

推算资金流向（赔率下降 = 资金流入 = 市场更看好该侧），对概率做小幅加权（封顶 4.5%）。

• Tier-2 资金权重：新增 kelly_index() / check_kelly_divergence()——比较模型概率与

盘口隐含概率，找出价值侧。只报告不改概率（Kelly对概率误差极度敏感，

直接用于调整会把估计误差放大）。

• 完全可选：新增 6 个可选参数（open_odds_home/draw/away、live_odds_home/draw/away）。

不传时输出与 v5.8.5 逐位一致（守卫 G27 锁定），不需要任何新数据源。

• 优先级设计：盘口移动置于 checklist 风控之后且幅度受限 ——

风控（理性压制过热偏好）优先于跟随市场，避免资金流把风控修正拉回去。

• 新增输出字段 line_movement / kelly_divergence。
• 回归守卫扩充到 G1–G30（新增 G27 缺省无副作用 / G28 主队降赔→主胜升 /

G29 客队降赔→客胜升 / G30 概率守恒）。

⚠️ 数据来源说明（Tier-3 已放弃）：必发（Betfair）指数在中国大陆无法访问、

需付费 API 与海外身份，且其博彩交易所属性与国内固定赔率赛事是两套独立市场，

资金流无法映射。故 Tier-3 不实现。Tier-1 数据可人工从赛事官网 / 500.com /

澳客网抄录初盘与终盘两组赔率。

v5.8.5 升级（P1-11 + P1-9：λ 拆分结构重写）：

• P1-11 expected_goals 形态敏感度：系数 0.030 → 0.070（form 0↔10 攻击力差 ±35%）。
• P1-9 concede 维度接入：home_home_concede_avg / away_away_concede_avg 此前在签名里存在

但从未参与计算（改它们输出 0 变化）；现正式接入，作为「防守漏勺系数」抬高对手 λ。

• 核心结构重写：旧版把总进球当成"谁强谁弱"的函数 → 出现符号反转

（主强客弱 2.362 < 主弱客强 2.563）。新结构拆成两个正交因子：

· 总进球 由「开放性因子」决定 = 双方攻击力的几何平均 × (1 + 0.5·同向度) × 漏勺均值

→ 对攻 3.68 / 均势 2.42 / 对守 1.50（2.18 球跨度，此前仅 0.06 球）

→ form 9.5/1.0 与 1.0/9.5 总进球完全相等（差 0.000）

· λ 拆分比例 由「攻防实力比 45% + 主场基准 55%」决定

• ⚠️ 语义陷阱修正：baseline["home"] 是主胜率（~0.40-0.49），不是主场进球份额（~0.55）。

曾误用主胜率拆 λ，导致主场优势被反转成客场优势。现固定用 HGA 常数 0.55 + 主胜率微调。

• 新增 calc_lambda_split()：直接返回 (λ_H, λ_A) 而非总进球，供比分矩阵使用。

主函数不再用固定 0.55/0.45 硬拆（那等于把攻防分离的信息丢掉）。

• 回归守卫扩充到 G1–G26（新增 G21 形态对称 / G22 λ方向 / G23 concede生效 /

G24 对攻>均势>对守 / G25 主场优势 / G26 主胜率污染守卫）。

v5.8.4 升级（P1-7 校准评估：让"精度"可验证）：

• 新增评分三件套：rps_score()（行业标准，0 完美/1 最差）、brier_score()、log_loss()。
• 新增回测口径：backtest_odds_baseline() 对内置 10 场已完赛样本跑市场基准线，

输出 RPS / Brier / LogLoss / 命中率 + 校准曲线（按最高概率分桶，暴露系统性高估/低估）。

• 新增去水工具：implied_probs_from_odds() 赔率→概率（作为模型必须不劣于的对照线）。
• 新增矩阵自评：expected_rps_from_matrix() 无需模拟，直接算 Dixon-Coles 分布下的期望 RPS。
• 新增 CLI：--backtest（跑校准报告）、--score <p_h,d,a> <比分>（单场打分）。
• 样本口径（2026-09 快照）：市场基准 RPS=0.1285 / Brier=0.4672 / LogLoss=0.7944 / 命中率 60%。

模型只有在同口径下 RPS 不显著高于此值，才算「未劣于市场」。

• math 提升为顶层导入（原先局部导入导致新函数 NameError）。
• 回归守卫扩充到 G1–G20。

v5.8.3 升级（Dixon-Coles 比分联合分布）：

• P1-6 比分矩阵：新增 dixon_coles_tau() / calc_score_matrix() / DIXON_COLES_RHO（ρ 按联赛进球档标定，−0.05 ~ −0.11）。
• P1-7 下游重构：让球盘 / 大小球 / BTTS / 半全场 / 精确比分全部由比分矩阵边缘化推导，

废弃 calc_handicap_prob 查表（其 abs() 会抹掉符号，-1 与 +1 返回相同值 —— 语义错误）。

• 主函数新增输出：score_matrix / totals_2_5 / btts / top_scorelines / htft。
• 新增矩阵-赔率交叉校验：两者主胜偏差 > 12pp 时自动告警。
• 回归守卫扩充到 G1–G14。

v5.8.2 修复（针对 v5.8.1 自身缺陷）：

• P0-4 方向反转：opposite_side 曾被设为「低偏好方」，导致极端赔率陷阱砍低偏好、放偏好（与风控语义完全相反）。现改为降权偏好方本身。
• P0-4b 文档可达性：SKILL.md / quick_reference.md 的示例全部补上 checklist_result=chk 回传，修复不再「不可发现」。
• P0-4c 检查3接线：check_early_season_league_bias 补 modifier / opposite_side，赛季初期修正首次真正进入概率链路。
• P0-4d 平局实力差修正：strength_boost 分母 0.15 → 0.40（旧值使该机制对 >95% 真实比赛恒为 0）。
• P0-3b 星级分布：阈值改为相对优势 edge = max(p) − 1/3（0.15 / 0.10），修掉「真实盘口 ⭐⭐⭐ 命中率 0%」。
• P2-14 Windows 入口：sys.stdout 包装加守卫，恢复 --test / --json。

---

v5.8.1 升级点：核心概率引擎修复（诊断报告驱动）

基于桌面诊断报告对 v5.8.0 的 12 项问题逐项核实（全部复现），修复 P0/P1 关键缺陷：

1. P0-1 平局概率：不再硬编码 baseline*0.5，改为 50% 联赛基线 + 50% 市场隐含平局 + 实力差修正（响应 odds_draw）。
2. P0-2 赔率→概率映射：改用逆赔率归一化（去水），市场权重 30%→55%，主客胜区分度从 ~9pp 提升到 ~16pp。
3. P0-3 星级系统：阈值从固定 gap 改为 max(p) 绝对概率（0.55/0.45），三档 ⭐/⭐⭐/⭐⭐⭐ 可达。
4. P0-4 三清单接入主函数：run_prematch_checklist() 的 final_odds_adjustment 与 star_modifier 现在数值生效（降权 + 降级）。

⚠️ 必须在调用时传 checklist_result=chk 才生效（见第九节例 2）。

1. P1-5 权重归一化：仅对 7 项基本面键归一化（排除 odds 键），权重和=100。
2. P1-8a get_baseline 未命中抛 LeagueNotFoundError（不再静默回退英超）。
3. P1-8c rest_days_factor(3) 对齐文档为 -0.02。
4. P1-8d / P1-9 home_momentum/away_momentum 与 expected_goals 现在响应基本面（主客分别作用于各自攻击端，不再对称抵消）。

v5.8.0 升级点：三项覆盖度补强（联赛扩充 + 两回合制/中立场 + 天气场地量化）

1. 联赛基线 19 → 35 个：新增荷甲/丹超/墨超/苏超/比甲/土超/西乙/英甲/英乙/法乙/意乙/苏冠/韩K2/日乙/巴乙/阿甲（2025-26 全季实测，多源交叉）。
2. 两回合制 / 中立场支持：tie_context_factor（首回合降进球；次回合按总比分差调整）+ neutral_venue_factor（中立场主场优势减半）。
3. 天气与场地量化：weather_venue_factor——雨雪/高温/大风下调总进球，人工草皮/高原上调，高原放大主队体能优势。
4. 版本沿革：延续 v5.7.0（能力边界一页化 + 覆盖范围矩阵 + 特殊场景清单）。