Skip to content
dsh marketplace

dsh-doubaoimage-cgf

Verified

dsh-doubaoimage-cgf · v1.4.3 · MIT · Web UI

豆包 Seedream 生图插件：调用火山方舟图像生成 API，把图片保存到工作区并显示在会话中

Install

dsh plugin add dsh-doubaoimage-cgf

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Published to npm without a public repository. Inspect the package contents before installing.

Tags

Creators

Readme

dsh-doubaoimage-cgf

DeepSeek Harness 的豆包生图插件：调用火山方舟（Volcengine Ark）Seedream 图像生成 API，把生成的图片保存到会话工作区，并在会话里直接显示。

  • 模型工具 doubao_image：提示词 → 图片，支持参考图（图生图 / 改图）、尺寸档位、模型切换、水印开关。
  • 输入框工具栏里的入口：输入框工具行左侧（和附件、权限等控件同一行）多一个「豆包生图」按钮，点开是居中浮层，不占聊天布局；填提示词、选尺寸、点「生成」直接出图。
  • 专属卡片：工具结果用宿主主题渲染成卡片，图片用宿主授权的 loader 渲染，并显示模型、尺寸、像素和保存路径。
  • 可视化设置：「设置 → 插件 → 豆包生图」里可改 API Key、模型、尺寸、水印、保存目录、超时，不用手改 YAML。
  • 原生图片块：工具结果里带有原生 image 内容块，deepseek-flash 这类支持图片输入的模型可以直接"看到"生成的图并继续修改。

界面与设置

  • 入口在输入框工具行左侧（conversation.input.left），浮层挂在宿主全屏浮层（shell.overlay）里，position: fixed 居中，不改变聊天区与输入框布局；结果图限制在 52vh 高度内等比缩放，面板自身可滚动。
  • 浮层里只有提示词、尺寸档位（1K/1.5K/2K）和「生成」；模型不在这里填，读取插件设置里的默认模型（标题栏会显示当前模型）。
  • 面板的请求走本机路由 /api/doubao-image-v2/settings 与 /api/doubao-image-v2/generate，只接受回环地址的请求。
  • 设置页注册在两个标准位置，渲染同一个表单：设置 → 插件 → 「豆包生图」标签页（settings.plugins.tab），以及插件管理页 → dsh-doubaoimage-cgf → 组件行 doubao-image → 配置（plugins.row.config，键 dsh-doubaoimage-cgf#doubao-image）。
  • 保存走 /api/doubao-image-v2/config，由 Host 的 configEditor.edit() 写回 profile 的 cordis.patch.yml，插件随即重载；API Key 输入框留空表示不修改。

安装

单机开发时可以直接装目录（会以软链接方式挂进 profile）：

# 在 Harness 会话里用 plugin_manager 安装本地目录：
#   action: install_bundle
#   target: <本目录的绝对路径>

安装后新会话即可使用；浏览器端如果是首次加载，刷新页面后卡片生效。

给他人使用

从 npm 安装（推荐）

包名：dsh-doubaoimage-cgf

  1. 打开 DSH，左侧栏 「插件」 → 添加插件；
  2. 填入 dsh-doubaoimage-cgf，安装并 启用；
  3. 点输入框左侧的「生图」按钮——首次使用浮层里会直接出现 API Key 输入框，粘贴自己的 Key 点「保存 Key」即可；也可以到 设置 → 插件 → 豆包生图 里填。Key 在 火山方舟控制台 的「API Key 管理」创建；
  4. 确认账号已开通图片模型（默认 doubao-seedream-5-0-flash-260915），未开通时接口会返回 ModelNotOpen 并在面板里提示去开通。

离线 / 内网：用 tgz

pnpm pack 会生成 dsh-doubaoimage-cgf-<版本>.tgz。把 tgz 发给对方，在 插件 → 添加插件 里填 tgz 的绝对路径，其余步骤同上。

要点：

  • 插件本身不含任何 Key，每个 profile 的 Key、模型、保存目录都是各自独立的；
  • 安装时会从 npm 拉取依赖 @deepseek-ai/schemastery（已在 package.json 声明），离线环境需要先配好源；
  • API Key 保存在对方自己 profile 的 cordis.patch.yml 里，不会随包分发；
  • 如果对方也要 Pro 画质，在设置里把模型换成 doubao-seedream-5-0-pro-260628（需其账号开通）。

配置 API Key

插件按以下顺序取 Key：

  1. 插件配置里的 apiKey（明文写在 cordis.patch.yml 的 config 中）；
  2. ctx.credentials 中与 apiKeyEnv 同名的凭据；
  3. 与 apiKeyEnv 同名的环境变量（默认 ARK_API_KEY）。

推荐第 3 种。Windows PowerShell（当前用户，重启 Harness 后生效）：

[Environment]::SetEnvironmentVariable('ARK_API_KEY', '<你的 API Key>', 'User')

设置后完全退出并重新打开 DeepSeek Harness（不是只关窗口），新会话里模型就能直接调用 doubao_image。

API Key 在火山方舟控制台的「API Key 管理」里创建；同时必须在「开通管理」里开通一个图片生成模型（默认 doubao-seedream-5-0-flash-260915）。未开通时接口会返回 ModelNotOpen，插件会把这句话原样带回并提示去开通。

验证

装好并设置 Key、开通模型后，在会话里说「用豆包画一只在窗台上晒太阳的橘猫」，模型会调用 doubao_image：

  • 工具卡片显示生成的图（首次安装后刷新一次页面，让浏览器加载插件的前端半边）；
  • 图片保存在 <工作区>/doubao-images/doubao-<时间戳>-<随机>.png；
  • 失败时错误信息会说明是缺 Key、模型未开通、HTTP 状态码还是响应里没有图片。

配置项（cordis.patch.yml）

- id: doubao-image
  name: dsh-doubaoimage-cgf
  config:
    apiKeyEnv: ARK_API_KEY
    model: doubao-seedream-5-0-flash-260915
    size: "2K"
    watermark: false
    saveDir: doubao-images
    timeoutMs: 180000
键 默认值 说明
apiKey 空 直接写在这里的 API Key；留空则走凭据/环境变量
apiKeyEnv ARK_API_KEY 保存 Key 的环境变量名，也是凭据服务的键
baseUrl https://ark.cn-beijing.volces.com/api/v3 网关地址（国际站 BytePlus 换成对应域名）
model doubao-seedream-5-0-flash-260915 默认模型（Seedream 5.0 Flash），可换成账号已开通的其他 Seedream 模型
size 2K 1K / 1.5K / 2K / 3K 或 宽x高；3K 是否可用取决于模型，Flash / Pro 上限 4,624,220 像素
watermark false 是否加水印
saveDir doubao-images 保存目录：相对会话工作区，或绝对路径（如 D:\pics\doubao）
timeoutMs 180000 单次请求超时

工具参数

参数 必填 说明
prompt 是 画面描述
size 否 覆盖默认尺寸（含 3K、宽x高）
model 否 覆盖默认模型
watermark 否 覆盖默认水印设置
reference_image 否 工作区内的本地图片路径或 http(s) 链接，用于图生图/改图

实现说明

  • 请求：POST {baseUrl}/images/generations，Authorization: Bearer <key>，response_format: "url"、sequential_image_generation: "disabled"。
  • 响应：优先读 data[0].b64_json，否则下载 data[0].url；用文件魔数确认 PNG/JPEG/WebP/GIF。
  • 落盘：写入 <cwd>/<saveDir>/doubao-<时间戳>-<随机>.png，路径限制在工作区内。
  • 展示：通过 ctx.attachments.saveImage 生成持久附件引用，工具结果返回文本信封 + 原生 image 块；卡片注册 tool.call.toolview 的 doubao_image 键，并用宿主传给卡片的 loadImage（会话授权 loader）渲染图片——tool.call.images 子 slot 已被自带 read_image 卡片声明，其它卡片不能重复声明，renderSlot 会抛 not declared by this entry's children。
  • 失败：缺少 Key、模型未开通、HTTP 非 2xx、响应无图片、超时都会给出可操作的错误信息。

已知限制

  • 一次调用只生成一张图；组图（sequential_image_generation 多图）未实现。
  • 参考图只支持本地工作区文件或公网 http(s) 链接。
  • 图片会进入会话历史，长会话里会持续占用图片 token；可用宿主自带的图片卸载/压缩策略处理。
  • 卡片文案目前为中文写死，未接入宿主 locale。
  • 首次安装（或改客户端代码后）需要刷新一次页面，浏览器才会加载前端半边；服务端 HMR 有时能直接热更，但不保证。