学习伙伴笔记 V-Reason/dsh-study-buddy

dsh-study-buddy

给 DeepSeek Harness（DSH）的「学习伙伴」：一个插件 + 智能体预设，陪你把一份资料讲完、问透、写成自己的文档。

讲解按熟悉度自动切换快速或详细；输出自然、克制、不重复。笔记不是摘要卡片，而是 vault 里一篇篇能独立复读的 .md——写到哪个目录由你规划，写法由你 vault 根的《笔记期望.md》决定。

版本基线：v1.3.0 ｜ MIT ｜ 快速开始 · 用户使用指南 · 文档地图 · 更新记录

它替你解决什么

- 读完就忘 → 四步闭环：读取资料 → 自适应讲解 → 对话答疑 → 归档成文档
- 笔记像流水账 → 一个块 = 一个能独立阅读的知识单元，按 资料 / 章 / 节 / 块 成篇，每层有 微目录.md 当导航
- 写法不合口味 → 写法只看你的《笔记期望.md》（受众、文风、详略、结构、公式图表都由它决定），改完立即生效
- AI 乱建文件 → 归档前先出文件夹规划给你拍板，落盘路径必须在你确认的范围内
- 数据不是黑盒 → 就是 vault 里的普通 Markdown：Obsidian 手改、git 回滚永远有效；推翻重写前旧正文先进 .study/archive/ 可回退，删掉 .study/ 也不丢一篇笔记

快速开始

前提：一份能跑的 DSH 部署（web 配置档）+ Node.js ≥ 22 + pnpm。本仓库是插件 + 预设，不含 DSH 本体。
DSH 要求 >=0.1.7-rc.1 且 <0.3.0-0（更低版本没有 dsh.bundle.patch 这套声明式预设； 0.3 线未验证，见 安装与兼容性）。

1. 装进 DSH profile —— 本包是「bundle」：装它同时把「学习伙伴」预设声明进 profile
dsh plugin --profile web add dsh-study-buddy
本地开发也可以用：plugin_manager install_bundle target=<绝对路径> 装完确认 profile 的 dsh.profile.bundles 含本包（预设在下次启动/热重载时出现）

2. 告诉插件你的 vault 在哪（包内不含机器路径，三种给法任选） $env:DSH_STUDY_VAULT = 'D:\你的vault绝对路径' # ① 环境变量（推荐，重启 DSH 生效） ② 或写 <DSH_HOME>\study-buddy.json： {"vaultRoot":"D:\\你的vault绝对路径","skipDirs":["资源"]} ③ 或覆盖 presets/study.patch.yml 里 study 行的 config.vaultRoot（部署侧精调）

3. 把默认期望模板复制进 vault 根，改成你自己的写法（笔记写法的唯一来源） Copy-Item presets/study/assets/笔记期望.md "D:\你的vault绝对路径\笔记期望.md"

4. 重启 DSH，新建会话，选择「学习伙伴」预设

只读自检三步（都不需要翻日志）：plugin_manager list_bundles → 本包在列；plugin_manager list_plugins → include:preset-study 且 fiberPhase: active；新会话里 19 个 note_ / study_ 工具都在。

⚠ 第 3 步不是可选项：没有《笔记期望.md》时 note_write 会拒绝写入并给创建指引（有意为之——允许回退到内建写法会把"写法只看期望"变成两处口径）。
升级插件后若 DSH 没加载到新代码：删掉 <profileDir>\node_modules\dsh-study-buddy 再 pnpm install（依赖不自动刷新）。逐步详解见 用户指南 §3，出问题看 §11 排障。

安装与兼容性

| DSH 版本 | 本插件 | 说明 |
| >=0.1.7-rc.1 <0.3.0-0 | v1.3.0+ | 现行形态：自适应快速/详细讲解、自然正文优先、19 个工具；接受 0.1.7-rc.x / 0.2.0-rc.1 / 0.2.1-rc.2 |
| 0.2.1-rc.2 | v1.2.0 | 预设仍写 {{cwd}}，而 0.2.1 的 loop 只注册 provider / model → 首个模型请求前报 unknown prompt variable "{{cwd}}"，预设不可用 → 升到 v1.2.1 |
| 0.1.7-rc.1 / 0.1.7-rc.2 | v1.1.1 | 交付形态与注入来源都对，但 peer 范围 ^0.1.7-rc.1 的上界是 <0.2.0-0 → 在 0.2.0-rc.1 上判不兼容：整个 bundle 层被跳过，「学习伙伴」与 18 个工具一起消失 → 升到 v1.2.0 |
| ≥ 0.1.7-rc.1 | v1.1.0 | 交付形态对，但开场门禁的来源用了退场的 {kind:'plugin'} 包装：每个新会话的首条消息都会整轮失败（format v4 message requires a producer-owned source kind）→ 升到 v1.1.1 |
| ≤ 0.1.6 | v1.0.x | 目录式预设（%DSH_HOME%\.agent-presets\study\）；该目录自 0.1.7 起平台已不再读取 |

- 装法：dsh plugin --profile <name> add dsh-study-buddy（或 plugin_manager install_bundle），然后确认 dsh.profile.bundles 里有本包 —— 少了这一步只是"预设不出现"，不会报错，这是 2026-09-24 那次失效的真实形态（详见 技术文档 §9.2）。
- 升级 / 本地改动：profile 里记的是 github:V-Reason/dsh-study-buddy，所以改了必须先 git push，再 dsh plugin --profile <name> update dsh-study-buddy。只改本机不推，下一次 profile 里的任何 pnpm install（装卸别的插件也会触发）都会把 node_modules\<插件> 换回远端那个提交——旧版没有 dsh.bundle.patch，于是被从 dsh.profile.bundles 里摘掉、预设在注册表里消失，而 dsh web 只会报别的插件的错。pnpm tools/verify-deploy.ps1 -Profile <name> 的第 1、2 节就是为这种「看着改了、其实被回滚」准备的。另外：dsh plugin update 在装完扫描到不兼容时会拒绝安装并回滚（dsh: installation rejected: … nothing was installed），或者——如果这次 update 根本没改动那个依赖——只告警并返回 0。所以「没报错」不等于「是新的」，产物哈希仍要核。
- 兼容门禁：本包在 package.json 声明 peerDependencies["@deepseek-ai/dsh"]，当前值为 >=0.1.7-rc.1 <0.3.0-0。注意这条门禁判在交付形态上（DSH 按已装副本声明的范围判），失效形态随 DSH 版本不同：

| DSH 侧 | 表现 |
| 0.2.0+ | 跳过整个 bundle 层，启动 stderr 留一行 dsh: skipping profile bundle "dsh-study-buddy": Plugin … is incompatible with dsh …；plugin_manager list_bundles 里本包 error.code=incompatible-version、rows: [] → 预设整行与 19 个工具一起消失 |
| 0.1.7 ~ 0.1.x | 同上跳过，提示直接内联写在加载期 |

两种形态都不是「插件自己报错」，所以升级 DSH 后先跑 pnpm run verify:contract：它用平台自己的门禁判这个范围，并带一张离线版本表断言（没装 DSH 的机器/CI 上也跑）。用 dsh plugin allow-version 的 exact-version 豁免也能绕过，但有崩溃与丢数据的风险，本仓库的做法是提范围，不授豁免。忘了提范围的表现是「插件被跳过、工具全没」，而不是「插件报错」。
- 提示词变量：DSH 0.2.1-rc.2 起 loop 只注册 provider / model（cwd 已随 working-directory 迁移退场）。自定义 persona 模板不要再写 {{cwd}}——strict 插值会在首个模型请求前抛 unknown prompt variable；目录事实看 working-directory 的 Current working directory: … 上下文。tests/preset.spec.ts 与 verify:contract 都会拦。
- DSH 内部 API 漂移怎么办：本插件对 DSH 的依赖全部收在 src/host.ts（HOST_CONTRACTS 契约表 + 特性探测/降级），源码与产物里没有任何 @deepseek-ai/ 静态 import。升级 DSH 后先跑 pnpm run verify:contract：它会对着运行中的 DSH 逐点断言并指出「平台源码坐标 + 失效后果 + 改哪里」。
- 可选兼容层：@dsh-plugin/dsh-loader 装了就用它的稳定入口，没装完全照常（本包不 import、不 inject 它）。注意它当前的覆盖面是 settings 桥 / 包名别名 / Session.events 补丁，不含本插件的三个真实触点（工具注册、系统提示段、agent/pre-step），所以它是加分项而不是防线。

笔记长什么样

ID: 202610241430_ab12cd # note_write 自动生成标题: 高斯消元法领域: #计算方法-线性方程组 # 首个标签 = 领域键（可选）来源: 《计算方法》 # 资料名（必填）状态: 已确认 # 草稿 / 已确认 / 需更新来源章节: 《计算方法》第2章 线性方程组数值解法 / 2.1节顺序: 3 # 同目录阅读顺序（微目录排序用）简介: 用初等行变换把系数矩阵化为上三角，再回代求解。

直接法

用初等行变换把系数矩阵化为上三角，再回代求解……

关联
- 前置：[[矩阵与向量]]

- 没有必填小节，写什么、写多细看你的《笔记期望.md》；来源章节 是覆盖度总览的唯一数据源。
- 文件名不加序号前缀，阅读顺序由 顺序 键与 微目录.md 承担；检索覆盖 vault + 会话工作目录 + searchRoots 旧笔记，旧笔记默认只读。

三条硬门禁（为什么它写不乱）

1. 没读过《笔记期望.md》 → 不写（改过期望就得重读，挡住旧口径落盘）
2. 没有你确认过的文件夹规划 → 不写（提案只在对话里，凭据默认 24 小时过期，可 abandon）
3. 路径不在规划内 / 同一规划重复消费 → 不写

每条拒绝都带修复步骤，且磁盘零改动（测试逐条断言目标文件不存在）。

你说一句，它做什么

| 你说 | 它做 |
| 给文件路径 / "读取 X" | 只出读取报告（PDF/PPTX/DOCX 的内嵌图片自动逐张读），不自动开讲 |
| "讲解 / 讲讲" | 自动判断快速或详细，讲一个完整知识单元；默认不出重复笔记预览 |
| 提问 | 直接回答，再补机制、例子与边界；追问可选 |
| "快速 / 详细 / 自动" | 切换本会话讲解模式；新会话恢复自动 |
| "整理笔记 / 归档" | 十步归档：查未答追问 → 读期望 → 列目录 → 规划提案（你拍板） → 逐块写入 → 微目录 → 覆盖度 → 更新进度 |
| "接着讲" | 从上次断点继续（进度与记忆存在 vault 的 .study/） |
| 改旧笔记 | 永远先给"旧 vs 新"对比，你确认才动；追加 / 整体替换 / 只改定位 / 挪目录 |

最小配置

vaultRoot 是唯一必填项，而且它不在包里（包开源、多机共用）。三种给法按优先级：

| 序 | 给法 | 例子 |
| 1 | 预设声明行 presets/study.patch.yml 的 study 行 config.vaultRoot | 部署侧精调（会随包更新被覆盖的注意点见 用户指南 §3） |
| 2 | 环境变量 DSH_STUDY_VAULT（别名 DSH_VAULT_ROOT） | setx DSH_STUDY_VAULT "D:\vault"，重启 DSH |
| 3 | <DSH_HOME>/study-buddy.json | {"vaultRoot":"D:\\vault","skipDirs":["资源"],"searchRoots":[]} |

三者都没有 → 挂载失败（fail-loud），错误里会列出这三种给法。挂载时日志会打印一行 [dsh-study-buddy] vaultRoot ← <来源>：<路径>，排障第一问不必翻配置。

| 键 | 默认 | 说明 |
| vaultRoot | — | Obsidian vault 绝对路径；为空或文件系统根会挂载失败（fail-loud） |
| expectFile | 笔记期望.md | 期望文件名（vault 根下）；读取路径、门禁签名与回显都用它 |
| planTtlHours | 24 | 规划凭据有效期，超期要重新提案 |

其余键（stateDir / fallbackDir / domainFolders / skipDirs / searchRoots / includeSessionCwd / linkIntoNotes / lint. / indexTtlMs / maxWalkFiles）见 用户指南 §4 配置参考（含"来源与优先级"一节）。

隐私

vault 内容会出境：note_* 工具读出的标题、简介、正文片段、整篇原文与路径都会进入会话日志并发给模型服务商，.study/ 里的进度与记忆同理；插件自身不联网（全仓无 child_process、无 HTTP 客户端、无 eval）。
完整的边界与自查清单见 用户指南 §14 隐私与数据流向。不要把不适合交给模型服务商的内容放进同一个 vault。

文档

| 想知道 | 看这里 |
| 怎么装、怎么用、19 个工具、排障 | 用户使用指南 |
| 全部文档地图 +"改代码要同步哪些文档" | docs/README.md |
| 性能与成本（19 工具固定开销预算 ≤16.2 KB） | 用户指南 §12 |
| 为什么这样设计 / 怎么实现 | 设计文档 · 技术文档 |
| 本轮重构的来龙去脉 | 需求分析 → 架构选型 → 重构计划 |
| 逐版变更 / 踩过的坑与技巧 | 更新记录 · 经验文档 |
| 已知限制与路线图 | 用户指南 §13 |
| 全功能验证脚本 | check/prompt-verify-all-features.md |
| 历史归档（v0.9 审查原件、早期设计稿） | archive/README.md |

开发

pnpm install && pnpm run check # typecheck → vitest → esbuild 构建 lib/index.js

- src/ 零运行时依赖（只用 Node 内置模块）；模块清单、工具契约、测试布局见 技术文档。
- 想改行为？先读 docs/README.md §二"改代码要同步哪些文档"，再动手。
- DSH 升级后先跑这两条（只读，10 秒出结论；判读口径见 tools/README.md）：

pnpm run verify:contract # 交付形态 + 插件 ↔ 本机 DSH 的平台契约（没装 DSH 时自动跳过探针）
pnpm run verify:deploy -- -Profile web # 产物哈希 / 已装 bundle 的预设 patch / 技能目录 / 《笔记期望.md》

平台与插件之间的契约变更不会以编译错误的形式暴露，pnpm run check 对它无感；部署副本落后（插件升了、预设还是老模板，或 bundle 没被 profile 选中）同样是"看着改了其实没生效"。
verify:contract 还会断言本包交付形态：dsh.bundle.patch 存在、声明可解析、study 行不含 vaultRoot（这两条正是 2026-09-24 那次"预设整行消失、工具全没"的病根）。

致谢与许可

- 插件包结构与构建方式参考 dsh-at-file（MIT）
- 交互设计源自早期需求稿 docs/archive/design/DeepSeekHarness —— 通用学习 Agent.md（历史溯源；现行口径以 presets/study/skills/ 为准）
- MIT