# Fmode Image Set

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

## 能力

- 商品可见事实、包装、颜色、材质、Logo、文字和风格分析
- 25 类双语电商模板与平台/行业路由
- 精简七图和 H1-H5/M1-M9 完整十四图预设
- 主图、副图、详情页、多角度、广告和社媒视觉
- 商品身份锁、颜色锁、风格锁、本地主图 Data URL 锚点和 Gemini 生成后质量复核
- 计划/付费执行分离、gateway-unit 预算上限、幂等、停止和部分完成保护
- 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
分析这张商品图，先规划七张套图，不要生图。
```

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

## MCP Tools

- `fmode_image_set_analyze`：Gemini 商品识图。
- `fmode_image_set_plan`：套图规划、模型选择和人民币预算预留。
- `fmode_image_set_templates`：查询模板和预设。
- `fmode_image_set_generate`：确认后付费生成并接收 Base64 结果。
- `fmode_image_set_status`：读取本地运行状态。
- `fmode_image_set_edit`：Gemini/Seedream 图像编辑。
- `fmode_image_set_upscale`：Seedream 高质量 2K 增强。

## 输出

运行结果写入调用方项目：

```text
outputs/fmode-image-set/<run_id>/
```

`state.json` 保存脱敏状态，图片以绝对路径返回。输出根目录固定，Tool 调用不能改写工作区或输出根路径。

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

## 费用与安全

- 识图会使用 Gemini 配额；模板查询和本地规划不调用外部模型。
- 生成、编辑和 2K 增强必须显式 `confirmed: true` 并提供人民币字段 `budgetLimitCny`。
- Seedream 已验证固定价为 0.03 USD/张；Gemini 按量计费，使用 0.10 USD/生成和 0.01 USD/识图或质检的保守预留。两者统一按网关 `usd_exchange_rate=6.8` 换算为人民币。
- 预算会按受信美元价格和 USD/CNY 汇率重新计算，不采信计划中可修改的费用字段。
- 网络中断或响应无法解析时返回 `submission_unknown`，不会自动切换模型或重提。
- 第一张通过 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`。