用途：安全地把 Weaverse Pilot 主题从当前版本升级到较新版本，全过程包含检测、规划、执行与验证，未经明确批准不会覆盖用户自定义内容。主题仓库为 https://github.com/Weaverse/pilot，发布页为 https://github.com/Weaverse/pilot/releases，包名为 @weaverse/pilot，版本号为 YYYY.M.D（如 2026.4.7），早期使用 semver。
主要能力：快速检查更新可运行 node skills/theme-update/scripts/check_pilot_updates.mjs，或加 --target v2026.4.7 指定目标版本。流程分六阶段：检测（读 package.json、拉取 releases、列出中间版本与关键变更）；分支（git checkout -b update/v{CURRENT}-to-v{TARGET} 并推送）；规划（对每个 release 获取比较差异，将文件分为可自动合并、需要评审、跳过三类，并以表格呈现计划等待确认）；执行（先自动合并，再逐文件三方对比处理需评审文件，按 release 分别提交）；验证（安装依赖、bun run typecheck、bun run build，失败则定位并提议修复）；收尾（汇总变更、手动后续步骤与回滚方式，询问是否合并到 main）。
必要用法与注意：始终先建分支，不在 main 上直接更新；每个可能含用户改动的文件都需评审；按 release 逐个提交便于排查；typecheck 与 build 均通过才算成功；提供回滚说明；尊重用户删除的文件。常见陷阱包括版本号前缀差异（package.json 无 v、GitHub 标签有 v）、更新 package.json 后需按锁文件运行对应包管理器、保留用户自定义组件与路由结构、注意 CSS 合并冲突。另含仅升级 @weaverse/hydrogen SDK 的补充步骤（先记录基线错误、检查 peerDependencies、处理 5.15 的 errorComponent 类型变化、以完整构建收尾）及 Weaverse 内部的 Pilot 锁文件与 demo 部署说明。适用场景为使用 Pilot 主题的项目升级；限制：需网络访问 GitHub API，具体收费与平台信息暂未提供。