docs: sync cmhub download diagnostics and progress

04-architecture/api 记录下载层最多 3 次安全重试（复用同一 image_url、
不重发生图）、下载超 20 秒告警、CMSHOPEE_DEBUG_CMHUB_IMAGE_URL 调试开关；
current-state/progress 同步。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/04-architecture.md

@@ -402,7 +402,8 @@ data/images/<batch_id>/<slug>/<task_id>_<item_id>_new.<ext>    # AI 生成的新
 1. **并发生成标题**：线程池大小 = `title_concurrency`，调 `gen_title(标题提示词, old_title)` → new_title。默认 `backend=cmhub`，调用 `POST /api/v1/generate/title` 并使用 `title_alias`；`backend=direct` 仅内部兼容时使用 `default_text_model`。
 2. **若②勾选「生成封面图片（成本较高）」**：接着并发生成图片，线程池大小 = `image_concurrency`，调 `gen_cover(封面提示词, old_cover_path, resolution, jpg_quality)` → 新图存 `data/images/<batch_id>/<slug>/<task_id>_<item_id>_new.jpg`。默认 `backend=cmhub`，调用 `POST /api/v1/generate/image`，拿 `image_url` 后立即安全下载并转本地 JPEG；`backend=direct` 仅内部兼容时使用 `default_image_model`。
    - T-545 已实现：cmhub 模式下不再直接按用户填写的 `image_concurrency` 全量打到网关；实际生图请求并发 = `min(image_concurrency, 5)`。拿到 `image_url` 后交给独立下载/保存线程池，下载线程数量与实际生图请求并发一致，同样最大 5。这样批量时“下一批生图请求”和“上一批图片下载/保存”可以流水线并行，但不会对 cmhub 生图接口或 `/media/generated/images/*.png` 静态下载打出超过 5 的并发。direct 兼容路径暂不改变。
-   - cmhub 生图连接超时取 `ai.cmhub.connect_timeout`；生图请求和随后 `image_url` 下载的读取等待统一固定 650 秒，读超时不自动重发，避免重复扣点。`backend=direct` 兼容路径仍按模型 `timeout_seconds` 或 `resolution_timeouts[resolution]`（512→180/1k→240/2k→360/4k→600）取返回超时。
+   - cmhub 生图连接超时取 `ai.cmhub.connect_timeout`；生图请求和随后 `image_url` 下载的读取等待统一固定 650 秒，读超时不自动重发，避免重复扣点。下载层最多安全重试 3 次，只复用同一个 `image_url`，不重新请求 cmhub 生图；下载总耗时超过 20 秒时写“图片下载较慢”警告。`backend=direct` 兼容路径仍按模型 `timeout_seconds` 或 `resolution_timeouts[resolution]`（512→180/1k→240/2k→360/4k→600）取返回超时。
+   - cmhub 返回的完整 `image_url` 默认只在内存中临时用于下载，不写入 `tasks` 或 `run_log_events`。本机调试时可设置环境变量 `CMSHOPEE_DEBUG_CMHUB_IMAGE_URL=1`，②本轮可见运行日志会显示脱敏后的 URL 调试行，且该行不持久化到 SQLite。
 3. **若未勾选生成封面**：标题成功后立即写 `new_title`，`new_cover_path=NULL`，不渲染封面提示词、不调用 `gen_cover()`、不创建本地新封面文件。
 
 - 失败重试：每次调用失败按 `retry` 次重试，仍失败则记 error（不阻塞其余）。

docs/api.md

@@ -313,7 +313,8 @@ fetch_cmhub_models(base_url, api_key, connect_timeout=10, read_timeout=30) -> li
 - `api_type=chat/auto` 走 OpenAI-compatible chat JSON；`api_type=images_edits` 走 multipart form。
 - direct 连接超时参考模型 `connect_timeout_seconds`；**返回超时 = 模型 `timeout_seconds` 或 `appconfig.response_timeout()`（随分辨率：512/1k/2k/4k → 180/240/360/600）**。cmhub 使用 `requests timeout=(connect, read)`，connect 来自 `ai.cmhub.connect_timeout`；cmhub 生文读取等待固定 600s，cmhub 生图请求和图片下载读取等待固定 650s，且生图读超时不自动重发。
 - 并发数/重试/分辨率/jpg 质量来自 `appconfig.ai_config()`；Key 本地明文存储，但不入日志、不导出。cmhub 响应的 `points_cost/points_balance/call_id` 不改变返回值，通过 `on_event` metadata 事件上报，GUI 余额/计费展示留给 T-528。
-- 标题快、图片慢：分两段、各用各自并发数；失败按 `retry` 重试，仍失败记 error 不阻塞其余。cmhub 生图使用内部实际并发 `min(image_concurrency, 5)`，拿到 `image_url` 后交给独立下载/保存线程池，下载线程数与实际生图并发一致且最大 5；direct 兼容路径暂保持原 `image_concurrency` 语义。
+- 标题快、图片慢：分两段、各用各自并发数；失败按 `retry` 重试，仍失败记 error 不阻塞其余。cmhub 生图使用内部实际并发 `min(image_concurrency, 5)`，拿到 `image_url` 后交给独立下载/保存线程池，下载线程数与实际生图并发一致且最大 5；下载失败最多安全重试 3 次，只复用同一个 `image_url`，不会重新调用 cmhub 生图接口；下载总耗时超过 20 秒时写“图片下载较慢”警告；direct 兼容路径暂保持原 `image_concurrency` 语义。
+- 调试 cmhub 图片 URL：默认不在日志或 DB 中记录完整 `image_url`。若本机调试需要查看，启动程序前设置环境变量 `CMSHOPEE_DEBUG_CMHUB_IMAGE_URL=1`，②本轮可见运行日志会显示脱敏后的“cmhub 图片 URL”，但该调试行不写入 SQLite `run_log_events`。
 - 调用有成本与失败可能：超时、限流、内容安全拒绝都要返回明确错误。
 - 生成结果**直接进入 ③ 更新候选**；③ 点击「开始更新」后弹窗批量确认，确认后提交线上。本地留档 + 回写 Excel 供追溯。
 

docs/current-state.md

@@ -49,13 +49,13 @@
 | `.github/workflows/tests.yml` | 已有 | T-522/T-525 产出：push / pull_request 自动在 `windows-latest` + Python 3.11 安装 `requirements.txt` 与 `requirements-dev.txt`，设置 `QT_QPA_PLATFORM=offscreen`，运行 ruff lint、`python -m compileall app main.py` 与 `python -m unittest discover -s tests` |
 | `app/version.py` | 已有 | T-540 产出：统一维护 `APP_NAME`、`APP_CODE_NAME`、`APP_VERSION` 和窗口显示名；GUI 标题、打包脚本、release 目录、portable zip 和 `version.txt` 共用该版本源 |
 | `cmshopee.spec` / `scripts/build_exe.ps1` | 已有 | T-524/T-540 产出：PyInstaller onedir 构建配置与发布目录校验脚本；`cmshopee.spec` 不声明本地数据 `datas`，脚本固定使用 `py -3.10`，先检查 `dist\\cmshopee` 不含配置、DB、图片、日志、Chrome 登录态或提示词，再组装 `release\\cmshopee-<APP_VERSION>\\` 与 `release\\cmshopee-<APP_VERSION>-portable.zip` |
-| `app/gui/` | 已有 | T-523 产出：由旧 `app/gui.py` 拆分的 PySide6 GUI 包，包入口 `__init__.py` 继续兼容 `from app import gui` / `from app.gui import MainWindow`；`main_window.py` 放 MainWindow，`models.py` 放 3 个 TableModel，`widgets.py` 放色板/空状态/批次总览/helper，`workers.py` 放具体 GUI workers，`tabs/` 放 ①~⑤ Tab； T-104/T-105/T-106/T-202/T-202b/T-203/T-204/T-204b/T-205/T-206/T-207/T-302/T-302p/T-303/T-303b/T-401/T-402/T-403/T-404a/T-501/T-501b/T-501c/T-503/T-504/T-506/T-507/T-508/T-509/T-510/T-505/T-511/T-512/T-513/T-514/T-515/T-516/T-517/T-518/T-519/T-520/T-527/T-528/T-529/T-530/T-531/T-532/T-536/T-537/T-539/T-540/T-541/T-542/T-545 产出：PySide6 `QMainWindow` + 五 Tab；窗口标题显示「蝦皮圈優化助手 v<APP_VERSION>」，启动时按屏幕可用区域限制尺寸、居中并保证标题栏可见；顶部 Tab 栏防误点样式；全局 `QPushButton` 基础样式统一 4px 圆角、hover/pressed/disabled/focus 状态；统一语义色板、①②③状态列前景色、③开始更新 warning 语义色、①导入校验数字标红、④登录状态点、③Tab warning 小圆点、删除/未匹配按钮 danger 语义色样式、①②③首次空状态引导卡片和批次阶段进度总览；① 导入采集导入按钮、导入汇总栏、批次/店铺/商品ID/状态筛选、删除批次软删除按钮、`QTableView` 任务列表、未匹配筛选与略过标记、采集旧标题旧封面 worker（旧封面路径按批次/店铺/任务细分）、采集前账号就绪预检与④引导、采集完成自动回写与手动重试、采集运行日志视图；② AI生成左右布局、提示词管理、批次/店铺/商品ID/状态筛选栏、任务列表、新标题列本地编辑、开始生成/停止/标题与图片双进度条、双击新旧封面预览、用户可读自动滚动AI生成运行日志、重置生成结果与 `GenerateWorker`；③ 更新蝦皮批次/店铺/商品ID/状态筛选栏、任务列表、开始更新主按钮、重置更新状态右键菜单、蝦皮更新安全拦截与「前往设置」跳转、「检查本轮更新」按钮、开始更新确认弹窗、`ApplyWorker` 检查/分批串行/按账号并行、账号与端口预检、运行日志、逐条 `set_applied`、自动回写结果到 Excel、结束汇总弹窗与手动回写重试；④ 账号管理表格、账号弹窗、密码本地明文保存提示、启动登录、检测登录、快捷方式；⑤ 设置普通默认展示 cmhub 网关 Base URL、API Key、生文/生图动态别名、Base URL 网关根提示、刷新别名、测试连接/查余额并保存 `config/cmhub.json` Key，不再显示 AI 后端选择、direct 模型选择/详情/角色下拉；direct 配置仅内部兼容/手工回滚；通用生成参数里分辨率只控制 cmhub 生图尺寸，返回超时标签展示实际等待口径「标题 600 秒 / 图片 650 秒」，direct 兼容路径仍显示分辨率映射；Chrome 路径和端口配置、三列 蝦皮更新安全与执行模式设置仍保留，数据路径输入框已隐藏但保留配置兼容，高频安全/执行模式分区前置、基础设施分区后置，`test_item_id`/`dry_run` 兼容字段无用户入口且普通更新不再阻断正式更新；②封面模板「另存为/重命名/删除」低频操作已收敛进「模板操作」菜单；②AI生成底部已增加标题/图片双进度条，运行日志已改为用户可读、自动滚动、脱敏的长任务日志，且②本轮「生成封面图片（成本较高）」开关默认关闭并持久化到 `ai.generate_cover`，关闭时只生成标题并进入可更新状态；②cmhub模式会显示生成后的剩余点数，记录 points_cost/call_id 计费日志，并在点数不足时弹提示且中止未开始任务；②cmhub 生图会额外记录“cmhub 已返回 image_url / 图片下载完成 / 本地保存完成”的分段耗时和下载/保存大小，开始日志会显示“图片并发 X，cmhub实际生图并发 Y，下载并发 Y”，便于区分服务端生成慢、下载慢或本地保存慢；⑤设置页已显示“● 未保存更改”，切 Tab/关闭窗口时拦截保存/放弃/取消，放弃会从 `config.json` 与 `config/cmhub.json` 重新回填，刷新别名/测试连接不自动保存并提醒点保存；cmhub 测试连接/查余额成功时会优先显示 cmhub 账号名或脱敏邮箱，缺账号信息时保留普通成功提示 |
+| `app/gui/` | 已有 | T-523 产出：由旧 `app/gui.py` 拆分的 PySide6 GUI 包，包入口 `__init__.py` 继续兼容 `from app import gui` / `from app.gui import MainWindow`；`main_window.py` 放 MainWindow，`models.py` 放 3 个 TableModel，`widgets.py` 放色板/空状态/批次总览/helper，`workers.py` 放具体 GUI workers，`tabs/` 放 ①~⑤ Tab； T-104/T-105/T-106/T-202/T-202b/T-203/T-204/T-204b/T-205/T-206/T-207/T-302/T-302p/T-303/T-303b/T-401/T-402/T-403/T-404a/T-501/T-501b/T-501c/T-503/T-504/T-506/T-507/T-508/T-509/T-510/T-505/T-511/T-512/T-513/T-514/T-515/T-516/T-517/T-518/T-519/T-520/T-527/T-528/T-529/T-530/T-531/T-532/T-536/T-537/T-539/T-540/T-541/T-542/T-545 产出：PySide6 `QMainWindow` + 五 Tab；窗口标题显示「蝦皮圈優化助手 v<APP_VERSION>」，启动时按屏幕可用区域限制尺寸、居中并保证标题栏可见；顶部 Tab 栏防误点样式；全局 `QPushButton` 基础样式统一 4px 圆角、hover/pressed/disabled/focus 状态；统一语义色板、①②③状态列前景色、③开始更新 warning 语义色、①导入校验数字标红、④登录状态点、③Tab warning 小圆点、删除/未匹配按钮 danger 语义色样式、①②③首次空状态引导卡片和批次阶段进度总览；① 导入采集导入按钮、导入汇总栏、批次/店铺/商品ID/状态筛选、删除批次软删除按钮、`QTableView` 任务列表、未匹配筛选与略过标记、采集旧标题旧封面 worker（旧封面路径按批次/店铺/任务细分）、采集前账号就绪预检与④引导、采集完成自动回写与手动重试、采集运行日志视图；② AI生成左右布局、提示词管理、批次/店铺/商品ID/状态筛选栏、任务列表、新标题列本地编辑、开始生成/停止/标题与图片双进度条、双击新旧封面预览、用户可读自动滚动AI生成运行日志、重置生成结果与 `GenerateWorker`；③ 更新蝦皮批次/店铺/商品ID/状态筛选栏、任务列表、开始更新主按钮、重置更新状态右键菜单、蝦皮更新安全拦截与「前往设置」跳转、「检查本轮更新」按钮、开始更新确认弹窗、`ApplyWorker` 检查/分批串行/按账号并行、账号与端口预检、运行日志、逐条 `set_applied`、自动回写结果到 Excel、结束汇总弹窗与手动回写重试；④ 账号管理表格、账号弹窗、密码本地明文保存提示、启动登录、检测登录、快捷方式；⑤ 设置普通默认展示 cmhub 网关 Base URL、API Key、生文/生图动态别名、Base URL 网关根提示、刷新别名、测试连接/查余额并保存 `config/cmhub.json` Key，不再显示 AI 后端选择、direct 模型选择/详情/角色下拉；direct 配置仅内部兼容/手工回滚；通用生成参数里分辨率只控制 cmhub 生图尺寸，返回超时标签展示实际等待口径「标题 600 秒 / 图片 650 秒」，direct 兼容路径仍显示分辨率映射；Chrome 路径和端口配置、三列 蝦皮更新安全与执行模式设置仍保留，数据路径输入框已隐藏但保留配置兼容，高频安全/执行模式分区前置、基础设施分区后置，`test_item_id`/`dry_run` 兼容字段无用户入口且普通更新不再阻断正式更新；②封面模板「另存为/重命名/删除」低频操作已收敛进「模板操作」菜单；②AI生成底部已增加标题/图片双进度条，运行日志已改为用户可读、自动滚动、脱敏的长任务日志，且②本轮「生成封面图片（成本较高）」开关默认关闭并持久化到 `ai.generate_cover`，关闭时只生成标题并进入可更新状态；②cmhub模式会显示生成后的剩余点数，记录 points_cost/call_id 计费日志，并在点数不足时弹提示且中止未开始任务；②cmhub 生图会额外记录“cmhub 已返回 image_url / 图片下载完成 / 本地保存完成”的分段耗时和下载/保存大小，开始日志会显示“图片并发 X，cmhub实际生图并发 Y，下载并发 Y”，便于区分服务端生成慢、下载慢或本地保存慢，下载超过 20 秒会显示“图片下载较慢”警告；设置环境变量 `CMSHOPEE_DEBUG_CMHUB_IMAGE_URL=1` 时，②本轮可见运行日志会额外显示脱敏后的 cmhub 图片 URL 调试行，该行不写入 SQLite `run_log_events`；⑤设置页已显示“● 未保存更改”，切 Tab/关闭窗口时拦截保存/放弃/取消，放弃会从 `config.json` 与 `config/cmhub.json` 重新回填，刷新别名/测试连接不自动保存并提醒点保存；cmhub 测试连接/查余额成功时会优先显示 cmhub 账号名或脱敏邮箱，缺账号信息时保留普通成功提示 |
 | `app/workers.py` | 已有 | T-104b 产出：`BaseWorker` + 通用 signals + 取消标记 + `run_worker()` QThread 包装 |
 | `app/accounts.py` | 已有 | T-105/T-106 产出：账号 CRUD 服务、目录创建、端口分配、启动登录、检测登录、快捷方式 |
 | `app/editor.py` | 已有 | T-001/T-103/T-205b/T-207/T-501c/T-502/T-404b + T-404 补丁产出：登录状态检测、打开商品页、详情页加载失败 toast 捕获与商品失效归因、读/写标题、读/下载封面、采集步骤回调、更新步骤回调、采集后关闭自动新建商品页 tab、上传前等待图片管理器稳定、点击上传块后注入文件并检测 CDN 后拖封面、更新封面统一先校验旧封面备份再删线上第一张、重复图片 toast 明确失败、页面主更新按钮、Shopee 站点侧确认框主按钮、apply_task；更新成功后可按设置关闭本轮自动新建商品页 |
 | `app/appconfig.py` | 已有 | T-002/T-501c/T-503/T-504/T-520/T-526/T-527/T-538 产出：`data/config.json` 默认值、读写、更新、路径/端口/AI 参数读取、`data_dir` 路径解析、旧顶层用户数据迁移、`data/` 可写性检测、AI `backend=direct/cmhub` 和 `ai.cmhub` 默认值、`data/config/cmhub.json` Key helper、蝦皮更新安全与 dry-run/多账号并行默认值，②生成封面默认关闭的 `ai.generate_cover`；拒绝敏感字段写入；提供敏感值打码、结构化日志脱敏与自由文本替换工具 |
 | `app/diagnostics.py` | 已有 | T-207 + AI生成诊断补丁 + T-505 产出：本地 `data/logs/cmshopee.log` 诊断日志、大小滚动、异常类型/traceback/step/耗时记录，结构化 payload 和自由文本脱敏后写入 |
-| `app/ai.py` | 已有 | T-301/T-303 + AI生成诊断补丁 + T-519/T-520/T-526/T-528/T-533/T-535/T-545 产出：`gen_title()`/`gen_cover()`/`generate_batch()`；支持 direct 默认模型直连和 cmhub 网关 backend；cmhub 使用 `CMHubError` 结构化错误、tuple timeout、非幂等生图读超时不重发、`image_url` 安全下载、`fetch_cmhub_models()` 别名发现、`fetch_cmhub_balance()` 余额查询和 metadata 事件；cmhub 标题请求连接超时取 `ai.cmhub.connect_timeout`、读取等待固定 600 秒；cmhub 生图请求和图片下载读取等待固定 650 秒；cmhub 生图实际请求并发 = `min(ai.image_concurrency, 5)`，拿到 `image_url` 后交给独立下载/保存线程池，下载并发同样最大 5，下载失败只记该任务失败、不重发 cmhub 生图请求；direct 保留通用 HTTP 调用、失败重试、错误脱敏；封面按 resolution/jpg_quality 保存并按批次/店铺/任务路径落盘；批量生成可按 `ai.generate_cover` 跳过封面阶段，开启封面时按缺失组件增量补齐，已有标题不重生、不覆盖手动标题，已有封面不重生；进度回调按标题/封面组件统计，逐条落库、失败标记、事件/错误回调、停止取消未开始项 |
+| `app/ai.py` | 已有 | T-301/T-303 + AI生成诊断补丁 + T-519/T-520/T-526/T-528/T-533/T-535/T-545 产出：`gen_title()`/`gen_cover()`/`generate_batch()`；支持 direct 默认模型直连和 cmhub 网关 backend；cmhub 使用 `CMHubError` 结构化错误、tuple timeout、非幂等生图读超时不重发、`image_url` 安全下载、`fetch_cmhub_models()` 别名发现、`fetch_cmhub_balance()` 余额查询和 metadata 事件；cmhub 标题请求连接超时取 `ai.cmhub.connect_timeout`、读取等待固定 600 秒；cmhub 生图请求和图片下载读取等待固定 650 秒；cmhub 生图实际请求并发 = `min(ai.image_concurrency, 5)`，拿到 `image_url` 后交给独立下载/保存线程池，下载并发同样最大 5，下载失败最多安全重试 3 次，仍失败只记该任务失败、不重发 cmhub 生图请求；direct 保留通用 HTTP 调用、失败重试、错误脱敏；封面按 resolution/jpg_quality 保存并按批次/店铺/任务路径落盘；批量生成可按 `ai.generate_cover` 跳过封面阶段，开启封面时按缺失组件增量补齐，已有标题不重生、不覆盖手动标题，已有封面不重生；进度回调按标题/封面组件统计，逐条落库、失败标记、事件/错误回调、停止取消未开始项 |
 | `app/prompts.py` | 已有 | T-302p 产出：标题提示词读写、封面模板列表/读取/保存/重命名/删除、变量替换 |
 | `app/db.py` | 已有 | T-003/T-206/T-404a/T-504/T-509/T-534 产出：batches/accounts/tasks schema；batches 软删除字段与默认业务查询过滤；run_logs/run_log_events；WAL/busy_timeout/foreign_keys；账号/批次/任务与 set_* 阶段写库；生成结果/更新状态本地重置，②生成结果支持按标题/封面组件清空并保持 generated；`update_generated_title()` 本地新标题微调；运行日志写入与查询 |
 | `app/config.py` | 已有 | T-101 产出：别名→稳定 slug；创建并返回绝对 user-data-dir |

progress.md

@@ -1469,3 +1469,17 @@
 - 测试：`tests/test_ai.py` 覆盖并发计划、下载慢不阻塞后续 cmhub 生图请求提交、下载失败不重复请求 cmhub 生图；`tests/test_gui.py` 覆盖开始日志中的实际并发展示，并把 direct/mock 路径测试明确指定为 direct backend。
 - 文档：`docs/06-tasks.md` 将 T-545 标为 DONE；同步 `docs/04-architecture.md`、`docs/cmhub-integration-design.md`、`docs/api.md`、`docs/routes.md` 和 `docs/current-state.md`。
 - 验证：`py -3.10 -m unittest discover -s tests -p "test_ai.py"` 通过（27 tests）；`py -3.10 -m unittest discover -s tests -p "test_gui.py"` 通过（102 tests）；`python -m ruff check app tests main.py` 通过；`py -3.10 -m compileall app main.py` 通过；`git diff --check` 通过；`py -3.10 -m unittest discover -s tests` 通过（237 tests）。
+
+## 【2026-07-07】cmhub 图片 URL 调试开关
+
+- 背景：排查 cmhub 图片下载链路时，需要临时看到网关返回的 `image_url`，但默认把完整 URL 写入 DB/历史日志可能保留带签名参数的临时资源地址。
+- 代码：`app/ai.py` 在环境变量 `CMSHOPEE_DEBUG_CMHUB_IMAGE_URL=1` 时发出 `cover_image_url` 调试事件；`app/gui/workers.py` 将该事件显示到②本轮可见运行日志，并通过 `debug_only` 跳过 SQLite `run_log_events` 持久化。日志仍经过 `diagnostics.redact_log_text()` 脱敏。
+- 文档：同步 `docs/04-architecture.md`、`docs/api.md` 和 `docs/current-state.md`。
+- 验证：`py -3.10 -m unittest discover -s tests -p "test_ai.py"` 通过（28 tests）；`py -3.10 -m unittest discover -s tests -p "test_gui.py"` 通过（102 tests）；`python -m ruff check app tests main.py` 通过；`py -3.10 -m compileall app main.py` 通过；`git diff --check` 通过。
+
+## 【2026-07-07】cmhub 图片下载安全重试与慢下载警告
+
+- 背景：同一 cmhub 图片 URL 用 `curl` 测试通常 3~14 秒完成，但 GUI 日志中曾出现 1.7MB 下载耗时 72 秒，判断更像静态文件下载链路瞬时波动。
+- 代码：`app/ai.py` 的 cmhub `image_url` 下载层新增最多 3 次安全重试，只复用同一个 `image_url`，不重新调用 cmhub 生图接口，避免重复扣点；下载总耗时超过 20 秒时发出 `cover_download` warning 事件。`app/gui/workers.py` 将该事件显示为“图片下载较慢”运行日志。
+- 文档：同步 `docs/04-architecture.md`、`docs/api.md` 和 `docs/current-state.md`。
+- 验证：`py -3.10 -m unittest discover -s tests -p "test_ai.py"` 通过（30 tests）；`py -3.10 -m unittest discover -s tests -p "test_gui.py"` 通过（102 tests）；`python -m ruff check app tests main.py` 通过；`py -3.10 -m compileall app main.py` 通过；`git diff --check` 通过；`py -3.10 -m unittest discover -s tests` 通过（240 tests）。