dsh-auto-visual：DSH 插件的图片素材编排工具

下面介绍 DeepSeek Harness（DSH）插件 herbert-wang820/dsh-image（即 dsh-auto-visual）。它解决的是 DSH Agent 在处理文档、网页或演示文稿时的配图需求：把“需要什么图”变成结构化计划，交给可替换的供应方生成，再登记每张图被用在哪里。

核心功能¶

该插件将图片生成任务拆解为三个独立步骤，各自负责不同职责：

visual_plan：分析任务，给出结构化的素材需求清单（用途、主体、风格、比例等），返回确定的提示词与素材 ID。
visual_generate：根据计划 ID 和素材 ID，调用配置的供应方生成图片。已生成的结果会直接复用，不重复调用。
visual_finalize：主 Agent 在完成文档或网页制作后，登记每张图的实际放置位置和工作区相对路径。

安装¶

通过 DSH 命令行安装该插件。安装后需重启 Host 并刷新页面。

dsh plugin --profile <profile> add github:Herbert-wang820/dsh-image

配置¶

插件提供一组配置项，用于控制生成模式、供应方及资源限制。默认出厂配置为安全模式，不会产生任何调用与费用。

字段	取值	含义
`mode`	`off` / `suggest` / `auto`	关闭 / 仅规划 / 允许生成
`provider`	`disabled` / `mock` / `openai`	禁用 / 本地测试图 / OpenAI 兼容 API
`model`	模型 ID	如 `gpt-image-2`；`mock` 仅接受 `mock-v1`
`baseURL`	API 根地址	默认 `https://api.openai.com/v1`
`apiKey`	API Key	保存后不回显，留空不覆盖已有密钥
`maxAssets`	1–100	每个会话的素材上限，默认 3

默认配置示例：

mode: suggest
provider: disabled
model: mock-v1
baseURL: https://api.openai.com/v1
apiKey: ''
maxAssets: 3

使用流程：
1. 先将 mode 设为 auto、provider 设为 mock，在无网络环境下验证全流程。
2. 验证通过后，将 provider 切换为 openai，填入模型 ID、Base URL 和 API Key。

使用示例¶

在 Agent 工作流中，通常按以下顺序调用工具：

调用 visual_plan 传入任务描述和素材列表。
调用 visual_generate 传入 planId 和 assetId 生成图片。
主 Agent 完成文档编辑后，调用 visual_finalize 填入图片的路径和位置。

工具输入示例：

{
  "task": "网站首页配图",
  "assets": [{
    "purpose": "website hero illustration",
    "subject": "abstract collaborative research workspace",
    "style": "navy and teal, minimal flat illustration",
    "placement": "right side hero; leave left side clear for text",
    "ratio": "1:1",
    "required": true
  }]
}

安全与权限¶

该插件对安全性和权限有明确要求：

密钥安全：API Key 以 Host 侧 role('secret') 配置字段保存。写入后不回显，不随配置描述回传浏览器，不进入对话、提示词或日志。
文件权限：工具需要写权限，连查询也会取工作区锁。
沙箱要求：沙箱策略必须返回 full enforcement，否则插件会拒绝运行。
存储限制：仅支持映射到 Host 的本地/同世界文件系统，不支持远程执行世界。

已知限制¶

中断恢复：中断的请求不会自动重试，状态恢复为 uncertain。
图片格式：OpenAI 兼容适配器仅支持同步返回 base64 PNG，固定比例 1:1。
Mock 限制：不会用 Mock 图片充当用户要求的真实图片交付。
校验范围：PNG 校验仅覆盖特定子集（非隔行、8-bit、最长边 4096 等），不覆盖所有合法 PNG。
功能边界：不提供视觉质量判定，不重写编辑器，不保证主 Agent 会主动触发配图。

许可证¶

MIT