Skip to content

Commit ae24f37

Browse files
ShellMonsterShellMonster
committed
feat: v2.8.0 - migrate to gpt-image-2-all, add CLAUDE.md, update docs
- Migrate openai-image default model from gpt-image-1 to gpt-image-2-all - Remove unsupported quality parameter from openai-image provider - Bump version to 2.8.0 across all config files - Create CLAUDE.md with project context for AI assistants - Update all 4 language READMEs with v2.8.0 changes and 3-provider architecture - Fix Korean README duplicate config table entries - Refactor ImageCard component with thumbnail/full switching
1 parent 7bb4b04 commit ae24f37

15 files changed

Lines changed: 332 additions & 113 deletions

File tree

‎CLAUDE.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# CLAUDE.md — Banana Pro AI 项目指南
2+
3+
> 本文件为 AI 编码助手提供项目上下文，遵循 Anthropic CLAUDE.md 最佳实践。
4+
5+
## 项目概述
6+
7+
**大香蕉 AI (Banana Pro AI)** — 跨平台 AI 图片生成应用，支持 Gemini 和 OpenAI 标准接口。
8+
9+
- **版本**: v2.8.0
10+
- **协议**: MIT
11+
- **仓库**: ShellMonster/Nano_Banana_Pro_Web
12+
13+
三层架构：React 前端 → Tauri (Rust IPC 桥) → Go Sidecar 后端。桌面端通过 Tauri 打包，Web 端通过 Docker + Nginx 部署。
14+
15+
## 常用命令
16+
17+
```bash
18+
# 后端
19+
cd backend && go run cmd/server/main.go # 启动后端 (默认 :8080)
20+
make build # 编译
21+
make run # 运行
22+
23+
# 桌面端 (前端 + Tauri)
24+
cd desktop && npm install && npm run tauri dev
25+
26+
# Web 前端 (独立版，非 Tauri)
27+
cd frontend && npm install && npm run dev
28+
29+
# 打包发布
30+
cd desktop && npm run tauri build # 本地构建桌面安装包
31+
32+
# Docker 部署 (Web 版)
33+
docker compose -p banana-pro up -d
34+
35+
# 发布流程
36+
git tag v2.8.0 && git push origin v2.8.0 # 触发 GitHub Actions 自动构建
37+
```
38+
39+
## 项目结构
40+
41+
```
42+
backend/ # Go 后端 (Sidecar)
43+
├── cmd/server/main.go # 服务入口、路由注册、生命周期
44+
├── internal/
45+
│ ├── api/ # API Handlers (generate, folders, templates, export, history, config, images)
46+
│ ├── provider/ # AI 提供商适配器
47+
│ │ ├── gemini.go # Gemini /v1beta 接口
48+
│ │ ├── openai.go # OpenAI /v1/chat/completions (多模态)
49+
│ │ ├── openai_image.go # OpenAI /v1/images/generations (gpt-image-2-all)
50+
│ │ └── model_resolver.go # 模型名称解析
51+
│ ├── worker/pool.go # Worker 池 (6 workers, 100 queue, panic recovery)
52+
│ ├── model/ # 数据模型 (ProviderConfig, Task, Folder)
53+
│ ├── storage/storage.go # 存储层 (本地文件系统 + 可选阿里云 OSS)
54+
│ ├── config/config.go # Viper 配置管理
55+
│ ├── templates/store.go # 模板市场 (935+ 模板, 内嵌+远程+缓存)
56+
│ ├── promptopt/service.go # 提示词优化 (text/json 模式, singleflight, 10min cache)
57+
│ ├── diagnostic/ # 日志 & 错误分类 (20+ 类别)
58+
│ ├── folder/ # 文件夹管理 (自动月分组 + 手动文件夹)
59+
│ └── platform/runtime.go # 运行环境检测 (Tauri/Docker)
60+
61+
desktop/ # Tauri 桌面端
62+
├── src/
63+
│ ├── components/ # 37 React 组件
64+
│ ├── store/ # 8 个 Zustand Store (configStore migration v19)
65+
│ ├── hooks/ # 6 个自定义 Hook
66+
│ ├── services/ # 8 个 API 服务文件
67+
│ ├── i18n/locales/ # 4 种语言 (zh-CN, en-US, ja-JP, ko-KR)
68+
│ └── types/ # TypeScript 接口定义
69+
├── src-tauri/
70+
│ ├── Cargo.toml # Rust 依赖
71+
│ ├── tauri.conf.json # Tauri 配置 (窗口、权限、Updater)
72+
│ └── capabilities/ # Tauri 权限声明
73+
└── package.json
74+
75+
frontend/ # 独立 Web 前端 (v2.5.2, 非 Tauri)
76+
```
77+
78+
## 技术栈
79+
80+
| 层 | 技术 | 版本 |
81+
|---|---|---|
82+
| 前端 | React + TypeScript + Zustand | 18.3.1 |
83+
| 桌面容器 | Tauri (Rust) | 2.0 |
84+
| 后端 | Go + Gin | 1.21+ |
85+
| 数据库 | SQLite (via mattn/go-sqlite3) | - |
86+
| CI/CD | GitHub Actions | release.yml + pr-check.yml |
87+
| 部署 | Docker multi-stage (Alpine + Nginx) | - |
88+
89+
## AI 提供商架构
90+
91+
项目支持 3 种 AI 提供商，通过 `ProviderType` 区分：
92+
93+
| Provider | API Endpoint | 用途 |
94+
|---|---|---|
95+
| `gemini` | `/v1beta/models/{model}:generateContent` | 文生图/图生图，支持 4K |
96+
| `openai` | `/v1/chat/completions` (多模态) | 文生图/图生图/提示词优化 |
97+
| `openai-image` | `/v1/images/generations` | 专用图片生成 (gpt-image-2-all) |
98+
99+
- 提供商配置热更新：存储在 SQLite，修改后立即生效，无需重启
100+
- 默认模型：`gemini-2.0-flash-exp` (gemini), `gpt-4o` (openai), `gpt-image-2-all` (openai-image)
101+
102+
## 关键架构决策
103+
104+
1. **asset:// 协议**：桌面端注册原生资源协议，绕过 HTTP 栈加载本地图片，速度提升 300%
105+
2. **Sidecar 模式**：Go 后端作为 Tauri sidecar 运行，Tauri 退出时自动清理进程
106+
3. **Worker 池**：6 workers + 100-slot 队列，per-provider 超时，panic 自动恢复
107+
4. **IPC 优化**：前后端只传文件路径，二进制数据通过 asset:// 协议直读
108+
5. **Prompt 优化**：singleflight 去重 + 10min 缓存，支持 text/json 两种输出模式
109+
6. **模板市场**：内嵌 JSON + 远程 GitHub Raw + 本地缓存三层策略，24h 自动刷新
110+
111+
## 代码风格
112+
113+
### Go 后端
114+
- 标准 Go 项目布局 (`cmd/`, `internal/`)
115+
- Gin 框架，中间件链式调用
116+
- 错误处理：使用 `internal/diagnostic` 分类错误，返回结构化 JSON
117+
- 配置：Viper 读取 `config.yaml`，环境变量覆盖
118+
- 数据库：`database/sql` + `mattn/go-sqlite3`，不使用 ORM
119+
120+
### React 前端
121+
- 函数组件 + Hooks，无 Class 组件
122+
- Zustand 状态管理，`configStore` 管理 provider 配置和迁移
123+
- API 调用集中在 `services/` 目录
124+
- i18n 使用 `react-i18next`，翻译文件在 `i18n/locales/`
125+
- Tailwind CSS 样式
126+
127+
### 通用
128+
- 中文注释解释「为什么」而非「做什么」
129+
- 提交信息格式：`feat:`, `fix:`, `chore:`, `docs:`
130+
- 版本号统一在 `Cargo.toml`, `tauri.conf.json`, `package.json`, `Cargo.lock`, `package-lock.json`
131+
132+
## 注意事项 & 易错点
133+
134+
1. **端口冲突**：Go sidecar 监听 `127.0.0.1:8080`，确保无其他进程占用。调试时检查 `lsof -i :8080`
135+
2. **模型名称**：`openai-image` provider 默认模型是 `gpt-image-2-all`（v2.8.0 更新），不支持 `quality` 参数
136+
3. **版本同步**：发布前确保 5 个文件的版本号一致（见上方「通用」部分）
137+
4. **Tauri 权限**：新功能涉及文件系统/网络访问时需更新 `capabilities/default.json`
138+
5. **Docker vs Desktop**：后端通过 `platform/runtime.go` 检测运行环境，Docker 监听 `0.0.0.0`，Tauri 监听 `127.0.0.1`
139+
6. **configStore 迁移**：前端配置存储在 localStorage，版本迁移在 `configStore.ts` 的 `migrations` 中处理，当前版本 v19
140+
7. **图片存储路径**：桌面端默认 `~/Library/Application Support/com.banana.pro/` (macOS)，`%APPDATA%/com.banana.pro/` (Windows)
141+
142+
## 测试
143+
144+
项目当前无自动化测试套件。验证方式：
145+
- `cd desktop && npm run tauri dev` 启动桌面端手动测试
146+
- `cd backend && go run cmd/server/main.go` 启动后端，用 curl 测试 API
147+
- Docker: `docker compose up -d` 后访问 `http://localhost:8090`
148+
149+
## CI/CD
150+
151+
- **release.yml**: 推送 `v*` tag 触发，构建 macOS ARM/Universal + Windows x64，生成 latest.json + .sig 签名
152+
- **pr-check.yml**: PR 触发，运行后端 `go vet` + 前端 `npm run build` 检查
153+
- GitHub Secrets 需配置：`TAURI_SIGNING_PRIVATE_KEY`, `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`

‎README.md‎

Lines changed: 21 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,8 @@
2929
> - **🤖 提示词优化增强**：新增 **JSON 模式** 按钮，支持强制输出结构化 JSON 并自动格式化回填，提升 Prompt 质量。
3030
> - **🧵 模板市场**：下拉打开整版模板市场，支持筛选、预览、来源与技巧提示，一键复用。
3131
> - **🚀 大规模列表性能优化**：历史记录与模板市场改为虚拟列表/虚拟网格，图片加载更顺滑。
32+
> - **🤖 OpenAI 专用图片生成**：新增 `openai-image` 提供商类型，支持 `/v1/images/generations` 标准接口（gpt-image-2-all 模型）。
33+
> - **🎨 图片卡片重构**：缩略图/全图智能切换，拖拽优化，加载体验提升。
3234
3335
> 💡 **推荐使用**：为了获得最佳的生成体验与极高的性价比，推荐搭配 [云雾API](https://yunwu.ai/register?aff=i4hh) 使用。
3436
>
@@ -44,7 +46,7 @@
4446

4547
- **🚀 极致性能**：采用 **Tauri 2.0** 架构，配合 **Go 语言** 编写的高并发 Sidecar 后端，资源占用极低。
4648
- **🖼️ 4K 超清创作**：深度优化 Gemini 3.0 模型，支持多种画幅的 4K 超清图像生成。
47-
- **🔌 标准接口兼容**：支持 Gemini(/v1beta) 与 OpenAI(/v1) 标准格式对接，Base URL 与模型可配置。
49+
- **🔌 标准接口兼容**：支持 Gemini(/v1beta)、OpenAI(/v1 多模态) 与 OpenAI Image(/v1/images/generations) 三种提供商类型，Base URL 与模型可配置。
4850
- **⚡ 自定义协议 (asset://)**：在桌面端注册原生资源协议，绕过 HTTP 协议栈，本地图片加载速度提升 300%。
4951
- **💾 智能历史管理**：内置本地数据库与持久化缓存，支持任务状态自动恢复与大批量历史记录秒开。
5052
- **📸 精准图生图**：支持多参考图输入，提供细腻的风格与构图控制。
@@ -74,7 +76,7 @@
7476
- **多样化画幅选择**：预设 1:1, 16:9, 9:16, 4:3, 2:3 等多种主流比例。
7577
- **画质自定义**：支持从 1K 到 4K 的超清分辨率配置。
7678
- **智能尺寸适配**：系统会自动根据模型特性，将图片尺寸对齐到最佳像素点（8的倍数），确保生成效果最优化。
77-
- **对接方式切换**：设置中可选 `Gemini(/v1beta)` 或 `OpenAI(/v1)`，并分别配置 Base URL / API Key / 模型 ID。
79+
- **对接方式切换**：设置中可选 `Gemini(/v1beta)`、`OpenAI(/v1 多模态)` 或 `OpenAI Image(/v1/images/generations)`，并分别配置 Base URL / API Key / 模型 ID。
7880

7981
### 4. 极致的交互与管理
8082
- **大图沉浸式预览**：支持全屏查看图片，提供自由缩放与拖拽功能。
@@ -90,7 +92,7 @@
9092
- **稳定连接保障**：自动切换 WebSocket 与 HTTP 轮询模式，确保在复杂网络环境下生成任务不中断。
9193

9294
### 6. 模板市场 (Template Market)
93-
- **海量资源**：目前已收录 **900+** 优质模板，涵盖多种风格与行业。
95+
- **海量资源**：目前已收录 **935+** 优质模板，涵盖多种风格与行业。
9496
- **下拉打开**：顶部“拉绳”交互，向下拉出整版模板市场。
9597
- **多维筛选**：支持搜索、渠道/物料/行业/画幅比例筛选。
9698
- **PPT 类目**：标记为 `PPT` 的 16:9 模板会集中展示，便于制作演示稿素材。
@@ -203,7 +205,9 @@ graph TD
203205
subgraph "推理后端层 (Go Sidecar)"
204206
GoServer[Gin API 服务]
205207
WorkerPool[并发任务池]
206-
GeminiSDK[Google GenAI SDK]
208+
GeminiProvider[Gemini Provider]
209+
OpenAIProvider[OpenAI Provider]
210+
OpenAIImageProvider[OpenAI Image Provider]
207211
SQLite[(SQLite 任务存储)]
208212
end
209213
@@ -212,9 +216,13 @@ graph TD
212216
IPC <--> TauriBridge
213217
TauriBridge <--> GoServer
214218
GoServer <--> WorkerPool
215-
WorkerPool <--> GeminiSDK
219+
WorkerPool <--> GeminiProvider
220+
WorkerPool <--> OpenAIProvider
221+
WorkerPool <--> OpenAIImageProvider
216222
WorkerPool <--> SQLite
217-
GeminiSDK <--> |Imagen 3.0| Cloud[Google AI Cloud]
223+
GeminiProvider <--> |/v1beta| GeminiCloud[Google AI Cloud]
224+
OpenAIProvider <--> |/v1/chat/completions| OAICloud[OpenAI 兼容服务]
225+
OpenAIImageProvider <--> |/v1/images/generations| OAIImageCloud[OpenAI Image 服务]
218226
GoServer -.-> |保存图像| FS
219227
FS -.-> |映射资源| AssetProtocol
220228
AssetProtocol -.-> |极速显示| UI
@@ -224,7 +232,7 @@ graph TD
224232

225233
1. **前端 (React + Zustand)**：负责响应式 UI 与状态管理，提供流畅的用户交互。
226234
2. **桌面容器 (Tauri)**：作为 Rust 桥梁，处理窗口控制、本地资源访问及 Sidecar 进程管理。
227-
3. **推理引擎 (Go Sidecar)**：负责与 Google GenAI SDK 通讯，处理 Worker 任务池与本地图片存储。
235+
3. **推理引擎 (Go Sidecar)**：负责与 Gemini、OpenAI 及 OpenAI Image 三种 AI 提供商通讯，处理 Worker 任务池与本地图片存储。
228236

229237
### 核心优化点
230238
- **IPC 负荷优化**：前端与后端之间仅传递文件路径，大型二进制数据通过 `asset://` 协议直接由前端读取。
@@ -292,13 +300,13 @@ npm run dev
292300
```
293301

294302
### 5. 自动化构建 (GitHub Actions)
295-
只需推送带有版本号的标签（如 `v1.3.0`），即可触发自动化构建：
303+
只需推送带有版本号的标签（如 `v2.8.0`），即可触发自动化构建：
296304
```bash
297-
git tag v1.3.0
298-
git push origin v1.3.0
305+
git tag v2.8.0
306+
git push origin v2.8.0
299307
```
300308

301-
> **注意**：v1.3.0 之后支持通过推送 Tag 自动生成 Release 并上传多平台二进制文件。
309+
> **注意**：v2.8.0 支持通过推送 Tag 自动生成 Release 并上传多平台二进制文件。
302310
303311
### 6. 自动更新 (Updater)
304312
项目已集成 Tauri 官方 Updater 插件，发布新版本后用户启动应用会收到更新提示，可一键下载安装。
@@ -342,7 +350,7 @@ cat ~/.tauri/banana-updater.key
342350

343351
| 配置项 | 描述 |
344352
| :--- | :--- |
345-
| `AI对接方式` | `Gemini(/v1beta)` 或 `OpenAI(/v1)`；不同模式使用不同的 Base URL 与模型。 |
353+
| `AI对接方式` | `Gemini(/v1beta)`、`OpenAI(/v1 多模态)` 或 `OpenAI Image(/v1/images/generations)`；不同模式使用不同的 Base URL 与模型。 |
346354
| `API Base / API Key` | 兼容标准 OpenAI 格式接口，可替换成任意兼容平台。 |
347355
| `生图模型` | 用于生成图片的主模型。 |
348356
| `识图模型` | 用于逆向提示词功能，分析图片并生成提示词。默认继承生图配置的 Base URL 和 API Key。 |
@@ -351,9 +359,7 @@ cat ~/.tauri/banana-updater.key
351359
| `Templates Remote URL` | 远程模板 JSON 地址（默认 GitHub Raw），启动时会拉取并缓存。 |
352360
| `asset://` | 自定义资源协议，用于安全、快速地访问本地生成的图片。 |
353361

354-
> **提示**：OpenAI 类型接口通常要求生图模型（model_id）必填；Gemini 类型需使用 `/v1beta` 路径。
355-
>
356-
> **注意**：OpenAI 对接方式当前仅支持 1K 图片生成（具体取决于所用兼容接口）。
362+
> **提示**：OpenAI 类型接口通常要求生图模型（model_id）必填；Gemini 类型需使用 `/v1beta` 路径。`OpenAI Image` 类型默认使用 `gpt-image-2-all` 模型，不支持 `quality` 参数。
357363
358364
---
359365

‎README_EN.md‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@
2323
</p>
2424

2525
> 💡 **Recent Highlights**:
26+
> - **🤖 Dedicated OpenAI Image Generation**: New `openai-image` provider type supporting `/v1/images/generations` standard API (gpt-image-2-all model).
27+
> - **🎨 Image Card Refactor**: Smart thumbnail/full-size switching, improved drag-and-drop, better loading experience.
2628
> - **🎓 Onboarding Tour**: Interactive guide shown on first launch to help new users get started. Can be replayed anytime from settings.
2729
> - **🔍 Independent Vision Model Config**: New "Vision Model" settings tab for reverse prompt feature, inherits image model config by default.
2830
> - **✨ Reverse Prompt Extraction**: Click "Extract Prompt" on reference images to let AI analyze and generate reusable prompts.
@@ -47,7 +49,7 @@
4749

4850
- **🚀 Extreme Performance**: Built with **Tauri 2.0** architecture and a high-concurrency Sidecar backend written in **Go**, ensuring extremely low resource usage.
4951
- **🖼️ 4K Ultra-HD Creation**: Deeply optimized Gemini 3.0 model, supporting 4K UHD generation across multiple aspect ratios.
50-
- **🔌 Standard API Compatibility**: Supports Gemini (/v1beta) and OpenAI (/v1) standard formats with configurable Base URL and Model ID.
52+
- **🔌 Standard API Compatibility**: Supports three provider types: `gemini` (/v1beta), `openai` (/v1/chat/completions multimodal), and `openai-image` (/v1/images/generations) with configurable Base URL and Model ID.
5153
- **⚡ Custom Protocol (asset://)**: Registered native resource protocol for desktop, bypassing the HTTP stack to increase local image loading speed by 300%.
5254
- **💾 Smart History Management**: Built-in local database and persistent caching, supporting task recovery and instant opening of large history records.
5355
- **📸 Precise Image-to-Image**: Supports multiple reference images with fine-grained style and composition control.
@@ -77,7 +79,7 @@
7779
- **Aspect Ratios**: Preset ratios including 1:1, 16:9, 9:16, 4:3, 2:3.
7880
- **Quality Settings**: Customizable resolution from 1K to 4K.
7981
- **Smart Sizing**: Automatically aligns image dimensions to 8-pixel boundaries for optimal model performance.
80-
- **Interface Switching**: Toggle between `Gemini(/v1beta)` and `OpenAI(/v1)` modes in settings.
82+
- **Interface Switching**: Toggle between `Gemini(/v1beta)`, `OpenAI(/v1)` multimodal, and `OpenAI Image(/v1/images/generations)` modes in settings.
8183

8284
### 4. Advanced UX & Management
8385
- **Immersive Preview**: Full-screen view with free zooming and dragging.
@@ -185,6 +187,8 @@ graph TD
185187
GoServer[Gin API Server]
186188
WorkerPool[Worker Pool]
187189
GeminiSDK[Google GenAI SDK]
190+
OpenAIProvider[OpenAI Provider]
191+
OpenAIImageProvider[OpenAI Image Provider]
188192
SQLite[(SQLite Storage)]
189193
end
190194
@@ -194,8 +198,12 @@ graph TD
194198
TauriBridge <--> GoServer
195199
GoServer <--> WorkerPool
196200
WorkerPool <--> GeminiSDK
201+
WorkerPool <--> OpenAIProvider
202+
WorkerPool <--> OpenAIImageProvider
197203
WorkerPool <--> SQLite
198204
GeminiSDK <--> |Imagen 3.0| Cloud[Google AI Cloud]
205+
OpenAIProvider <--> |/v1/chat/completions| OpenAI[OpenAI Compatible API]
206+
OpenAIImageProvider <--> |/v1/images/generations| OpenAIImg[OpenAI Image API]
199207
GoServer -.-> |Save Images| FS
200208
FS -.-> |Map Resource| AssetProtocol
201209
AssetProtocol -.-> |Fast Display| UI
@@ -204,7 +212,7 @@ graph TD
204212
The project uses a "three-layer architecture" to balance performance and scalability:
205213
1. **Frontend (React + Zustand)**: Handles responsive UI and state management.
206214
2. **Desktop Container (Tauri)**: Acts as a Rust bridge for window control and local resource access.
207-
3. **Inference Engine (Go Sidecar)**: Communicates with Google GenAI SDK and manages task pools.
215+
3. **Inference Engine (Go Sidecar)**: Communicates with AI providers (Gemini, OpenAI, OpenAI-Image) and manages task pools.
208216

209217
### Core Optimizations
210218
- **IPC Load Optimization**: Only file paths are passed between frontend and backend; large binary data is read directly via the `asset://` protocol.
@@ -269,8 +277,8 @@ npm run dev
269277
### 5. Automated Build (GitHub Actions)
270278
Push a version tag to trigger CI:
271279
```bash
272-
git tag v1.3.0
273-
git push origin v1.3.0
280+
git tag v2.8.0
281+
git push origin v2.8.0
274282
```
275283

276284
### 6. Auto Updater
@@ -285,9 +293,9 @@ Integrated Tauri Updater for one-click updates.
285293

286294
| Item | Description |
287295
| :--- | :--- |
288-
| `AI Mode` | `Gemini(/v1beta)` or `OpenAI(/v1)`. |
296+
| `AI Provider` | `gemini` (/v1beta), `openai` (/v1/chat/completions), or `openai-image` (/v1/images/generations). Each uses its own Base URL and model. |
289297
| `API Base / Key` | Standard OpenAI format compatibility. |
290-
| `Image Model` | Primary model for image generation. |
298+
| `Image Model` | Primary model for image generation (e.g., gemini-2.0-flash-exp, gpt-4o, gpt-image-2-all). |
291299
| `Vision Model` | Model for reverse prompt extraction. Inherits Image Model's Base URL and API Key by default. |
292300
| `Chat Model` | Model for prompt optimization. |
293301
| `Storage Dir` | Default to system `AppData` (Win) or `Application Support` (Mac). |

0 commit comments

Comments
 (0)