code4history/MIGRATION.md

已有研究项目升级提醒

v0.7 起建议使用 UPGRADE_v0.7.md 所述自动迁移工具。 以下仅保留旧版手动迁移说明供历史参考。

从 Code4History v0.2 更新到 v0.3

新建项目：直接解压完整 v0.3 ZIP 即可；不要把 v0.1/v0.2 的旧 Skill 目录混入新项目。

已有研究项目：先备份本地 topic.md、STATE.md、00_governance/、01_sources/—09_outputs/、尚未提交的其他变更（如 git status）；勿用空白模板覆盖真实研究资料。然后引入新的框架说明、测试和工具，并完成以下两项旧入口清理：

• 旧 Skill：.agents/skills/history-writing-workflow/ → 用新的 .agents/skills/history-writing-workflow-c4h/ 替换。不要让旧新两种 Skill 同时存在；新技能的 name 已更改。
• 删除退休入口 agent.md（若存在 AGENT.md 也删除）。保留 AGENTS.md，它是 Codex 默认文件。

PowerShell（在仓库根目录执行；确认旧目录没有用户自己额外写入的内容再运行）：

Remove-Item -LiteralPath '.agents/skills/history-writing-workflow' -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath 'agent.md' -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath 'AGENT.md' -Force -ErrorAction SilentlyContinue

Linux/macOS：

rm -rf -- .agents/skills/history-writing-workflow
rm -f -- agent.md AGENT.md

将 v0.3 模板的 USERINFO.md 空文件加入项目；如果用户已有自己的 USERINFO.md，不要覆盖或清空。将旧版 Q18 保留原答，在 topic.md 末尾添加 Q19/Q20（空白即原默认95分、50字），不要改动其他已确认问题。

然后检查：

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

如果旧项目包含自定义 Skill，比较后再迁移相应功能，不能简单认为新框架覆盖后不会有冲突。本文件是迁移操作建议，不自动改变任何远程 Git 仓库。

v0.8 双向交接区

升级操作使用 v0.8 tools/migrate.py 与 migration_baselines.json。upload 等待处理的附件（即使被 .gitignore 排除）、todo 尚待用户回答的事项、requests 尚未完成的请求、handoff/latest.md 均属于研究内容，不是可被新版空白模板清理的框架文件。详细参见 UPGRADE_v0.8.md。