ankye/dsh-image-generation#tool-image-generation

English | 中文

给你的 DeepSeek Harness agent 装上画笔。dsh-image-generation 是面向 DeepSeek Harness 的图像生成插件：agent 用文字描述画面，设置中选择的生成通道通过可插拔后端产出图片并落盘返回文件路径——整个过程在模型之外，完全不需要具备图像能力的模型。

兼容性

本修订要求 DeepSeek Harness core 为 0.1.2-alpha.5 或以上的 0.1.x 版本；它使用该 core 版本引入的 Settings 服务 API。

为什么值得装

• deepseek 不会画？现在会了。 harness 模型没有图像输出。本插件把「创作」放在模型之外，返回真实文件路径，agent 可以直接交付或继续核验。
• 多通道架构，天生可扩展。 generate_image 工具与生成后端完全解耦。gpt-image-2 通道开箱即用；加 Gemini / FLUX / 本地模型 = 一个 generate() 实现 + 一行注册，工具 schema 永远不用改。
• 参数标准化。 count / aspect_ratio / quality 跨通道归一化；通道特有的旋钮留在设置段的每通道默认值里。
• 生成即自检。 图片解码落盘到 generated/ 并返回路径；搭配 dsh-client-vision 识图插件可做「生成 → 识图验收」闭环。
• 密钥安全。 API Key 存在 harness credentials 服务里（GENERATION_OPENAI_API_KEY）——绝不进设置文件、日志或会话记录。
• 所有 preset 开箱即用。 host 层全局挂载，code / standard / cordis / minimal 任何 preset 都能生成。
• 默认参数可配。 默认宽高比 / 质量 / 张数 / 输出目录都能在设置页配置；工具也支持单次调用覆盖。
• 开箱可分发。 附构建产物；三种安装路径（拖入 monorepo / pnpm publish / tarball）。

能力说明

工具

工具	作用
generate_image	从文字提示生成 1–10 张图。参数：prompt（必填）、count、aspect_ratio（1:1…2:3）、quality（low/medium/high/auto）、output_dir。返回落盘文件路径 + MIME。

设置（generation 命名空间）

配置入口：设置 → 插件 → 插件配置 →「图像生成」

字段	含义
接口地址（baseUrl）	域名 + 可选路径前缀；自动拼接 /images/generations。例：https://api.example.com/v1
生成通道	当前生效的生成后端（目前为 gpt-image-2）
模型	gpt-image-2
输出目录	生成图片的写入位置；留空使用 <cwd>/generated
默认宽高比 / 质量 / 张数	工具未传单次参数时使用
API Key	通过 harness credentials 服务存储为 GENERATION_OPENAI_API_KEY；明文永远不离开你的机器

多通道架构

模型 → generate_image(prompt, count?, aspect_ratio?, quality?)
        │  读取 generation.channel
        ▼
  channels/<id>/generate()          ← 每个后端一个实现
        │
  gpt-image-2:  POST {baseUrl}/images/generations   （b64_json / url）
  gemini / flux / 本地模型: …        ← 在这里加你的
        │
        ▼
  output.ts → 解码写盘 → {path, mime}[]

加一个通道，小到不能再小：

// src/channels/<id>/index.ts
export async function myGenerate(ctx, call): Promise<GeneratedImage[]> {
  // call.prompt / call.count / call.aspectRatio / call.quality / call.config / call.signal
  return await fetchYourGenerationApi(...)
}

// src/channels/index.ts —— 一行注册
export const channels = {
  'gpt-image-2': { label: 'GPT Image', generate: gptImageGenerate, maxCount: 10, ... },
  myChannel: { label: 'My Channel', generate: myGenerate },
}

generate_image 工具及其 schema 永远不用改。

安装方式（官方部署，不改仓库）

dsh plugin add 把包装进 profile；每个包都声明了 dsh.bundle，挂载自动完成——不需要手写 patch 行、不需要改官方工程。

前置条件

• DeepSeek Harness core 0.1.2-alpha.5 或以上的 0.1.x 版本，且 dsh 与 pnpm 在 PATH。

1. 取包（三选一）

a. 从本仓库（发布前推荐）：

dsh plugin --profile web add \
  file:/path/to/dsh-image-generation/packages/tool-image-generation \
  file:/path/to/dsh-image-generation/packages/ui-image-generation

b. Tarball：

cd packages/tool-image-generation && npm pack
cd packages/ui-image-generation   && npm pack
dsh plugin --profile web add file:/path/to/deepseek-ai-dsh-tool-image-generation-0.1.0-rc.7.tgz \
                            file:/path/to/deepseek-ai-dsh-client-ui-image-generation-0.1.0-rc.7.tgz

c. npm registry（发布后）：

dsh plugin --profile web add @deepseek-ai/dsh-tool-image-generation @deepseek-ai/dsh-client-ui-image-generation

安装时的 [WARN] Issues with peer dependencies 是正常的，可忽略——peer 由部署自身的 bundle 在运行时提供。

2. 验证安装

node -e "console.log(JSON.stringify(require(process.env.HOME + '/.dsh/profiles/web/package.json').dsh.profile.bundles))"
# 应包含 dsh-tool-image-generation 与 dsh-client-ui-image-generation

3. 重启 + 配置

重启 harness，打开 设置 → 插件 → 插件配置 →「图像生成」：填接口地址、模型、默认参数、输出目录和你自己的 API Key（GENERATION_OPENAI_API_KEY），保存。

4. 功能验证

让 agent「生成一张……的图片」——它会调用 generate_image 并返回 generated/ 下的文件路径。

卸载

dsh plugin --profile web remove @deepseek-ai/dsh-tool-image-generation @deepseek-ai/dsh-client-ui-image-generation

备选：在 harness 分支内构建

如果你运行的是 deepseek-harness 的分支（而非官方部署），也可以把包拖进 monorepo：

cp -R packages/tool-image-generation <harness>/packages/vision/tool-image-generation
cp -R packages/ui-image-generation   <harness>/packages/client/ui-image-generation

然后在 harness 仓库内：apps/cli/package.json 加两个依赖（workspace:^）、tsconfig.host.json/tsconfig.client.json 加引用、pnpm install、构建（tsdown host + client），重启。

参数

参数	含义	默认
prompt	描述要生成的图像的文字（必填）。	—
count	生成张数（1–10）。	1
aspect_ratio	1:1 / 4:3 / 3:4 / 16:9 / 9:16 / 3:2 / 2:3，映射为 OpenAI 像素尺寸。	1:1
quality	low / medium / high / auto。	auto
output_dir	输出文件目录；相对路径基于会话工作区解析。	generated/

不支持的宽高比、质量或越界的张数会明确报错并给出支持值——工具从不静默替换。

快速上手

1. 重启 harness。
2. 工具目录出现 generate_image。
3. 打开 设置 → 插件 → 插件配置 →「图像生成」，填接口地址、模型和你自己的 API Key，保存。
4. 让 agent「生成一张……的图片」——它会返回落盘的文件路径。

开发说明

• 本仓库是源码分发形态：peer 依赖（@deepseek-ai/dsh-tools 等）来自你的部署；lib/ 已附构建产物，npm pack 立即可用。
• tsconfig.json 已适配独立目录；harness monorepo 内的构建管线（含 client bundle 的 tsdown.config.ts）在方式 A 下生效。
• 绝不提交密钥：API Key 只存在每台机器的 .credentials.yaml 里。

License

MIT