theme-update

主题更新 — Weaverse Pilot

安全地将 Weaverse Pilot 主题从当前版本升级到较新版本。本技能将引导你完成检测、规划、执行和验证，绝不会在未经明确批准的情况下覆盖用户自定义内容。

来源

• 主题仓库：https://github.com/Weaverse/pilot
• 版本发布：https://github.com/Weaverse/pilot/releases
• 软件包名称：@weaverse/pilot
• 版本格式：YYYY.M.D（例如，2026.4.7）。旧版本使用 semver（v8.1.0）

快速检查

node skills/theme-update/scripts/check_pilot_updates.mjs
node skills/theme-update/scripts/check_pilot_updates.mjs --target v2026.4.7

---

流程

按顺序完成以下阶段。请勿跳过步骤。

阶段 1 — 检测

1. 读取 package.json → 获取 version 字段
2. 如果 name 不是 @weaverse/pilot，请用户确认这是一个基于 Pilot 的项目
3. 获取版本发布信息：

curl -s "https://api.github.com/repos/Weaverse/pilot/releases?per_page=50"

4. 找出当前版本与最新版本（或用户指定的目标版本）之间的所有版本发布
5. 向用户展示：
   • 当前版本
   • 目标版本（除非另有指定，否则为最新版本）
   • 中间版本发布的数量
   • 主要变更摘要（功能、修复、重大变更）

如果已经是最新版本 → 到此为止并告知用户。

阶段 2 — 分支

git checkout -b update/v{CURRENT}-to-v{TARGET}
git push -u origin update/v{CURRENT}-to-v{TARGET}

始终在分支上操作。绝不要直接在 main 上更新。

阶段 3 — 规划

对于更新范围内的每个版本发布（从最早到最新）：

1. 获取相邻版本之间的差异：

# Full comparison URL
https://api.github.com/repos/Weaverse/pilot/compare/v{OLD}...v{NEW}

# Raw diff
https://github.com/Weaverse/pilot/compare/v{OLD}...v{NEW}.diff

2. 下载目标版本的源代码（用于参考文件）：

curl -sL "https://api.github.com/repos/Weaverse/pilot/tarball/v{TARGET}" | tar xz

3. 将每个变更文件归入以下三类：

自动合并（可安全应用，无需询问）

• package.json 版本更新、依赖项
• 锁文件（package-lock.json、bun.lockb、pnpm-lock.yaml）
• tsconfig.json、vite.config.ts、tailwind.config.ts — 仅限用户未自定义的文件
• 用户项目中不存在的新文件（仅添加）
• .github/、CHANGELOG.md、LICENSE

需要审核（展示差异并征求批准）

• app/components/ — 用户可能已自定义的 UI 组件
• app/routes/ — 用户可能已修改的路由文件
• app/lib/ — 工具模块
• app/root.tsx、app/entry.client.tsx、app/entry.server.tsx
• app/styles/ — CSS/Tailwind 变更
• 用户有本地变更的任何文件（git diff 显示其相对于 Pilot 基础版本有修改）

跳过（提及但不修改）

• 用户已删除的文件（他们有意移除了该功能）
• 用户已重新整理目录中的文件
• .env、.env.example — 绝不覆盖环境文件

4. 以清晰的表格展示计划：

## Update Plan: v2026.3.23 → v2026.4.7

### Auto-merge (3 files)
✅ package.json — version + dependency bumps
✅ bun.lockb — lock file update
✅ app/lib/utils.ts — new helper function added

### Needs Review (5 files)
⚠️  app/components/Header.tsx — Pilot added shopify-account web component
    Your version: custom mega menu logic
    Pilot change: replaced AccountButton with <shopify-account>
    → Recommend: keep your mega menu, add shopify-account separately

⚠️  app/routes/_index.tsx — performance improvements
    Your version: added custom hero section
    Pilot change: caching + skeleton loading
    → Recommend: apply caching, keep your hero

### New Files (2 files)
➕ app/components/ScrollReveal.tsx — new scroll animation component
➕ app/lib/reviews.ts — extracted reviews API

### Skipped (1 file)
⏭️  app/components/CombinedListings.tsx — you deleted this file

继续之前请等待用户确认。 询问：

“请审核以上计划。批准后继续，或告知我哪些文件需要采用不同的处理方式。”

阶段 4 — 执行

按顺序应用变更；如果跨多个版本升级，则一次处理一个版本发布：

4a. 自动合并文件

# Copy new file from Pilot source
cp /tmp/pilot-reference/{FILE_PATH} {FILE_PATH}

# Or apply targeted patch
git apply --3way <patch-file>

每次自动合并后，使用 git diff --stat 验证。

4b. 需要审核的文件

针对每个文件：

1. 展示三方对比：

   • 用户所用版本的 Pilot（基线）
   • 目标版本的 Pilot（其变更）
   • 用户当前的文件（本地修改）

2. 确定哪些变更来自用户，哪些来自 Pilot：

   • 仅用户的变更 → 保留
   • 仅 Pilot 的变更 → 应用
   • 重叠的变更 → 标记为冲突

3. 对于冲突，提供以下选项：

   • 接受 Pilot 版本（丢失用户自定义内容）
   • 保留用户版本（跳过 Pilot 的改进）
   • 手动合并（展示双方内容，让用户编辑）
   • 智能合并（尝试合并双方内容 — 仅限变更区域不重叠的情况）

4. 继续之前，等待用户对每项冲突作出决定。

4c. 按版本发布提交

git add -A
git commit -m "chore: update Pilot v{OLD} → v{NEW}

- [list key changes applied]
- [list files with manual merge decisions]
"

如果跨多个版本升级，则对每个中间版本发布重复上述步骤。

阶段 5 — 验证

应用所有更改后：

# 1. Install dependencies
bun install  # or npm install / pnpm install based on lockfile

# 2. TypeScript check
bun run typecheck

# 3. Build check
bun run build

如果构建失败：

1. 列出错误
2. 分析根本原因（依赖项不匹配？遗漏了破坏性更改？）
3. 提出修复方案
4. 获得用户批准后应用修复
5. 重新运行构建

如果构建成功：

1. 短暂运行 bun run dev，检查是否存在运行时错误
2. 总结所做的所有更改
3. 列出所有后续手动操作：
   • 需要配置的新功能
   • 需要更新自定义文件中代码的破坏性更改
   • 以后需要迁移的弃用模式

阶段 6 — 完成

1. 提供最终总结：

## Update Complete: v2026.3.23 → v2026.4.7

✅ 12 files auto-merged
✅ 5 files reviewed and merged
✅ 2 new files added
✅ Build passes
✅ TypeCheck passes

### New features available
- Shopify Account Web Component (<shopify-account>)
- Vite chunk splitting for better caching
- ScrollReveal component for animations

### Manual follow-up (optional)
- Configure shopify-account in your Header if you want native sign-in
- Review ScrollReveal component for use in custom sections

### Rollback
git checkout main
git branch -D update/v2026.3.23-to-v2026.4.7

2. 询问用户：“准备好合并到 main 了吗？”

# If approved
git checkout main
git merge update/v{CURRENT}-to-v{TARGET}
git push origin main

---

安全规则

1. 始终先创建分支 — 切勿直接在 main 上更新
2. 未经询问，绝不覆盖 — 任何可能包含用户更改的文件都需要先检查
3. 每个版本单独提交 — 如果出现问题，便于使用二分法定位
4. 构建必须通过 — 只有 typecheck 和 build 都通过后才能宣布成功
5. 提供回滚方法 — 始终告知用户如何撤销整个更新
6. 尊重用户删除操作 — 如果用户删除了某个文件，未经询问不要重新添加

常见问题

• 版本格式：package.json 中没有 v 前缀（2026.4.7），GitHub 标签有 v 前缀（v2026.4.7）。务必统一格式。
• 锁文件：更新 package.json 后，必须运行正确的包管理器（检查存在的是哪个锁文件）
• 自定义组件：始终保留原始 Pilot 中没有的用户组件 — 切勿删除或移动它们
• 路由结构：如果用户重新组织了路由，不要强制采用 Pilot 的结构 — 应将路由逻辑更改应用到用户的结构中
• CSS 冲突：Pilot 可能会更改 Tailwind 类或基础样式 — 需要谨慎合并，以免破坏用户样式

仅更新 SDK 版本（@weaverse/hydrogen）

有时用户只要求“更新 Weaverse SDK”，而不是完整更新主题。经过验证的流程（用于将客户端从 5.5.0 更新到 5.15.1）：

1. 更新前建立基准。 在当前版本上运行 npx react-router typegen && npm run typecheck，并记录每个错误（客户端分支通常已有预存错误）。更新后，与此基准比较差异 — 你只需处理新增的问题。没有基准的话，你会浪费时间排查一直存在的错误。
2. 先检查同级依赖：npm view @weaverse/hydrogen@<target> peerDependencies。5.15.x/5.16.x 需要 @shopify/hydrogen >=2025.5、react 19、react-router 7 和 @shopify/remix-oxygen 3。react-error-boundary 和 @weaverse/schema 会作为传递依赖引入 — 它们未出现在主题的 package.json 中也没关系。
3. 5.15 中已知的破坏性更改：errorComponent 的类型为 FC<{ error: unknown }>（之前是类似 Error 的对象）。移植上游 Pilot 的 GenericError，它会在运行时缩窄类型（error && typeof error === "object" && "message" in error）。
4. 最后运行完整的 shopify hydrogen build --codegen — 仅运行类型检查无法发现打包器层面的问题。

Weaverse 内部：Pilot 锁定与演示部署

• Pilot 位于 Weaverse pnpm 单体仓库中，但使用 npm 锁文件。使用 npm i --package-lock-only --workspaces=false 刷新锁文件；普通的 npm i 会因单体仓库的 catalog: 协议而失败。
• 部署 pilot.weaverse.dev：合并到 Weaverse/pilot 的 main，然后运行 gh repo sync Weaverse/pilot-demo --source Weaverse/pilot — 该分支带有 Oxygen 部署操作，并会在同步后部署（约 1 分钟）。