# dsh-study-buddy 用户使用指南（v1.0 · 文档式笔记）

> 版本基线：v1.1.1 ｜ 配套预设：「学习伙伴」（preset name）｜ 读者：使用者
>
> 这是给**使用者**看的完整指南：安装部署、逐键配置、18 个工具、笔记规范、Obsidian 配合、排障。
> 快速总览见 [README](../README.md)；文档地图见 [docs/README](README.md)；笔记规范细则以
> `presets/study/skills/note-format/SKILL.md` 为准；学习闭环细则以 `presets/study/skills/study-loop/SKILL.md` 为准。
>
> **v1.0 与 v0.9 的最大差别**：笔记从"原子卡片"改为**文档式笔记块**；写法不再由代码里的模板决定，
> 而是由你 vault 根的 **《笔记期望.md》** 决定；归档前必须先做**文件夹规划**并经你确认（三条硬门禁）。

---

## 目录

1. [这是什么](#1-这是什么)
2. [功能速览](#2-功能速览)
3. [安装与部署](#3-安装与部署)
4. [配置参考（逐键详解）](#4-配置参考逐键详解)
5. [核心概念](#5-核心概念)
6. [日常使用指南（按场景）](#6-日常使用指南按场景)
7. [工具参考（18 个工具）](#7-工具参考18-个工具)
8. [笔记规范](#8-笔记规范)
9. [在 Obsidian 中的配合](#9-在-obsidian-中的配合)
10. [检索原理与技巧](#10-检索原理与技巧)
11. [故障排查手册](#11-故障排查手册)
12. [性能与成本](#12-性能与成本)
13. [已知限制与路线图](#13-已知限制与路线图)
14. [隐私与数据流向](#14-隐私与数据流向)
15. [开发与测试](#15-开发与测试)
16. [附录](#16-附录)

---

## 1. 这是什么

`dsh-study-buddy` 是给 [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeekHarness)（DSH）做的**「通用学习 Agent」模式**，由两部分组成：

| 组成 | 是什么 | 装在哪里 |
| :-- | :-- | :-- |
| **插件**（本仓库 `src/`，构建产物 `lib/index.js`） | 注册 18 个 `note_*` / `study_*` 工具，用 `node:fs` 直写你的 Obsidian vault | 你的 DSH profile 的 `node_modules` |
| **预设**（本仓库 `presets/study.patch.yml` + `presets/study/`） | 「学习伙伴」Agent：persona + 6 个技能（`study-loop` / `note-format` / `file-reading` / `incremental-update` / `domain-adaptation` / `memory-auto`）+ 默认期望模板 + 插件挂载行 | **随包发**：`package.json` 的 `dsh.bundle.patch` → 你在 profile 里选中本包即生效（DSH ≥ 0.1.7-rc.1） |
| **机器相关配置** | `vaultRoot`（以及可选的 `skipDirs` / `searchRoots` / `domainFolders`） | **不在包里**：`DSH_STUDY_VAULT` 环境变量或 `<DSH_HOME>\study-buddy.json`（见 §3.5） |

一句话定位：**快节奏、听指挥、把知识沉淀成可独立复读的文档式笔记，按你规划的目录结构写进你的 Obsidian vault**。

核心理念（与 v0.9 一致的三条不变量）：

- **磁盘是唯一真相**：笔记就是 vault 里普通的 `.md`（带 frontmatter）。Obsidian 手改、git 回滚永远有效；插件按 mtime/ctime/大小签名重扫索引，不与你的编辑打架。
- **决定权在你**：讲不讲、写什么、**落到哪个目录**、改不改旧笔记，都由你下令。归档前必须先看你确认过的规划。
- **fail-loud**：配置错误、状态文件损坏、门禁未满足一律抛错并给出修复步骤，不静默降级。
- **内容会出境**：vault 正文、路径、进度与记忆都会随工具结果进入会话日志并发给模型服务商；插件自身不联网。详见 [§14 隐私与数据流向](#14-隐私与数据流向)。

---

## 2. 功能速览

| 功能 | 一句话 | 详见 |
| :-- | :-- | :-- |
| 四步学习闭环 | 读取 → 讲解 → 问答 → 归档，每步有模板和检查清单 | [5.1](#51-四步学习闭环) |
| 指令驱动 | 读取 ≠ 讲解；默认待命，一次只执行你的一条指令 | [5.5](#55-指令驱动状态机) |
| **笔记期望（热配置）** | 写法只看你 vault 根的《笔记期望.md》，代码里没有模板 | [6.3](#63-笔记期望热配置) |
| **文件夹规划（硬门禁）** | 归档前先出目录+块清单提案，你拍板后才落盘 | [6.6](#66-归档整理笔记) |
| **文档式块** | 一个块 = 一个可独立阅读的知识单元；无必填小节、字数不设限 | [8](#8-笔记规范) |
| **微目录** | 每个主题目录都有 `微目录.md`，工具生成、手写导读保留 | [7.9](#79-note_toc--生成微目录) |
| **覆盖度总览** | 按 `来源章节` 聚合出"这个主题记全了没有" | [7.6](#76-note_overview--主题总览与覆盖度) |
| **历史存档** | 推翻重写时旧正文存 `.study/archive/`，正文不留历史块；可回退 | [6.10](#610-更新与回退) |
| 增量更新（活笔记） | 补充追加；推翻替换并先存档；决定权在你 | [6.7](#67-增量更新活笔记) |
| 多根只读检索 | `note_search` 覆盖 vault + 工作目录 + `searchRoots` 旧笔记 | [10](#10-检索原理与技巧) |
| 跨会话进度与记忆 | 断点/未答追问/偏好持久化；首条消息**硬门禁** | [6.8](#68-进度与记忆附指挥词速查) |
| 轻量 & 便宜 | 工具 schema 固定开销约 14.7 KB / 18 工具 | [12](#12-性能与成本) |
| 可靠性 | 原子写；路径越界防护；门禁拒绝时磁盘零改动（测试布局见 [技术文档](技术文档.md) §8） | [11](#11-故障排查手册) |

---

## 3. 安装与部署

### 3.1 前提

一份**可运行的 DSH 部署（web profile）**；Node.js ≥ 22 与 pnpm（锁文件为 pnpm 11）；一个 Obsidian vault 目录（绝对路径）。
若需读取 PDF/PPTX：本机 Python 环境，PDF 需要 `PyMuPDF`（新版本 `import pymupdf`），PPTX 需要 `python-pptx`；DOCX 用标准库即可。

### 3.2 获取插件

```powershell
git clone https://github.com/V-Reason/dsh-study-buddy.git
cd dsh-study-buddy
pnpm install
pnpm run check        # typecheck + 测试 + 构建 lib/index.js
```

直接用发布版可以跳过这步：§3.3 的 `dsh plugin add dsh-study-buddy` 会自己取包并跑构建。

### 3.3 装进 DSH profile（**关键步**）

```powershell
dsh plugin --profile web add dsh-study-buddy
# 本地开发/未发布时：plugin_manager install_bundle target=<仓库绝对路径>
```

装完**必须确认 profile 的 `dsh.profile.bundles` 含 `dsh-study-buddy`**——本包是 bundle：
它携带的 `presets/study.patch.yml` 只有被选中才会被 DSH 读入。少了这一步的表现是
**预设整行不出现、工具全没，但没有任何报错**（这正是 2026-09-24 DSH 0.1.7 那次失效的形态）。

### 3.4 预设是声明式的（不要再复制预设目录）

DSH 0.1.7-rc.1 起**删除了目录式预设**（提交 `d1e22a7e24` / #4569）：`%DSH_HOME%\.agent-presets\<id>\`
再没有任何读者。所以：

- 不要再往 `.agent-presets\study\` 复制/编辑东西；**升级前复制过请删掉那个目录**（留着只会误导排查）。
- 预设的 persona、工具行、技能、期望模板全部**随包发**（`presets/study.patch.yml` + `presets/study/{skills,assets}`）；
  要改就改仓库/包，再让 profile 的副本跟上（§3.7）。
- 机器相关的只有 `vaultRoot` 等少数键，走 §3.5 的用户级来源——**不会因为你重装插件而丢**。

### 3.5 给 vaultRoot + 复制期望模板（两步）

**第一步：告诉插件你的 vault 在哪**（三种给法，按优先级）：

```powershell
# ① 环境变量（推荐：一处生效，所有会话共用；设完重启 DSH）
setx DSH_STUDY_VAULT "D:\你的vault绝对路径"      # 当前用户级永久环境变量
# ② 或写用户级配置（键名与预设声明里的 config 完全一致）
'{ "vaultRoot": "D:\\你的vault绝对路径", "skipDirs": ["资源"] }' | Set-Content "$env:DSH_HOME\study-buddy.json" -Encoding utf8
# ③ 或改预设声明里 study 行的 config.vaultRoot（部署侧精调；注意重装包会被覆盖）
```

三者都没有 → 挂载失败（fail-loud），错误里会列出这三种给法。挂载日志会打印一行
`[dsh-study-buddy] vaultRoot ← <来源>：<路径>`，排障第一问不必翻配置。
`vaultRoot` 是**挂载期不变量**：改完要重启 DSH（或让预设重新挂载）才生效。

**第二步：把默认期望模板复制进 vault 根并改成你的写法**：

```powershell
Copy-Item presets/study/assets/笔记期望.md "<你的vault>\笔记期望.md"
```

这份文件是笔记写法的**唯一来源**；缺失时写入会被门禁拒绝（这是有意的，见 [6.3](#63-笔记期望热配置)）。
另外可选：`domainFolders`（领域键 → 目录的**快捷方式**，不传 `path` 时的兜底）、`skipDirs`、
`searchRoots`、`includeSessionCwd` —— 都能写在 §3.5 的 `study-buddy.json` 里，见[第 4 章](#4-配置参考逐键详解)。

### 3.6 启动并选择预设

重启 DSH，新建会话，在预设列表中选择 **「学习伙伴」**（id `study`）。

只读自检三步（不需要翻日志）：

```
plugin_manager list_bundles                     → 本包在列（enabled）
plugin_manager list_plugins                     → include:preset-study 且 fiberPhase: active（failed 时看 diagnostic）
新会话里                                        → 18 个 note_* / study_* 工具都在
```

### 3.7 升级插件

`dsh plugin --profile web update dsh-study-buddy`（或删掉 `<profileDir>\node_modules\dsh-study-buddy`
再 `pnpm install`），然后重启 DSH。**预设/技能/期望模板随包更新**，你写在
`<DSH_HOME>\study-buddy.json` 里的机器配置不受影响。

改完用这两条只读命令判"到底生效了没"（10 秒出结论）：

```powershell
pnpm run verify:contract                 # 交付形态 + 插件 ↔ 本机 DSH 的平台契约
pnpm run verify:deploy -- -Profile web   # 产物哈希 / 已装 bundle 的预设 patch / 技能目录 / 期望文件
```

> **升级 DSH 本体**同样要跑上面两条：DSH 0.1.5 把 persona 行的 `text` 改成必填 `prefix`
> （旧副本报 `invalid config: $.prefix missing required value`）；0.1.7-rc.1 删除了目录式预设
> （症状是"预设消失且不报错"）。平台改动不会变成编译错误，`pnpm run check` 对它无感——
> 这两条命令就是为这段盲区准备的。

> ⚠ 部署形态：若启动器**以 vault 目录作为 DSH 工作目录**（`vaultRoot` == `{{cwd}}`），这是**受支持**的形态；插件只拒绝"文件系统根"这一真正危险的落盘目标。

---

## 4. 配置参考（逐键详解）

配置有**四个来源**（后者覆盖前者，逐键合并）：

| 序 | 来源 | 位置 |
| --: | :-- | :-- |
| 1 | 内置默认值 | 下表"默认"列 |
| 2 | 用户级配置 | `<DSH_HOME>\study-buddy.json`（键名与下表一致；不是合法 JSON / 未知键只告警，不阻断挂载） |
| 3 | 环境变量 | `DSH_STUDY_VAULT`（别名 `DSH_VAULT_ROOT`）；**只管 `vaultRoot`** |
| 4 | 预设声明行 | `presets/study.patch.yml` 里 `study` 行的 `config`（部署侧精调；重装包会回到包内取值） |

| 键 | 默认 | 预设当前值 | 说明 |
| :-- | :-- | :-- | :-- |
| `vaultRoot` | — | **不写**（机器相关，出包） | Obsidian vault 绝对路径。四层都没有 / 为文件系统根会**挂载失败**（fail-loud）。日志里回显来源。 |
| `expectFile` | `笔记期望.md` | `笔记期望.md` | **《笔记期望.md》的文件名**（位于 vaultRoot 根）。缺失时 `note_write` 拒绝写入并给创建指引。 |
| `planTtlHours` | `24` | `24` | 规划凭据有效期（小时）。超期必须重新提案——这是门禁的**防死锁**设计。 |
| `stateDir` | `.study` | `.study` | 状态目录（相对 vaultRoot）：`progress.json`、`memory.json`、`session.json`、`plans/`、`archive/`。 |
| `fallbackDir` | `未分类` | `未分类` | 未映射领域且规划未给路径时的兜底目录，实际写入 `未分类/<领域名>/`。 |
| `domainFolders` | `{}` | 见预设 | 领域键 → 目录的**快捷方式**（v1.0 起落盘目录以规划的 `path` 为主）。支持多键别名。 |
| `skipDirs` | `[]` | `[资源]` | 额外跳过扫描的**顶层**目录名。内置已跳过 `.obsidian` / `.trash` / `.study` / `.git` / `node_modules`。 |
| `includeSessionCwd` | `false` | `true` | 把会话工作目录（`{{cwd}}`）的旧笔记纳入检索；与 vault 相同/嵌套时自动去重。 |
| `searchRoots` | `[]` | `[]` | 额外检索根（绝对路径或相对 vaultRoot）：固定旧笔记库，**只读**。目录不存在 → **挂载失败**。 |
| `linkIntoNotes` | `false` | `false` | `note_link` 是否允许写无 ID 的旧笔记（默认只写笔记侧）；同时决定只读根是否可写。 |
| `lint.residueLevel` | `warn` | 未设置 | 会话残留级别：`off` / `warn` / `error`。`off` 时报告单列 `⊘ 未执行`（不当成通过）。 |
| `lint.rulesOff` | `[]` | 未设置 | 禁用的规则 id 列表。**写错/写已删除的 id 会在挂载时报错**并列出可用 id。 |
| `indexTtlMs` | `2000` | 未设置 | 索引缓存 TTL（毫秒）：TTL 内跳过全库 `stat`。**未命中会自动强制重扫一次**，所以在 Obsidian 里刚写完立刻就能搜到；设 `0` = 每次调用都重扫。 |
| `maxWalkFiles` | `20000` | 未设置 | 每根扫描**文件数安全阀**：超限**截断扫描**并在报告里 `⚠` 提示（不再让所有工具失败）。 |

> **v1.0 已删除的键**：`mocDir`（`card_moc` 退场，导航改由各级微目录承担）、`templateHints`（三型模板退场）。
> 写进 preset 也不会生效——`tests/preset.spec.ts` 会直接断言这两个键不存在。

**调优思路**：目录是大规模整理过的，就为每个主题目录建一对「子域键 → 子目录」并保留原键兜底；再用 `study_memory(set prefs.xxx=…)` 把新约定写进跨会话记忆。

---

## 5. 核心概念

### 5.1 四步学习闭环

```
阶段一·读取（摄入）   你给路径/说"读取 X" → 输出读取报告（只报告，不讲）
阶段二·讲解（拓展）   你说"讲解" → 一次一个原子点，讲完问"清晰？细化/跳过？"
阶段三·问答（反诘）   你提问 → 三明治回答：直击 ≤3 句 → 底层逻辑 → 反诘追问
阶段四·归档（笔记）   你说"整理笔记/归档" → 读期望 → 规划确认 → 落块 → 微目录 → 覆盖度
```

红线（persona 内建，违反即失职）：
- 不替用户写完整项目代码（引导拆解，单次 ≤100 行完整代码，超出拆片段并标注作用/依赖/输入输出）。
- 不假装理解图片（识别不了如实说，请补文字）。
- 读取后未经命令不讲解。
- **不跳过归档前置**：未答追问先问答；**未读期望、未确认规划不写笔记**。
- 无记忆不办事：对话历史为空的首条消息先 `study_memory(get)` + `study_progress(get)`，读取结果返回前不响应。

### 5.2 文档块

- 一个**块** = 一个**可独立阅读的知识单元**，落成 vault 里一篇普通 `.md`，带 frontmatter（`ID`/`标题`/`领域`/`来源`/`状态` + 文档键 `来源章节`/`顺序`/`简介`）。
- **ID**：`YYYYMMDDHHmm_随机6位hex`（如 `202610241430_ab12cd`），由 `note_write` 自动生成；`note_id` 只是**预生成占位符**，`note_write` **不会使用**它。
- **三种状态**：`草稿` / `已确认` / `需更新`。
- **文件名** = 标题清洗后（Windows 非法字符替换、≤80 字符）**不加序号前缀**；同目录重名时自动加 `_ID末6位`，再冲突用完整 ID。
- 落盘目录由**文件夹规划**决定；未给 `path` 时回退 `domainFolders` 快捷方式，仍未映射落 `未分类/<领域>/`。

### 5.3 文档类型三态

| 类型 | 判据 | 能力 |
| :-- | :-- | :-- |
| **块** | 有 `ID` **且**有 `来源章节` | 完整能力；计入覆盖度 |
| **存量卡** | 有 `ID`，无 `来源章节` | 可检索/读取/更新；补上 `来源章节` 即升级为块（不需要专门工具） |
| **旧笔记** | 无 `ID`（vault 内旧文件或只读根） | 只读；`linkIntoNotes: true` 才允许写关联 |

### 5.4 检索根

`note_search` / `note_get` 的范围是**多个根**的并集：vault（可写）、`searchRoots`（只读）、会话工作目录（只读）。
同一文件被多根扫到按规范化路径去重，**vault 标签优先**；命中会标注 `类型：块/存量卡/旧笔记` 与 `路径`。

### 5.5 指令驱动状态机

```
待命 ──(给路径/"读取 X")──▶ 读取（只出报告）──▶ 待命
待命 ──("讲解/讲吧/开始讲解")──▶ 讲解（一次一个原子点）──▶ 待命
待命 ──(提问)──▶ 问答 ──▶ 待命
待命 ──("整理笔记/归档")──▶ 归档（十步含门禁）──▶ 待命
待命 ──("接着讲")──▶ 从断点续讲 ──▶ 待命
```

默认状态是**待命**：每次只执行你当前一条指令，不自动进入下一步、不续讲。

### 5.6 磁盘上有什么

```
vault/
├── 笔记期望.md                  # 写法唯一来源（你自己维护）
├── <各主题目录>/块.md           # 文档块（带 ID）
├── <各主题目录>/微目录.md        # 主题导航入口（note_toc 生成）
├── 未分类/<领域名>/块.md        # 未映射领域兜底
├── .study/                      # 过程状态（内置跳过扫描；删掉不丢笔记）
│   ├── progress.json            # 学习进度
│   ├── memory.json              # 跨会话记忆（含 _autoPrefs 自迭代开关）
│   ├── session.json             # 门禁状态：期望已读签名 + 待消费规划
│   ├── plans/<planId>.json      # 规划凭据与消费记录（提案只在对话里，这里只存凭据）
│   └── archive/<ID>/<时间戳>.md  # 被推翻/替换的旧正文
└── ...旧笔记.md                 # 无 ID = 旧笔记（只读侧）
```

---

## 6. 日常使用指南（按场景）

### 6.1 新会话开场（自动衔接）

新会话第一条消息，Agent 执行**硬门禁**：先 `study_memory(get)` + `study_progress(get)`（get 首行含「自迭代记忆：开/关」），读取结果返回前不响应指令。有进度/记忆 → 首行给衔接提示并问"接着讲？"；无 → 正常待命。

### 6.2 读取资料（仅读取）

**触发**：给文件路径 / "读取 X" / "看一下" / 上传或粘贴截图。

工具链固定（`file-reading` 技能）：图片 → `read_image`；文本/代码 → `read`；PDF → `pwsh` + Python PyMuPDF 提文本 + 含图页渲染 PNG；PPTX → python-pptx；DOCX → 标准库解 `word/document.xml`。

**输出**只有：文件信息 / 内容骨架 / 一行重叠预警（来自一次 `note_search`，只允许一行）。

### 6.3 笔记期望（热配置）

- 位置：`<vaultRoot>/笔记期望.md`（固定；文件名可用 `expectFile` 改）。
- 内容：受众、文风、详略、结构、公式与代码、图表与对比、交叉引用、命名与落盘习惯、**领域侧重**、自检清单。自由 Markdown。
- **可选**检查项语法：`- [检查] 禁止 xxx` / `- [检查] 必须 xxx`（支持 `理由：…` 与 `严重：error|warn|info`）——写了才会被 `note_lint` 检查。
- Agent 每次归档前必读（`note_expect_get`）；**你中途改了期望，签名就变，Agent 必须重读**才能继续写。
- 缺这份文件时写入会被拒绝——**不回退到内建写法**（否则"约束只从期望来"就变成两处口径）。

### 6.4 讲解（仅你命令触发）

**触发**："讲解 / 讲吧 / 开始讲解"。一次**一个原子点**，≤15 行，通俗重构；讲完出「笔记预览」（文档式块，不带 ID）并问"清晰？细化/跳过？"，然后回待命。

### 6.5 提问（三明治回答）

① 直击 ≤3 句 → ② 底层逻辑一两句 → ③ 反诘收尾（"别问了"才不带）。引用笔记标 `（详见笔记：路径）`。

**领域适配**：Agent 按资料/提问切换侧重——**但侧重表在《笔记期望.md》里**（v1.0 起 `domain-adaptation` 技能不再自带标准侧重表）。期望里没写这个领域时，Agent 会先问你或建议你补一条。

### 6.6 归档（整理笔记）

**触发**："整理笔记 / 生成笔记 / 归档"。

十步（细则见 `study-loop` 技能）：

```
1. study_progress(get)    未答追问未清 → 先提示并问答
2. note_library(check)    库状态 + 期望是否已读 + 有无待消费规划
3. note_expect_get        读《笔记期望.md》（门禁开门；改过要重读）
4. note_list（可多次）     探明现有层级，判断哪些目录可复用
5. note_plan              出提案（目录 + 块清单 + 顺序 + 来源章节）→ 你拍板
6. note_plan(confirm)     拍板后确认凭据（rootPath 传 planId）；有效期从确认时刻起算
7. note_write × N         逐个落块（只重组去重，不加新知识）
8. note_link              建 prev/next/sibling 关联
9. note_toc               生成/刷新微目录
10. note_overview         回报覆盖情况与缺口
11. study_progress(set) + study_memory(set lastSummary=…)
```

**三条硬门禁**（工具会拒绝，不是靠 Agent 自觉）：

| 门禁 | 拒绝时的提示 |
| :-- | :-- |
| 未读期望 | `未读取笔记期望——请先调用 note_expect_get …` |
| 期望已更新 | `笔记期望.md 已更新（内容变了）——请重新调用 note_expect_get` |
| 无规划 | `本次会话没有已确认的文件夹规划——请先调用 note_plan 输出提案，用户拍板后用 note_plan(action=confirm) 确认，再写入` |
| 规划未确认 | `规划尚未确认（planId：…）——请让用户拍板后用 note_plan({ action: "confirm", rootPath: "…" }) 确认` |
| 规划过期 | `规划已过期（超过 24 小时，planId：…）——请重新调用 note_plan 提案并确认（确认后有效期重新起算）` |
| 路径越界 | `"…" 不在本次规划范围（规划根：…）——请重新规划把该目录纳入范围` |
| 重复写入 | `该块已在本规划中写入过：…（如需重写，请重新规划或改用 note_update）` |

**典型对话**：

```
你：生成笔记
Agent：已检查未答追问：0 条。
  已读期望（笔记期望.md，86 行）。
  规划提案（planId：202610241430_ab12cd）
  - 规划根：计算机通识/计算方法/第2章 线性方程组数值解法
  - 本次将新建目录：…/直接法
  | # | 块 | 落盘路径 | 来源章节 | 顺序 |
  | 1 | 高斯消元法 | …/直接法/高斯消元法.md | 《计算方法》第2章 / 2.1节 | 1 |
  确认后我再逐个落盘；结构与顺序要改，直接说改哪里。
你：可以
Agent：→ note_plan(action=confirm)：已确认规划（planId：202610241430_ab12cd）
  → note_write ×2
  → note_toc：微目录.md（收录 2 块）
  → note_overview：《计算方法》第2章 线性方程组数值解法——2 篇（节：2.1、2.2）
  已写入：计算机通识/计算方法/…/直接法/高斯消元法.md（ID：202610241431_3f9a01）……（整篇）
```

### 6.7 增量更新（活笔记）

新内容与旧笔记相关时，Agent 先给"旧 vs 新"对比，再由你决定：

| 情形 | 动作 | 结果 |
| :-- | :-- | :-- |
| 补充 | `note_update(append)` | 追加进正文（可指定小节）；**不产生版本块** |
| 推翻/大改 | `note_update(replace)` | **旧正文先存入 `.study/archive/`** 再写新版；正文里不留 `<details>` |
| 只改一句话定位 | `note_update(definition)` | 字段级微调，不算知识更新 |
| 挪目录 | `note_update(move)` | 搬到 `targetPath`；记得重跑 `note_toc` |
| 无关 | `note_write` + `note_link(next)` | 新块 + 与旧块建关联 |

**你拒绝 → 不写任何文件。**

### 6.8 进度与记忆（附指挥词速查）

| 你说 | 发生什么 | 底层 |
| :-- | :-- | :-- |
| "接着讲" | 从上次断点继续 | `study_progress(get)` 找断点 |
| "清空进度" | 只清进度位置，记忆保留 | `study_progress(clear)` |
| "记住……" | 写跨会话记忆（偏好/约定） | `study_memory(set)`，惯例键 `prefs.*` |
| "忘了……" | 删对应记忆 | `study_memory(remove)`；键不存在时明确提示且不写盘 |
| "开启自迭代" / "关闭自迭代" | 偏好/约定自动记录 | `study_memory(set _autoPrefs=on/off)` |
| "清空记忆" | 彻底重来（含开关） | `study_memory(clear)`（不动进度） |
| "别问了" | 停止反诘追问 | persona 行为 |
| "先到这 / 结束" | 收尾写小结 | `study_memory(set lastSummary=…)` |
| "回退 / 恢复旧版本" | 从存档恢复 | `note_history(list)` → `note_restore` |

- 进度四要素：当前资料、当前小节、未答追问队列、触及笔记 ID（`set` 为**整体替换**）。
- 记忆键名 ≤64 字符、值 ≤4000 字符；保留键 `lastSummary`（置顶）与 `_autoPrefs`（on/off，只接受 set/remove）。
- 自迭代开启后：Agent 自动把持久偏好写入 `prefs.*`（每类一个键、覆盖更新），每次标注「（已自动记入偏好：prefs.xxx）」。
- 「清空进度」与「清空记忆」互不影响。

### 6.9 指挥词速查表

| 你输入 | Agent 行为 |
| :-- | :-- |
| 新会话第一条消息 | 硬门禁：先 `study_memory(get)` + `study_progress(get)`，读取结果返回前不响应 |
| 给文件路径 / "读取 X" / "看一下" | 阶段一·读取：`file-reading` 技能，仅输出读取报告 |
| 上传/粘贴截图 | 图片读取：`read_image`，仅输出读取报告 |
| "讲解 / 讲吧 / 开始讲解" | 阶段二·讲解：一次一个原子点，讲完问"清晰？细化/跳过？" |
| 提问 | 三明治回答（直击 → 底层逻辑 → 反诘） |
| "查一下 / 详细讲讲 / 深入研究" | `web_search`（标 `[联网补充]`）或展开讲解 |
| "接着讲" | 从上次断点续讲 |
| "整理笔记 / 生成笔记 / 归档" | 十步归档：读期望 → 规划确认 → 落块 → 微目录 → 覆盖度 |
| "回退 / 恢复旧版本 / 改坏了" | `note_history(list)` → `note_restore` |
| "标题改成 X / 名字写错了" | `note_rename`（先 dryRun 预演） |
| "记住…" / "忘了…" | `study_memory` set / remove |
| "开启自迭代" / "关闭自迭代" | `study_memory(set _autoPrefs=on/off)` |
| "别问了" | 停止反诘追问 |
| "清空进度" / "清空记忆" | `study_progress(clear)` / `study_memory(clear)` |

### 6.10 更新与回退

- **回退**：`note_history({ref})` 看存档清单 → `note_restore({ref, archiveId})` 恢复。恢复前**当前正文也会先存档**，所以可以反复来回。
- **改名**：`note_rename({ref, title})` 同步四件事——frontmatter 标题 → 文件名（仅当文件名 = 旧标题清洗结果）→ 全库 wikilink 入链 → 断链检测。冲突时**不做任何写入**；`dryRun` 先预演。

---

## 7. 工具参考（18 个工具）

插件注册 18 个工具，**只在「学习伙伴」预设作用域内可见**。工具面按"一个工具一个动词"设计。

| 工具 | 作用 | 必填 | 可选 |
| :-- | :-- | :-- | :-- |
| `note_library` | 库状态自检（vault/期望/规划/计数） | `action=check` | — |
| `note_expect_get` | 读《笔记期望.md》并标记已读（门禁开门） | — | — |
| `note_list` | 逐层导航（子目录 + 笔记 + 是否缺微目录） | — | `path`、`depth` |
| `note_get` | 读一篇完整原文 | `ref` | — |
| `note_search` | 关键词全库检索（多根） | `query` | `domain`、`status`、`kind`、`path`、`limit` |
| `note_overview` | 主题总览 + 覆盖度 | — | `path`、`material` |
| `note_plan` | 文件夹规划提案 / 确认 / 放弃 | `rootPath`、`items` | `action(create\|confirm\|abandon)`、`material`、`notes` |
| `note_write` | 落一个块（门禁三连校验） | `planId`、`title`、`path`、`source`、`content` | `sourceSection`、`order`、`domain`、`status`、`summary`、`tags`、`links`、`dryRun` |
| `note_update` | 更新（append/replace/move/definition） | `ref`、`action` | `changes`、`section`、`newContent`、`summary`、`sourceSection`、`targetPath`、`dryRun` |
| `note_toc` | 生成/刷新微目录 | `dir` | `title`、`dryRun` |
| `note_link` | 建双向 wikilink 关联 | `from`、`to`、`kind` | — |
| `note_unlink` | 移除关联 | `from`、`to` | — |
| `note_rename` | 改标题 + 同步入链 | `ref`、`title` | `dryRun` |
| `note_history` | 看历史存档 | `ref` | `action(list/read)`、`archiveId` |
| `note_restore` | 恢复某份存档 | `ref` | `archiveId`、`dryRun` |
| `note_lint` | 质量体检（4 条规则，无分数） | — | `ref`、`scope`、`limit`、`rule` |
| `study_progress` | 读/写/清进度 | `action` | `material`、`section`、`pendingQuestions[]`、`touchedIds[]` |
| `study_memory` | 读/写/清记忆 | `action` | `key`、`value` |

### 7.1 note_library — 库状态自检

返回：vault 路径与可写性、状态目录、块/存量卡/旧笔记计数、**期望文件状态**（不存在 / 未读 / 已读）、待消费规划。写入被拒时先用它定位原因。

### 7.2 note_expect_get — 读期望（门禁开门）

返回《笔记期望.md》全文并**按文件签名标记已读**。文件不存在时报错并给出创建指引（复制 `presets/study/assets/笔记期望.md` 到 vault 根）。

### 7.3 note_list — 逐层导航

```
## 计算机通识/计算方法/第2章 线性方程组数值解法
- 📁 直接法/（块 2）  ⚠ 缺微目录
  - 高斯消元法 · 块（《计算方法》第2章 线性方程组数值解法 / 2.1节） —— 初等行变换化上三角后回代
```

- 目录计数与"缺微目录"**按子树累加**（父级目录通常只放章节标题，块在下几层）。
- vault 根的《笔记期望.md》不是笔记，不会列出来。

### 7.4 note_get — 读全文

`ref` 支持 ID、标题、根限定路径（`vault/…`、`工作目录/…`）、相对路径、文件名。

### 7.5 note_search — 关键词全库检索

命中行：`### 标题 [ID]` → `类型`（块/存量卡/旧笔记）→ `路径` → `领域/状态/来源/来源章节` → `简介` → `片段`。
`kind` 三态过滤；`path` 限定目录；`limit` 默认 5（上限 50）。无命中会**强制重扫一次**再给换词提示。

### 7.6 note_overview — 主题总览与覆盖度

```
《计算方法》第2章 线性方程组数值解法——2 篇（节：2.1、2.2）
  - 高斯消元法（…/直接法/高斯消元法.md）
  - 列主元消元（…/直接法/列主元消元.md）
- 《计算方法》：已记录第 2 章

### 未归类 1 篇（缺 来源章节 或写法无法解析）
```

- 按 `来源章节` 聚合；节号按**数值**排序（`2.10` 在 `2.2` 之后）。
- **不虚构章节**：完整性只依据笔记里真实出现的章节号；缺口只给"未归类"与"节号跳号"提示。

### 7.7 note_plan — 文件夹规划

- `items[]` 是待落块清单（`title` + `path`，同一规划内标题唯一）。
- `rootPath` 是规划根；之后 `note_write` 的 `path` 必须落在它之下。
- **提案只在对话里，不落盘**；凭据存 `.study/plans/<planId>.json`。
- 用户改结构 → 重新提案一次即可（拿到新的 planId，旧凭据作废）。
- 你拍板后必须**再调一次** `action=confirm`（此时 `rootPath` 传 **planId**）才能写入；未确认的规划会被 `note_write` 拒绝。确认后有效期**从确认时刻起算**（默认 24 小时），搁置太久（超过 24 小时）的提案要先重新提案。
- `action=abandon`（同样把 `rootPath` 传要放弃的 planId）放弃规划。

### 7.8 note_write — 落块（门禁）

三连校验：期望已读且未变 → 规划已确认未过期 → 路径在规划根内、标题在清单内且未消费。
返回 `已写入：rel` + `ID：…` + 规划归属 + 缺微目录提醒 + 整篇内容。`dryRun` 只回显不落盘。
目标已存在时报错（避免覆盖）；改写请用 `note_update`。

### 7.9 note_toc — 生成微目录

- 只重写 `<!-- note_toc:begin -->` 与 `<!-- note_toc:end -->` 之间的生成段；**你手写的导读段原样保留**（标题会按目录名归一）。
- 排序：`顺序` 键 → 标题字典序；条目带来源章节与一句话简介。
- 增删改名笔记后重跑一次即可保持一致；`dryRun` 先看将写入什么。

### 7.10 note_link / note_unlink — 关联

`kind`：`prev`（前置）/ `next`（后续）/ `sibling`（同主题兄弟）。两侧都写（`prev`↔`next` 互为反向，`sibling` 同向）。
落盘为 `- 前置：[[目标]]`。重复关联不重复添加；旧笔记默认只写笔记侧；**先校验两侧再写，不留单向入链**。

### 7.11 note_rename — 改名

同步 frontmatter 标题 → 文件名（仅当文件名 = 旧标题清洗结果）→ 全库 wikilink → 断链检测。
冲突时不做任何写入；只写 vault 内文件；旧笔记拒绝。

### 7.12 note_history / note_restore — 存档与回退

- `note_history({ref})`：列出存档（时间/原因/原路径）；`action=read` + `archiveId` 看全文。
- `note_restore({ref})`：恢复（缺省最新那份）；恢复前当前版本也会先存档。
- 存档位置：`.study/archive/<ID>/<时间戳>.md`（毫秒级时间戳，防撞名）。

### 7.13 note_lint — 质量体检（4 条规则，无分数）

| 规则 | 级别 | 判据 |
| :-- | :-- | :-- |
| `session-residue` 会话残留 | warn（可配 off/error） | 本机路径 / 源码行号 / 第二人称 / 会话时间词 / 阶段代号 / 会话口吻 |
| `code-language` 代码块语言 | warn | 存在未标语言的代码块（报块序号） |
| `external-resource` 外部资源 | info | `<iframe>` / `<script>` / `<img src="http…">` |
| `expect-rule` 期望检查项 | 按期望文件 | 《笔记期望.md》里 `- [检查] 禁止/必须 xxx` 命中或缺失 |

- **废弃 100 分制**：模板类规则（必填小节/主干线/重入点/验证实验/…）随三型模板一起删除；报告给问题清单与严重级。
- 白名单（实证校准）：`L0/L1/L2` 球谐带、`LOD`、`GAMES101 L15`/`第 15 讲`、代码块与 `<details>` 内不扫。
- 未执行的规则单列 `⊘ 未执行（不计入通过）`。

### 7.14 study_progress / study_memory

见 [6.8](#68-进度与记忆附指挥词速查)。补充：`study_progress(set)` 无字段时不写盘；队列上限 50 条 × 200 字；`study_memory` 键名拒绝 `__proto__`/`prototype`/`constructor`。

### 7.15 模型在同一会话中还能用什么

预设还挂载：文件读写/检索（`read`/`glob`/`grep`/`fs-search`，**仅限工作区**；vault 在沙箱外只能走 `note_*` 工具）、`pwsh`（演示验证用，遵守 100 行红线）、`skill`、`web_search`（仅你要求时）、`ask_user_question`、`todo_write`。
**不挂载**：计划模式、子代理、工作流、目标工具、后台任务控制。

---

## 8. 笔记规范

> 完整规范与细则见 `presets/study/skills/note-format/SKILL.md`；本节给使用者视角的要点。

### 8.1 一个块 = 一个可独立阅读的知识单元

- 判据：**单独拿出来读，读者不需要先看别的块才懂**。
- **拒绝伪拆分**：别把连贯推导切碎；也别让一个块塞进三个不相关主题。
- 篇幅由信息完备性决定：**尽细尽全，不设上下限**。简短不是美德——"简陋"正是本轮重构要消灭的问题。

### 8.2 写法由《笔记期望.md》决定

结构、详略、文风、公式与图表偏好、互引习惯、**领域侧重**，全部来自你的期望文件。
**没有模板、没有必填小节、没有字数硬限**——想怎么写就怎么写；改期望立即生效（Agent 会发现签名变了并重读）。

### 8.3 frontmatter 契约

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

- 只认这几个键；`简介` 无长度限制（可从正文首个引用块自动提取），`定义` 作为旧别名仍可读；`模板` 键读取时忽略。
- `来源章节` 语法：`《资料名》第N章 章标题 / N.N节`（无节号也合法）。全角数字、`第 2 章` 的空格、全角斜杠都会被**无损归一**；识别不出时原文保留，进总览的"未归类"。

### 8.4 目录层级与微目录

- `资料 / 章 / 节 / 块`（课程笔记四层）；项目类笔记可少一层。
- **章可以是目录，也可以是 `第N章 章标题.md` 文件**——按你 vault 的既成习惯。
- 每个主题目录都应有 `微目录.md`：`note_toc` 生成导航段，你手写的导读段保留。
- 文件名**不加序号前缀**：顺序由 `顺序` 键与微目录承担。

### 8.5 关联与互引

`note_link` 落盘为 Obsidian wikilink：`- 前置：[[目标]]`。引用同资料其他章节写"详见第N章 N.N节"。

### 8.6 更新后的形态（不留历史块）

- `append`：内容追加进正文（可指定小节），**不产生"版本更新"小节**。
- `replace`：正文只留最新版，旧正文进 `.study/archive/<ID>/<时间戳>.md`。
- 想回退：`note_history` + `note_restore`；恢复前当前版本也会先存档。
- **三者都不丢旧内容**——这是活笔记的底线（只是旧内容不在正文里）。

---

## 9. 在 Obsidian 中的配合

- **直接编辑**：笔记就是 `.md`，打开、编辑、打标签、移动都行；索引按签名变化自动重扫，未命中还会强制重扫一次。
- **wikilink 全通**：关联与微目录都用 `[[文件名]]`，Obsidian 内链、反向链接、图谱视图正常工作。
- **git 管理**：vault 可整体 git 管理；插件写入用「临时文件 + rename」原子写，不会写坏一半。
- **不要做的事**：
  - 不要手改 `ID`、`标题`、`来源章节` 的**字段名**（解析只认这几个键）。
  - 不要指望 `note_id` 预生成的 ID 会被 `note_write` 采用。
  - 不要手动搬文件——用 `note_rename` / `note_update(move)`，否则会留下断链。
  - 移动/重命名不影响检索（按内容/ID 检索）；但新笔记落盘位置由规划决定，vault 目录重组后要同步更新 `domainFolders` 快捷方式。
- **旧笔记原地升级**：想让某篇旧笔记变成块，直接说"把这篇改成笔记"——Agent 走 `note_update(replace)` 原地重写，旧版本进存档。

---

## 10. 检索原理与技巧

### 10.1 分词

中文：**双字组**（「投影矩阵」→ 投影/影矩/矩阵），查询侧对 ≤4 字短中文串额外展开单字提升召回；英文/数字按单词切分（长度 ≥2）；大小写不敏感。

### 10.2 加权打分

| 字段 | 权重 |
| :-- | --: |
| 标题 | 4 |
| 简介 | 3 |
| 领域标签 | 2 |
| 正文 | 1 |

同分按 块 → 存量卡 → 旧笔记 排序，再按路径字典序。召回由插件做，语义判断由模型完成——**检索词用核心术语/概念名，不要整句**。

### 10.3 过滤与限制

`domain`（frontmatter 领域或旧笔记顶层目录推断）、`status`、`kind`（block/legacy/note）、`path`（限定目录）、`limit`（默认 5，上限 50）。

### 10.4 引用寻址顺序

`note_get`/`note_update`/`note_link` 的 `ref` 解析：**ID 精确 → 标题精确 → 路径/文件名候选唯一**。

### 10.5 歧义处理

多根下同名文件报歧义，用根限定路径（`vault/…`、`工作目录/…`、`<searchRoot标签>/…`）。

### 10.6 实用检索词示例

| 目的 | 说法 |
| :-- | :-- |
| 找概念 | "我笔记里有没有讲过 高斯消元？" |
| 找旧笔记 | "在旧笔记里搜 分页 的内存管理" |
| 按领域 | "检索 图形学 的 光照 笔记" |
| 看某个主题记全了没 | "看一下 计算方法 第2章 的覆盖情况" |

---

## 11. 故障排查手册

### 11.1 现象与原因速查

| 现象 | 可能原因 | 处理 |
| :-- | :-- | :-- |
| 会话能建，但没有任何 `note_*` 工具 | ① 预设行不在（bundle 没装 / 没被 profile 选中 / patch 路径写错）② 插件代码是旧的 ③ `vaultRoot` 缺失导致整行挂载失败 | 先 `plugin_manager list_plugins` 看 `include:preset-study`：不在 → 见 §3.3/§3.4；在但 `failed` → 读它的 diagnostic（多半是 `vaultRoot`，见 §3.5）；再核对 [3.7](#37-升级插件) 与 `pnpm run verify:deploy -- -Profile web` |
| **预设整行从名单里消失（不报错）** | DSH 0.1.7 前用目录式预设装的（`%DSH_HOME%\.agent-presets\study\`）——该形态**平台已删除**，目录再没有读者 | 按 §3.3 装包并确认 `dsh.profile.bundles` 含本包；然后删掉 legacy 目录（§3.4） |
| **工具在，但模型一直调 `card_*` / 归档报工具不存在** | 组合是**卡片时代**的（v1.0 已把 12 个 `card_*` 换成 18 个 `note_*`）；旧部署常见于已装包未更新 | 重新装包（§3.7）让 `presets/study.patch.yml` 跟上，再跑 `pnpm run verify:deploy -- -Profile web` |
| **本轮运行失败 `format v4 message requires a producer-owned source kind`**（新会话第一条消息就中，界面只剩这一行） | 跑的是 **v1.1.0 或更早**的插件产物：开场门禁的注入消息用了退场的 `{kind:'plugin'}` 包装，被 DSH 0.1.7 的 **v4 会话格式写盘准入**拒绝（来源必须是生产者自有的非空 kind） | 升到 **≥ v1.1.1**（§3.7 刷新安装副本）；`pnpm run verify:contract` 的来源断言会直接点名。**注意**：这一条不是 vault/配置问题，改配置无效 |
| 挂载报 `agent-preset-invalid` | `vaultRoot` 四层来源都没有 / 为空 / 为文件系统根，或 `searchRoots` 目录不存在 | 看挂载日志的 `vaultRoot ← 来源` 行；按 §3.5 给出绝对路径 |
| 切换预设报 `invalid config: $.prefix missing required value` | DSH 0.1.5 起 persona 的 `text` 改名必填 `prefix` | 把 persona 行的 `text:` 改成 `prefix:`；挂载失败不留缓存，重选一次即生效 |
| 报「笔记期望文件不存在」 | vault 根没有《笔记期望.md》 | 复制 `presets/study/assets/笔记期望.md` 到 vault 根（**有意不自动创建**） |
| 报「未读取笔记期望」 | 本次会话还没 `note_expect_get` | 先说"读一下笔记期望"或直接归档（Agent 会自动读） |
| 报「笔记期望已更新」 | 你改了期望文件 | 让 Agent 重读一次（`note_expect_get`） |
| 报「没有已确认的文件夹规划」 | 归档时跳过了规划 | 让 Agent 先出规划提案 |
| 报「规划尚未确认」 | 提案出了但没拍板/没确认 | 你拍板后让 Agent 调 `note_plan(action=confirm)`（或直接在对话里说"可以/就按这个"） |
| 报「规划已过期」 | 超过 `planTtlHours`（默认 24h）未确认，或确认后搁置超期 | 重新提案；**确认后有效期重新起算** |
| 报「不在本次规划范围」 | 写入路径不在规划根下 | 重新规划把该目录纳入，或改写到规划内路径 |
| 报「该块已在本规划中写入过」 | 同一规划同一标题写了两次 | 重新规划，或改用 `note_update` |
| 报「目标已存在」 | 目标文件已在（可能是手动建的） | 用 `note_update` 改写，或换标题 |
| `note_search` 搜不到刚写/刚改的笔记 | 索引 TTL（默认 2s） | 未命中会自动强制重扫一次，通常已即时可见；仍不中可设 `indexTtlMs: 0` |
| `note_search` 搜不到旧笔记 | 旧笔记不在检索范围 | 检查 `includeSessionCwd` / `searchRoots` |
| 返回出现「⚠ 跳过 N 项未完整处理」 | 文件被锁/断链符号链接/目录深度超限/扫描文件数达上限 | 按括号原因处理；大库调高 `maxWalkFiles` |
| 报「找不到笔记」 | ref 不唯一/不匹配/跨根歧义 | 用 ID 或根限定路径 |
| 报「笔记校验失败」 | 必填缺项/status 非法/字段含换行 | 按报错补字段；status 只能 `草稿/已确认/需更新` |
| 报「……位于只读检索根」 | 想写 `searchRoots`/工作目录里的文件 | 这些根默认只读；笔记一律写 vault 内，或开 `linkIntoNotes` |
| 报「lint.rulesOff 含未识别的规则 id」 | `rulesOff` 里写了不存在/已删除的 id（挂载即失败） | 按报错列出的可用 id 修正 |
| 报「目标文件名已存在……未做任何写入」 | 改名后撞名 | 换标题；该报错保证**什么都没改** |
| 报「改名失败并已回滚」 | 写入被占用/权限不足 | 检查占用后重试；已写文件已恢复原状 |
| `note_write` 提示「已存在同名笔记」 | 同一概念重复建块 | 改用 `note_update`；该提示不触发全库扫描，新会话首次建块可能不提示 |
| 报「进度文件损坏/记忆文件损坏」 | `.study/*.json` 手改坏 | 报错含文件名与原因；手动修复或删除该文件（回到空状态） |
| `note_lint` 报会话残留但看着没问题 | 白名单外的 L 编号等 | 用 `rule:'session-residue'` 单看命中行；必要时 `lint.rulesOff` 关掉 |
| `.study/session.json` 被我删了 | 门禁状态丢失 | **无害**：视为"未读/无规划"，Agent 会要求重做一步；笔记不受影响 |
| 读取 PDF/PPTX 失败 | 缺 PyMuPDF / python-pptx | `pip install pymupdf`（或 `python-pptx`）；仍失败走渲染 PNG 兜底 |

### 11.2 部署四要素自查

1. **插件产物**：`<profileDir>/node_modules/dsh-study-buddy/lib/index.js` 存在且为最新构建。
2. **交付形态**：已装包的 `package.json` 声明 `dsh.bundle.patch` → `presets/study.patch.yml` 存在；
   patch 里 `study` 行**不含** `vaultRoot`。
3. **bundle 选中**：profile 的 `dsh.profile.bundles` 含 `dsh-study-buddy`（少了它预设不出现且不报错）。
4. **legacy 清干净**：`%DSH_HOME%\.agent-presets\study\` 已删除（旧形态没有任何读者）。

**一条命令代替人工核对四要素**（只读，不写任何文件）：

```powershell
pnpm run verify:deploy -- -Profile web      # 产物哈希 / 预设 patch 与 bundle 选中 / legacy 目录 / 技能 / 《笔记期望.md》
```

**升级 DSH 本体的标准动作**：先跑下面两条，10 秒区分「插件坏了」「平台契约变了」「部署副本落后了」三种情况。

```powershell
pnpm run verify:contract                    # 插件 ↔ 本机 DSH 的平台契约（没装 DSH 时自动跳过探针）
pnpm run verify:contract:self-test          # 负向对照：断言被改坏必须报错
```

> 为什么需要这两条：平台与插件之间的契约变更**不会以编译错误的形式暴露**——源码零
> `@deepseek-ai/*` 运行时导入，`pnpm run check` 对它无感。2026-09-15 的 DSH 更新把 Typert
> strict codec 的 `schema` 换成惰性 `create()`，另一个插件整行未激活而 `check` 全绿；
> 2026-09-24（0.1.7-rc.1）删除目录式预设，症状是**预设与工具整体静默消失**、探针仍全绿。
> 两条命令的判读口径见 [`tools/README.md`](../tools/README.md)。

### 11.3 fail-loud 说明

插件对配置错误、注册失败、JSON 损坏都**直接抛错**，不静默降级——看到报错按提示修复即可，它比"静默缺工具"好得多。

---

## 12. 性能与成本

**每次请求的固定开销**（persona + 工具 schema）：

| 模式 | 固定开销 | 模型可见工具 |
| :-- | --: | --: |
| 标准模式 | ~21.3 KB | ~26 个 |
| 学习伙伴 | **14.7 KB** | 18 个（插件）+ 文件/搜索/问询等 |

> 测量方法：`buildToolDefs({})` 的 name + description + parameters JSON 总字节（实测 14704 字节 / 18 工具；v0.9 基线 ~15.0 KB / 21 工具）。

**日常成本**（V4-Flash、约 60 轮/天、2 小时学习；[2026-08-17 峰谷定价](http://www.nbd.com.cn/articles/2026-08-17/4543868.html)）：

| 计费项 | 高峰（9-12、14-18 点） | 低谷（晚上/清晨） |
| :-- | --: | --: |
| 输入·缓存命中 | ¥0.10/天 | ¥0.05/天 |
| 输入·未命中 | ¥0.54/天 | ¥0.27/天 |
| 输出（含推理） | ¥0.27/天 | ¥0.14/天 |
| **合计** | **≈ ¥0.9/天** | **≈ ¥0.45/天** |

月开销约 ¥14–27（Flash）；换 V4 Pro 约 ×3。精简省的主要是延迟（每轮少处理 ~1.1k tokens），成本大头始终是输出与新鲜输入。

**索引与内存**：

- 索引**不常驻正文**，只驻留元数据 + 倒排 token；`note_search` 只对命中的前 N 篇现读正文算片段，目录导航（`note_list`）只读 frontmatter 头。
- 会话早期自动压缩历史（阈值 30%、保留 15%、上限 4096 tokens），配合 `study_progress`，「接着讲」不依赖历史。

---

## 13. 已知限制与路线图

**当前限制**

- 检索为**关键词召回**（CJK 双字组 + 英文单词），无语义向量；近义改写可能漏检。
- 每个 `apply` 实例一个索引缓存（不跨挂载共享）；TTL 默认 2s，未命中强制重扫一次。
- `note_lint` 只覆盖 4 条可判定规则；"段落是否过长""因果是否连贯"这类人工约束没有自动校验。
- **覆盖度依赖 `来源章节` 的书写规范**：解析不出的条目进"未归类"，不会替你猜。
- 微目录的生成段由工具重写；如果你在生成段里手写内容，重跑会覆盖（手写请放在 `note_toc:begin` 之前）。
- **内容会出境**：vault 正文、路径、进度与记忆都会随工具结果进入会话日志并发给模型服务商。
- 旧二进制 Office 格式（.ppt/.doc/.xls）不直接读，需转存。
- 未挂载会话历史检索工具；跨会话靠 `study_progress` / `study_memory`。

**路线图**

- 复习测验子模式（基于笔记库抽卡出题）
- 语义检索（嵌入向量）替代纯关键词召回
- 笔记浏览面板（客户端 Slot UI）
- `/整理笔记`、`/接着讲` 斜杠命令
- 多 vault 支持
- 覆盖度的"计划块 vs 已落块"对照（需要规划留痕，当前提案不落盘）

---

## 14. 隐私与数据流向

**vault 内容会出境。** 这个插件把 vault 里的内容读出来交给模型，这是它的工作方式，需要明确写在这里：

- `note_search` / `note_get` / `note_list` / `note_overview` 的返回文本（标题、简介、正文片段、**整篇原文**）与绝对/相对路径，都会写入 DSH 会话日志，并作为请求内容发送给模型服务商。
- `.study/progress.json`（进度、未答追问）、`.study/memory.json`（跨会话记忆）与 `session.json`（门禁状态）在开场或写入前被读取，同样进入上下文。
- 笔记正文里的 HTML 外链（`<img src="http…">`、`<iframe>`）会在你于 Obsidian 打开笔记时由**本机主动外联**；`note_lint` 的 `external-resource` 规则会给出 info 级提示。
- 插件本身**不联网**：全仓无 `child_process`、无 HTTP 客户端、无 `eval`；所有 IO 只有 `node:fs` 与 `.study/*.json`。
- 记忆与进度中的文本是**用户数据**：persona 与 `memory-auto` 技能明确要求只能作为事实引用，不得当作指令执行；`study_memory(get)` 对以"忽略/指令/你现在是"开头的记忆给出软提示。

**结论**：不要把不适合交给模型服务商的内容放进同一个 vault，或为该 vault 单独配置部署。

---

## 15. 开发与测试

```bash
pnpm install
pnpm run check              # typecheck + vitest + esbuild 构建
pnpm run verify:contract    # 插件 ↔ 本机 DSH 的平台契约（只读；没装 DSH 时自动跳过探针）
pnpm run verify:deploy -- -Profile web   # 部署三要素（只读；见 §11.2）
```

- 源码 `src/`：**零运行时依赖**（仅 Node 内置模块）；模块清单见 [技术文档](技术文档.md) §2。
- 构建：`node build.mjs`（esbuild 打包 → `tsc` 出 `lib/types/*.d.ts`；**构建前会清空 `lib/types`**，避免删掉的模块留下可 import 的声明）。
- 测试 `tests/`：契约往返、门禁（含端到端零改动）、规划与存档、覆盖度、目录索引与列举、检索多根、排序口径与宿主 locale 无关、atomic 写与路径越界、文档/配置/技能守卫；逐文件布局与项数见 [技术文档](技术文档.md) §8。
- 契约与部署校验：`tools/` 两条只读脚本，判读口径见 [tools/README.md](../tools/README.md)；升级后按 [check/升级后验收清单.md](check/升级后验收清单.md) 走一遍。
- CI：push/PR 自动跑 `pnpm run check`，并在**非中文 locale**（`LC_ALL=en_US.UTF-8`）下复跑一遍测试——文本排序等口径不得依赖宿主环境。

---

## 16. 附录

### A. 全功能验证脚本

见 `docs/check/prompt-verify-all-features.md`（复制进新会话即可跑）。

### B. 目录结构

```
dsh-study-buddy/
├── src/                 # 插件源码（零运行时依赖；模块清单见技术文档 §2）
├── tests/               # 单元与端到端测试（布局见技术文档 §8）
├── presets/
│   ├── study.patch.yml  # ★ 声明式 preset：persona + 工具行 + study 插件行（DSH 0.1.7 起的唯一形态）
│   └── study/
│       ├── assets/笔记期望.md # 默认期望模板（复制到 vault 根后自定义）
│       └── skills/      # study-loop / note-format / file-reading / incremental-update / domain-adaptation / memory-auto
├── docs/                # 现行文档 + refactor/（本轮过程）+ check/（验证）+ archive/（历史）
├── tools/               # verify-contract.mjs / verify-deploy.ps1（两条只读校验，见 tools/README.md）
├── build.mjs            # esbuild + tsc 构建脚本（先清 lib/types）
└── cordis.patch.yml     # 备用宿主挂载层（**默认不生效**：列进 dsh.bundle.patch 才会全局挂载）
```

### C. 文档索引

| 文档 | 内容 |
| :-- | :-- |
| [docs/README](README.md) | **文档地图**：现行/过程/验证/归档 + "改代码要同步哪些文档"对照表 |
| [README](../README.md) | 项目门面：定位 / 快速开始 / 三条硬门禁 / 笔记样例 / 最小配置 / 隐私 / 文档导航 |
| [docs/更新记录](更新记录.md) | 逐版变更（**唯一来源**；README 只留版本行） |
| `docs/refactor/需求分析.md` | 本轮重构的**需求基线**：30 条决策、功能与非功能需求、范围边界 |
| `docs/refactor/架构选型.md` | **怎么做**：模块划分、18 个工具契约、数据契约、门禁机制、扩展点 |
| `docs/refactor/重构计划.md` | **按什么顺序做**：8 个阶段、批次门禁、回归策略、计划偏离记录 |
| `docs/设计文档.md` | 现行设计：块定位、期望驱动、硬门禁、关键决策与取舍 |
| `docs/技术文档.md` | 现行实现：模块 API、工具契约、lint 规则、配置键、错误语义、性能与缓存、测试布局 |
| `docs/经验文档.md` | 开发经验：方法论与本轮踩坑 |
| `docs/archive/审查修复记录.md` | 历史审查台账（v0.9 时期，保留溯源） |
| `presets/study/skills/*/SKILL.md` | 6 个技能的权威细则 |