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

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

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

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

在 Windows PowerShell 中（Python 3.10+）：

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 必须是尚不存在的新目录，不能与旧目录相同或位于旧目录内。成功后在新项目运行：

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

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

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

从旧项目导出：

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

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

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 不会覆盖新版。

冲突处理与安全性

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

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

不自动导出的内容

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

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

3.8 KiB Raw Blame History Unescape Escape