dsh-study-buddy

简体中文 | English

把一份资料讲透，并整理成真正能复读的笔记。

dsh-study-buddy 是 DeepSeek Harness（DSH）的「学习伙伴」插件与 Agent 预设。它陪你完成读取资料、自适应讲解、对话答疑和归档笔记，并把内容写成 Obsidian vault 里普通、可检索的 Markdown 文档。

当前版本：v1.6.0 · MIT · 支持 DSH >=0.1.7-rc.1 <0.3.0-0

为什么值得用

• 讲解跟着你的熟悉度走：新主题通常详细展开；有相关笔记且近期学过的主题可以快速回顾。
• 笔记不是聊天摘要：一块笔记就是一个能独立阅读的知识单元，可以有自己的例子、推导、代码、依赖图、时序图和关联。
• 写法由你决定：受众、文风、详略和领域侧重集中写在 vault 根的《笔记期望.md》里，修改后重新读取即可生效。
• 不会悄悄改乱目录：归档前先给文件夹规划，只有你确认后才写入；路径越界和重复写入会被拒绝。
• 文档始终属于你：内容是普通 Markdown，Obsidian 可以直接编辑，Git 可以版本控制，.study/ 删除后笔记也不会丢。

它适合正在学习计算机科学、游戏开发或工程技术的个人用户，也适合希望给 DSH 增加长期学习工作流的开发者。

核心能力

能力	你得到什么
自适应讲解	根据已有笔记和学习轨迹选择快速或详细；证据不足时默认详细
四步学习闭环	读取、讲解、问答、归档是一条连续工作流，不需要手工搬运聊天内容
计划感知	study_progress(brief) 返回当前主线、一个下一步和完成判据
期望驱动笔记	不用维护多套模板；写作规则来自你的《笔记期望.md》
文档块与微目录	按 资料 / 章 / 节 / 块 组织，每个主题目录都有可维护的 微目录.md
覆盖度与体检	检查来源章节、缺微目录、孤立链接、断链和重复标题
增量更新与存档	追加、替换、移动和改名都有明确流程；替换前旧正文会归档
跨会话连续性	进度、未答追问和偏好保存在 vault 的 .study/ 中

学习闭环

读取资料 → 自适应讲解 → 对话与追问 → 规划并归档
   ↑                                      │
   └──────── 进度、记忆与下一次复习 ←─────┘

读取和讲解是分开的：给出文件或说“读取”时只输出资料报告；明确要求“讲解”后才进入讲解。每次只推进一个完整知识单元，用户始终掌握下一步。

一次典型会话

你：读取《游戏引擎架构》第 2 章
它：输出资料报告，不自动开讲
你：讲解
它：按熟悉度选择模式，讲一个完整知识单元
你：整理笔记
它：先给文件夹规划，确认后才写入

快速开始

1. 准备环境

需要：

• 一份可运行的 DSH 部署，版本位于 >=0.1.7-rc.1 <0.3.0-0
• Node.js 22 或更高版本
• 一个 Obsidian vault，以及它的绝对路径
• 可选：读取 PDF / PPTX 资料时需要 Python、PyMuPDF 或 python-pptx

本仓库是插件与预设，不包含 DSH 本体。

2. 安装 bundle

dsh plugin --profile web add dsh-study-buddy

安装后确认 profile 的 dsh.profile.bundles 包含 dsh-study-buddy。本包通过 bundle 提供声明式预设；如果 profile 没有选中它，会话中的预设和工具都不会出现。

3. 配置 vault

在 <DSH_HOME>/study-buddy.json 中写入：

{
  "vaultRoot": "/absolute/path/to/your/vault"
}

Windows 也可以使用类似 "D:/Notes/Study" 的绝对路径。vaultRoot 是唯一必填配置，不写入仓库，因此重装插件不会覆盖它。

4. 复制笔记期望并启动

# Windows PowerShell
Copy-Item presets/study/assets/笔记期望.md "<你的 vault>/笔记期望.md"

# macOS / Linux
cp presets/study/assets/笔记期望.md "<your vault>/笔记期望.md"

重启 DSH，新建会话并选择「学习伙伴」预设。确认会话中出现 19 个 note_* / study_* 工具。 如果预设没有出现，先检查 profile 的 bundle 列表，而不是修改 vault 配置。

《笔记期望.md》不能省略。没有它时，写笔记会被有意拒绝，并给出创建指引。

笔记为什么不会乱

归档前有三道保护：

1. 当前会话必须读取过《笔记期望.md》。
2. 必须先给出文件夹规划，并由用户确认。
3. 落盘路径必须在已确认范围内，同一规划项不能重复消费。

需要重写笔记时，旧版本会先进入 .study/archive/，再写入新正文；之后可以从历史记录恢复。

隐私与数据边界

插件本身不联网，也不启动 shell 或 HTTP 客户端，所有文件操作都发生在本地 vault 和 .study/ 状态目录中。

但模型需要读到内容才能工作。note_* 工具返回的标题、简介、正文、路径，以及保存在 .study/ 中的进度和记忆，都会进入 DSH 会话日志，并作为请求内容发送给模型服务商。不要把不适合交给模型服务商的数据放进同一个 vault。

完整的数据流与安全检查清单见用户指南 §14（中文）。

兼容性与当前限制

• 当前支持 DSH >=0.1.7-rc.1 <0.3.0-0，提供 19 个 note_* / study_* 工具。
• 检索目前基于关键词和 CJK 双字组，不包含语义向量检索。
• 覆盖度依赖规范的 来源章节 字段；无法解析的内容会进入“未归类”。
• 详细配置、升级步骤、平台兼容历史和故障排查见中文用户指南。

文档

想了解	文档
安装、配置、工具与排障	用户使用指南（中文）
设计原则与关键取舍	设计文档（中文）
模块、API、规则与测试布局	技术文档（中文）
全部文档入口与维护约定	文档地图（中文）
版本变化与已知问题	更新记录（中文）

开发

pnpm install
pnpm run check
pnpm run verify:contract

pnpm run check 会执行类型检查、Vitest 测试和构建。verify:contract 用于检查插件与当前 DSH 的平台契约；未安装 DSH 时会跳过在线探针。

源码位于 src/，预设与技能位于 presets/study/，测试位于 tests/。

许可

MIT

插件包结构参考 dsh-at-file（MIT）。早期交互设计保存在 docs/archive/design/，现行行为以 presets/study/skills/ 和用户指南为准。