XieZongChen/dsh-md-notes

---

概述（Overview）

一个面向 DeepSeek Harness（DSH）的笔记插件：提供完整的 MD 笔记管理器 和 MD 笔记编辑器，对话内容可快速记入笔记。笔记可同步 Git 仓库维护。对话时可将笔记加入上下文。

适合谁：DSH Web 用户，想要本地、基于文件的笔记（无数据库、无云）——一键把对话存进笔记，之后在任意编辑器里继续编辑，并可用 Git 仓库备份 / 多端同步。

当前功能：

• 侧边栏笔记入口 → 全屏笔记管理器：按工作区分组的笔记列表（可折叠）、markdown 编辑/预览、保存、删除（页面内确认）、一键新建。
• 笔记搜索：管理器顶部搜索框，跨全部工作区搜标题 + 正文（多关键词 AND、大小写不敏感）；结果按工作区分组、命中行高亮，点命中行在编辑器中定位到该行并选中关键词；笔记行另有「在侧栏查看」动作（dsh ≥ 0.1.5-rc）。
• 右侧栏笔记查看器（dsh ≥ 0.1.5-rc）：对话文件链接 / 文件树 / 搜索 / @ chip 点击都能把笔记以 markdown 渲染打开在 dsh 右侧停靠面板；互链可直接跳转新 tab；正文中的本地图片内联显示（编辑仍在管理器）。
• 回答操作栏（复制按钮旁）→ 选择或新建一篇笔记，把该段对话（用户提问 + 回答）即时追加进去——文本直接取自对话本身，无需等待；分段标签跟随界面语言（思考内容不记入，只保留最终回答）。
• 对话引用笔记（@）：输入 @ 选择笔记（支持跨工作区，候选行带插件 logo），点击已插入的 chip 可在右侧栏预览；发送时插件后端把笔记内容注入模型上下文——模型直接引用，无需提示它读取文件；引用行只含相对路径，不泄露本机目录。
• Git 同步（可选，URL 驱动）：共享仓库模式（一个仓库管所有工作区，按工作区分子目录）或独立仓库模式（每工作区：URL + 分支 + 子路径）。推送 = 镜像同步（含删除）；更新 = 拉取 + 三向冲突确认；打开笔记自动拉取；推送被拒可「合并远端并重试」。管理器内每个工作区有 Git 同步卡片：显示「已同步 / 未推送 N 处」状态、远端有新提交时提示更新。
• 笔记写入互斥（写锁）：同一笔记写入期间跨会话锁定，入口 / 记入弹窗 / 管理器三处状态联动，写入完成自动还原。
• 设置面板（dsh 设置 → MD 笔记）：模式、仓库 URL / 分支 / 子路径、自动拉取、提交作者——表单控件与 dsh 原生一致。
• 主题与国际化：token 化配色适配明暗主题；UI 文案跟随 dsh 语言（中 / 英）；错误信息本地化。
• 版本更新提示：npm 有新版时显示黄色「有新版本需要更新」tag。

规划中（见 docs/TODO.md）：Git 冲突渲染与可视化解决、笔记能力增强（标题目录 / 互链反链等）、交互体验优化（编辑器脏状态提醒、保存快捷键等）。

兼容性（Compatibility）

dsh 快速迭代且不做向下兼容，固定 dsh 版本只适配固定插件版本。已验证组合见下表 （完整适配历史见 docs/compatibility.zh.md）：

版本对齐规则：插件只对齐 dsh 的稳定版——rc 与（将来的）final。dsh 的 npm latest 指向的就是 rc，即用户实际安装的版本；alpha 约 1-2 天一发、很快被同线 rc 收口，因此不逐版适配：一条 minor 线的 alpha 由该线 rc 的一次校验整体覆盖， 仅当插件要使用某个 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

插件未绑定具体 mainline commit；如需固定组合，请在安装时固定插件版本 （如 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 的 producer-owned 消息来源；*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。

安装 / 卸载（Install / Uninstall）

前置：已安装 dsh CLI，目标 profile 为 web。

从 npm 安装（推荐）：

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

然后重启 dsh web（bundle 层与 client 包元数据在进程内缓存，必须重启才生效）。

升级：

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。

快速开始（Quick start）

1. 安装插件（见上），重启 dsh web。
2. 新建笔记：点击侧边栏底部（设置上方）的笔记入口 → 在工作区行点「+」→ 弹窗里填标题（默认「未命名笔记 <日期>」）和可选的文件名 → 编辑内容 → 保存。
3. 记入对话：在某条回答下方点笔记图标（复制按钮旁）→ 选择目标笔记（或现场新建）→ 写入笔记。该回答及对应的用户提问会以「会话标题 -- 时间戳」分段追加到笔记末尾。
4. 引用笔记：在输入框输入 @ 选择笔记（可跨工作区），发送后笔记内容自动进入模型上下文。

笔记文件存放在各工作区的 .dsh-notes/ 目录（<工作区>/.dsh-notes），随时可以直接用任意编辑器打开修改。Git 同步为可选功能——配置一个仓库 URL 即可把笔记同步到远程（共享仓库或每工作区独立仓库）。

关于插件的全部功能与使用方式——笔记管理、记入对话、Git 同步（共享 / 独立仓库）、推送与更新、冲突处理、设置面板——请参阅 使用文档。

配置（Configuration）

所有选项都是插件 Config 键，可在 profile 的 cordis.patch.yml 中覆盖（patch 会整体替换该行的 config）：

- id: md-notes
  config:
    gitMode: 'off'               # 'off' | 'shared' | 'own'
    gitAutoPull: true            # 打开笔记时自动拉取远程

HTTP API 前缀固定为 /plugins/md-notes（前端硬编码同值，故刻意不做配置项）。

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

插件配置不含环境变量，也不涉及任何密钥。

已知局限（Known limitations）

• 无头 / SDK / ACP 部署不支持：插件依赖 webServer 服务，而它只由 dsh 的 web-app bundle 提供；dsh --profile sdk 之类的无头 profile 里插件不会加载（笔记与记忆都不可用）。 解锁条件见 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 换了设置 API 并引入 volatile schema，旧版请用 0.13.0）。dsh 不做向下兼容，升级 dsh 前请看兼容性。

权限与数据（Permissions & data）

• 文件系统：只读写各工作区 .dsh-notes 目录下的笔记（普通 .md 文件 + meta.json 缓存；笔记深度绑定工作区）；git 操作只触碰 $DSH_HOME/md-notes-repos/ 下插件管理的 clone。
• 网络：本机回环 HTTP API（POST <route>，浏览器 ↔ 本地 dsh 服务）与同源图标请求；此外仅有可选的 npm 版本检查（registry.npmjs.org，checkUpdate: false 可完全关闭）。无遥测、无其他外呼。
• 凭据：不收集、不传输任何凭据。

故障排查（Troubleshooting）

现象	处理
安装/升级后改动不生效	重启 dsh web —— bundle 层与 client 元数据缓存在进程内。
图标没更新	强制刷新页面；图标以 no-cache 提供，每次请求都会反映 assets/dsh-md-notes.svg 的最新内容。
插件没加载	验证层：dsh --profile web --dump-config，查找 md-notes 行。
从 git 安装且 add 失败	pnpm ≥10 默认拦截构建脚本；把打印出的包键加入 profile 的 pnpm-workspace.yaml 的 allowBuilds，然后重跑 add。
笔记无法创建/保存	先在 dsh 侧边栏新建工作区，确认其 .dsh-notes 目录存在且可写。

回滚：dsh plugin --profile web remove dsh-md-notes 即可恢复（笔记文件不受影响）。

贡献（Contributing）

详细内容见 CONTRIBUTING.zh.md。

仓库结构（Repository structure）

路径	内容
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/	构建产物（gitignored；npm 发布内容）

许可证与安全（License & security）

使用 MIT 许可证（见 LICENSE）。

安全问题：请通过仓库的 Security Advisory 私下报告，而不是公开 issue，以便在披露前处理。