cmshoppe/docs/tasks/T-565.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-565	兼容 cmhub 异步生图返回相对图片地址	7	T-564	DONE	2026-07-09

问题 / 背景

T-564 切到 cmhub 异步生图任务接口后，②AI生成在 poll 返回 succeeded 后进入下载阶段，但真实运行出现：

图片生成失败：下载新封面失败：cmhub 图片地址只允许 http/https

从日志看，submit 和 poll 都成功，失败发生在本地下载前的 URL 安全校验。根因是当前 app/ai.py 的异步 poll 成功分支只读取 result.image_url / 顶层 image_url，并直接传给下载器；如果 cmhub 返回的是相对路径（如 /generated/images/...png）、协议相对 URL（//host/path）、image_url 对象或图片列表字段，本地会把非完整 URL 字符串交给 _assert_public_http_url()，从而报“只允许 http/https”。

方案

• app/ai.py
  • 新增 cmhub 异步任务图片地址提取/规整 helper。
  • poll succeeded 后复用现有 _find_image_ref() 递归提取图片地址，兼容 result.image_url、result.image_url.url、result.images[]、result.image_urls[]、顶层同类字段。
  • 对相对路径按当前 cmhub Base URL 规整为完整 http(s)://host/... 后再进入原有公网 URL 安全校验和下载流程。
  • 如果仍无法提取地址，报清晰中文错误“cmhub 生图任务成功但没有图片地址”；如果字段存在但格式不可用，报“cmhub 生图任务返回的图片地址格式错误”。
• tests/test_ai.py
  • 覆盖异步 poll 返回相对路径时能拼成完整 URL 下载。
  • 覆盖异步 poll 返回 image_urls 列表时能提取第一张图片。

验收要点

• cmhub poll 返回 result.image_url="/generated/xxx.png" 时，下载 URL 应为 <base_url>/generated/xxx.png。
• cmhub poll 返回 result.image_urls=["https://..."] 时可正常下载。
• 原有绝对 https://... 图片地址路径不回归。
• 验证命令：
  • py -3.10 -m unittest tests.test_ai
  • python -m ruff check app tests main.py
  • py -3.10 -m compileall app main.py
  • git diff --check

边界（不改什么）

• 不改 DB schema、tasks.image_task_id/image_task_key 生命周期。
• 不改 cmhub submit/poll 状态机和重试策略。
• 不改 curl/requests 下载实现和公网 URL 安全校验。
• 不改 CDP/Shopee、Excel、GUI 布局。

执行记录

• 2026-07-09：完成 T-565。
  • app/ai.py：新增 _extract_cmhub_image_url() / _normalize_cmhub_image_url()，异步 poll 和旧同步兼容路径统一通过 helper 提取图片地址；兼容 image_url、image_url.url、images[]、image_urls[]、协议相对 URL 与相对路径，并在下载前按 cmhub Base URL 补全。
  • tests/test_ai.py：新增/调整 cmhub 异步生图测试，覆盖 poll 返回相对路径时拼接完整 URL 下载，以及 image_urls 列表提取。
  • 文档：同步 docs/api.md、docs/cmhub-integration-design.md 的图片地址兼容口径。
  • 验证通过：py -3.10 -m unittest tests.test_ai、python -m ruff check app tests main.py、py -3.10 -m compileall app main.py、py -3.10 -m unittest discover -s tests、git diff --check。