用途
本技能用于编写体育模型的模型卡（Model Card）。模型卡是一份版本化的运营契约，与用户拥有的模型、数据、指标、特征和验证产物绑定。它描述一个已经完成评估的模型：用途是什么、如何测试、在哪些情况下失效、何时重新训练或退役。
模型卡不是营销页面，不是实验历史，也不能替代证据。实验序列和结果应使用实验日志；某次评估的人类可读叙述应使用结果报告。
何时使用
以下情况适合使用：模型已有值得保留的稳定留出集证据；将已接受的实验提升为命名版本；为模型复用、交接、评审或发布做准备；为新的不可变模型版本更新文档；用户要求记录、冻结或共享体育模型。
不要为了暗示模型成熟度而创建一份未经证实的精美卡片。如果验证、基线或决策时间合法性未知，须明确说明并将模型标记为未批准运营使用。
所需证据
稳定的模型名称和版本；负责人、评审人、创建日期和下次评审日期；预期用户、决策和禁止用途；运动项目、赛事、人群、粒度、目标和决策时间；数据来源、窗口、过滤条件、排除项和不可变快照；特征定义和可用时间；命名的朴素基线和强简单基线；验证设计、折边界和指标定义；在相同留出人群上的聚合和折级结果；校准、泄漏、公平性、稳定性和切片发现（如适用）；序列化模型、环境信息和复现说明；监控、重新训练和退役标准。
如实使用未知、未测试或不适用。绝不用推断值或通用承诺填补空白。
必需章节
身份、归属、状态和版本；预期用途、用户、决策和禁止用途；目标、粒度、预测时间戳、时间跨度和输出语义；数据来源、窗口、人群、排除项和快照；特征族、转换和时间安全规则；基线和候选族；验证设计、折构建和指标定义；结果（含不确定性、折变化、切片和校准）；已知限制、失效模式和误用风险；监控、重新训练、评审和退役规则；产物清单、依赖和复现说明；批准历史和关联实验。
填写结构可阅读 references/card_template.md。定义监控或退役规则前，阅读 references/kill_conditions.md 并根据实际决策和指标调整示例。
工作流程
- 确认候选模型在留出数据上满足预先声明的接受规则。若不满足，记录为实验性而非已批准。
- 验证模型版本和不可变产物标识符。
- 从实验、数据、特征、泄漏、校准和验证产物中复制事实字段；不要凭记忆重建。
- 狭窄地陈述预期用途，并列出明确的禁止用途。
- 描述数据覆盖、排除项、标签构建和评估未代表的人群。
- 记录每个特征族并证明决策时的可用性。
- 在相同折和行上呈现候选和基线。
- 先总结主要指标，然后是不确定性、校准、稳定性和误差切片。
- 将已知失效模式转化为可检查的监控和终止条件。
- 记录用户或环境提供的准确产物路径和复现说明。
- 由第二名评审人追溯每一项定量和操作性声明。
- 冻结版本；未来实质性变更创建新卡片。
状态和冻结规则
首次满足章程的候选：创建 v1 并标记为已评估。特征定义或目标变更：新主版本或次版本；新卡片。数据窗口或源快照变更：新版本和重新验证。超参数变更：新版本并关联到原始实验。仅编辑更正：就地修订并附日期更正说明。终止条件触发：标记为已退役或已废弃；保留先前证据。复现不再有效：标记为不可复现，直到修复和评审。
仅当数据快照、特征集、配置、序列化模型和验证结果不可变时才冻结。绝不要静默编辑已冻结的卡片以使历史看起来更好。
结果呈现
更好的获胜概率：相同折上对比基线的 log-loss 或 Brier。有用的概率水平：校准曲线/表和校准误差上下文。更好的分差预测：对比常数/简单评分基线的 MAE 或 RMSE。稳定的球队排名：时间外排名效用和排名稳定性。跨赛季通用：每赛季结果，而非仅聚合均值。跨人群通用：评估切片结果和覆盖声明。
说明指标方向。“0.681 对比 0.693”不完整，除非卡片说明较低的 log-loss 更好、给出样本量并标识留出期。
监控和终止条件
条件必须可观察、有界并关联响应。良好形式包括：主要指标连续两个评审窗口输给锁定基线；校准误差在最小样本量下超过指定阈值；所需字段的缺失或模式变更使特征族失效；泄漏审计无法解决或失败；规则、赛程、阵容或测量制度变化超出评估范围；人群覆盖移出文档范围；从固定产物和支持环境复现失败。
对每个触发，记录负责人、检查节奏、最小证据、宽限期和行动：调查、重新训练、限制、回滚或退役。避免“性能感觉不好”之类的条件。
体育特有注意事项
说明模型是评分比赛、球队比赛、球员比赛、控球、回合还是投球。双倍球队比赛面板不是比赛级独立。定义平局、加时、季后赛、中立场和取消/不完整比赛的处理。记录可能限制跨赛季迁移的赛程强度、扩张、规则时代、阵容和来源变更。赛前模型须说明准确截止时间和如何处理伤病、阵容、首发、天气或市场信息的延迟。球队或球员标识符必须在迁移和改名后保持稳定。若概率驱动决策，记录校准和任何阈值或效用假设；仅准确率不够。
硬约束和完整性规则
绝不要将训练指标描述为预期性能。绝不省略基线、决策时间、粒度或主要指标。绝不声称超出评估的运动、赛季和人群的通用性。绝不发布没有产物位置、负责人和评审日期的卡片。绝不让退役标准保持隐含。绝不隐藏泄漏、验证或校准状态。绝不将探索描述为生产就绪。绝不列出与所代表版本不匹配的复现命令。绝不用更好看的后续结果覆盖已冻结的模型历史。如果所需证据不可用，说明运营后果。
反模式
“运行良好”但没有指标、基线、时期或分母；在任何有序留出评估存在之前编写的卡片；一个聚合分数但省略了失败的折；将 NFL 的措辞、假设或命令复制到另一项运动的卡片中；无法计算的终止条件；没有 as-of 可用性的特征列表；没有切片、定义或结果的通用“偏差已审查”声明；无法连接到其数据和配置的模型文件名。
工作示例
赛前球队获胜概率。身份：home_form_logit_v3。状态：已评估；未批准用于投注。目的：从场地和偏移形式估计赛前 P(球队获胜)。粒度：球队比赛；配对行共享一场比赛。决策时间：计划开始，在活动日更新之前。数据：已完成的常规赛，2018-2024；不可变 Parquet 快照。验证：赛季前向；主要指标 log-loss。基线：常数训练折流行率。结果：在相同行上报告均值和每个留出赛季。泄漏：已检查；所有滚动特征在聚合前偏移。限制：无伤病或阵容模型；赛季初冷启动。终止：在两个合格赛季差于基线 log-loss 后退役。产物：数据快照、特征清单、折指标、预测、模型文件。
校准范围不完整的分差模型。身份：pregame_margin_ridge_v1。目的：在阵容锁定前预测主队最终分差。主要指标：对比历史均值和简单评分基线的 MAE。校准：不适用于点预测；区间覆盖未测试。状态：实验性，直到评估预测区间覆盖。
第二个示例没有制造校准声明；它陈述了缺失的不确定性检查并相应地约束状态。
辅助工具
python <path-to-model-card>/scripts/write_card_stub.py
--name home-form-logit
--version v1
--grain team-game
--out data/model_card.md
从验证产物填充生成的用户拥有 Markdown 文件。辅助工具仅创建结构；它不验证性能或批准模型。
输出契约
完整卡片具有：每个必需章节存在；基线和主要指标与候选结果并列；聚合、折级和适用切片证据；决策时间和时间安全状态；明确的泄漏和校准状态；具体的监控、重新训练和终止条件；关联实验和不可变产物标识符；准确的复现说明；版本状态、负责人、评审人和下次评审日期。
资源
references/card_template.md — 逐节起草完整卡片时阅读。references/kill_conditions.md — 将失效模式转换为可测量监控和退役规则时阅读。scripts/write_card_stub.py — 可移植的模型卡脚手架编写器。