dsh-agent-prompt

Edit the AGENTS.md instruction files DeepSeek Harness actually loads —
user-global and per-workspace — from a panel in the GUI's left sidebar.
English | 简体中文

Agent Prompt — edit the AGENTS.md instruction files DeepSeek Harness
actually loads, from a panel in the GUI's left sidebar.

DSH seeds every session with workspace guidance taken from AGENTS.md-compatible
files: one user-global file plus a project chain. Those files normally get edited
in an external editor, in a terminal, one path at a time. This plugin puts them
in one page: a tree of every global and per-workspace instruction file on the
left, a plain text editor on the right, and a Save button that writes the exact
bytes the agent will read next session.

┌── Agent Prompt ────────────────────────────────────────────────────────────┐
│  Filter workspaces…    │  ~/workspace/dsh-plugins/AGENTS.md                │
│                        │    ┌───────────────────────────────────────────┐  │
│  GLOBAL                │    │ Save  Reload │ Undo Redo │ Wrap           │  │
│   ● User-global        │    ├───────────────────────────────────────────┤  │
│     ~/.dsh/AGENTS.md   │    │ # dsh-plugins                             │  │
│  WORKSPACES            │    │                                           │  │
│   ● dsh-plugins        │    │ Instructions for agents working in this   │  │
│   ○ harness  (new)     │    │ repository.                               │  │
│                        │    └───────────────────────────────────────────┘  │
│                        │      20 lines  531 chars                  Saved   │
└────────────────────────────────────────────────────────────────────────────┘

What it contributes

Those are host paths and stay absolute; the panel asks for them relative to
the document (AGENT_PROMPT_CLIENT_API, derived from AGENT_PROMPT_API by
clientPath() in src/protocol.ts). The distinction matters wherever the client
is not at the origin root: dsh-remote-control serves it at /s//,
and an absolute /api/… request would leave that prefix and be answered by its
host — a 200 text/html page that this panel would read as a body-less success
because request() tolerates a non-JSON body. test/protocol.spec.ts resolves
both forms against a mounted base to pin it.

Which files it edits, and why those

The host half resolves paths with the same rules as
@deepseek-ai/dsh-agent-instructions,
the package that loads these files. Its shipped defaults are
projectRootMarkers: ['.git'], instructionFileCandidates: ['AGENTS.md', 'CLAUDE.md']
and dshHome: $DSH_HOME || ~/.dsh; the agent-instructions row in
@deepseek-ai/dsh-base sets only maxBytes, so no path in this deployment is
overridden.

The tree shows the resolved absolute path for each node, and marks a file
not created when it does not exist yet — saving creates it. A workspace whose
project root differs from its directory (a monorepo package, say) is shown
against its repository root, not the package.

Only AGENTS.md is offered. The loader also accepts CLAUDE.md,
AGENTS.local.md and CLAUDE.local.md at every level of the project chain, and
edits them too. Those are out of scope here; this panel is deliberately one file
per scope.

The page

Registrations, both keyed agentPrompt:

The page title carries the panel's version and the author credit — Agent Prompt v0.1.2 Author: icrefin [icrefinai@gmail.com] — as a muted tag beside the
20px/500 title, matching dsh-skill-mgr and dsh-mcp-mgr.

Unlike those two, the number is inlined into the browser bundle at build time
rather than fetched from the host. The two halves of a plugin do not update
together: the browser bundle is re-imported the moment its revision changes,
while the host half is a boot-time ESM import that keeps serving the code the
process started with. A host-sourced tag therefore goes blank as soon as the
client gets ahead of the running host — which is exactly how this panel once
rendered a bare v. tsdown.config.ts reads package.json and defines
__DSH_AGENT_PROMPT_VERSION__; src/client/version.ts exports it, and the tag is
skipped when it is empty.

Selecting the row is ctx.layout.selectPanel('agentPrompt'), a lookup in the
live main registry, so the two share the id by construction. dsh.client.inject
orders the bundle after dsh-client-ui-sidebar and dsh-client-ui-layout, the
packages that declare those two slots.

Editor commands

The clipboard gets no buttons at all: ⌘X, ⌘C, ⌘V and ⌘A already reach
the focused textarea, and a toolbar duplicate of a working platform shortcut is
noise. What is left is exactly the set the textarea cannot reach by itself.

Style contract

The panel follows the workspace's STYLES.md:

• Colour is --dsw-alias-* only — the stylesheet contains no literal hex and
  no non-alias token. State chips are their state colour on a 10%
  color-mix(… transparent) tint; surfaces are bg-layer-1 (the tree column),
  bg-layer-3 (the editor field) and bg-module-platform (the filter, chips).
• Buttons are the contract's two families: neutral is a bare 8px/12.5px
  control that fills with interactive-bg-hover → -active, and the primary Save
  uses button-primary-fill/-hover with label-primary-foreground.
  brand-primary appears only as the :focus-visible outline — never as a fill.
• Type and geometry: 20px/500/28 title, 13px/20 intro, 11px chips; the header
  owns padding-top: 28px plus --dsh-frame-top-clearance under Darwin, and the
  page's horizontal rhythm is clamp(24px, 4vw, 48px).
• color-scheme: light dark on the page root, with no dark-mode overrides: the
  tokens carry both modes.

The two-pane body is the one deliberate departure: the contract describes a
centred 960px column page, which would starve a tree-plus-editor split. The header
keeps the contract's inset so the title lines up with its sibling panels, and the
body is full-bleed beneath it.

The editor is a plain monospace ``: no Markdown preview, no syntax
highlighting. Switching files with unsaved changes asks first, and closing the
window with unsaved changes triggers the browser's own unload prompt. Saving or
reloading starts a fresh undo history, so Undo can never walk back to a body the
host never saw.

Install

The desktop profile is owned by the Electron application, so installs go through
Settings → Plugins (or the plugin-manager tool); dsh plugin add refuses that
profile.

pnpm install
pnpm build                              # tsc -> lib/, tsdown -> lib/client.js
npm pack --pack-destination dist        # dist/dsh-agent-prompt-0.1.2.tgz

Then add dist/dsh-agent-prompt-0.1.2.tgz from the Plugins page. The bundle is
recorded in the profile's dsh.profile.bundles and its cordis.patch.yml insert
row mounts the host half; the dsh.client manifest field loads the browser half.

Two operational notes:

• Reinstalling the same version is a no-op. pnpm sees an unchanged spec and
  leaves the extracted copy in node_modules alone, so a rebuilt tarball at the
  same version does not reach the profile. Remove the bundle first, then install
  it again — or bump the version.
• A first install needs no restart; an update of a loaded plugin does for
  host-side changes. On the first install the host routes mounted and the browser
  half registered as soon as the install finished, with no page refresh. After that
  the two halves diverge: the browser bundle is re-imported on its new revision,
  but the host half is a boot-time ESM import and keeps serving the code the
  process started with. A host-side change — a new route field, say — reaches the
  running app only on the next start; client-side changes never need one. This is
  upstream behaviour, not this plugin's: @deepseek-ai/dsh-hmr states that
  "replacing installed package versions still requires a restart". Restart if an
  entry reports failed to import.

HTTP API

Both routes are registered on ctx.webServer and carry a loopback-only fence:
the write route rewrites a file the agent reads as instructions, so a
LAN-exposed dsh web deployment must not serve it. Requests are additionally
capped at 4 MiB.

GET  /api/agent-prompt/tree
-> { dshHome, homeDisplay, global: Node, workspaces: Node[], skipped: string[] }

GET  /api/agent-prompt/file?key=global|ws:
-> { key, path, displayPath, exists, bytes, mtimeMs, content }

POST /api/agent-prompt/file   { key, content }
-> the same payload, re-read from disk after the write

Target keys are global and ws:. A workspace key must name a
registered workspace id — the panel cannot be pointed at an arbitrary path,
and an unknown id is a 404, not a filesystem probe. content is the whole file
body; a missing file reads as an empty string, and a write creates missing parent
directories.

Configuration

None. The plugin has no Loader config, no settings section and no stored state:
the files on disk are the state.

Architecture

The workspace registry is read through ctx.get('workspaceRegistry') rather than
a hard inject: without it the routes still mount and the global file still works,
and only the per-workspace targets answer 503.

Develop

pnpm install
pnpm check     # tsc (host + client) then vitest
pnpm build     # tsc -p tsconfig.build.json && tsdown
pnpm test

lib/ and dist/ are build products and are not committed.

Preview harness

tools/preview.mjs renders the built client bundle outside the GUI and
screenshots it: it loads lib/client.js through a stub window.__ModuleLoader__,
calls the plugin's apply with a minimal fake client context, mounts the main
entry, and replays a captured tree through a stubbed fetch.

node tools/preview.mjs --out /tmp/ap-preview      # writes index.html + panel.png
node tools/preview.mjs --open                     # ...and opens the PNG

It needs Google Chrome (or Chromium/Edge) on the host, plus the react and
react-dom dev dependencies (the UMD builds the harness page loads). This is how
the panel's layout and stylesheet are checked without a browser session in the
running app.

Verification

Run on this host against dsh 0.2.1-rc.3 (desktop profile desktop).

test/files.spec.ts (13 tests) exercises path resolution against a real temporary
filesystem — the $DSH_HOME precedence including the blank-string case, the .git
walk including the worktree .git-file form, and the missing-file/directory-in-file-
position cases. test/routes.spec.ts (10 tests) serves the real route handlers from
a real loopback HTTP server and drives them with fetch: tree shape, nested
workspace → repository root, read of a missing file, unknown target key, unknown
workspace, create-and-round-trip for both the global and workspace files, and the
method fence. Nothing about the handler bodies is stubbed. test/version.spec.ts
(2 tests) covers the one trap in the version module: it must stay importable where
the build-time define is absent. test/protocol.spec.ts (5 tests) resolves the
panel's request paths against a root base and against a mounted one, which is the
only check that would catch a request escaping a path prefix.

Not covered by an automated test: an end-to-end write against the live host (the
route tests write into a temporary directory instead, so no real AGENTS.md is
touched), and the platform clipboard shortcuts, which belong to the browser
rather than to this plugin.

Caveats

• AGENTS.md only — CLAUDE.md and the .local overlays are not offered.
• No live reload of external edits. The page reads a file when you select it
  or press Reload. If something else changes the file while the page is open,
  saving overwrites it; there is no mtime check or merge.
• The routes are reachable by any local process, like every other
  loopback-fenced plugin API in this composition. They are not covered by the web
  app's ?token= launch token, because named routes are matched before the
  authenticated SPA fallback.
• A pinned dshHome in the agent-instructions config would diverge from the
  panel's $DSH_HOME || ~/.dsh resolution. The shipped composition pins only
  maxBytes, so the two agree today.

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md
for the development setup and the sign-off expectation. Please report security
issues privately as described in SECURITY.md.

License

MIT — see LICENSE.

> If this panel saves you a trip to an external editor, a ⭐ star helps other DSH users find it.