dsh-inspector

简体中文 | English

npm package: dsh-inspector · GitHub repository: CocoSgt/dsh-inspector

A third-party plugin for DeepSeek Harness (dsh): an "Instruction Files" panel on the right side of the Web UI that shows — and manages — the instruction chain actually in effect for the current session, in the harness's real load order: global $DSH_HOME/AGENTS.md → project root → … → the session's cwd, one directory level at a time — plus the status of the four skill roots. The information architecture mirrors the official dsh-agent-instructions discovery algorithm exactly: what you see is what the model gets.

Open a session whose workspace sits in a project directory, then toggle the "Instruction Files" button in the session header; the panel follows the current session's workspace directory automatically. The UI ships in Chinese and English (follows the harness language preference).

The instruction-chain model (matches the harness exactly)

The layers, deduplication, and status flags shown by the panel align with the real behavior of packages/context/agent-instructions:

1. Global layer: $DSH_HOME/AGENTS.md (default ~/.dsh/AGENTS.md). Only AGENTS.md is recognized; it applies to every session and always loads first.
2. Project chain: starting from the session cwd, the nearest ancestor containing .git is the project root (the cwd itself if none is found); every directory level from the project root down to the cwd is probed for 4 candidates: AGENTS.md and CLAUDE.md (base), plus AGENTS.local.md and CLAUDE.local.md (local overlays, by convention not committed). Every candidate that exists is loaded; within one directory, candidates whose content is identical after trimming surrounding whitespace are collapsed into the first one (the panel flags this as "Same as X · collapsed to one").
3. Order is priority: global → cwd goes broad to specific, and the model is told that more specific instructions win; the panel is ordered and annotated accordingly. When the byte budget overflows, the harness omits the broadest entries first; a single file over 1 MB is ignored outright (the panel flags it as "Over 1 MB · not loaded").
4. Subdirectory injection is on demand: instruction files in subdirectories below the cwd are not preloaded; they are injected as additional instructions only when the model reads or writes a file inside that subdirectory — the panel footnote explains this instead of mixing non-preloaded files into the chain.

Why there is no hooks.json / .env / .sessions: the hooks bridge is not mounted by default and its configPath is required with no default file name (it is deployment configuration, not a project file); .env and .sessions are resolved against the dsh launch directory and take effect process-wide, unrelated to the session workspace. Listing them as "project files" would invite users to create files nothing ever reads, so they were removed from the panel. Files of other agent tools (GEMINI.md, .cursorrules, …) are not read by dsh and are equally absent.

Features

• Instruction-chain view: one card per layer, tagged with its identity (Global · all sessions / Project root / Current working directory), listing existing candidate files with status chips (local/not committed, duplicate collapsed, oversized-ignored) plus last-write time and size.
• In-place creation: the "+ New" button on each layer card expands the missing candidates (AGENTS.md marked recommended, local candidates marked gitignore-suggested), pre-seeds a template — in the current UI language — and writes to disk only on save. Templates seed the editor only for files that do not exist yet; editing an existing file never re-templates it.
• Editor dirty guard: navigating back with unsaved changes offers "Save and go back / Discard changes / Keep editing" — nothing is dropped silently; an unsaved dot shows in the title bar; Cmd/Ctrl+S saves; after a save the panel notes that "updates are injected at the session's next step" (the harness reconciles and injects the change on the next step).
• Skill directory status: the four skill roots — project-level .dsh/skills and .agents/skills, user-level ~/.dsh/skills and ~/.agents/skills — with existence and skill counts (SKILL.md counting, depth- and entry-capped scan). Skill SKILL.md/flat .md files can be viewed and edited in place; skill files reached through symlinks write through to their source file by design.
• Floating right panel: registered on shell.overlay (additive list slot); the session-header toggle is registered on conversation.session.header.utilities; switching sessions follows the new workspace automatically.
• Path safety: read/write addresses are the quadruple cwd + scope + dir + name. name must hit the 4-candidate whitelist; dir must hit the project-chain directory set recomputed from the cwd at call time (the global layer accepts only AGENTS.md); skill-file access is limited to .md inside the two project skill roots or the two user skill roots; the resolved path is prefix-checked as defense in depth.
• Bilingual UI (zh/en): dictionaries are registered into the harness locale service; the panel and toggle read the standard reactive t seat and re-render on language switch. User-visible host failures travel the wire as stable dot-codes (read.err.missing, address.err.offChain, …) with the Chinese text as fallback, and are localized client-side.

Architecture

One npm package, two faces:

• Host side (lib/index.js, the package main entry): ProjectFilesGateway extends TypertRemoteService (from @deepseek-ai/dsh-typert-protocol) and exposes the six RPC endpoints projectFiles/overview, readFile, readSkillFile, writeSkillFile, writeFile, and removeFile, probing and writing the instruction chain directly with node:fs. Layer discovery (.git marker walk-up, candidate order, trimmed-content dedup, 1 MB cap) matches the harness. Under the third-party dual-copy scenario SRC discovery is blind, so a weak (src-json) manifest is also registered into the host typert registry. User-visible failures are returned as data (see above), not thrown.
• Browser side (lib/client.js, exports["./client"]): a closure-factory bundle. On startup it $mounts hand-written strict zod call descriptors onto ctx.remote, registers its zh/en dictionaries into ctx.locale, and then registers the React UI onto two slots (each registration declares locale: so components receive the t seat); the panel reads the current session's cwd from the ctx.sessions list snapshot.

The built lib/ output is pre-built and committed with the repository, so git installs need no build step.

Install

Install from npm:

dsh plugin --profile web add dsh-inspector

All three dsh plugins can be added in one command:

dsh plugin --profile web add dsh-skills dsh-attachments dsh-inspector

GitHub fallback:

dsh plugin --profile web add github:CocoSgt/dsh-inspector

Note: a self-built profile's ~/.dsh/profiles/<name>/package.json must list @deepseek-ai/dsh-base and @deepseek-ai/dsh-web-app in dsh.profile.bundles, otherwise startup hangs silently.

Restart dsh web afterwards. Uninstall: dsh plugin --profile web remove dsh-inspector.

Companion plugins

The other two plugins from the same suite:

• dsh-skills (npm) — a skill hub: aggregate skills scattered across Claude Code directories, projects, and .skill packages into one global library, invocable from the "/" menu.
• dsh-attachments (npm) — bring any file into the conversation as cards above the composer; the model reads images by path via read_image, so even non-vision models are never blocked.

Usage

1. Open a session whose workspace is a project directory (pick the directory when creating the session, or restore an old one).
2. Click the "Instruction Files" button in the session header; the panel opens on the right with the workspace path at the top.
3. The panel lists the instruction chain in load order; click a file to edit it, or "+ New" to create a missing candidate in place; deletion asks for confirmation and going back with unsaved changes raises the dirty guard.

With no current session (or a session without a workspace directory), the panel prompts to open a project session.

Known limitations

• The panel is a fixed floating right column in shell.overlay, not a draggable native pane; the width is fixed at min(440px, 92vw).
• The host trusts the session cwd sent by the browser (a local-panel use case); the cwd must be an existing absolute directory path, but it is not checked against dsh's workspace list.
• "In effect" is inferred from existence + harness rules (dedup/size cap); the session's actual byte-budget truncation (64 KB baseline) is not reflected in the panel.
• The on-demand injection state of subdirectories below the cwd (which have been touched and injected) is not shown; only the footnote explains it.
• The editor is a plain textarea, with no Markdown preview or syntax highlighting.
• The panel does not watch the file system; returning from the edit view re-fetches, but external changes during editing are not synced live.

Development

pnpm install
pnpm run typecheck   # tsc --noEmit
pnpm run build       # tsc (host side, downleveled decorators) + tsdown (browser bundle)

Source layout:

src/
  index.ts         Host-side gateway service (@Remote methods = RPC endpoints
                   + weak manifest registration + failure-code protocol)
  scoped-files.ts  Instruction-chain model and shared types (candidate list,
                   layers, overview shapes, FailureStatus)
  client/
    index.ts       Browser plugin body ($mount + dictionary registration +
                   slot registration)
    locales.ts     zh/en dictionaries (zh is the key-set source of truth;
                   UI copy, creation templates, and host failure codes)
    descriptors.ts Hand-written strict call descriptors (zod)
    panel.tsx      Instruction-chain panel, editors, and header toggle
    store.ts       Panel open/close and edit-target state
    styles.ts      Injected CSS (dsi- prefix, --dsw-alias-* design tokens)
    types.ts       Minimal client-side service type surface (incl. locale)

Note: the host-side methods' parameter names are the RPC wire field names (the Gateway SRC mode reads them via Function.prototype.toString), so public methods keep the plain-identifier parameter form and builds must not minify parameter names (this repository's build does not minify). The RPC method is named removeFile, not remove: remove is already taken on the client namespace service's prototype, and a name clash would be rejected by the gateway at mount time.

Tags

This package and its repository carry the dsh-plugin, dsh, deepseek-harness and related keywords/topics. DeepSeek Harness ships no official plugin marketplace and no official discovery tag — once a third-party plugin is published, nothing links it back to the ecosystem and users have no way to find it. These community tags are the only practical discovery channel (npm: keywords:dsh-plugin; GitHub: topic:dsh-plugin). Unofficial, but essential — that is why they are here.

License

MIT