migrate-googleai

规则：将 Google AI Studio 原型迁移为 Domo App Platform 自定义应用（静态 dist 部署）

你正在将一个始于 Google AI Studio（通常面向 Cloud Run / 预览）的项目，转换为通过 Domo CLI 以静态资源方式部署的 Domo App Platform 自定义应用。 所需的部署约定是：

1. npm run build 必须生成一个自包含的 dist/ 文件夹
2. cd dist && domo publish 必须可用（Domo 从子路径提供应用，而不是从站点根目录）
3. 应用必须能正确加载资源，并且在刷新/导航时不会出错

识别 AI Studio 来源

如果出现以下任意情况，就将该项目视为“AI Studio 来源”：

• README 提到 Google AI Studio / Gemini API / “Build” 模式 / Cloud Run
• cloudbuild.yaml、Dockerfile 或 Cloud Run 部署说明
• 使用 process.env.GEMINI_API_KEY 或描述为“由 AI Studio 提供”的占位符
• 通过服务器/容器而非静态托管运行的结构

如果检测到，请应用以下步骤。

---

主要目标

让该项目成为一个常规前端，使其：

• 可通过 npm run dev 在本地运行
• 可通过 npm run build 将生产文件生成到 dist/
• 可从非根子路径托管（Domo App Platform）
• 渲染 UI 不需要任何服务器运行时

---

第 1 步 — 确保存在标准构建流水线

打开 package.json，并确保脚本存在且适用于所选工具链：

• 如果是 Vite：

  • dev：vite
  • build：vite build
  • preview：vite preview
  • 确认输出为 dist/

• 如果是 CRA：

  • build 默认输出到 build/（不符合我们的约定）
  • 要么： A) 迁移到 Vite（App Platform 的首选），或者 B) 相应地更新 Domo 发布文档/命令（仅在用户明确想要 CRA 时）

如果不确定，默认使用 Vite。

验收标准：

• npm install 成功
• npm run build 生成包含 index.html 和 assets/* 的 dist/

---

第 2 步 — 修复 base，使资源在 Domo（子路径托管）中可用

Domo App Platform 不会将你的应用托管在 /。它位于嵌套路径下。 因此资源路径必须为相对路径或显式指定。

• 如果是 Vite：将 base 设置为相对路径

  • 在 vite.config.* 中：base: './'

• 如果是其他打包工具：确保等效的“public path”为相对路径。

验收标准：

• 从嵌套路径打开构建后的 dist/index.html 时，仍能加载 JS/CSS 资源（无 404）。
• 没有硬编码的绝对资源路径，如 /assets/...，除非你确定宿主根目录。

---

第 3 步 — 使路由在静态托管下稳健可靠

如果应用使用 React Router（或任何客户端路由器）：

• 在 App Platform 上优先使用 HashRouter，除非你确定平台提供 SPA 重写。
• 如果切换到 HashRouter 侵入性太大，请说明：除非 Domo 配置了重写规则，否则在深层路由上刷新会 404。

默认操作：

• 如果存在路由器且未知是否有重写控制：切换到 HashRouter。

验收标准：

• 构建后的应用无需服务器重写即可导航和刷新。

---

第 4 步 — 环境变量与密钥：移除仅适用于 AI Studio 的假设

AI Studio 可以在其托管运行期间“神奇地”提供占位符（例如 Gemini API 密钥）。 在 Domo App Platform 中，浏览器无法安全地保存密钥。

规则：

• 不要在客户端代码中发布任何原始 API 密钥。
• 如果 UI 需要 Gemini/LLM 调用：
  • 如果可用/允许，优先通过 domo.js 使用 Domo AI API，或者
  • 通过后端（例如 Domo Code Engine）代理，在服务端注入密钥。
• 将 process.env.* 模式替换为工具链原生环境变量用法：
  • Vite：import.meta.env.VITE_*
• 添加 .env.example，记录所需变量（仅非密钥）。

验收标准：

• 没有提交的密钥。
• 不会因缺少 AI Studio 环境变量注入而导致运行时崩溃。

---

第 5 步 — Domo 部署约定

确保最终开发者工作流为：

• npm run build
• cd dist
• domo publish

如果 App Platform 项目需要 Domo 清单/配置文件（例如 manifest.json），请确保它位于 Domo 期望的位置，或在构建期间复制到 dist/ 中。

如果平台期望清单位于根目录但发布 dist/，请实现以下之一：

• 作为构建的一部分，将所需配置/清单复制到 dist/ 中（postbuild 脚本）
• 或者如果用户既定的标准不同，则调整发布策略

默认：

• 添加 postbuild 脚本，将所需应用平台文件复制到 dist/ 中（如果它们缺失）。

验收标准：

• dist/ 包含发布和运行所需的一切。
• 在 dist/ 内运行 domo publish 无需手动复制文件即可成功。

---

输出要求（你作为助手必须交付的内容）

应用更改后，提供：

1. 已更改文件的简短列表
2. 在本地运行的确切命令
3. 一份“完成检查清单”，确认：
   • 构建生成 dist/
   • 资源在子路径下加载
   • 路由正常工作（hash 路由或已记录的 rewrite 需求）
   • 客户端中没有密钥

要果断；实施更改，而不是提出后续问题，除非因缺少文件而受阻。