dsh-study-buddy

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

讲解快节奏、听懂才往下走；笔记不是摘要卡片，而是 vault 里一篇篇能独立复读的 .md——写到哪个目录由你规划，写法由你 vault 根的《笔记期望.md》决定。

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

它替你解决什么

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

快速开始

前提：一份能跑的 DSH 部署（web profile）+ Node.js ≥ 22 + pnpm。本仓库是插件 + 预设，不含 DSH 本体。

# 1. 克隆并构建插件
git clone https://github.com/V-Reason/dsh-study-buddy.git
cd dsh-study-buddy
pnpm install
pnpm run check          # typecheck + 测试 + 构建 lib/index.js

# 2. 装进 DSH profile（<profileDir> 通常是 %DSH_HOME%\profiles\web）：在其 package.json 的
#    dependencies 里加 "dsh-study-buddy": "file:D:/path/to/dsh-study-buddy"，再 pnpm install

# 3. 部署预设
Copy-Item -Recurse presets/study "$env:DSH_HOME\.agent-presets\study"

# 4. 必改两步：agent.cordis.yml 里的 vaultRoot 换成你的 vault 绝对路径；
#    再把默认期望模板复制进 vault 根，改成你自己的写法（笔记写法的唯一来源）
Copy-Item presets/study/assets/笔记期望.md "<你的vault>\笔记期望.md"

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

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

笔记长什么样

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

## 直接法

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

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

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

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

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

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

你说一句，它做什么

最小配置

其余键（stateDir / fallbackDir / domainFolders / skipDirs / searchRoots / includeSessionCwd / linkIntoNotes / lint.* / indexTtlMs / maxWalkFiles）见 用户指南 §4 配置参考。

隐私

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

文档

开发

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          # 产物哈希 / 部署预设 / 技能目录 / 《笔记期望.md》

  平台与插件之间的契约变更不会以编译错误的形式暴露，pnpm run check 对它无感；部署副本落后 （插件升了、预设还是老模板）同样是"看着改了其实没生效"。

致谢与许可

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