wf-apps-migrate-googleai

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rule: Migrate Google AI Studio prototype to Domo App Platform Custom App (static dist deploy)

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

You are converting a project that began in Google AI Studio (often Cloud Run / preview oriented) into a Domo App Platform Custom App deployed as static assets via the Domo CLI. The required deployment contract is:

```
npm run build
```
must produce a self-contained
```
dist/
```
folder
```
cd dist && domo publish
```
must work (Domo serves the app from a subpath, not from site root)
The app must load assets correctly and not break on refresh/navigation

你需要将一个始于Google AI Studio（通常面向Cloud Run/预览环境）的项目，转换为可通过Domo CLI以静态资产形式部署到Domo App Platform的自定义应用。所需遵循的部署规范如下：

```
npm run build
```
必须生成一个独立的
```
dist/
```
文件夹
执行
```
cd dist && domo publish
```
必须能够成功运行（Domo会从子路径而非站点根目录提供应用服务）
应用必须能正确加载资源，且在刷新/导航时不会崩溃

Detect AI Studio origin

检测是否源自AI Studio

Treat the project as "AI Studio-origin" if you see any of:

README mentions Google AI Studio / Gemini API / "Build" mode / Cloud Run
cloudbuild.yaml, Dockerfile, or Cloud Run deploy instructions
use of
```
process.env.GEMINI_API_KEY
```
or placeholders described as "provided by AI Studio"
structure that runs via a server/container rather than static hosting

If detected, apply the steps below.

如果项目中出现以下任意一种情况，则将其视为“源自AI Studio”：

README中提及Google AI Studio / Gemini API / “Build”模式 / Cloud Run
存在cloudbuild.yaml、Dockerfile或Cloud Run部署说明
使用了
```
process.env.GEMINI_API_KEY
```
或被描述为“由AI Studio提供”的占位符
项目结构依赖服务器/容器运行，而非静态托管

如果检测到以上特征，请执行以下步骤。

Primary objective

核心目标

Make the project a conventional front-end that:

runs locally with
```
npm run dev
```
produces production files with
```
npm run build
```
into
```
dist/
```
can be hosted from a non-root subpath (Domo App Platform)
does NOT require any server runtime to render the UI

将项目改造为常规前端项目，满足：

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

Step 1 — Ensure a standard build pipeline exists

步骤1 — 确保标准构建流程存在

Open

package.json

and ensure scripts exist and are correct for the chosen toolchain:

If it is Vite:

```
dev
```
:
```
vite
```
```
build
```
:
```
vite build
```
```
preview
```
:
```
vite preview
```
Confirm output is
```
dist/
```

If it is CRA:
- ```
build
```
  outputs
```
build/
```
  by default (NOT acceptable for our contract)
- Either: A) migrate to Vite (preferred for App Platform), OR B) update Domo publish docs/commands accordingly (only if user explicitly wants CRA)

Default to Vite if uncertain.

Acceptance criteria:

```
npm install
```
succeeds
```
npm run build
```
creates
```
dist/
```
with
```
index.html
```
and
```
assets/*
```

打开

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/
```
目录

Step 2 — Fix base path so assets work in Domo (subpath hosting)

步骤2 — 修复基础路径以适配Domo的子路径托管

Domo App Platform does NOT host your app at

. It’s under a nested path. Therefore asset paths MUST be relative or explicitly configured.

If Vite: set base to relative
- in
```
vite.config.*
```
  :
```
base: './'
```
If other bundler: ensure the equivalent "public path" is relative.

Acceptance criteria:

Opening the built
```
dist/index.html
```
from a nested path still loads JS/CSS assets (no 404s).
No hardcoded absolute asset paths like
```
/assets/...
```
unless you know the host root.

Domo App Platform不会将你的应用托管在根路径

下，而是在嵌套子路径中。因此资源路径必须设置为相对路径或进行显式配置。

若使用Vite：将base设置为相对路径
- 在
```
vite.config.*
```
  中添加：
```
base: './'
```
若使用其他打包工具：确保对应的“公共路径”设置为相对路径。

验收标准：

从嵌套路径打开构建后的
```
dist/index.html
```
时，JS/CSS资源仍能正常加载（无404错误）。
除非已知主机根路径，否则请勿使用
```
/assets/...
```
这类硬编码的绝对资源路径。

Step 3 — Make routing robust for static hosting

步骤3 — 优化路由以适配静态托管

If the app uses React Router (or any client router):

Prefer HashRouter for App Platform unless you know the platform provides SPA rewrites.
If switching to HashRouter is too invasive, document that refresh on deep routes will 404 unless Domo is configured with a rewrite rule.

Default action:

If router is present and no rewrite control is known: switch to
```
HashRouter
```
.

Acceptance criteria:

Built app can navigate and refresh without server rewrites.

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

除非确知平台支持SPA重写规则，否则优先为App Platform使用HashRouter。
若切换到HashRouter的改动过大，请记录：除非Domo配置了重写规则，否则在深层路由刷新时会出现404错误。

默认操作：

若存在路由配置且不了解重写控制权限：切换为
```
HashRouter
```
。

验收标准：

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

Step 4 — Environment variables and secrets: remove AI Studio-only assumptions

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

AI Studio can "magically" provide placeholders (e.g., Gemini API key) during its hosted run. In Domo App Platform, the browser cannot safely hold secrets.

Rules:

Do NOT ship any raw API keys in client code.
If the UI needs Gemini/LLM calls:
- Prefer Domo AI APIs via domo.js if available/allowed, OR
- Proxy through a backend (e.g., Domo Code Engine) that injects secrets server-side.
Replace
```
process.env.*
```
patterns with toolchain-native env usage:
- Vite:
```
import.meta.env.VITE_*
```
Add
```
.env.example
```
documenting required variables (non-secret only).

Acceptance criteria:

No committed secrets.
No runtime crashes from missing AI Studio env injection.

AI Studio可以在其托管运行时“自动”提供占位符（例如Gemini API密钥）。但在Domo App Platform中，浏览器无法安全存储密钥。

规则：

请勿在客户端代码中嵌入任何原始API密钥。
如果UI需要调用Gemini/大语言模型接口：
- 若允许，优先通过domo.js使用Domo AI API，或
- 通过后端（如Domo Code Engine）进行代理，在服务器端注入密钥。
将
```
process.env.*
```
的使用方式替换为工具链原生的环境变量用法：
- Vite：
```
import.meta.env.VITE_*
```
添加
```
.env.example
```
文件，记录所需的非机密变量。

验收标准：

代码中无已提交的机密信息。
不会因缺少AI Studio的环境变量注入而导致运行时崩溃。

Step 5 — Domo deploy contract

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

Ensure the final developer workflow is:

```
npm run build
```
```
cd dist
```
```
domo publish
```

If a Domo manifest/config file is required by the App Platform project (e.g.,

manifest.json

), ensure it is located where Domo expects it OR copied into

dist/

during build.

If the platform expects the manifest in the root but publishes

dist/

, implement one of:

Copy required config/manifest into
```
dist/
```
as part of build (postbuild script)
Or adjust publish strategy if the user’s established standard differs

Default:

Add a
```
postbuild
```
script to copy required app platform files into
```
dist/
```
if they are missing there.

Acceptance criteria:

```
dist/
```
contains everything needed to publish and run.
```
domo publish
```
from inside
```
dist/
```
works without manual file copying.

在应用所有改动后，请提供：

一份简短的文件变更列表
本地运行的确切命令
一份“完成检查清单”，确认：
- 构建可生成
```
dist/
```
  目录
- 资源可在子路径下正常加载
- 路由功能正常（使用哈希路由或已记录重写需求）
- 客户端代码中无机密信息

请果断执行改动，除非因缺少文件而受阻，否则无需提出后续问题。

Output requirements (what you must deliver as the assistant)

—

After applying changes, provide:

A short list of files changed
The exact commands to run locally
A "done checklist" confirming:
- build produces
```
dist/
```
- assets load under subpath
- routing works (hash router or documented rewrite need)
- no secrets in client

Be decisive; implement changes rather than asking follow-up questions unless blocked by missing files.

—