MD 笔记 XieZongChen/dsh-md-notes

dsh-md-notes

DSH 第三方插件（bundle）：MD Notes Manager

用户指南 · 功能 · 架构 · 上下文 · AI 冲突 · 路线图 · 更新日志

概览

这是给 DeepSeek Harness（DSH）用的笔记插件。它提供完整的 MD 笔记管理器和 MD 笔记编辑器，让你把对话内容快速记成笔记。笔记可以同步到 Git 仓库来维护。

适合谁用：想要本地、基于文件的笔记（不用数据库，不上云）的 DSH Web 用户——一键把对话记成笔记，随时继续编辑 .md，再用 Git 仓库备份 / 同步。

当前功能：

- 侧边栏笔记入口 → 全屏笔记管理器：按工作区列出笔记（分组、可折叠），支持 markdown 编辑 / 预览、保存、删除（页内确认）、一键新建。
- 笔记搜索：管理器顶栏的搜索框会扫描每个工作区——标题和正文都搜（空格分隔关键词，AND 逻辑，不区分大小写）；结果按工作区分组，命中行高亮，点击命中项会在编辑器中打开该笔记并定位到那一行、选中关键词；每条笔记还有「在侧边栏查看」操作（dsh ≥ 0.1.5-rc）。
- 右侧边栏笔记查看器（dsh ≥ 0.1.5-rc）：对话里的文件链接、文件树、搜索、@ chip 点击，都会在 dsh 右侧可停靠边栏里以 markdown 渲染打开笔记；互链会跳到新标签页；正文里的本地图片内联渲染（编辑仍在管理器里进行）。
- 助手消息操作（复制按钮旁边）→ 选一条笔记或新建一条，把这段对话（用户提问 + 回答）立刻追加进去——文本直接从对话本身抓取，所以不用等；小节标签已本地化（不抓取推理内容——只抓最终回答）。
- 在对话中引用笔记（@）：输入 @ 挑选笔记（跨工作区也能选，候选行带插件 logo）；点击插入的 chip 会在右侧边栏预览笔记；发送时插件后端会把每条笔记的内容注入模型上下文，模型不用去读文件就能引用。引用行只带相对路径，绝不带本地绝对路径。
- Git 同步（可选，由 URL 驱动）：共享仓库模式（所有工作区共用一个仓库，按工作区分文件夹）或独立仓库模式（每个工作区单独配置：URL + 分支 + 子路径）。Push = 镜像同步（包含删除），Update = 拉取并三方确认冲突，打开时自动拉取，合并远端后重试。每个工作区在管理器里显示一张 Git 同步卡片：「已同步」/「N 条未推送」状态，远端有新提交时还会给出提示。
- 笔记写入互斥锁：对同一篇笔记的写入跨会话加锁 —— 写入完成前，侧边栏条目、选择器和管理器保持一致。
- 设置面板（dsh Settings → MD Notes）：模式、仓库 URL/分支/子路径、自动拉取、提交作者 —— 表单控件沿用 dsh 风格。
- 主题与国际化：基于 token 的颜色（浅色/深色），界面文案跟随 dsh 的语言（中文 / 英文），错误消息本地化。
- 更新通知：npm 上有更新版本时，显示黄色「有可用更新」标签。

路线图（见 docs/TODO.md）：可视化 Git 冲突渲染与解决、笔记能力增强（目录 / wiki 链接与反向链接）、交互体验打磨（编辑器未保存提醒、保存快捷键等）。

兼容性

dsh 迭代很快，且不提供向后兼容，所以固定的 dsh 版本只能匹配固定的插件版本。已验证的组合列在下面（完整适配历史见 docs/compatibility.md）：

版本对齐规则：插件只对齐 dsh 的稳定版本 —— rc 和（未来的）final 发布。dsh 在 npm 上的 latest dist-tag 指向 rc，用户实际安装的就是它；alpha 每一两天发一次，大约一周内就会被同一线的 rc 取代，所以不按版本逐个适配 —— 检查一次 rc 就覆盖整条线的 alpha 范围，只有插件想用某个 alpha 引入的能力，或要确认破坏性变更时，才检查具体 alpha。因此下表只列 rc/final 版本（早期 alpha 行作为历史保留）。

| 插件版本 | dsh 版本 | 验证日期 |
| 0.13.0 | 0.1.5-rc.2 | 2026-09-11 |
| 0.12.0 | 0.1.3-alpha.2 | 2026-09-07 |
| 0.11.0 | 0.1.3-alpha.2 | 2026-09-07 |

插件不锁定到某个主线提交；需要固定组合时，在安装时锁定插件版本（例如 dsh plugin --profile web add dsh-md-notes@0.13.0）。运行时依赖（@deepseek-ai/、react）声明为可选 peer 依赖，从 dsh 安装中解析。

未发布版本（NEXT_VERSION）：适配 dsh 0.1.7-rc.1（Session V4 由生产者持有消息源；16 图标系列更名为 *Medium），并要求 dsh ≥ 0.1.7-rc.1 —— 0.1.7 用 SettingsForms + volatile Config 字段取代了 ctx.settings.register()，为它构建的插件在更旧的 dsh 上无法加载。在它发布之前，请在 dsh 0.1.5-rc.2 上使用 0.13.0。

安装 / 卸载

前置条件：已安装 dsh 命令行，目标配置档为 web。

从 npm 安装（推荐）：

dsh plugin --profile web add dsh-md-notes

然后重启 dsh web（bundle 层和客户端包元数据会缓存在进程里，必须重启才能生效）。

升级：

dsh plugin --profile web update dsh-md-notes

需要重启 dsh web 才能生效。

卸载：

dsh plugin --profile web remove dsh-md-notes

从源码开发/调试：在插件项目的父目录下运行 dsh plugin --profile web add ./dsh-md-notes。

快速开始

1. 安装插件（见上），重启 dsh web。
2. 新建笔记：点击侧边栏底部的笔记入口（在 Settings 上方）→ 在工作区行上点击 + → 在对话框中输入标题（默认「Untitled note <date>」）和可选的文件名 → 在编辑器中输入内容 → Save。
3. 捕获对话：在任意助手回答下方，点击笔记图标（复制按钮旁边）→ 选择目标笔记（也可以当场新建）→ Write to note。用户提问和回答会以「<session title> -- <timestamp>」小节的形式追加到笔记中。
4. 引用笔记：在聊天输入框输入 @ 选择笔记（支持跨工作区）；发送时笔记内容会自动进入模型上下文。

笔记文件存放在各工作区的 .dsh-notes/ 目录（<workspace>/.dsh-notes）；你可以用任意编辑器直接打开和编辑。Git 同步是可选的——把插件指向一个仓库 URL，它就会保持笔记同步（共享仓库或按工作区独立仓库）。

插件能做的全部事情——笔记管理器、捕获对话、Git 同步（共享 / 按工作区独立仓库）、推送/更新、冲突处理、设置面板——见用户指南。

配置

所有选项都是插件 Config 键，可在配置档的 cordis.patch.yml 中覆盖（补丁会替换该行的整个 config）：

- id: md-notes
config:
gitMode: 'off' # 'off' | 'shared' | 'own'
gitAutoPull: true # pull remote before opening a note

HTTP API 前缀固定为 /plugins/md-notes（浏览器前端硬编码了同一个常量，所以刻意不做成可配置）。

| 键 | 默认值 | 含义 |
| gitMode | 'off' | Git 同步模式：'off' 关闭 / 'shared' 共享仓库 / 'own' 按工作区独立仓库。 |
| gitAutoPull | true | 打开笔记前先拉取远程。 |
| checkUpdate | true | 允许后端向 registry.npmjs.org 查询插件是否有新版本；设为 false 则完全离线。 |

本插件的配置中没有环境变量，也没有密钥。

已知限制

- 不支持 headless / SDK / ACP 部署：插件依赖 webServer 服务，只有 dsh 的 web-app bundle 才提供该服务，所以像 dsh --profile sdk 这样的配置档永不加载（那里既没有笔记也没有记忆）。解锁条件： docs/TODO.md §0.9。
- 图片不会通过 Git 同步：图片放在 .dsh-notes/assets/，而 Git 同步只镜像 .md（git.ts 里的同步/冲突逻辑是按文本设计的）。图片目前是本地文件——在另一台设备上看不到。
- 仅限 Web 形态：右侧边栏的笔记查看器需要 dsh ≥ 0.1.5-rc；在更旧的版本上这部分会静默禁用。
- 笔记按工作区划分：没有跨项目的个人库；每条笔记都属于某个工作区。
- 锁定 dsh 版本范围：本插件要求 dsh ≥ 0.1.7-rc.1（0.1.7 替换了 settings API，并引入 volatile schema；在更旧的 dsh 上用 0.13.0）。dsh 不保持向后兼容——升级 dsh 前先读 Compatibility。

权限与数据

- 文件系统：以纯 .md 文件（外加 meta.json sidecar）读写笔记，位置在每个工作区的 .dsh-notes 目录下（笔记与工作区绑定）；git 操作只触碰 $DSH_HOME/md-notes-repos/ 下由插件管理的克隆。
- 网络：一个回环 HTTP API（POST <route>，浏览器 ↔ 本地 dsh 服务器），以及从同一来源提供的图标；唯一的其他出站调用是可选的 npm 更新检查（registry.npmjs.org，设 checkUpdate: false 可完全关闭）。无遥测，无其他外部调用。
- 凭据：不收集、不传输任何凭据。

故障排查

| 现象 | 修复 |
| 安装/升级后改动不生效 | 重启 dsh web——bundle 层和客户端元数据缓存在进程里。 |
| 图标看起来是旧的 | 强制刷新页面；图标以 no-cache 提供，每次请求都反映 assets/dsh-md-notes.svg。 |
| 插件不加载 | 检查层：dsh --profile web --dump-config，找 md-notes 那一行。 |
| 从 git 安装且 add 失败 | pnpm ≥10 默认拦截构建脚本；在配置档的 pnpm-workspace.yaml 里把打印出的包键加到 allowBuilds 下，然后重新运行 add。 |
| 笔记无法创建/保存 | 确认工作区的 .dsh-notes 指向一个存在且可写的目录（先在 dsh 侧边栏创建工作区）。 |
| 感觉有点慢 | 用 docs/debug.md 里的浏览器探针抓请求耗时——以秒为单位区分排队时间与服务器时间。 |

回滚：dsh plugin --profile web remove dsh-md-notes 恢复之前的状态（笔记文件不受影响）。

贡献

详见 CONTRIBUTING.md。

仓库结构

| 路径 | 内容 |
| src/ | 源代码（Node 后端 + 浏览器前端） |
| src/host/ | 笔记领域（notes.ts）+ Git（git.ts）+ HTTP 层（http.ts）+ 上下文注入（context-inject.ts）+ 写互斥锁（keyed-lock.ts） |
| src/client/ | 浏览器前端：入口（index.ts）+ features/ 下的功能模块（每个功能一个目录；当某个功能大到单文件放不下时，会拆出功能私有的 components/ 和 hooks/ 子目录 —— 这种模式见 NotesManager/，以及 docs/architecture.md） |
| src/client/features/locales/ | 中英文 UI 词典（dsh locale 命名空间 md-notes） |
| assets/ | 插件图标（SVG 源文件 + PNG） |
| docs/ | 文档：usage.md/usage.zh.md（用户指南）、features.md（功能说明）、architecture.md、context.md（@ 引用）、git.md（Git 同步）、ai-conflict.md（AI 冲突解决）、state.md / write-lock.md（状态与写互斥设计）、manager-redesign.md（管理器重构）、search.md（笔记搜索设计）、debug.md（性能）、compatibility.md / compatibility.zh.md（dsh ↔ 插件版本兼容矩阵，中英双语）、TODO.md |
| scripts/ | 开发工具（例如 link-deps.mjs） |
| lib/ | 构建产物（已 gitignore；npm 发布的内容） |

许可证与安全

基于 MIT License 授权（见 LICENSE）。

安全问题：请通过仓库的 Security Advisory 私下报告，不要开公开 issue，这样在披露之前还有机会处理。