zhp282515-wq/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，拿回一个真实落盘的 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 图片引用的、给模型阅读的摘要。

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

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

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

所有改动下一次生成立即生效，无需重启、无需重新挂载。插件在每次调用时实时合并配置， 优先级从高到低：操作者在补丁层写的 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 槽位、 渲染一个 <iframe>，原因有三：

• 打包版 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。

---

English