工作交接说明（HANDOFF）

更新：2026-08-29 晚读者：下一个接手工作的 AI / 开发者（工具无关）。先读本文再动手，避免重复探索。配套文档：README（项目总览）、collect.md（采集）、trial-page.md（试算页）、image-suite.md（生图）、api.md（契约）、backend-structure.md（后端结构）

1. 项目一句话

Ozon 跨境上品工具链。当前主链路（V2.1，已放弃 Ozon API 直传）：

extensions/collector 扩展采集（Ozon/1688/淘宝/天猫）
  → 「上报商品」POST /api/materials 入库 + 自动打开试算页
  → studio /trial/{id} 试算页：计价 → 俄文文案 → AI 生图（套图+单张）→ 登记
  → 导出 CSV / 组合码 → 人工上 Ozon 卖家后台

技术栈：FastAPI（server，8800）+ React19/Vite/antd6（studio，8900）+ WXT Chrome 扩展（extensions/collector）。SQLite（data/app.db），无鉴权（V2.1 决策：先功能后鉴权）。

2. 启动与构建

# 一键启动（推荐）：自动装依赖 → 构建采集插件 → 起插件改动监听 → 起 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

# 扩展改动后（start.command 的监听会自动构建，仍需去 chrome://extensions 手动点刷新）
pnpm -C extensions/collector build     # 产物 .output/chrome-mv3

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. 生图供应商现状（2026-08-29，重要）

供应商	域名	模型（下拉显示）	状态
通义/阿里	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）

模块	内容
试算页	五区块页面、计价、俄文文案、采集图片/出图方案/生成结果、登记导出
采集对接	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 自动构建+监听插件

验证口径（本轮均实测通过）

上传/生图/导出/批量删除/规划，全部真实接口+浏览器操作验证；Pcore 端到端 56s 出图并回写素材。
每个 UI 改动后 pnpm -C studio exec tsc -b 零错误；插件构建通过；/api/health 200。

6. ⚠️ 未提交改动清单（当前最大事项）

分支 feat-2.1.0，工作区有 19 个文件改动 + 1 个新目录，建议按模块分 3-4 个 commit：

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
试算页 UI 迭代 + 采集箱批量操作 + 请求层修复 studio/src/pages/trial/{TrialSuitePanel,TrialInfoPanel,TrialPage}.tsx、studio/src/pages/collection/CollectionPage.tsx、studio/src/services/api.ts
web v1 样式修复（CDN 固化）+ start.command 插件自动构建 web/ozonSeller.html、web/vendor/tailwind.js（新目录）、start.command
交接文档：docs/v2.1/HANDOFF.md

提交前：git checkout -- studio/tsconfig.app.tsbuildinfo（构建产物，勿提交）。

7. 下一步（按优先级）

提交：按 §6 分组提交。
手动全流程回归（浏览器 + Chrome 真机扩展）：采集 → 上报 → 试算页五区块 → 生成（Pcore）/编辑/删除 → 登记表录入/导出 CSV/组合码 → 清空。
运营观察：pcore 余额（$5 起步）与 image2 分组日限（1.2K 张/天）；RightCode 通道恢复情况（恢复后 nano-banana 系列可回归）。
Phase D 待办：批量 CSV 服务端化（GET /api/export/trial-csv）；登记表数据存 localStorage（跨设备需落库）。
远期：鉴权/账户体系重做（从 deps.py 层重引）；ISS-only 产品模式构建；extension-v1/v2、web/、server/legacy/ 清理时机。

8. 已知坑（新会话必读）

#	坑	对策
1	`uvicorn --reload` 不监控 `.env`	改 `.env` 后手动重启 server
2	套图任务在内存（`services/tasks.py`）	server 重启丢任务状态（前端已提示重新生成）；已落盘图片不丢（在「生图记录」区）
3	生图全局串行（`generator.py` 的 `asyncio.Lock`）	一次只跑一个生成队列，测试时别并发提交
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 页面即恢复

9. 关键文件速查

功能	前端（studio/src/）	后端（server/）
试算页骨架	`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 图片与生图（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`

10. 验收标准（改完怎么算完成）

pnpm -C studio exec tsc -b 零错误、pnpm -C studio build 通过（提交前还原 tsconfig.app.tsbuildinfo）
改扩展：pnpm -C extensions/collector build 通过
改 server：/api/health 200、涉及接口 curl/页面冒烟通过
UI 改动：浏览器实测 + 必要时截图确认

13 KiB Raw Blame History Unescape Escape