dsh-web-notes
Floating notes for the DeepSeek Harness web GUI (dsh web). Keep commands, credentials, parameter values and any other important snippets at hand while working — and feed them back into the conversation with one click.
中文
Features
- Floating dock — an animated notebook icon on the right edge of the chat window, one click away at all times. Drag it anywhere (the position persists); it honours
prefers-reduced-motion.
- Configurable placement & size — in Settings → Plugins → Plugin Configuration the dock can be set to floating (draggable) or fixed (pinned to the chat window's top-right corner, not draggable), and the button size to Small / Regular / Large. Changes apply live — no reload.
- Notes panel — slide-over panel with search, a note list (title, preview, tags, relative time), and per-note actions.
- Dismissing the panel — the X, ESC, the dock button, a click outside the panel, and (on touch) a bottom Close button all dismiss it. Every dismissal persists an in-progress draft instead of losing it; the editor's Cancel is the one explicit discard.
- Touch / coarse-pointer ready — on touch devices every control grows to at least a 44px target, the per-note actions become a permanent tappable row instead of hover-only pills (which are unreachable without a hover), the resize gutter widens, and a bottom Close button lands in the thumb zone. Fine-pointer desktops keep the compact layout unchanged.
- Insert into the composer — one click places the note's content into the current session's input box (the title stays a list label), ready to review and send. When no session is open, the content is copied to the clipboard instead.
- Save any selection — select text anywhere on the page (e.g. part of an AI answer) and a floating "Save as note" button appears; one click captures it, with the first line as the title. The bubble follows the selection while you scroll and only disappears when the selection collapses, you click elsewhere on the page, or you switch windows.
- Markdown preview — the note editor auto-detects Markdown (headings, lists, code fences, quotes, tables, links, bold/italic…). Plain notes stay a plain editor; once MD syntax is present an Edit / Preview toggle appears, and the preview renders full GFM (sanitized with DOMPurify — raw HTML/scripts never execute).
- Per-session notes — a note can be bound to the current session (visible only while that session is current) or saved as global (visible in every session and on the new-conversation screen). The panel has All / This session / Global scope tabs; new notes default to the current session, with a "save to global" checkbox in the editor — or default to global for every new note via the Default to global setting.
- Persistence — notes are stored locally on the host under
$DSH_HOME/notes/notes.json (default ~/.dsh/notes/notes.json), atomic writes, tolerant reads.
- Privacy by design — the notes API is loopback-only, so the data never leaves the local machine.
- Theme & skin adaptive — every color rides the official dsh design tokens (
--dsw-alias-*), so the UI matches the official light/dark theme out of the box AND recolors live when a skin plugin (dsh-skins / skin-center) is installed — no reload, no skin-specific code.
- zh/en UI — follows the document language.
Install
From npm
The package is published on the npm registry:
dsh plugin --profile web add dsh-web-notes
If your default npm registry is a mirror that has not synced the package yet (e.g. npmmirror — read-only, syncs with a delay), install straight from the official registry instead:
dsh plugin --profile web add dsh-web-notes --registry https://registry.npmjs.org/
From a local checkout (development)
dsh plugin --profile web add link:/path/to/dsh-web-notes
Then add the bundle to the profile manifest so it actually boots:
# append "dsh-web-notes" to the bundles list in ~/.dsh/profiles/web/package.json
# under "dsh" > "profile" > "bundles", then restart dsh web
The official dsh plugin --profile web add <spec> command forwards to pnpm; it installs the package but does not edit the dsh.profile.bundles manifest — that list decides which installed packages boot. Add the package name there (or ship a cordis.patch.yml insert via an aggregator bundle) and restart.
Verify the install
dsh plugin --profile web list # dsh-web-notes should be installed
npm view dsh-web-notes version # → the latest published version
After restarting dsh web, the notebook icon appears on the right edge of the chat window (see Usage).
Update
dsh plugin forwards to pnpm, so updating is just pnpm's update — no manifest edits needed (the profile reconciles its bundle list against what is installed on the next dsh plugin run), then restart dsh web:
dsh plugin --profile web update dsh-web-notes
# or pin an exact version:
dsh plugin --profile web add dsh-web-notes@latest --registry https://registry.npmjs.org/
Mirror sync delay: publishing goes to the official registry, but mirrors like npmmirror sync on a delay — right after a release your default registry may still serve the previous version (or briefly 404). If an update "does nothing" after a new release, point at the official registry with --registry https://registry.npmjs.org/.
Updates never touch your notes: they live on the host at $DSH_HOME/notes/notes.json and your settings survive an upgrade.
Usage
- Click the notebook icon on the right edge of the chat window.
- Click New to write a note (title optional — defaults to the first line), or select any text on the page and click Save as note.
- In the note list:
- Insert — puts the note into the input box of the current session (appended after any existing draft); press Enter to send.
- Copy — copies title + content to the clipboard.
- Edit / Delete — manage the note.
Notes are searchable by title, content and tags (comma-separated in the editor).
Configuration
The plugin registers a notes settings namespace and a settings card in Settings → Plugins → Plugin Configuration (the namespace is also editable via ~/.dsh/settings.yaml):
notes:
enabled: true # master switch: false hides the dock entirely
selectionCapture: true # false disables the selection "Save as note" bubble
dockMode: floating # floating (draggable) | fixed (chat window top-right)
buttonSize: large # small | regular | large
defaultGlobal: false # new notes default to global (all sessions)
All five options are editable live in the settings card; the dock and panel pick up changes immediately.
Security
Notes may contain credentials, tokens, or other sensitive values. They are stored in plaintext in a local JSON file (~/.dsh/notes/notes.json, same trust model as ~/.dsh/credentials.yaml) and are served only to the loopback browser UI. Do not store secrets you cannot afford to expose on this machine, and protect the file with your OS-level user permissions. Exporting/backing up that file also exports every note.
Development
pnpm install
pnpm run build # tsc -b (types) + tsdown (lib/index.js + lib/client.js)
node scripts/smoke-host.mjs # standalone host-logic smoke test (no dsh app needed)
# client UI verification that needs no dsh app (see below)
pnpm exec tsdown --config tsdown.harness.config.ts
node scripts/verify-touch.mjs
scripts/verify-touch.mjs drives scripts/harness/entry.tsx — a standalone harness that renders the REAL NotesDock component tree with the REAL NOTES_CSS against mocked host contracts (notes API, sessions store, settings scope) — in headless Chrome over CDP. It asserts the coarse-pointer adaptation and every dismissal path, and writes .logs/touch-desktop.png / .logs/touch-coarse.png for visual inspection.
The scripts/cdp-*.mjs / screenshot.mjs probes drive the running GUI, so they need that instance's browser auth. dsh ≥ 0.1.5 gates / behind a per-process launch token (minted into a signed cookie), so a fresh headless browser gets 401 dsh web authentication required and never boots the app — open the token URL printed by dsh web in the same browser profile, or reach for the harness for client-only checks.
Architecture:
- Host half (
src/index.ts, src/service.ts, src/routes.ts, src/persist.ts) — cordis plugin row notes; CRUD service, atomic JSON persistence, loopback-guarded /api/notes/* routes, settings namespace.
- Browser half (
src/client/) — global floating surface mounted on document.body (notes have no session dimension); talks to the host through same-origin JSON; inserts into the composer through the official conversation input facade (ctx.conversation.input.for(actx).setDraft(...)).
The client bundle is built as a closure-factory artifact (window.__ModuleLoader__.load({ id: 'dsh-web-notes', factory })) served by the web plugin table at /plugins/dsh-web-notes/client.js.
Roadmap
- Note categories/pinning.
- Insert with optional send-immediately.
License
Apache-2.0. © 2026 Shrbuz — see NOTICE for attribution.
