ai-studio-project-converter

AI Studio Project Conversion Specification

Convert a zero-configuration React app generated by Google AI Studio into a page component of this project, preserving visual effects and functionality, and complying with this project's development standards.

Core Objectives

• Maintain page visual consistency
• Remove AI Studio-specific entry points and HTML templates
• Produce a page component that can run in this project

Usage

Step 1: Run the preprocessing script

node scripts/ai-studio-converter.mjs <ai-studio-project-dir> [output-name]

Example

node scripts/ai-studio-converter.mjs "temp/my-ai-studio-project" my-page

**脚本会自动完成**：
- 完整复制 AI Studio 项目到 `src/prototypes/[页面名]/`
- 分析项目结构（Import Map、自定义样式、依赖等）
- 生成 AI 工作文档（`.ai-studio-tasks.md`）
- 生成详细数据（`.ai-studio-analysis.json`）
- **不修改任何代码**（100% 安全）

### 步骤 2：按任务清单完成转换

脚本会生成 `.ai-studio-tasks.md` 文件，包含：
- 项目概况统计
- 5 个具体任务清单
- Import Map 依赖映射
- 环境变量配置提示
- 验收测试步骤

按任务清单与本规范示例执行转换。

## 转换要点

### AI Studio 项目特征

**典型目录结构**：

ai-studio-project/ ├── assets/ # Static assets (optional) ├── components/ # UI components ├── App.tsx # Main app component ├── index.tsx # React mount entry ├── index.html # HTML template (Import Map + Tailwind CDN) ├── constants.ts # Constant definitions (optional) ├── types.ts # Type definitions (optional) ├── vite.config.ts # Vite configuration (optional) └── metadata.json # Project metadata (optional)

**技术栈**：
- **框架**：React 19（Function Components + Hooks）
- **语言**：TypeScript
- **模块**：Native ESM（Import Map，通常是 esm.sh CDN）
- **样式**：Tailwind CSS（CDN Runtime Mode）
- **图标**：Lucide React
- **配置**：Vite（如果有 vite.config.ts）

### 关键文件特征

**index.html**：
```html
<script src="https://cdn.tailwindcss.com"></script>
<script type="importmap">
{
  "imports": {
    "react": "https://esm.sh/react@19",
    "lucide-react": "https://esm.sh/lucide-react"
  }
}
</script>
<style>/* 可能包含自定义样式 */</style>
<link href="https://fonts.googleapis.com/...">  <!-- 可能包含外部字体 -->

This Project's Page Component Specification

By default, first convert to a plain React page component. Only when the requirements explicitly call for integrating Axhub / Axure runtime capabilities should you introduce forwardRef<AxureHandle, AxureProps>、useImperativeHandle and axure-types。

Default format (recommended)：

/**
 * @name 页面名称
 * 
 * 参考资料：
 * - /rules/development-guide.md
 * - /skills/default-resource-recommendations/SKILL.md
 */

import './style.css';
import React from 'react';

export default function PageName() {
  // 组件逻辑
  
  return (
    // JSX 内容
  );
}

Only integrate the Axure API in the following scenarios：

• The page needs to be taken over by Axhub / Axure
• A configuration panel, external data source, event callback, or action trigger is needed
• The user explicitly requests keeping the interface form consistent with existing Axure components

In this case, refer to /rules/axure-api-guide.md, using the following wrapper form:

import React, { forwardRef, useImperativeHandle } from 'react';
import type { AxureProps, AxureHandle } from '../../common/axure-types';

const Component = forwardRef<AxureHandle, AxureProps>(function PageName(innerProps, ref) {
  useImperativeHandle(ref, function () {
    return {
      getVar: function () { return undefined; },
      fireAction: function () {},
      eventList: [],
      actionList: [],
      varList: [],
      configList: [],
      dataList: []
    };
  }, []);

  return (
    // JSX 内容
  );
});

export default Component;

Convert the main app component

AI Studio original code：

// App.tsx
import { useState } from 'react';
import Header from './components/Header';

export default function App() {
  const [count, setCount] = useState(0);
  return <div><Header /></div>;
}

Convert to this project's default specification：

/**
 * @name 页面名称
 * 
 * 参考资料：
 * - /rules/development-guide.md
 * - /skills/default-resource-recommendations/SKILL.md
 */

import './style.css';
import React, { useState } from 'react';
import Header from './components/Header';

export default function PageName() {
  const [count, setCount] = useState(0);

  return <div><Header /></div>;
}

Key conversion points：

1. Add a file header comment (@name and reference materials)
2. By default, keep the plain React component style, prioritizing minimal changes
3. Only when Axhub / Axure takeover is explicitly needed should you add forwardRef<AxureHandle, AxureProps> and useImperativeHandle
4. Keep the original JSX, Hooks, and Tailwind class names unchanged
5. If the Axure API is added, refer to /rules/axure-api-guide.md

Handle styles

From index.html extract style information, create style.css：

@import "tailwindcss";

/* 提取 <style> 标签中的自定义样式 */
/* 例如：自定义动画、字体、选择器样式等 */

/* 如果有外部字体，添加 @import */
@import url('https://fonts.googleapis.com/css2?family=...');

Dependency management

From index.html extract dependencies from the Import Map:

# 常见依赖：lucide-react, framer-motion 等
# 排除：react, react-dom（本项目已有）
pnpm add [识别到的依赖列表]

CDN to npm package mapping：

• https://esm.sh/lucide-react → lucide-react
• https://esm.sh/framer-motion → framer-motion
• https://esm.sh/@google/genai → @google/generative-ai

Environment variable handling

Convert process.env.* to import.meta.env.VITE_*：

• Check vite.config.ts in define configuration
• Inform the user of the environment variables that need to be configured
• Provide .env.local example

Remove AI Studio-specific files

Must remove：

• index.html(delete after extracting information)
• index.tsx(this project has its own entry point)
• metadata.json(optionally keep as reference)

Acceptance criteria

After conversion is complete, run the acceptance script:

node scripts/check-app-ready.mjs /prototypes/[页面名]

Acceptance requirements：

• Status is READY
• The page renders normally
• No console errors
• Interactive functionality works normally
• Styles display correctly

Common Issues

Missing Dependencies

# 根据报告中的依赖列表安装
pnpm add [依赖名称]

Import Map Conversion

• Check .ai-studio-analysis.json CDN dependency mappings in
• Ensure all CDN dependencies have been converted to npm packages

Style Issues

• Confirm that style.css contains @import "tailwindcss"
• Check whether the <style> tag in index.html has been extracted

Environment Variables

• Change process.env.* to import.meta.env.VITE_*
• Configure the .env.local file

Reference Resources

• Development Standards：/rules/development-guide.md
• Debugging Guide：/rules/debugging-guide.md
• Tailwind CSS：/skills/default-resource-recommendations/SKILL.md

Detailed Conversion Process (for reference)

Step 1: Analyze the Project Structure

The script will automatically scan and identify:

• Main application:App.tsx
• Entry file:index.tsx(needs to be removed)
• HTML template:index.html(extract dependency and style information)
• Component files:components/**/*.tsx
• Configuration file:vite.config.ts(extract path aliases)
• Constants/types:constants.ts, types.ts(if present)
• Static assets:assets/**

Step 2: Debug and Validate

Run the validation script and fix issues based on the results.