XieZongChen / dsh-md-notes

dsh-md-notes

中文

DSH third-party plugin (bundle): MD Notes Manager
User Guide · Features · Architecture · Context · 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.
• Assistant-message action (next to copy) → pick or create a note and append that conversation (user question + answer) to it, with localized section labels.
• 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 conflict confirmation, auto-pull on open, merge-remote-and-retry.
• 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): restyle the note picker with cross-workspace capture, reference notes as conversation context, and visual Git conflict rendering & resolution.

Compatibility

• Verified plugin version: 0.4.0 (see CHANGELOG.md for history).
• Verified dsh version: deepseek-harness mainline 0.1.0-rc.7.
• The plugin is not pinned to a specific mainline commit; pin the plugin version at install time if you need a fixed combination. 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) → enter a title in the "New note title…" field → New → 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 with a timestamped section.

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:
    route: '/plugins/md-notes'   # HTTP API prefix; default is fine
    gitMode: 'off'               # 'off' | 'shared' | 'own'
    gitAutoPull: true            # pull remote before opening a note

Key	Default	Meaning
route	/plugins/md-notes	HTTP API prefix served by the plugin; also hosts the icon at <route>/icon.svg.

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. No external network calls, no telemetry.
• Credentials: none collected or transmitted.

Troubleshooting

Symptom	Fix
Changes don't appear after install/upgrade	Restart dsh web — bundle layer and client metadata are cached in the process.
Icon looks stale	Hard-refresh the page; the icon is served with no-cache and reflects assets/dsh-md-notes.svg on every request.
Plugin doesn't load	Verify the layer: dsh --profile web --dump-config and look for the md-notes row.
Installed from git and add failed	pnpm ≥10 blocks build scripts by default; add the printed package key under allowBuilds in the profile's pnpm-workspace.yaml, then re-run add.
Notes can't be created/saved	Make sure the workspace's .dsh-notes points to an existing writable directory (create a workspace in the dsh sidebar first).

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

Development

npm install --legacy-peer-deps   # first time or after dependency changes
npm run link-deps                # link deepseek-harness checkout types (before changing code)
npm run build                    # build lib/index.js + lib/client.js

After changing code and building successfully, restart dsh web for it to take effect.

Common scripts:

Command	Purpose
npm run build	Full build (tsc host → tsc client → tsdown)
npm run typecheck	Type-check only (both programs)
npm run link-deps	Re-link @deepseek-ai/* types to the checkout
npm run bundle	Build only the client bundle

Contributions are welcome: open an issue to discuss, then a PR. Design docs: docs/features.md · docs/architecture.md.

Repository structure

Path	Contents
src/	Source code (host half + client half)
src/host/	Notes domain logic (notes.ts) + HTTP layer (http.ts)
src/client/	Browser half: entry (index.ts) + feature modules under features/
src/client/features/locales/	zh/en UI dictionaries (dsh locale namespace md-notes)
assets/	Plugin icon (SVG source + PNG)
docs/	Design docs: features.md (functional), architecture.md, TODO.md
scripts/	Dev tooling (e.g. link-deps.mjs)
lib/	Build output (gitignored; what npm publishes)

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.