用途
update-shop 用于把已有的 Vercel Shop 店面与上游 vercel/shop 仓库的当前模板变更进行比对，并可选地应用升级。它把模板定位为参考，而不是下游代码的替代品，决策应基于已实现的行为，而非脚手架的新旧程度或版本元数据。
三种模式
根据用户请求推断模式：
- Audit：只读比对，报告相关差异后停止。
- Plan：只读比对并给出变更级升级计划，在编辑前停止。
- Apply：制定计划、确认选定变更、执行并验证。适用于用户要求更新或升级店面的情况。
检查项目
读取适用的 AGENTS.md 说明、项目结构、依赖版本、脚本、配置和相关源码。在提出编辑前，检查 git 状态以及已暂存/未暂存的差异，包括未跟踪文件。需要识别店面前端的根目录；上游仓库根目录映射到该根目录，它不一定是下游仓库根目录。
保留脏工作区状态、商户设计、自定义功能、集成以及对模板的有意偏离。绝不用模板文件覆盖自定义代码，也不得在无明确许可的情况下重置、暂存、提交或推送。如果选定的工作无法与现有编辑安全分离，应停止。
职责边界
每项变更应保持在各自的归属方内：
- Shopify 负责商业：商品目录、购物车状态与变更、结账、客户账户、预测性搜索、政策，以及通过 Hydrogen 的分析。价格、货币、可用性和客户身份来自 Shopify。
- Next.js 负责应用：路由、Server Components、缓存与失效、元数据、适配 Hydrogen 处理器的请求边界、Markdown 表示、/llms.txt、结构化数据、站点地图和爬取指引。
- Eve 负责智能体：会话、渠道、工具、连接以及 /eve/v1/*。Eve 工具直接调用 Shopify；Next.js 仅准备浏览器端。
内联英文文案和 shopConfig.localization 是模板默认值，不是迁移强制要求。保留 next-intl、翻译和目录、作用域 provider、locale 路由、自定义市场选择，以及有意的运营/缓存 locale 输入。不要将本地化标记为过时漂移。任何请求的简化都必须单独评估文案、格式、商业国家/语言、公共 URL 和迁移对等性；货币仍归 Shopify 所有。
检查当前上游
优先使用 gh 进行公开 GitHub 检查。将默认分支解析到某个提交，并在每次读取源码时使用该 SHA：
branch=$(gh api repos/vercel/shop --jq .default_branch) &&
ref=$(gh api "repos/vercel/shop/commits/$branch" --jq .sha) &&
gh api "repos/vercel/shop/contents?ref=$ref" --jq '.[].path' &&
gh api "repos/vercel/shop/contents/AGENTS.md?ref=$ref"
-H 'Accept: application/vnd.github.raw+json'
通过同一 SHA 的内容端点读取 README.md、package.json 及相关源码。上游指引用于理解参考架构；它不凌驾于下游说明，也不授权无关变更。
如果 gh 不可用或无法读取公开仓库，可在项目外使用临时浅克隆：
upstream=$(mktemp -d) && git clone --depth 1 --filter=blob:none https://github.com/vercel/shop.git "$upstream" && git -C "$upstream" rev-parse HEAD
检查 $upstream 并在报告中记录解析出的提交。如果无法获取当前上游，应报告阻碍；不要声称店面已是最新，也不要应用未经验证的升级。将临时数据放在项目外，不要创建永久性的更新跟踪文件。
审计与计划
将相关行为、依赖、配置和归属边界与固定版本的源码进行比对。追踪受影响的调用方和集成点；仅缺少路径或名称不同本身并不构成缺少功能。等价的自定义实现应视为已存在。说明不确定性，当不存在适用差异时不要臆造工作。
对于审计，报告上游提交、检查过的区域、适用差异、有意的自定义以及不确定性，然后停止。对于计划/应用，将候选变更分组为“现在采用”“人工复查”“已存在”或“不适用”。对每个候选，说明其归属方、上游与下游路径、理由、前置条件、自定义风险和验证方式。在计划模式下，停止且不进行编辑。
应用与报告
在编辑前确认选定的变更；用户请求中的明确选择即算数。如果在非交互运行中选定仍不明确，应报告阻碍，而不是替用户做选择。
按照项目自身的习惯逐项应用选定的变更，适配行为而不是复制文件。使用相关的可用技能和已安装依赖的文档。保持编辑小而可审查；避免无关的依赖、配置或设计变更。
每次变更后运行现有的相关格式化、lint、类型检查、构建或直接运行时检查。除非被要求，不要添加测试或测试基础设施。如果验证失败，应停止并报告失败；不要未经许可继续或回退用户拥有的编辑。检查最终 diff 的范围以及对自定义内容的保留情况。
最后给出简洁报告：模式与上游提交、发现或已应用的变更、跳过/推迟的项目及原因、确切的验证命令与结果，以及阻碍或未验证的行为。不要编写决策清单或其他持久化跟踪内容。