dsh-annotate

dsh-annotate adds a visual review panel to DeepSeek Harness Desktop and its web client. Open a local app, click the elements you want changed, leave notes, and send the whole review to your conversation as structured text.

⌘/Ctrl ⇧ B → choose a local app → Mark → click → comment → send

Install

Give a coding agent this prompt:

Read https://github.com/alaliqing/dsh-annotate and install dsh-annotate into the current local Harness profile following its README. Preserve existing configuration and keep the current task running. Report the installed version and explain how to restart after the task finishes.

The commands below install 0.1.15 and can also upgrade an existing install.

Desktop (macOS)

Open Desktop once to initialize its profile. It can stay open during installation. Use its bundled CLI; with the app installed in /Applications:

"/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" plugin --profile desktop add dsh-annotate@0.1.15

Adjust the app path if needed. After the current task finishes, fully quit and reopen Desktop, then click Annotate or press ⌘/Ctrl⇧B.

Web

With the web CLI, Node.js 20+ and pnpm available, run:

dsh plugin --profile web add dsh-annotate@0.1.15

Replace web with your profile name if needed. After the current task finishes, restart that profile and refresh the browser, then open Annotate.

If installation fails, the panel is missing after restart, or you are upgrading 0.1.2 or earlier, see installation troubleshooting. See compatibility for tested versions.

What it gives you

• Zero-config discovery of running loopback development servers, including IPv4 and IPv6, with the services that belong to the current workspace first.
• Static pages need no server: an index.html — or a built page under dist/, build/, out/ or public/ — is offered straight from the workspace and previewed from its own directory.
• Focused feedback: your full note and an element locator, with extra verification context only when the selector is ambiguous or unverified.
• Markers that stay attached through window or nested scrolling, resizing, and layout shifts.
• Two explicit send paths: send the review by itself, or add it to the current draft. Failed sends keep every annotation.
• Isolated previews that preserve app routes, assets, fetches, and WebSocket upgrades without sharing the Harness origin.
• English and Chinese UI, switchable from the toolbar’s More menu.

No screenshot is captured. Mark mode adds a temporary crosshair and overlay, while page and container scrolling stays native. By default, the plugin only discovers servers you already run; process control requires an explicitly configured command.

Use

1. Start your app's development server.
2. Open a Harness conversation, then press ⌘/Ctrl⇧B or choose Annotations from the right sidebar.
3. Choose a detected service or one of the workspace's static pages, or enter a port or loopback URL.
4. Click Mark, select an element, and write a note.
5. Press Enter or click Save, then select the next element to keep annotating. Press Esc or Mark again to exit. Click a numbered marker to view its note; click inside its text to edit. Unchanged notes never become drafts. Esc or an outside click keeps actual changes as a resumable draft; Cancel discards them.
6. Use the floating bottom bar to send the batch. Click its count to view notes; its More menu offers Add to composer.

Annotations and drafts are stored by Harness conversation and full app URL, so routes restore independently and conversations never share notes.

Rows are ordered by how likely they are to be yours: a service whose process was started inside the conversation's workspace is tagged This project, a port the workspace names in package.json or a Vite config is tagged Configured port, then the common-port order follows. Static pages are listed under their own heading, and when exactly one candidate exists it opens on its own — a static page only when no server is running at all.

What gets sent

Page annotations · http://127.0.0.1:5173/settings (1)
1. Disable this until the form changes.
   Element: button#save · “Save changes”

Each batch includes the full app URL once. Notes are never truncated; target labels are capped at 64 characters. Computed styles and component chains stay out of the message. If the selector has zero/multiple matches, is invalid or has no recorded match count, the message explicitly asks for verification and adds available semantic, component and geometry hints. No selector is treated as uniquely matched without a captured count of one.

How the preview stays isolated

A normal cross-origin iframe does not expose its DOM. Instead of moving the app onto the Harness origin, dsh-annotate gives each conversation/app pair an ephemeral loopback origin and injects a small shim and picking overlay.

• Panel and overlay validate both message source and origin.
• Targets are restricted to localhost, 127.0.0.1, and [::1].
• A static page is served by the plugin itself, read-only, from its own directory on a loopback origin: GET/HEAD only, nothing outside the workspace, no dotfiles, and a 64 MiB ceiling per file.
• App cookies are namespaced; unprefixed cookies are stripped both ways.
• Closing a panel, returning to the service list, or switching apps releases its preview. Other windows using the same preview keep it alive. Abandoned previews expire after five minutes without activity or a renewed lease; plugin disposal closes all remaining servers and sockets.

This is a local development tool, not a browser sandbox. OAuth flows, strict origin allowlists, service workers, restrictive CSP, Shadow DOM internals, cross-origin child frames, and individual canvas objects may need a normal browser or app-specific setup. The full cookie model has only been validated in Chromium.

Optional configuration

- id: dsh-annotate
  config:
    detect:
      extraPorts: [4321]
      probeTimeoutMs: 900
      cacheMs: 2000
      staticPorts: false
      staticFiles: false

For 0.1.3 and later, put this override in your active profile's cordis.patch.yml ($DSH_HOME/profiles/<profile>/cordis.patch.yml, with DSH_HOME defaulting to ~/.dsh); the bundle supplies the plugin row. detect.staticPorts: false stops probing the common-port list and leaves only real listeners; detect.staticFiles: false stops offering the workspace's own HTML pages. detect.extraPorts adds ports people run on by habit.

The repository also includes dsh-app-bridge for the narrower case where an app must be mounted at a fixed path on the Harness origin. It is a reverse proxy, not an annotation UI.

Development

npm ci
npx playwright install chromium
npm run check
npm test

To use an unreleased checkout, install it through dsh plugin so the bundle is selected in the web profile:

git clone https://github.com/alaliqing/dsh-annotate.git
dsh plugin --profile web add "link:/absolute/path/to/dsh-annotate/packages/dsh-annotate"

The default tests drive the real built client, shim, and overlay in Chromium against a Harness fixture; no model is called. npm run test:harness separately checks a packed install in a real, isolated Harness with a local model fixture. Generated files under packages/dsh-annotate/lib/ are committed and must stay in sync with their sources.

See CONTRIBUTING.md for repository conventions and SECURITY.md for private vulnerability reporting.

License

MIT, with third-party attribution in NOTICE.

Independent community plugin; not affiliated with or endorsed by DeepSeek.