> 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 的图像契约为代理提供了一种稳定的方式来推理图像生成和本地图像检查，而无需将提示层绑定到单一提供方运行时。

## 范围

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

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

这一层被刻意设计为高层。现有的底层工具仍然负责其具体行为：

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

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

## `image_generation`

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

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

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

## `view_image`

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

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

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

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

## 提示指导

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

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

## 测试

该模块的 Rust 测试聚焦于：

* 用于以下内容的 JSON 模式结构： `image_generation`.
* 用于以下内容的 JSON 模式结构： `view_image`.
* 生成与本地查看的独立门控。
* 从配置到规范再到提示指导的端到端契约渲染。

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

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

与上面的高层 `image_generation` 契约 `src/openhuman/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-v1` 层级上，因此它可以检查自己生成的内容。
* **`video_agent`** (`delegate_create_video`）负责文生视频和图生视频。它会设定生成可能需要数分钟的预期，并阻塞直到剪辑保存完成。