前言¶
在 DSH（DeepSeek Harness）里做智能体或日常对话时，若需要调用腾讯混元 Hy-Image 出图，常见做法是自行拼 TokenHub API、处理尺寸约束，并另建脚本保存结果——远程 URL 约 12 小时后会失效，图库也容易和对话上下文脱节。dsh-plugin-hunyuan-image 是面向 DSH 的原生插件：在客户端提供生成面板与本地图库，并注册可被模型调用的工具，把混元 v3.5-preview 与 v3.0 接到同一套工作流里。下面介绍其定位、能力与安装配置方式。
这是什么¶
- 名称：
dsh-plugin-hunyuan-image（面板标题：腾讯混元生图） - 维护者：rayyugz
- 版本：1.0.0（MIT 许可证）
- 分类：模型推理
- 仓库：github.com/rayyugz/dsh-plugin-hunyuan-image
- 目录页：skillhub.cn 插件页
插件依赖 Node ≥ 20，无原生二进制依赖，可在 macOS、Windows、Linux 上运行。文档提供英语及另外 7 种语言（含简体中文）。DSH 社区插件目录为独立站点，与 DeepSeek / 幻方无官方从属关系；安装前建议自行查看源码与许可证，插件以当前 DSH 进程权限运行。
核心功能¶
双模型¶
| 模型 ID | 能力概要 |
|---|---|
hy-image-v3.5-preview |
Chat/Messages 协议；多模态输入、多轮编辑、思维链改写；输出最高 4K（4096×4096） |
hy-image-v3 |
经典文生图；提示词改写；官方 37 种预设尺寸 |
官方两步尺寸选择¶
交互与腾讯 TokenHub 控制台一致：分辨率档位 × 宽高比。插件将选择转换为 API 所需的 WxH 字符串，并校验官方约束（v3.5：边长 [256, 8192]、面积 ≤ 16,777,216；v3.0：边长 [512, 2048]、面积 ≤ 1,048,576）。界面会显示即将提交的精确像素尺寸。
v3.5 支持 1K / 1.5K / 2K / 4K 及多种宽高比，另有 Auto（不传 size，由模型决定）。v3.0 支持 720P / 1K 等组合，或 Auto 从 37 种预设中选取。
批量生成¶
单次请求可并行生成 1 / 2 / 4 张图；结果逐张展示并带 1/4 类序号。部分失败时会单独报错。
本地图库¶
- 成功生成的图片自动落盘（纯 JS JSON 存储，无 SQLite、无原生模块）
- 缩略图网格与列表视图
- 关键词搜索（匹配原始 prompt 与改写后的 prompt），可按模型、时间范围筛选
- 详情抽屉展示完整 prompt、模型、尺寸、时间戳与本地路径
- 再次生成：一键回填当时的 prompt 与参数
- 多选批量删除（同时删除本地文件）、复制 prompt、复制图片
腾讯远程 URL 约 12 小时过期；插件会在生成后立即下载到本地，避免图库链接失效。
输出目录¶
默认 ~/Pictures/DSH-Hunyuan-Image，可在设置里通过系统文件夹选择器改为任意路径（建议非系统盘）。修改立即生效，无需重启插件。文件按 <文件夹>/<YYYY-MM>/ 分月存放。
参考图¶
支持从磁盘上传（转为 data URL）或公开 URL。v3.5 最多 20 张（每张 ≤ 20 MB）；v3.0 最多 3 张（每张 ≤ 10 MB）。
官方高级参数（会话级）¶
| 参数 | 适用模型 | 说明 |
|---|---|---|
seed |
两者 | 复现结果 |
footnote |
两者 | 水印脚注，≤ 16 字符，右下角 |
use_search_tool |
v3.5 | 出图前联网搜索增强 |
resize_max_pixels |
v3.5 | 限制大图参考图的 token 成本 |
revise |
v3.0 | 自动改写 prompt（约增加 11 s，默认建议开启） |
模型可调用工具¶
插件注册工具 hunyuan_generate_image。在对话中直接描述需求（例如「画一只猫」），模型可主动调用该工具出图。
安装与启用¶
官方推荐从 Release 安装预构建包，无需本地编译。
- 在 Releases 下载
dsh-plugin-hunyuan-image-1.0.0.tgz。 - 解压到固定目录，例如
~/dsh-plugins/：
mkdir -p ~/dsh-plugins
tar -xzf dsh-plugin-hunyuan-image-1.0.0.tgz -C ~/dsh-plugins
- 在 DSH 对话中让助手执行插件安装（使用
plugin_manager的install_bundle）：
Please install
~/dsh-plugins/packageas a DSH plugin (useplugin_managerwithinstall_bundle).
- 重启 DSH。
更完整的重装 / 新机器步骤见仓库内 INSTALL.md（含简体中文 INSTALL.zh-CN.md）。开发者也可在 Node ≥ 20、pnpm 环境下自行 pnpm build 并链入 profile，详见 README。
配置¶
获取 API Key¶
- 登录 腾讯云。
- 开通 TokenHub。
- 在 API Key 页 创建 Key（形如
sk-...）。 - 在 在线推理 → 视觉模型 为
hy-image-v3.5-preview与hy-image-v3开通后付费。
插件设置¶
打开输入框下方的 🖼 Hunyuan Image 面板 → Settings：
| 字段 | 说明 | 默认 |
|---|---|---|
| API Key | 上一步创建的 Key | — |
| Output folder | 本地保存路径 | ~/Pictures/DSH-Hunyuan-Image |
| Default model | hy-image-v3.5-preview 或 hy-image-v3 |
v3.5-preview |
| Default resolution | 见上文尺寸档位 | 1K |
| Default aspect ratio | 见上文宽高比 | 1:1 |
| Watermark footnote | 水印脚注 | 空 |
点击 Save，再用 🔌 Test connection 验证 Key。注意：图片实际保存在所选目录下的月份子文件夹中，而非根目录直下。
典型用法¶
面板出图¶
- 点击 Hunyuan Image 打开生成面板。
- 输入 prompt，选择模型、分辨率档位与宽高比，按需设置 batch（1/2/4）与高级参数。
- 生成完成后在图库中查看、搜索或「再次生成」。
对话内出图¶
在 DSH 对话中用自然语言描述画面；若助手具备工具权限，可调用 hunyuan_generate_image 完成出图，结果同样会写入本地图库与输出目录。
适用场景与注意¶
适合：已在 DSH 桌面端做对话或智能体开发、需要混元 Hy-Image 且希望尺寸选择与 TokenHub 一致、并要本地持久化与图库检索的用户。
注意：
- 调用 TokenHub 会产生云侧费用，需自行开通后付费并保管 API Key。
- 未实现能力以 README 中「Known limitations & roadmap」为准；本文仅描述当前 1.0.0 已实现行为。
- 插件与 DSH 同进程运行，安装 bundle 前请核对发布包来源与仓库 LICENSE。
结尾¶
dsh-plugin-hunyuan-image 把腾讯混元 Hy-Image-3.5-preview 与 Hy-Image-3.0 以原生 DSH 插件形式接入：官方尺寸交互、批量出图、本地图库与 hunyuan_generate_image 工具，并零原生依赖跨平台运行。进一步了解可访问 SkillHub 目录页 与 GitHub 仓库（含 8 语言 README）。
