用途
OpenPress Upgrade 负责 OpenPress 框架包升级与工作区迁移。命令与源码边界的路由由 openpress 技能处理，升级与迁移工作流由本技能处理。
主要能力
- 检测已安装的与目标 OpenPress 版本。
- 在确认后刷新框架包与已安装的 OpenPress 技能。
- 从 OpenPress 仓库中选择适用的迁移文档。
- 编辑前扫描工作区源码。
- 根据文档生成并实施迁移计划。
- 循环运行迁移 QA 检查点，直到全部通过或出现需要用户输入的阻塞项。
源码边界
使用 openpress 提供的源码/生成物边界。迁移期间仅编辑：
- press/
- 根 package.json 和 openpress/settings.json
- .agents/skills/ 中项目自有的本地技能文件
- 迁移文档明确指定的项目配置
不要手动编辑 node_modules/、public/openpress/、dist-react/、.deploy/、.openpress/、.turbo/cache/ 或安装器管理的 .claude/skills/ 链接。
工作流
0. 解析 CLI 命令
使用工作区本地的 OpenPress CLI。不要使用 npx open-press；open-press 是二进制名，不是 npm 包名。
使用以下形式之一：
open-press <command> .
npm run openpress:skills
node node_modules/@open-press/core/engine/cli.mjs <command> .
在仅安装 @open-press/core 的工作区中，优先使用 core CLI 路径。仅当安装了 @open-press/cli 且 node_modules/.bin/open-press 存在时才使用 open-press 二进制。
1. 检查
运行：
git status --short
node node_modules/@open-press/core/engine/cli.mjs doctor . --json
记录：
- 当前 @open-press/core 版本；
- doctor 报告的目标/最新版本；
- 已安装和已跟踪的技能、所有 lockfile 来源、缺失的规范技能，以及损坏或缺失的 agent 链接；
- 不得触碰的无关脏文件。
Doctor 是信息性的，即使过期也以 0 退出。如果无法检查最新版本，报告网络限制，不要猜测迁移范围。
2. 预览
运行：
node node_modules/@open-press/core/engine/cli.mjs upgrade . --dry-run
说明本地 OpenPress CLI 升级命令会更新依赖和技能，不会重写工作区内容。
3. 变更前确认
在运行会改变依赖、技能或工作区源码的命令或编辑前，先询问用户。
确认后运行：
node node_modules/@open-press/core/engine/cli.mjs upgrade .
当 doctor 报告 settingsMigrationRequired 时，此命令还会执行内置的 package.json#openpress → openpress/settings.json 迁移。它会验证完整结果，原子写入 settings，然后才移除遗留包字段。不要先手动删除遗留字段。不支持的字段或冲突的值需要用户解决。
当用户要求更窄范围的更新时，可用变体：
node node_modules/@open-press/core/engine/cli.mjs upgrade . --no-skills
node node_modules/@open-press/core/engine/cli.mjs upgrade . --no-deps
命令完成后，确认：
- 框架版本前 -> 后，可从 node_modules/@open-press/core/package.json 读取；
- 除非使用了 --no-skills，否则应安装七个默认 OpenPress 工作流技能、刷新确切的已跟踪可选和第三方技能，并修复 .claude/skills/ 链接。
4. 选择迁移文档
迁移文档位于 OpenPress 仓库的 docs/migrations/<version>.md。选择满足以下条件的每个文档：
currentVersion < version <= targetVersion
如果某个版本没有迁移文档，视为不需要工作区迁移。不要从 changelog 文本编造迁移步骤。
5. 扫描工作区源码
对每个选定的迁移文档，针对当前工作区源码运行每个 Find 命令或模式。优先使用迁移文档的确切命令；仅当工作区使用现代源码布局时，将旧的 document/ 路径适配到当前的 press/ 目录树。
至少扫描：
rg '<pattern-from-migration-doc>' press openpress/settings.json package.json .agents/skills .claude/skills
跳过缺失的可选目录，不要将其视为失败。
6. 生成并应用计划
编辑前总结匹配到的迁移工作：
- 受影响的迁移版本；
- 匹配的文件和模式；
- 建议的源码编辑；
- agent 无法执行的手动步骤；
- 必须通过的 QA 检查点。
仅在用户确认迁移计划后，才应用工作区源码编辑。编辑范围限于迁移文档。不要捆绑无关重构、设计变更、内容重写或部署工作。
7. 迁移 QA 循环
运行每个选定迁移文档 ## Migration QA 部分中的每个检查点。检查点必须包含命令或检查、预期结果，以及失败的含义。
如果检查点失败：
- 对照迁移文档诊断失败。
- 应用满足检查点的最小源码修复。
- 重新运行失败的检查点。
- 重新运行可能受修复影响的任何后续检查点。
在每个适用的检查点通过之前，不要报告迁移完成。如果检查点无法在无用户输入或外部变更的情况下通过，报告阻塞项，附上确切的失败命令和输出。
对于没有 ## Migration QA 的较旧迁移文档，回退到：
- 所有 Manual steps；
- Runtime / API 变更所隐含的检查；
- 默认构建验证：
npm run build
仅当 PDF 输出属于用户交付路径或迁移文档明确要求时，才运行 npm run openpress:pdf。
迁移文档策略
仅当某个版本影响现有工作区时，才创建 docs/migrations/<version>.md。以下情况需要迁移文档：
- press/ 源码布局变化；
- package.json 或 openpress/settings.json 配置变化；
- 公开的 @open-press/core API 变化；
- CLI 命令、标志或行为变化；
- 捆绑技能目录或路由变化；
- 生成的工作区/文档 schema 变化；
- 可能要求源码编辑或输出验证的部署、PDF、渲染、分页或页面契约行为。
以下情况不需要迁移文档：
- 不涉及工作区操作的内部系统缺陷修复；
- 仅 workbench 的 UI 打磨；
- 仅文档变化；
- 测试或包元数据；
- 仅新模板的设计更新，不改变现有工作区。
如果某个版本可能在不需要源码重写的情况下视觉上改变现有输出，编写带 QA 检查点的仅验证迁移文档。
禁止事项
- 不要使用 npm create @open-press 或全新模板 diff 作为迁移真相来源。
- 升级后不要自动部署。
- 不要对工作区文件使用强制覆盖。
- 不要编辑生成的输出。
- 没有最新的命令输出，不要声称升级或迁移就绪。