Preface

The philosophy of DeepSeek Harness (DSH) is “everything is a plugin”. In agent development, defining notes and rules is a core aspect. The dsh-notes plugin aims to provide a local Markdown note storage solution, managing content through directory-based groups and offering a Web interface for interaction. It can not only store notes, but also read rule files such as AGENTS under the root directory or a group as writing context, helping the model write files while following specific conventions.

Installation and Activation

To install the plugin, run the following command:

dsh plugin --profile web add ./dsh-notes

After installation, restart the Web sidebar (profile) for the change to take effect:

pnpm dsh web

After restarting, a “Notes” entry will appear in the left sidebar.

Core Features

Directory and Note Structure

The plugin uses a local directory model:
- Root directory: The local path you choose (default is <DSH_HOME>/dsh-notes).
- Group: A direct subdirectory (second-level directory) under the root directory is a group.
- Note: A .md file under a group directory is a note.

When you write a note, if the corresponding group directory does not exist, the plugin automatically creates it.

Rule Context

To standardize writing, the plugin supports reading rule files. Files under the root directory or a group whose names match the following patterns (case-insensitive) are recognized as rule files:
- AGENTS.md
- AGENTS.local.md
- CLAUDE.md
- *.rules.md
- *规则.md / *規則.md

Before writing, the model can read these rule files through tools, understand the conventions, and then perform file writes.

Web Interface and Tools

  • Sidebar page: Click “Notes” to open the management page, where you can view the group list, preview rules, create/edit/rename/delete notes, and switch the root directory.
  • Root directory switching: Supports switching the root directory within the page. The ~ symbol is supported; leaving it empty restores the default path. The switch takes effect immediately and is persisted.
  • Agent tools: The plugin registers the following tools with DSH:
  • note_root: View or switch the root directory.
  • note_list: View a group overview, or view the note list under a group.
  • note_rules: Read the root rules or the rules for a specified group as context.
  • note_create: Create or update a note (auto-creates the group).
  • note_read: Read the full text of a note.
  • note_delete: Delete a note.

Usage

Default Path and Switching

The default root directory is <DSH_HOME>/dsh-notes. On the Web page, use the “switch directory” feature to point to any absolute local path (~ is supported).

Rule and Note Naming

  • Rule files and note files share the same namespace.
  • If a file name matches a rule naming pattern (such as AGENTS.md), the file is treated as a rule and cannot be created as a note.
  • Pasting a complete Markdown file (including Front Matter) stores it as-is and does not wrap it again.

Technical Details and Limitations

  • Security boundary: The browser accesses data only through protected routes and does not directly touch the disk. All file operations are subject to strict path traversal character filtering and existence checks.
  • Data writing: Markdown writing uses a “temporary file + atomic rename” mechanism, with a single-writer queue to prevent concurrent corruption.
  • Size limits: Rule and note reads are subject to byte limits; exceeding the limit returns a 413 status code.
  • Dependencies: @deepseek-ai/dsh-tools and @deepseek-ai/schemastery are optional peer dependencies used to extend functionality.

Summary

dsh-notes provides a complete local Markdown note management solution. Combined with a Web UI and Agent tools, it standardizes note creation, management, and context retrieval. It is released under the MIT License and is suitable for developers who need local knowledge management in DSH environments.