framework-update

CataForge 框架同步 (framework-update)

能力边界

• 能做: 包↔scaffold 版本差异检测、pip/uv 包升级、scaffold 增量刷新、IDE 产物部署、doctor 验证、按 references/version-migration.md 提示升级区间的更新重点与迁移动作、upgrade.state 簿记、项目 init/resume 分流
• 不做: 修改项目业务代码、升级操作系统依赖、跨平台 adapter 变更（由 platform-audit 负责）、内嵌 Project Bootstrap 协议（仅委托 orchestrator 执行）

输入规范

• 操作指令: check（只读检测）、apply（同步并初始化/恢复）、verify（迁移检查）
• 无参数时默认执行完整流程（check → 确认 → apply）
• --dry-run: 仅在 apply 中有效，预览 plan 不写盘
• --upgrade-package: 在 apply 中强制执行 pip/uv 包升级（缺省仅在 check 探测到包落后时升级）
• 本 skill 是脊柱命令 cataforge bootstrap 的薄编排层

输出规范

• 版本对比（scaffold 版本 vs 已安装版本）与初始化状态（{INSTRUCTION_FILE} 是否存在）
• scaffold 刷新文件统计（写入数 / 保留数）、部署产物清单
• 升级区间的更新重点摘要与迁移动作清单（来自 version-migration 迁移要点）
• 迁移检查结果（PASS / SKIP / FAIL 逐项）
• upgrade.state 更新确认（框架版本字段由 deploy 阶段盖入）
• init/resume 决策与已装配的执行环境命令

---

操作指令

指令1: 版本与初始化状态检测 (check)

Step 1: 读取当前状态

执行:

cataforge upgrade check

从输出记录 installed_version（Installed package 行）、scaffold_version（Scaffold version 行）、二者是否一致，以及 {INSTRUCTION_FILE} 是否存在（→ 需 init / 已初始化）。

Step 2: 报告

已安装包  : <installed_version>
Scaffold  : <scaffold_version>
版本状态  : up-to-date | outdated
项目状态  : 未初始化（无 {INSTRUCTION_FILE}） | 已初始化

outdated 或未初始化时提示用户运行 framework-update apply；outdated 时补一句：升级完成后会按新版迁移要点提示需人工跟进的动作（当前 scaffold 内的 version-migration 仍是旧版内容，升级前不据其预告新版变更）。

---

指令2: 同步并初始化/恢复 (apply)

单一脊柱 cataforge bootstrap（幂等 setup→upgrade→deploy→doctor）只在 Step 3 调用一次；前置包升级、后置簿记、init/resume 分支分别包裹其前后。

Step 1: 版本与状态前置检查

执行指令1 取版本差异与初始化状态。若已 up-to-date 且已初始化，告知用户并询问是否仍强制刷新 scaffold（确认后继续，cataforge bootstrap 会自动跳过 current 步骤仅跑 doctor），否则结束。

Step 2: 包升级（条件执行）

仅当 Step 1 探测到包落后、或传入 --upgrade-package 时执行；--dry-run 时跳过。依次探测包管理器（短路，找到即停）:

uv tool list 2>/dev/null | grep -q cataforge && echo "uv"

pip show cataforge 2>/dev/null | grep -q Name && echo "pip"

• uv → uv tool upgrade cataforge
• pip → pip install --upgrade cataforge
• 均未探测到 → 提示用户手动升级包，不 abort，继续 Step 3 仅刷 scaffold（解耦"升级包"与"刷 scaffold"）