Back to Details

openpress-upgrade

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenPress Upgrade

OpenPress 升级

openpress-upgrade
owns framework package upgrades and workspace migrations. Use 
openpress
for command/source-boundary routing, then use this skill for the upgrade and migration workflow.
openpress-upgrade
负责框架包升级和工作区迁移。 使用 
openpress
进行命令/源码边界路由，然后借助此技能完成升级与迁移工作流。

Responsibilities

职责

  • Detect installed and target OpenPress versions.
  • Refresh framework packages and installed OpenPress skills after confirmation.
  • Select applicable migration docs from the OpenPress repo.
  • Scan workspace source before editing.
  • Generate and implement migration plans from the docs.
  • Run migration QA checkpoints in a loop until all pass or a blocker needs user input.
  • 检测已安装的OpenPress版本与目标版本。
  • 确认后刷新框架包及已安装的OpenPress技能。
  • 从OpenPress仓库中选择适用的迁移文档。
  • 编辑前扫描工作区源码。
  • 根据文档生成并执行迁移计划。
  • 循环运行迁移QA检查点，直至全部通过或遇到需要用户输入的阻塞问题。

Source Boundaries

源码边界

Use the source/generated boundary from 
openpress
. During migration, edit only:
  • press/
  • root 
    package.json
    and 
    openpress/settings.json
  • project-owned local skill files in 
    .agents/skills/
  • project config explicitly named by a migration doc
Do not hand-edit 
node_modules/
, 
public/openpress/
, 
dist-react/
, 
.deploy/
, 
.openpress/
, 
.turbo/cache/
, or installer-managed 
.claude/skills/
links.
使用 
openpress
定义的源码/生成代码边界。迁移过程中，仅可编辑以下内容：
  • press/
    目录
  • 根目录下的 
    package.json
    和 
    openpress/settings.json
  • .agents/skills/
    目录下项目自有本地技能文件
  • 迁移文档中明确指定的项目配置
请勿手动编辑 
node_modules/
、
public/openpress/
、
dist-react/
、
.deploy/
、
.openpress/
、
.turbo/cache/
，或安装程序管理的 
.claude/skills/
链接。

Workflow

工作流程

0. Resolve The CLI Command

0. 解析CLI命令

Use the workspace's local OpenPress CLI. Do not use 
npx open-press
; 
open-press
is a binary name, not the npm package name.
Use one of these forms:
bash
open-press <command> .
npm run openpress:skills
node node_modules/@open-press/core/engine/cli.mjs <command> .
Prefer the core CLI path in workspaces that only install 
@open-press/core
. Use the 
open-press
binary only when 
@open-press/cli
is installed and 
node_modules/.bin/open-press
exists.
使用工作区本地的OpenPress CLI。请勿使用 
npx open-press
；
open-press
是二进制文件名，而非npm包名。
可使用以下形式之一：
bash
open-press <command> .
npm run openpress:skills
node node_modules/@open-press/core/engine/cli.mjs <command> .
对于仅安装了 
@open-press/core
的工作区，优先使用核心CLI路径。仅当安装了 
@open-press/cli
且存在 
node_modules/.bin/open-press
时，才可使用 
open-press
二进制文件。

1. Inspect

1. 检查

Run:
bash
git status --short
node node_modules/@open-press/core/engine/cli.mjs doctor . --json
Record:
  • current 
    @open-press/core
    version;
  • target/latest version from doctor;
  • installed and tracked skills, all lockfile sources, missing canonical skills, and broken or missing agent links;
  • unrelated dirty files that must not be touched.
Doctor is informational and exits 0 even when stale. If latest version cannot be checked, report the network limitation and do not guess the migration range.
运行：
bash
git status --short
node node_modules/@open-press/core/engine/cli.mjs doctor . --json
记录以下信息：
  • 当前 
    @open-press/core
    版本；
  • 检查工具返回的目标/最新版本；
  • 已安装和跟踪的技能、所有锁文件来源、缺失的标准技能，以及损坏或缺失的Agent链接；
  • 无关的未提交文件，这些文件绝对不可修改。
检查工具仅提供信息，即使内容过时也会返回0。若无法检查最新版本，需报告网络限制，且不得猜测迁移版本范围。

2. Preview

2. 预览

Run:
bash
node node_modules/@open-press/core/engine/cli.mjs upgrade . --dry-run
Explain that the local OpenPress CLI 
upgrade
command updates dependencies and skills. It does not rewrite workspace content.
运行：
bash
node node_modules/@open-press/core/engine/cli.mjs upgrade . --dry-run
说明：本地OpenPress CLI的 
upgrade
命令用于更新依赖和技能，但不会重写工作区内容。

3. Confirm Before Mutation

3. 确认后执行变更

Ask before running commands or edits that mutate dependencies, skills, or workspace source.
After confirmation, run:
bash
node node_modules/@open-press/core/engine/cli.mjs upgrade .
When 
doctor
reports 
settingsMigrationRequired
, this command also performs the built-in 
package.json#openpress
→ 
openpress/settings.json
migration. It validates the complete result, writes settings atomically, and only then removes the legacy package field. Do not manually delete the legacy field first. Unsupported fields or conflicting values require user resolution.
Useful variants when the user asks for a narrower update:
bash
node node_modules/@open-press/core/engine/cli.mjs upgrade . --no-skills
node node_modules/@open-press/core/engine/cli.mjs upgrade . --no-deps
After the command completes, confirm:
  • framework version before -> after, reading from 
    node_modules/@open-press/core/package.json
    when available;
  • seven default OpenPress workflow skills installed, exact tracked optional and third-party skills refreshed, and 
    .claude/skills/
    links repaired, unless 
    --no-skills
    was used.
在运行会修改依赖、技能或工作区源码的命令或编辑操作前，需先征得用户确认。
确认后运行：
bash
node node_modules/@open-press/core/engine/cli.mjs upgrade .
若检查工具提示 
settingsMigrationRequired
，此命令还会执行内置的 
package.json#openpress
→ 
openpress/settings.json
迁移。它会验证完整结果，以原子方式写入设置，之后才会移除旧版包字段。请勿手动先删除旧版字段。不支持的字段或冲突值需由用户解决。
当用户要求更精细化更新时，可使用以下变体命令：
bash
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
    读取（若存在）；
  • 已安装7个默认OpenPress工作流技能，精确跟踪的可选和第三方技能已刷新，且 
    .claude/skills/
    链接已修复（除非使用了 
    --no-skills
    参数）。

4. Select Migration Docs

4. 选择迁移文档

Migration docs live in the OpenPress repo under 
docs/migrations/<version>.md
. Select each doc where:
txt
currentVersion < version <= targetVersion
If a release has no migration doc, treat it as no workspace migration required. Do not invent migration steps from changelog text.
迁移文档位于OpenPress仓库的 
docs/migrations/<version>.md
路径下。选择符合以下条件的每个文档：
txt
currentVersion < version <= targetVersion
若某个版本无迁移文档，则视为无需对工作区进行迁移。不得根据变更日志内容自行编造迁移步骤。

5. Scan Workspace Source

5. 扫描工作区源码

For each selected migration doc, run every 
Find
command or pattern against the current workspace source. Prefer the migration doc's exact command; adapt only old 
document/
paths to the current 
press/
tree when the workspace uses the modern source layout.
Scan at least:
bash
rg '<pattern-from-migration-doc>' press openpress/settings.json package.json .agents/skills .claude/skills
Skip missing optional directories without treating them as failure.
对于每个选中的迁移文档，针对当前工作区源码运行文档中的所有
查找
命令或模式。优先使用迁移文档中的精确命令；仅当工作区使用现代源码结构时，需将旧版的
document/
路径适配为当前的
press/
目录结构。
至少运行以下扫描命令：
bash
rg '<pattern-from-migration-doc>' press openpress/settings.json package.json .agents/skills .claude/skills
若可选目录不存在，跳过即可，无需视为失败。

6. Generate And Apply Plan

6. 生成并执行计划

Summarize matched migration work before editing:
  • affected migration versions;
  • matched files and patterns;
  • proposed source edits;
  • manual steps the agent cannot perform;
  • QA checkpoints that must pass.
Apply workspace source edits only after the user confirms the migration plan. Keep edits limited to the migration doc. Do not bundle unrelated refactors, design changes, content rewrites, or deploy work.
在编辑前总结匹配到的迁移工作：
  • 受影响的迁移版本；
  • 匹配到的文件和模式；
  • 建议的源码编辑内容；
  • Agent无法执行的手动步骤；
  • 必须通过的QA检查点。
仅在用户确认迁移计划后，才可对工作区源码进行编辑。编辑内容需严格限定在迁移文档范围内，不得包含无关的重构、设计变更、内容重写或部署工作。

7. Migration QA Loop

7. 迁移QA循环

Run every checkpoint in each selected migration doc's 
## Migration QA
section. A checkpoint must include a command or inspection, expected result, and what failure means.
If a checkpoint fails:
  1. Diagnose the failure against the migration doc.
  2. Apply the smallest source fix that satisfies the checkpoint.
  3. Re-run the failed checkpoint.
  4. Re-run any later checkpoints that could be affected by the fix.
Do not report migration complete until every applicable checkpoint passes. If a checkpoint cannot pass without user input or an external change, report the blocker with the exact failing command and output.
For older migration docs without 
## Migration QA
, fall back to:
  • all 
    Manual steps
    ;
  • checks implied by 
    Runtime / API changes
    ;
  • default build verification:
bash
npm run build
Run 
npm run openpress:pdf
only when PDF output is part of the user's delivery path or a migration doc explicitly requires it.
运行每个选中迁移文档中
## Migration QA
部分的所有检查点。每个检查点需包含命令或检查操作、预期结果，以及失败的含义。
若检查点失败：
  1. 根据迁移文档诊断失败原因。
  2. 应用最小化的源码修复以满足检查点要求。
  3. 重新运行失败的检查点。
  4. 重新运行所有可能受修复影响的后续检查点。
仅当所有适用检查点都通过后，才可报告迁移完成。若某个检查点无法通过，且需要用户输入或外部变更，需报告阻塞问题，并附上精确的失败命令及输出结果。
对于无
## Migration QA
部分的旧版迁移文档，可 fallback 至以下内容：
  • 所有
    手动步骤
    ；
  • 运行时/API变更
    隐含的检查；
  • 默认构建验证：
bash
npm run build
仅当PDF输出是用户交付流程的一部分，或迁移文档明确要求时，才运行 
npm run openpress:pdf
。

Migration Doc Policy

迁移文档规范

Create 
docs/migrations/<version>.md
only when a release affects existing workspaces. A migration doc is required for:
  • press/
    source layout changes;
  • package.json
    or 
    openpress/settings.json
    config changes;
  • public 
    @open-press/core
    API changes;
  • CLI command, flag, or behavior changes;
  • bundled skill catalog or routing changes;
  • generated workspace/document schema changes;
  • deploy, PDF, render, pagination, or page-contract behavior that may require source edits or output verification.
A migration doc is not required for:
  • internal system bug fixes with no workspace action;
  • workbench-only UI polish;
  • docs-only changes;
  • tests or package metadata;
  • new-template-only design updates that do not change existing workspaces.
If a release can visually shift existing output without requiring a source rewrite, write a verify-only migration doc with QA checkpoints.
仅当版本发布会影响现有工作区时，才需创建 
docs/migrations/<version>.md
文档。以下情况必须编写迁移文档：
  • press/
    源码目录结构变更；
  • package.json
    或 
    openpress/settings.json
    配置变更；
  • @open-press/core
    公开API变更；
  • CLI命令、参数或行为变更；
  • 内置技能目录或路由变更；
  • 生成的工作区/文档 schema 变更；
  • 部署、PDF生成、渲染、分页或页面契约行为变更，且可能需要修改源码或验证输出。
以下情况无需编写迁移文档：
  • 内部系统bug修复，且无需工作区执行任何操作；
  • 仅工作台UI优化；
  • 仅文档内容变更；
  • 测试或包元数据变更；
  • 仅新模板设计更新，不影响现有工作区。
若版本发布虽未要求重写源码，但会导致现有输出视觉变化，则需编写仅包含QA检查点的验证型迁移文档。

Do Not

注意事项

  • Do not use 
    npm create @open-press
    or a fresh template diff as the source of migration truth.
  • Do not auto-deploy after upgrade.
  • Do not use force overwrites on workspace files.
  • Do not edit generated output.
  • Do not claim upgrade or migration readiness without fresh command output.
  • 请勿将 
    npm create @open-press
    或全新模板差异作为迁移的依据。
  • 升级后请勿自动部署。
  • 请勿强制覆盖工作区文件。
  • 请勿编辑生成的输出内容。
  • 若无最新命令输出，请勿宣称已完成升级或迁移准备。