# Code4History v0.7：跨版本迁移工具

从 v0.1–v0.6 迁移至 v0.7 时，不再需要手工判断哪些文件属于框架、哪些属于研究资料。

## 一键升级（建议：创建新目录）

先下载最新的完整模板 ZIP（例如 `code4history-v0.7.zip`），**无需先删除或覆盖旧目录**。

在 Windows PowerShell 中（Python 3.10+）：

```powershell
python .\code4history\tools\migrate.py upgrade --source "D:\History\old-project" --template "D:\Downloads\code4history-v0.7.zip" --target "D:\History\new-project"
```

此处 `migrate.py` 是从新版模板提取的脚本；旧版 v0.1–v0.6 没有这个工具。`--target` 必须是**尚不存在的**新目录，不能与旧目录相同或位于旧目录内。成功后在新项目运行：

```powershell
python tools/doctor.py
python tools/validate.py
python -m unittest discover -s tests -v
```

原项目、原 PDF、原论文与原 Git 历史均保持原状。迁移并不会自动复制 `.git` 历史；如需延续原仓库 Git 分支与提交，需另行迁移 Git 仓库或选取新目录后重新绑定远端。

## 分两步导出、恢复（可控制和预览）

从旧项目导出：

```bash
python /path/to/new/tools/migrate.py export --source /path/to/old-project --out /path/to/private-backup.c4h.zip
```

把新模板 ZIP 解压为一个**独立的新项目目录**，然后预览与恢复：

```bash
python /path/to/new/tools/migrate.py restore --bundle /path/to/private-backup.c4h.zip --target /path/to/new-project --dry-run
python /path/to/new/tools/migrate.py restore --bundle /path/to/private-backup.c4h.zip --target /path/to/new-project
```

可以在 `export` 加 `--dry-run` 先查看分类统计。两个命令都有 `--help`。

## 会保留什么？

- 已填写的 `topic.md`、`USERINFO.md`、`STATE.md`；研究决策、检查点、日志、参考文献数据库。
- 史料原始文件（包括未被 Git 跟踪的 PDF）、转录、史料卡、证据卡、问题卡、假说卡、概念和背景笔记、学术史、综合与论点。
- 论文正文、章节排列、大纲、审稿记录和研究产出；框架目录之外的普通自建研究文件。
- 已改写的**框架规则文件、Skills、脚本、模板、目录 readme** 会**另外归档**，不会直接覆盖新版本的规则。可在恢复后自行择取需要保留的自定义规则。

精确匹配 v0.1–v0.7 官方模板内容的空白文件不会重复导出。旧框架源代码、旧 Skill 不会覆盖新版。

## 冲突处理与安全性

1. 如果目标位置不存在：恢复至原路径。
2. 如果目标位置仍是官方空白研究模板：填入旧研究内容（例如 `topic.md` 和 `STATE.md`）。
3. 如果目标位置已有不同的用户内容：**不覆盖**，将迁入内容放在 `.code4history-migration/conflicts/<时间>/incoming/`。
4. 如果是修改过的旧框架规则或附加的 Skill/脚本：放在 `.code4history-migration/conflicts/<时间>/framework_customizations/`，需人工审阅后再使用。
5. 所有导入文件在写入之前经过 SHA-256 完整性校验；禁止路径穿越和软链接提权；写入用临时文件后原子替换。

恢复记录保存于 `.code4history-migration/latest-report.json`。如果出现冲突，**应当解决这些冲突之后再进行下次升级**。这不是自动语义合并工具，不会替你合并同一研究卡的两份不同修改。

## 不自动导出的内容

- Git 历史 (`.git/`)、Python 虚拟环境、编辑器缓存和临时编译文件。
- `.env`、密钥、证书与常见凭证文件，以免误打包机密；如它们确实属于你的研究资料，请另行安全备份。
- 软链接（不会追踪链接目标）。

**迁移包可能包含未公开手稿、版权受限的 PDF 和个人研究笔记。应当在本地保管，不要上传到公开仓库。**