setup-weaverse-project

设置 Weaverse 项目 — Agent 技能

带领用户从零开始，搭建一个正在运行并已连接的 Weaverse Hydrogen 店面。 这是入口。所有其他 Weaverse 技能都假设项目已经存在——本技能负责创建项目。

解决入门问题的一条规则

在索要任何凭据之前，先在演示商店上启动实时预览。

大多数用户会在看到任何内容正常运行之前，就被 GitHub、Shopify 令牌或 CLI 这些关卡挡住，从而放弃入门流程。Weaverse 主题在 .env.example 中附带了可用的演示商店令牌，因此无需任何凭据，就能在约 2 分钟内展示一个真实运行的店面。先这样做。让用户感受到“哇”的一刻，然后再让它成为他们自己的店面。

在用户看到店面运行之前，不要让他们创建 GitHub 仓库、关联 Shopify 商店或粘贴令牌。如果这样做了，即使每条命令都成功，也说明入门流程失败了。

由你驱动 CLI——用户只需点击浏览器流程

用户（商家或开发者）绝不应该需要输入 CLI 命令。由你在后台运行 shopify hydrogen 和 @weaverse/cli。Shopify CLI 会执行实际工作（拉取环境变量、启动开发服务器、代码生成、部署）——由你驱动它，不要重新实现这些功能。npm run dev 本身也会调用 shopify hydrogen dev，因此 CLI 始终会参与其中；只需让用户看不到即可。

用户只需：批准浏览器流程、在商店选择器中选择商店、复制凭据并提供密钥。绝不要让他们粘贴命令。

你需要的输入

尽量少询问。大多数设置值都会自动生成或自动发现。

需要在设置提示词中提供或由用户提供：

• WEAVERSE_PROJECT_ID — 来自 Weaverse Builder
• 主题标识符 — 仅在未提供时默认使用 pilot
• 项目文件夹名称 — 默认使用 my-hydrogen-storefront

稍后为真实商店所需：

• PUBLIC_STORE_DOMAIN
• PUBLIC_STOREFRONT_API_TOKEN

由你生成：

• SESSION_SECRET — 绝不要向用户索要；生成一个随机值

稍后可选：

• PRIVATE_STOREFRONT_API_TOKEN
• SHOP_ID
• 客户账户变量
• 结账域名
• 分析/评价变量

---

阶段 0 — 检测环境

开始之前，先检测并记录（不要假定）：

node --version            # need >= 18
git --version
gh --version 2>/dev/null && gh auth status 2>/dev/null   # is GitHub CLI present AND authed?
npx shopify version 2>/dev/null                          # Shopify CLI availability
npx @weaverse/cli@latest create --help 2>/dev/null        # CLI availability + template choices
ls package-lock.json pnpm-lock.yaml yarn.lock 2>/dev/null # infer package manager

后续步骤都基于此进行分支处理。如果缺少 gh 或未通过身份验证，则使用阶段 6 中的手动仓库备用方案。如果 Node 版本低于 18，则停止并告知用户升级。

---

阶段 1 — 使用 Weaverse CLI 搭建主题脚手架

优先使用 Weaverse CLI，而不是 git clone。它了解受支持的模板，会下载正确的源代码，并写入初始环境文件。

npx @weaverse/cli@latest create \
  --template=<theme-handle> \
  --project-id=<WEAVERSE_PROJECT_ID> \
  --project-name=<project-folder> \
  --no-install \
  -y

cd <project-folder>
git init

规则：

• 如果缺少主题标识符，则默认使用 pilot。

• 如果 CLI 拒绝某个主题（例如过时或不存在的 blank 标识符），则显示受支持的模板列表，并让用户选择替代项。不要擅自切换主题。

• 如果已安装的 CLI 不支持 --no-install，则让 CLI 安装依赖，然后从已创建的文件夹继续操作。

• 不要手动编写 GitHub 下载器。优先使用 CLI；仅当 CLI 不可用且主题仓库存在时，才使用 clone/degit。

• 使用 clone/degit 作为备用方案后，删除 CLI 本应移除的内容，然后重新开始历史记录：

  rm -rf .git .github .weaverse
  git init
  

  .git 是主题仓库的历史记录（其 origin 会导致阶段 3 中的 GitHub 推送失败），.github 存放主题的内部工作流（Oxygen 部署、CI、代码审查），这些工作流在没有 Weaverse 密钥时会失败，而 .weaverse 存放内部规范。

---

阶段 2 — 惊艳时刻（在演示商店上启动）

这是核心环节。在索要 Shopify 凭据之前，先使用演示 Shopify 凭据启动实时预览。

首先，确保服务器启动之前.env 已配置完整（开发服务器会在启动时读取环境变量——之后再修复就意味着必须重启）：

• CLI 生成的 .env 应已包含演示 Shopify 值以及用户的 WEAVERSE_PROJECT_ID。如果缺少 .env，请将 .env.example 复制为 .env，然后根据设置提示填写 WEAVERSE_PROJECT_ID。
• 切勿向用户索要 SESSION_SECRET。如果缺少该变量，或其值仍是演示占位符（例如 foobar），请生成一个并立即写入 .env：

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

然后启动：

npm install                   # or pnpm/yarn per lockfile
npm run dev                   # boots http://localhost:3456

然后，在声称启动成功之前，确认它确实已启动：

curl -sf -o /dev/null -w "%{http_code}" http://localhost:3456   # expect 200

用通俗的语言告诉用户：

“你的店面正在本地运行，地址为 http://localhost:3456 — 这是 Weaverse 演示商店。接下来，我们会把它变成你的商店。”

在预览启动并确认正常之前，不要继续索要凭据。

---

阶段 3 — 打造用户自己的商店（Shopify 凭据）

现在，将演示商店替换为用户自己的商店。渲染 Weaverse 预览所需的最少变量包括：

• PUBLIC_STORE_DOMAIN — their-store.myshopify.com
• PUBLIC_STOREFRONT_API_TOKEN — Storefront API 访问令牌
• WEAVERSE_PROJECT_ID — 参见阶段 4（这是唯一无法从 Shopify 获取的变量）

Hydrogen 仍然需要 SESSION_SECRET，但它由 Agent 生成。其他所有内容（SHOP_ID、PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID、PUBLIC_CHECKOUT_DOMAIN、PUBLIC_STOREFRONT_ID、分析、评价）都是功能完善所需的额外配置——首次成功后再设置，绝不能因此阻塞流程。

仅有一种方式：安装 Hydrogen 应用并关联店面

Hydrogen 支持 Shopify 开发商店。没有 Headless 应用的备用方案：无论套餐如何，本地关联和凭据设置都要通过 Hydrogen 应用完成。

1. 让用户安装 Hydrogen 应用：https://apps.shopify.com/hydrogen。用户可能需要选择商店、批准安装，并在应用中创建 Hydrogen 店面项目。
2. 关联店面（由你执行）：

   npx shopify hydrogen link
   

   如果出现商店选择器，请向用户确认要选择的准确 .myshopify.com 域名——不要根据商店列表猜测。
3. 拉取环境变量（由你执行）：

   npx shopify hydrogen env pull
   

   这会将商店的真实变量写入 .env。如果拉取操作覆盖了 WEAVERSE_PROJECT_ID 和生成的 SESSION_SECRET，请保留它们。
4. 替换之前先验证——绝不要用未经验证的凭据替换演示凭据。检查 .env 中是否已包含真实值，而非占位符：

   grep -E "^(PUBLIC_STORE_DOMAIN|PUBLIC_STOREFRONT_API_TOKEN)=" .env
   

   PUBLIC_STORE_DOMAIN 必须是商店实际的 <store>.myshopify.com 域名，PUBLIC_STOREFRONT_API_TOKEN 必须是非空的 Storefront API 令牌。只有验证通过后才能替换（拉取操作已完成替换）；然后重新执行阶段 2 中的验证：

   curl -sf -o /dev/null -w "%{http_code}" http://localhost:3456   # expect 200
   

如实说明限制，仅说明一次： 公开的 Oxygen / 可分享的生产环境仍取决于商店的 Shopify 套餐。本地关联和凭据设置则不受影响——它们可通过 Hydrogen 应用在开发商店中使用。 环境文档：https://shopify.dev/docs/storefronts/headless/hydrogen/environments 入门指南：https://shopify.dev/docs/storefronts/headless/hydrogen/getting-started

如果 env pull 不可用或执行失败，请让用户从 Shopify Admin → Hydrogen app → Storefront settings → Environments and variables 复制变量；你将渲染所需的最少变量写入 .env，并按上述步骤验证。

---

阶段 4 — 项目标识（WEAVERSE_PROJECT_ID）

WEAVERSE_PROJECT_ID 是唯一仅存在于 Weaverse Builder 中、无法从 Shopify 推导出的值。

Weaverse Builder 生成的设置提示词中包含项目的 WEAVERSE_PROJECT_ID（和主题名称）。从收到的提示词中读取该值，并将其写入 .env。如果没有收到该值，请让用户从 Weaverse Studio → Project Settings 中复制。

---

阶段 5 — Weaverse API 令牌 + MCP（通过聊天实时编辑）

Weaverse MCP 可让 Agent 直接通过聊天读取和编辑此项目（以及同一商店中的其他项目），包括通过已挂载的 Content API 实时写入页面/内容。

1. 创建令牌（由用户操作）。 用户在 Weaverse Studio → Dashboard → Account/Settings → API Keys 中创建 Weaverse API token（https://studio.weaverse.io）。将其复制到环境中，作为 WEAVERSE_API_KEY — 绝不要写入受版本控制的文件，也绝不要写入提示词。
2. 配置 MCP 服务。 在 Agent 的 MCP 配置中添加 @weaverse/mcp@latest，并将 bearer 环境变量准确设置为：

   WEAVERSE_API_KEY=<token>
   

   不同客户端（Cursor、Claude Code、Codex、opencode、VS Code、pi 等）的配置格式各不相同；各客户端的具体配置片段请参阅文档：https://weaverse.io/docs/developer-tools/weaverse-mcp
3. 验证读取功能。 使用实际的读取工具：list_projects、get_project、list_pages、get_page、get_theme_settings、list_languages、get_openapi_spec。没有 whoami 工具。
4. 默认关闭实时写入 — 仅在获得同意后启用。 六种写入工具都要求将环境变量准确设置为：

   WEAVERSE_ENABLE_LIVE_WRITES=true
   

   设置后可使用：update_project、create_page、delete_pages、update_page、assign_template_resources、update_theme_settings。 启用前，请用通俗语言说明： 启用实时写入后，这些工具会更改在线店面的内容 — update_page 会编辑实际页面项，create_page/delete_pages 会创建/删除实际页面，assign_template_resources 会将 Shopify 资源添加到一个现有的共享模板页面（绝不会将分配关系从其他页面转移；如果任何 handle 已属于其他在线页面，整个批次都会因 409 错误被拒绝，且不会写入任何内容），update_theme_settings 会更改主题设置，update_project 会重命名项目。写入会通过与 Studio 保存相同的缓存失效流程立即生效 — 没有单独的发布步骤。每次写入后，都要重新读取受影响的资源以确认更改。

此功能是为未来的工作提供便利 — 并非完成设置所必需。如果用户使用的 Agent 不支持 MCP，请跳过此步骤。

---

第 6 阶段 — 创建用户的仓库并推送（先询问）

推送会在用户的 GitHub 帐户下创建仓库并发布他们的代码，这是必须经用户批准的外部操作。切勿因此阻止本地设置：如果用户未批准，店面仍可在本地正常运行，设置仍可报告为已完成。

在执行任何 gh repo create、git commit 或 git push 之前，务必先询问——包括 gh 已完成身份验证的情况。检测到的 gh 状态只决定批准后如何执行，绝不代表用户已批准。请询问并复述以下信息：

• 确切的仓库名称（默认为 <project-folder>），
• 可见性（除非用户另有说明，否则为私有），
• 是否确认进行首次推送。

获得批准后，如果 gh 存在且已通过身份验证（第 0 阶段）：

git add -A
git commit -m "Initial commit: Weaverse Hydrogen storefront"
gh repo create <approved-name> --private --source=. --remote=origin --push

如果仓库名称已存在，请先检查，再采取操作：

gh repo view <owner>/<approved-name> --json isEmpty,sshUrl,url

• 空仓库 → 将其添加为 origin 并推送。
• 非空仓库 → 不要覆盖或强制推送。提出一个不同的名称，例如 <project-folder>-pilot 或 <project-folder>-weaverse，并在继续之前就该名称征求批准。

**获得批准后，如果缺少 gh / 尚未通过身份验证：**提供可点击的操作路径，并请用户启用推送：

1. 验证 GitHub CLI 身份（https://github.com/login），或在 https://github.com/new 创建新的空仓库（不要添加 README）。
2. 然后运行（由你填入用户的 URL）：

   git add -A && git commit -m "Initial commit: Weaverse Hydrogen storefront"
   git remote add origin https://github.com/<user>/<repo>.git
   git branch -M main && git push -u origin main
   

**如果用户拒绝或未回复：**明确说明，保留仅在本地提交（或未提交）的工作，然后继续。不要在未获提示的情况下再次尝试推送。

**切勿提交 .env 或密钥。**确认 .gitignore 已覆盖 .env*（脚手架自带该文件），并确认提交中不会包含任何令牌。如果密钥已暂存，先取消暂存并将其加入 .gitignore，然后再提交。

切勿将“由 Agent 执行”和“由用户执行”作为同一步骤呈现——获得批准后，根据第 0 阶段的检测结果选择路径，并说明你将采用哪种路径。

---

第 7 阶段 — 将预览连接到 Weaverse Builder

引导用户：在 Builder 中，点击预览地址栏里的 URL，然后选择 管理预览（或 Builder → 项目设置 → 管理 URL，在 Preview URLs 部分）→ 添加 http://localhost:3456 → 保存。

---

第 8 阶段 — 验证（成功判定标准）

未通过以下检查，不要声称设置成功：

curl -sf -o /dev/null -w "%{http_code}" http://localhost:3456   # 200
npm run typecheck                                               # passes

建议在交接或生产环境准备之前进行完整检查：

npm run build

此外，如果用户可以检查，请确认 Builder 中的 Weaverse 预览显示为已连接。如果任何必需检查未通过，请先修复再报告完成；如果无法修复，请准确报告未通过的检查项。

---

第 9 阶段 — 安装完整技能包（收尾）

最后，在生成的店面项目内部（不能在其他位置）安装完整的 shopify-hydrogen-skills 技能包——所有技能、所有 Agent，并以非交互方式安装。设置请求明确要求了此操作，因此预期会执行安装：

npx skills@latest add Weaverse/shopify-hydrogen-skills --all

然后检查生成的内容：

git status --short          # review what the pack install generated

**发布这些更改属于单独的外部操作——请再次征求批准。**向用户展示 git status 的文件列表以及拟定的提交消息，然后等待批准，再运行以下任何命令：

git add -A && git commit -m "Add shopify-hydrogen-skills pack"
git push

如果用户拒绝，请将已安装的技能包留在工作区中，并说明它尚未提交。切勿无条件运行此提交/推送代码块。

---

完整流程（速查表）

1. 检测环境（node、gh+auth、shopify CLI、包管理器）。
2. 使用 npx @weaverse/cli@latest create（默认值为 pilot）搭建项目 → git init。
3. 如有需要，生成 SESSION_SECRET。
4. 在 Shopify 演示商店上启动（安装、npm run dev、验证返回 200）。← 惊喜时刻。
5. 切换到用户的商店：安装 Hydrogen 应用 → npx shopify hydrogen link → npx shopify hydrogen env pull → 确认 PUBLIC_STORE_DOMAIN 和 PUBLIC_STOREFRONT_API_TOKEN 是真实值后再信任它们。
6. 创建仓库和首次推送前，征求批准，确认仓库名称和可见性（获得批准后运行 gh repo create，也可手动操作）。切勿提交 .env 或机密信息。
7. 配置 Weaverse MCP（WEAVERSE_API_KEY；只有在获得同意后，才通过 WEAVERSE_ENABLE_LIVE_WRITES=true 执行实时写入）。
8. 在 Builder 中连接预览 URL（Manage previews）。
9. 验证必需检查（返回 200 + 类型检查）；准备交接或用于生产环境时运行构建。
10. 安装完整技能包：npx skills@latest add Weaverse/shopify-hydrogen-skills --all；检查 git status，然后在提交或推送前征求批准。

必需变量速查

变量	渲染时是否需要？	来源
SESSION_SECRET	是	Agent 生成的随机字符串
PUBLIC_STORE_DOMAIN	是	Shopify Hydrogen 应用（env pull）
PUBLIC_STOREFRONT_API_TOKEN	是	Shopify Hydrogen 应用（env pull）
WEAVERSE_PROJECT_ID	是	Weaverse Builder（设置提示词）
WEAVERSE_API_KEY	仅 MCP 需要	Weaverse Studio → Dashboard → Account/Settings → API Keys
SHOP_ID、customer-account、checkout、storefront-id、analytics	否（功能完整时）	Shopify / 后续配置