Agnes 生图 zhp282515-wq/dsh-plugin-agnes-image

dsh-plugin-agnes-image

DeepSeek Harness（dsh）的 Agnes 生图插件：一个给模型直接调用的 agnes_image 工具，外加一个设置页里的可视化控制台。

一个包，两半：

- 宿主半边 —— 注册 agnes_image 工具，并提供一小套仅监听本机的 HTTP 接口（设置、Key 管理、历史、生成）。
- 浏览器半边 —— 在「设置 → Agnes Image」里加一个分区，内嵌宿主半边提供的控制台页面。

零运行时依赖：只用 Node 内建模块 + 全局 fetch，要求 Node ≥ 22。

| 上游接口 | POST https://apihub.agnes-ai.com/v1/images/generations |
| 模型 | agnes-image-2.5-flash（默认）、agnes-image-2.1-flash、agnes-image-2.0-flash |
| 能力 | 文生图、图生图、多图合成 |
| 费用 | 撰写时全部档位与参考图免费 |

Agnes Image 控制台

你得到什么

一、工具。 模型调用 agnes_image，拿回一个真实落盘的 PNG，以及一份可以继续处理的 JSON。

| 参数 | 类型 | 必填 | 说明 |
| prompt | string | ✅ | 好用的结构：主体 + 场景 + 风格 + 光照 + 构图 + 质量要求 |
| size | string | | 档位：1K / 2K / 3K / 4K，默认 2K |
| ratio | string | | 1:1 3:4 4:3 16:9 9:16 2:3 3:2 21:9，默认 1:1 |
| model | string | | 单次覆盖已配置的模型 |
| images | string[] | | 参考图（图生图 / 多图合成）。本地绝对路径、http(s):// 或 data: URI |
| out | string | | 输出绝对路径。省略则写入配置目录，文件名 agnes-<时间戳>-<提示词摘要>.png |

返回 { ok, path, url, bytes, model, size, ratio, nativePixels, prompt, revisedPrompt, keySource }，并由 output.render 生成一段带 Markdown 图片引用的、给模型阅读的摘要。
其中 url、nativePixels、revisedPrompt 是可选字段：接口没给出时直接省略，因为输出 schema 每个字段只声明一个类型字符串（DSH 不接受 ['string', 'null'] 这种写法）。

二、控制台。 「设置 → Agnes Image」：

| 分区 | 作用 |
| 当前模型 | 选择工具默认使用哪个图像模型 |
| 默认参数 | 档位 + 画幅，并实时预览原生像素尺寸 |
| 输出 | 图片落盘目录，以及「打开文件夹」 |
| API 密钥 | 掩码指纹与来源；替换或清除已存 Key；测试连通性；跑一次真实生成来验证 |
| 高级 | 超时、重试次数、接口地址覆盖、历史开关 |
| 提示词预设 | 保存、复用、删除提示词模板 |
| 生成 | 完整工作台：预设、提示词、档位、画幅、模型、参考图上传、结果预览 |
| 历史记录 | 所有生成结果的缩略图画廊（工具调用的和控制台生成的都在内） |

控制台中英双语，用顶栏里的语言选择器切换。设置页的分区标签跟随 dsh 外壳自己的语言，所以分区会显示成 Agnes Image 或 Agnes 生图。跟随界面（默认）指「先跟外壳、再跟浏览器」；显式选 English 或 中文 会固定下来，并在重启后保留。

English console

English console

所有改动下一次生成立即生效，无需重启、无需重新挂载。插件在每次调用时实时合并配置，优先级从高到低：操作者在补丁层写的 config → 控制台保存的设置 → 内置默认值。

安装

本包没有发布到 npm，作为本地插件接进某个 dsh profile：

1. 克隆到任意位置
git clone <本仓库> /path/to/dsh-plugin-agnes-image

2. 链接进 dsh 实际运行的那个 profile
cd ~/.dsh/profiles/desktop # 换成你用的 profile
pnpm add "link:/path/to/dsh-plugin-agnes-image"

link: 必须写绝对路径。Windows 跨盘根本写不出相对路径，所以常见写法是 link:D:/dsh-plugin/dsh-plugin-agnes-image。不想用 pnpm 的话，目录联接（junction）同样可行：

New-Item -ItemType Junction
-Path "$HOME\.dsh\profiles\desktop\node_modules\dsh-plugin-agnes-image"
-Target "D:\dsh-plugin\dsh-plugin-agnes-image"

3. 登记 bundle。 只做链接是不够的。打开该 profile 的 package.json，把包名追加进 dsh.profile.bundles：

{
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-plugin-agnes-image"
]
}
}
}

链接了但没写进 dsh.profile.bundles 的包永远不会加载，而且 dsh 不会告诉你原因。

4. 重启一次 dsh。 之后宿主半边可以自行热重载，但浏览器半边是在启动时组装进 boot graph 的（见「踩过的坑」）。

卸载

从 dsh.profile.bundles 里删掉，移除依赖，再删链接。Windows 上删 junction 要用 cmd /c rmdir <链接> —— 不要用 Remove-Item -Recurse，它会穿透链接删掉你的源码。

API Key

lib/agnes.js 的解析顺序：

1. 插件 config 里显式传入的 apiKey
2. 环境变量 AGNES_AI_API_KEY，其次是 AGNES_API_KEY
3. config 指定的 key 文件
4. 按顺序第一个存在的默认 key 文件：
- ~/.dsh/agnes_key.txt
- ~/.agnes/api_key.txt

key 文件是纯文本，首尾空白会被裁掉。启动时插件会打印 [agnes-image] API key source: … —— 只打印来源，永不打印 key。

控制台可以代你把 key 写入文件（权限 0600），但永远不会把 key 读回页面： GET /agnes-image/state 只返回掩码指纹（sk-Wsd***J8FR）和来源描述，仅此而已。

别把 key 提交进仓库。 .gitignore 已经排除了 agnes_key.txt 和 .env。
上游也是同样的要求：不要把 API Key 放进公开仓库、前端代码或截图。

不想改任何文件时，设置环境变量 AGNES_AI_API_KEY 后重启 dsh 即可覆盖。

HTTP 接口

控制台就是一个普通网页配普通接口，所以它能做的一切都可以脚本化：

| 方法 | 路径 | 用途 |
| GET | /agnes-image/state | 控制台启动所需的全部数据：设置、Key 状态、模型目录 |
| POST | /agnes-image/settings | 打补丁式更新设置，返回新状态 |
| POST | /agnes-image/key | 写入或清除 API Key |
| POST | /agnes-image/test | {mode:"auth"} 列模型；{mode:"generate"} 真跑一次生成 |
| POST | /agnes-image/generate | 生成，并追加进历史 |
| POST | /agnes-image/upload | 暂存参考图 |
| GET | /agnes-image/history | 历史，最新在前 |
| POST | /agnes-image/history/clear | 清空历史（不动磁盘上的图片） |
| GET | /agnes-image/image?path=… | 回传生成的图片 |
| POST | /agnes-image/reveal | 用系统文件管理器打开输出目录 |
| GET | /agnes-image/console | 控制台页面本身 |
| GET | /agnes-image/console.css、/agnes-image/console.js | 它的静态资源 |

这些路由不继承 dsh 自己 /api 的同源防护（exact 匹配会赢过它的 prefix），所以插件自己实现检查：Host 必须是环回地址，sec-fetch-site: cross-site 一律拒绝，存在 Origin 时必须与 Host 完全一致。缺失 Origin 是允许的，这样 curl 和脚本仍可用。
另外 GET /agnes-image/image 只允许配置的输出目录之内、或历史记录中出现过的路径，所以这个路由变不成任意文件读取。

curl -s http://127.0.0.1:19387/agnes-image/state

curl -s -X POST http://127.0.0.1:19387/agnes-image/generate \
-H 'content-type: application/json' \
-d '{"prompt":"一盏红纸灯笼悬在静止的黑水之上","size":"1K","ratio":"16:9"}'

目录结构

dsh-plugin-agnes-image/
├── package.json dsh.bundle.patch 与 dsh.client 是两个关键字段 ├── cordis.patch.yml bundle 层：一条纯 insert，写上行名 ├── lib/ │ ├── index.js 插件入口：apply(ctx, config) → ctx.tools.register(…)
│ ├── agnes.js 纯客户端：key 解析、请求、重试、下载、落盘 │ ├── settings.js 默认值、校验、原子持久化 │ ├── history.js JSONL 生成日志 │ └── routes.js HTTP 接口，含同源防护 ├── client/index.js 浏览器半边：只注册一个 settings.section ├── console/ 控制台页面：纯 HTML / CSS / DOM，无构建步骤 │ └── tokens.css dsh 自己的设计 token，让控制台看起来是原生的 ├── test/ node --test，不联网 └── scripts/ 手动执行、会打真实接口的冒烟脚本

为什么控制台是个 iframe

浏览器半边本来可以写成一个原生 React 面板。它现在只是注册一个 settings.section 槽位、渲染一个 ，原因有三：

- 打包版 dsh 对第三方客户端 bundle 没有 HMR。 浏览器半边每改错一次就要重启整个应用，所以这一半被压到尽可能小，真正的界面放在可以随时刷新的地方。
- 槽位本身只依赖 react。不依赖 client store、不依赖 UI-primitives 的组件签名、也不依赖会在版本间漂移的样式约定。
- 它就是一个普通 URL：可以在标签页里打开、刷新，开发时还能用无头浏览器截图。

为什么控制台长得像设置页

它穿的是 dsh 自己的设计 token，而不是自带的配色，所以看起来就是设置面板里的又一个分区，而不是一个外挂网页。

console/tokens.css 是宿主 --dsw-static- 调色板与浅色/深色两套 --dsw-alias- 别名的逐字副本。console.css 把一套简短的内部变量（--bg、--panel、--text、--accent …）
映射到这些别名上，于是整页换肤只改一个块。布局不依赖任何具体颜色；单列满宽卡片意味着没有卡片会被挤在更矮的邻居旁边，也不会被吸顶元素盖住。

页面被嵌入时，console.js 会从宿主文档重新读一遍这些 token 并覆盖副本，所以之后被重新配色的 dsh 会连带把控制台一起换掉。这个同步用的是一份白名单（只含样式表真正消费的 token）——固定清单不会顺手捎上某个无关属性把整页刷成别的样子。

踩过的坑

- response_format 必须放在 extra_body.response_format。 放请求体顶层会被拒；上游文档对此有明确警告。
- 图生图走 extra_body.image（字符串数组）。不要传 tags: ["img2img"]。
- 优先传档位而不是精确像素。 1920x1080、2560x1440 不是原生尺寸，会被标准化（通常落到 16:9 的 1K 1312x736）。应该请求 size:"2K" + ratio:"16:9" 再在下游裁剪。
返回里的 nativePixels 会告诉你接口实际给了什么。
- agnes-image-2.0-flash 其实也接受 size + ratio，尽管它的文档只列了 size 并只给精确像素示例。已实测：1K/16:9 生成后读 PNG 头，得到 1312x736。
- 重试覆盖 408 409 425 429 500 502 503 504，指数退避
min(1500 × 2^(n-1), 30s)；其余状态码是明确答复，不重试。
- revisedPrompt 在这个接口上恒为空字符串，不要依赖它。
- 打包版 dsh 里第三方客户端 bundle 无法热重载。 HMR 只在 dsh 从源码 checkout 跑、且有 pnpm run dev:web 在监听时才存在。新增或修改 dsh.client 需要重启。
- 不要 import @deepseek-ai/dsh-settings。 在 0.2.0-rc.2 上这个服务既没有
settings.register(namespace, …) 也没有 settings.get(namespace)；模块级缺失导出会直接
杀掉整个插件加载。设置改走插件私有存储：~/.dsh/agnes-image/settings.json，原子写（临时文件 + fsync + rename），权限 0600 —— 这也是本机上每个第三方插件实际都在用的做法。
- 同一个值绝不要混用两条持久化路径。 宿主的 config schema / 补丁层与插件私有存储是两个写入者，会互相覆盖。
- 浏览器半边只能用相对 URL。 环回端口是随机的（--port 0），每次重启都变，所以任何东西都不能按 origin 记忆。
- 槽位注册里的 label 是函数，每次投影都会重读，不是字符串。

开发

node --test test/.test.mjs # 54 项测试，不联网，不需要 dsh

测试覆盖的都是「出错时要么静默、要么危险」的部分：同源防护、设置的校验与往返、历史对损坏行的容忍、原生像素表自身的自洽性，以及浏览器半边的 loader 信封与槽位注册（在 vm 里配一个桩外壳执行）。

test/i18n.test.mjs 值得单独说一句：它把 console.js 当文本读，一旦出现漏译、只有 en 没有 zh 的键、某一语言多出或少掉 {placeholder}、没人引用的死条目，或者藏进字符串字面量 / CSS content: 里的用户可见句子，就让构建失败。
最后两类真的发过一次，是靠肉眼看截图发现的——这种 review 不该靠人工。

冒烟测试会打真实接口，手动执行：

node scripts/smoke-text-to-image.mjs
node scripts/smoke-image-to-image.mjs <reference.png>
node scripts/smoke-tool.mjs

迭代控制台时完全不必启动 dsh：这个页面由插件自己的路由提供，可以独立跑，并且读写的就是同一份设置文件：

node scripts/preview-console.mjs # http://127.0.0.1:8791/agnes-image/console
node scripts/preview-console.mjs --port 9000

然后截图：

chrome --headless=new --disable-gpu --hide-scrollbars \
--window-size=1500,1420 --virtual-time-budget=9000 \
--screenshot=console.png "http://127.0.0.1:8791/agnes-image/console?theme=dark&lang=zh"

?theme=light|dark 覆盖配色；不带则跟随操作系统。宿主内嵌该页面时会把外壳主题传进去，因为在 iframe 里 prefers-color-scheme 跟的是操作系统而不是应用。?lang=en|zh 同理，但只在保存的偏好是「跟随界面」时生效——显式选择永远压过外壳的提示。

许可

MIT —— 见 LICENSE。