Skip to main content

notes

148Stars4Forks0Issues0Watchers

Have the DSH agent organize the current conversation into Markdown and export it as a Hammer Note, saving it to the note service or generating a note long image.

Evidence4/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
TypeScript
Branch
main
dsh-pluginnotessmartisan

Install

cmdweb profile
$ dsh plugin --profile web add @zhaoolee/dsh-notes

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin zhaoolee/notes for me: review the repository at https://github.com/zhaoolee/notes first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

One-line Positioning

Let the DeepSeek Harness intelligent agent organize the current conversation into Markdown and export it as a Smartisan Note—when the note service is configured, it directly writes to the cloud workspace; when not configured, it falls back to the demo server to generate a note long image.

Core Capabilities

  • Organize conversation content into Markdown, call to create or update a Smartisan Note
  • Support updating existing notes by note_id; when updating, category, starred, and pinned attributes that are not explicitly passed retain their original values
  • When note service is not configured, fall back to the default demo server, render Smartisan Note long image PNG and save locally
  • Support note metadata writing such as category (folder), starred, and pinned
  • Image mode supports six note themes (warm white paper, late night notes, iPhone notes light/dark, Bear minimal, Telegra.ph)
  • Handle workspace concurrent conflicts: if server returns 409 during write, automatically re-read and retry up to 4 times

Technical Implementation

  • Language: TypeScript (compiled to ES Module)
  • Key Dependencies: @deepseek-ai/dsh-tools, @deepseek-ai/cordis, @deepseek-ai/schemastery, Node built-in node:fetch/node:fs/node:crypto
  • Architecture Pattern: Insert notes-export line in the host composition via cordis.patch.yml, registered as a Host-side tool by apply(ctx, config) calling ctx.tools.register(defineTool(...)); client only depends on Node built-in capabilities and can be tested independently without DSH
  • Entry Files: dsh-plugin/src/index.ts (tool registration); dsh-plugin/src/notes-client.ts (note service API client)

Use Cases

Used when intelligent agent users want to沉淀 the current conversation or long-form content into their Smartisan Notes list; especially suitable for one-click saving of code reviews, research summaries, and conversation minutes. When note service is not configured, can also generate note long images for direct sharing, posting to WeChat public accounts, or screenshot saving.

Prerequisites and Compatibility

DependencyMinimum VersionDescription
DSH Host Runtime0.1.0-rc.6+Plugin injects tools via cordis.patch.yml, requires @deepseek-ai/dsh-tools ^0.1.0-rc.6 and @deepseek-ai/cordis ^4.0.1 (peerDependencies)
Node.jsNot declaredSource code only uses built-in modules like node:crypto / node:fs/promises / node:os / node:path, no engines declared in package.json
PlatformCross-platformOnly depends on Node built-in fetch, no native modules

Installation

dsh plugin --profile web add github:zhaoolee/notes

Configuration

ConfigTypeDescriptionDefault
baseUrlstringNote service base address, e.g., http://127.0.0.1:18080; when not configured, falls back to default demo server (image mode)None
tokenstringStable Bearer Token (starts with notes_sk_v1.), takes precedence over username/passwordNone
usernamestringUsed to request Token from /api/auth/skill-token when no tokenNone
passwordstringSame as above, paired with usernameNone
demoServerstringDemo server to fall back to when baseUrl is not configuredhttps://notes.fangyuanxiaozhan.com

Configuration priority: plugin config > process environment variable NOTES_API_* > built-in defaults.

FAQ

Q: After installation, the intelligent agent won't call it automatically. What do I need to say?

A: Restart the target profile after installation to activate the plugin. The intelligent agent has registered the notes_export_conversation tool. Say "export our conversation as a note" or similar to trigger it. The tool will automatically organize the conversation into Markdown and call it.

Q: Can I use it directly without any configuration?

A: Yes. The plugin will automatically fall back to the default demo server notes.fangyuanxiaozhan.com, render the conversation as a Smartisan Note long image PNG and save it locally. This mode cannot write to the note list, only suitable for trial or temporary sharing.

Q: I want to save notes to my own service. How do I configure it?

A: Set the note service address (NOTES_API_BASE_URL or plugin config's baseUrl), and provide a token or username/password. The intelligent agent will write the conversation as a note to the current account's cloud workspace, creating new or updating by note_id. If baseUrl is configured but no credentials are provided, it will explicitly error and won't silently fall back to the demo server.

Q: What are the action types returned by the tool, and what do they mean?

A: created means a new note was written; updated means an existing note was updated by note_id; exported-image means it was rendered as a note long image via the demo server (image mode), returning the local PNG path instead of a note link.

Q: Where does the note title come from?

A: It takes the first line of the full Markdown; the plugin removes heading symbols, quotes, and list markers, truncating to within 38 characters. It is recommended to write the title as # Title on the first line of the body.

Q: What note themes are supported?

A: Image mode supports default, smartisan-dark, apple-notes, apple-notes-light, bear, telegraph six themes; in write mode, the theme is determined by the note service side, and the tool does not modify the theme.

Q: Can I use version 0.1.0?

A: Not recommended. 0.1.0 will abort the session on first call with DSH 0.1.0-rc.6 due to duplicate installation of the host runtime. Please use version 0.1.1 or above (current latest 0.1.2).

Q: How to completely uninstall?

A: Execute dsh plugin --profile web remove @zhaoolee/dsh-notes, then restart the target profile; also clean up NOTES_API_* environment variables and credentials in the plugin config.

Ease of Use

Beginner — no configuration needed to generate note long images via the demo server; to write to your own note list, just set an address and credentials, which ordinary conversation users can complete.

Known Issues and Limitations

  • When note service is not configured, conversation content will be sent to the default demo server notes.fangyuanxiaozhan.com's anonymous export interface for image rendering; the interface does not save to any account workspace, but for sensitive conversations, please configure your own note service first
  • When only baseUrl is configured but no token or username/password provided, write mode will explicitly error and won't silently fall back to demo server
  • In write mode, the note theme is determined by the note service side, and the tool does not modify the theme; theme parameter only takes effect in image mode
  • Plugin version in repository source (github:zhaoolee/notes) is 0.1.2; old version 0.1.0 will abort the session on first call with DSH 0.1.0-rc.6 due to duplicate installation of the host tool runtime, please avoid using it
  • Automatic re-read up to 4 times for workspace concurrent conflicts; after 4 consecutive conflicts, it will throw "Workspace has been changing during consecutive retries, please try again later"
  • Notes in trash cannot be updated by note_id; the interface will return error "Notes in trash cannot be modified"

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/zhaoolee/notes)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory