listing-report/fmode-image-set

Fmode Image Set

当前版本：0.9.0。终局评分升级为逐图矩阵与分层结果：仅有成品图即可给基础质量分，有商品参考和角色合同时再给商品一致性、合同适配与完整保障分；生成流程、Provider、7 个 MCP Tool、模板和生成提示词保持不变。

面向 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 增强
• 完成后或任意外部套图的只读终局评分：逐图 × rubric 矩阵、基础质量、参考一致性、角色合同适配、最差四分位惩罚、固定硬失败与源文件哈希保护

配置

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

$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。

安装

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

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

使用

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

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

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

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

独立终局评分

完整评分由 Skill 先实际打开全部成品图与可用商品原图，再把可定位证据通过 stdin 交给确定性 CLI；全程不调用 MCP、Provider 或网络，不读取凭据，也不回写图片或运行状态。可以检查本包生成目录，也可以检查任意外部套图。

下面的目录命令只产生文件/规格/集合结构的自动技术基线，overallScore 会保持 N/A；它不能替代完整视觉评分：

node skills/fmode-image-set-score/scripts/score-image-set.mjs "D:\待验收\套图A" --profile generic --format markdown
node skills/fmode-image-set-score/scripts/score-image-set.mjs --manifest - --base "D:\待验收\套图A" --format json

第二条命令要求从 stdin 传入 score-contract/v3 JSON。完整 quality 矩阵可独立给出 qualityScore；有商品参考时给 fidelityScore，有显式角色时给 contractFitScore，三层均具备资格后才给 assuredOverallScore。覆盖按逐图评分单元计算，单次模型审查最高为 medium 可信度。真实 CTR/CVR/ROAS 不由视觉模型预测，也不进入图片质量分。详见 skills/fmode-image-set-score/SKILL.md、references/visual-rubric.md 和 references/scoring-contract.md。内置 profile 是内部验收基线，不代表平台官方审核保证。

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 增强。

独立评分不注册 MCP Tool；它由第 8 个 Skill 自带的 CLI 执行，避免参与生成状态机。

输出

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

输出/商品套图/<商品名称>-<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，不得复制到普通用户输出。

测试与排障

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。