文档: 重构并扩展README.md，补充详细的功能介绍、技术实现和使用指南

2025-08-29 14:34:06 +08:00
parent 23b470334d
commit 15b0535d81
1 changed files with 191 additions and 136 deletions
--- a/README.md
+++ b/README.md
@@ -1,185 +1,240 @@
-# OpenRouter Image Generator Web应用
+# OpenRouter Image Generator

-这是一个基于OpenRouter API的图像生成Web应用，实现了与原始Python代码相同的功能，但提供了用户友好的Web界面。
+基于OpenRouter API的智能图像生成Web应用，提供完整的图像生成、管理和批量处理功能。

-## 功能特性
+## ✨ 核心功能

-### 核心功能
- 🎨 **图像生成**: 通过OpenRouter API生成高质量图像
- 📤 **图像上传**: 支持拖拽上传参考图像
- 💬 **对话界面**: 直观的聊天式交互界面
- 🖼️ **图像画廊**: 展示和管理生成的图像
- ⚙️ **API配置**: 灵活的API设置和连接测试
+### 🎨 图像生成
+- **单张生成**: 快速生成单个图像
+- **批量生成**: 一次性生成1-20张图像（可配置数量）
+- **参考图像**: 支持上传参考图像进行图像到图像的生成
+- **重试机制**: 内置API请求重试机制，提高成功率

-### 技术特性
- 🌐 **响应式设计**: 适配各种设备屏幕
- 🎯 **实时预览**: 即时显示上传的图像
- 💾 **本地存储**: 自动保存用户设置
- 🔗 **连接状态**: 实时显示API连接状态
- 📱 **移动友好**: 支持触摸操作
+### 🖼️ 图像管理
+- **图像画廊**: 网格布局展示所有生成的图像
+- **全屏查看**: 点击图像进入全屏查看模式
+- **图像导航**: 在查看器中左右翻页浏览图像
+- **批量下载**: 一键下载所有生成的图像
+- **单独下载**: 下载指定图像文件
+- **图像删除**: 删除不需要的图像
+- **URL复制**: 复制图像链接到剪贴板

-## 快速开始
+### 💬 对话功能
+- **聊天历史**: 完整的对话记录管理
+- **消息复制**: 复制用户或AI的消息内容
+- **消息编辑**: 编辑已发送的消息内容
+- **折叠界面**: 手风琴式UI，节省空间

-### 1. 获取OpenRouter API密钥
+### ⚙️ 配置管理
+- **API设置**: 完整的OpenRouter API配置
+- **连接测试**: 实时测试API连接状态
+- **本地存储**: 使用IndexedDB持久化保存数据
+- **存储清理**: 一键清除所有本地数据

+## 🚀 快速开始
+
+### 1. 获取API密钥
 1. 访问 [OpenRouter官网](https://openrouter.ai/)
-2. 注册账户并登录
-3. 在控制台中生成API密钥
+2. 注册并创建API密钥

 ### 2. 配置应用
+1. 打开应用，展开"API设置"面板
+2. 输入您的API Key
+3. 点击"测试连接"验证配置

-1. 打开 `index.html` 文件
-2. 在"API设置"面板中输入您的API密钥
-3. 点击"测试连接"按钮验证配置
+### 3. 开始使用
+- **单张生成**: 输入描述，点击"生成一张"
+- **批量生成**: 设置生成数量，点击"批量生成"
+- **参考图像**: 拖拽或选择图像上传

-### 3. 使用应用
+## 📋 支持的AI模型

-#### 上传参考图像（可选）
- 拖拽图像文件到上传区域
- 或点击"选择图像"按钮
- 支持多种图像格式（JPG、PNG、GIF等）
+| 模型 | 描述 | 费用 |
+|------|------|------|
+| `google/gemini-2.5-flash-image-preview:free` | Google Gemini 2.5 Flash 图像预览版 | 免费 |
+| `openai/gpt-4-vision-preview` | OpenAI GPT-4 视觉预览版 | 付费 |
+| `anthropic/claude-3-sonnet-20240229` | Anthropic Claude 3 Sonnet | 付费 |

-#### 生成图像
-1. 在对话输入框中输入您的图像生成请求
-2. 点击"发送"按钮或按Enter键
-3. 等待API处理并生成结果
+## ⚡ 主要特性

-#### 管理生成的图像
- 在图像画廊中查看所有生成的图像
- 悬停在图像上显示操作按钮
- 下载图像或复制图像URL
+### 技术特性
+- **响应式设计**: 适配桌面和移动设备
+- **拖拽上传**: 直观的文件拖拽界面
+- **实时预览**: 即时显示上传的图像
+- **加载指示**: 清晰的加载状态显示
+- **错误处理**: 完善的错误捕获和用户提示
+- **存储管理**: 智能的本地存储空间管理

-## 配置选项
+### UI/UX特性
+- **手风琴界面**: 可折叠的设置和历史面板
+- **全屏查看器**: 沉浸式图像查看体验
+- **批量操作**: 支持批量生成和批量下载
+- **状态指示器**: 实时显示连接和操作状态
+- **快捷操作**: 键盘快捷键支持（Enter发送）

-### API设置
- **API Key**: 您的OpenRouter API密钥
- **Base URL**: OpenRouter API的基础URL（默认：https://openrouter.ai/api/v1）
- **模型**: 选择使用的AI模型
-  - Google Gemini 2.5 Flash Image Preview (Free)
-  - OpenAI GPT-4 Vision Preview
-  - Anthropic Claude 3 Sonnet
- **超时时间**: 请求超时时间（秒）
- **代理**: 可选的代理服务器设置
-
-### 支持的模型
- `google/gemini-2.5-flash-image-preview:free` - 免费的Google Gemini模型
- `openai/gpt-4-vision-preview` - OpenAI的GPT-4视觉预览版
- `anthropic/claude-3-sonnet-20240229` - Anthropic的Claude 3 Sonnet模型
-
-## 使用示例
-
-### 基本图像生成
-```
-请生成一张美丽的日落风景图像
-```
-
-### 基于参考图像的生成
-1. 上传一张参考图像
-2. 输入提示：`请根据上传的图像风格，生成一张类似的现代建筑图像`
-
-### 复杂场景生成
-```
-请生成一张未来城市的图像，包含飞行汽车、玻璃建筑和绿色植物，风格要写实且具有科技感
-```
-
-## 技术实现
+## 🛠️ 技术实现

 ### 前端技术栈
- **HTML5**: 语义化标记和现代Web API
- **CSS3**: 响应式设计和动画效果
- **JavaScript**: 原生JS实现所有交互功能
- **Bootstrap 5**: UI组件和响应式布局
+- **HTML5**: 语义化标记
+- **CSS3**: 响应式设计和动画
+- **JavaScript (ES6+)**: 原生JS实现
+- **Bootstrap 5**: UI框架
 - **Font Awesome**: 图标库

+### 数据存储
+- **IndexedDB**: 主要数据持久化存储
+- **LocalStorage**: 配置数据备份
+- **内存管理**: 自动清理过期数据
+
 ### 核心功能实现

-#### API调用
+#### API调用与重试
 ```javascript
-async function generateImage(message) {
-    const payload = {
-        model: model,
-        messages: messages,
-        stream: false
-    };
-    
-    const response = await fetch(`${baseUrl}/chat/completions`, {
-        method: 'POST',
-        headers: {
-            'Authorization': `Bearer ${apiKey}`,
-            'Content-Type': 'application/json'
-        },
-        body: JSON.stringify(payload)
-    });
-    
-    return await response.json();
+async generateImageWithRetry(message, images, settings, imageIndex, totalImages) {
+    const maxRetries = 3;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            return await this.generateImage(message, images, settings);
+        } catch (error) {
+            if (attempt === maxRetries) throw error;
+            await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
+        }
+    }
 }
 ```

-#### 图像处理
- 支持Base64编码的图像数据
- 文件拖拽上传功能
- 图像预览和管理
- 图像下载和URL复制
+#### 批量生成管理
+```javascript
+async sendBatchMessage() {
+    const batchCount = parseInt(document.getElementById('batchCount').value) || 6;
+    const promises = [];
+    
+    for (let i = 0; i < batchCount; i++) {
+        promises.push(this.generateImageWithRetry(message, images, settings, i, batchCount));
+    }
+    
+    await Promise.allSettled(promises);
+}
+```

-#### 状态管理
- 本地存储用户设置
- 实时连接状态显示
- 加载状态指示器
- 错误处理和用户反馈
+## 🎯 使用示例

-## 浏览器兼容性
+### 基本图像生成
+```
+生成一张美丽的日落海滩风景图
+```

- ✅ Chrome 80+
- ✅ Firefox 75+
- ✅ Safari 13+
- ✅ Edge 80+
+### 基于参考图像
+1. 上传参考图像
+2. 输入: `基于上传的图像风格，生成一座现代建筑`

-## 注意事项
+### 批量生成
+1. 设置生成数量为10
+2. 输入: `科幻城市建筑，未来主义风格`
+3. 点击"批量生成"

-1. **API限制**: 请注意OpenRouter API的使用限制和费用
-2. **图像大小**: 上传的图像文件大小建议不超过10MB
-3. **网络要求**: 需要稳定的网络连接以访问OpenRouter API
-4. **隐私安全**: API密钥存储在浏览器本地，请勿在公共设备上使用
+### 复杂场景描述
+```
+生成一张赛博朋克风格的未来城市夜景，包含霓虹灯、飞行汽车和摩天大楼，色调以蓝紫色为主，具有强烈的科技感和未来感
+```

-## 故障排除
+## 📱 浏览器支持
+
+| 浏览器 | 版本要求 | 支持状态 |
+|--------|----------|----------|
+| Chrome | 80+ | ✅ 完全支持 |
+| Firefox | 75+ | ✅ 完全支持 |
+| Safari | 13+ | ✅ 完全支持 |
+| Edge | 80+ | ✅ 完全支持 |
+
+## 📐 配置选项
+
+### API设置
+- **API Key**: OpenRouter API密钥
+- **Base URL**: API端点 (默认: `https://openrouter.ai/api/v1`)
+- **模型选择**: 支持的AI模型列表
+- **超时时间**: 请求超时限制 (默认: 600秒)
+- **代理设置**: 可选的代理服务器配置
+
+### 生成设置
+- **生成数量**: 1-20张图像 (批量生成)
+- **图像格式**: 支持 JPG, PNG, GIF, WebP
+- **文件大小限制**: 最大10MB
+
+## 🔧 故障排除

 ### 常见问题

-**Q: 连接测试失败**
- 检查API密钥是否正确
- 确认网络连接正常
- 验证Base URL设置
+**连接测试失败**
+- 检查API密钥是否正确输入
+- 确认网络连接稳定
+- 验证Base URL设置正确

-**Q: 图像生成失败**
- 检查输入的提示词是否合适
- 确认选择的模型支持图像生成
- 查看浏览器控制台错误信息
+**图像生成失败**
+- 确认API余额充足
+- 检查提示词是否合适
+- 尝试更换模型

-**Q: 图像上传失败**
- 检查图像格式是否支持
- 确认图像文件大小是否合理
- 尝试使用不同的浏览器
+**图像无法显示**
+- 检查网络连接
+- 清除浏览器缓存
+- 尝试刷新页面

-### 调试技巧
-1. 打开浏览器开发者工具（F12）
+**存储空间不足**
+- 使用"清除存储数据"功能
+- 删除不需要的图像
+- 检查浏览器存储限制
+
+### 调试方法
+1. 打开浏览器开发者工具 (F12)
 2. 查看Console标签的错误信息
-3. 检查Network标签的API请求状态
-4. 验证API响应数据格式
+3. 检查Network标签的请求状态
+4. 验证API响应内容

-## 许可证
+## 📊 性能优化

-本项目基于MIT许可证开源，详见LICENSE文件。
+### 存储优化
+- 自动清理过期聊天记录 (最多50条)
+- 限制生成图像数量 (最多20张)
+- 使用IndexedDB替代LocalStorage

-## 贡献
+### 网络优化
+- 请求重试机制
+- 并发控制
+- 超时处理

-欢迎提交Issue和Pull Request来改进这个项目！
+### 用户体验优化
+- 加载状态指示
+- 批量操作进度显示
+- 错误信息友好提示

-## 联系方式
+## 🔒 安全注意事项

-如有问题或建议，请通过以下方式联系：
- GitHub Issues
- Email: [您的邮箱]
+1. **API密钥安全**: 密钥仅存储在本地浏览器，不会上传到服务器
+2. **隐私保护**: 所有数据本地存储，不收集用户信息
+3. **文件安全**: 上传文件仅用于图像生成，不会被保存或传输
+4. **网络安全**: 仅与OpenRouter官方API通信
+
+## 📄 许可证
+
+本项目基于 MIT 许可证开源。详见 [LICENSE](LICENSE) 文件。
+
+## 🤝 贡献指南
+
+欢迎提交 Issue 和 Pull Request！
+
+1. Fork 本仓库
+2. 创建功能分支
+3. 提交更改
+4. 发起 Pull Request
+
+## 📞 支持与反馈
+
+如有问题或建议，请：
+- 提交 GitHub Issue
+- 查看项目Wiki
+- 参与社区讨论

 ---

-**注意**: 这是一个前端演示应用，生产环境使用时请注意API密钥的安全性。
+**提示**: 本应用为前端静态应用，可直接在浏览器中运行，无需服务器部署。建议在HTTPS环境下使用以确保最佳安全性。