# 🍌 Nano Banana AI 图像编辑器

发布版本: v1.0

### **⏬ 获取一键安装副本!** 
加入 [Vibe Coding is Life Skool 社区](https://www.skool.com/vibe-coding-is-life/about?ref=456537abaf37491cbcc6976f3c26af41) 获取此应用的 **一键 ⚡Bolt.new 安装克隆**，以及现场构建会话、独家项目下载、AI 提示、大师课程和网络上最好的氛围编码社区的访问权限！

---

**专业的 AI 图像生成和对话式编辑平台**

一个生产就绪的 React + TypeScript 应用程序，用于愉快的图像生成和使用 Google Gemini 2.5 Flash Image 模型进行对话式、区域感知的修改。采用现代网络技术构建，专为创作者和开发者设计。

## ✨ 主要功能

### 🎨 **AI 驱动的创作**
- **文本到图像生成** - 从描述性提示创建令人惊叹的图像
- **实时质量提示** - 实时反馈以改进您的提示
- **参考图像支持** - 使用最多 2 张参考图像指导生成
- **高级控制** - 微调创意水平并使用自定义种子

### ✏️ **智能编辑**
- **对话式编辑** - 使用自然语言指令修改图像
- **区域感知选择** - 绘制遮罩以针对特定区域进行编辑
- **样式参考图像** - 上传参考图像以指导编辑样式
- **非破坏性工作流** - 所有编辑都保留原始图像

### 🖼️ **专业画布**
- **交互式画布** - 平滑缩放、平移和导航大图像
- **画笔工具** - 可变画笔尺寸以实现精确的遮罩绘制
- **移动设备优化** - 响应式设计，在所有设备上都能完美运行
- **键盘快捷键** - 使用热键提高工作效率

### 📚 **项目管理**
- **生成历史** - 跟踪所有创作和编辑
- **变体比较** - 生成并并排比较多个版本
- **完整撤销/重做** - 具有分支历史的完整生成树
- **资产管理** - 有序存储所有生成的内容

### 🔒 **企业功能**
- **图像上传和分享** - 上传生成的图像以轻松分享
- **离线缓存** - IndexedDB 存储以实现离线资产访问
- **类型安全** - 完整的 TypeScript 实现和严格类型检查
- **性能优化** - React Query 实现高效状态管理

## 🚀 快速开始

### 先决条件
- Node.js 18+ 
- 一个 [Google AI Studio](https://aistudio.google.com/) API 密钥
- 可选：访问令牌用于图像上传功能

### 安装

1. **克隆并安装依赖**:
   ```bash
   git clone <repository-url>
   cd nano-banana-image-editor
   npm install
   ```

2. **配置环境**:
   ```bash
   cp .env.example .env
   # 将您的 Gemini API 密钥添加到 VITE_GEMINI_API_KEY
   # 可选：添加访问令牌到 VITE_ACCESS_TOKEN 以启用图像上传
   ```

3. **启动开发服务器**:
   ```bash
   npm run dev
   ```

4. **在浏览器中打开**: 导航到 `http://localhost:5173`

## 🎯 使用指南

### 创建图像
1. 选择 **生成** 模式
2. 编写详细提示描述您想要的图像
3. 可选上传参考图像（最多 2 张）
4. 如需要调整创意设置
5. 点击 **生成** 或按 `Cmd/Ctrl + Enter`

### 编辑图像
1. 切换到 **编辑** 模式
2. 上传图像或使用先前生成的图像
3. 可选绘制遮罩以针对特定区域
4. 用自然语言描述您想要的更改
5. 点击 **应用编辑** 查看结果

### 高级工作流
- 使用 **选择** 模式绘制精确遮罩以进行目标编辑
- 在历史面板中比较变体
- 下载高质量 PNG 输出
- 使用键盘快捷键进行高效导航

## ⌨️ 键盘快捷键

| 快捷键 | 操作 |
|----------|--------|
| `Cmd/Ctrl + Enter` | 生成/应用编辑 |
| `Enter` | 生成/应用编辑（在任何地方按下）|
| `Shift + R` | 重新生成变体 |
| `E` | 切换到编辑模式 |
| `G` | 切换到生成模式 |
| `M` | 切换到选择模式 |
| `H` | 切换历史面板 |
| `P` | 切换提示面板 |
| `Esc` | 中断生成 |

## 🏗️ 架构

### 技术栈
- **前端**: React 18, TypeScript, Tailwind CSS
- **状态管理**: Zustand 用于应用状态, React Query 用于服务器状态  
- **画布**: Konva.js 用于交互式图像显示和遮罩叠加
- **AI 集成**: Google Generative AI SDK (Gemini 2.5 Flash Image)
- **存储**: IndexedDB 用于离线资产缓存
- **构建工具**: Vite 用于快速开发和优化构建

### 项目结构
```
src/
├── components/          # React 组件
│   ├── ui/             # 可重用的 UI 组件 (Button, Input, 等)
│   ├── PromptComposer.tsx  # 提示输入和工具选择
│   ├── ImageCanvas.tsx     # 使用 Konva 的交互式画布
│   ├── HistoryPanel.tsx    # 生成历史和变体
│   ├── Header.tsx          # 应用头部和导航
│   └── InfoModal.tsx       # 关于模态框和链接
├── services/           # 外部服务集成
│   ├── geminiService.ts    # Gemini API 客户端
│   ├── uploadService.ts    # 图像上传服务
│   ├── cacheService.ts     # IndexedDB 缓存层
│   └── imageProcessing.ts  # 图像处理工具
├── store/              # Zustand 状态管理
│   └── useAppStore.ts      # 全局应用状态
├── hooks/              # 自定义 React 钩子
│   ├── useImageGeneration.ts  # 生成和编辑逻辑
│   └── useKeyboardShortcuts.ts # 键盘导航
├── utils/              # 工具函数
│   ├── cn.ts              # 类名工具
│   └── imageUtils.ts      # 图像处理助手
└── types/              # TypeScript 类型定义
    └── index.ts           # 核心类型定义
```

## 🔧 配置

### 环境变量
```bash
VITE_GEMINI_API_KEY=your_gemini_api_key_here
VITE_ACCESS_TOKEN=your_access_token_here  # 可选，用于图像上传
VITE_UPLOAD_ASSET_URL=your_asset_url      # 可选，用于图像上传的资产URL前缀
```

### 模型配置
- **模型**: `gemini-2.5-flash-image-preview`
- **输出格式**: 1024×1024 PNG
- **输入格式**: PNG, JPEG, WebP
- **温度范围**: 0-1 (0 = 确定性, 1 = 创意)

## 🚀 部署

### 开发
```bash
npm run dev      # 启动开发服务器
npm run build    # 构建生产版本
npm run preview  # 预览生产构建
npm run lint     # 运行 ESLint
npm run test     # 运行测试
```

### 生产考虑
- **API 安全**: 在生产环境中为 API 调用实现后端代理
- **速率限制**: 添加适当的速率限制和使用配额
- **身份验证**: 考虑为多用户部署添加用户身份验证
- **存储**: 设置云存储以存储生成的资产
- **监控**: 添加错误跟踪和分析

## 📄 许可证和版权

**版权所有 © 2025 [Mark Fulton](https://markfulton.com)**

该项目根据 **GNU Affero 通用公共许可证 v3.0** (AGPL-3.0) 授权。

### 这意味着：
- ✅ **免费使用** 于个人和商业项目
- ✅ **修改和分发** 需要适当署名
- ⚠️ **分享修改** - 任何更改必须在相同许可证下共享
- ⚠️ **网络使用** - 如果您将其作为网络服务运行，必须提供源代码

有关完整详情，请参见 [LICENSE](LICENSE) 文件。

## 🤝 贡献

我们欢迎贡献！请：

1. **遵循既定模式** - 保持组件在 200 行以内
2. **维护类型安全** - 严格使用 TypeScript 和正确定义
3. **彻底测试** - 确保键盘导航和可访问性
4. **记录更改** - 更新 README 并添加内联注释
5. **遵守许可证** - 所有贡献都将遵循 AGPL-3.0

## 🔗 链接和资源

- **创建者**: [Mark Fulton](https://markfulton.com)
- **AI 培训计划**: [Reinventing.AI](https://www.reinventing.ai/)
- **社区**: [Vibe Coding is Life Skool](https://www.skool.com/vibe-coding-is-life/about?ref=456537abaf37491cbcc6976f3c26af41)
- **Google AI Studio**: [获取您的 API 密钥](https://aistudio.google.com/)
- **Gemini API 文档**: [官方文档](https://ai.google.dev/gemini-api/docs)

## 🐛 已知问题和限制

- **客户端 API 调用** - 目前使用直接 API 调用（在生产环境中实现后端代理）
- **浏览器兼容性** - 需要支持 Canvas 和 WebGL 的现代浏览器
- **速率限制** - 受 Google AI Studio 速率限制约束
- **图像尺寸** - 针对 1024×1024 输出进行了优化（Gemini 模型输出尺寸可能有所不同）

## 🎯 建议更新

- [ ] 后端 API 代理实现
- [ ] 用户身份验证和项目共享
- [ ] 高级画笔工具和选择方法
- [ ] 自定义过滤器的插件系统
- [ ] 与云存储提供商集成

---

**由 [Mark Fulton](https://markfulton.com) 构建** | **由 Gemini 2.5 Flash Image 提供支持** | **使用 Bolt.new 制作**