dsh-acp-enhanced

中文 | English

dsh-acp-enhanced

An enhanced Agent Client Protocol (ACP) server for
DeepSeek Harness (dsh), built for ACP
editors like Zed. It is a drop-in replacement for the official @deepseek-ai/dsh-acp
bridge: the official bridge only streams plain text, this one exposes the Web GUI's
capabilities — streaming, telemetry, model/permission control, session management, MCP —
over the ACP wire.

Features

Output & telemetry

• Block + reasoning streaming: text blocks and the model's thinking arrive live
  (agent_message_chunk / agent_thought_chunk); cancelled/retried attempts never leak
  torn output. Set streamDeltas: true on the acp-enhanced row for token-level
  streaming instead — the reply renders while the model writes it, coalesced on a 75 ms
  timer; the trade-off is that a mid-block retry can no longer hide its abandoned
  partial text, so a visible _[stream interrupted — retrying]_ marker separates the
  seam (off by default)
• Full telemetry: context usage ring plus cache hit rate / TPS / input-output-reasoning
  tokens / tool timing / turn counts (usage_update._meta carries the full breakdown)
• Image support (multimodal): when the dsh composition mounts an attachment store
  (dsh 0.1.1-rc.2+ with dsh-attachment-local, the default in dsh-base), promptCapabilities.image
  is advertised and pasted/uploaded images are ingested into the harness's durable attachment
  store — a vision-capable model (e.g. deepseek-v4-flash-vision-exp) reads them natively,
  in wire order with surrounding text. Older stacks (no attachment store) automatically
  downgrade: image is not advertised and an image prompt is refused with a clear error.

Model & permissions

• Model switching: live provider/model catalog dropdown (ACP grouped-select wire shape)
• Reasoning effort: reasoning_effort dropdown — only when the routed model exposes
  selectable efforts; each model remembers the effort it last used (persisted per profile),
  so switching back restores it, and a first-time model falls back to its own default — or
  its first offered effort — instead of an empty "unknown" selection
• Permission presets: read-only / workspace-write / full-access session modes
• Approval: native allow-once / reject-once prompts per tool call
• Agent presets: per-session model-facing composition (tools + prompt sections)
  from the dsh agent-presets roster. standard is the full coding agent (default),
  minimal (极简模式) is a bare shell + files editor with no subagent/web/todo/plan
  tools — nothing from the host layer leaks into a minimal agent; code and cordis
  ship alongside, and your own presets under ~/.dsh/.agent-presets appear too.
  Choose via the agent_preset config option, the /preset command, or the
  DSH_ACP_PRESET env var (per-session default); switching is only allowed while the
  session is still blank (no turn has run), so history never straddles two tool sets.

Zed deep integration

• Tool cards: one-line summary in the collapsed header — Read <path>, the
  model's own intent line for shell commands (description, Codex-style — the
  exact command stays one click away), Search: <pattern>, Fetch: <url>, etc.
  The card body follows the ACP best practice: file edits render as a real
  diff, bash/pwsh commands as a real terminal card (codex-acp wire
  shape: command line + output + exit pill inside a terminal panel — no more
  raw-JSON cards), other executors as a syntax-highlighted code block, and
  touched files as clickable locations that open the file — with rawInput
  / rawOutput kept one click away for transparency, plus per-kind icons and a
  proper in-progress → completed/failed status lifecycle
• Zed files & terminal: zed_read_text_file / zed_write_text_file / zed_terminal
  put file edits into Zed's "edited files" area (diff + accept/reject) and commands into a
  real Zed terminal
• Native form questions: ask_user_question → elicitation/create form, click an
  option — or type a custom answer when none of them fit: options render with their
  descriptions, each option-backed question gets a free-text "Custom answer" field, and a
  custom answer replaces the single selection / accompanies a multi-select (same semantics
  as dsh's native question card)
• Plan panel: plan mode toggle → "planning" status bar in Zed

Sessions

• Resume & archive: session/load restores past threads (full replay);
  session/list / session/delete manage the thread archive (titled, sorted by last
  activity); live title updates
• Multi-root workspaces: sessionCapabilities.additionalDirectories is advertised,
  so Zed no longer shows "this agent doesn't currently support multi-root workspaces"
  and instead passes every workspace root on session/new / session/load. All roots
  are described to the model in the system prompt and reported on session/list; the
  sandbox keeps the primary cwd as its single writable root (see Known limitations)

Commands

• Slash commands: typing / reveals the command list (available_commands_update):
  /status shows the route and telemetry, /model lists or switches the model, /preset
  lists or switches the agent preset (listings render as monospace code blocks — readable
  at a glance), everything else (/compact /goal /permission /plan…) runs straight
  through the harness command registry — all executed without a model turn. Every
  user-invocable skill is advertised as a command too, so /ask-matt, /code-review,
  /tdd, … reach the bridge instead of being rejected by the editor, and the skill's
  instructions are injected into the message (dsh-tool-skill-style user invocation).
  Images pasted next to a slash line ride along as command attachments (e.g. reference
  screenshots for a /goal objective), the same way the Web composer submits them

MCP

• MCP servers: session/new mcpServers mount any MCP server (stdio + streamable
  HTTP); tools join as mcp__<server>__<tool>; a failing server never takes the session
  down

Preview

After picking dsh-acp-enhanced in Zed's AI Agent panel:

Quick start

This package follows the official dsh plugin conventions (it declares dsh.bundle), so
installation matches any official bundle: one command — auto-initializes the profile,
installs the package, appends the bundle layer; no profile YAML to write.

Install (2 steps)

Step 1 — install (from the npm registry; no source checkout needed):

dsh plugin --profile acp-enhanced add dsh-acp-enhanced

When hacking on the code, use link: to a local checkout instead (live edits):
dsh plugin --profile acp-enhanced add "link:/absolute/path/to/dsh-acp-enhanced"

Step 2 — register in Zed (under agent_servers in ~/.config/zed/settings.json;
Zed spawns agents with a minimal PATH, so use the shipped launcher
scripts/dsh-acp-zed.sh, which locates node/dsh itself)

The launcher ships with the package. Its absolute path depends on how you
installed in Step 1:

• npm install (default): $HOME/.dsh/profiles/acp-enhanced/node_modules/dsh-acp-enhanced/scripts/dsh-acp-zed.sh — replace $HOME with your home directory (e.g. /Users/you); Zed does not expand ~ or env vars, so write the full literal path.
• link: dev install: <your checkout>/scripts/dsh-acp-zed.sh.

Most common: DeepSeek official API (the default route)

{
  // ...your existing settings...
  "agent_servers": {
    "dsh-acp-enhanced": {
      "type": "custom",
      "command": "/bin/bash",
      "args": ["/absolute/path/to/dsh-acp-enhanced/scripts/dsh-acp-zed.sh"],
      "env": {
        "DSH_ACP_PROVIDER": "deepseek-official",  // the official provider id
        "DSH_ACP_MODEL": "deepseek-v4-flash",     // the official model id
        "DSH_ACP_PRESET": "standard"              // optional: agent preset id (minimal / standard / code / cordis / yours)
      }
    }
  }
}

Both env vars match the shipped patch's defaults, so they can be omitted entirely —
writing them out just makes the route explicit. DSH_ACP_PRESET defaults to standard
on the roster side; set it when you want every new session to start in a specific mode.
The API key does not have to live in Zed:
store it in ~/.dsh/.credentials.yaml (DEEPSEEK_API_KEY) and the dsh credentials
service resolves it; the launcher also falls back to a running dsh web process's key.

Debugging a stalled turn (is it the model request or the tool?):

"env": {
  // ...existing vars...
  "ACP_LOG": "/Users/you/.dsh/dsh-acp-enhanced.trace.jsonl"  // append-only JSONL event trace
}

Each line is one session event with wall-clock time (ms epoch); a turn that appears to
hang is attributable afterwards: a model request stall shows a long gap between
step/start and the first assistant/chunk, while a tool-execution stall shows a
long gap between tool/call and tool/result (the result line carries elapsedMs).
prompt/settled lines cover the full user-message round trip (stopReason + elapsed).

Optional: pin the panel's default config options (all still changeable in the panel):

"dsh-acp-enhanced": {
  // ...the type/command/args/env above...
  "default_config_options": {
    "model": "deepseek-official/deepseek-v4-flash",
    "agent_preset": "standard",
    "plan_mode": false,
    "reasoning_effort": "high"
  },
  "favorite_config_option_values": {
    "model": ["deepseek-official/deepseek-v4-flash", "deepseek-official/deepseek-v4-pro"]
  }
}

Extended: route through an OpenAI-Responses gateway (e.g. a company model gateway)

Same install path; only the env values change to the provider/model the gateway exposes
plus the key env var it requires:

"dsh-acp-enhanced": {
  "type": "custom",
  "command": "/bin/bash",
  "args": ["/absolute/path/to/dsh-acp-enhanced/scripts/dsh-acp-zed.sh"],
  "env": {
    "DSH_ACP_PROVIDER": "<gateway-provider-id>",  // provider id exposed by the gateway
    "DSH_ACP_MODEL": "<gateway-model-id>",         // model id exposed by the gateway
    "<KEY_ENV_NAME>": "<key>"                      // the key env var the gateway reads
  }
}

<KEY_ENV_NAME> can also be omitted and the key stored in
~/.dsh/.credentials.yaml instead.

Zed hot-reloads settings. Open the AI Agent panel (Cmd+Shift+A) → pick
dsh-acp-enhanced in the agent selector → send your first message: replies stream in
real time, the status bar shows context usage, the panel exposes Model / Permission preset
/ Plan mode options plus three modes, and the thread archive lists and resumes past
sessions.

Verify locally (no Zed needed):

node scripts/acp-client.mjs                    # official default route, no env; expect ALL CHECKS PASSED
DSH_ACP_PROVIDER=... DSH_ACP_MODEL=... node scripts/acp-client.mjs   # only for a custom route

Web search

The bridge ships no search provider and takes no position on which one you use: the
model-facing web_search tool rides on the web seam's searchProvider, so mount any
ctx.web provider into the profile — a package with dsh.bundle via
dsh plugin --profile acp-enhanced add <package>, or a plain package via your user-layer
insert rows (see below). Which provider exists in your dsh deployment is a profile
concern, not a bridge one.

Managing the profile's plugins

dsh-acp-enhanced runs in its own profile — acp-enhanced, created at
~/.dsh/profiles/acp-enhanced/ by the install command above — fully separate from the
web profile behind dsh web, so plugin changes here never affect your web setup.

The profile composes its plugin tree from three sources, each layer patching the ones
before it:

1. Bundle layers — dsh.profile.bundles in the profile's package.json: the
   template's @deepseek-ai/dsh-base first, then every installed package that declares
   dsh.bundle (like dsh-acp-enhanced), in array order.
2. Your user layer — ~/.dsh/profiles/acp-enhanced/cordis.patch.yml: id-targeted
   row config overrides, disabled: true row disables, and insert lists (how a
   package without dsh.bundle — e.g. a hand-mounted custom provider — gets
   mounted).
3. Per-run overlays — dsh --profile acp-enhanced --patch extra.yml.

Adjust the set with:

dsh plugin --profile acp-enhanced add <package>     # install; a dsh.bundle package auto-joins the layer stack
dsh plugin --profile acp-enhanced remove <package>  # uninstall; auto-leaves the stack
dsh plugin --profile acp-enhanced update [package]  # update one/all, then reconcile
dsh --profile acp-enhanced --dump-config             # inspect the composed tree (per-layer provenance)

dsh plugin is a thin pnpm forwarder (run inside the profile directory) that
reconciles dsh.profile.bundles against the installed state after every run. Two
consequences worth knowing:

• Disabling a bundle by deleting it from bundles does not stick — the package is
  still an installed dependency, and the next dsh plugin run appends it right back.
  To disable a single row without uninstalling, target it in the user layer by its
  row id (not the package name — find ids in the --dump-config output):

  - id: mnemon
    disabled: true
  

• A package without dsh.bundle loads nothing by itself — it installs as a plain
  dependency (with a one-time warning) and needs your own insert entry in the user
  layer. To change an existing row's config, override it with - id: <row> + config:
  — patch entries replace the whole row config, they do not merge.

Changes take effect in the next process: Zed spawns a fresh
dsh --profile acp-enhanced for every agent thread, so open a new agent thread (or
restart Zed) after editing the profile.

Compatibility

One bridge binary runs against every harness generation from 0.1.0-rc.6 through
0.1.2-rc.1. The 0.1.2 line rewrote three APIs this bridge consumes, and the
bridge absorbs every generation at runtime — no fork, no version flag:

API	≤ 0.1.1-rc.2 (legacy)	≥ 0.1.2-alpha.2 (projection)	Bridge behavior
running preset of a session	resolveSessionPreset({header, events}) export	export removed; agentPreset session projection	folds the log itself (last agent-preset/selected wins, header fallback) — identical semantics in both
preset resolution failure	UnknownPresetError / PresetMountError	RemoteError, codes agent-preset/*	isPresetClientError: RemoteError duck-typed by isDSHRemoteError + code, legacy classes identified structurally by presetId (never cross-copy instanceof)
permissionPresets.current(x)	current(events)	current(session) (via permissionState)	currentPermissionMode probes the service instance per call
session event log reads	synchronous session.events array	session.events removed (0.1.2-rc.1); snapshotEvents() / ownEvents() / eventAt()	sessionEventsOf reads snapshotEvents() when present, the live array otherwise
registry execute signature	execute(agent, line, signal)	execute(agent, line, images, signal) (images between line and signal, 0.1.1-rc.1+)	executeRegistryCommand probes the declared arity (the Remote decorator never wraps the method)
userQuestions registration	registerProvider({ask})	user-questions/request Cordis waterfall (0.1.2-alpha.2+)	probes the service instance; waterfall listener answers bridge-owned requests and delegates via next()

Two invariants make this safe (same conclusions the openma deepseek-harness-acp adapter
reached independently): value-import pure helpers only (createUserMessage,
ReasoningEffortId, SessionId, defineTool, … — a foreign copy is functionally
equivalent), and service-generation questions are answered by probing the service
instance, because the booting CLI — not this package's dependency range — decides the
service generation. dsh-agent-presets is imported as a namespace: 0.1.2-alpha.1
removed its named exports, and a named import would fail at ESM link time.

Check both generations from a clean tree:

node scripts/compat-check.mjs   # installs 0.1.0-rc.6 + 0.1.2-alpha.2+ sets, imports the bridge from each

Dev checkout: repo-pinned CLI, isolated home

When the launcher runs from a checkout (link: install), it resolves the dsh CLI in
this order:

1. $DSH_PATH — an explicit dsh binary, or a directory whose node_modules/.bin/dsh holds one
2. the repo-pinned CLI — <repo>/node_modules/.bin/dsh (this package's @deepseek-ai/dsh
   devDependency, currently 0.1.2-rc.1)
3. global fallback — dsh on PATH / npx cache / npm prefix (the legacy behavior; a fresh
   clone without pnpm install degrades to it)

Whenever (1) or (2) wins, the profile boots under an isolated home
(DSH_ACP_HOME, default ~/.dsh-acp): dsh heals its whole dependency closure into
$DSH_HOME/profiles/node_modules on every boot — a dir shared by every profile under that
home whose content flips to whichever CLI booted last — so a second CLI generation must not
share a home with e.g. a running dsh web. The default home is never touched by this path.
Harness-injected DSH_HOME=$HOME/.dsh in the child environment (dsh exports it into every
agent/tool process) is detected and overridden, not honored — only a DSH_HOME pointing
away from the default home is respected; to force the pinned CLI onto the default home,
set DSH_ACP_HOME=$HOME/.dsh deliberately.

Bootstrap the isolated home once (profile without dsh-mnemon — it does not support the
0.1.2-alpha harness — plus your old profile's user rows ported verbatim and credentials/settings
migration, the subagent-model-selection-settings host service the 0.1.2-alpha standard
preset requires, and the DeepSeek plugin-package inventory reporter disabled):

scripts/init-acp-home.sh            # idempotent; re-runs never clobber your files

Both harness generations persist sessions under $DSH_HOME/sessions/<slug>/<id>/session.jsonl.zstd, and the new generation reads old-generation logs (verified: history replay and the preset fold work cross-generation). Old threads therefore only need their session history copied to the new home — scripts/init-acp-home.sh prints the one-liner (or pass --copy-sessions); it copies nothing by default, because the default home's tree also holds every web-profile session.

Troubleshooting

Symptom	Fix
exec: dsh: not found (status 127)	Use the shipped dsh-acp-zed.sh launcher (locates node/dsh itself)
no API key for provider route "xxx"	Write ~/.dsh/.credentials.yaml, or set env.DEEPSEEK_API_KEY on the agent_servers entry
SyntaxError: ... 'PresetMountError'	You are running a pre-0.7.0 bridge copy against a 0.1.2-alpha host — update this package
modelSelectionSettings requires ... in the Host scope	A 0.1.2-alpha host without the subagent-model-selection-settings row — run scripts/init-acp-home.sh (or add the insert row to your user layer, see the script)
Old threads start empty after a host upgrade	The sessions live under $DSH_HOME/sessions/<slug>/; copy the old home's history to the isolated home (scripts/init-acp-home.sh --copy-sessions) and the new host resumes them
Cannot switch models	The saved reasoning_effort default (or the session's current effort) is carried onto the new model. Since 0.3.6 the bridge remembers the last effort per model (per-profile JSON): an unsupported carried effort is replaced by that model's remembered effort, else its own default, else its first offered effort — never an "unknown" dropdown, never a failed switch. Also check: a "phantom provider" route was picked — this bridge filters them by default (only config.provider's models are advertised), so point the profile's provider at a real route
Context usage missing	A "phantom provider" route was picked; this bridge filters them by default (only config.provider's models are advertised) — point the profile's provider at a real route
Need detailed diagnostics	ACP_DEBUG=1 dsh --profile acp-enhanced (stderr lifecycle trace)

Development

node scripts/compat-check.mjs         # cross-generation link check (0.1.0-rc.6 + 0.1.2-alpha.2+ scratch installs)
node scripts/acp-client.mjs           # end-to-end smoke (needs an API key)
node scripts/acp-client-tools.mjs     # client-tool tests (mocks Zed fs/terminal/elicitation/plan)
node scripts/acp-mcp-test.mjs         # MCP mount test (no model calls)
node scripts/acp-smoke-keyless.mjs    # keyless boot smoke (CI)
node scripts/acp-resume-test.mjs      # session resume test
node scripts/codec-image-test.mjs     # image-codec unit tests (no network, fake store)
node scripts/terminal-codec-test.mjs   # terminal-card codec unit tests (no network)
node scripts/acp-image-e2e.mjs        # image capability e2e (vision-model leg needs an API key)
scripts/init-acp-home.sh              # bootstrap/refresh the isolated home (~/.dsh-acp)

DevDependency pins for the harness packages use the same ranges the pinned
@deepseek-ai/dsh CLI declares (e.g. ^0.1.2-rc.1), so the repo's tree and a fresh
CLI install resolve one coherent family — exact patch pins here mixed with the CLI's
range-resolved closure produce a split closure (two versions of one name) that breaks
profile boots with export-not-found errors. After changing those pins, regenerate the
whole lockfile (rm -rf node_modules pnpm-lock.yaml && pnpm install): an incremental
install both leaves stale store entries poisoning the profile heal AND retains stale
lockfile peer resolutions — bumping 0.1.2-alpha.2 → 0.1.2-rc.1 in place left
dsh-session-persistence@0.1.2-alpha.3 (old-generation peers) wired into the rc.1
packages' snapshots, which passes boot and session/new and only breaks the first turn
with TypeError: Cannot read properties of undefined (reading 'length') from
PersistenceCoordinator.
pnpm-workspace.yaml approves the CLI closure's build scripts (node-pty prebuilds, koffi)
— they are runtime requirements when the repo CLI boots the profile.

Known limitations

Audio attachments are not supported (audio capability is not advertised), text streams at
block granularity by default (streamDeltas: true opts into token-level streaming, see
Features), one in-flight prompt per session. MCP supports stdio and streamable HTTP
(legacy SSE / acp transports are not advertised).
session/close / session/fork / session/resume are not implemented (capabilities
undeclared, compliant clients will not call them); session/delete removes the
persisted directory directly because dsh persistence has no official delete API.

Multi-root workspaces are advertised and all roots are visible to the model, but dsh's
sandbox policy resolves one writable root per session (the primary cwd, i.e.
session.header.cwd) and the local sandboxes bind exactly that root for writes. Reads
work in every root; under workspace-write a write under an additional root is denied
first and needs escalation/approval, while danger-full-access writes everywhere.
True multi-root write enforcement belongs in dsh core (dsh-sandbox-policy /
dsh-sandbox-local would need a root list instead of a single root).

Agent presets take over the model-facing rows: the shipped cordis.patch.yml disables
the dsh-base rows a preset owns (tool-bash/fs/subagent/todo/web/… — exactly the official
dsh-web-app/tui list minus hmr) and mounts the agent-presets roster (standard
default; code/minimal/cordis ship with the dsh CLI, your own preset dirs under
~/.dsh/.agent-presets are picked up automatically). The bundle's own patch applies
automatically (package.json dsh.bundle.patch) — do not copy it into the profile's
user-layer cordis.patch.yml, or the loader rejects the duplicate entry ids at boot.
When upgrading a profile that already carries a customized user-layer patch, keep
only your custom row configs there (e.g. includeAllProviders: true on the
acp-enhanced row, restating provider/model/preset since patch entries replace whole
rows, they do not merge). A session created before the upgrade resumes under the
roster's default preset.