# Cheat Migrate

把老用户的 .cheat-state.json 升级到当前 schema_version。读 migrations/registry.md...

- Repository: https://github.com/XBuilderLAB/cheat-on-content (7435 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-26
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add XBuilderLAB/cheat-on-content --skill cheat-migrate -g -a claude-code -y`
Codex: `npx skills add XBuilderLAB/cheat-on-content --skill cheat-migrate -g -a codex -y`
Cursor: `npx skills add XBuilderLAB/cheat-on-content --skill cheat-migrate -g -a cursor -y`
Gemini CLI: `npx skills add XBuilderLAB/cheat-on-content --skill cheat-migrate -g -a gemini-cli -y`

## Description

把老用户的 .cheat-state.json 升级到当前 schema_version。读 migrations/registry.md 算迁移链，按顺序应用每一步迁移文件。幂等：跑两次结果一样。失败停在中间版本不前进。触发词："迁移"/"升级 state"/"migrate"/"我的 state 是老版本"/"schema 版本不对"。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# /cheat-migrate, Schema 版本迁移

把用户 `.cheat-state.json` 从旧 `schema_version` 升级到 cheat-on-content 当前期望的 `LATEST_SCHEMA`。

---

## Overview

```
[用户：迁移 / 或 SessionStart 提示后用户跑]
  ↓
[Phase 0: 读 .cheat-state.json + migrations/registry.md → 确定迁移链]
  ↓
[Phase 1: dry-run（默认）展示迁移计划，等用户确认]
  ↓
[Phase 2: 备份 .cheat-state.json → .cheat-state.json.backup-<timestamp>]
  ↓
[Phase 3: 按顺序对每个 step 应用对应迁移文件的 HOW 段]
  ↓
[Phase 4: 验证升级后 state 文件能被解析 + schema_version 已更新]
  ↓
[Phase 5: 报告 + 提示如有备份需要清理]
```

---

## Constants

- **REGISTRY_PATH = `${SKILL_DIR}/../../migrations/registry.md`**, 版本链单一来源
- **MIGRATIONS_DIR = `${SKILL_DIR}/../../migrations/`**, 迁移文件目录
- **DRY_RUN_BY_DEFAULT = true**, 首次跑展示计划，不直接改文件
- **BACKUP_BEFORE_WRITE = true**, 写之前必备份；备份文件保留至下次成功 init / 用户手动清理
- **STOP_ON_STEP_FAILURE = true**, 任何 step 失败 → 停在中间版本，不前进，不回滚

> 💡 调用时覆盖：`/cheat-migrate, dry-run: false` 直接执行 / `/cheat-migrate, to: 1.2` 仅升到指定版本

---

## Inputs

| 必填 | 来源 |
|---|---|
| `.cheat-state.json` | 用户项目根 |
| `migrations/registry.md` | LATEST_SCHEMA + 版本链表 |
| `migrations/<from>-to-<to>.md` | 每步具体迁移指令 |

---

## Workflow

### Phase 0: 确定迁移链

1. 读 `.cheat-state.json` → 解析 `current_version = state.schema_version`
2. 读 `migrations/registry.md` → 解析 `LATEST_SCHEMA` 字段（行：`LATEST_SCHEMA = "X.Y"`）
3. 解析 `args.to` 覆盖（如有）；否则 target = LATEST_SCHEMA
4. 解析 `args.from` 覆盖（罕见场景：用户的 state 文件 schema 字段坏了，强制指定起点）
5. **状态判断**：
   - `current_version == target` → 输出"✅ state 已是 {target}，无需迁移" → 退出
   - `current_version > target`（比如用户跑了 dev 版又切回 release）→ 报错"无法降级，请手动调整或重新 init"
   - `current_version < target` → 继续，从注册表查出迁移链
6. 从注册表"版本链"表算出 `chain = [(from, to, file), ...]`，按顺序串起 current → target

如果某一步在注册表里缺失（比如 `current_version` 不在表里）→ 报错并展示"目前已知版本：[1.0, 1.1, ...]"，让用户检查。

### Phase 1: dry-run

输出迁移计划：

```
📋 迁移计划

当前版本: 1.0
目标版本: 1.2
将按顺序跑 2 步：

The rest: https://github.com/XBuilderLAB/cheat-on-content/blob/HEAD/skills/cheat-migrate/SKILL.md