SK-model-maintenance

Files (1)

• SKILL.md

SKILL.md (first lines)

# SK-model-maintenance — 模型维护最小化纪律

## 🔴 适用范围（场景隔离·唯一触发点）

- ✅ **适用**：**更新模型时**——改脚本 / 新增功能 / 写文档 / 重构 / 加数据源 / 清理归档
- ❌ **不适用**：**比赛分析（Step0-11）**——分析场景由「预算红线豁免铁律」管辖：
 **零步骤省略·零输出弱化·token/篇幅永远不是理由·以正确性为目的**
- 🔴 触发词区分：用户说「更新/改/加/精简/清理模型」→ 读本 skill；用户发竞彩 txt 要分析 → **不读**（按原流程完整执行）

## 🔴 YAGNI 阶梯（动手前逐级自问·借鉴 Ponytail）

```
① 这真的需要存在吗？        → 不需要 → 跳过（多数需求止步于此）
② 已有脚本/函数/表能复用吗？ → 复用（先查: data/tmp 脚本 · data/online_learning 模块 · 现成 json 表）
③ 标准库/现成参数/机制能解决吗？→ 用（新增 argparse 参数 ≫ 新写脚本）
④ 最小实现                   → 够用即止·不预留"以后可能用得上"的扩展/抽象层
⑤ 写后自查                   → 删除零消费的代码/参数（存在≠活跃·判定标准=产物是否被消费）
```

## 🔴 不可"懒"的红线（维护场景同样强制·违反即未完成）

| 红线 | 说明 |
|:--|:--|
| **文档三处同步** | AGENTS + 主技能 SKILL.md + `data/足球分析模型.txt` ——缺一不可 |
| **check_sync 全绿** | 含新增防回退校验（改了什么就加什么校验） |
| **改前备份** | `data/backups/<时间戳>/`（含被改文件） |
| **副本同步** | 涉及桌面副本已同步的文件 → 同步 + 双端 check_sync |
| **用完即清** | 临时脚本/探针/测试文件 → 删除（不留仓库） |
| **数据源纪律** | 按「数据源成功路径固化表」执行（如 api-football 纯 date） |

## 🔴 数据链三层风险（用户核心关切「一切以模型数据链不出错为基准」）

**任何改动先问：动的是哪一层？**

| 层 | 内容 | 改动纪律 |
|:--|:--|:--|
| **① 输入/解析层** | txt 竞彩格式解析（`txt_normalize`/`txt_features`）、欧亚盘抓取（Odds-API/api-football） | 🔴 **高危·禁止擅动**——字段错位/静默失效/数据提不出（真实事故: goal_odds "球后缀"静默失败 / 让球标题正则不匹配致假"数据不足" / F8 格式不匹配恒失效）。改前必须**用真实 txt 双格式实测** |
| **② 数据表层** | `goal_bins_table.json` / `league_table.json` / `score_depth_table.json` 等（键名+结构） | 🔴 **高危·禁改键名**——下游 live 引擎/查表按列名读 → 改键=静默失效。新增只能**加值不改名**·并同步全部消费方 |
| **③ 展示/留痕层** | calc_all 输出行 / raw 第八节 / 模板 / 校验器（output_checker/check_luopan） | 🟢 **安全区·新增标注优先放这层**——只读、不改数据、不改接口 |

**铁律**：**新增任何「标注/别名/档位显示」= 只读消费现有表 → 一律放第③层**；**外部术语体系（如他处提到的 L1-L7 七档量级）不得反向改写第①/②层**——量级与口径以 **txt 竞彩（总进球 8档）+ 欧亚盘（O2.5）为唯一基准**（决策: L1-L7 不引入·原表不在库不造数字 + 三套档位并存=口径混乱风险）。
**自检**：改完后问「这条改动会不会改变任何**已有字段的读法**？」→ 会 → 停手重设计。

## 🔴 实证（为什么需要本纪律）

- **2026-09-19 一轮内**即产生 2 个临时运行器（`_prestep_run_0917.py` / `_ps917_night.py` → 用后已删）——正是本纪律要防的"多写"
- **历史归档**：8 个脚本因"产物零消费"归档 → 本纪律的第 ⑤ 条（写后自查消费方）可提前拦住
- **对照正例**：`txt_normalize.py`（330 行）= **真正需要的工具**（下游实测揪出 2 个真 bug·格式兼容覆盖 6 类输入）→ **合理规模·非过度工程**
- 🔴 **注意区分**：分析场景的「批末压缩」「分 5 批执行」是**上下文管理**（信息已持久化 raw·零损失）·**不属于**本纪律的"精简"范畴

## 📋 维护任务标准流程（最小版）

```
① 备份 → ② YAGNI 阶梯自问（能否复用/最小实现） → ③ 修改（代码+文档三处）
→ ④ check_sync（+防回退校验） → ⑤ 副本同步+双端全绿 → ⑥ 清理临时产物 → ⑦ 记忆（一条）
```

From MENG-COOLMAN/PitchQuant, MIT.

More from MENG-COOLMAN/PitchQuant