dsh-md-notes

dsh-md-notes

中文

DSH third-party plugin (bundle): MD Notes Manager

User Guide · Features · Architecture · Context · AI Conflict · Roadmap · Changelog

Overview

A note-taking plugin for DeepSeek Harness (DSH). It provides a full MD notes manager and MD notes editor, letting you quickly capture conversation content into notes. Notes can be maintained by syncing to a Git repository.

Who it's for: DSH web users who want local, file-based notes (no database, no cloud) — capture a conversation into a note with one click, keep editing the .md anywhere, and back up / sync with a Git repository.

Current features:

• Sidebar notes entry → full-screen notes manager: per-workspace note list (grouped, collapsible), markdown edit/preview, save, delete (in-page confirm), create with one click.
• Note search: a search box in the manager's top bar scans every workspace — titles and bodies (space-separated keywords, AND, case-insensitive); results are grouped by workspace with highlighted matched lines, and clicking a hit opens the note in the editor on that line with the keyword selected.
• Assistant-message action (next to copy) → pick or create a note and append that conversation (user question + answer) to it instantly — the text is captured from the conversation itself, so there's no waiting; section labels are localized (reasoning is not captured — only the final answer).
• Reference notes in chat (@): type @ to pick notes (cross-workspace included); on send the plugin's backend injects each note's content into the model context, so the model can cite it without being asked to read files.
• Git sync (optional, URL-driven): shared repo mode (one repo for all workspaces, per-workspace folders) or own repos mode (per workspace: URL + branch + subpath). Push = mirror-sync (deletions included), Update = pull with three-way conflict confirmation, auto-pull on open, merge-remote-and-retry. Each workspace shows a Git sync card in the manager: "Synced" / "N unpushed" status, plus a hint when the remote has new commits.
• Note write mutex: writes to the same note are locked across sessions — the sidebar entry, picker and manager stay in sync until the write finishes.
• Settings panel (dsh Settings → MD Notes): mode, repo URL/branch/subpath, auto-pull, commit author — with dsh-styled form controls.
• Theme & i18n: token-based colors (light/dark), UI copy follows dsh's language (Chinese / English), error messages localized.
• Update notifications: a yellow "Update available" tag appears when a newer npm version exists.

On the roadmap (see docs/TODO.md): visual Git conflict rendering & resolution, note capability enhancements (TOC / wiki links & backlinks), and interaction UX polish (dirty-editor reminders, save shortcut, etc.).

Compatibility

dsh iterates fast and provides no backward compatibility, so a fixed dsh version only matches fixed plugin versions. Verified combinations are listed below (full adaptation history in docs/compatibility.md):

The plugin is not pinned to a specific mainline commit; pin the plugin version at install time if you need a fixed combination (e.g. dsh plugin --profile web add [email protected]). Runtime dependencies (@deepseek-ai/*, react) are declared as optional peer dependencies and resolve from the dsh installation.

Install / Uninstall

Prerequisites: dsh CLI installed, target profile is web.

Install from npm (recommended):

dsh plugin --profile web add dsh-md-notes

Then restart dsh web (bundle layer and client package metadata are cached in the process; a restart is required for changes to take effect).

Upgrade:

dsh plugin --profile web update dsh-md-notes

A restart of dsh web is required for it to take effect.

Uninstall:

dsh plugin --profile web remove dsh-md-notes

For development/debugging from source: run dsh plugin --profile web add ./dsh-md-notes

from the parent directory of the plugin project.

Quick start

1. Install the plugin (above), restart dsh web.
2. Create a note: click the notes entry at the bottom of the sidebar (above Settings) → click + on a workspace row → in the dialog enter a title (default "Untitled note ") and an optional file name → type in the editor → Save.
3. Capture a conversation: below any assistant answer, click the notes icon (next to copy) → pick a target note (or create one on the spot) → Write to note. The user question + answer are appended to the note as a " -- " section.
4. Reference a note: type @ in the chat input to pick a note (cross-workspace included); on send the note's content enters the model context automatically.

Note files live in each workspace's .dsh-notes/ directory (<workspace>/.dsh-notes); you can open and edit them directly with any editor. Git sync is optional — point the plugin at a repo URL and it keeps notes in sync (shared repo or per-workspace repo).

For everything the plugin can do — the notes manager, capturing conversations, Git sync (shared / per-workspace repos), pushing/updating, conflict handling, and the settings panel — see the User Guide.

Configuration

All options are plugin Config keys, overridable in the profile's cordis.patch.yml (a patch replaces the whole config of the row):

- id: md-notes
  config:
    gitMode: 'off'               # 'off' | 'shared' | 'own'
    gitAutoPull: true            # pull remote before opening a note

The HTTP API prefix is fixed at /plugins/md-notes (the browser frontend hardcodes the same constant, so it is intentionally not configurable).

There are no environment variables and no secrets in this plugin's configuration.

Permissions & data

• Filesystem: reads and writes notes as plain .md files (plus a meta.json sidecar) under each workspace's .dsh-notes directory (notes are workspace-bound); git operations touch only the plugin-managed clones under $DSH_HOME/md-notes-repos/.
• Network: a loopback HTTP API (POST <route>, browser ↔ local dsh server) and the icon served from the same origin; the only other outbound call is the optional npm update check (registry.npmjs.org, fully off with checkUpdate: false). No telemetry, no other external calls.
• Credentials: none collected or transmitted.

Troubleshooting

Rollback: dsh plugin --profile web remove dsh-md-notes restores the previous state (notes files are untouched).

Contributing

See CONTRIBUTING.md for details.

Repository structure

License & security

Licensed under the MIT License (see LICENSE).

Security issues: please report them privately via the repository's Security Advisory rather than a public issue, so they can be addressed before disclosure.