dsh-md-preview

English | 中文

@benz-ai-x/dsh-md-preview

Read and edit workspace documents beside a DeepSeek Harness conversation. Open a Markdown document produced by an assistant, browse the session workspace, or pick up where you last read.

Current release: v0.10.0, published on 2026-09-08. Requires the pinned Harness 0.1.2-rc.1 baseline and a web profile.

Install or upgrade

dsh plugin --profile web add @benz-ai-x/dsh-md-preview@0.10.0 --save-exact
dsh --profile web --dump-config

The effective configuration should contain the md-preview row. Start the profile with dsh --profile web; if it is already running, restart that same instance and reload its page. Replace web with your existing web-profile name when needed.

To remove the plugin:

dsh plugin --profile web remove @benz-ai-x/dsh-md-preview

What it does

• Preview and edit — render Markdown, GFM tables, highlighted code, TeX and Mermaid; edit existing Markdown documents with CodeMirror and save back to the workspace.
• Read beside the conversation — a document sidebar reserves space on wide screens, remembers your width preference and uses an overlay on narrow screens or when maximized. Native navigation and tool details keep their own controls.
• Find documents — browse the workspace tree, search document names across unexpanded directories, and use current-turn outputs, recently read documents and the continue-reading entry.
• Keep your place — reopening restores the recorded reading position after fetching the latest content. Panel width, navigation width and navigation choices persist when browser storage is available.
• Guard edits — closing, opening another document or switching back to Preview checks for an unsaved draft. Concurrent file changes offer Reload or Force overwrite; failures retain a retry path.
• Follow Harness styling — shared typography, theme colors, native icons and visible keyboard focus; document paragraphs and headings use the platform Markdown renderer.

Open, navigate and close

Entry or control	Action
Paperclip beside Session-log download	Opens workspace browsing while the panel is closed; closes the current panel while it is open
Markdown chip under a turn	Opens that produced document
Per-message “Preview documents” action	Lists Markdown documents produced by that message's turn
Folder icon inside the panel	Toggles the workspace navigation on wide panels; opens the Browse Face on narrow panels
Outline	Navigates headings and highlights the current reading position
Preview / Edit	Switches between the View Face and Edit Face for editable documents
Maximize / Restore	Fills the application content area, then returns to the remembered width
×	Closes the panel through the Unsaved Guard and returns focus to the paperclip entry

The paperclip opens workspace documents; uploaded attachments are not supported. Non-Markdown produced-file chips keep Harness's desktop-open behavior. The workspace browser can also preview .txt as plain text by default.

The sidebar docks when the available application width is at least 1056px; narrower layouts and maximized reading use an overlay. Width starts at half the viewport, capped at 720px, and remembers a 360–1200px drag preference subject to available space. Drag the left edge to resize; double-click it to toggle maximization. Panels at least 640px wide can show the Files/Outline navigation beside the document; narrower panels use the Browse Face or outline popover. Direct document entries open body-first unless you have chosen a navigation preference.

In Edit, save with the toolbar button or Cmd/Ctrl-S. To leave without saving, request Preview, another document or close, then choose Discard changes in the guard; Keep editing preserves the draft. There is no separate Cancel-edit button. Save writes only an existing file and returns to Preview after confirmation.

Workspace search matches document names, case-insensitively, without reading file contents. Partial traversal reports an incomplete result with its reasons. Clearing a query restores the tree expansion state. Recently read documents are derived from recorded reading positions, so opening a file without scrolling may not add a recent entry.

Keyboard

Mod means Cmd on macOS and Ctrl on Windows/Linux. Panel shortcuts require focus inside the panel; editor shortcuts require focus in the editor.

Shortcut	Action
Mod-S	Save
Mod-F	Find within the editor
Mod-Z / Mod-Shift-Z	Undo / redo
Mod-B / Mod-I / Mod-K	Wrap the selection as bold, italic or a link
Mod-Shift-O / Mod-Shift-E	Open Outline / workspace navigation
Mod-/	Show editor shortcut help
Esc	Dismiss an open popover or editor find panel first, then request panel close; never silently discard a draft
Arrow keys / Enter	Navigate and open workspace tree entries

Configuration

After installation, override the existing row in the profile's cordis.patch.yml:

- id: md-preview
  config:
    maxBytes: 1048576
    allowedExtensions: ['.md', '.markdown']
    previewExtensions: ['.md', '.markdown', '.txt']
    searchMaxResults: 200
    searchMaxDirectories: 2000
    searchConcurrency: 8

A later patch replaces the row's whole config; preserve all custom values you intend to keep. Omitted fields use schema defaults.

Field	Default	Meaning
maxBytes	1048576	Per-file read/write cap in bytes
allowedExtensions	[".md", ".markdown"]	Extensions allowed for editing
previewExtensions	[".md", ".markdown", ".txt"]	Preview extensions; members outside the editable set are read-only
searchMaxResults	200	Maximum matches returned by a workspace search
searchMaxDirectories	2000	Maximum directories visited by a workspace search
searchConcurrency	8	Parallel directory listings per traversal step

Paths are scoped to the session workspace. Saves require the backing read's fingerprint or an explicit force-overwrite choice. The schema is the authority for configuration defaults; the editable extensions are included in the preview union.

Failure codes

Code	Meaning
md-preview/bad-request	Invalid input; for example, a save with neither fingerprint nor force
md-preview/unknown-session	Session does not exist
md-preview/no-workspace	Session has no working directory
md-preview/unsupported-extension	Unsupported document extension
md-preview/forbidden	Workspace containment or filesystem access was denied
md-preview/not-found	Target does not exist
md-preview/too-large	Read or write exceeds maxBytes
md-preview/conflict	File changed since the read backing the save
md-preview/unavailable	Filesystem or transport operation failed

Installation forms

Form	Command	Delivery
npm	dsh plugin --profile web add @benz-ai-x/dsh-md-preview@0.10.0 --save-exact	Prebuilt JavaScript and declarations
Release archive	dsh plugin --profile web add ./benz-ai-x-dsh-md-preview-0.10.0.tgz	The same archive verified for publication; available with SHA256SUMS in the GitHub Release
Git source	dsh plugin --profile web add github:benz-ai-x/dsh-md-preview#<commit>	Self-contained prepare builds JavaScript; this form does not generate declarations

For Git installs, pnpm may require explicit build permission. Use the exact package key it reports in that profile's pnpm-workspace.yaml, then rerun add:

allowBuilds:
  '@benz-ai-x/dsh-md-preview': true

Build permission runs the package's source on your machine. Use a trusted source and a fixed commit. npm and release archives already contain their build output.

Development and verification

Node must satisfy ^22.19.0 || >=24.0.0; the repository declares pnpm 11.17.0. The pinned Harness checkout is resolved from DSH_HARNESS_ROOT, falling back to ../deepseek-harness.

pnpm install
pnpm context:check:strict
pnpm verify
pnpm watch:client

Dependencies use published versions by default. pnpm context:link explicitly switches development dependencies to the pinned source checkout and refreshes the lockfile; it is also the available command for resynchronizing moved source links.

Area	Source	Responsibility
Host service	src/remote.ts	mdPreview.read/write/list/search, workspace authority and cancellation
Remote descriptors	src/typert/remote-client.ts	Browser-safe codecs and the four RPC methods
Client registration	src/client/mount.ts	Remote mounting and four Slot contributions
Preview Panel	src/client/PreviewOverlay.tsx	Rendering, navigation and local geometry
Dock adapter	src/client/panel-dock.ts, use-panel-dock.ts	Reversible space reservation beside the pinned Harness frame
Header entry	src/client/WorkspaceDocsAction.tsx, PanelToggle.tsx	Paperclip entry, × close and current-turn output projection
Preview Session	src/client/preview-session.ts, use-preview-session.ts	Read/edit/save lifecycle and guarded transitions
Reading and preferences	src/client/reading.ts, preferences.ts	Position restoration and bounded browser preferences
Workspace Browser	src/client/WorkspaceBrowser.tsx	Tree, search results, quick entries and navigation
Editor / diagrams	src/client/editor.tsx, diagrams.ts	CodeMirror editing and lazy Mermaid enhancement

The v0.10.0 release passed 290 tests, strict baseline checks, typechecking and build checks. Its exact archive passed a clean-profile install, public-name imports, configuration composition, startup, client-resource serving and removal; see the release verification.

For publication, run pnpm pack:publishable, complete the clean-profile smoke with that archive, then publish the same .tgz with npm publish <archive.tgz> --ignore-scripts --access public --registry=https://registry.npmjs.org/. The full procedure, browser 2FA and runtime verification are in the maintainer handover.

Known limits and documentation

• The layout adapter depends on the pinned Harness frame structure; revalidate it when upgrading Harness. See ADR-0004.
• Uploaded document attachments are not previewable. Inline prose mentions of .md files keep Harness's desktop-open behavior.
• Editing targets existing supported documents; it does not create files. Fenced code and inline HTML are edited as plain text.
• The outline collects ATX headings; setext headings render but are not listed.
• Mermaid uses its default theme. Mixed indented and fenced code blocks skip enhancement; rendering failures retain the original code block.
• Browser theme/zoom acceptance and further header refinements remain tracked in TODO.

Development starts with the project contract and domain glossary. Release notes are under GitHub Releases.

License

MIT