画谱 (HuaPu)

一个基于 AI 的智能绘画教学 Web 应用，使用 Google Gemini 进行视觉理解和教学指导，Nano Banana Pro 进行图像生成。

✨ 功能特性

核心功能

• 🎨 智能目标生成 - 使用 Nano Banana Pro API 生成学习目标图像
• 🧠 Gemini VLM 分析 - 使用 Google Gemini 进行图像理解、评估和教学
• 📋 分步骤教学 - 将复杂绘画任务分解为可执行的步骤
• 🔍 实时反馈评估 - AI 分析用户作品，标注问题区域并给出改进建议
• 📊 综合能力评估 - 完成学习后生成雷达图评分和详细建议

UI 特性

• 💬 类 ChatGPT 的对话式交互界面
• 📁 左侧会话历史列表，支持管理多个学习会话
• 🖼️ 支持拖拽上传图片
• 🏷️ 可视化标注问题区域
• 📈 美观的雷达图展示学习成果

🔧 技术栈

• 框架: React 18 + TypeScript
• 构建工具: Vite 5
• 样式: Tailwind CSS
• 图表: Recharts
• AI 服务:
  • Google Gemini 2.0 Flash (VLM - 视觉语言模型)
  • Nano Banana Pro (图像生成)

🚀 快速开始

1. 获取 API 密钥

Google Gemini API

1. 访问 Google AI Studio
2. 登录 Google 账号
3. 创建 API 密钥

Nano Banana Pro API

1. 访问 Nano Banana Pro 官网
2. 注册开发者账号
3. 获取 API 密钥

2. 配置环境变量

在项目根目录创建 .env 文件：

# Google Gemini API Key
VITE_GEMINI_API_KEY=your_gemini_api_key_here

# Nano Banana Pro API
VITE_NANO_BANANA_API_KEY=your_nano_banana_api_key_here
VITE_NANO_BANANA_API_URL=https://api.defapi.org/api/image/gen

3. 安装依赖

npm install

4. 启动开发服务器

npm run dev

访问 http://localhost:3000 查看应用。

5. 构建生产版本

npm run build

📁 项目结构

src/
├── components/              # React 组件
│   ├── Sidebar.tsx          # 左侧会话列表
│   ├── ChatArea.tsx         # 主聊天区域
│   ├── ChatInput.tsx        # 输入框组件
│   ├── MessageBubble.tsx    # 消息气泡
│   ├── TeachingStatus.tsx   # 教学状态显示
│   ├── ImageWithAnnotations.tsx # 带标注的图片
│   ├── PlanDisplay.tsx      # 学习计划展示
│   └── RadarChart.tsx       # 雷达图评估
├── services/                # 服务层
│   ├── api.ts               # API 统一接口
│   ├── geminiService.ts     # Gemini VLM 服务
│   ├── nanoBananaService.ts # Nano Banana 图像生成服务
│   └── teachingService.ts   # 教学流程编排服务
├── types/                   # TypeScript 类型定义
│   └── index.ts
├── App.tsx                  # 主应用组件
├── main.tsx                 # 入口文件
└── index.css                # 全局样式

🔄 教学工作流

状态机流转

INIT → STEP_ACTIVE → STEP_REVIEW
         ↑               ↓
         |         ┌─────┴─────┐
         |         ↓           ↓
         └── STEP_DONE   STEP_FIX_REQUIRED
                  ↓               │
          (循环下一步) ←──────────┘
                  ↓
         FINAL_ASSESSMENT → COMPLETED

AI 调用流程

1. 首次输入 (INIT)

   • Gemini: 判断用户意图
   • Nano Banana: 生成目标图像（如需要）
   • Gemini: 生成学习计划
   • Gemini: 生成步骤指导
   • Nano Banana: 生成子目标图像

2. 用户提交作品 (STEP_ACTIVE)

   • Gemini: 比较用户作品与子目标
   • 通过 → 进入下一步或最终评估
   • 未通过 → 生成标注和修改建议

3. 文字问答

   • Gemini: 基于上下文回答问题

4. 最终评估 (FINAL_ASSESSMENT)

   • Gemini: 生成雷达图评分和综合建议

📝 API 接口说明

应用内部实现了完整的教学 API，包括：

• 会话管理（创建、列表、删除）
• 消息发送与处理
• 图片资产管理
• 教学状态机维护

详细 API 规范请参考 1.md 文档。

⚠️ 注意事项

1. API 费用: 使用 Gemini 和 Nano Banana Pro API 可能会产生费用，请查看各服务的定价。

2. 图片存储: 当前版本使用浏览器本地 URL 存储上传的图片，刷新后会失效。生产环境建议接入真实的存储服务。

3. 网络要求: 需要能够访问 Google API 和 Nano Banana API。

4. 浏览器兼容性: 推荐使用 Chrome、Firefox、Safari 最新版本。

🔒 安全建议

• 不要将 API 密钥提交到版本控制
• 生产环境建议通过后端代理调用 AI API
• 设置 API 使用限额防止意外费用

License

MIT