# Fmode Image Set

> 当前版本：`0.6.0`。在 `0.5.0` 基线上，将计划确认交接升级为跨 MCP 重启、工作区/会话/精确计划绑定的加密 `planToken`；图像质量、模板、Provider 与生成提示词保持不变。

面向 VSCode Claude Code 的商品套图设计包：用 `gemini-3.1-flash-image-preview` 分析商品图和检查质量，先生成可确认的套图计划，再通过 New API 的 Gemini 或 `doubao-seedream-4-0-250828` 生图。需要 Node.js 20.11 或更高版本。

## 能力

- 商品可见事实、包装、颜色、材质、Logo、文字和风格分析
- 对话中显式粘贴项目内商品图路径；不依赖 VSCode 图片上传或目录扫描
- 25 类双语电商模板与平台/行业路由
- 淘宝/天猫、京东、拼多多独立商品图片资产规则；官方证据不足时明确安全降级，不冒充平台合规
- 精简七图和 H1-H5/M1-M9 完整十四图预设
- 主图、副图、详情页、多角度、广告和社媒视觉
- 商品身份锁、颜色锁、风格锁、本地主图 Data URL 锚点和 Gemini 生成后质量复核
- 国内平台生成结果的 PNG/JPEG/WebP 真实像素、比例、透明通道和规则状态检查
- 套图内 `quality_rejected` 单图返修自动归位原运行目录，使用版本化文件名并更新原套图状态
- 计划/执行分离、短期计划引用稳定衔接、单图临时异常最多三次自动尝试、失败不阻断后续图片、原 run 指定项续跑
- Gemini 高质量默认生图、Seedream 2K 备选生图、两模型编辑和 Seedream 2K 增强

## 配置

不要把真实密钥写入仓库。至少为 Claude Code/MCP 进程配置：

```powershell
$env:FMODE_LLM_BASE_URL="http://server.fmode.cn:9999"
$env:FMODE_LLM_API_KEY="<your-new-api-key>"
$env:FMODE_ALLOW_INSECURE_HTTP="true" # 仅在确认信任该内网 HTTP 网关时
```

也兼容 `LLM_BASE_URL` 与 `LLM_API_KEY`。优先使用 HTTPS；远程 HTTP 默认阻断，必须显式授权。可选成本预留变量见 `.env.example`。

## 安装

```powershell
npm ci
node install.js --check
node bin/fmode-image-set.js workspace --smoke
```

工作区安装会复制完整包和七个 Skill、合并 `.mcp.json`，并把 MCP 路径改写为安装副本的绝对路径。安装后重启 Claude Code 会话。

## 使用

```text
D:\项目\商品正面.png、D:\项目\参考图\商品背面.jpg 是 MORI 咖啡的商品图，先规划七张套图，不要生图。
```

```text
采用刚才确认的高质量模型计划生成，confirmed=true。

继续原任务，只重试 D4，不要重新规划或生成已完成图片。
```

国内平台必须明确传入 `platform=淘宝/天猫/京东/拼多多`。计划中的 `platformRule` 会显示资产用途、目标规格、证据状态和风险提醒；京东、拼多多当前缺少可公开核验的通用图片数值时使用保守建议，不能描述为官方审核保证。

## MCP Tools

- `fmode_image_set_analyze`：Gemini 商品识图。
- `fmode_image_set_plan`：套图规划和模型选择，不向用户展示生成费用；传入 `sessionId + promptId` 时返回跨重启有效的加密 `planToken`，并保留旧 `planRef`。
- `fmode_image_set_templates`：查询模板和预设。
- `fmode_image_set_generate`：确认后以 `planToken + confirmedPlanId + 同一 sessionId` 精确执行并接收 Base64 结果；兼容旧 `planRef`、完整 plan 和原 run 指定 outputId 续跑。
- `fmode_image_set_status`：读取本地运行状态。
- `fmode_image_set_edit`：Gemini/Seedream 图像编辑；受管理套图中的当前质量拒绝项会原位返修，普通图片仍创建独立编辑运行。
- `fmode_image_set_upscale`：Seedream 高质量 2K 增强。

## 输出

新运行结果写入调用方项目的中文目录：

```text
输出/商品套图/<商品名称>-<8位短请求标识>/
```

`state.json` 保存脱敏状态，图片以绝对路径返回。完整成功后，项目根直属商品图移动到运行目录的 `商品原图/`，项目子目录商品图复制到该目录，并在结果中逐项报告。部分完成、失败、质量拒绝或 `submission_unknown` 不移动项目根原图。旧 `outputs/fmode-image-set/run_*` 继续支持状态读取，但不再用于新运行。

输出根目录固定，Tool 调用不能改写工作区或输出根路径。

完整目录契约见 `docs/directory-layout.md`。正常流程不会在项目根目录创建 `.tmp-*`；自动测试临时文件统一位于系统 Temp。

## 确认、恢复与安全

- 模板查询和本地规划不调用外部模型；生成、编辑和 2K 增强必须显式 `confirmed: true`。
- 同一商品的多张路径可一次传入并设置 `allImagesSameProduct=true`；混合参考图才需要逐张角色映射。
- `planToken` 是 AES-256-GCM 加密的短期自包含计划载体，绑定工作区摘要、规划会话和精确 `planId`，不落盘且不替代用户确认；MCP 重启后仍可执行。它用于防止误串台，但当前 MCP 的 `sessionId` 由调用方提供，不能宣称为宿主级不可伪造身份。旧 `planRef` 仅作同进程兼容。
- 普通用户计划、状态和总结不展示预计、累计或实际费用。内部仍保留可信安全上限；`budgetLimitCny` 只作为旧调用兼容字段。
- 单图网络中断、临时网关异常或响应无法解析时，使用稳定幂等键最多自动尝试三次；仍失败则继续后续图片，不自动切换模型。
- 已取得远程结果 URL 时只重试下载，不重新生成。执行结束后列出失败 outputId，用户确认后以原 `runId + retryOutputIds` 续跑。
- 已完成图片是稳定资产：失败恢复不得重新识图、规划或生成已完成项。
- 第一张通过 Gemini 质检后，以本地 Data URL 作为后续图片的身份锚点。
- 单次最多 14 张；换模型、扩容或改变设计目标必须重新规划并确认。

开发者内部安全上限口径见 `docs/cost-model.md`，不得复制到普通用户输出。

## 测试与排障

```powershell
npm test
npm run smoke:package
npm run mcp:smoke
npm run acceptance:installer
npm run acceptance
```

详见 `docs/customer-quickstart.md`、`docs/live-manual-acceptance-checklist.md` 和 `docs/troubleshooting.md`。