尧图网站建设 
OpenHuman Image Tools 全解析image_generation 与 view_image 的模型层契约设计与 GMI 媒体生成实战【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman本篇文章深入解析 OpenHuman 的 Image Tools 架构它如何在模型与运行时之间建立一套与具体提供商无关的稳定契约让 Agent 可以一致地完成图像生成image_generation与本地图像查看view_image同时梳理已接入后端media_generation提供商GMI CloudSeedream、SeedEdit、Seedance、Veo的可实际执行的图片/视频生成工具。读完你将掌握两个核心契约的 JSON Schema 与权限模型、运行时门控gating策略、Prompt 指南的渲染规则以及 GMI 异步生成工具「提交—轮询—落盘」的完整实现链路。一、为什么需要「图像工具契约层」OpenHuman 的定位是本地优先的跨平台Mac / Windows / Linux个人 AI。在其 Agent 运行时中图像能力天然分为两类诉求生成/编辑位图需要托管提供商与把本地图片像素加载进模型上下文纯本地只读。如果把这两类能力直接绑定到某个具体的提供商运行时会让 Prompt 表面prompt surface随提供商切换而漂移Agent 无法稳定决策。因此OpenHuman 在顶层 src/openhuman/media/image/ 模块中定义了一个高层契约层。正如模块注释mod.rs所述该层不直接执行图像生成或像素检查而是定义稳定的工具名称、JSON Schema、门控gating规则与 Prompt 指南供具备图像能力的运行时/提供商适配器按需暴露。契约层当前覆盖两个模型可见工具工具用途权限输出image_generation根据 Prompt 生成或编辑位图图像Write写本地 generated-media 产物路径view_image将本地图像文件加载进模型可见的图像上下文Read-only只读模型可见的图像内容该层刻意保持高层抽象底层具体行为仍由既有底层工具负责image_info读取本地图像元数据与可选的 base64 文本模块说明Agent 多模态准备为接受图像数据的提供商规范化[IMAGE:...]标记浏览器snapshot暴露结构化 DOM 与无障碍内容不捕获页面像素。契约层只定义名称、Schema、门控与 Prompt 规则让运行时在逐步接入直接支持时Agent 能保持一致决策而无需在工具注册表中重复实现业务逻辑。模块结构src/openhuman/media/image/ 目录结构清晰文件职责mod.rs导出型模块入口统一重导出契约符号types.rs共享描述符、权限/配置类型与门控辅助函数image_generation.rsimage_generationSchema 与输出格式契约image_view.rsview_imageSchema 与 detail 级别契约prompt.rs面向 Agent 的图像工具 Prompt 指南渲染image_tests.rs覆盖配置、Schema 与 Prompt 输出的契约级端到端测试二、image_generation托管式图像生成契约image_generation是一个托管提供商能力。Rust 核心不应在没有任何提供商支持时伪装成图像渲染器。契约源码image_generation.rs将其建模为ImageToolSpec名称固定为image_generation权限为ImagePermission::Writewrites_files: truemodel_visible_image_output: false输出是文本路径而非图像内容本身。运行时应当遵循的四步流程当能力启用时运行时应当校验input_image_path与图像查看共用同一套本地文件策略即只有已批准工作区、当前会话创建、用户或可信工具显式引用的路径才合法发送 Prompt 与可选编辑图给托管图像提供商持久化返回的字节写入会话作用域的 generated-media 根目录或写入经批准的调用方指定output_path返回已保存的产物路径供最终助手回答引用这些具体文件。参数 Schema该工具的参数为 JSON Schema object仅prompt为必填参数类型说明promptstring必填面向托管图像模型的详细视觉 Prompt 或编辑指令output_pathstring可选工作区相对或已批准的绝对输出路径省略时由运行时选择 generated-media 路径sizestring可选输出尺寸如1024x1024、1536x1024或提供商默认值input_image_pathstring可选的待编辑本地图像路径运行时必须在校验本地文件访问后才可附加output_formatstring枚举持久化文件格式png、webp、jpeg默认值来自运行时的ImageGenerationOutputFormat配置output_format的合法值与序列化由 ImageGenerationOutputFormat 枚举 保证#[serde(rename_all snake_case)]对应png/webp/jpeg。三、view_image把本地像素送进模型上下文view_image把本地文件中的像素加载进模型可见上下文。契约源码image_view.rs中model_visible_image_output: true、writes_files: false、权限为ImagePermission::ReadOnly——它只读不写。适用场景当纯文本元数据不足以支撑推理时使用截图分析、UI 审查、OCR、图表/示意图理解、视觉差异对比、生成图像自检等。本地文件边界必须显式运行时必须保持本地文件边界清晰仅允许已批准工作区approved workspace内的路径当前会话期间创建的路径用户或可信工具输出显式引用的路径拒绝策略之外的路径且不得静默附加无关的本地图像。参数 Schema参数类型说明pathstring必填本地图像路径绝对路径或相对于已批准工作区detailstring枚举默认auto检查细节级别auto、high、original仅在需要全分辨率检查时使用originaldetail的三档取值由 ImageDetail 枚举 定义默认值为auto。四、能力门控ImageToolConfig与image_specs契约层将「哪些图像工具对会话可见」收敛到ImageToolConfigtypes.rs它包含五个开关字段含义image_generation_enabled运行时是否支持托管图像生成image_view_enabled运行时是否支持本地图像附加/查看image_generation_output_format生成图像的期望输出格式默认Pnglocal_image_reads_allowed当前文件系统策略是否允许工作区图像读取默认truegenerated_image_writes_allowed是否允许在配置的输出根目录下写入生成文件默认true关键设计是独立门控image_specs(config)types.rs只在「生成启用且允许写入」时暴露image_generation只在「查看启用且允许读取」时暴露view_image。默认配置两个能力开关均为false闭门策略只有显式开启后才进入工具目录。is_image_tool_gated(tool_name, config)返回「该工具是否应从会话隐藏」。这些逻辑被 image_tests.rs 以用例锁定例如image_specs_gate_each_tool_independently当local_image_reads_allowed: false时image_generation可见而view_image被门控image_specs_hide_generation_when_writes_are_blocked当generated_image_writes_allowed: false时view_image可见而image_generation被门控image_specs_are_empty_when_runtime_support_is_disabled运行时未启用任何能力时specs 为空任何工具名包括未知工具都被判定为 gatedimage_config_default_is_closed_by_capability默认配置闭门、输出格式为png。五、Prompt 指南什么时候让 Agent 看到图像规则prompt.rs 的render_image_prompt_guidance(config, options)负责渲染「## Image Tools」小节。它只在至少一个媒体工具实际可用时输出内容两者都不可用时返回空字符串避免无意义的 Prompt 膨胀。渲染规则包括需要像素UI 审查、OCR、图表检查、视觉对比、理解本地截图时使用view_image而普通文件元数据不要用它需要位图创建/编辑时使用image_generation并给出具体 Prompt目的地重要时提供输出路径生成完成后必须在最终回答中提及产物保存路径方便用户查找附加文件到模型上下文前尊重本地图像边界仅查看已批准工作区/本会话创建/用户或可信工具显式引用的图像。ImagePromptOptions提供两个开关include_final_answer_rules是否包含最终回答产物引用指南默认true与include_local_file_boundaries是否包含本地文件隐私边界默认true便于宿主按需裁剪。端到端契约测试 image_e2e_contract_renders_specs_and_prompt_guidance 验证了从配置到 specs 与 Prompt 指南的完整链路当image_generation_output_format为Jpeg时specs 中output_format默认值为jpegview_image的detail默认值为auto且 Prompt 同时包含两个工具名。六、测试策略与演进约定契约模块带有聚焦的 Rust 测试覆盖image_generation的 JSON Schema 形态含序列化/反序列化往返见 image_spec_serializes_for_schema_catalogsview_image的 JSON Schema 形态生成与本地查看的独立门控从配置到 specs 与 Prompt 指南的端到端契约渲染工具名稳定性known_image_tool_names_stay_stable。演进约定同样明确未来的运行时 PR 应把提供商相关的执行测试放在运行时适配器旁边而不是塞进托管契约模块——契约层只负责稳定表面执行细节由各运行时负责。七、GMI 媒体生成可实际执行的图片与视频工具与上述高层image_generation契约分离src/openhuman/media/generation/ 域提供了已接线、可执行的工具通过 OpenHuman 后端的media_generation提供商GMI CloudSeedream、SeedEdit、Seedance、Veo生成图片与视频。入口为 tools.rs 的build_media_tools(root_config, action_dir)当未配置集成客户端无后端 URL / 未登录时返回空列表工具族静默跳过。工具用途权限输出media_generate_image经 GMI 文生图 / 图生图Executegenerated-media/下的本地文件路径media_generate_video经 GMI 文生视频 / 图生视频Executegenerated-media/下的本地文件路径media_list_models列出精选模型目录可选含 GMI 实时列表Read-only模型 id 定价提交—轮询—落盘的工作机制生成是异步的工具通过共享流程generate_and_persisttools.rs执行提交向POST /agent-integrations/media-generation/images视频为/videos发送wait: false请求——后端在提交时即计费并立即返回request_id由核心自己负责进度 UX轮询以 4 秒为间隔POLL_INTERVAL轮询GET /agent-integrations/media-generation/requests/{requestId}直到请求达到终态terminal state图片等待上限IMAGE_MAX_WAIT_SECS 300秒视频VIDEO_MAX_WAIT_SECS 420秒下载落盘GMI 返回的是会过期的签名 URL工具把每个产物下载到 Agent 的generated-media/目录返回稳定的本地文件路径persist_media位于 download.rs返回结果工具输出包含request_id、model、cost_usd与每个产物的类型、本地路径、源 URL、缩略图 URL并以 Markdown 列表呈现方便 Agent 在最终回答中引用。值得注意的可靠性语义如果请求在等待预算内未达到终态工具返回错误而非虚假成功——因为「成功」会谎报一个从未产出的文件。错误信息明确提示该请求已被接受并计费、可能仍在服务端运行且没有按 id 恢复的路径再次调用会新建并再次计费因此不得自动重试应上报用户由其决定tools.rs。瞬态轮询失败不会中止已付费的生成会持续轮询至截止时间并记录最后错误。后端拥有 GMI 的密钥、计费与限流/agent-integrations/media-generation/*。工具参数与端点常量均集中在 tools.rs。工具参数速查media_generate_image必填prompt可选model默认seedream-4-0-250828、size如1024x1024、1536x1024、n1–8 张默认 1、input_images参考图 URL 数组用于图生图/编辑、seed复现种子media_generate_video必填prompt可选model默认seedance-1-0-pro-fast-251015、input_image首帧/参考图 URL、duration_seconds1–60、aspect_ratio如16:9、9:16、1:1、negative_prompt、seedmedia_list_models可选include_upstream默认false为true时额外拉取 GMI 完整实时模型列表?includeUpstreamtrue。两个生成工具都属于ToolCategory::Workflow、PermissionLevel::Execute并通过execute_with_context优先使用工具执行上下文的工作区根目录作为产物目录。八、图像与视频子代理两个专家子代理包装上述工具可由编排器orchestrator通过委派delegation触达image_agentdelegate_create_image负责 Prompt 打磨、模型选择与生成图片保存运行在多模态vision-v1档位因此可以检查自己产出的图像video_agentdelegate_create_video负责文生视频与图生视频会明确告知生成可能需要数分钟并阻塞直到片段保存完成。这种「契约层稳定的工具表面 执行层GMI 真实生成 子代理领域专家编排」的三层结构使 OpenHuman 既能对模型保持稳定一致的图像工具语义又能随提供商能力扩展而渐进接入同时通过门控与本地文件边界守住隐私与安全底线。【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenHuman Image Tools 全解析：image_generation 与 view_image 的模型层契约设计与 GMI 媒体生成实战
OpenHuman Image Tools 全解析image_generation 与 view_image 的模型层契约设计与 GMI 媒体生成实战【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman本篇文章深入解析 OpenHuman 的 Image Tools 架构它如何在模型与运行时之间建立一套与具体提供商无关的稳定契约让 Agent 可以一致地完成图像生成image_generation与本地图像查看view_image同时梳理已接入后端media_generation提供商GMI CloudSeedream、SeedEdit、Seedance、Veo的可实际执行的图片/视频生成工具。读完你将掌握两个核心契约的 JSON Schema 与权限模型、运行时门控gating策略、Prompt 指南的渲染规则以及 GMI 异步生成工具「提交—轮询—落盘」的完整实现链路。一、为什么需要「图像工具契约层」OpenHuman 的定位是本地优先的跨平台Mac / Windows / Linux个人 AI。在其 Agent 运行时中图像能力天然分为两类诉求生成/编辑位图需要托管提供商与把本地图片像素加载进模型上下文纯本地只读。如果把这两类能力直接绑定到某个具体的提供商运行时会让 Prompt 表面prompt surface随提供商切换而漂移Agent 无法稳定决策。因此OpenHuman 在顶层 src/openhuman/media/image/ 模块中定义了一个高层契约层。正如模块注释mod.rs所述该层不直接执行图像生成或像素检查而是定义稳定的工具名称、JSON Schema、门控gating规则与 Prompt 指南供具备图像能力的运行时/提供商适配器按需暴露。契约层当前覆盖两个模型可见工具工具用途权限输出image_generation根据 Prompt 生成或编辑位图图像Write写本地 generated-media 产物路径view_image将本地图像文件加载进模型可见的图像上下文Read-only只读模型可见的图像内容该层刻意保持高层抽象底层具体行为仍由既有底层工具负责image_info读取本地图像元数据与可选的 base64 文本模块说明Agent 多模态准备为接受图像数据的提供商规范化[IMAGE:...]标记浏览器snapshot暴露结构化 DOM 与无障碍内容不捕获页面像素。契约层只定义名称、Schema、门控与 Prompt 规则让运行时在逐步接入直接支持时Agent 能保持一致决策而无需在工具注册表中重复实现业务逻辑。模块结构src/openhuman/media/image/ 目录结构清晰文件职责mod.rs导出型模块入口统一重导出契约符号types.rs共享描述符、权限/配置类型与门控辅助函数image_generation.rsimage_generationSchema 与输出格式契约image_view.rsview_imageSchema 与 detail 级别契约prompt.rs面向 Agent 的图像工具 Prompt 指南渲染image_tests.rs覆盖配置、Schema 与 Prompt 输出的契约级端到端测试二、image_generation托管式图像生成契约image_generation是一个托管提供商能力。Rust 核心不应在没有任何提供商支持时伪装成图像渲染器。契约源码image_generation.rs将其建模为ImageToolSpec名称固定为image_generation权限为ImagePermission::Writewrites_files: truemodel_visible_image_output: false输出是文本路径而非图像内容本身。运行时应当遵循的四步流程当能力启用时运行时应当校验input_image_path与图像查看共用同一套本地文件策略即只有已批准工作区、当前会话创建、用户或可信工具显式引用的路径才合法发送 Prompt 与可选编辑图给托管图像提供商持久化返回的字节写入会话作用域的 generated-media 根目录或写入经批准的调用方指定output_path返回已保存的产物路径供最终助手回答引用这些具体文件。参数 Schema该工具的参数为 JSON Schema object仅prompt为必填参数类型说明promptstring必填面向托管图像模型的详细视觉 Prompt 或编辑指令output_pathstring可选工作区相对或已批准的绝对输出路径省略时由运行时选择 generated-media 路径sizestring可选输出尺寸如1024x1024、1536x1024或提供商默认值input_image_pathstring可选的待编辑本地图像路径运行时必须在校验本地文件访问后才可附加output_formatstring枚举持久化文件格式png、webp、jpeg默认值来自运行时的ImageGenerationOutputFormat配置output_format的合法值与序列化由 ImageGenerationOutputFormat 枚举 保证#[serde(rename_all snake_case)]对应png/webp/jpeg。三、view_image把本地像素送进模型上下文view_image把本地文件中的像素加载进模型可见上下文。契约源码image_view.rs中model_visible_image_output: true、writes_files: false、权限为ImagePermission::ReadOnly——它只读不写。适用场景当纯文本元数据不足以支撑推理时使用截图分析、UI 审查、OCR、图表/示意图理解、视觉差异对比、生成图像自检等。本地文件边界必须显式运行时必须保持本地文件边界清晰仅允许已批准工作区approved workspace内的路径当前会话期间创建的路径用户或可信工具输出显式引用的路径拒绝策略之外的路径且不得静默附加无关的本地图像。参数 Schema参数类型说明pathstring必填本地图像路径绝对路径或相对于已批准工作区detailstring枚举默认auto检查细节级别auto、high、original仅在需要全分辨率检查时使用originaldetail的三档取值由 ImageDetail 枚举 定义默认值为auto。四、能力门控ImageToolConfig与image_specs契约层将「哪些图像工具对会话可见」收敛到ImageToolConfigtypes.rs它包含五个开关字段含义image_generation_enabled运行时是否支持托管图像生成image_view_enabled运行时是否支持本地图像附加/查看image_generation_output_format生成图像的期望输出格式默认Pnglocal_image_reads_allowed当前文件系统策略是否允许工作区图像读取默认truegenerated_image_writes_allowed是否允许在配置的输出根目录下写入生成文件默认true关键设计是独立门控image_specs(config)types.rs只在「生成启用且允许写入」时暴露image_generation只在「查看启用且允许读取」时暴露view_image。默认配置两个能力开关均为false闭门策略只有显式开启后才进入工具目录。is_image_tool_gated(tool_name, config)返回「该工具是否应从会话隐藏」。这些逻辑被 image_tests.rs 以用例锁定例如image_specs_gate_each_tool_independently当local_image_reads_allowed: false时image_generation可见而view_image被门控image_specs_hide_generation_when_writes_are_blocked当generated_image_writes_allowed: false时view_image可见而image_generation被门控image_specs_are_empty_when_runtime_support_is_disabled运行时未启用任何能力时specs 为空任何工具名包括未知工具都被判定为 gatedimage_config_default_is_closed_by_capability默认配置闭门、输出格式为png。五、Prompt 指南什么时候让 Agent 看到图像规则prompt.rs 的render_image_prompt_guidance(config, options)负责渲染「## Image Tools」小节。它只在至少一个媒体工具实际可用时输出内容两者都不可用时返回空字符串避免无意义的 Prompt 膨胀。渲染规则包括需要像素UI 审查、OCR、图表检查、视觉对比、理解本地截图时使用view_image而普通文件元数据不要用它需要位图创建/编辑时使用image_generation并给出具体 Prompt目的地重要时提供输出路径生成完成后必须在最终回答中提及产物保存路径方便用户查找附加文件到模型上下文前尊重本地图像边界仅查看已批准工作区/本会话创建/用户或可信工具显式引用的图像。ImagePromptOptions提供两个开关include_final_answer_rules是否包含最终回答产物引用指南默认true与include_local_file_boundaries是否包含本地文件隐私边界默认true便于宿主按需裁剪。端到端契约测试 image_e2e_contract_renders_specs_and_prompt_guidance 验证了从配置到 specs 与 Prompt 指南的完整链路当image_generation_output_format为Jpeg时specs 中output_format默认值为jpegview_image的detail默认值为auto且 Prompt 同时包含两个工具名。六、测试策略与演进约定契约模块带有聚焦的 Rust 测试覆盖image_generation的 JSON Schema 形态含序列化/反序列化往返见 image_spec_serializes_for_schema_catalogsview_image的 JSON Schema 形态生成与本地查看的独立门控从配置到 specs 与 Prompt 指南的端到端契约渲染工具名稳定性known_image_tool_names_stay_stable。演进约定同样明确未来的运行时 PR 应把提供商相关的执行测试放在运行时适配器旁边而不是塞进托管契约模块——契约层只负责稳定表面执行细节由各运行时负责。七、GMI 媒体生成可实际执行的图片与视频工具与上述高层image_generation契约分离src/openhuman/media/generation/ 域提供了已接线、可执行的工具通过 OpenHuman 后端的media_generation提供商GMI CloudSeedream、SeedEdit、Seedance、Veo生成图片与视频。入口为 tools.rs 的build_media_tools(root_config, action_dir)当未配置集成客户端无后端 URL / 未登录时返回空列表工具族静默跳过。工具用途权限输出media_generate_image经 GMI 文生图 / 图生图Executegenerated-media/下的本地文件路径media_generate_video经 GMI 文生视频 / 图生视频Executegenerated-media/下的本地文件路径media_list_models列出精选模型目录可选含 GMI 实时列表Read-only模型 id 定价提交—轮询—落盘的工作机制生成是异步的工具通过共享流程generate_and_persisttools.rs执行提交向POST /agent-integrations/media-generation/images视频为/videos发送wait: false请求——后端在提交时即计费并立即返回request_id由核心自己负责进度 UX轮询以 4 秒为间隔POLL_INTERVAL轮询GET /agent-integrations/media-generation/requests/{requestId}直到请求达到终态terminal state图片等待上限IMAGE_MAX_WAIT_SECS 300秒视频VIDEO_MAX_WAIT_SECS 420秒下载落盘GMI 返回的是会过期的签名 URL工具把每个产物下载到 Agent 的generated-media/目录返回稳定的本地文件路径persist_media位于 download.rs返回结果工具输出包含request_id、model、cost_usd与每个产物的类型、本地路径、源 URL、缩略图 URL并以 Markdown 列表呈现方便 Agent 在最终回答中引用。值得注意的可靠性语义如果请求在等待预算内未达到终态工具返回错误而非虚假成功——因为「成功」会谎报一个从未产出的文件。错误信息明确提示该请求已被接受并计费、可能仍在服务端运行且没有按 id 恢复的路径再次调用会新建并再次计费因此不得自动重试应上报用户由其决定tools.rs。瞬态轮询失败不会中止已付费的生成会持续轮询至截止时间并记录最后错误。后端拥有 GMI 的密钥、计费与限流/agent-integrations/media-generation/*。工具参数与端点常量均集中在 tools.rs。工具参数速查media_generate_image必填prompt可选model默认seedream-4-0-250828、size如1024x1024、1536x1024、n1–8 张默认 1、input_images参考图 URL 数组用于图生图/编辑、seed复现种子media_generate_video必填prompt可选model默认seedance-1-0-pro-fast-251015、input_image首帧/参考图 URL、duration_seconds1–60、aspect_ratio如16:9、9:16、1:1、negative_prompt、seedmedia_list_models可选include_upstream默认false为true时额外拉取 GMI 完整实时模型列表?includeUpstreamtrue。两个生成工具都属于ToolCategory::Workflow、PermissionLevel::Execute并通过execute_with_context优先使用工具执行上下文的工作区根目录作为产物目录。八、图像与视频子代理两个专家子代理包装上述工具可由编排器orchestrator通过委派delegation触达image_agentdelegate_create_image负责 Prompt 打磨、模型选择与生成图片保存运行在多模态vision-v1档位因此可以检查自己产出的图像video_agentdelegate_create_video负责文生视频与图生视频会明确告知生成可能需要数分钟并阻塞直到片段保存完成。这种「契约层稳定的工具表面 执行层GMI 真实生成 子代理领域专家编排」的三层结构使 OpenHuman 既能对模型保持稳定一致的图像工具语义又能随提供商能力扩展而渐进接入同时通过门控与本地文件边界守住隐私与安全底线。【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考