Introduction¶
The ecosystem philosophy of DeepSeek Harness (DSH) is “everything is a plugin.” When developing or using a DSH Agent, people often run into problems such as forgetting what they just read, notes being hard to search, and document style being difficult to keep consistent. dsh-study-buddy is a plugin and Agent preset combination designed to address this pain point. It turns scattered materials into structured, interactive, and archivable Markdown notes.
Core Features¶
The plugin uses a fixed workflow to explain a resource thoroughly, ask and answer key points, and write the result into documentation.
- Four-step closed loop
The workflow includes: read the resource → explain → questioning and Socratic follow-up → archive into documentation.
- Structured notes
Notes are organized into pieces following a resource / chapter / section / block hierarchy. Each level has a corresponding mini table of contents for navigation. File names do not include numeric prefixes. Reading order is determined jointly by the order key inside the file and the mini table of contents.
- You decide the writing style
The plugin does not automatically generate a unified template. It requires the presence of a Note Expectations.md file in the vault root directory. The format, structure, and level of detail of the notes are all determined by this file.
- Safe archiving mechanism
Before writing to the vault, the plugin first lists the folder plan for confirmation. It only writes to disk after confirmation. If a path is outside the planned scope or has already been consumed, the write operation will be rejected.
- Pure Markdown data
All notes are regular Markdown files inside the vault. This means you can open and edit them directly with Obsidian, or manage them with Git version control. Before rewriting an old note, it is automatically backed up to the .study/archive/ directory, supporting rollback.
Installation and Enablement¶
Before installing, please make sure your environment meets the following conditions:
- A working DSH deployment (web profile).
- Node.js version
>= 22. - pnpm installed.
- DSH version requirement
>=0.1.7-rc.1 <0.3.0-0.
1. Install the Plugin¶
Use the official command to add the plugin to the profile:
dsh plugin --profile web add dsh-study-buddy
2. Configure the Vault Path¶
The plugin does not include machine-specific paths. You need to specify the path on the deployment side. Environment variables are recommended:
$env:DSH_STUDY_VAULT = 'D:\YourAbsoluteVaultPath'
Restart DSH for the change to take effect. You can also specify it through <DSH_HOME>/study-buddy.json or by overriding the preset configuration’s vaultRoot.
3. Configure Note Expectations¶
This is the core basis for the plugin to work. You must copy the default template into the vault root directory:
Copy-Item presets/study/assets/Note Expectations.md "D:\YourAbsoluteVaultPath\Note Expectations.md"
If this file is not found, the plugin will refuse to write notes.
Typical Usage¶
After installing and selecting the “Study Buddy” preset, you can control the workflow through conversational commands.
- Read only, no explanation
If you only want to see the extracted content, enter a file path or “read X.” The plugin will only output a reading report and will not automatically start explaining.
- Step-by-step explanation
Enter “explain” or “talk about it.” The plugin will explain one atomic knowledge point at a time and ask after each point: “Clear? Detail / Skip?”
- Deep Q&A
Ask directly about any point you do not understand. The plugin uses a “sandwich answer”: first give a core-focused answer in no more than 3 sentences, then explain the underlying logic, and finally follow up with counter-questions to ensure understanding.
- Archive and organize
Enter “organize notes” or “archive” to trigger the ten-step archiving workflow. This includes checking unanswered follow-up questions, reading expectations, generating the directory plan, waiting for confirmation, writing block by block, and updating mini tables of contents and coverage.
- Continue learning
If the session is interrupted, enter “continue explaining,” and the plugin will resume from the last breakpoint.
- Modify old notes
When modifying an old note, the plugin first shows an “old vs. new” comparison. It only performs the write after you confirm that the change is correct.
Use Cases and Notes on Usage¶
This plugin is suitable for users who need to transform external documents (PDF, PPTX, etc.) into an internal knowledge base. It does not connect to the internet, but it sends the content it reads (titles, body text, paths) to the model service provider for processing. Do not place sensitive data into the same vault.
Upgrade notice: After upgrading the plugin, if DSH does not automatically load the new code, delete node_modules\dsh-study-buddy under the profile directory and then rerun pnpm install.
Summary¶
dsh-study-buddy is a complete workflow tool for digesting, internalizing, and archiving materials. Through strict folder planning, customizable Markdown writing, and a pure-text data format, it ensures that knowledge accumulation is controllable and traceable.
