前言¶
在 DeepSeek Harness (DSH) 的对话过程中，想法、决策、实施细节和后续任务会不断涌现。这些内容如果仅停留在聊天记录中，容易淹没或丢失。同时，在 DSH 和其他编辑器之间频繁切换会打断工作流。
dsh-notes-markdown 插件旨在 DSH 的侧边栏提供一个轻量级、持久化的 Markdown 笔记空间。它允许你在保持当前对话可见的同时，直接记录决策、计划、API 和任务，且无需切换窗口。
定位¶
该插件由维护者 Tieboyh 开发，核心定位是：
* 持久化笔记：侧边栏内的 Markdown Notes 页面，长期驻留。
* 真实文件：每个笔记都是本地 .md 文件，默认存储在 ~/.dsh/docs，可直接被编辑器、Git、脚本和智能体访问。
* 工作流整合：通过一键创建、自动保存、实时预览和源码模式，将文档管理融入 DSH 流程。
核心功能¶
该插件提供以下具体能力：
- 文档创建与管理：支持一键创建笔记（使用当前工作区名称和自动编号），支持打开、搜索、重命名和删除。笔记列表可折叠，并会记住用户的展开/收起状态。
- 双模式编辑：支持 Typora 风格的实时预览（Live edit）模式和精确的源码模式（Source mode）。源码模式适用于需要精确控制 Markdown 或使用不支持的扩展时。
- GFM 渲染与支持：支持 GitHub Flavored Markdown (GFM) 的实时渲染，包括标题、链接、列表、任务列表、引用、表格和围栏代码块。
- 自动保存与状态反馈：输入停止约 700 毫秒后触发自动保存，界面会有保存状态提示。切换或重命名文档前会先刷新未保存内容。
- 内容与路径操作：支持复制当前 Markdown 内容，或复制文档的绝对文件路径（便于与智能体协作）。
- 冲突检测与安全：包含版本检查机制，当另一个 DSH 窗口修改了文件时，会报告冲突而不是覆盖新内容。支持原子保存、重复名称保护、路径遍历保护和符号链接拒绝。
安装与启用¶
- 安装本插件：
dsh plugin --profile web add github:Tieboyh/dsh-notes-markdown
- 安装、升级或移除插件后，需重启 DSH Web 才能生效。
- 在 Better Sidebar 的
+菜单中找到并打开 Markdown Notes。
典型用法¶
- 边聊边记：在 DSH 对话窗口中记录技术设计、API 调试计划或实施检查清单。
- 保持文件流：将对话中产生的想法保存为本地
.md文件，确保数据不丢失且可被后续处理。 - 智能体协作：复制笔记的绝对文件路径，直接交给同一环境下的智能体使用。
- 常见场景：技术设计文档、API 记录、会议结论、可复用提示词、代码片段及 Mermaid 流程图源码。
注意事项¶
- 存储位置：笔记默认存储在
~/.dsh/docs目录，目录会自动创建。若需使用不同目录，可在启动 DSH Web 前设置环境变量DSH_NOTES_MARKDOWN_DIR。 - 文件名限制：当前版本笔记存储在单层目录中，文件名不能包含
/、\、隐藏文件前缀（如.）或路径遍历段。 - 版本机制：编辑停止约 700 毫秒后触发保存。若检测到文件在他处被修改，会提示冲突。
结语¶
dsh-notes-markdown 通过文件级持久化和侧边栏集成，解决了 DSH 用户在对话过程中记录和保存关键信息的痛点。它让笔记管理变得轻量且透明，适合需要频繁记录和查阅技术文档的开发者。
