theme-update

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Theme Update — Weaverse Pilot

主题更新 — Weaverse Pilot

Safely upgrade a Weaverse Pilot theme from its current version to a newer release. This skill walks through detection, planning, execution, and verification — never overwriting user customizations without explicit approval.

安全将Weaverse Pilot主题从当前版本升级到新发布版本。本技能将引导你完成检测、规划、执行和验证全流程，未经用户明确许可绝不会覆盖自定义修改。

Source

来源

Theme repo: https://github.com/Weaverse/pilot
Releases: https://github.com/Weaverse/pilot/releases
Package name:
```
@weaverse/pilot
```
Versioning:
```
YYYY.M.D
```
(e.g.,
```
2026.4.7
```
). Older: semver (
```
v8.1.0
```
)

主题仓库：https://github.com/Weaverse/pilot
版本发布页：https://github.com/Weaverse/pilot/releases
包名：
```
@weaverse/pilot
```
版本规则：
```
YYYY.M.D
```
（例如
```
2026.4.7
```
），旧版本使用semver规则（
```
v8.1.0
```
）

Quick Check

快速检查

bash

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

bash

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

Procedure

操作流程

Follow these phases in order. Do NOT skip steps.

请按顺序执行以下阶段，请勿跳过步骤。

Phase 1 — Detection

阶段1 — 检测

Read
```
package.json
```
→ get
```
version
```
field
If
```
name
```
is not
```
@weaverse/pilot
```
, ask the user to confirm this is a Pilot-based project
Fetch releases:

bash

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

Identify all releases between current version and latest (or user-specified target)
Present to user:
- Current version
- Target version (latest unless specified)
- Number of intermediate releases
- Summary of key changes (features, fixes, breaking changes)

If already on latest → stop here and tell the user.

读取
```
package.json
```
文件，获取
```
version
```
字段值
如果
```
name
```
字段不是
```
@weaverse/pilot
```
，请询问用户确认当前项目是否为基于Pilot的项目
拉取版本发布信息：

bash

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

识别当前版本到最新版本（或用户指定的目标版本）之间的所有发布版本
向用户展示以下信息：
- 当前版本
- 目标版本（未指定则默认最新版本）
- 中间版本数量
- 核心变更概要（功能、修复、破坏性变更）

如果当前已是最新版本 → 终止流程并告知用户。

Phase 2 — Branch

阶段2 — 新建分支

bash

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

Always work on a branch. Never update on main directly.

bash

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

必须在分支上操作，禁止直接在main分支上更新。

Phase 3 — Plan

阶段3 — 规划更新

For each release in the update range (oldest to newest):

Fetch the diff between consecutive versions:

bash

undefined

针对更新范围内的每个版本（从旧到新）：

拉取相邻版本之间的差异：

bash

undefined

Full comparison URL

完整对比URL

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

Raw diff

原始diff文件

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


2. **Download the target version's source** (for reference files):

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

Categorize every changed file into three buckets:

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


2. **下载目标版本的源代码**（作为参考文件）：

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

将所有变更文件分类到三个组别：

Auto-merge (safe to apply without asking)

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

```
package.json
```
version bump, dependencies

Lock files (

package-lock.json

bun.lockb

pnpm-lock.yaml

)

tsconfig.json

vite.config.ts

tailwind.config.ts

— ONLY if user hasn't customized them

New files that don't exist in user's project (additive only)
```
.github/
```
,
```
CHANGELOG.md
```
,
```
LICENSE
```

```
package.json
```
版本号提升、依赖更新

锁文件（

package-lock.json

、

bun.lockb

、

pnpm-lock.yaml

）

```
tsconfig.json
```
、
```
vite.config.ts
```
、
```
tailwind.config.ts
```
— 仅当用户未自定义这些文件时
用户项目中不存在的新增文件（仅增量添加）
```
.github/
```
目录、
```
CHANGELOG.md
```
、
```
LICENSE
```

Needs review (show diff, get approval)

需要审核（展示diff，获取用户批准）

```
app/components/
```
— UI components user may have customized
```
app/routes/
```
— route files user may have modified
```
app/lib/
```
— utility modules

app/root.tsx

app/entry.client.tsx

app/entry.server.tsx

```
app/styles/
```
— CSS/Tailwind changes
Any file where the user has local changes (
```
git diff
```
shows modifications from Pilot base)

```
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基准版本有差异）

Skip (mention but don't touch)

跳过（仅告知，不修改）

Files the user deleted (they removed the feature intentionally)
Files in directories the user reorganized
```
.env
```
,
```
.env.example
```
— never overwrite environment files

Present the plan in a clear table:

undefined

用户已删除的文件（用户主动移除了对应功能）
用户重构过的目录下的文件
```
.env
```
、
```
.env.example
```
— 绝不覆盖环境变量文件

以清晰的表格形式展示更新计划：

undefined

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


**Wait for user confirmation before proceeding.** Ask:
> "Review the plan above. Approve to continue, or tell me which files to handle differently."

⏭️ app/components/CombinedListings.tsx — you deleted this file


**继续前请等待用户确认**，询问：
> "请审核以上更新计划，批准即可继续，或者告知我需要调整哪些文件的处理方式。"

Phase 4 — Execute

阶段4 — 执行更新

Apply changes in order, one release at a time if multi-version jump:

按顺序应用变更，如果是跨多个版本升级，请逐个版本应用：

4a. Auto-merge files

4a. 自动合并文件

bash

undefined

bash

undefined

Copy new file from Pilot source

从Pilot参考源码复制新文件

cp /tmp/pilot-reference/{FILE_PATH} {FILE_PATH}

Or apply targeted patch

或者应用定向补丁

git apply --3way <patch-file>


After each auto-merge, verify with `git diff --stat`.

git apply --3way <patch-file>


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

4b. Needs-review files

4b. 需要审核的文件

For each file:

Show a three-way comparison:
- Pilot at user's version (baseline)
- Pilot at target version (their changes)
- User's current file (local modifications)
Identify what the user changed vs what Pilot changed:
- User-only changes → preserve
- Pilot-only changes → apply
- Overlapping changes → flag conflict
For conflicts, present options:
- Accept Pilot's version (lose user customization)
- Keep user's version (skip Pilot improvement)
- Manual merge (show both, let user edit)
- Smart merge (try to combine both — only if non-overlapping regions)
Wait for user decision on each conflict before proceeding.

针对每个文件：

展示三方对比：
- 对应用户当前版本的Pilot基准代码
- 目标版本的Pilot代码（官方变更）
- 用户当前的文件（本地修改）
区分用户修改和Pilot官方修改：
- 仅用户修改的内容 → 保留
- 仅Pilot官方修改的内容 → 应用
- 重叠修改 → 标记为冲突
针对冲突，提供以下选项：
- 接受Pilot官方版本（丢失用户自定义内容）
- 保留用户版本（跳过Pilot的优化内容）
- 手动合并（展示两个版本，让用户编辑）
- 智能合并（仅当修改区域不重叠时尝试合并两个版本）
继续前请等待用户对每个冲突的处理决策。

4c. Commit per release

4c. 每个版本更新后提交

bash

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

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

If doing multi-version jump, repeat for each intermediate release.

bash

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

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

如果是跨多个版本升级，每个中间版本都重复以上操作。

Phase 5 — Verify

阶段5 — 验证

After all changes applied:

bash

undefined

所有变更应用完成后：

bash

undefined

1. Install dependencies

1. 安装依赖

bun install # or npm install / pnpm install based on lockfile

bun install # 或者根据锁文件使用npm install / pnpm install

2. TypeScript check

2. TypeScript检查

bun run typecheck

3. Build check

3. 构建检查

bun run build


**If build fails:**
1. List the errors
2. Analyze root cause (dependency mismatch? breaking change missed?)
3. Propose fixes
4. Apply fixes with user approval
5. Re-run build

**If build succeeds:**
1. Run `bun run dev` briefly to check no runtime errors
2. Summarize all changes made
3. List any **manual follow-up steps**:
   - New features that need configuration
   - Breaking changes requiring code updates in customized files
   - Deprecated patterns to migrate later

bun run build


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

**如果构建成功：**
1. 短暂运行`bun run dev`检查是否存在运行时错误
2. 汇总所有已应用的变更
3. 列出所有**手动后续步骤**：
   - 需要配置的新功能
   - 需要在自定义文件中适配的破坏性变更
   - 后续需要迁移的弃用写法

Phase 6 — Finalize

阶段6 — 收尾

Present final summary:

undefined

展示最终汇总：

undefined

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

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

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. Ask user: "Ready to merge into main?"

```bash

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


2. 询问用户："是否准备合并到main分支？"

```bash

If approved

获得批准后执行

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

---

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

---

Safety Rules

安全规则

Always branch first — never update on main directly
Never overwrite without asking — every file that could have user changes needs review
Commit per release — easy to bisect if something breaks
Build must pass — don't declare success until
```
typecheck
```
+
```
build
```
both pass
Offer rollback — always tell user how to undo the whole update
Respect user deletions — if they removed a file, don't re-add it without asking

永远先新建分支 — 禁止直接在main分支上更新
绝不未经询问覆盖内容 — 每个可能存在用户修改的文件都需要审核
每个版本单独提交 — 出现问题时方便二分排查
必须通过构建 — 只有
```
typecheck
```
和
```
build
```
都通过才算更新成功
提供回滚方案 — 永远告知用户如何撤销整个更新
尊重用户的删除操作 — 如果用户删除了某个文件，未经询问不要重新添加

Common Pitfalls

常见陷阱

Version format: package.json has no
```
v
```
prefix (
```
2026.4.7
```
), GitHub tags have
```
v
```
prefix (
```
v2026.4.7
```
). Always normalize.
Lock files: After updating
```
package.json
```
, MUST run the correct package manager (check which lockfile exists)
Custom components: User components not in original Pilot are always preserved — never delete or move them
Route structure: If user reorganized routes, don't force Pilot's structure — apply route logic changes to user's structure instead
CSS conflicts: Pilot may change Tailwind classes or base styles — these need careful merge to avoid breaking user styling

版本格式：package.json中的版本没有
```
v
```
前缀（
```
2026.4.7
```
），GitHub标签有
```
v
```
前缀（
```
v2026.4.7
```
），请始终做归一化处理
锁文件：更新
```
package.json
```
后，必须使用正确的包管理器运行安装（检查存在的锁文件类型）
自定义组件：原始Pilot中不存在的用户自定义组件会永久保留 — 绝不删除或移动
路由结构：如果用户重构了路由结构，不要强制使用Pilot的结构 — 将路由逻辑变更适配到用户的结构中
CSS冲突：Pilot可能修改Tailwind类名或基础样式 — 需要谨慎合并避免破坏用户样式