DEV Community: Dogwind

One plugin, two surfaces: putting an image editor inside an agent's composer

Dogwind — Sat, 31 Oct 2026 09:57:30 +0000

Most "chat with images" flows assume the image is already finished when you send it. Mine usually isn't: I want to circle a face and say "this expression, but warmer", or mask a product and say "re-shoot it on a wooden table". Typing that description is slower than pointing at it.

So the plugin I built for DeepSeek Harness, dsh-img2img-config, adds a full-screen editor that opens on the images already staged in the composer. The editing itself was the easy part — canvas, markers, brush mask, resize. The interesting problem was the hand-off: how do the edits reach the model without turning the composer into a JSON dump?

This post is about that hand-off, plus the two surfaces the plugin ships and the host half that wires it to real provider credentials.

Two surfaces, one bundle

The package is one npm artifact with a browser half and a host half:

Browser half (./client): the composer dock + editor, and a Settings panel.
Host half (./index.js): the provider store and HTTP routes behind /dsh-img2img-config/*.

Installation is a bundle patch — the profile gets a row pointing at the package:

# cordis.patch.yml
- insert:
    - id: dsh-img2img-config
      name: 'dsh-img2img-config'

and package.json declares both halves:

{
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" },
    "client": {
      "inject": [
        "@deepseek-ai/dsh-client-locale",
        "@deepseek-ai/dsh-client-ui-slots",
        "@deepseek-ai/dsh-client-ui-conversation",
        "@deepseek-ai/dsh-client-ui-session",
        "@deepseek-ai/dsh-client-ui-settings",
        "@deepseek-ai/dsh-client-ui-theme"
      ],
      "platform": "web"
    }
  }
}

That dsh.bundle field is the part people forget. A plugin that only declares dsh.client is not installable — the client half has nowhere to attach. (I learned this the hard way; more in the last section.)

The dock renders nothing most of the time

The editor is a dock entry on conversation.input.dock. The rule that matters for a crowded composer: the strip renders nothing while the session holds no image drafts, so it never competes with the queue / todo / goal docks that may already be there. When there are image drafts, each one gets a chip; clicking a chip opens the editor.

Confirming the editor does three things:

exports the edited files (edited.png, plus marked.png when markers exist, plus a binary brush mask when strokes exist),
stages them as draft attachments, replacing the edited source,
hands the brief to the composer.

Step 3 is where the design questions are.

Hand-off, three options

If you read the image plus the instructions as "one message to the model", there are three shapes:

Write the instructions into the draft as text. Simple, but users hate it: a wall of coordinates in the input box they have to scroll past.
Attach the images and say nothing. The model gets pixels, not intent. "Warmer" doesn't survive.
Carry the instructions out-of-band and attach them as a file. The model still reads them; the human still gets a clean composer.

I went with a variant of 3 plus a reference chip. The composer shows one chip labelled with the edit summary. The chip owns a payload — the full brief text — and the model never sees the chip: at submit, the chip's codec expands it.

// src/client/brief-source.ts (trimmed)
export function briefSource(): TriggerSourceFace {
  return {
    trigger: '@',
    name: 'img2img-brief',
    order: 900,
    showGroupTitle: false,
    candidates: () => Promise.resolve([]),   // no menu rows
    onPick: () => undefined,
    codec: {
      // Projection used for copy, draft persistence, and "flatten to text"
      clipboardText: (ref) => {
        const first = ref.split('\n', 1)[0]
        return first === undefined || first === '' ? BRIEF_MARK : first
      },
      // The payload already IS the model text
      serialize: (ref) => Promise.resolve(ref),
    },
  }
}

Two details make this work in practice:

The first line is the marker. Every brief starts with [img2img] 图片编辑请求 · img2img-studio. That line is short, language-neutral as an identifier, and is exactly what the chip flattens to when the draft is persisted or copied. The rest of the brief never enters the draft.
Re-editing replaces, it doesn't stack. mergeDraft() removes the previous [img2img] … [/img2img] block (and the legacy  block from an older version), then appends the new brief. Your own typed text is left alone.

The same facts are also attached as a machine-readable file, img2img-manifest.json, next to the exported PNGs. So the model can read pixels and fields:

{
  "version": 1,
  "createdAt": "2026-10-27T09:12:44.183Z",
  "source": { "name": "table.png", "width": 1600, "height": 1200 },
  "size": { "width": 1024, "height": 1024, "mode": "cover", "changed": true },
  "bgRemove": { "requested": true, "localPreview": false, "tolerance": 18 },
  "erase": { "strokes": 2, "prompt": "replace the price tag with the same wood grain" },
  "markers": [
    { "id": 1, "x": 0.412, "y": 0.238, "text": "keep the glaze highlights here" }
  ],
  "files": { "edited": "edited.png", "marked": "marked.png", "mask": "mask.png" }
}

Marker coordinates are normalized percentages with the origin at the top-left, so a model that works in relative terms doesn't need the source resolution. And the brief closes with an explicit instruction to the generation provider:

按标记与掩码做局部重绘，再做整体 i2i；标记与掩码只用于定位，不要出现在成图里。
(Local redraw per mark and mask first, then a whole-image i2i. Marks and masks are for localisation only — never let them into the output.)

That last sentence is doing real work. Without it, models happily draw the numbered pins into the final image.

Degrading instead of crashing

The chip path depends on services owned by the harness (inputTriggers, conversation, session). Those are not guaranteed to be present, or present at the moment this plugin applies — a batched client boot can materialise a service after your apply. So the client half resolves them lazily and falls back:

No trigger registry (older client build, moved service): the same brief is written into the draft as text between [img2img] and [/img2img]. Re-editing replaces that block instead of stacking another one.
Service appears late: register the codec source in ctx.inject(['inputTriggers'], …) rather than reading it once during apply. A one-shot read on such a boot finds nothing and silently leaves an unexpandable chip behind.
Draft attachments unavailable: keep the dock, but the confirm path drops to the draft-line carrier.

None of these paths crash; they get less pretty. That's the trade I wanted: the editor is a convenience layer on top of the composer, not a new failure mode for it.

The settings surface: from a panel to real credentials

The second surface is a Settings panel that configures both halves of the toolchain: vision (dsh-vision-skill) and generation (this skill). The panel talks to the host half through the plugin's own routes, and the host owns a provider store at ~/.dsh/dsh-img2img-config/providers.json.

What the panel actually manages, briefly:

Three priority tiers (main / backup / fallback) with drag ordering — so "try ChatGPT web, then DashScope, then a local fallback" is a configuration, not code.
Per-channel model fallback chains — a provider can list several models; the script walks them on failure.
Arrears-aware probing — providers that report insufficient balance can be auto-disabled instead of retried into a wall.
A ChatGPT-web account store — the channel that drives a real browser session, with per-account quota state.

Saving writes each provider back into the matching skill's scripts/.env, so the skill's own scripts pick the settings up with no extra step. The mapping — which keys to write, which to delete, which to leave alone — lives in one planSync() function, which is also exported to an offline regression script (scripts/verify-catalog.mjs). That last part matters: the panel can be tested without a browser.

What shipping it actually took

The code was the fun part. Distribution was the humbling part:

dsh.client alone is not installable. The first version declared only the client half; the plugin resolved, but had nowhere to attach. dsh.bundle + cordis.patch.yml is what makes it a bundle.
Guessed peer upper bounds are a silent killer. I had >=4.0.0-rc <5 on the host package. That's a promise to be refused on the next major release — with no log line, because the harness refuses before importing your module. I dropped the upper bounds and pinned "no < in peer ranges" with a CI check instead.
Publishing needed three gates. Security-key 2FA, provenance (only from CI, via OIDC), and staged publishing for a brand-new package name. I wrote that one up separately: Three gates before your first npm publish.
Storefront metadata lives in your repo. A screenshots.json next to package.json (1–8 images, relative paths or GitHub-hosted URLs) is what gives the plugin page App Store-style screenshots; without it, the storefront falls back to scraping your README.

What I would change next

Make the brief locale-aware. The brief is written in Chinese today because the primary user is; a model-facing text probably should follow the session language, not the author's.
Version the manifest schema explicitly. version: 1 is there, but there's no migration path yet for when the editor grows a new operation.
Two carriers, one truth. The chip and the manifest file carry the same facts; I'd like to derive one from the other in exactly one place rather than keeping both builders in sync by hand.

The point of the plugin was to make "point at the image and describe the change" feel like part of writing, not a separate app. The dock and the chip get most of the way there; the degradation paths are what make it survive contact with a host that is still moving.

Package: https://www.npmjs.com/package/dsh-img2img-config
Repository: https://github.com/Dogwind221/img2img-studio/tree/main/plugins/dsh-img2img-config
Market entry: https://awesome-dsh-plugin.com/p/Dogwind221/img2img-studio--plugins-dsh-img2img-config/

Three gates before your first npm publish: 2FA, provenance, and staged releases

Dogwind — Mon, 26 Oct 2026 13:25:37 +0000

I published a small plugin to npm for the first time last week. It is a DeepSeek Harness plugin called dsh-img2img-config — a composer image editor plus a provider settings panel. The code was done in a day; getting it onto the registry took three separate attempts, each blocked by a different gate.

None of the errors said what the gate was for. They said things like EUSAGE, E403, and 404 Not Found — the last one while publishing a package that did not exist yet. This post is the write-up I wish I had found first.

Gate 1 — 2FA is a browser flow, not a code

The account had 2FA set up with a security key, not a TOTP app. npm publish does not ask for a six-digit code in that case, so the first attempt looked like this:

npm error code EOTP
npm error This operation requires a one-time password.
npm error Open this URL in your browser to authenticate:
npm error   https://www.npmjs.com/auth/cli/***

The URL is the actual gate. Open it in a browser that is already logged in to npm, confirm with the security key, and the waiting CLI continues. Two things make this confusing:

The URL is masked in non-interactive output. Run npm publish from a TTY and the prompt is obvious. Run it from a script, a background job, or an agent, and you get *** and no way to complete the flow. If you are automating, you cannot be the thing that authorizes a new package by hand — that is what trusted publishing is for (Gate 2).
An expired session token fails with 404, not 401. After the token in ~/.npmrc had been revoked, npm whoami returned E401 Unauthorized, but npm publish returned:

npm error 404 Not Found - PUT https://registry.npmjs.org/my-package - Not found

For a brand-new package name, the registry does not tell you whether the name is taken or whether you are simply not authenticated. It returns 404 either way. If a publish fails with 404 on a name you know is free, check npm whoami before you start debugging the package.

One more detail worth knowing early: npm is tightening bypass-2FA tokens — account changes first, direct publishing later. The deprecation notice points at gh.io/npm-gat-bypass2fa-deprecation.

Gate 2 — `provenance: true` cannot run on your laptop

The package had this in package.json:

{
  "publishConfig": {
    "access": "public",
    "provenance": true
  }
}

Locally that fails immediately:

npm error code EUSAGE
npm error Automatic provenance generation not supported for provider: null

null here means "I am not running inside a supported CI provider, so I have no OIDC identity to sign a build statement with". Provenance is a SLSA attestation: it says this tarball was built by this workflow, from this commit, in this repository. A laptop has no such identity to vouch for.

So you have two options, and they are not interchangeable:

Publish locally with --no-provenance. The package goes up without an attestation. Fine for a first version if you just need the name and a working tarball.
Publish from CI with --provenance and permissions: id-token: write. This is the one that produces the "Built and signed on GitHub Actions" badge on the package page.

The CI route is not much more work. A minimal workflow:

name: publish
on:
  workflow_dispatch:

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write          # required for provenance / trusted publishing
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          registry-url: https://registry.npmjs.org
      - run: npm install -g npm@latest   # OIDC publishing needs a recent npm
      - run: npm publish --access public --provenance

With that workflow present in the repository, configure the trusted publisher once:

npm trust github my-package \
  --file publish.yml \
  --repo my-org/my-repo \
  --allow-publish

npm trust list my-package then shows what you granted:

type: github
file: publish.yml
repository: my-org/my-repo
permissions: publish, stage publish

From that point on, a workflow_dispatch run publishes with a signed attestation and no long-lived token. That is the whole point: the gate moves from "a human proves presence with a security key" to "a workflow proves identity with OIDC".

You can check the result from the registry:

curl -s https://registry.npmjs.org/-/npm/v1/attestations/my-package@0.1.0 | jq '.attestations[].predicateType'
# "https://github.com/npm/attestation/tree/main/specs/publish/v0.1"
# "https://slsa.dev/provenance/v1"

Gate 3 — stage-only tokens and the `0.0.0-stage` placeholder

The first API token I created was allowed to publish, but only to the staging area. For an existing package that is fine — you stage a version, review it, approve it. For a package that has never been published, npm refuses:

npm error 403 Forbidden - PUT https://registry.npmjs.org/my-package
npm error Cannot publish "my-package": this token can only publish to a staging area,
npm error and "my-package" does not exist yet. Create it first with a direct-capable
npm error token, then use `npm stage publish`. (E_STAGE_REQUIRED)

The message is oddly specific and worth reading twice: the first publish of a name needs a direct publish capability. Staged publishing is a mechanism for subsequent versions.

What you get when a staged path does run is a placeholder version:

versions: ["0.0.0-stage", "0.1.0"]
_dist-tags: { latest: "0.1.0" }

0.0.0-stage is npm's own placeholder for staged publishing — its description literally reads "Temporary package placeholder for staged publishing". Do not unpublish it; it is the name reservation that lets the staged flow exist. Make sure you set latest to your real version:

npm dist-tag add my-package@0.1.0 latest

Useful commands from this family: npm stage publish, npm stage list, npm stage view <id>, npm stage approve <id>, npm stage reject <id>.

The part nobody warns you about: propagation is not instant

The CI run printed:

npm notice Publishing to https://registry.npmjs.org/ with tag latest and public access
npm notice publish Signed provenance statement with source and build information from GitHub Actions
+ my-package@0.1.0

Green checkmarks, + my-package@0.1.0, done — except the version was not on the registry yet. For a few minutes, GET /my-package/0.1.0 returned 404, latest still pointed at the previous version, and the tarball URL 404'd. npm says as much, one line earlier:

npm notice Your package is being processed and may take a few minutes to become available.

So if a "successful" publish does not show up immediately, wait and re-check the registry directly instead of re-running the publish:

curl -s -o /dev/null -w '%{http_code}\n' https://registry.npmjs.org/my-package/0.1.0

Checklist I now run before publishing anything

npm whoami — is the token still alive?
Is this the first publish of the name? Then plan for a direct/interactive publish, not a staged one.
Does package.json carry a dsh.bundle / framework manifest that the host can actually load? (For DeepSeek Harness plugins, dsh.client alone is not installable — the most common rejection reason on the community list.)
Are there guessed upper bounds in peerDependencies? A >=1.0.0 <2.0.0 on a host package becomes a silent refusal on the next major release. See deepseek-ai/deepseek-harness#10776 for the failure mode: the module resolves, apply() never runs, and the host logs nothing. Pin "no upper bounds" with a test rather than a comment.
Prefer the trusted-publisher path from day one: workflow + OIDC + --provenance. No stored token, and the supply-chain evidence is a side effect.

What actually shipped

Three attempts, one evening:

0.1.0 — published by hand, with browser authorization and no provenance.
0.1.1 — published from GitHub Actions through the trusted publisher, with a SLSA provenance attestation and a fixed peer range.

The gates are not arbitrary. 2FA asks "is a human here?"; provenance asks "which build produced this artifact, and can anyone check?"; staged publishing asks "is this name already owned, and by whom?". Each one is answered by a different mechanism, which is why the first publish feels like three unrelated failures instead of one publishing model.

The package: https://www.npmjs.com/package/dsh-img2img-config
The repository: https://github.com/Dogwind221/img2img-studio