前言¶
DeepSeek Harness (DSH) 的理念是「一切皆插件」。在智能体开发中，笔记与规则的定义是核心环节。dsh-notes 插件旨在提供一个本地化的 Markdown 笔记存储方案，通过目录分组来管理内容，并提供 Web 界面进行交互。它不仅能存储笔记，还能读取根目录或分组下的 AGENTS 等规则文件作为写作上下文，帮助模型遵循特定规范进行文件写入。
安装与启用¶
安装该插件需要执行以下命令：
dsh plugin --profile web add ./dsh-notes
安装完成后，需要重启 Web 侧栏（profile）才能生效：
pnpm dsh web
重启后，左侧侧栏会出现「笔记」入口。
核心功能¶
目录与笔记结构¶
插件采用本地目录模型：
- 根目录：你选择的本地路径（默认为 <DSH_HOME>/dsh-notes）。
- 分组：根目录下的直接子目录（二级目录）即为分组。
- 笔记：分组目录下的 .md 文件即为笔记。
当你写入笔记时，如果对应的分组目录不存在，插件会自动创建该目录。
规则上下文¶
为了规范写作，插件支持读取规则文件。根目录或分组下匹配（不区分大小写）以下命名的文件会被识别为规则文件：
- AGENTS.md
- AGENTS.local.md
- CLAUDE.md
- *.rules.md
- *规则.md / *規則.md
在写作前，模型可以通过工具读取这些规则文件，了解约定后再执行文件写入。
Web 界面与工具¶
- 侧栏页面：点击「笔记」进入管理页面，可查看分组列表、规则预览、创建/编辑/重命名/删除笔记，以及切换根目录。
- 根目录切换：支持在页面内切换根目录，支持
~符号，留空则恢复默认路径。切换操作会立即生效并持久化。 - Agent 工具：插件向 DSH 注册了以下工具：
note_root：查看或切换根目录。note_list：查看分组概览，或查看分组下的笔记列表。note_rules：读取根规则或指定分组规则作为上下文。note_create：创建或更新笔记（自动创建分组）。note_read：读取笔记全文。note_delete：删除笔记。
使用方式¶
默认路径与切换¶
默认根目录为 <DSH_HOME>/dsh-notes。在 Web 页面中，使用「switch directory」功能指向任何绝对本地路径（支持 ~）。
规则与笔记的命名¶
- 规则文件和笔记文件共享同一命名空间。
- 如果文件名匹配规则命名规则（如
AGENTS.md），则该文件被视为规则，无法作为笔记创建。 - 粘贴完整的 Markdown 文件（包含 Front Matter）会原样存储，不会重复包装。
技术细节与限制¶
- 安全边界：浏览器仅通过受保护的路由访问数据，不直接接触磁盘。所有文件操作都经过严格的路径遍历字符过滤和存在性检查。
- 数据写入：Markdown 写入采用「临时文件 + 原子性重命名」机制，配合单写队列防止并发损坏。
- 大小限制：规则和笔记的读取有字节限制，超过限制会返回 413 状态码。
- 依赖项：
@deepseek-ai/dsh-tools和@deepseek-ai/schemastery为可选的 peer dependencies，用于扩展功能。
总结¶
dsh-notes 提供了一套完整的本地 Markdown 笔记管理方案，结合 Web UI 与 Agent 工具，使得笔记的创建、管理与上下文读取变得标准化。它遵循 MIT 协议，适合需要在 DSH 环境中进行本地化知识管理的开发者。
