feat: AI 生图、图片下载优化

docs/v2.1/HANDOFF.md

@@ -1,7 +1,7 @@
 # 工作交接说明（HANDOFF）
 
-> 更新：2026-08-28 晚
-> 读者：下一个接手工作的 AI / 开发者。先读本文再动手，避免重复探索。
+> 更新：2026-08-29 晚
+> 读者：下一个接手工作的 AI / 开发者（工具无关）。先读本文再动手，避免重复探索。
 > 配套文档：[`README`](../../README.md)（项目总览）、[`collect.md`](./collect.md)（采集）、[`trial-page.md`](./trial-page.md)（试算页）、[`image-suite.md`](./image-suite.md)（生图）、[`api.md`](./api.md)（契约）、[`backend-structure.md`](./backend-structure.md)（后端结构）
 
 ---
@@ -22,78 +22,118 @@ extensions/collector 扩展采集（Ozon/1688/淘宝/天猫）
 ## 2. 启动与构建
 
 ```bash
-# server（我最后用的方式；日志在 /tmp/osk-server.log）
-cd ozon-seller-kit
+# 一键启动（推荐）：自动装依赖 → 构建采集插件 → 起插件改动监听 → 起 studio → 起 server
+./start.command
+
+# server 单独起（等价；日志建议重定向到 /tmp/osk-server.log）
 .venv/bin/uvicorn main:app --app-dir server --reload --reload-include "*.yaml" --host 127.0.0.1 --port 8800
 
-# studio
-pnpm -C studio dev          # http://localhost:8900，/api 代理到 8800
-
-# 扩展（改了扩展代码后必跑，然后 chrome://extensions 刷新）
-pnpm -C extensions/collector install   # 首次
+# 扩展改动后（start.command 的监听会自动构建，仍需去 chrome://extensions 手动点刷新）
 pnpm -C extensions/collector build     # 产物 .output/chrome-mv3
 ```
 
-密钥在根目录 `.env`（已配好）：`DEEPSEEK_API_KEY`（规划+文案）、`RIGHTAPI_API_KEY`（生图主力：gpt-image-2-vip / nano-banana 系列）、`DASHSCOPE_API_KEY`（通义，可选）、`ARK_API_KEY` 未配（豆包未用）。
+- **start.command 新增**：启动时自动构建采集插件，并起后台监听（3s 轮询 `src/**` + `wxt.config.ts`，改动自动重建；BSD find 语法，无新依赖）。Ctrl+C 会连同监听进程一起清理。
+- **运行态提醒**：交接时 server 是上个会话用 nohup 起的后台进程（日志 `/tmp/osk-server.log`），原 start.command 终端已被停掉。新会话建议：`kill $(lsof -ti :8800)` 后用 `./start.command` 正常接管。
+- **`uvicorn --reload` 不监控 `.env`**：改 `.env` 后必须手动重启 server（Kill 8800 端口进程再起）。
+- 密钥在根目录 `.env`：`DEEPSEEK_API_KEY`（规划+文案）、`DASHSCOPE_API_KEY`（通义，可用 ✅）、`RIGHTAPI_API_KEY`（RightCode 中转，**通道当前故障** ❌）、`PCORE_API_KEY`（pcore.ai，**可用 ✅**）、`ARK_API_KEY` 未配（豆包未用）。`.env.example` 有全部键位说明。
 
-## 3. 当前进度
+## 3. 生图供应商现状（2026-08-29，重要）
 
-### ✅ 已完成（已提交，git log 有记录）
-| 阶段 | 内容 |
+| 供应商 | 域名 | 模型（下拉显示） | 状态 |
+|---|---|---|---|
+| 通义/阿里 | dashscope.aliyuncs.com | `qwen-image-3.0-pro` 等（阿里巴巴） | ✅ 可用，实测 10s 出图 |
+| RightCode | rightapi.ai | `gpt-image-2`、`gpt-image-2-vip`、`nano-banana` 系列（RightCode） | ❌ 通道故障：任务能提交但生成阶段 503/「No available channel」，纯文生图也失败；中转侧问题，待其恢复 |
+| Pcore | pcore.ai | `gpt-image-2@pcore`（Pcore） | ✅ 可用（用户已在 pcore 开通 image2 分组后端到端跑通，全链路约 1 分钟/张） |
+
+- **默认生图模型 = `gpt-image-2@pcore`**（`studio/src/services/suite.ts` 的 `DEFAULT_IMAGE_MODEL`）。
+- **同名模型多中转的路由约定**：前端模型 value 用「api模型@provider」后缀区分（目前仅 pcore 用到），服务端 `schemas/suite.py` 的 `MODEL_PROVIDERS` + `api_model()`（剥后缀）处理；白名单 `PCORE_MODELS`。
+- **pcore 协议要点**（`generator.py` 的 `_pcore_request`/`_pcore_poll_task`）：无参考图走 `POST /v1/images/generations`，带参考图走 `/v1/images/edits` 且 images 必须是 **`[{image_url: dataURI}]` 对象数组**（纯字符串报错）；均为异步：提交拿 `id` → 轮询 `GET /v1/images/{kind}/{task_id}` → `completed` 后 `data[0].url` 取图。`size` 是枚举（1024x1536/1024x1024），不接受自定义尺寸。new_api 系中转常见「HTTP 200/503 + 错误体」，错误解析已兼容嵌套 `error.{code,message}`；「No available channel」类错误不重试直接失败。
+- **速率**：image2 分组 RPM 70 / RPD 1.2K（日限）；生图全局串行（`generator.py` 的 `asyncio.Lock`），远碰不到 RPM。pcore 账户余额 $5，按张扣费。
+
+## 4. AI 规划张数策略（`planner.py`）
+
+- **不设硬性数量**：prompt 让 AI 按商品复杂度自主决定，「建议 8 张左右」；规划规则 = 先保证每个 SKU 1 张主图，其余类型自行取舍。
+- **用户可通过「生图要求」指定张数**：写了「N 张」AI 必须严格执行；服务端 `_total_budget()` 用正则提取，安全上限：默认 15、指定时按 N 最大 24（防跑飞，超限从尾部截断，SKU 主图优先保留）。
+- **规划器曾频繁报「规划器未返回有效方案项」**：根因是 deepseek-v4 是思维链模型而规划器裸调用没禁 thinking，token 被推理烧光、正文为空。已修复：请求体加 `"thinking": {"type": "disabled"}` + 解析失败/空方案自动重试一次 + 失败时记录原始输出 + 缺 title 的方案项从 detail/kind 兜底合成不再丢弃。30 SKU 压测 3/3 通过。
+
+## 5. 当前进度
+
+### ✅ 已完成（含 2026-08-29 一轮，**全部未提交**，见 §6）
+
+| 模块 | 内容 |
 |---|---|
-| Phase A | 试算页前端 `/trial/:id` 五区块：1 商品信息 / 2 价格试算（公式对齐 v1 web）/ 3 俄文文案 / 4 采集图片+出图方案+生成结果 / 5 入库与导出 |
-| Phase C | ISS 扩展并入 `extensions/collector/`；「上报商品」按钮（01 区块下方）→ 入库 + 新标签打开试算页；设置弹窗含上报开关/后台地址/试算页地址 |
-| Phase B | 生图服务端（`server/api/suite.py` + `services/{planner,generator,prompts/,tasks,watermark}`，平移自 image-suite-studio） |
-| 后端整理 | 鉴权全删（server+studio）；冻结链路隔离 `server/legacy/`（接口仍挂载）；`collection.py`→`materials.py`；suite 业务下沉 `services/suite_service.py` |
+| 试算页 | 五区块页面、计价、俄文文案、采集图片/出图方案/生成结果、登记导出 |
+| 采集对接 | ISS 扩展并入 `extensions/collector/`，「上报商品」入库 + 自动打开试算页 |
+| 生图服务端 | planner/generator/prompts/watermark/tasks，套图 + 单张 AI 生图 + 水印 + ZIP 导出 |
+| **本轮：Pcore 接入** | 新 provider 全链路（生成/编辑/轮询/重试/错误处理），`@pcore` 路由约定，下拉带供应商名，默认模型切 Pcore |
+| **本轮：规划器修复** | thinking 禁用 + 重试 + 张数策略（AI 自主，建议 8 张左右，生图要求可指定） |
+| **本轮：采集箱** | 勾选列 + 全选/取消全选 + 批量删除（硬删、Popconfirm 二次确认、删空页自动回退） |
+| **本轮：采集图片区改版** | 8 列网格；AI 生图按钮半透明悬浮图片右下角；图名显示在图片下方（取 URL 末段）；SKU 名并入图名行（不再悬浮遮挡勾选钮）；勾选钮在右上角；默认全部不勾选 |
+| **本轮：生成结果区** | 「导出图片」按钮（水印按钮右侧，复用 POST /api/export/images，ZIP 内分「套图结果/单张生图」文件夹）；「单张 AI 生图」小节改名「生图记录」（落库历史，刷新后保留） |
+| **本轮：关键 bug 修复** | ① axios 全局 Content-Type 导致 FormData 被 JSON 化 → 上传 422（`api.ts` 移除全局头，**今后勿设**）；② TrialPage `load()` 置 loading 导致整页闪 Spin、卸载面板（杀生图轮询/丢勾选）→ 改静默刷新；③ web v1 页面因 cdn.tailwindcss.com 被墙整页无样式 → tailwind 运行时固化到 `web/vendor/tailwind.js` |
+| **本轮：杂项** | 采买地址「打开地址」改图标按钮（与复制图标同款）；start.command 自动构建+监听插件 |
 
-### ✅ 已联调验证（真实调用生图 API）
-plan / generate（串行队列+轮询+回写 generated）/ image-edit（单张，含 `after_asset_id` 插入原图后）/ 水印（文字 Panda Store 右下角）/ export/images（ZIP 分组结构）/ proxy-image / DELETE /api/assets/{id}（删素材+文件）/ materials 上报（product_id 返回）。
+### 验证口径（本轮均实测通过）
 
-### 🔨 最近一轮 UI 迭代（**部分未提交**，见 git status）
-- 出图方案卡：左右 12:12；左列灰卡内含「规划并生成 + AI 智能规划」；数量改 Stepper（− 输入 ＋，0-5）；AI 智能规划按钮高度与一键生图一致；说明文字支持换行
-- 水印设置移到「6 生成结果」标题栏最右；默认文本改 `Panda Store`
-- 生成结果卡：新增「单张 AI 生图」小节（含套图回写与单张图）；底部「AI 编辑」可点击 → 同款生图弹窗，新图经 `after_asset_id` 插在原图后；每张图右上角 ✕ 删除（Popconfirm 二次确认 → `DELETE /api/assets/{id}`）
-- 采集图片卡不再显示 generated 素材（归生成结果卡）
-- 型号/货号：后缀独立存储（货号框 `addonBefore` 展示 `型号-`，只输后缀；型号/货号框后有复制按钮）；型号含 `-` 不再增殖
-- 侧边栏：展开 200 / 折叠 60，折叠图标居中（`SidebarMenu.css` 尾部规则）
-- 采买地址：「打开地址」按钮 + 复制图标；仅 1688/淘宝/天猫/拼多多来源自动填充
-- 试算页水印弹窗默认文本 Panda Store（注意 localStorage `trialWatermark` 有旧值需手改一次）
+- 上传/生图/导出/批量删除/规划，全部真实接口+浏览器操作验证；Pcore 端到端 56s 出图并回写素材。
+- 每个 UI 改动后 `pnpm -C studio exec tsc -b` 零错误；插件构建通过；`/api/health` 200。
 
-## 4. 下一步（按优先级）
+## 6. ⚠️ 未提交改动清单（当前最大事项）
 
-1. **提交当前改动**：`git status` 有一批未提交（后端整理 + 最近 UI 迭代 + extensions settings 改动），建议按模块分 2-3 个 commit
-2. **手动全流程回归**（浏览器 + Chrome 真机扩展）：采集 → 上报 → 试算页五区块 → 生成/编辑/删除 → 登记表录入/导出 CSV/组合码 → 清空
-3. **Phase D 待办**：批量 CSV 服务端化（`GET /api/export/trial-csv`，替代前端逐个拉详情拼装）；登记表数据当前存 localStorage（换设备不可见，如需跨设备要落库）
-4. **远期**：鉴权/账户体系重做（从 `server/deps.py` 层重新引入）；ISS-only 产品模式构建配置；`extension-v1/v2`、`web/`、`server/legacy/` 的清理时机
+分支 `feat-2.1.0`，工作区有 19 个文件改动 + 1 个新目录，**建议按模块分 3-4 个 commit**：
 
-## 5. 已知坑（新会话必读）
+1. **Pcore 生图接入 + 规划器修复 + 张数策略**
+   `server/services/{generator,planner,suite_service,prompts/__init__}.py`、`server/{api/suite.py,schemas/suite.py,config/settings.py}`、`studio/src/services/suite.ts`、`.env.example`、`docs/v2.1/{image-suite,api}.md`
+2. **试算页 UI 迭代 + 采集箱批量操作 + 请求层修复**
+   `studio/src/pages/trial/{TrialSuitePanel,TrialInfoPanel,TrialPage}.tsx`、`studio/src/pages/collection/CollectionPage.tsx`、`studio/src/services/api.ts`
+3. **web v1 样式修复（CDN 固化）+ start.command 插件自动构建**
+   `web/ozonSeller.html`、`web/vendor/tailwind.js`（新目录）、`start.command`
+4. **交接文档**：`docs/v2.1/HANDOFF.md`
+
+提交前：`git checkout -- studio/tsconfig.app.tsbuildinfo`（构建产物，勿提交）。
+
+## 7. 下一步（按优先级）
+
+1. **提交**：按 §6 分组提交。
+2. **手动全流程回归**（浏览器 + Chrome 真机扩展）：采集 → 上报 → 试算页五区块 → 生成（Pcore）/编辑/删除 → 登记表录入/导出 CSV/组合码 → 清空。
+3. **运营观察**：pcore 余额（$5 起步）与 image2 分组日限（1.2K 张/天）；RightCode 通道恢复情况（恢复后 nano-banana 系列可回归）。
+4. **Phase D 待办**：批量 CSV 服务端化（`GET /api/export/trial-csv`）；登记表数据存 localStorage（跨设备需落库）。
+5. **远期**：鉴权/账户体系重做（从 `deps.py` 层重引）；ISS-only 产品模式构建；`extension-v1/v2`、`web/`、`server/legacy/` 清理时机。
+
+## 8. 已知坑（新会话必读）
 
 | # | 坑 | 对策 |
 |---|---|---|
 | 1 | `uvicorn --reload` 不监控 `.env` | 改 `.env` 后手动重启 server |
-| 2 | 套图任务在内存（`services/tasks.py`） | server 重启丢任务状态（前端已提示重新生成）；已落盘图片不丢 |
+| 2 | 套图任务在内存（`services/tasks.py`） | server 重启丢任务状态（前端已提示重新生成）；已落盘图片不丢（在「生图记录」区） |
 | 3 | 生图全局串行（`generator.py` 的 `asyncio.Lock`） | 一次只跑一个生成队列，测试时别并发提交 |
-| 4 | 单张 image-edit 是同步接口 | gpt 系列单张 1-5 分钟，前端 axios 超时 120s 可能先断（后端仍在跑，图会出现在生成结果） |
-| 5 | **ZCode IAB 浏览器调试 quirks**：`press`/Backspace 键注入在该页时灵时不灵（`fill` 可靠）；`fullPage` 截图偶发失败；文件上传不可用；改代码后页面 React 事件偶发失灵 → **reload 页面**即恢复 | 优先用 `fill`/`domSnapshot`/`getBoundingClientRect` 的 evaluate（注意 evaluate 可能被拒 side-effect，读值即可） |
-| 6 | 试算页水印文本存 localStorage（`trialWatermark`） | 改默认值不影响已保存设置；登记表同理存 localStorage `trialRegisterRecords` |
-| 7 | `studio/tsconfig.app.tsbuildinfo` 是构建产物 | 提交前 `git checkout -- studio/tsconfig.app.tsbuildinfo` |
-| 8 | 冻结代码不要投入 | `server/legacy/`、`extension-v1/`、`extension-v2/`、`web/`、studio 商品编辑页的属性映射/发布区块 |
-| 9 | AI 规划/生图花钱 | rightapi 按张计费；联调时 plan 张数设 1-2、优先 `nano-banana-2-lite`（快/便宜） |
+| 4 | 单张 image-edit 是同步接口 | 慢模型单张 1-5 分钟，前端 axios 超时 120s 可能先断（后端仍在跑，图会出现在生图记录） |
+| 5 | **axios 实例勿设全局 Content-Type** | axios 1.x 遇「默认 JSON 头 + FormData」会把表单转 JSON 发送（`formDataToJSON`），multipart 接口全 422。已从 `api.ts` 移除；对象请求体 axios 会自动补 JSON 头 |
+| 6 | `web/` 样式依赖公网 CDN | tailwind 已固化 `web/vendor/tailwind.js`；font-awesome/jsdelivr 若也断，同样方式下载到 `web/vendor/` 改引用 |
+| 7 | 试算页水印文本存 localStorage（`trialWatermark`） | 改默认值不影响已保存设置；登记表同理存 localStorage `trialRegisterRecords` |
+| 8 | `studio/tsconfig.app.tsbuildinfo` 是构建产物 | 提交前 `git checkout -- studio/tsconfig.app.tsbuildinfo` |
+| 9 | 冻结代码不要投入 | `server/legacy/`、`extension-v1/`、`extension-v2/`、`web/`（本轮 CDN 固化属修复例外）、studio 商品编辑页的属性映射/发布区块 |
+| 10 | AI 规划/生图花钱 | pcore 按 $ 扣费、RightCode 按张计费；联调时 plan 张数设 1-2、优先低成本模型 |
+| 11 | TrialPage `load()` 勿再置 loading | 置 loading = 整页 Spin + 卸载面板 = 杀生图轮询/丢状态（已修，保持静默刷新） |
+| 12 | 浏览器自动化调试怪癖（如 ZCode IAB） | 截图偶发超时（重试一次多半仍失败，改用几何测量/计算样式验证）；文件上传需用 DataTransfer+input change 事件模拟；改代码后 React 事件偶发失灵 → reload 页面即恢复 |
 
-## 6. 关键文件速查
+## 9. 关键文件速查
 
 | 功能 | 前端（studio/src/） | 后端（server/） |
 |---|---|---|
-| 试算页骨架 | `pages/trial/TrialPage.tsx` | — |
-| 01 商品信息（型号/货号联动、采买地址） | `pages/trial/TrialInfoPanel.tsx` | `api/materials.py`（上报/删素材） |
+| 试算页骨架 | `pages/trial/TrialPage.tsx`（load() 是静默刷新，见坑 11） | — |
+| 01 商品信息（采买地址图标、型号/货号联动） | `pages/trial/TrialInfoPanel.tsx` | `api/materials.py` |
 | 02 价格试算 | `pages/trial/TrialPricingPanel.tsx` + `pricing/pricing.ts` | — |
 | 03 俄文文案 | `pages/product/CopyPanel.tsx`（共用） | `api/ai.py` + `services/deepseek.py` + `prompts/copy_ru.py` |
-| 04 图片与生图 | `pages/trial/TrialSuitePanel.tsx` + `AiImageGenModal.tsx` | `api/suite.py` + `services/{suite_service,generator,planner,prompts/,tasks,watermark}.py` |
+| 04 图片与生图（8 列网格/悬浮按钮/图名） | `pages/trial/TrialSuitePanel.tsx` + `AiImageGenModal.tsx` | `api/suite.py` + `services/{suite_service,generator,planner,prompts/,tasks,watermark}.py` |
+| 生图供应商路由 | `services/suite.ts`（IMAGE_MODEL_OPTIONS 带供应商名；DEFAULT_IMAGE_MODEL） | `schemas/suite.py`（MODEL_PROVIDERS/`@pcore` 约定）+ `services/generator.py`（generate_pcore 等） |
 | 05 登记与导出 | `pages/trial/TrialExportPanel.tsx`（localStorage `trialRegisterRecords`） | — |
+| 生成结果导出 | `TrialSuitePanel.tsx` handleExportResult（套图+单张分组 ZIP） | `api/export.py` |
+| 采集箱（全选/批量删除） | `pages/collection/CollectionPage.tsx` | `api/products.py`（DELETE hard=true） |
 | 前端服务层 | `services/{suite,product,ai,fx,api}.ts` | `schemas/suite.py`（契约对齐） |
 | 扩展上报 | `extensions/collector/src/api/report.ts` + `entrypoints/{background,sidepanel/App}.tsx` + `storage/settings.ts` | `api/materials.py` |
 
-## 7. 验收标准（改完怎么算完成）
+## 10. 验收标准（改完怎么算完成）
 
 1. `pnpm -C studio exec tsc -b` 零错误、`pnpm -C studio build` 通过（提交前还原 `tsconfig.app.tsbuildinfo`）
 2. 改扩展：`pnpm -C extensions/collector build` 通过

docs/v2.1/api.md

@@ -33,7 +33,7 @@
 ```
 **Res** `{ "summary": "一句话方案说明", "items": [ { "kind": "white_bg", "title": "白底主图", "detail": "…", "prompt_hint": "…", "count": 2, "variant_name": "粉色|null" } ] }`
 
-实现要点：DeepSeek 单行紧凑 JSON；kind 白名单清洗；count 钳 0-3；幻觉 variant 丢弃绑定；总数建议 8-15。同步接口（数秒级）。
+实现要点：DeepSeek 单行紧凑 JSON；kind 白名单清洗；count 钳 0-3；幻觉 variant 丢弃绑定；总张数 AI 自主（建议 8 张左右；安全上限：默认 15，生图要求指定「N 张」时按 N、最大 24）。同步接口（数秒级）。
 
 ## 3. 一键生成 `POST /api/suite/generate`（Phase B）
 

docs/v2.1/image-suite.md

@@ -30,7 +30,7 @@
 
 - **类型白名单（10 种）**：white_bg 白底主图 / key_features 核心卖点图 / selling_pt 卖点图 / material 材质图 / lifestyle 场景展示图 / multi_scene 多场景拼图 / ecommerce_detail 电商详情图 / size_chart 尺寸标注图 / sku_collection SKU合集 / custom 创意图。
 - **默认方案**：前 7 种各 1 张；行点击切换 0↔1，± 调 0-5，「全部方案」批量开关。
-- **AI 规划**：请求 `{product_id, texts, sku_variants, image_stats, platform, requirements}`；DeepSeek 输出单行 JSON `{summary, items:[{kind,title,detail,prompt_hint,count,variant_name}]}`；服务端清洗（kind 白名单、count 钳 0-3、幻觉 SKU 丢弃绑定、截断修复）。规则：每个带图 SKU 1 张 white_bg 且绑定 variant_name；总数 8-15。
+- **AI 规划**：请求 `{product_id, texts, sku_variants, image_stats, platform, requirements}`；DeepSeek 输出单行 JSON `{summary, items:[{kind,title,detail,prompt_hint,count,variant_name}]}`；服务端清洗（kind 白名单、count 钳 0-3、幻觉 SKU 丢弃绑定、截断修复）。规则：每个带图 SKU 1 张 white_bg 且绑定 variant_name。**总张数由 AI 自主决定（不设硬性数量，建议 8 张左右）**；「生图要求」写「N 张」可指定张数（AI 必须执行）；服务端只设防跑飞安全上限（默认 15、指定时按 N 最大 24），超限从尾部截断（2026-08-29）。
 - **规划并生成**：勾选后规划完成直接进入生成。
 - SKU 规格来源：`product_assets` 中 `group_key='sku'` 的 `variant_name` 去重。