尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

OpenHuman 图像能力契约层解析:image_generation 与 view_image 工具的模型侧接口设计

OpenHuman 图像能力契约层解析:image_generation 与 view_image 工具的模型侧接口设计 OpenHuman 图像能力契约层解析image_generation 与 view_image 工具的模型侧接口设计【免费下载链接】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 仓库中src/openhuman/media/image/README.md及其配套 Rust 源码系统讲解图像能力运行时image-capable agent runtimes的高层模型侧契约设计image_generation托管栅格图像生成/编辑与view_image本地图像加载为模型可见上下文两个稳定工具接口的 schema、权限门控gating、策略开关与 Agent 提示词渲染逻辑。读完本文你将掌握该模块的契约边界、配置开关组合矩阵、JSON Schema 参数细节以及如何在 provider/runtime 适配层接入这套接口。模块定位契约层而非执行层在 OpenHuman 的 Rust 代码结构中图像能力被刻意设计为薄契约层high-level contract layer模块入口位于 src/openhuman/media/mod.rs其自身明确声明This module does not execute image generation or pixel inspection directly. It defines the stable model-facing contracts that provider/runtime adapters can expose when image capabilities are available.也就是说该模块不执行任何图像生成或像素检查只负责定义稳定的、面向模型的工具契约。真正调用托管服务或做模型附件attachment的执行适配器未来应依赖这些契约并紧邻真正执行 hosted 调用或模型附件的 runtime/provider 实现存放。从media/mod.rs的注释还可以确认一个重要事实image子模块目前是契约脚手架contracts scaffold尚未接入真实执行路径源码注释标注为 currently unwired, #2997整体由mediafeature 在家族根部src/openhuman/mod.rs中的pub mod media;统一门控。这是一个“surface-only”门控媒体生成经由共享的reqwest后端代理而imagecrate 与频道上传共享因此不会甩掉任何独占依赖该模块家族是纯粹的 agent-tools 域没有DomainGroup::Media标记的 controller/store/subscriber。模块结构如下原文表格 源码文件一一对应文件仓库相对路径职责src/openhuman/media/image/mod.rs仅做导出的模块入口统一 re-export 各契约src/openhuman/media/image/types.rs共享描述符、权限/配置类型与门控辅助函数src/openhuman/media/image/image_generation.rsimage_generationschema 与输出格式契约src/openhuman/media/image/image_view.rsview_imageschema 与 detail 级别契约src/openhuman/media/image/prompt.rs图像工具启用时的 Agent 提示词指导渲染src/openhuman/media/image/tests.rs覆盖配置、schema、提示词输出的契约级 e2e 测试两个一等公民契约image_generation 与 view_image模块声明两个一等契约first-class contractsimage_generation—— 创建或编辑栅格图像并返回存储后的文件引用view_image—— 把本地图像文件挂载为模型可见的图像内容供 Agent 检视。契约与执行分离的意义在于provider runtime 可以在不复制工具注册表tools registry中业务逻辑的前提下增量采纳这套接口面。工具名作为稳定常量被集中定义并 re-exportIMAGE_GENERATION_TOOL_NAME image_generation见 image_generation.rsIMAGE_VIEW_TOOL_NAME view_image见 image_view.rsIMAGE_TOOL_NAMES数组将两者打包供过滤与策略决策使用见 types.rs测试 image_tests.rs 显式锁定了IMAGE_TOOL_NAMES的稳定顺序防止工具名漂移破坏既有调用方。ImageToolSpecprovider 无关的工具描述符每个契约最终都编译成一个统一的、与 provider/runtime 无关的描述符ImageToolSpec见 types.rs字段含义如下字段类型含义nameString稳定的模型侧工具名descriptionString注入提示词/工具目录的精炼描述parametersserde_json::Value工具参数的 JSON Schema 对象permissionImagePermissionOpenHuman 策略门policy gates要求的执行权限model_visible_image_outputbool工具输出是否应成为模型可见图像内容而非纯文本writes_filesbool执行时是否会在输出目录中写文件权限类ImagePermissiontypes.rs只有两个变体且以 snake_case 序列化ReadOnly—— 元数据或只读本地检视Write—— 创建或编辑生成的媒体文件。image_generation 契约详解image_generation是托管/提供商能力hosted/provider capability而非本地 Rust 图像渲染器。契约注释image_generation.rs明确要求支持该能力的 runtime 应把生成的字节持久化到会话作用域的生成媒体根目录session-scoped generated-media root并在工具输出中返回稳定的文件路径以便最终答案引用具体产物。image_generation_spec(output_format)生成的参数 JSON Schema 如下完整结构见 image_generation.rs{ type: object, properties: { prompt: { type: string, description: Detailed visual prompt or edit instruction for the hosted image model. }, output_path: { type: string, description: Optional workspace-relative or approved absolute output path. When omitted, the runtime chooses a generated-media path. }, size: { type: string, description: Optional output size such as 1024x1024, 1536x1024, or provider default. }, input_image_path: { type: string, description: Optional local image path to edit. The runtime must validate local-file access before attaching it. }, output_format: { type: string, enum: [png, webp, jpeg], default: 当前配置的输出格式, description: Requested persisted file format. } }, required: [prompt] }要点归纳唯一必填参数是prompt测试 image_generation_tests.rs 断言了这一点output_path省略时由 runtime 自动选择生成媒体路径size是可选字符串示例值为1024x1024、1536x1024或交给 provider 默认input_image_path用于“编辑已有图像”场景runtime 在 attach 前必须校验本地文件访问权限output_format的枚举[png, webp, jpeg]与ImageGenerationOutputFormat枚举一一对应默认值来自当前配置image_generation_tests.rs 验证了当配置为 Webp 时默认值为webp该工具的元属性固定为permission Write、model_visible_image_output false输出是文本形式的人工产物路径而非像素、writes_files trueimage_generation.rs。view_image 契约详解view_image负责把本地图像文件桥接为模型可见图像内容。它刻意与image_info区分开元数据提取可以保持文本形态而view_image要求 runtime 把像素加载进对话上下文image_view.rs。image_view_spec()生成的 schemaimage_view.rs{ type: object, properties: { path: { type: string, description: Local image path, absolute or relative to the approved workspace. }, detail: { type: string, enum: [auto, high, original], default: auto, description: Inspection detail. Use original only when full resolution is necessary. } }, required: [path] }要点归纳唯一必填参数是path绝对路径或相对已批准工作区的路径detail三档枚举auto / high / originaloriginal仅在全分辨率确有必要时使用——这是对 token 开销与视觉细节之间的权衡约束测试 image_view_tests.rs 锁定了枚举值与 path 的 string 类型该工具元属性固定为permission ReadOnly、model_visible_image_output true这是它与image_generation在语义上的根本区别加载的是“模型可见的图像内容”、writes_files falseimage_view.rs。门控机制能力开关 × 本地策略契约暴露与否由运行时支持与本地策略共同决定这一逻辑集中在ImageToolConfigtypes.rs与image_specs()中。ImageToolConfig的五个字段字段类型默认值语义image_generation_enabledboolfalseruntime 是否支持托管图像生成image_view_enabledboolfalseruntime 是否支持本地图像挂载/查看image_generation_output_formatImageGenerationOutputFormatPng生成图像的期望输出格式local_image_reads_allowedbooltrue当前文件系统策略是否允许工作区图像读取generated_image_writes_allowedbooltrue生成文件是否可写入配置的输出根目录默认配置在能力上是关闭的closed by capability两个 enabled 字段默认均为false因此ImageToolConfig::default()下image_specs()恒为空测试 image_tests.rs 专门验证了这一点。这符合“能力门控 策略门控”双保险的安全设计即便策略允许读写只要 runtime 未声明支持契约就不会暴露给模型。image_specs(config)的组装规则types.rs是一个典型的 AND 语义矩阵当image_generation_enabled generated_image_writes_allowed时加入image_generation_spec(...)当image_view_enabled local_image_reads_allowed时加入image_view_spec()两者独立判定、互不影响。对应的门控判定函数is_image_tool_gated(tool_name, config)types.rs当工具名不在image_specs()生成的可见集合中时返回true即应从会话中隐藏。门控矩阵的测试证据契约级 e2e 测试把上述矩阵的每一种组合都固化了可以直接作为接入方的行为参考读策略关闭、写策略开启只暴露image_generationview_image被门控image_tests.rs写策略关闭、读策略开启只暴露view_imageimage_generation被门控image_tests.rs能力开关全关specs 为空任意未知工具名都被门控image_tests.rs全开组合按固定顺序返回[image_generation, view_image]且output_format默认值与detail默认值分别随配置注入image_tests.rs。此外ImageToolSpec的序列化往返serde serialize → deserialize也被测试覆盖image_tests.rs确保 schema 目录catalog消费方拿到的是稳定可反序列化的描述符。Agent 提示词指导render_image_prompt_guidance当图像工具可用时模块还负责为 Agent 渲染精炼的提示词指导。入口是render_image_prompt_guidance(config, options)prompt.rs输出以## Image Tools标题开头按可用性分别追加规则行。渲染选项ImagePromptOptionsprompt.rs控制两段可选文本include_final_answer_rules默认true是否包含“生成图像后在最终答案中提及保存的人工产物路径方便用户找到”的规则include_local_file_boundaries默认true是否包含“只查看位于已批准工作区、本会话内创建、或用户/可信工具输出显式引用的本地图像”的隐私边界规则。渲染逻辑要点两个可用性判定复用门控矩阵image_generation_available image_generation_enabled generated_image_writes_allowedimage_view_available image_view_enabled local_image_reads_allowedprompt.rs两者均不可用时返回空字符串不污染提示词即使策略全开只要能力关闭也一样测试 prompt_tests.rs 验证了“能力开 策略全关 → 输出为空”view_image的指导明确其适用场景UI 审查、OCR、图表检视、视觉比较、理解本地截图image_generation的指导要求提供具体 prompt并在目的地重要时给出 output_path只启用单个工具时指导文本只包含对应工具prompt_tests.rs关闭include_final_answer_rules与include_local_file_boundaries后对应文本段被精确省略prompt_tests.rs。这段指导的可裁剪设计意味着宿主程序可以按需决定提示词里携带多少“行为约束”在引导模型正确使用工具与压缩上下文之间取得平衡。与既有底层能力的边界划分README 明确列出既有底层图像助手保持独立、不并入本契约层接入时注意区分image_info只读取元数据/Base64 文本属于文本化能力浏览器snapshot暴露结构化 DOM 与无障碍accessibility内容不捕获页面像素多模态[IMAGE:...]准备规范化图像引用以便支持图像的 provider 使用。这三者与view_image的关键差异在于“是否把像素送入模型上下文”view_image是像素级桥接其余是文本/结构级描述。view_image与image_info的边界在 image_view.rs 的模块注释中有明确表述。从代码结构看可以推断未来若实现执行适配器execution adapters它们应当依赖本模块导出的image_specs、is_image_tool_gated与render_image_prompt_guidance等函数紧邻实际执行 hosted 调用或模型附件的 runtime/provider 实现存放从而保持工具注册表与业务逻辑的解耦。接入实践要点综合契约定义与测试用例接入方provider/runtime 适配器应遵守以下约定工具命名稳定必须使用image_generation与view_image两个常量名不得自定义变体IMAGE_TOOL_NAMES已锁定顺序参数校验以 JSON Schema 为准image_generation必填promptview_image必填path其余字段均为可选且output_format与detail的枚举不可扩展png|webp|jpeg、auto|high|original权限元数据不可混淆生成工具标Writewrites_filestruemodel_visible_image_outputfalse查看工具标ReadOnlywrites_filesfalsemodel_visible_image_outputtrue策略门据此做差异审批产物落盘约定生成图像必须写入会话作用域的生成媒体根目录并返回稳定路径供最终答案引用本地访问校验view_image的 path 与image_generation的input_image_path都要求 runtime 在执行前校验本地文件访问权限配置驱动暴露通过ImageToolConfig的五个开关组合决定暴露面默认配置全能力关闭即最安全形态提示词随配置渲染调用render_image_prompt_guidance生成指导文本并可通过ImagePromptOptions裁剪最终答案规则与本地文件边界文本。以上行为均有对应测试锚点门控矩阵见 image_tests.rsschema 细节见 image_generation_tests.rs 与 image_view_tests.rs提示词渲染见 prompt_tests.rs。需要注意的是本契约层当前尚未接入真实执行路径源码标注 #2997上文第 4、5 条属于契约要求的行为约定最终落地形态以仓库后续实现为准。【免费下载链接】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),仅供参考
返回列表