WechatHookBot/plugins/Flow2API/修复说明.md

# Flow2API 插件修复说明

## 问题诊断

根据日志：
```
2025-11-26 11:44:16 | INFO | 使用 AIChat 代理: socks5://38.55.107.103:53054
2025-11-26 11:44:35 | ERROR | 图像生成失败
```

**问题：** 只显示"图像生成失败"，没有具体的错误信息，无法诊断问题原因。

## 修复方案

### 1. 改进错误日志 (main.py:204-209)

**修改前：**
```python
except Exception as e:
    logger.error(f"请求异常: {e}")
    continue
```

**修改后：**
```python
except Exception as e:
    import traceback
    logger.error(f"请求异常: {type(e).__name__}: {str(e)}")
    logger.error(f"异常详情:\n{traceback.format_exc()}")
    logger.error(f"提示词长度: {len(prompt)} 字符")
    continue
```

**改进点：**
- 显示完整的异常类型和堆栈跟踪
- 记录提示词长度，便于诊断
- 不再截断错误信息

### 2. 增强调试信息 (main.py:108-126)

**修改前：**
```python
logger.info(f"Flow2API请求: {model}, 提示词: {prompt[:50]}...")
timeout = httpx.Timeout(connect=10.0, read=api_config["timeout"], write=10.0, pool=10.0)
```

**修改后：**
```python
logger.info(f"Flow2API请求: {model}, 提示词长度: {len(prompt)} 字符")
logger.debug(f"完整提示词: {prompt}")
logger.debug(f"请求URL: {url}")
logger.debug(f"Payload大小: {len(str(payload))} 字节")

# 设置合理的超时时间
max_timeout = min(api_config["timeout"], 600)  # 增加到 10 分钟
timeout = httpx.Timeout(
    connect=10.0,      # 连接超时：10秒
    read=max_timeout,  # 读取超时：10分钟
    write=10.0,        # 写入超时：10秒
    pool=10.0          # 连接池超时：10秒
)
logger.debug(f"超时配置: connect=10s, read={max_timeout}s")

# 添加提示词长度检查和警告
if len(prompt) > 1000:
    logger.warning(f"提示词较长 ({len(prompt)} 字符)，可能影响处理速度")
```

**改进点：**
- 记录提示词长度而不是截断内容
- 增加超时时间到 10 分钟
- 添加 DEBUG 级别的详细信息
- 长提示词警告

### 3. 改进响应处理 (main.py:133-187)

**新增功能：**
```python
logger.debug(f"收到响应状态码: {response.status_code}")

# 处理流式响应
image_url = None
full_content = ""
async for line in response.aiter_lines():
    logger.debug(f"收到响应行: {line[:100]}...")
    # ... 解析逻辑 ...
    if content:
        full_content += content
        logger.debug(f"累积内容: {full_content[:100]}...")

# 如果没有从流中提取到URL，尝试从完整内容中提取
if not image_url and full_content:
    import re
    urls = re.findall(r'https?://[^\s\)\]"\']+', full_content)
    if urls:
        image_url = urls[0].rstrip("'\"")
        logger.info(f"从完整内容提取到图片URL: {image_url}")
    else:
        logger.warning(f"完整响应内容中未找到URL: {full_content}")

if not image_url:
    logger.error(f"未能提取到图片URL，完整响应: {full_content}")
```

**改进点：**
- 记录每一步的处理过程
- 累积完整响应内容
- 双重 URL 提取机制
- 显示完整响应内容以便调试

### 4. 添加 ReadTimeout 处理 (main.py:200-203)

```python
except httpx.ReadTimeout:
    logger.warning(f"读取超时（ReadTimeout），可能是图像生成时间过长，重试中... ({attempt + 1}/{max_retry})")
    logger.info(f"提示词长度: {len(prompt)} 字符，建议缩短提示词或增加超时时间")
    continue
```

**改进点：**
- 单独捕获 `ReadTimeout` 异常
- 提供友好的错误提示
- 自动重试（最多 3 次）

### 5. 添加下载失败重试 (main.py:184-187)

```python
if image_path:
    logger.success("成功生成图像")
    return [image_path]
else:
    # 下载失败，继续重试
    logger.warning(f"图片下载失败，将重试 ({attempt + 1}/{max_retry})")
    continue
```

**改进点：**
- 图片下载失败时自动重试
- 重新请求 API 获取新的图片 URL

## 常见错误及解决方案

### 错误 1: 未能提取到图片URL

**日志示例：**
```
ERROR | 未能提取到图片URL，完整响应: {"error": "..."}
```

**可能原因：**
- API 返回了错误而不是图片 URL
- 响应格式不符合预期
- Token 无效或过期

**解决方案：**
- 检查 API Token 是否正确
- 查看完整响应内容，了解 API 返回的错误信息
- 检查 API 配置（base_url）

### 错误 2: ReadTimeout 超时

**日志示例：**
```
WARNING | 读取超时（ReadTimeout），可能是图像生成时间过长，重试中... (1/3)
```

**可能原因：**
- 图像生成时间过长（复杂提示词）
- 网络不稳定
- API 服务器响应慢

**解决方案：**
- 缩短提示词长度
- 增加配置文件中的 `timeout` 值
- 检查网络连接和代理设置

### 错误 3: 图片下载失败

**日志示例：**
```
ERROR | 下载图片失败: Client error '404 Not Found'
WARNING | 图片下载失败，将重试 (1/3)
```

**可能原因：**
- 图片 URL 已过期
- CDN 链接失效
- 网络问题

**解决方案：**
- 自动重试会重新请求 API 获取新 URL
- 检查代理设置
- 如果持续失败，联系 API 提供商

### 错误 4: Token 认证失败

**日志示例：**
```
ERROR | Token认证失败
```

**解决方案：**
- 检查 `config.toml` 中的 `token` 配置
- 确认 Token 是否有效
- 联系 API 提供商获取新 Token

## 调试步骤

### 1. 启用 DEBUG 日志

修改 `main_config.toml`：
```toml
[Performance]
log_level_console = "DEBUG"  # 改为 DEBUG
log_level_file = "DEBUG"
```

### 2. 查看详细日志

```bash
# 实时查看日志
tail -f WechatHookBot/logs/hookbot.log | grep -E "Flow2API|图像生成"

# 搜索错误
grep "Flow2API" WechatHookBot/logs/hookbot.log | grep -E "ERROR|WARNING"
```

### 3. 测试命令

```bash
# 在微信中发送
/绘画f 一只可爱的猫咪

# 或横屏
/绘画f横屏 美丽的风景
```

### 4. 检查配置

查看 `plugins/Flow2API/config.toml`：
```toml
[api]
base_url = "https://your-api-url.com"  # 确认 URL 正确
token = "your-token"                    # 确认 Token 有效
timeout = 600                           # 超时时间（秒）
```

## 预期日志输出

### 成功案例：

```
INFO | Flow2API请求: gemini-3.0-pro-image-portrait, 提示词长度: 15 字符
DEBUG | 完整提示词: 一只可爱的猫咪
DEBUG | 请求URL: https://api.example.com/v1/chat/completions
DEBUG | Payload大小: 234 字节
DEBUG | 超时配置: connect=10s, read=600s
INFO | 使用 AIChat 代理: socks5://127.0.0.1:7890
DEBUG | 收到响应状态码: 200
DEBUG | 收到响应行: data: {"choices":[{"delta":{"content":"https://..."}}]}
INFO | 提取到图片URL: https://cdn.example.com/image.jpg
INFO | 图片下载成功: /path/to/flow2_20251126_114435_abc123.jpg
SUCCESS | 成功生成图像
```

### 失败但重试成功：

```
INFO | Flow2API请求: gemini-3.0-pro-image-portrait, 提示词长度: 15 字符
DEBUG | 收到响应状态码: 200
INFO | 提取到图片URL: https://cdn.example.com/expired.jpg
ERROR | 下载图片失败: Client error '404 Not Found'
WARNING | 图片下载失败，将重试 (1/3)
INFO | Flow2API请求: gemini-3.0-pro-image-portrait, 提示词长度: 15 字符
INFO | 提取到图片URL: https://cdn.example.com/new-image.jpg
INFO | 图片下载成功: /path/to/flow2_20251126_114436_def456.jpg
SUCCESS | 成功生成图像
```

### 完全失败（显示详细错误）：

```
INFO | Flow2API请求: gemini-3.0-pro-image-portrait, 提示词长度: 15 字符
ERROR | 请求异常: HTTPStatusError: Client error '401 Unauthorized'
ERROR | 异常详情:
Traceback (most recent call last):
  File "main.py", line 131, in generate_image
    async with client.stream("POST", url, json=payload, headers=headers) as response:
  ...
httpx.HTTPStatusError: Client error '401 Unauthorized' for url '...'
ERROR | 提示词长度: 15 字符
ERROR | 图像生成失败
```

## 配置建议

### config.toml 推荐配置

```toml
[api]
base_url = "https://your-api-url.com"
token = "your-api-token"
timeout = 600  # 10分钟，适合复杂图像生成

[generation]
default_orientation = "portrait"  # 默认竖屏
max_retry_attempts = 3            # 最多重试3次

[behavior]
enable_command = true
command_keywords = ["/绘画f", "/画图f"]
enable_group = true
enable_private = true

[llm_tool]
enabled = true
tool_name = "flow2_image_generation"
tool_description = "使用Flow2 AI生成图像..."
```

## 相关文件

- `main.py` - 主要修改文件
- `config.toml` - 配置文件
- `修复说明.md` - 本文档

## 总结

修复后，Flow2API 插件现在会：

1. ✅ 显示完整的错误堆栈跟踪
2. ✅ 记录详细的请求和响应信息
3. ✅ 自动处理 ReadTimeout 超时
4. ✅ 图片下载失败时自动重试
5. ✅ 提供友好的错误提示和调试信息

现在当遇到"图像生成失败"时，你可以在日志中看到具体的错误原因，便于快速定位和解决问题！