docs: add T-619 vision task and image edit script

docs/00-ai-start-here.md

@@ -48,7 +48,7 @@
 4. Phase 3：对外 API 与充值 —— T-301 Key 鉴权、T-302 生成接口、T-303 余额查询、T-304 充值回调、T-305 扫码下单与轮询、T-306 安全加固已完成。
 5. Phase 4：用户端（Django 模板 SSR）—— T-501 注册登录、T-502 API Key 管理、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化已完成。
 6. Phase 5：后台与发布 —— T-401 运营后台完善、T-402 完整验收 MVP、T-403 部署 / 运行文档已完成；计划内 MVP 任务已收尾。
-7. Phase 6：增强（MVP 后）—— T-601 可用别名发现已完成，实现 `/api/v1/models` 与 portal 只读「可用模型」页；T-602 已完成 django-admin 分组/表名中文化；T-603 已完成字段级中文标签代码与 no-op 迁移并人工确认 admin 字段中文化；T-604 已完成中文敏感词本地过滤；T-605 已完成免邮箱验证策略落地；T-606 已完成公开首页 + 客户端下载入口；T-607 已完成桌面端最新版本检查接口；T-608 已完成新用户注册赠送 100 点试用点数；T-609 已完成桌面端版本检查接口增加强制更新标记；T-610 已完成首页导入模板下载入口；T-611 已完成用户端品牌名统一为虾皮圈；T-612 已完成生图同步接口止血；T-613 已完成抽生成核心 service；T-614 已完成生图异步任务化接口；T-615 已完成旧同步生图接口遥测与弃用口径；当前没有未领取的编号任务。
+7. Phase 6：增强（MVP 后）—— T-601~T-618 已完成，覆盖可用别名发现、后台中文化、敏感词过滤、免邮箱验证、公开首页与客户端发布、注册赠点、用户端品牌、生图异步化 / 遥测 / 自动重试和客户端发布校验元数据；T-619「多张图片理解并返回文字」已登记为下一项 `TODO`，将新增独立 `vision` 操作、能力别名和同步多图理解接口，当前尚未实现。
 
 ## 领取任务规则
 

docs/06-tasks.md

@@ -98,6 +98,7 @@
 
 | T-617 | 桌面端版本检查接口增加文件大小字段 | T-607, T-609 | 在 `GET /api/v1/client/releases/latest?platform=windows` 的当前版本响应中，为 `release` 对象新增 `size_bytes` 字段，用于桌面端下载后比对文件大小。**接口兼容**：只新增字段，不删除既有 `version` / `download_url` / `sha256` / `release_notes` / `force_update` / `published_at`；无当前版本或无下载地址时仍返回 `release:null`，不返回顶层 `size_bytes`。**数据来源**：`DownloadRelease` 新增 `size_bytes` 可空正整数字段，单位字节，django-admin 可填写并在列表展示；老数据为空时接口返回 `null`，客户端只在值为正整数时做大小校验。**安全**：接口仍公开匿名只读，不读取用户、不扣点、不暴露后台 ID、本地文件路径或内部状态。**文档**：同步 `api.md`、`routes.md`、`04-architecture.md`、`02-requirements.md`、`current-state.md`。**测试**：覆盖有值返回整数、未配置返回 `null`、未发布响应不返回顶层字段、响应字段白名单更新、admin 字段可见；`makemigrations --check` / `check` / 目标测试通过并在 `../progress.md` 留证据 | DONE |
 | T-618 | 客户端发布版本后台必填文件校验元数据 | T-617 | 把 django-admin 里 `DownloadRelease` 的 `sha256` 和 `size_bytes` 改为必填，避免运营发布客户端安装包时漏填校验元数据，导致桌面端无法完整校验下载文件。**范围**：本任务只要求 admin 后台保存时必填；为兼容历史数据和现有 API 合约，第一步不直接把数据库字段改成 `NOT NULL`，`size_bytes` 仍允许旧记录为空，API 暂保持可返回 `null`；若后续要数据库级强约束，需先单独回填全量历史发布记录再做迁移。**实现**：`DownloadReleaseAdmin` 已挂专用 `ModelForm`，将 `sha256`、`size_bytes` 设为 required，并保留 `sha256` 64 位十六进制校验、`size_bytes >= 1` 校验；admin 新增 / 编辑保存时未填会显示字段级错误，不写库。**生产数据**：上线后必须补齐当前 `windows` 发布版本的 `size_bytes`，再验证 `/api/v1/client/releases/latest?platform=windows` 返回正整数 `release.size_bytes`；已有 `sha256` 继续保留并核对。**兼容性**：不删除既有 API 字段，不改变无当前版本时的 `release:null`；非 admin 的历史数据、迁移和只读接口不应因空值直接 500。**文档**：同步 `api.md`、`04-architecture.md`、`routes.md`、`current-state.md` 和 `progress.md` 的发布校验口径。**测试**：已覆盖 admin 表单缺 `sha256` / 缺 `size_bytes` 拒绝保存、合法 `sha256 + size_bytes` 可保存、API 仍能读取历史空值记录、当前版本补齐后接口返回正整数；`check` / `makemigrations --check` / 目标测试通过并在 `../progress.md` 留证据 | DONE |
+| T-619 | 多张图片理解并返回文字 | T-613, T-601, T-306 | 新增独立的多模态图片理解能力，不复用“生成标题”语义。**操作与别名**：在 `ModelAlias.OperationType`、`CallRecord.OperationType` 和别名解析中新增 `vision`；建议首个数据库别名为 `vision-standard`，但不得在接口中暴露具体供应商模型名。`vision` 别名指向的 `AiModel` 及 Provider 必须同时具备 `vision` 与文字输出能力，图片生成 / 编辑专用 Provider 不得误接。**新增接口**：`POST /api/v1/analyze/images`，继承 `ExternalApiView`、使用 API Key 鉴权和生成限流，同步返回 `{text, alias, model_used, points_cost, points_balance, call_id}`；不改变 `/api/v1/generate/title`、`/api/v1/generate/image` 及异步生图接口。**请求结构**：`prompt` 必填，`model` 可选，`images` 为有序列表且至少 1 张；每项必须且只能提供一个 `image_url` 或 `image_base64`，允许 URL/base64 混合。新增 `VISION_MAX_IMAGES=8`、`VISION_MAX_IMAGE_BYTES=10485760`、`VISION_MAX_TOTAL_BYTES=33554432` 三个可配置上限，分别控制单次图片数量、单图解码后字节数和总字节数；超限、空列表、格式错误或同项双来源返回 `400 bad_request`，不扣点、不调上游。**安全时序**：serializer 后先按 T-604 审核 prompt，再下载 URL / 解码 base64；每个 URL 必须复用 T-306 的协议、公网地址、重定向逐跳校验、超时和响应大小保护，不另写弱化下载器。第一版只审核文字 prompt，不声称已做图片内容审核。**Provider**：复用 `apps/ai/providers` 现有 HTTP 适配层，增加向 Chat Completions / Gemini 发送多张图片并保序的兼容能力；不得复制第二套上游调用实现。现有单图标题 / 生图调用签名与行为保持兼容。**计费与留痕**：复用 T-613 共享生成 core 与 billing 的预扣 / 成功确认 / 幂等退点；第一版按 `operation_type=vision + alias` 的默认 `PricingRule` 对一次请求固定扣点，不按图片张数重复扣费，图片数量上限用于控制成本；上游失败必须退点。`CallRecord` 记录 `vision`、别名、实际模型、点数、耗时和结果摘要，不保存输入图片、base64、provider raw 或完整上游响应。**目录与运营配置**：`GET /api/v1/models` 和 portal 可用模型页按 T-601 既有语义列出 active、能力匹配的 `vision` 别名并显示 `requires_image=true`；有定价时返回 `priced`，缺定价时仍返回 `unpriced`，不得改变现有目录兼容行为。代码部署 / migrate 后由运营在 admin 配置支持视觉理解的 `AiModel`、`vision-standard` 默认别名和计费规则，不通过数据迁移写入真实上游配置或密钥。**范围边界**：本任务只做同步文字结果，不做流式输出、异步 vision task、OCR 专用接口、结构化 JSON schema、图片内容审核，也不为 OCR / 商品识别 / 图片对比各建别名；这些用途先由 prompt 表达，只有底层模型或价格确实不同时再增加别名。**文档**：实现时同步 `02-requirements.md`、`04-architecture.md`、`api.md`、`routes.md`、`env.md`、`current-state.md` 和 `progress.md`。**测试**：覆盖单图 / 多图 / 混合来源及顺序、默认 / 指定别名、模型与 Provider 能力拒绝、图片数量与大小限制、SSRF、敏感词先拦截、成功仅扣一次、上游失败仅退一次、调用记录不保存图片 / raw、模型目录安全字段、旧标题 / 生图接口回归；`makemigrations` / `migrate` / `check` / 目标测试 / `init` 通过并在 `../progress.md` 留证据 | TODO |
 
 ## 里程碑
 
@@ -115,6 +116,7 @@
 - M12：生图失败自动重试（T-616）。
 - M13：桌面端版本文件大小校验元数据（T-617）。
 - M14：客户端发布版本后台必填校验元数据（T-618）。
+- M15：多张图片理解并返回文字（T-619）。
 
 ## 待办池（Backlog）
 

progress.md

@@ -1898,3 +1898,18 @@
   - 测试期仍保留 allauth `account.EmailAddress` 条件唯一约束在 MySQL 上不可创建的既有 `models.W036` 警告。
 - 部署提醒：
   - 代码部署后需要在生产 admin 补齐当前 Windows 发布版本的 `size_bytes`，并验证 `GET /api/v1/client/releases/latest?platform=windows` 返回正整数 `release.size_bytes`。
+
+## 2026-07-16 文档登记：T-619 多张图片理解并返回文字
+
+- 状态：TODO（仅任务登记，未改代码或数据库）。
+- 背景：现有对外能力只有生成标题与生成图片；标题接口虽然可带单张图片，但返回语义固定为标题，不能作为通用的单图 / 多图理解接口。当前 Provider 已有部分 `vision` 能力声明，但生成核心、序列化器和公开操作类型仍只支持单个图片输入与 `title` / `image`。
+- 文档变更：
+  - `docs/06-tasks.md`：新增 T-619「多张图片理解并返回文字」，状态为 TODO，并登记 M15。
+  - `docs/current-state.md` / `docs/00-ai-start-here.md`：把 T-619 设为下一项可领取任务，并明确当前尚未实现。
+- 方案口径：
+  - 新增独立 `vision` 操作与建议默认别名 `vision-standard`，不复用标题别名，不向调用方暴露具体上游模型。
+  - 新增同步 `POST /api/v1/analyze/images`；请求使用有序 `images` 列表，每项二选一提供 `image_url` 或 `image_base64`，返回普通文字 `text`。
+  - 第一版按一次请求固定扣点，并通过 `VISION_MAX_IMAGES=8`、`VISION_MAX_IMAGE_BYTES=10485760`、`VISION_MAX_TOTAL_BYTES=33554432` 限制图片数量、单图大小和总大小；只审核 prompt，不声称已做图片内容审核。
+  - 多图上游调用必须扩展既有 Provider 和 T-613 共享生成 core；图片 URL 必须复用现有 SSRF 防护，失败复用计费层幂等退点。
+  - 本任务不包含流式、异步 vision task、OCR 专用接口或结构化 JSON 输出；OCR、商品识别和图片对比先通过 prompt 表达。
+- 验证：`./init.ps1` 通过，Python 3.12.3，依赖已满足，`manage.py check` 0 issues；任务登记完成后继续执行文档 diff 检查。

xiaxiuxiu.py

@@ -0,0 +1,49 @@
+# POST https://xiaxiuxiu.com/v1/images/edits (OpenAI compatible)
+# Use the fixed source image and prompt file to generate one optimized image.
+import base64
+import os
+import urllib.request
+from pathlib import Path
+
+from openai import OpenAI
+
+
+BASE_DIR = Path(__file__).resolve().parent
+SOURCE_IMAGE = BASE_DIR / "51513423876.jpg"
+PROMPT_FILE = BASE_DIR / "图生图提示词.txt"
+OUTPUT_IMAGE = BASE_DIR / "51513423876_new.jpg"
+TITLE = "韓系極簡V領扭結短袖上衣"
+
+
+api_key = os.environ.get("XIAXIUXIU_API_KEY", "").strip()
+if not api_key:
+    raise RuntimeError("请先设置环境变量 XIAXIUXIU_API_KEY")
+if not SOURCE_IMAGE.is_file():
+    raise FileNotFoundError(f"找不到固定原图：{SOURCE_IMAGE}")
+if not PROMPT_FILE.is_file():
+    raise FileNotFoundError(f"找不到固定提示词文件：{PROMPT_FILE}")
+
+client = OpenAI(
+    api_key=api_key,
+    base_url="https://xiaxiuxiu.com/v1",
+)
+prompt = PROMPT_FILE.read_text(encoding="utf-8").replace("{新标题}", TITLE)
+
+with SOURCE_IMAGE.open("rb") as image_file:
+    response = client.images.edit(
+        model="gpt-image-2",
+        image=image_file,
+        prompt=prompt,
+        size="1024x1024",
+        n=1,
+    )
+
+item = response.data[0]
+if getattr(item, "b64_json", None):
+    OUTPUT_IMAGE.write_bytes(base64.b64decode(item.b64_json))
+elif getattr(item, "url", None):
+    urllib.request.urlretrieve(item.url, OUTPUT_IMAGE)
+else:
+    raise RuntimeError(f"返回数据中没有图片内容：{item}")
+
+print(f"已生成新图片并保存到本地：{OUTPUT_IMAGE}")

图生图提示词.txt

@@ -0,0 +1,41 @@
+商品标题:{新标题}
+【核心執行指令：韓系極簡・質感女裝電商主圖】
+1. 畫面風格與氛圍 (視覺基調)
+
+場景化生活感： 捨棄死板工廠掛拍與雜亂背景，全面升級為高級的「韓系生活氛圍感」實穿場景。整體色彩採用韓系極簡風，以奶茶色調、莫蘭迪色系、鼠尾草綠等低飽和色彩為主。搭配明亮、柔和的自然光影，呈現乾淨清透的視覺質感與愜意的日常氛圍（如咖啡廳一角、質感街道、畫廊展間）。
+
+情緒價值： 讓買家在 1 秒內產生強烈共鳴，傳遞出「這套搭配極具質感 / 穿起來氣質很好 / 這就是我想要的韓系高級感」。
+
+2. 模特兒設定與人體結構防錯 (重點規範)
+
+精準人體結構 (最高權重防錯)： 確保人體骨骼與四肢結構 100% 符合真實人類解剖學。嚴格禁止生成多餘肢體（如三隻手、三條腿、多根手指）、禁止關節扭曲、肢體融合或殘缺。手部動作（如提包、拿咖啡、整理髮絲）必須極度自然逼真。
+
+目標受眾樣貌： 模特兒限定為 20-22歲的年輕台湾女孩，標準通用身材（不刻意強調過瘦或大碼）。展現出自信、慵懶或優雅俐落的韓系歐膩氣質。臉部樣貌需具備多樣性，絕對避免每次生成同一張臉。
+
+自然動態展示： 模特兒需展現自然神情（自然微笑或放鬆的表情）。透過不經意的動態姿勢（如微側身、自然走動、轉身）優雅展現衣服的版型、剪裁與垂墜感，动作姿态需具備多樣性。
+
+3. 產品還原與視覺優化 (商品核心)
+
+100% 實物還原： 完美保留原圖衣服的款式、材質與設計亮點（如特色刺繡、盤扣、不規則下擺、抽繩褶皺、獨特印花等），禁止擅自改變服裝結構。完美承襲原圖的靈魂單品搭配（如小棕包、項鍊、手鐲等配件）。
+
+版面佔比與構圖： 服裝必須佔據整體版面 60% 以上，確保商品是畫面的絕對視覺中心。
+
+4. 標籤、排版與浮水印 (後製規範)
+
+動態時效性標籤 (條件觸發)： 嚴格遵循標題判定機制。
+
+若商品標題中未出現「現貨」、「快速出貨」、「24H出貨」等時效性詞彙，嚴禁在圖片上添加任何相關標籤。
+
+若標題中明確包含此類時效詞，則必須在主圖中設計一個吸睛、突出的時效性標籤。標籤設計需精緻，與整體的韓系極簡美學保持絕對和諧，不可破壞畫面美感。
+
+極簡文案： 畫面保持 90% 以上的純淨度。若需添加核心賣點文字，絕對不可遮擋服裝細節。
+
+隱蔽防盜浮水印： 強制在圖片空白处添加「潮衣舍」浮水印。严禁遮挡衣服或者模特。字體總寬度嚴格限制在圖片總寬度的 5% 以內，透明度絕對鎖定在 3%。確保其極度低調、無侵入性，絕不破壞 4K 高清細節與畫面留白美感。
+
+5. 輸出與交付標準 (系統設定)
+
+免選方案直接輸出： 接收商品圖與標題後，請大腦自動篩選並「直接輸出」最具點擊率潛力（最能打動 20-25 歲客群）的唯一優化主圖，無需再提供多種方案挑選。
+
+規格限制： 輸出為 4K 高清畫質的 JPEG 格式，比例 1:1（建議解析度 1024x1024 或以上），且單張檔案大小不超過 2MB。
+
+6.本系列全部为现货商品，请增加设计一个突出，吸睛的含有现货，隔日达，快速出货等时效性词的标签。整体画面和谐，絕對不可遮擋服裝細節。