dsh-sense-img:原理与使用
这是一个 DeepSeek Harness 插件,把商汤的生图接口接成 Agent 工具。设置里保存多个账号,Agent 调用 generate_image 时使用当前账号,生成结果保存到工作目录并显示在对话里。
插件由哪几部分组成
| 部分 | 文件 | 职责 |
|---|---|---|
| Host 半 | index.js | 声明配置结构,注册 generate_image 工具,解析账号与密钥,发请求、下载图片、落盘并返回结果。 |
| 浏览器半 | client.js | 在「设置 → 图片生成」渲染账号列表与编辑表单,读写配置、管理密钥。 |
| Bundle patch | cordis.patch.yml | 向 profile 插入一行插件记录,行 id 为 dsh-sense-img。 |
| 显示资源 | locale/、icon.svg | 插件标题、描述与图标。 |
插件没有 npm 运行时依赖,也不需要构建。Host 半用运行中的 DSH 自带的 @deepseek-ai/schemastery 构造 Config,浏览器半只依赖 react。
一次生图的完整链路
- 模型按工具定义调用
generate_image,参数是prompt,可选size和account。 - Host 按
account匹配账号;没传就用activeProfileId。账号里有请求地址、模型和密钥引用名。 - 通过 DSH 的凭证服务按引用名取出真实 API Key。配置里始终只有引用名,没有密钥值。
- 向账号的请求地址发
POST,请求体{ model, prompt, size, watermark: false },请求头Authorization: Bearer <API Key>。 - 解析响应里的图片地址或 base64,必要时下载图片,并校验确实是 PNG/JPEG/WebP/GIF。
- 把图片存进 DSH 附件库,同时写到会话工作目录的
generated-images/。 - 返回文字结果和保存路径;当前模型支持图片输入时,再附带一个图片块,对话里就能直接看到图。
请求超时和默认尺寸都能在设置页改,保存后立即生效,不需要重启。工具每次被调用时都会重新读取当前配置和密钥。
配置与密钥分别存在哪
| 数据 | 位置 | 说明 |
|---|---|---|
| 账号列表、当前账号、默认尺寸、超时 | profile 的 Cordis 配置层 | 设置页写入,字段标记为热更新,下一次工具调用生效。 |
| API Key 值 | DSH 凭证存储 | 账号里的 apiKeyEnv 只是引用名,例如 SENSENOVA_API_KEY。 |
| 生成图片 | 附件库与工作目录 | 附件库用于对话展示,文件用于本地使用与留档。 |
所以把仓库公开、把配置复制给别人,都不会带出密钥。
安装与首次使用
- 克隆仓库:
git clone https://github.com/HuoGu-Hub/dsh-sense-img.git。 - 打开 DSH 的 设置 → 插件,把
dsh-sense-img目录作为插件添加。 - 刷新一次页面。侧栏「设置」里出现「图片生成」,Agent 工具列表里出现
generate_image。 - 打开 设置 → 图片生成。默认账号已经指向
SENSENOVA_API_KEY,如果你之前配置过这个环境变量或凭证,会显示「密钥已设置」。 - 直接对 Agent 说「画一只橘猫」,或在对话里让它调用
generate_image。
多账号与额度切换
- 点「添加账号」,填写名称、模型、请求地址,粘贴该账号的 API Key,保存。
- 每个账号有自己的密钥引用,互不影响;点「切换至此」把某个账号设为当前账号。
- 工具也可以临时指定账号:传
account,值为账号 id 或名称。account不传时用当前账号。 - 删除账号时会先删除配置,再清理对应密钥;如果密钥清理失败,页面会提示它可能仍留在凭证库中。
工具参数
| 参数 | 必填 | 说明 |
|---|---|---|
prompt | 是 | 画面描述,主体、风格、构图、光线都可以写进去。 |
size | 否 | 形如 1024x1024;不传时用设置页的默认尺寸。 |
account | 否 | 账号 id 或名称;不传时用当前账号。 |
调用示例:
{
"prompt": "a red apple on a white table, soft studio lighting",
"size": "1024x1024"
}
结果与限制
- 图片保存为
<会话工作目录>/generated-images/dsh-sense-img-<时间>-<随机>.png。 - 如果当前模型不声明图片输入,工具只返回保存路径,不附带图片块;换成支持图片的模型就能直接看图。
- 接口只支持文本生图:请求体固定为
model、prompt、size、watermark,不支持参考图、批量生成、局部编辑。 - 请求固定带
watermark: false,生成的图片不带服务商水印。
常见问题
| 现象 | 处理 |
|---|---|
| 设置里没有「图片生成」 | 确认插件已启用,然后刷新页面;Host 半已加载但页面需要刷新才能拿到新的设置页。 |
| 卡片显示「未设置密钥」 | 点「编辑」,把该账号的 API Key 粘进去保存。 |
| 提示 401 或 403 | 密钥错误或已过期,重新填写;也可能是该账号没有这个模型的权限。 |
| 提示 402 或 429 | 额度不足或被限流,点「切换至此」换另一个账号。 |
| 只有路径,没有图 | 当前对话模型不支持图片输入;图片已经保存,可换支持图片的模型再生成。 |
| 移动了插件目录后失效 | 插件以本地目录链接的方式安装;移动后需要在设置 → 插件里重新添加新路径。 |
维护
插件是无构建的原生模块:改完 index.js 或 client.js 后,Host 侧在下次 profile 重组时加载新模块,浏览器侧刷新页面即可。配置文件不含密钥;如果怀疑密钥泄漏,在凭证库里删除对应引用并重新添加即可,不需要改代码。