> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/gong-neng/native-tools/image-tools.md).

# 图像工具

OpenHuman 的图像契约为代理提供了一种稳定的方式来推理图像生成和本地图像检查，而不会把提示词表面绑定到单一提供方运行时。

## 范围

该契约位于顶层 `crates/openhuman-core/src/media/image/` 模块中，目前涵盖两个面向模型的工具：

| 工具                 | 用途                     | 权限 | 输出          |
| ------------------ | ---------------------- | -- | ----------- |
| `image_generation` | 根据提示词生成或编辑栅格图像。        | 写入 | 本地生成媒体产物路径。 |
| `view_image`       | 将本地图像文件加载到模型可见的图像上下文中。 | 只读 | 模型可见的图像内容。  |

这一层有意保持高层抽象。现有的更底层工具仍然负责其具体行为：

* `image_info` 读取本地图像元数据和可选的 base64 文本。
* 代理的多模态准备会规范化 `[IMAGE:...]` 针对接受图像数据的提供方的标记。

图像层定义名称、模式、门控和提示规则，以便随着运行时增加直接支持，代理可以做出一致的决策。

## `image_generation`

`image_generation` 是托管提供方能力。Rust 核心不应在没有任何提供方支持时假装自己是图像渲染器。启用后，运行时应：

1. 验证任何 `input_image_path` 通过与图像查看相同的本地文件策略。
2. 将提示词和可选的编辑图像发送给托管图像提供方。
3. 将返回的字节持久化到会话作用域的 generated-media 根目录下，或保存到经批准的调用方提供的 `output_path`.
4. 返回已保存的产物路径，以便最终助手回答可以引用它们。

该 schema 包含 `提示词`，可选的 `output_path`，可选的 `尺寸`，可选的 `input_image_path`，以及 `输出格式` (`png`, `webp`, `jpeg`).

## `view_image`

`view_image` 从本地文件中加载像素到模型可见的上下文中。当文本元数据不足时使用它：截图、界面审查、OCR、图表、视觉差异以及生成图像检查。

运行时必须保持本地文件边界明确：

* 允许位于已批准工作区中的路径。
* 允许在当前会话期间创建的路径。
* 允许用户或受信任工具输出明确引用的路径。
* 拒绝策略之外的路径，并且不要静默附加无关的本地图像。

该 schema 包含 `路径` 以及可选的 `详细程度` (`自动`, `高`, `原始`）。仅在需要全分辨率检查时使用 `原始` 。

## 提示指导

只有在至少启用了一个媒体工具时，提示渲染才应包含图像指导。该指导应告知代理：

* 在需要像素内容时使用， `view_image` 而不是用于普通文件元数据。
* 在需要像素内容时使用， `image_generation` 用于所请求的栅格图像创建或编辑。
* 当目标位置重要时，提供输出路径。
* 在最终回答中提及生成的产物路径。
* 在将文件附加到模型上下文之前，遵守本地图像边界。

## 测试

该模块有针对以下内容的 Rust 定向测试：

* ……的 JSON Schema 结构 `image_generation`.
* ……的 JSON Schema 结构 `view_image`.
* 生成与本地查看的独立门控。
* 从配置到规范和提示指导的端到端契约渲染。

未来的运行时 PR 应该在运行时适配器旁边添加特定于提供方的执行测试，而不是放在托管契约模块中。

## 媒体生成（GMI）：图像和视频工具

与高层 `image_generation` 契约不同，该 `crates/openhuman-core/src/media/generation/` 领域提供 **已接线、可执行的** 通过 OpenHuman 后端的 `media_generation` 提供方（GMI Cloud：Seedream、SeedEdit、Seedance、Veo）。

| 工具                     | 用途                        | 权限 | 输出                                  |
| ---------------------- | ------------------------- | -- | ----------------------------------- |
| `media_generate_image` | 通过 GMI 进行文本到图像 / 图像到图像。   | 执行 | 位于以下目录下的本地文件路径： `generated-media/`. |
| `media_generate_video` | 通过 GMI 进行文本到视频 / 图像到视频。   | 执行 | 位于以下目录下的本地文件路径： `generated-media/`. |
| `media_list_models`    | 列出精选模型目录（以及可选的 GMI 实时列表）。 | 只读 | 模型 ID + 价格。                         |

工作方式：

* 生成是异步的。该工具将请求提交到后端（提交时计费并返回请求 ID），然后 **带着进度阻塞等待**，轮询直到请求进入终态。
* GMI 返回会过期的签名 URL；该工具将每个产物下载到代理的 `generated-media/` 目录中，并返回一个稳定的本地文件路径。
* 后端负责管理提供方密钥、计费和速率限制（`/agent-integrations/media-generation/*`，参见 `backend/docs/media-generation.md`).

### 图像与视频子代理

两个专门的子代理封装了这些工具，并可通过委派从编排器访问：

* **`image_agent`** (`delegate_create_image`）负责提示词设计、模型选择以及保存生成的图像。它运行在多模态 `vision` 工作负载路由层级上，因此可以检查自己生成的内容。
* **`video_agent`** (`delegate_create_video`）负责文本到视频和图像到视频。它会明确生成可能需要几分钟，并会阻塞直到剪辑保存完成。