Migrations Registry
May 12, 2026 · View on GitHub
cheat-on-content 的 schema 版本演进单一来源。/cheat-migrate 读这份文件决定要跑哪些迁移。
当前 schema_version
1.4 —— 由 cheat-init Phase 3 写入新 state 文件。
下方 LATEST_SCHEMA 标记位被 cheat-migrate skill 和 SessionStart hook 引用：
LATEST_SCHEMA = "1.4"
维护者注意：bump 这个值的同时必须新增对应迁移文件 + 在下方"版本链"追加一行。
版本链
按时间顺序，每行表示一个 schema 升级。/cheat-migrate 用此表算出从用户当前版本到 LATEST_SCHEMA 需要按顺序跑哪些 step。
| from | to | breaking? | 迁移文件 | 描述 |
|---|---|---|---|---|
| (none) | 1.0 | — | (内置) | v1 首版 schema |
| 1.0 | 1.1 | NO | 1.0-to-1.1.md | 删 mode / prediction_complexity / bucket_scheme 三个枚举字段；新增 target_publish_cadence_days / baseline_plays / benchmark_* / shoots 等 |
| 1.1 | 1.2 | NO | 1.1-to-1.2.md | shoots[] 项扩展 5 字段（scripts_path / script_consistency / script_diff_pct / v2_prediction_written / script_hash_at_shoot）— 配合"拍后改稿触发 v2 预测重判"工作流 |
| 1.2 | 1.3 | NO | 1.2-to-1.3.md | 新增 last_prediction_self_scored: bool + last_self_scored_at 字段——配合 cheat-score-blind sub-agent 引入的 channel B 隔离打分。true 表示上次预测走了 --skip-blind，cheat-status 持续 nag |
| 1.3 | 1.4 | BREAKING for blind channel | 1.3-to-1.4.md | rubric 文件拆分：rubric_notes.md → rubric_notes.md（blind 白名单，通用语言）+ rubric-memo.md（blind 硬禁读，含真实视频名/实绩）。state 字段不变；老用户必须跑 migrate 把现有 rubric_notes.md 拆开。不跑 → blind sub-agent 仍会标 non_blind_warning |
迁移文件命名约定
- 文件名：
<from>-to-<to>.md（如1.1-to-1.2.md） - 每份必含 4 段：
- WHAT changed — 字段层 diff（新增 / 删除 / 重命名）
- WHY — 为什么这个改动
- HOW (Claude steps) — Claude 跑
/cheat-migrate时按顺序执行的自然语言步骤 - Manual fallback — 如果用户不想跑 skill，手改
.cheat-state.json的最小指令
哲学（详见 shared-references/migration-protocol.md）
- MINOR bump（如 1.1 → 1.2）：仅新增字段或软化 enum 取值。老 state 用
state.get(field, default)读到默认值，可以不跑 migrate——但跑了能让 state 文件变完整 - MAJOR bump（如 1.x → 2.0）：删字段 / 重命名字段 / 改字段语义。老 state 必须跑 migrate，否则 skill 会读到不一致的字段
- 不允许跳版：1.0 用户升到 1.3 必须按顺序跑 1.0→1.1、1.1→1.2、1.2→1.3。每步幂等
- 失败停在原地：迁移到第 N 步失败 → state.schema_version 仍是 N-1（不是目标版本）。修复后重跑能从断点继续
给开发者：新增一个迁移
bump schema 时（顺序）：
- 想清楚是 MINOR 还是 MAJOR（参考上面哲学段）
- 改
cheat-init/SKILL.md的schema_version硬编码为新值 - 改本文件的
LATEST_SCHEMA = "X.Y"标记位 - 本文件"版本链"表追加一行
- 新建
migrations/<old>-to-<new>.md，4 段都填 - CHANGELOG.md 标
BREAKING（major）或MINOR，加迁移文件链接 - 跑一遍：在 fixture 老 state 上调
/cheat-migrate，验证升级到新版且 state 字段齐全
如果懒得写 4 段的标准 migration 文件，把 schema bump 推迟到下一次有规模改动时一起做——不要先 bump schema 再补文档。