---
title: 图像生成工具
created: 2026-05-07
updated: 2026-05-07
type: entity
tags: [tool, agent, backend, llm]
sources: [packages/backend/src/modules/netaclaw/tools/builtin/text_to_image.ts, packages/backend/src/modules/netaclaw/tools/builtin/image_to_image.ts, packages/backend/src/modules/netaclaw/image_providers/, packages/backend/src/modules/netaclaw/service/image_storage.ts, docs/superpowers/specs/2026-05-02-image-generation-tools-design.md]
---

# 图像生成工具

图像生成工具是 2026-05-03 新增的 AIGC 工具族，为 [[tool-system]] 增加 `text_to_image` 和 `image_to_image`。它支持火山引擎 Ark 与 MiniMax 图像模型，通过模型渠道配置读取 provider 凭据，并把生成结果持久化后返回给前端渲染。

## 工具

| 工具 | 文件 | 能力 |
| --- | --- | --- |
| `text_to_image` | `tools/builtin/text_to_image.ts` | 根据 prompt 生成图片，支持宽高比、尺寸、数量、水印、seed 和 provider 扩展参数 |
| `image_to_image` | `tools/builtin/image_to_image.ts` | 基于输入图片和 prompt 做图生图 |
| `image_common.ts` | `tools/builtin/image_common.ts` | 尺寸裁剪、结果持久化和工具返回格式 |

两者注册到 Tool Catalog 的 `aigc` toolset，能力标识为 `image_aigc`，`requiresModel: true`，因此最终可见性仍由 [[tool-governance]] 和 Agent 模型渠道配置决定。

## Provider 层

`image_providers/` 抽象了 provider 差异：

- `types.ts`：统一 `ImageGenerationProvider`、凭据、请求和错误类型。
- `ark.ts`：火山引擎 Ark 图像生成实现。
- `minimax.ts`：MiniMax 图像生成实现。

工具执行时会从模型渠道读取 supplier、baseUrl、apiKey 和 `extra.imageDefaults/imageConstraints`，再合并用户参数。provider 错误会被包装成可重试/不可重试的文本结果，避免直接把底层异常泄漏给模型。

## 结果持久化

`ImageStorageService` 负责把 URL/base64 图片结果落到后端可访问存储，并返回结构化结果。工具返回不再只是纯文本，而是可包含图片数组的 `rawResult`，由 [[frontend-architecture]] 的 renderer registry 决定展示方式。

## 与工具系统的关系

图像工具继承当前工具链路：

```text
Tool Catalog 注册
  -> Tool Governance 同步/启停
  -> ToolResolver 根据 Agent 和模型渠道注入
  -> runAgent 执行工具
  -> WebSocket 推送结构化 tool_result
  -> 前端 renderer 展示图片结果
```

这意味着排查“Agent 看不到图像工具”时，不应只看 `tools/builtin` 文件，还要检查 catalog 同步、工具治理、模型渠道是否支持 image provider。

## 相关页面

- [[tool-system]]
- [[tool-catalog]]
- [[tool-governance]]
- [[llm-providers]]
- [[frontend-architecture]]