dsh-plugin-agnes-image
DeepSeek Harness（dsh）的 Agnes 图像生成：提供 agnes_image 工具和设置页面控制台
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:zhp282515-wq/dsh-plugin-agnes-image#d053faa11dd6fd1099b294a7959ba68874c2192aPlugin Agnes Image 以 dsh-plugin-agnes-image 发布，当前版本为 1.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Agnes image generation for DeepSeek Harness (dsh):
a model-facing agnes_image tool, and a settings-page console for everything a
tool call should not have to carry around.
Two halves, one package:
agnes_image tool and serves a small loopback HTTP
API (settings, key management, history, generation).Zero runtime dependencies: Node built-ins plus the global fetch. Node ≥ 22.
| Upstream API | POST https://apihub.agnes-ai.com/v1/images/generations |
| Models | agnes-image-2.5-flash (default), agnes-image-2.1-flash, agnes-image-2.0-flash |
| Capabilities | text-to-image, image-to-image, multi-image composition |
| Cost | every tier and every reference image was free at the time of writing |
1. The tool. The model calls agnes_image and gets a real PNG on disk plus a
JSON result it can act on.
| Parameter | Type | Required | Notes |
|---|---|---|---|
prompt | string | ✅ | Structure that works well: subject + scene + style + lighting + composition + quality |
size | string | Tier: 1K / 2K / 3K / 4K. Default 2K | |
ratio | string | 1:1 3:4 4:3 16:9 9:16 2:3 3:2 21:9. Default 1:1 | |
model | string | One-off override of the configured model | |
images | string[] | Reference images for image-to-image or composition. Absolute local path, http(s)://, or data: URI | |
out | string | Absolute output path. Defaults to agnes-<timestamp>-<prompt slug>.png in the configured output directory |
Returns { ok, path, url, bytes, model, size, ratio, nativePixels, prompt, revisedPrompt, keySource },
and renders a model-readable summary that includes a Markdown image reference.
2. The console. Settings → Agnes Image:
| Section | What it does |
|---|---|
| Active model | Pick which of the three image models the tool uses by default |
| Defaults | Size tier + aspect ratio, with a live preview of the native pixel size |
| Output | Where PNGs are written, plus "Open folder" |
| API key | Masked fingerprint and source; replace or clear the stored key; test the connection; test with a real generation |
| Advanced | Timeout, retries, endpoint override, history on/off |
| Prompt presets | Save, reuse and delete prompt templates |
| Generate | A full workbench: preset, prompt, size, ratio, model, reference-image upload, result preview |
| History | A thumbnail gallery of everything generated, from the tool or from the console |
The console speaks English and Chinese, switched from the picker in its top
bar. The settings-section label follows the shell's own language, so the section
is listed as Agnes Image or Agnes 生图 depending on what dsh is using.
Auto (the default) means "follow the shell, then the browser"; an explicit
English or 中文 pins it and is remembered across restarts.
Every change takes effect on the next generation — no restart, no remount. The plugin merges its effective configuration at call time from (highest first) the operator's patch-row config, the console's saved settings, and built-in defaults.
This package is not on npm. Wire it into a dsh profile as a local plugin:
# 1. Clone anywhere.
git clone <this repo> /path/to/dsh-plugin-agnes-image
# 2. Link it into the profile that dsh actually runs.
cd ~/.dsh/profiles/desktop # or whichever profile you use
pnpm add "link:/path/to/dsh-plugin-agnes-image"
link: needs an absolute path. On Windows across drives a relative path cannot
be expressed at all, so link:D:/dsh-plugin/dsh-plugin-agnes-image is the normal
form. If you would rather not use pnpm, a directory junction works just as well:
New-Item -ItemType Junction `
-Path "$HOME\.dsh\profiles\desktop\node_modules\dsh-plugin-agnes-image" `
-Target "D:\dsh-plugin\dsh-plugin-agnes-image"
3. Register the bundle. The link alone is not enough. Open the profile's
package.json and append the package name to dsh.profile.bundles:
{
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-plugin-agnes-image"
]
}
}
}
A package that is linked but missing from dsh.profile.bundles will never load,
and dsh will not tell you why.
4. Restart dsh. Once. The host half then hot-reloads on its own, but the browser half is composed into the boot graph at startup (see Notes from the field).
Remove the entry from dsh.profile.bundles, remove the dependency, and delete the
link. On Windows, delete a junction with cmd /c rmdir <link> — not
Remove-Item -Recurse, which follows the link and deletes your source tree.
lib/agnes.js resolves the key in this order:
apiKey in the plugin configAGNES_AI_API_KEY, then AGNES_API_KEY~/.dsh/agnes_key.txt~/.agnes/api_key.txtA key file is plain text; surrounding whitespace is trimmed. On startup the plugin
logs [agnes-image] API key source: … — the source, never the key.
The console can write the key for you, at mode 0600. It never reads the key back
into the page: GET /agnes-image/state returns a masked fingerprint
(sk-Wsd********J8FR) and a source description, and nothing else.
Keep the key out of the repository.
.gitignorealready excludesagnes_key.txtand.env. Upstream asks the same: never put an API key in a public repo, in front-end code, or in a screenshot.
To override without touching any file, set AGNES_AI_API_KEY in the environment
and restart dsh.
The console is an ordinary web page talking to ordinary routes, so anything it can do is scriptable:
| Method | Path | Purpose |
|---|---|---|
GET | /agnes-image/state | Everything the console boots from: settings, key status, model catalog |
POST | /agnes-image/settings | Patch settings; returns the new state |
POST | /agnes-image/key | Store or clear the API key |
POST | /agnes-image/test | {mode:"auth"} lists models; {mode:"generate"} runs one real generation |
POST | /agnes-image/generate | Generate; appends to history |
POST | /agnes-image/upload | Stage a reference image |
GET | /agnes-image/history | History, newest first |
POST | /agnes-image/history/clear | Clear history (leaves the images on disk) |
GET | /agnes-image/image?path=… | Serve a generated image |
POST | /agnes-image/reveal | Open the output folder in the OS file manager |
GET | /agnes-image/console | The console page itself |
GET | /agnes-image/console.css, /agnes-image/console.js | Its assets |
These routes do not inherit dsh's own origin fence — exact matches beat its
prefix — so the plugin implements the check itself: the Host header must be
loopback, sec-fetch-site: cross-site is refused, and a present Origin must
match Host exactly. A missing Origin is allowed so curl and scripts keep
working. GET /agnes-image/image additionally refuses any path that is neither
inside the configured output directory nor present in the history, so the route
cannot be turned into an arbitrary file read.
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":"a red paper lantern over still black water","size":"1K","ratio":"16:9"}'
dsh-plugin-agnes-image/
├── package.json dsh.bundle.patch and dsh.client are the two fields that matter
├── cordis.patch.yml bundle layer: one plain insert naming the row
├── lib/
│ ├── index.js plugin entry: apply(ctx, config) → ctx.tools.register(…)
│ ├── agnes.js pure client: key resolution, request, retry, download, save
│ ├── settings.js defaults, validation, atomic persistence
│ ├── history.js JSONL generation log
│ └── routes.js the HTTP API, including the origin fence
├── client/index.js browser half: one settings.section registration
├── console/ the console page: plain HTML, CSS and DOM, no build step
│ └── tokens.css dsh's own design tokens, so the console looks native
├── test/ node --test, no network
└── scripts/ manual smoke tests that hit the live API
The browser half could have been written as a native React panel. It is a
single settings.section slot that renders an <iframe> instead, for three
reasons:
react for the slot itself. No client
store, no UI-primitives component signatures, no styling conventions that shift
between releases.It wears dsh's own design tokens rather than a palette of its own, so it reads as one more section of the settings panel instead of a bolted-on web page.
console/tokens.css is a verbatim copy of the harness's --dsw-static-* palette
and its light/dark --dsw-alias-* aliases. console.css maps a short internal
vocabulary (--bg, --panel, --text, --accent, …) onto those aliases, which
means the whole page re-skins from one block. Nothing in the layout depends on a
particular colour, and one column of full-width cards means no card can be
squeezed next to a shorter neighbour or clipped by a sticky one.
When the page is embedded, console.js re-reads those tokens off the host
document and writes the live values over the copy. A dsh that has since been
restyled therefore restyles the console with it. That sync uses an allow-list of
the tokens the stylesheet actually consumes — a fixed list cannot pick up some
unrelated property and repaint the page with it.
Things that cost time, written down so they cost nobody else any:
response_format must live in extra_body.response_format. At the top level
the request is rejected. The upstream docs warn about this explicitly.extra_body.image (an array of strings). Do
not send tags: ["img2img"].1920x1080 and 2560x1440 are not
native and get normalized (typically to 16:9 at 1K, 1312x736). Ask for
size:"2K" + ratio:"16:9" and crop downstream. The nativePixels field
reports what the API actually returned so you can check.agnes-image-2.0-flash accepts size + ratio too, even though its
documentation only lists size with literal pixel examples. Verified by
generating at 1K/16:9 and reading the PNG header: 1312x736.408 409 425 429 500 502 503 504 with exponential backoff
min(1500 × 2^(n-1), 30s). Everything else is a real answer and is not retried.revisedPrompt is always an empty string on this endpoint. Do not depend on it.pnpm run dev:web
watching. Adding or changing dsh.client needs a restart.@deepseek-ai/dsh-settings. On 0.2.0-rc.2 the service has no
settings.register(namespace, …) and no settings.get(namespace); a
module-level missing export kills the whole plugin load. Settings live in a
plugin-private store instead — a settings.json under ~/.dsh/agnes-image/,
written atomically (temp file + fsync + rename) at mode 0600, which is
what every installed out-of-tree plugin in this install actually does.--port 0) and changes on every restart, so nothing may be keyed to an origin.label in a slot registration is a function, re-read on every projection,
not a string.node --test test/*.test.mjs # 54 tests, no network, no dsh
The suite covers the parts that fail silently or dangerously: the origin fence,
settings validation and round-trips, history tolerance for corrupt lines, the
native-pixel table's internal consistency, and the browser half's loader
envelope and slot registration (executed in a vm with a stub shell).
test/i18n.test.mjs is worth a note: it reads console.js as text and fails the
build on a missing translation, a key with no zh counterpart, a {placeholder}
that exists in one language but not the other, a dead entry nobody references —
or a user-visible sentence hidden in a string literal or in a CSS content:.
Both of those last two shipped once and were caught by eye in a screenshot, which
is exactly the review that should not be manual.
Smoke tests hit the live API and are run by hand:
node scripts/smoke-text-to-image.mjs
node scripts/smoke-image-to-image.mjs <reference.png>
node scripts/smoke-tool.mjs
To iterate on the console, skip dsh entirely — the page is served by the plugin's own routes, so it can run standalone against the same settings file:
node scripts/preview-console.mjs # http://127.0.0.1:8791/agnes-image/console
node scripts/preview-console.mjs --port 9000
Then screenshot it:
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 overrides the palette; without it the page follows the OS.
The host passes the shell's theme when it embeds the page, because inside an
iframe prefers-color-scheme tracks the operating system rather than the
application. ?lang=en|zh works the same way, but only while the saved
preference is Auto — an explicit choice always wins over the shell's hint.
MIT — see LICENSE.