dsh-agentdebugx
用于 AgentDebugX 诊断的 DeepSeek Harness 插件桥接
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add dsh-agentdebugx@0.1.0Agentdebugx 以 dsh-agentdebugx 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
A separately packaged DeepSeek Harness plugin kept under the AgentDebugX
repository. It connects Harness sessions to AgentDebugX without coupling
Harness-specific code into the agentdebug Python package.
The plugin:
/agentdebug status|capabilities|diagnose|open;session.jsonl.zstd container;agentdebug/start and agentdebug/result session events;integrations/dsh-agentdebugx.This first integration targets DeepSeek Harness 0.1.1-rc.2 and AgentDebugX
0.3.x. Harness is in developer preview and may introduce breaking changes.
The bridge exposes AgentDebugX's deterministic heuristic pipeline and the DeepDebug profile. The external protocol deliberately leaves room for GUI RCA, discussion, and rerun operations without requiring those host-specific concerns to enter AgentDebugX core.
Prerequisites:
Install the Python runtime and the DSH bundle independently:
python -m pip install "agentdebugx[ui]>=0.3.1,<0.4"
dsh plugin --profile web add dsh-agentdebugx
dsh --profile web --dump-config
dsh web
The npm package intentionally does not install Python or execute install scripts. This keeps installation auditable and lets users choose the Python environment that owns AgentDebugX.
Prerequisites:
cd C:\path\to\AgentDebugX
python -m pip install -e ".[ui]"
dsh plugin --profile web add C:\path\to\AgentDebugX\integrations\dsh-agentdebugx
dsh --profile web --dump-config
dsh web
When running Harness from its source checkout, prefix the DSH commands with
pnpm:
pnpm dsh plugin --profile web add C:\path\to\AgentDebugX\integrations\dsh-agentdebugx
pnpm dsh --profile web --dump-config
pnpm dsh web
The plugin does not use deepseek-harness-sdk's bundled Python runtime. The
Node Harness host starts the packaged bridge script with the configured local
Python interpreter, which also works on Windows.
For local development, both sides are linked rather than copied:
pip install -e ".[ui]" points Python at the current AgentDebugX src/;dsh plugin ... add <directory> links the DSH profile to this plugin folder.After pulling or editing AgentDebugX, restart dsh web; Python imports the
updated AgentDebugX source when the bridge process starts. Re-run the editable
install only when pyproject.toml, dependencies, or package metadata changed.
After editing the JavaScript bridge/plugin, restart DSH as well. No repack or
reinstall is needed for this linked development setup.
Published npm/tarball installations are copies instead of links. For those,
bump the plugin version, run pnpm pack or publish to npm, update the DSH
profile dependency, and restart DSH.
SYSTEM_PROMPT.md is the shipped source of truth for the model-facing
AgentDebugX instructions. index.js resolves it relative to import.meta.url
and strictly renders its capture, open, and sessions-root policy placeholders
from plugin configuration when registering the prompt. Semantic edits must
preserve the persisted-session contract: list candidates first, present them
to the user, and confirm the selected saved session before diagnosis.
AgentDebugX is loaded as a Cordis plugin, not a Harness skill. After at least one Harness turn has completed:
/agentdebug status
/agentdebug capabilities
/agentdebug diagnose
/agentdebug open
The model-facing tools are:
agentdebug_list_sessions: list or search persisted DSH sessions beneath the
configured sessions root without starting Python or the dashboard;agentdebug_diagnose: diagnose this DSH session through its latest completed
turn boundary;agentdebug_analyze_trace: normalize and diagnose an existing trajectory
file or OSWorld trajectory directory inside a configured trace root;agentdebug_capabilities: return the installed integration contract,
formats, diagnosis mode, and current limitations.An ambiguous reference to a past or external DSH conversation must start with
agentdebug_list_sessions, followed by presenting the candidates and asking
the user to choose. agentdebug_diagnose is reserved for requests that clearly
identify the current, latest, or just-now conversation. Once a saved candidate
is confirmed, its path can be passed directly to
agentdebug_analyze_trace.
Both diagnosis tools take a mode:
heuristic (default) runs AgentDebugX's deterministic
Detect-Attribute-Recover pipeline and makes no model calls;deep runs the DeepDebug profile, seeded with the heuristic findings.Deep mode needs no extra API key: AgentDebugX's LLMClient protocol is
satisfied by an adapter that calls back into the Harness host over the same
pipe, so diagnosis runs on the model the session already uses. Set
llmProvider and llmModel together to pin a different model, which is also
how you get a second opinion from a model that did not produce the trace.
If a deep run fails, the bridge returns the deterministic report with a
deepError explaining why, rather than discarding the result. Automatic
per-turn capture never calls a model.
LLM judge, OSWorld GUI root-cause analysis, standalone LLM attribution, rerun,
batch processing, and Error Hub sharing stay on the agentdebug CLI against
the same store;
agentdebug_capabilities reports them so the model recommends the real command
instead of assuming the product lacks the feature. That tool reads the
installed package's own registries (version, ingest formats, and every
detect/attribute/recover component with its default and LLM requirement), so
the answer cannot drift from the AgentDebugX build in use.
By default the plugin is dormant: loading DSH registers its tools and commands
but starts neither the Python bridge nor the AgentDebugX dashboard. The first
status or capabilities request starts only the bridge. A diagnosis or
/agentdebug open also starts the local dashboard, waits for /healthz, and
reuses it for the rest of the DSH process:
http://127.0.0.1:7777/trace/<trace_id>/event/<event_id>
The plugin-owned dashboard stops when DSH exits. If dashboardUrl already has
a healthy AgentDebugX server, the plugin reuses it and does not stop that
external process.
autoCapture is disabled by default. When explicitly enabled, every completed
turn is captured and therefore may start the bridge. autoOpen accepts turn,
session, and off (default); enabling it together with autoCapture starts
the dashboard and opens the matching trace page. Explicit diagnosis keeps the
dashboard available but does not pop a browser when autoOpen is off;
/agentdebug open always opens it.
Heuristic detection reasons over events, so a benchmark trace scored as a
failure can still return zero findings. When the source trace carries an
outcome, the tool result repeats it under recordedOutcome, so "no findings"
is never mistaken for "the task succeeded". Use the CLI (agentdebug diagnose --mode gui-rca|judge|deep) for the model-backed root-cause modes.
You can still start the dashboard separately; the plugin will detect and reuse it:
agentdebug serve --store-sqlite .agentdebug\agentdebug.sqlite
Then open http://127.0.0.1:7777.
The default bundle row is:
- insert:
- id: agentdebugx
name: dsh-agentdebugx
config:
python: python
store: .agentdebug/agentdebug.sqlite
dashboardUrl: http://127.0.0.1:7777
traceRoots:
- .
timeoutMs: 120000
autoCapture: false
autoOpen: off
Environment shortcuts:
AGENTDEBUGX_PYTHONAGENTDEBUGX_STOREAGENTDEBUGX_DASHBOARD_URLAGENTDEBUGX_TRACE_ROOTS (semicolon-separated on Windows, colon-separated
elsewhere)AGENTDEBUGX_AUTO_CAPTURE (true enables per-turn capture)AGENTDEBUGX_AUTO_OPEN (turn, session, or off)deepTimeoutMs (default 900000) bounds a deep run, which issues several model
calls and therefore takes much longer than timeoutMs allows for the
heuristic path.
Harness patch layers replace a row's complete config; when overriding this
row, repeat every setting you need.
The plugin runs in the trusted Harness host process and launches a local Python
process. Session snapshots may contain prompts, model responses, tool
arguments, command output, paths, and system prompt material. Storage remains
local by default. The dashboard binds to 127.0.0.1; do not expose it remotely
without a separate authentication and TLS boundary.
agentdebug_analyze_trace can read only paths under traceRoots. Keep this
allowlist narrow; add an OSWorld results directory explicitly when the model
needs to analyze traces outside the DSH working directory.
$DSH_HOME/sessions is appended to the readable roots automatically so the
model can debug Harness's own past sessions. Point dshSessionsRoot at a
different directory to override it, or set it to an empty string to keep
Harness's session history out of reach.
agentdebug_list_sessions searches only that configured sessions root. It does
not accept a caller-supplied root, follow symlinked files or directories, or
make a model call. Persisted prompts and filesystem paths are sensitive local
data; the tool returns only bounded identification metadata and limits results
to at most 25 candidates.
agentdebug_analyze_trace accepts two sources beyond the live session:
$DSH_HOME/sessions/<workspace>/session-<uuid>/session.jsonl.zstd
(on Windows $DSH_HOME defaults to a dsh-* folder under %TEMP%).
Pass either the session directory or the log file;When the exact saved session is unknown, call agentdebug_list_sessions with
optional remembered text. Candidates show the session id, analyzable absolute
path, cwd/workspace, bounded first user prompt, and log modification time:
path to agentdebug_analyze_trace.Matching is deterministic and local: query text is normalized case-insensitively into whitespace-separated tokens, then ranked by token coverage, full-query presence, matched fields, recency, and finally lexical path. With no query, newest sessions come first. Missing, unreadable, partially written, or corrupt logs are skipped and reported through bounded aggregate counts and warnings rather than failing the entire listing.
Persisted session logs are a concatenated-Zstandard container that Node decodes frame by frame, and they are mapped through the same code path as the live session feed, so turn, step, and tool-call linkage is preserved rather than flattened by generic format detection.
assistant/chunk deltas are not duplicated into AgentDebugX. The assembled
assistant message is retained, while the number of skipped chunks is recorded
as trajectory metadata.
DeepSeek Harness currently does not accept external pull requests. Community plugins are distributed independently:
dsh-plugin;awesome-dsh-plugin require a separate
registry pull request.Publishing prebuilt/plain JavaScript avoids pnpm's Git prepare/allowBuilds
permission flow. This package intentionally has no install script.
This package lives in the repository's integrations/ directory. Registry
automation that only scans packages/, plugins/, or apps/ may not detect
the monorepo subpackage; npm and GitHub-topic discovery remain unaffected.
Official references:
pnpm install
$env:PYTHONPATH = "C:\path\to\AgentDebugX\src"
pnpm test
pnpm test:bridge
pnpm pack
The tests treat AgentDebugX as a read-only dependency. Compatibility changes belong in this adapter unless a generally reusable AgentDebugX public API is independently justified.