feat: 重构项目结构并添加平台同步基础架构

- 重构项目目录结构，将功能模块移至 modules/ 目录 - 创建平台同步基础架构，包括发布器基类和 GitHub 发布器 - 新增 UI 状态管理模块 (modules/ui/state.py) 统一管理会话状态 - 更新依赖配置，添加平台同步所需依赖 (httpx, pyperclip) - 整理文档结构，将所有文档分类移至 docs/ 目录 - 添加 .cursorrules 文件定义项目开发规范 - 清理根目录重复文件，保持项目结构整洁
2026-01-30 10:21:29 +08:00
parent 77d5ec70f8
commit 8f7f082c3d
102 changed files with 33742 additions and 1526 deletions
@@ -0,0 +1,221 @@
+# 图片生成问题调试指南
+
+> 问题：点击生成图片后直接提示"未成功生成任何图片"
+> 创建日期：2026-01-28
+
+---
+
+## 🔍 问题分析
+
+### 可能的原因
+
+1. **API Key 未配置或配置错误**
+   - 通义万相 API Key 未在侧边栏配置
+   - API Key 格式错误
+   - API Key 已过期或无效
+
+2. **API 调用失败**
+   - 网络连接问题
+   - API 服务不可用
+   - 免费额度已用完
+   - API 限流
+
+3. **Prompt 生成失败**
+   - LLM 调用失败
+   - Prompt 为空或格式错误
+   - 内容不合规
+
+4. **API 响应解析错误**
+   - 响应格式不符合预期
+   - `response.output.results` 为空
+   - `image_url` 为空
+
+5. **异常被静默捕获**
+   - 异常被捕获但没有正确显示
+   - 错误信息丢失
+
+---
+
+## ✅ 已添加的调试功能
+
+### 1. 详细的错误信息显示
+
+在图片生成失败时，现在会显示：
+- **错误类型**：API调用失败、Prompt为空、响应解析错误等
+- **错误详情**：具体的错误消息
+- **调试信息**：
+  - Prompt 内容（前200字符）
+  - API Key 配置状态
+  - 异常堆栈跟踪
+
+### 2. 输入验证
+
+- ✅ 验证 Prompt 不为空
+- ✅ 验证 API 响应不为空
+- ✅ 验证 `image_url` 存在
+- ✅ 验证 `response.output.results` 不为空
+
+### 3. 异常处理增强
+
+- ✅ 捕获所有异常并显示详细信息
+- ✅ 显示异常堆栈跟踪
+- ✅ 区分不同类型的错误
+
+---
+
+## 🔧 调试步骤
+
+### 步骤1：检查 API Key 配置
+
+1. 打开侧边栏 **⚙️ 全局配置**
+2. 找到 **🖼️ 通义万相（图片生成）** 部分
+3. 确认 API Key 已正确配置
+4. 点击 **应用配置**
+
+### 步骤2：查看错误信息
+
+如果生成失败，点击 **查看详细错误信息** 或 **查看异常详情**，查看：
+- 错误消息
+- Prompt 内容
+- API Key 配置状态
+- 异常堆栈跟踪
+
+### 步骤3：检查常见问题
+
+#### 问题1：API Key 未配置
+**症状**：错误信息显示"API Key 配置: 未配置"
+**解决**：在侧边栏配置通义万相 API Key
+
+#### 问题2：API 调用失败
+**症状**：错误信息显示"API调用失败，状态码：XXX"
+**可能原因**：
+- 网络连接问题
+- API 服务不可用
+- 免费额度已用完
+- API 限流
+
+**解决**：
+- 检查网络连接
+- 检查 API 服务状态
+- 检查免费额度
+- 等待后重试
+
+#### 问题3：Prompt 为空
+**症状**：错误信息显示"图片生成 Prompt 为空"
+**可能原因**：
+- LLM 调用失败
+- 内容为空
+- Prompt 生成异常
+
+**解决**：
+- 检查内容是否为空
+- 检查 LLM 配置
+- 重试生成
+
+#### 问题4：响应解析错误
+**症状**：错误信息显示"生成成功但未返回图片URL"
+**可能原因**：
+- API 响应格式变化
+- `response.output.results` 为空
+- `image_url` 为空
+
+**解决**：
+- 查看详细错误信息中的响应内容
+- 检查 API 文档是否有变化
+- 联系技术支持
+
+---
+
+## 📋 代码修改说明
+
+### 修改1：增强错误处理（geo_tool.py）
+
+**位置**：第3670-3700行（智能生成模式）
+
+**修改内容**：
+- 添加 Prompt 验证
+- 添加 result 验证
+- 添加 image_url 验证
+- 添加详细的错误信息显示
+- 添加异常堆栈跟踪
+
+### 修改2：增强错误处理（geo_tool.py）
+
+**位置**：第3792-3820行（基于描述生成模式）
+
+**修改内容**：
+- 与智能生成模式相同的错误处理增强
+
+### 修改3：增强 API 响应处理（multimodal_prompt.py）
+
+**位置**：第706-740行
+
+**修改内容**：
+- 验证 `response.output.results` 不为空且长度 > 0
+- 验证 `image_url` 不为空
+- 添加详细的错误信息
+- 包含响应状态码、消息、错误码、请求ID等
+
+---
+
+## 🧪 测试建议
+
+### 测试1：正常流程
+1. 配置正确的 API Key
+2. 生成内容
+3. 点击"生成图片"
+4. 应该成功生成图片
+
+### 测试2：API Key 未配置
+1. 不配置 API Key
+2. 点击"生成图片"
+3. 应该显示"请在侧边栏配置中设置通义万相 API Key"
+
+### 测试3：API 调用失败
+1. 配置错误的 API Key
+2. 点击"生成图片"
+3. 应该显示详细的错误信息
+
+### 测试4：Prompt 为空
+1. 使用空内容
+2. 点击"生成图片"
+3. 应该显示"图片生成 Prompt 为空"错误
+
+---
+
+## 📝 常见错误信息对照表
+
+| 错误信息 | 可能原因 | 解决方法 |
+|---------|---------|---------|
+| "图片生成 Prompt 为空" | LLM 调用失败或内容为空 | 检查内容、检查 LLM 配置 |
+| "图片生成 API 返回空结果" | API 调用异常 | 检查网络、检查 API Key |
+| "API调用失败，状态码：XXX" | API 服务错误 | 检查 API 服务状态、检查免费额度 |
+| "生成成功但未返回图片URL" | API 响应格式错误 | 查看详细错误信息、检查 API 文档 |
+| "图片生成成功但图片URL为空" | API 响应中缺少 URL | 查看详细错误信息、联系技术支持 |
+| "未安装 dashscope 库" | 缺少依赖库 | 运行：pip install dashscope |
+
+---
+
+## 🔍 进一步调试
+
+如果问题仍然存在，请：
+
+1. **查看详细错误信息**
+   - 点击"查看详细错误信息"或"查看异常详情"
+   - 复制错误信息
+
+2. **检查日志**
+   - 查看浏览器控制台
+   - 查看 Streamlit 日志
+
+3. **验证 API Key**
+   - 在阿里云 DashScope 控制台验证 API Key
+   - 检查免费额度
+
+4. **测试 API 调用**
+   - 使用 curl 或 Postman 直接测试 API
+   - 验证 API Key 是否有效
+
+---
+
+*文档创建时间：2026-01-28*