Agnes 画笔 Naskete/dsh-agnes-image

dsh-agnes-image

给 DeepSeek Harness 装一个会画图的大脑：说一句话，出图。 文生图 / 图生图 / 多图合成，基于 Agnes AI（agnes-image-2.5-flash）。零依赖，纯 JavaScript，无需构建。

Image generation for DeepSeek Harness — text-to-image, image-to-image and multi-image composition via Agnes AI. Zero dependencies, no build step.

关键词 / Keywords：dsh dsh-plugin deepseek-harness 生图 文生图 图生图 图片生成 图片编辑 Agnes agnes-image-2.5-flash image-generation text-to-image image-to-image

一只正在画布前作画的鹈鹕，由本插件调用 agnes-image-2.5-flash 生成（1K / 16:9）

非官方社区插件，与 DeepSeek、Agnes AI 均无隶属关系。MIT 许可，无担保。
Unofficial community plugin, not affiliated with DeepSeek or Agnes AI. MIT, no warranty.

30 秒看懂

| 你想干什么 | 你就这么说（不用记命令） |
| 凭空画一张 | 「画一张夕阳下的海，电影感，16:9」 |
| 改一张现有的图 | 「把 D:\shots\cat.png 改成赛博朋克夜景，保留构图」 |
| 用好几张图合成一张 | 「用这两张做海报：第一张是角色，第二张是产品」 |

模型会自动调用本插件的工具 agnes_generate_image，把图存到你的工作目录，并直接显示在对话里。

你的项目\
└── generated-images\
└── 2026-10-10\ ← 按日期分文件夹，不会堆成一坨 ├── a-cheerful-pelican-120933.png └── a-cheerful-pelican-120945.png ← 一秒内连画两张也不会互相覆盖

这是什么？（完全没接触过也能看懂）

三个名词，一句话一个：

| 名词 | 说人话 |
| DeepSeek Harness（DSH） | 你正在用的这个 AI 助手客户端。它有「手」——能读写文件、跑命令——但出厂时不带画图能力 |
| 插件（plugin） | 给 DSH 装的一个小零件，装完它就多一项本事。本插件加的是一把「画笔」 |
| Agnes AI | 一家提供 AI 画图接口的服务商（类似「云端画师」）。你把描述发给它，它把图发回来。图像模型目前免费 |

流程就是这样：

你说话 → DSH 里的模型理解意图 → 调用本插件的工具 → 插件把描述发给 Agnes → 拿回图片 → 存到本地 + 显示在对话里

它能做什么：文生图、图生图（改风格/换背景/局部改）、多图合成。
它不能做什么：视频、图库管理、批量队列、在线编辑器。

手把手安装（照着做，10 分钟）

准备清单

- [ ] 一个能正常对话的 DeepSeek Harness（桌面版或命令行版都行）
- [ ] 一个 Agnes AI 账号（注册免费）
- [ ] 大约 10 分钟

第 1 步：确认 Harness 能用

先随便跟它说句话，能正常回复就跳过这一步。

没有 Harness？

- 桌面版：去 deepseek.com/harness 下载安装包（Windows / macOS），自带运行环境，不用预装任何东西
- 命令行版：先装 Node.js（要求 ^22.19.0 或 >= 24），然后在终端跑 npx @deepseek-ai/dsh web

两个版本可以共存、共用会话记录，但插件要各自安装一次。

第 2 步：申请 Agnes API Key（就是一把钥匙）

1. 打开 agnes-ai.com，注册 / 登录
2. 进入开发者控制台
3. 找到 API Key 管理，点「创建」
4. 复制那串 sk- 开头的长字符串

⚠️ 两个最常见的新手错误：

- ❌ 复制的是你给 Key 起的名字（比如 my-image-key）→ ✅ 要的是创建时那串 sk-... 的值
- ❌ 关掉弹窗才想起来没复制 → ✅ 大多数平台只显示一次，看不到就重新创建一个

把它先粘贴到记事本里，第 4 步要用。

第 3 步：安装插件

方式 A：命令行（推荐，最不容易踩坑）

打开终端（Windows 用 PowerShell），执行其中一条：

从 GitHub 装（本项目发布后）
dsh plugin --profile web add github:Naskete/dsh-agnes-image

从本地目录装（自己 clone 下来或者别人给你的文件夹）
dsh plugin --profile web add D:\path\to\dsh-agnes-image

从压缩包装（Release 里下载的 .tgz）
dsh plugin --profile web add D:\path\to\dsh-agnes-image-0.1.0.tgz

--profile 后面填哪个？桌面版通常是 desktop，命令行版通常是 web。不确定就跑这条看：

dsh plugin --profile web list

✅ 成功的标志：命令跑完没有报错，list 里能看到 dsh-agnes-image。

方式 B：图形界面

1. 打开 Harness → 左侧边栏 「插件」
2. 右上角 「+ 添加插件」
3. 输入框里填 dsh-agnes-image（npm 包名），或本地文件夹的绝对路径
4. 点「安装」，等进度跑完界面在安装前会先联网查一次包信息，这一步只认 npm 上的包。
填 github:... 地址会卡在这里 —— 那种情况请走方式 A。

装完还想卸载？

dsh plugin --profile web remove dsh-agnes-image

第 4 步：把 Key 填进去（三选一）

方式 ①：写进密钥文件（最推荐 —— 不用重启、不会误传上网）

新建文件（Windows：C:\Users\<你的用户名>\.dsh\agnes-image.config.json，macOS / Linux：~/.dsh/agnes-image.config.json），内容就一行：

{ "apiKey": "sk-你的Key" }

插件每次调用都会重新读这个文件，所以换 Key 不需要重启 Harness。
它不在插件仓库里，也不会被提交到 git（仓库的 .gitignore 已排除）。

方式 ②：环境变量（适合多个配置档共用）

Windows（永久生效，但必须重启 Harness） setx AGNES_API_KEY "sk-你的Key"

macOS / Linux
export AGNES_API_KEY="sk-你的Key" # 写进 ~/.bashrc 或 ~/.zshrc 可长期生效

⚠️ 环境变量只在程序启动时读一次，所以设完必须重启 Harness。

方式 ③：写在插件配置里（适合只有这一个配置档）

编辑 ~/.dsh/profiles/<你的profile>/cordis.patch.yml，加入：

- id: agnes-image
name: dsh-agnes-image
config:
apiKey: sk-你的Key

⚠️ 这种写法会让 Key 留在配置文件里。如果这个文件会被同步或备份到别处，请改用方式 ①。

第 5 步：重启 Harness

改完配置后重启一次（桌面版注意：点窗口右上角的 X 只是最小化到托盘，要右键托盘图标 → 退出，再打开）。

只有用「方式 ① 密钥文件」时才可以跳过这步。

第 6 步：验证

对 Harness 说一句：

画一张：一只戴耳机的小熊猫在画画，扁平插画风格

✅ 成功的标志（三个都对才算成功）：

1. 它没有说「我没有画图能力」，而是去调用了 agnes_generate_image
2. 图片直接显示在对话里
3. 工作目录下出现 generated-images/<今天日期>/xxx.png

❌ 如果报 Agnes API key is missing → 回第 4 步，换方式 ① ❌ 如果报 401 / 403 → Key 值不对（多半填了名字），重新复制 ❌ 如果压根没这个工具 → 回第 3 步，并完全退出 Harness 再打开

怎么用

直接说话就行

你不需要记参数、不需要背命令。这几种说法它都能听懂：

- 「画一张海边日落的壁纸，16:9」
- 「来个插画：一只猫在开视频会议」
- 「给 README 配个头图，扁平风」
- 「把 D:\shots\room.png 改成雨夜赛博朋克，保留构图」
- 「用这两张图合成一张海报，第一张是主角，第二张是产品」

想精确控制？把参数说给它听

| 参数 | 怎么用 | 默认 |
| prompt | 必填，描述画面。写得越具体越好 | — |
| size | 清晰度档位：1K（快）/ 2K（清晰）/ 3K / 4K；也可写死尺寸如 1024x768 | 1K |
| ratio | 比例：1:1 3:4 4:3 16:9 9:16 2:3 3:2 21:9 | 1:1 |
| model | agnes-image-2.5-flash（默认，最新最强）/ 2.1-flash / 2.0-flash | 2.5 |
| image | 参考图：本地路径、公网链接、或 data:image/... | 无 |
| outputName | 指定文件名（不含扩展名） | 提示词自动生成 |

大白话对照：

| 你想要 | 就这么说 |
| 手机壁纸 | 「竖版，9:16」 |
| 电脑壁纸 | 「横版，16:9，2K」 |
| 头像 / 图标 | 「1:1，1K」 |
| 快一点 | 「1K 就行」 |
| 高清一点 | 「2K」|

三种玩法的区别

| 玩法 | 你需要给什么 | 插件怎么发请求 |
| 文生图 | 只说描述 | 只带 prompt（+ 尺寸比例） |
| 图生图 | 描述 + 一张参考图（路径或链接） | 参考图放进 image |
| 多图合成 | 描述 + 多张参考图 | 多张按顺序放进 image，顺序 = 你说的「第一张、第二张」 |

本地图片会被读出来换成 base64 再发出去（这是接口的要求）。
只支持 PNG / JPEG / WebP / GIF 四种格式，单张最大 12 MB —— 超大图先压缩一下。

出图尺寸对照表

| 比例 | 1K | 2K | 3K | 4K |
| 1:1 | 1024x1024 | 2048x2048 | 3072x3072 | 4096x4096 |
| 3:4 | 864x1152 | 1728x2304 | 2592x3456 | 3456x4608 |
| 4:3 | 1152x864 | 2304x1728 | 3456x2592 | 4608x3456 |
| 16:9 | 1312x736 | 2624x1472 | 3936x2208 | 5248x2944 |
| 9:16 | 736x1312 | 1472x2624 | 2208x3936 | 2944x5248 |
| 2:3 | 832x1248 | 1664x2496 | 2496x3744 | 3328x4992 |
| 3:2 | 1248x832 | 2496x1664 | 3744x2496 | 4992x3328 |
| 21:9 | 1568x672 | 3136x1344 | 4704x2016 | 6272x2688 |
想要 1920x1080 / 2560x1440 这类显示器分辨率？请用 2K + 16:9，再自己裁剪。
直接写 1920x1080，服务端会吸附到最接近的标准档位（画质不受损，只是尺寸不同）。

提示词怎么写（官方建议的模板）

| 场景 | 模板 |
| 文生图 | [主体] + [场景/环境] + [风格] + [光照] + [构图] + [质量要求] |
| 图生图 | [改动要求] + [新风格/场景] + [要加/要去的元素] + [必须保留的元素] |
| 多图合成 | 说明每张图的角色 + 图与图的关系 + 目标风格与构图 |

举例（图生图）：把白天街道改成赛博朋克雨夜，加霓虹招牌和湿地面反光，同时保留街道布局、相机角度和主要建筑形状。

安全与隐私（建议花两分钟看完）

你的 Key 会被怎么处理

- 插件只把 Key 放进 HTTP 请求头 Authorization: Bearer ...，发给你配置的 baseUrl（默认是 Agnes 官方地址）
- 不会写进日志、不会回显在对话里、不会写进生成的图片
- 报错信息里只会出现「去哪里放 Key」的路径，不会出现 Key 本身

你的图片和提示词去哪了

- 提示词、参考图、生成的图片都会经过 Agnes 的服务器（云端服务就是这么工作的）
- 生成结果的下载链接指向 Agnes 的对象存储，插件拿到后立刻下载到本地
- 不想让某张图上传？那就别把它当参考图。插件不会自动上传你工作区里的任何文件

本地文件什么时候会被读出来发出去

只有你（或模型替你）在 image 参数里明确写出路径时，插件才会读那个文件。为了防手滑和防提示词注入，插件设了三道闸：

1. 读出来先按文件头确认是图片（PNG / JPEG / WebP / GIF），不是图片直接拒绝—— 所以就算有人骗模型传 ~/.ssh/id_rsa，也不会被当成「参考图」发出去
2. 单张上限 12 MB，超了直接报错（本地文件要以 base64 内联，太大既慢又没意义）
3. data: 开头的内容只接受 data:image/...;base64,，其它类型一律拒绝

下载回来的图片同样有三道闸：只接受 http(s) 地址、有 64 MB 体积上限、响应内容按文件头/Content-Type 确认是图片才写入磁盘。

关于会话记录

DSH 会把对话原文存在本地（~/.dsh/sessions/）。你在对话里粘贴过的 Key 也在里面。所以：

- 不要把 ~/.dsh/sessions/ 提交到任何 git 仓库（本插件的安装已在 ~/.dsh/.gitignore 里加了忽略规则）
- 要彻底清理：去 Agnes 控制台吊销旧 Key 并新建一个，然后更新你的密钥文件

插件自己对系统的权限

它是一个普通的 DSH 插件：只做两件事——发 HTTP 请求、往工作区写图片文件。不执行 shell 命令、不 eval 代码、不装额外依赖、不读工作区以外的文件（除非你在 image 里指名）。

常见问题 FAQ

Q：要花钱吗？ A：插件本身免费开源；Agnes 的图像模型目前免费（官方定价页标注 $0）。以官方页面为准。

Q：一定要说「画一张」开头吗？ A：不用。「来个……」「配张图」「把这张改成……」都行，只要意图是出图/改图。

Q：必须联网吗？ A：必须。图片是在云端生成的。

Q：能一次生成好几张吗？ A：一次调用返回一张。想多张就多说几次，或者直接说「给我 3 个不同版本」，模型会自己调多次。

Q：图存哪儿了？会不会找不到？ A：存在你当前会话的工作目录下的 generated-images/<日期>/，文件名带时间戳。想换地方就改配置项 outputDir。

Q：可以画真实人物/品牌 logo 吗？ A：技术上可以描述，但请注意版权、肖像权和服务商的内容政策，别生成违规内容。

Q：能改我已有的照片吗？ A：可以（图生图）。把文件路径或链接一起给它就行。

Q：之前那张图还能再改一次吗？ A：能，它就在你的工作目录里。把那个路径再给它，或者直接用 @ 引用文件。

Q：生成的图有署名/水印吗？ A：插件不加水印；Agnes 侧的默认行为以服务商为准。

出错了？症状对照表

先做这三件事（能解决 80% 的问题）：

1. 完全退出 Harness 再打开（桌面版右键托盘 → 退出，点 X 只是最小化）
2. 确认 Key 读到了：让 AI 看一下 ~/.dsh/agnes-image.config.json 里有没有 apiKey
3. 确认网络通：curl https://apihub.agnes-ai.com/v1/models -H "Authorization: Bearer sk-你的Key"

| 你看到的 | 原因 | 怎么修 |
| 工具列表里没有 agnes_generate_image | 没装成功，或没重启 | 重装后完全退出 Harness |
| Agnes API key is missing | 三个地方都没找到 Key | 见「第 4 步」，方式 ① 最省事 |
| 401 / 403 | Key 的值不对 | 重新复制 sk- 开头的整串 |
| 404 | 模型名不认识 | 换 agnes-image-2.5-flash / 2.1-flash / 2.0-flash |
| 429 | 请求太频繁 | 等一会儿再试 |
| Invalid size / Invalid ratio | 参数写了不支持的值 | 尺寸用 1K~4K 或 宽x高；比例用表格里那 8 个 |
| Cannot read the reference image | 路径写错 / 文件不存在 | 用绝对路径，或改成公网链接 |
| is not a raster image | 参考图不是 PNG/JPEG/WebP/GIF | 换成这四种格式之一 |
| ... the limit is 12 MB | 参考图太大 | 先压缩，或改用公网链接 |
| Refusing to download a non-HTTP(S) | 服务端给了非法地址 | 重试；持续出现请提 issue |
| not an image | 下载回来的不是图片 | 重试；持续出现请提 issue |
| non-JSON body | 网络中间有代理/网关拦截 | 检查代理设置或换网络 |
| 生成要等 30 秒以上 | 正常 | 大部分时间花在云端生成。赶时间就用 1K |
| 装在桌面版却没用 | 桌面版和命令行版插件各自独立 | 给 desktop profile 也装一次 |

进阶：配置项

在你的 profile 里覆盖（~/.dsh/profiles/<profile>/cordis.patch.yml）：

- id: agnes-image
name: dsh-agnes-image
config:
apiKey: '' # 留空 → 环境变量 → 密钥文件 baseUrl: https://apihub.agnes-ai.com/v1 # 接口地址（国内备用：apihub.agnes-ai.cn） model: agnes-image-2.5-flash # 默认模型 outputDir: generated-images # 输出目录（相对会话工作区，可写绝对路径） timeoutMs: 300000 # 单次请求超时（毫秒），官方建议 60s–360s

| 字段 | 类型 | 默认 | 说明 |
| apiKey | string | 无 | 留空则按「环境变量 → 密钥文件」继续找 |
| baseUrl | string | https://apihub.agnes-ai.com/v1 | 末尾斜杠会被自动去掉 |
| model | string | agnes-image-2.5-flash | 调用时没指定就用它 |
| outputDir | string | generated-images | 相对会话工作区；实际落在其下的 <日期>/ |
| timeoutMs | number | 300000 | 超时后中止请求并报错 |

📌 写错配置项名字会直接报错（而不是被默默忽略）—— 这样你才能发现拼写错误。
📌 patch 是整体替换 config，不是逐项合并：覆盖时要重写所有你想保留的字段。

进阶：开发者

跑测试（完全离线：假 fetch、不需要 Key、不联网）
node --test # 33 个用例

语法检查
node --check index.js

改完代码想立刻看到效果（不重启 Harness）：在 profile 的 cordis.patch.yml 末尾追一段

- insert:
- id: agnes-image
name: dsh-agnes-image
config:
model: agnes-image-2.5-flash

前提是该 profile 的 dsh.profile.patchReload 是 live。
⚠️ 不要和 dsh plugin add 同时用：同一个插件插两行，工具会被注册两次。

仓库结构：

dsh-agnes-image/
├── index.js # 插件本体：一个 Host 工具 + Config 契约 ├── cordis.patch.yml # bundle 层：把插件行插进 Loader ├── package.json # dsh.bundle.patch / meta / icon ├── icon.svg # 插件卡片图标 ├── locale/{zh,en}.json # 插件卡片标题与描述 ├── test/ # node:test，离线运行 ├── docs/preview.jpg # README 配图（本插件生成的） ├── CHANGELOG.md # 变更记录 └── CONTRIBUTING.md # 贡献指南

设计说明（为什么这么写）

- 零依赖：只用 Node 内置模块。发布版 dsh 把 zod 之类的依赖藏在带哈希的 pnpm 路径下，从已安装的 bundle 里解析不到；自己实现 Standard Schema 契约反而更稳。
- response_format 必须放进 extra_body：Agnes 不接受请求体顶层的这个字段，参考图也必须走 extra_body.image。测试里有专门的断言盯着这点。
- 拿到图就立刻下载：服务端链接不保证长期有效，写进本地才是你的。同时注册为会话附件，这样对话里能直接看到图。
- 存到「会话工作区」而不是「进程目录」：DSH 宿主进程的工作目录往往是启动器的目录，不是你的项目目录。插件通过 workspaceRegistry 反查当前会话的工作区，查不到才退回到进程目录。
- 只有档位尺寸才搭配 ratio：1024x768 这种写死的尺寸已经确定了形状，再发比例会让服务端意图含混。
- 文件名安全：非法字符会被替换，Windows 保留设备名（CON、NUL、LPT1…）会自动改成 CON-image.png，避免写盘失败。
- Key 每次调用重新读：换 Key 不必重启。

许可证

MIT

相关链接

- DeepSeek Harness
- 插件打包与安装（官方教程）
- Agnes AI 文档
- Agnes Image 2.5 Flash 接口说明