Genarrative/docs/superpowers/plans/2026-06-16-editor-image-model-options.md

Editor Image Model Options Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 让图片画布的“生成角色形象”和“生成图标素材”支持 nanobanana2 与 gpt-image-2，并按模型提供合法的尺寸比例与大小尺寸选项。

Architecture: 前端抽出编辑器图片模型配置，生成面板只保存模型、比例、大小三个轻量状态；后端集中归一模型和尺寸组合，角色图与图标 spritesheet 继续走现有 VectorEngine、去背、OSS 和拆分链路。用户模型偏好用 localStorage 记住，默认 nanobanana2。

Tech Stack: React + TypeScript + Vitest；Rust Axum api-server；platform-image VectorEngine provider；Markdown 项目文档。

---

File Structure

• Modify C:\Genarrative\src\services\image-editor\editorProjectClient.ts
  • 扩展图片生成和图标 spritesheet 请求类型，加入 aspectRatio 与 imageSize。
  • 默认图标模型改为 gemini-3.1-flash-image-preview 对应的 nanobanana2。
• Modify C:\Genarrative\src\services\image-editor\editorProjectClient.test.ts
  • 先补失败测试：角色 / 图标请求会带模型、比例、大小。
• Modify C:\Genarrative\src\components\image-editor\ImageCanvasEditorView.tsx
  • 增加模型配置、选项归一、localStorage 偏好、角色 / 图标面板字段和提交 payload。
• Modify C:\Genarrative\src\components\image-editor\ImageCanvasEditorView.test.tsx
  • 先补失败测试：默认显示 nanobanana2，切换模型后比例 / 大小选项变更，并在请求中传递。
• Modify C:\Genarrative\server-rs\crates\platform-image\src\vector_engine\request.rs
  • 让 512 不被 normalize 成非法尺寸，并保留 gpt-image-2 尺寸。
• Modify C:\Genarrative\server-rs\crates\platform-image\tests\vector_engine.rs
  • 先补失败测试：nanobanana2 0.5K 请求 body 保留 512。
• Modify C:\Genarrative\server-rs\crates\api-server\src\editor_project.rs
  • 扩展请求 DTO，集中校验 nanobanana2 / gpt-image-2 与尺寸组合。
  • 角色生成按模型走 with_model 调用；图标生成按模型和组合选择尺寸。
• Modify docs:
  • C:\Genarrative\docs\【编辑器】画板角色形象生成入口设计-2026-06-15.md
  • C:\Genarrative\docs\【编辑器】画板图标素材生成入口设计-2026-06-15.md
  • C:\Genarrative\docs\technical\【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md

---

Task 1: Client request contract

Files:

• Modify: C:\Genarrative\src\services\image-editor\editorProjectClient.ts

• Test: C:\Genarrative\src\services\image-editor\editorProjectClient.test.ts

• Step 1: Write failing tests

Add tests asserting generateEditorImage and generateEditorIconSpritesheet serialize model, aspectRatio, and imageSize when supplied.

• Step 2: Run test to verify failure

Run: npm run test -- src/services/image-editor/editorProjectClient.test.ts -t "image model options" Expected: FAIL because payloads do not include aspectRatio / imageSize.

• Step 3: Minimal implementation

Extend input types and JSON body builders to include optional aspectRatio and imageSize; change icon default model constant to gemini-3.1-flash-image-preview if not already.

• Step 4: Verify green

Run same test command. Expected: PASS.

Task 2: Frontend panel state and local preference

Files:

• Modify: C:\Genarrative\src\components\image-editor\ImageCanvasEditorView.tsx

• Test: C:\Genarrative\src\components\image-editor\ImageCanvasEditorView.test.tsx

• Step 1: Write failing tests

Add tests for:

1. opening 生成角色形象 defaults to model nanobanana2 and shows 尺寸比例 / 大小尺寸;
2. switching to gpt-image-2 limits visible combinations and submits model + mapped size metadata;
3. icon spritesheet defaults to nanobanana2 and submits the chosen model.

• Step 2: Run test to verify failure

Run: npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx -t "模型|尺寸比例|大小尺寸" Expected: FAIL because current UI has placeholder model button only.

• Step 3: Minimal implementation

Add model option config, dialog fields imageModel/aspectRatio/imageSize, localStorage helpers, option buttons/selects, and submit payload wiring.

• Step 4: Verify green

Run same test command. Expected: PASS.

Task 3: Backend model and dimension normalization

Files:

• Modify: C:\Genarrative\server-rs\crates\platform-image\src\vector_engine\request.rs

• Modify: C:\Genarrative\server-rs\crates\api-server\src\editor_project.rs

• Test: C:\Genarrative\server-rs\crates\platform-image\tests\vector_engine.rs

• Test: existing unit tests inside editor_project.rs

• Step 1: Write failing tests

Add tests covering:

1. build_vector_engine_image_request_body_with_model("gemini-3.1-flash-image-preview", ..., "512", ...) keeps size = "512".
2. editor character model normalization defaults to nanobanana2 and maps gpt-image-2 + 2:3 + 1K to 1024x1536.
3. icon spritesheet model normalization accepts both models.

• Step 2: Run backend tests to verify failure

Run: cargo test -p platform-image --manifest-path server-rs/Cargo.toml vector_engine_request_body_can_use_nanobanana2_half_k -- --nocapture cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_project -- --nocapture Expected: FAIL until normalization functions exist.

• Step 3: Minimal implementation

Add constants and helpers:

• EDITOR_IMAGE_MODEL_NANOBANANA2 = "gemini-3.1-flash-image-preview"

• EDITOR_IMAGE_MODEL_GPT_IMAGE_2 = "gpt-image-2"

• normalize_editor_image_model

• normalize_editor_generation_dimensions Use with_model calls for character and icon generation responses.

• Step 4: Verify green

Run the same backend tests. Expected: PASS.

Task 4: Documentation and final checks

Files:

• Modify docs listed above.

• Step 1: Update docs

Document defaults, user preference, model-specific options, and Apifox source URLs.

• Step 2: Run focused verification

Run: npm run test -- src/services/image-editor/editorProjectClient.test.ts src/components/image-editor/ImageCanvasEditorView.test.tsx cargo test -p platform-image --manifest-path server-rs/Cargo.toml vector_engine_request_body_can_use_nanobanana2_half_k -- --nocapture cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_project -- --nocapture npm run typecheck -- --pretty false npm run check:encoding

---

Self-Review

• Spec coverage: covers role generation, icon spritesheet generation, default model, user preference, model-specific dimensions, docs.
• Placeholder scan: no unresolved placeholders.
• Type consistency: frontend uses model/aspectRatio/imageSize; backend DTO mirrors camelCase fields.