GPU_GUARD_MONOREPO/docs/superpowers/specs/2026-05-02-image-generation-tools-design.md

# 文生图与图生图工具设计

> 日期：2026-05-02
> 状态：待实施
> 范围：后端工具层、图片 Provider 层、前端工具渲染、Prompt Builder

## 1. 背景与目标

系统已在模型渠道中配置了火山引擎和 MiniMax 的图片生成模型。需要在 Agent 对话中提供文生图和图生图能力，主要面向电商场景（产品主图、详情图、文章配图），并支持配置专用电商套图 Agent 一次性生成成套图片。

### 目标

- 新增 `text_to_image` 和 `image_to_image` 两个独立工具
- 建立可扩展的图片生成 Provider 层，当前支持火山引擎和 MiniMax，未来可扩展其他渠道
- 扩展 `ToolResultContent` 支持多图返回
- 前端 tool-card 支持单图/多图渲染
- 生成图片转存本地，解决 Provider 临时 URL 过期问题
- Prompt Builder 根据可用工具动态生成附件提示语

### 不做

- 不改造 LLM Provider 层（图片生成走独立工具，不走 chat completions）
- 不新增附件上传能力（现有机制已满足图生图的参考图传递）
- 不做图片编辑器 UI（生成结果在 tool-card 内渲染和预览）

## 2. 架构总览

```
packages/backend/src/modules/netaclaw/
├── image_providers/                    # 新增：图片生成 Provider 层
│   ├── types.ts                        # 统一接口、凭证、错误类型、工厂函数
│   ├── ark.ts                          # 火山引擎（OpenAI SDK images.generate）
│   └── minimax.ts                      # MiniMax（自有 REST API）
├── tools/
│   ├── common.ts                       # 修改：新增 images 类型
│   ├── catalog.ts                      # 修改：注册两个新工具
│   └── builtin/
│       ├── text_to_image.ts            # 新增：文生图工具
│       └── image_to_image.ts           # 新增：图生图工具
├── service/
│   ├── tool_resolver.ts                # 修改：注入凭证和 provider
│   └── image_storage.ts               # 新增：图片转存本地服务
└── runtime/
    └── prompt_builder.ts               # 修改：附件提示语扩展

packages/frontend/src/modules/agent/
├── tools/renderer-registry.ts          # 修改：rawResult 新增 images 类型
└── components/tool-card.vue            # 修改：单图/多图渲染
```

## 3. Provider 层

### 3.1 统一接口

```typescript
// image_providers/types.ts

export interface ImageProviderCredentials {
  baseUrl: string;
  apiKey: string;
  supplier: string;
  modelId: string;
  promptHint: string | null;
  extra?: ToolGovernanceExtra | null;
}

export interface TextToImageParams {
  prompt: string;
  width?: number;
  height?: number;
  aspectRatio?: string;
  n?: number;
  responseFormat?: 'url' | 'base64';
  watermark?: boolean;
  seed?: number;
  extra?: Record<string, unknown>;
}

export interface ImageToImageParams extends TextToImageParams {
  referenceImage: string;
  strength?: number;
}

export interface ImageGenerationResult {
  images: { url?: string; base64?: string; width?: number; height?: number }[];
  model: string;
  provider: string;
}

export interface ImageGenerationProvider {
  readonly id: string;
  textToImage(params: TextToImageParams, creds: ImageProviderCredentials): Promise<ImageGenerationResult>;
  imageToImage(params: ImageToImageParams, creds: ImageProviderCredentials): Promise<ImageGenerationResult>;
}

export class ImageGenerationError extends Error {
  constructor(
    message: string,
    public readonly code: 'content_safety' | 'rate_limit' | 'insufficient_balance' |
                          'invalid_params' | 'timeout' | 'network' | 'unknown',
    public readonly retryable: boolean,
  ) {
    super(message);
  }
}
```

### 3.2 Provider 路由

supplier + baseUrl 联合路由，解决火山引擎 supplier 可能配为 "OpenAI" 的问题：

```typescript
export function getImageProvider(supplier: string, baseUrl: string): ImageGenerationProvider | null {
  const s = supplier.toLowerCase();
  if (s === 'minimax') return providers.get('minimax')!;
  if (s === 'ark' || s === 'volcengine') return providers.get('ark')!;
  if (s === 'openai') {
    if (baseUrl.includes('volces.com') || baseUrl.includes('volcengine')) return providers.get('ark')!;
    if (baseUrl.includes('minimax')) return providers.get('minimax')!;
  }
  return null;
}
```

### 3.3 火山引擎实现 (ark.ts)

- 使用 OpenAI SDK `client.images.generate()`
- 尺寸通过 `size` 字段传递（如 `"1024x1024"`、`"2K"`）
- 图生图通过 `extra_body.image` 传参考图
- 特有参数（watermark 等）通过 `extra_body` 透传
- 60 秒超时保护

### 3.4 MiniMax 实现 (minimax.ts)

- 使用自有 REST API `POST {baseUrl}/v1/image_generation`
- 尺寸通过 `aspect_ratio` 或 `width + height` 传递
- 图生图通过 `subject_reference` 字段传参考图
- 特有参数：`style`（画风）、`prompt_optimizer`（prompt 优化）通过 `extra` 透传
- 响应从 `data.image_urls[]` 归一化到统一结构
- Bearer token 认证
- 60 秒超时保护

### 3.5 扩展新渠道

新增 Provider 只需：
1. 在 `image_providers/` 下新建文件，实现 `ImageGenerationProvider` 接口
2. 在工厂函数 `getImageProvider` 中注册路由规则

## 4. 工具层

### 4.1 text_to_image

```typescript
// tools/builtin/text_to_image.ts

const Params = Type.Object({
  prompt: Type.String({ description: '图片描述，尽量详细具体' }),
  aspectRatio: Type.Optional(Type.String({
    description: '宽高比。可选: 1:1, 16:9, 4:3, 3:2, 2:3, 3:4, 9:16',
  })),
  width: Type.Optional(Type.Integer({ description: '精确宽度（像素），优先级低于 aspectRatio' })),
  height: Type.Optional(Type.Integer({ description: '精确高度（像素）' })),
  n: Type.Optional(Type.Integer({ description: '生成数量，默认 1，最大 9', minimum: 1, maximum: 9 })),
  watermark: Type.Optional(Type.Boolean({ description: '是否添加水印' })),
  seed: Type.Optional(Type.Integer({ description: '随机种子，相同 seed 可复现相近结果' })),
  extra: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
    description: 'Provider 特有参数，如 MiniMax 的 style、prompt_optimizer',
  })),
});

registerSchema({
  name: 'text_to_image',
  toolset: 'vision',
  description: '根据文字描述生成图片，支持指定尺寸、数量、风格等参数。',
  capability: 'multimodal',
  visibility: 'tool',
  isCore: false,
  canDisable: true,
  supportsPromptHint: true,
  requiresModel: true,
});
```

工具描述会拼接 `promptHint`，管理员可在后台配置行业特定的默认提示词。

### 4.2 image_to_image

```typescript
// tools/builtin/image_to_image.ts

const Params = Type.Object({
  prompt: Type.String({ description: '对参考图的修改描述' }),
  referenceImage: Type.String({ description: '参考图片 URL（从用户上传附件获取）' }),
  strength: Type.Optional(Type.Number({
    description: '参考图影响强度 0-1，越大越接近原图', minimum: 0, maximum: 1,
  })),
  aspectRatio: Type.Optional(Type.String({ description: '宽高比' })),
  width: Type.Optional(Type.Integer({ description: '精确宽度（像素）' })),
  height: Type.Optional(Type.Integer({ description: '精确高度（像素）' })),
  n: Type.Optional(Type.Integer({ description: '生成数量，默认 1，最大 9', minimum: 1, maximum: 9 })),
  watermark: Type.Optional(Type.Boolean({ description: '是否添加水印' })),
  seed: Type.Optional(Type.Integer({ description: '随机种子' })),
  extra: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
    description: 'Provider 特有参数',
  })),
});

registerSchema({
  name: 'image_to_image',
  toolset: 'vision',
  description: '基于参考图片生成新图片，支持风格迁移、内容编辑等。传入参考图URL和修改描述。',
  capability: 'multimodal',
  visibility: 'tool',
  isCore: false,
  canDisable: true,
  supportsPromptHint: true,
  requiresModel: true,
});
```

### 4.3 tool_resolver 集成

两个工具在 tool_resolver 中的注入逻辑与 `image_recognize` 对称：

1. 检查 `filteredNames` 是否包含工具名
2. 从 `toolRegistry.getToolModelConfig()` 获取模型渠道配置
3. 从 `modelChannelService.resolveForAgent()` 解析凭证
4. 通过 `getImageProvider(supplier, baseUrl)` 获取 provider 实例
5. 创建工具实例，注入 creds 和 provider
6. 未配置时写入 `disabledReasons`

两个工具可以绑定不同的模型渠道（如文生图用火山引擎，图生图用 MiniMax）。

## 5. 多图返回

### 5.1 后端类型扩展

```typescript
// tools/common.ts

export interface ImageItem {
  url: string;
  mimeType?: string;
  width?: number;
  height?: number;
  seed?: number;
}

export type ToolResultContent =
  | { type: 'text'; text: string }
  | { type: 'json'; data: unknown }
  | { type: 'image'; url: string; mimeType?: string; text?: string;
      width?: number; height?: number; bytes?: number;
      originalWidth?: number; originalHeight?: number;
      originalBytes?: number; resized?: boolean; }
  | { type: 'images'; images: ImageItem[]; text?: string };

export function imagesResult(images: ImageItem[], text?: string): ToolResultContent {
  return { type: 'images', images, text };
}
```

### 5.2 toolResultToText 扩展

```typescript
if (value.type === 'images') {
  const lines = value.images.map((img, i) =>
    `[图${i + 1}] ${img.url}${img.width && img.height ? ` (${img.width}x${img.height})` : ''}`
  );
  const header = value.text || `已生成 ${value.images.length} 张图片`;
  return `${header}\n${lines.join('\n')}`;
}
```

### 5.3 返回策略

- 单图（n=1）：返回 `type: 'image'`，向后兼容
- 多图（n>1）：返回 `type: 'images'`，前端网格渲染

## 6. 图片转存

### 6.1 问题

MiniMax URL 有效期 24 小时，火山引擎类似。历史会话中图片会失效。

### 6.2 方案

新增 `service/image_storage.ts`，工具 execute 完成后立即将临时 URL 下载并转存到本地存储：

```typescript
export class ImageStorageService {
  async persist(tempUrl: string, metadata?: { toolName: string }): Promise<string> {
    const response = await fetch(tempUrl);
    const buffer = Buffer.from(await response.arrayBuffer());
    const ext = this.detectExtension(response.headers.get('content-type'));
    const filename = `${Date.now()}-${randomUUID().slice(0, 8)}${ext}`;
    // 复用现有文件存储基础设施写入本地
    return await this.fileService.saveBuffer(buffer, filename);
  }
}
```

工具内部在 provider 返回后、构造 ToolResultContent 前执行转存，session tree 中存储的是永久本地 URL。

## 7. 前端渲染

### 7.1 renderer-registry 扩展

`ToolRenderSource.rawResult` 新增 `images` 类型：

```typescript
rawResult?: {
  type: 'text' | 'json' | 'image' | 'images';
  // 现有字段...
  images?: { url: string; mimeType?: string; width?: number; height?: number; seed?: number }[];
};
```

### 7.2 message-item.vue 渲染

当前 `message-item.vue` 已有 `rawResult.type === 'image'` 的单图渲染（`<img>` 标签）。需要：

- 将单图渲染升级为 `el-image`，支持点击预览大图
- 新增 `rawResult.type === 'images'` 分支，CSS Grid 网格布局，`el-image` 预览列表联动
- 其他类型保持原有 `<pre>` 文本渲染

多图网格样式：`grid-template-columns: repeat(auto-fill, minmax(140px, 1fr))`，自适应列数。

## 8. Prompt Builder 扩展

### 8.1 改动

`buildLLMMessages` 新增 `toolNames` 参数，附件提示语根据 Agent 实际可用工具动态生成：

- 有 `image_recognize` → 提示"如需分析图片内容，请使用 image_recognize 工具"
- 有 `image_to_image` → 提示"如需基于图片生成新图片，请使用 image_to_image 工具，将图片 URL 作为 referenceImage 参数"
- 两者都有 → 两条提示都输出

避免提到 Agent 没有的工具。

## 9. 错误处理

Provider 层统一抛出 `ImageGenerationError`，包含错误码和是否可重试标记：

| 错误码 | 含义 | 可重试 | Agent 可见信息 |
|--------|------|--------|--------------|
| content_safety | 内容安全拦截 | 否 | "提示词触发内容安全策略，请调整描述" |
| rate_limit | 限流 | 是 | "当前请求过多，请稍后重试" |
| insufficient_balance | 余额不足 | 否 | "模型渠道余额不足" |
| invalid_params | 参数错误 | 否 | 具体参数错误信息 |
| timeout | 超时（60s） | 是 | "生成超时，可尝试降低图片尺寸" |
| network | 网络错误 | 是 | "网络连接失败" |

工具层捕获后返回结构化错误文本，Agent 可据此决策（换 prompt 重试或告知用户）。

## 10. 工具参数控制权

### 10.1 问题

图片生成工具的参数（n、aspectRatio、watermark、width/height 等）存在三个来源：

| 来源 | 设置者 | 例子 |
|------|--------|------|
| 工具管理页 `extra` | 管理员 | 默认 n=1、watermark=true |
| Agent 系统 prompt | 管理员 | "电商主图用 1:1" |
| Agent 运行时 tool_use | Agent（响应用户） | `{ n: 4, aspectRatio: "16:9" }` |

如果管理员在工具管理页设置了 n=1，但用户说"生成 4 张"，Agent 传了 n=4，应该听谁的？

### 10.2 设计原则：Agent 决策优先，管理员设默认值

参数分为两类：

**默认值参数（Agent 可覆盖）**：`n`、`aspectRatio`、`width`、`height`、`watermark`、`seed`、`responseFormat`

管理员在工具管理页的 `extra` 字段中配置默认值。Agent 不传时用默认值，Agent 传了则以 Agent 为准。这些参数在工具编辑页可查看可编辑，标注"默认值，Agent 可覆盖"。

**约束参数（Agent 不可突破）**：`maxN`、`maxWidth`、`maxHeight`

管理员设置硬上限，工具 execute 内部做 clamp。防止 Agent 被用户诱导生成过多或过大图片导致成本失控。这些参数在工具编辑页可查看可编辑，标注"硬上限"。

### 10.3 extra 字段结构

扩展 `netaclaw_tool.extra`，图片工具新增：

```typescript
// ToolGovernanceExtra 扩展
export type ToolGovernanceExtra = {
  allowInSubagent?: boolean;
  workerRoutingStrategy?: ToolWorkerRoutingStrategy;
  // 图片工具新增
  imageDefaults?: {
    n?: number;
    aspectRatio?: string;
    width?: number;
    height?: number;
    watermark?: boolean;
    responseFormat?: 'url' | 'base64';
  };
  imageConstraints?: {
    maxN?: number;          // 默认 9
    maxWidth?: number;      // 默认 2048
    maxHeight?: number;     // 默认 2048
  };
};
```

### 10.4 工具 execute 内部合并逻辑

```typescript
async execute(_id, params) {
  const defaults = creds.extra?.imageDefaults ?? {};
  const constraints = creds.extra?.imageConstraints ?? {};

  const merged = {
    prompt: params.prompt,
    n: Math.min(params.n ?? defaults.n ?? 1, constraints.maxN ?? 9),
    aspectRatio: params.aspectRatio ?? defaults.aspectRatio,
    width: clamp(params.width ?? defaults.width, constraints.maxWidth ?? 2048),
    height: clamp(params.height ?? defaults.height, constraints.maxHeight ?? 2048),
    watermark: params.watermark ?? defaults.watermark ?? false,
    // ...
  };

  const result = await provider.textToImage(merged, creds);
  // ...
}
```

### 10.5 前端工具编辑页

工具编辑抽屉中，当工具名为 `text_to_image` 或 `image_to_image` 时，在模型配置区域下方新增"图片生成配置"区块：

```
┌─ 图片生成配置 ──────────────────────────────┐
│                                              │
│  默认值（Agent 可覆盖）                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│  │ 数量: 1  │ │ 比例: 1:1│ │ 水印: ☑     │ │
│  └──────────┘ └──────────┘ └──────────────┘ │
│                                              │
│  硬上限                                       │
│  ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│  │最大数量:9│ │最大宽:2048│ │最大高:2048   │ │
│  └──────────┘ └──────────┘ └──────────────┘ │
│                                              │
│  ⓘ 默认值在 Agent 未指定时生效，Agent 可根据   │
│    用户指令覆盖。硬上限不可突破。               │
└──────────────────────────────────────────────┘
```

## 11. 专用电商套图 Agent

通过管理后台 Agent 编辑页配置：

- **系统 Prompt**：电商视觉设计领域知识（平台尺寸规范、构图原则、套图工作流）
- **工具集**：`text_to_image` + `image_to_image` + `image_recognize` + `todo`
- **maxToolRounds**：30（套图需要多轮工具调用）
- **promptHint**：各工具在后台配置行业特定的默认提示词
- **imageDefaults**：工具管理页配置电商常用默认值（如 aspectRatio: "1:1"、watermark: false）
- **imageConstraints**：设置 maxN 防止成本失控

典型流程：用户描述产品 → Agent 规划套图方案 → 逐张生成 → 如有参考图则用图生图 → 汇总输出。

## 12. 完整改动清单

| 层 | 文件 | 改动类型 |
|----|------|---------|
| Provider | `image_providers/types.ts` | 新增 |
| Provider | `image_providers/ark.ts` | 新增 |
| Provider | `image_providers/minimax.ts` | 新增 |
| 工具 | `tools/common.ts` | 修改 |
| 工具 | `tools/builtin/text_to_image.ts` | 新增 |
| 工具 | `tools/builtin/image_to_image.ts` | 新增 |
| 注册 | `tools/catalog.ts` | 修改 |
| 治理 | `tools/manifest.ts` | 修改（ToolGovernanceExtra 扩展） |
| 解析 | `service/tool_resolver.ts` | 修改 |
| 存储 | `service/image_storage.ts` | 新增 |
| Prompt | `runtime/prompt_builder.ts` | 修改 |
| 前端 | `tools/renderer-registry.ts` | 修改 |
| 前端 | `components/message-item.vue` | 修改（图片渲染升级 + 多图支持） |
| 前端 | `views/tools.vue` | 修改（图片生成配置区块） |