前言¶
DeepSeek Harness（DSH）的生态理念是「一切皆插件」。在开发或使用 DSH Agent 时，常遇到资料读后即忘、笔记难以检索、文档风格难以统一的问题。dsh-study-buddy 是一个针对这一痛点的插件与 Agent 预设组合，旨在将零散的资料转化为结构化、可交互、可归档的 Markdown 笔记。
核心功能¶
这个插件通过一套固定的流程，把一份资料讲完、问透，并写成文档。
-
四步闭环
流程包含：读取资料 → 讲解 → 问答反诘 → 归档成文档。 -
结构化笔记
笔记按资料 / 章 / 节 / 块的层级成篇。每层都有对应的微目录作为导航。文件名不加序号前缀，阅读顺序由文件内的顺序键与微目录共同承担。 -
写法由你决定
插件不会自动生成统一的模板。它强制要求在 vault 根目录存在一个笔记期望.md文件。笔记的格式、结构、详略程度都由这个文件决定。 -
安全归档机制
在正式写入 vault 之前，插件会先列出文件夹规划供确认。只有确认后才会落盘。如果路径不在规划内或重复消费，写入操作会被拒绝。 -
纯 Markdown 数据
所有笔记都是 vault 里的普通 Markdown 文件。这意味着你可以直接用 Obsidian 打开编辑，也可以用 Git 进行版本控制。旧笔记在重写前会自动备份到.study/archive/目录，支持回退。
安装与启用¶
在安装前，请确保环境满足以下条件：
* 一份能跑的 DSH 部署（web profile）。
* Node.js 版本 >= 22。
* pnpm 已安装。
* DSH 版本要求 >=0.1.7-rc.1 <0.3.0-0。
1. 安装插件¶
使用官方命令将插件添加到 profile 中：
dsh plugin --profile web add dsh-study-buddy
2. 配置 Vault 路径¶
插件不包含机器路径，需要你在部署侧指定。推荐使用环境变量：
$env:DSH_STUDY_VAULT = 'D:\你的vault绝对路径'
重启 DSH 后生效。也可以通过 <DSH_HOME>/study-buddy.json 或覆盖预设配置中的 vaultRoot 来指定。
3. 配置笔记期望¶
这是插件工作的核心依据。必须复制默认模板到 vault 根目录：
Copy-Item presets/study/assets/笔记期望.md "D:\你的vault绝对路径\笔记期望.md"
如果未找到此文件，插件将拒绝写入笔记。
典型用法¶
安装并选择「学习伙伴」预设后，可以通过对话指令控制流程。
-
只读不讲解
如果只想看提取的内容，输入文件路径或“读取X”，插件只会输出读取报告，不会自动开始讲解。 -
逐步讲解
输入“讲解”或“讲讲”。插件会一次讲解一个原子知识点，并在每个点结束后询问：“清晰？细化 / 跳过？” -
深度问答
遇到不懂的点直接提问。插件会采用“三明治回答”：先给直击核心的 ≤3 句话，再解释底层逻辑，最后进行反诘追问，确保理解到位。 -
归档与整理
输入“整理笔记”或“归档”，触发十步归档流程。这包括检查未答追问、读取期望、生成目录规划、等待确认、逐块写入、更新微目录和覆盖度。 -
继续学习
如果会话中断，输入“接着讲”，插件会从上次断点继续。 -
修改旧笔记
对旧笔记进行修改时，插件会先展示“旧 vs 新”的对比，确认无误后才执行写入。
适用场景与注意事项¶
此插件适合需要将外部文档（PDF、PPTX等）转化为内部知识库的用户。它不联网，但会将其读取的内容（标题、正文、路径）发送给模型服务商处理，请勿将敏感数据放入同一个 vault。
升级注意：升级插件后，如果 DSH 没有自动加载新代码，需要删除 profile 目录下的 node_modules\dsh-study-buddy，然后重新运行 pnpm install。
总结¶
dsh-study-buddy 是一个将资料消化、内化、归档的完整工作流工具。它通过严格的文件夹规划、可定制的 Markdown 写法以及纯文本的数据格式，确保了知识沉淀的可控性与可追溯性。
