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

当前版本 v5.9.16 · 35 联赛基线 · 31 联赛实测 ρ · 89 项自测全 PASS（含 78 条回归守卫） · 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）

| 参数 | 类型/默认 | 说明 | |------|----------|------| | league | str, 必填 | 联赛名（35 联赛收录，别名/模糊匹配自动纠错） | | odds_home/draw/away | float, 必填 | 官方三项赔率 | | home_form / away_form | 0-10, 默认 5.0 | 近期状态分 | | home_home_goals_avg 等 4 项 | float, 可选 | 场均进/失球（主场/客场各自口径） | | home_key_missing / away_key_missing | int, 默认 0 | 缺席主力人数 | | home_h2h_win_rate | 0-1, 默认 0.33 | 交手胜率 | | xg_home / xg_away | float, 可选 | xG（传入则替代形态法估球） | | rest_days_home/away | int, 可选 | 休息天数（赛程拥挤因子） | | current_round | int, 可选 | analyze_match 参数，开季偏差检查用 | | open_odds | dict, 可选 | analyze_match 参数，初盘（触发市场资金因子） | | neutral_venue / leg / aggregate_lead | - | 中立场 / 两回合制 |

📖 去哪找什么

| 想找 | 位置 | |------|------| | 常见问题（参数怎么传/星级为何降/结果怎么解读） | references/FAQ.md | | 完整案例（输入→比分矩阵→输出→逐步解读） | references/case_study.md | | 全部函数签名速查表 | references/quick_reference.md | | 35 联赛基线参数 | references/league_baselines.md | | 能力边界（能做什么/不能做什么） | 下文「能力边界一览」 | | 历次版本改了什么 | 文末「版本历史」 |

---

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

| 文件 | 里面有什么 | 什么时候打开 | |------|-----------|-------------| | SKILL.md（本文件） | 使用说明、操作流程、能力边界一览（开头，唯一权威）、问题解答 | 想知道「怎么用 / 能不能做」 | | references/quick_reference.md | 所有数据表 + 函数速查 + 常量 + 阈值 + 代码示例 | 想知道「数据是多少 / 函数怎么调」 | | references/league_baselines.md | 基线详细来源、赛季快照、转会明细、杯赛/小联赛背景 | 想深挖某个数字的出处 | | football_calc.py | 计算引擎（计算库，可 import） | 要跑计算 / 二次开发 | | cli.py | 命令行入口（v5.9.16 拆出，原占主模块 25% 体量） | 跑 demo / 自测 / 各 CLI 开关 |

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

---

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

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

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

A. 能做到 ✅

| 能做什么 | 说明 | |---------|------| | 识别输入并解读 | 赔率截图/文字 → 识别场次、联赛、对阵 | | 七维基本面分析 | 实力 / 状态 / 伤停 / 主客 / H2H / 战意 / 赛程 | | 35 联赛基线校准 | 内置场均进球、主客胜率、赛季分期、xG 基线 | | 三项强制风险检查 | 极端赔率 / 市场大热（看好度 >75%）/ 赛季初期 | | 实力差距方向分析 | 给方向与星级；比分只给参考区间 | | 输入错误主动提示 | 联赛名、赔率数字有疑点先提示再继续 | | 数据来源标注 | 每条关键数据标 A/B/C/D 可靠性等级 | | 离线兜底 | 无网络时用内置基线，精度约 80%（推导见十三） | | 赛后核验 | 检索结果 → 逐场比对 → 失败维度归因 → 回填基线 |

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

| 能力 | 前提条件 | 不满足时 | |------|---------|---------| | 联赛识别 | 联赛名可辨识，或能从对阵推断 | ⛔ 停下，请你确认 | | 赔率解读 | 赔率填写正确（>1.0、结构合理） | ⛔ 停下，请你核对 | | 35 联赛内分析 | 属于内置基线联赛 | 按最接近联赛估算，误差 ±15–20%，星级 −1 | | 小联赛 / 次级联赛 | 你补充关键信息（排名 / 伤停 / 近况） | 只给方向，星级 ≤ ⭐，不出比分 | | 极端低赔解读 | 你确认是「0 档」还是「实力差距档」 | 给风险提示后继续 | | 情报检索 | 国内源可访问 | 自动重试 3 次 → 离线基线兜底 → 熔断跳过 |

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

| 做不到 | 原因 | 替代做法 | |--------|------|---------| | 精确比分 | 低概率事件，对比率 ≈ 0% | 只取方向 + 最可能比分区间 | | 半全场精确预测 | 历史对比率 30–40% | 仅作娱乐参考 | | 临场首发阵容 | 赛前 2–4 小时的信息无法反映 | 官方首发公布后你补充，再重算 | | 赛季初期强队 / 新援队的精确判断 | 磨合期，基线失效 | 降星级，只看方向 | | 杯赛淘汰赛的精确判断 | 战意分化、轮换、两回合规则 | 说明假设，或建议不做该场 | | 实时赔率变动追踪 | 只分析你截图那一刻 | 赛前 30 分钟重新截图 | | 保证数据最新 | 离线 / 检索失败时不保证时效 | 关键数据自行核实 | | 内幕与突发伤病第一手消息 | 只依赖公开信息 | — |

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

| 范围 | 状态 | 说明 | |------|------|------| | 五大联赛（德/英/西/意/法） | ✅ 完整 | 基线与情报最齐 | | 其他主流与次级联赛（v1.4.0 起内置 35 赛事） | ✅ 基本够用 | 含荷甲/丹超/墨超/苏超/比甲/土超/西乙/英甲/英乙/法乙/意乙/苏冠/韩K2/日乙/巴乙/阿甲；个别赛季数据可能滞后 | | 小联赛 / 低级别联赛（各国第三级别及未收录赛事） | ⚠️ 数据可能不全 | 降级协议：按最接近联赛估算，误差 ±15–20%，星级 −1，仅给方向 | | 杯赛 / 淘汰赛（含两回合、加时、点球） | ⚠️ 联赛模型不适用，但提供修正 | v1.4.0 起支持两回合制与中立场修正；战意/轮换仍主导，需你补充首回合比分 | | 国家队赛事 | ❌ 不覆盖 | 无基线，征召/磨合差异大 | | 青年队 / 预备队 | ❌ 不覆盖 | 阵容与主客模型均不可靠 | | 赛会制 / 中立场 | ⚠️ 部分支持 | neutral_venue_factor 可削减主场优势；其余仍不可靠 |

三档口径：✅ 直接可用　⚠️ 可用但降级（会明确告诉你）　❌ 不适用（会说明原因）。 「小联赛数据不全」具体指：无内置基线、伤停与近况检索命中率低、赛季样本少——请务必补充你手上的信息。

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

| 场景 | 状态 | 处理方式 | |------|------|---------| | 换帅（上任 <5 场） | ✅ 已覆盖 | manager_bounce_factor 加成；样本少时降级 | | 保级 / 夺冠 / 欧战资格的极端战意 | ✅ 已覆盖 | MOTIVATION_FACTORS 调整 | | 密集赛程 / 轮换 | ✅ 已覆盖 | rest_days_factor 扣减 | | 核心球员停赛 / 累计黄牌 | ✅ 已覆盖 | 计入伤停维度 | | 升班马 / 首次交手（无 H2H） | ✅ 已覆盖 | H2H 权重归零，改用联赛基线 | | 极端天气（雨雪 / 高温 / 大风） | ✅ 已量化 | weather_venue_factor：大雨 −8%、降雪 −12%、强风 −7%、酷热 −5% | | 场地因素（人工草皮 / 高原主场） | ✅ 已量化 | weather_venue_factor：人工草皮 +4%、高原 +5% 且放大主队体能优势 | | 空场 / 无观众 | ⚠️ 部分覆盖 | 可用 neutral_venue_factor 部分削减主场优势 | | 门将伤缺 / 临时门将 | ⚠️ 部分覆盖 | 计入伤停，提示失球风险上浮 | | 转会窗未关 / 注册问题（新援上不了） | ⚠️ 部分覆盖 | 需你确认出场资格 | | 超长补时 / VAR 频密 | ⚠️ 部分覆盖 | 提示总进球可能高于基线 | | 国家队比赛日回归（FIFA 病毒） | ⚠️ 部分覆盖 | 提示疲劳与长途飞行影响 | | 提前夺冠 / 提前降级后的战意真空 | ⚠️ 部分覆盖 | 显著降星级 | | 德比 / 心理战等软因素 | ❌ 不量化 | 仅文字提示 | | 两回合制的次回合（需算总比分） | ✅ 已量化 | tie_context_factor：首回合降进球；次回合按主队总比分领先/落后调整 | | 赛会制 / 中立场 | ✅ 已量化 | neutral_venue_factor：主场优势减半、平局略升 | | 罢赛 / 延期 / 场地临时变更 | ❌ 暂不处理 | 信息确认后再分析 | | 假球 / 数据造假风险（低级别联赛） | ❌ 不判断 | 提醒风险，建议回避 |

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

| 情况 | 系统行为 | |------|---------| | 联赛名完全无法识别 | ⛔ 阻断，先问你 | | 赔率 ≤1.0 或明显填错 | ⛔ 阻断，先问你 |

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

---

---

一、执行操作指南

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

我能做这两件事

| 任务 | 怎么触发 | 多久出结果 | |------|---------|-----------| | 赛前数据分析 | 上传赛事对阵信息（赔率/阵容/伤停等），或说"帮我分析今天的比赛" | 5-15 分钟 | | 赛后核验 | 说"复盘昨天的比赛" | 3-5 分钟 |

使用流程图

你提供赛事信息 / 说一句话
        ↓
  ★ 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 分钟，我会输出：

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

如果结果不如预期

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

---

二、快速开始

你可以这样问

| 你说什么 | 我会做什么 | |---------|-----------| | "帮我分析今天的足球比赛" | 收集今日赛程 → 逐场分析 → 产出分析文件 | | "上传了赔率截图，帮我看看" | 读取截图 → 识别场次 → 七维分析 → 汇总表 | | "复盘昨天的比赛" | 搜索最终结果 → 逐场核验方向/比分对比率 → 输出教训 | | "皇马最近状态如何" | 查皇马近期表现、伤停、联赛排名、下一场情报 | | "德甲场均进球多少" | 查基线库德甲场均3.24球 → 回答大球特征 | | "某队赔率只有1.10，能打吗" | 先提示你核对赔率是否填错，再分析极端赔率的含义 |

你会得到什么

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

---

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

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

分析前必做：三步校验

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

| 校验项 | 检测什么 | 触发后的动作 | |--------|---------|-------------| | 联赛名 | 是否在基线库 / 是否可识别 | 提醒你确认，用暂定联赛继续或让你重填 | | 赔率结构 | 是否 ≤1.0 / 隐含概率和是否异常 / 是否极端低赔 | 疑似填错时阻止分析，等你确认 | | 数据缺失 | 赔率缺项、必填字段为空 | 列出缺什么，请补齐 |

三种典型提示

① 联赛名写错 / 用了别名

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

若完全无法识别：

你输入：威尔士超级联赛
系统：⚠️ 联赛名「威尔士超级联赛」无法识别（基线库收录 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 状态：

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

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

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

你怎么回应

| 情况 | 你回复 | |------|--------| | 联赛名识别错了 | "不对，是XX联赛" | | 赔率确实填错了 | 直接给正确赔率 | | 赔率没错 | "确认无误" → 系统按极端赔率逻辑继续 |

---

四、完整分析案例

案例：德甲 拜仁 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：逐场核验 | 场次 | 分析方向 | 最终结果 | 方向对比 | 预测比分 | 比分对比 | 预测进球 | 进球对比 | |------|---------|---------|---------|---------|---------|---------|---------| | 001 英超 | 主胜 | 曼城1-0考文垂 | ✅ | 2-0 | ❌ | 2 | ✅ | | 002 法甲 | 主胜 | 里昂3-1蒙彼利埃 | ✅ | 2-1 | ❌ | 3 | ✅ | | 011 葡超 | 客胜 | 马里迪莫0-3本菲卡 | ✅ | 0-3 | ✅ | 3 | ✅ | | 012 欧冠 | 主胜 | 拜仁0-0沙尔克 | ❌ | 3-0 | ❌ | 3 | ❌ | | 020 西甲 | 客胜 | 毕尔巴鄂3-0马竞 | ❌ 方向全反 | 0-1 | ❌ | 1 | ❌ | | 027 意甲 | 主胜 | 罗马2-1亚特兰大 | ✅ | 2-1 | ✅ | 3 | ❌ | | ... | ... | ... | ... | ... | ... | ... | ... |

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%）

| 维度 | 权重 | 关注点 | |------|------|--------| | 近期状态 | 25% | 近5-10场胜负平、进球/失球模式 | | 主客场表现 | 15% | 主场龙 vs 客场虫 | | 伤停与阵容 | 20% | 核心球员缺阵、首发阵容质量 | | 交锋往绩 | 15% | 历史对战胜平负、打法克制 | | 战术对位 | 10% | 阵型相克、风格冲突 | | 战意与赛程 | 5% | 杯赛轮换、保级 vs 争冠 | | 市场赔率结构 | 30% | 极端赔率、市场预期反向 |

联赛基线校准

| 进球档 | 联赛 | 默认思路 | |------|------|----------| | 大球档（≥3.0） | 芬超 3.29、德甲 3.24、挪超 3.18、沙特联 3.01、美职 3.00 | 默认大球 | | 中球档（2.7-2.9） | 德乙 2.93、瑞超 2.83、法甲 2.82、英超 2.75、英冠 2.74、西甲 2.69、葡超 2.68 | 2-3 球为主 | | 小球档（≤2.6） | 意甲 2.56、K1 2.53、巴甲 2.52、J1 2.40 | 1-0/2-1/1-1 为主 |

赛季分期与状态修正

| 阶段 | 进球修正 | 特点 | |------|---------|------| | 开季（8-10月） | +5%~15% | 阵容磨合，大球与低偏好并存 | | 中期（11-2月） | -10%~15% | 寒冷疲劳，小球增多 | | 末段（3-5月） | +5% | 保级队拼命 | | 末轮 | +17% | 进球激增 | | 保级区末5轮 | +8~12% | 弱队反而进球多 |

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，触发警告「实力差距明显」

战意类型

| 类型 | 加成 | 触发场景 | |------|------|---------| | title | +15% | 争冠（前三且差5分以内） | | top4 | +8% | 争 4/欧战席位 | | mid | 0% | 中游无欲无求 | | relegation | -8% | 保级死战 | | cup | -10% | 杯赛轮换 | | dead_rubber | -15% | 末轮无意义 |

换帅效应

| 比赛数 | 加成 | 说明 | |--------|------|------| | 第1场 | +8% | 换帅最大反弹 | | 第2场 | +6% | 反弹仍在 | | 第3场 | +4% | 递减中 | | 第4-6场 | +1-2% | 趋于正常 | | ≥7场 | 0% | 回归常态 |

赛程密度

| 休息天数 | 加成 | 场景 | |---------|------|------| | ≥7天 | +5% | 充分休整（国家队后/杯赛后） | | 4-6天 | 0% | 正常节奏 | | 3天 | -3% | 轻微疲劳 | | ≤2天 | -8% | 赛程密集（欧冠/联赛连转） |

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

| 联赛 | form | HA | inj | h2h | tac | mot | xg | 特点 | |------|------|------|------|------|------|------|------|------| | 英超 | 20 | 15 | 20 | 10 | 15 | 5 | 15 | 均衡型 | | 意甲 | 20 | 10 | 20 | 20 | 10 | 5 | 15 | H2H 权重最高 | | 德甲 | 25 | 20 | 15 | 5 | 10 | 5 | 20 | 主场龙极强 | | 西甲 | 20 | 15 | 20 | 10 | 15 | 5 | 15 | 战术权重较高 | | 法甲 | 25 | 20 | 15 | 5 | 10 | 5 | 20 | 与德甲类似 | | 挪超 | 15 | 30 | 15 | 5 | 10 | 5 | 20 | 主场优势最强 | | 葡超 | 20 | 20 | 20 | 5 | 10 | 5 | 20 | 主场权重最高 | | 沙特联 | 20 | 15 | 15 | 5 | 10 | 15 | 20 | 战意权重最高 | | 欧冠 | 15 | 10 | 25 | 15 | 15 | 5 | 15 | 伤停权重最高 | | 其他 | 默认值 | | | | | | | 自动 fallback |

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

---

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

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

| 参数 | 通俗问法 | 普通人怎么判断 | 填什么 | 示例 | |------|---------|--------------|--------|------| | xg_home / xG | "这支球队最近创造机会的能力怎么样？" | 近 5 场平均进了多少球？ | 小数，如 1.5 | 曼城近 5 场进 8 球 → xG ≈ 1.6 | | 战意类型 | "这场比赛对球队有多重要？" | 排名靠前/靠后？还剩几场？ | 6 种之一 | 巴萨差皇马 5 分 → title（争冠） | | | | | | 中游无欲无求 → mid | | | | | | 倒数第 3 名 → relegation（保级） | | 换帅场次 | "这支球队最近换教练了吗？" | 新教练带队了几场？ | 整数 1-10 | 上周换帅，本场是新帅第 1 场 → 1 | | 休息天数 | "这支球队上一场是什么时候？" | 今天日期 − 上场日期 | 整数 | 周三分析周二到今天 → 1 天 | | | | | | 周二分析周二到今天 → 0 天 | | | | | | 国际比赛周后首战 → 7-14 天 |

不会填怎么办？

• 不填 → 系统用联赛默认值，不影响分析流程
• 填错 → 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%）

---

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

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

快速导航

| 你遇到的症状 | 对应条目 | |-------------|---------| | 提示"联赛名无法识别/已识别为XX" | A1 | | 赔率看起来不对 / 某队只有 1.10 | A2 | | 输错了数据想改 | A3 | | 结果里出现"数据待定" | B1 | | 查不到某队/某球员信息 | B2 | | 国外网站打不开、很慢、显示不全 | B3 | | 转会消息不确定真假 | B4 | | 结果置信度只有 ⭐ | C1 | | 比分预测不准 | C2 | | 想改某场结论 / 重新分析 | C3 | | 想离线用、不想联网 | D1 | | 想知道模型什么时候最准 | D2 | | 报错、卡住、没有输出 | D3 |

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

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

| # | 错误类型 | 案例 | 正确做法 | |---|---------|------|---------| | 1 | 极端赔率陷阱 | 拜仁1.05→0-0沙尔克 | ≤1.15降权，深差距仅参考 | | 2 | 市场预期反向 | 77%看好客胜→3-0主胜 | >75%视为反向信号 | | 3 | 赛季初期强队慢热 | 德甲初期集体爆冷 | 开季6-8轮降预期 | | 4 | 比分过于自信 | 对比率≈0% | 比分仅参考 | | 5 | 实力差距交叉缺失 | 方向对但深差距输 | 置信度低时以差距为主 | | 6 | OCR错误未校验 | "阿贾克斯斯" | 对阵双方交叉验证 | | 7 | 赔率权重过高 | 过度依赖赔率连错 | 上限30% | | 8 | 脱离联赛基线 | 用一般规律套所有 | 先查基线库 | | 9 | 凭记忆生成阵容 | 3次被抓包 | 必须真实检索 | | 10 | 联赛特性忽视 | 挪超频繁预测平 | 按特性调整 | | 11 | 数据不标来源 | 转会消息当既定事实 | 标注A/B/C/D并交叉验证 | | 12 | 输入错误不提示 | 填错联赛名静默替换 | 走输入校验，主动告知 |

---

七、赛前数据分析流程

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.15 | 表面主队极强，实为市场诱导 | 降权；深差距如-2/-3仅参考；关注反方向+1 | | 客胜 ≤ 1.15 | 同上 | 降权；关注主队+1 | | 平局 ≤ 1.15 | 极罕见 | 降权为⭐，比分偏保守 |

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

---

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

| 看好度/赔率特征 | 风险 | 修正动作 | |----------------|------|---------| | 某方看好度 > 75% | 市场赔率被压低，打出概率低于隐含 | 预期方向降权；优先考虑反方向 | | 赔率差 > 1.5（一方 < 1.50 另一方 > 2.50） | 推断大热方向 | 大热方降⭐；反方向值得重视 |

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

---

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

| 联赛 | 主场修正 | 风险特点 | |------|---------|---------| | 德甲 | 主胜 +8% | 开季主场龙极强，弱队主场超预期 | | 法甲 | 主胜 +6% | 巴黎独大但客场不稳 | | 英超 | 主胜 +5% | 升班马和强队开季均不稳定 | | 西甲 | 主胜 +4% | 夏窗调整大，主力磨合期 |

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

---

三清单结果汇总：

| 触发检查数 | 置信度修正 | |-----------|----------| | 0 项 | 不修正 | | 1 项 | 降1级（⭐⭐⭐→⭐⭐） | | 2 项 | 降2级（⭐⭐⭐→⭐） | | 3 项 | 直接⭐，仅参考方向 |

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 "~\.workbuddy\skills\football-analysis\cli.py"
python "~\.workbuddy\skills\football-analysis\cli.py" --test
python "~\.workbuddy\skills\football-analysis\cli.py" --json

# 向后兼容（旧命令仍可用）：
python "~\.workbuddy\skills\football-analysis\football_calc.py" --test

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

函数清单

| 函数 | 说明 | |------|------| | get_baseline(league) | 查 35 联赛离线基线 | | normalize_score(value, direction) | 归一化到 [0,1] | | calc_season_goals(league, phase, ...) | 含分期系数的预期进球 | | calc_handicap_prob(line) | 实力差距覆盖概率 | | calc_1X2_probabilities(...) | ★ 主函数：输出概率+置信度+警告 | | check_extreme_odds_trap(...) | 检查1：极端赔率 | | check_public_favorite_reverse(...) | 检查2：市场预期反向 | | check_early_season_league_bias(...) | 检查3：赛季初期偏差 | | run_prematch_checklist(...) | 三清单主入口（结果须回传 calc_1X2_probabilities(checklist_result=chk)） | | calc_xg_advantage(xg_h, xg_a, ...) | xG 优势计算 | | calc_xg_expected_goals(...) | xG 估算期望进球 | | manager_bounce_factor(games) | 换帅反弹加成 | | rest_days_factor(days) | 休息天数加成 | | 🆕 resolve_league(raw) | 联赛名智能解析（精确/别名/包含/模糊） | | 🆕 check_odds_sanity(h,d,a) | 赔率合理性检查（识别填错/极端低赔） | | 🆕 validate_user_input(...) | 输入校验统一入口（联赛名+赔率） | | 🆕 get_data_sources(region) | 数据源优先级（国内优先） | | 🆕 rate_data_reliability(source) | 数据源可靠性分级 A/B/C/D | | 🆕 verify_transfer_claim(claim, sources) | 转会/阵容信息交叉验证 | | diagnose_error(ex, key, ctx) | 错误分类诊断 | | handle_error(ex, key, ctx) | 错误处理主入口（含熔断） |

常量：

• 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"~\.workbuddy\skills\football-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 "~\.workbuddy\skills\football-analysis\cli.py" --test   # 89 项自检 + 78 条回归守卫
python "~\.workbuddy\skills\football-analysis\cli.py" --json   # 纯 JSON（无横幅，可直接 json.loads）

---

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

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

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

| 优先级 | 站点 | 用途 | 可靠性 | |--------|------|------|--------| | 1 | 中国体彩网 lottery.gov.cn | 官方赛程/赔率 | A | | 2 | 懂球帝 dongqiudi.com | 阵容/伤停/战报 | B | | 3 | 直播吧 zhibo8.com | 赛程/阵容/新闻 | B | | 4 | 新浪体育 sports.sina.com.cn | 综合报道 | B | | 5 | 网易体育 sports.163.com | 综合报道 | B | | 6 | 500赛事网 500.com | 赔率/数据 | B | | 7 | 虎扑 hupu.com | 论坛线索 | C | | 8 | 兜底（慢）| Transfermarkt / FBref / Understat / FotMob | A/B |

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

数据可靠性分级

| 等级 | 标签 | 来源 | 处理 | |------|------|------|------| | A | 官方/权威 | 体彩官网、联赛官网、Transfermarkt/FBref/Understat | 可直接采用 | | B | 主流媒体 | 懂球帝、直播吧、新浪/网易体育、FotMob | 采用；关键项交叉验证 | | C | 自媒体/聚合 | 虎扑贴、彩客、内容农场 | 仅作线索，必须验证 | | D | 待核实 | 单一来源、转载、无出处 | 标「待核实」，不作决策依据 |

关键数据核实规则

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

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 文件

---

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

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

错误类型速查表

| 提示文字 | 错误类型 | 根因 | 修正方案 | |---------|---------|------|---------| | ❌ 图片模糊 | 图片质量 | 分辨率低/字体过小/截图角度倾斜 | 重新截图；或分两张上传 | | ❌ 网络检索失败 | 网络问题 | 检索引擎临时不可用/防火墙阻断 | 等待30秒后重试；系统自动切国内源 | | ❌ 联赛不在基线库 | 联赛缺失 | 低偏好联赛/小联赛未收录 | 自动检索补充；若失败用离线基线 | | ⚠️ 数据待定 | 综合 | 以上多种情况 | 按对应类型处理 | | ⚠️ 赔率结构异常 | 输入错误 | 赔率≤1.0 / 隐含概率和异常 | 核对后重新提供 | | ⚠️ 极端低赔 | 输入/风险 | 赔率≤1.15 | 确认赔率/数字；确认无误则降权处理 |

熔断机制

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

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

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

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

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

| 你看到什么 | 底层发生了什么 | 你需要做什么 | |-----------|--------------|------------| | "正在查询..." | 最多尝试 3 个数据源 | 等待 | | "数据待定" | 已用离线基线兜底，星级自动降 | 可补充该场信息后重算 | | "某场置信度只有 ⭐" | 缺数据/基本面分歧大 | 参考方向，不参考比分 | | "网络异常，建议稍后重试" | 5 场连续失败触发全局熔断 | 稍后重新上传截图 | | 全部正常输出 | 全部 3 个数据源成功 | 直接使用结果 |

---

十三、能力边界机制说明

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

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

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

| 情况 | 系统行为 | 你会看到 | 你该怎么做 | |------|---------|---------|-----------| | 联赛名完全无法识别 | ⛔ 阻断，不出分析 | 「联赛名「XX」无法识别…请确认名称」 | 重新给出准确联赛名 | | 赔率 ≤1.0 或明显填错 | ⛔ 阻断，不出分析 | 「赔率输入有误：…请核对」 | 核对截图/数字后重新提供 | | 联赛名写法模糊（如「德甲联赛」） | ⚠️ 降级继续 | 「已识别为「德甲」…如不对请指出」 | 确认即可，或纠正 | | 赔率极端低（≤1.15） | ⚠️ 降级继续 | 「检测到极端低赔…请先确认三点」 | 确认是「0档」还是「实力差距档」 | | 某场情报查不到（网络/检索失败） | 🔁 自动重试，最多 3 次 | 「该场数据暂不可用，已用离线基线」 | 可补充关键信息 | | 同一场连续失败 3 次 | ⏭️ 跳过该场（熔断） | 「该场已跳过」 | 稍后重试或手动补充 | | 连续 5 场都失败 | ⏸️ 暂停整批 | 「网络似乎异常，已暂停」 | 检查网络后重发 | | 联赛不在基线库（35 个之外） | ⚠️ 降级继续 | 「已按最接近联赛估算，误差 ±15–20%」 | 可补充该联赛参数 | | 完全离线 | ⚠️ 降级继续 | 「离线模式，精度约 80%」 | 关键数据自行核实 |

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

置信度分级

| 评级 | 触发条件 | 预测可信度 | 使用建议 | |------|---------|-----------|---------| | ⭐⭐⭐ | 基本面和市场方向一致，且有情报支撑 | 较高 | 可参考 | | ⭐⭐ | 基本面和市场有一方支撑 | 中等 | 谨慎参考 | | ⭐ | 双方分歧大，或某维度数据缺失 | 低 | 仅作方向参考 | | ⚠️ 已跳过 | 数据检索全部失败 | 极低 | 完全不参考 |

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

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

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

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

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

第一层：数据维度覆盖率

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

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

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

| 数据维度 | 联网时准确率 | 离线时用基线代替的准确率 | |---------|-----------|----------------------| | 联赛进球档（场均X球） | ~85% | ~80%（基线来自历史均值） | | 主客胜率分布 | ~80% | ~75%（主客场随赛季微调） | | 赛季分期规律（开季/中期/末段） | ~75% | ~70%（规律相对稳定） | | 伤停信息 | ~90% | 无法提供（用均值代替，~50%） | | 实时状态（近5场） | ~80% | 无法提供（用均值代替，~50%） | | 阵容质量 | ~85% | 无法提供（用均值代替，~50%） | | 赔率实时变化 | ~75% | 无法提供（用截图赔率，~90%） |

第三层：综合计算

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

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

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

取整后保守估计为 80%。

精度下降的主要来源：

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

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

---

一句话总结

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

---

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

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）。任何模型提升必须跨过这条线。
2. 去水口径差异可忽略：等比例 0.9712 / Shin 0.9716 / 等边际 0.9728 / power1.5 0.9855。 此前「Shin 明显更优」源自归一化 bug，已作废。默认等比例不动。
3. FLB 方向存在但不显著：偏好方（<70%）实际 0.4664 vs 预测 0.5047， −3.83pp，z = −1.22（n=253）。→ FLB_CORRECTION_ENABLED 继续出厂关闭。
4. λ 反演通过盲测，tol=0.22 后反超市场让球盘：只用胜平负盘反解 λ 再预测让球盘， LogLoss 0.9640 vs 市场真实让球盘赔率 0.9668 —— 反超 0.28%， 且全程零让球盘信息输入（tol=0.03 时是 0.9720，落后 0.52%，改值后由负转正）。 反解残差同步从 3.48pp 降到 0.57pp，λ 更贴合市场。主梁站得住。 另：双盘口联合拟合残差中位 0.0070（概率单位）→ 赛事两个盘口内部自洽， 不存在可用 λ 模型交叉分析的定价裂缝。
5. 强度链路 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）。
5. P1-5 权重归一化：仅对 7 项基本面键归一化（排除 odds 键），权重和=100。
6. P1-8a get_baseline 未命中抛 LeagueNotFoundError（不再静默回退英超）。
7. P1-8c rest_days_factor(3) 对齐文档为 -0.02。
8. 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（能力边界一页化 + 覆盖范围矩阵 + 特殊场景清单）。