# dsh-study-buddy 技术文档（v1.0 · 文档式笔记）

> 版本基线：v1.1.1 ｜ 读者：插件维护者、二次开发者、需要精确口径的使用者
> 配套：`docs/README.md`（文档地图与维护约定）、`docs/设计文档.md`（为什么这样设计）、`docs/refactor/架构选型.md`（本轮选型）、
> `docs/refactor/需求分析.md`（需求基线）、`docs/经验文档.md`（方法论与踩坑）、`docs/用户使用指南.md`（操作手册）

---

## 1. 环境与构建

| 项 | 值 |
| :-- | :-- |
| 运行时 | Node.js ≥ 22（`engines.node`） |
| 包管理 | pnpm 11（`pnpm-workspace.yaml` + `pnpm-lock.yaml`） |
| 依赖 | **零运行时依赖**（仅 `node:` 内置模块）；devDeps 只有 esbuild / typescript / vitest / @types/node |
| 构建 | `node build.mjs`：**先清 `lib/types`** → esbuild 打包 `src/index.ts` → `lib/index.js`（ESM, node22）→ `tsc -p tsconfig.json` 产出 `lib/types/*.d.ts` |
| external | `@deepseek-ai/cordis`、`@deepseek-ai/dsh-*`（宿主提供） |
| 交付形态 | 本包是**声明式 bundle**：`package.json` → `dsh.bundle.patch: ./presets/study.patch.yml` 声明「学习伙伴」预设（DSH 0.1.7 起目录式预设已删除，见 §9.2）；根目录 `cordis.patch.yml` 是**默认不生效**的备用宿主行 |
| 校验 | `pnpm run check` = `typecheck` → `test` → `build` |
| 产物自检 | `lib/index.js` 中 `@deepseek-ai` 出现次数必须为 0；冒烟：`node -e "import('./lib/index.js').then(m => console.log(m.name, m.buildToolDefs({}).length))"` → `study-buddy 18` |

> **为什么构建前要清 `lib/types`**：`tsc` 是增量输出，删掉的模块会留下 `.d.ts`，
> 消费方仍能 `import` 到"已经不存在的 API"，而编译期零信号（见 `docs/经验文档.md` 第二轮坑 3）。

---

## 2. 模块地图（23 个）

```
src/
├── index.ts         VaultStore（业务编排）+ apply + re-export
├── host.ts          **宿主适配层**：唯一接触面（HOST_CONTRACTS 契约表 + 特性探测/降级 + 可选 dsh-loader）
├── config.ts        配置来源链（行 config / DSH_STUDY_VAULT / <DSH_HOME>/study-buddy.json）→ VaultLayout
├── tools.ts         18 个工具定义（ToolDef）；ToolExecLike/sessionCwdOf 从 host.ts 转发
├── note.ts          块契约：ID/校验/渲染/append·replace·definition/wikilink 关联
├── notemodel.ts     段落模型（小节切分/渲染/标题匹配/块插入/围栏语言/块抹除）
├── frontmatter.ts   极简 YAML 解析与生成（六键 + 三文档键）
├── dirs.ts          目录模型：路径归一/DirIndex/层级校验/listDir/期望路径
├── search.ts        分词、加权、多根索引（**不常驻正文**）
├── gate.ts          硬门禁：三连校验 + 提案渲染
├── planstore.ts     规划记录状态机（.study/plans/<id>.json）
├── archive.ts       历史存档（.study/archive/）+ archiveThenWrite 不变量
├── store.ts         .study/session.json（期望签名、已读规划）
├── overview.ts      覆盖度聚合与渲染（纯函数）
├── sourceSection.ts `来源章节` 语法与无损归一
├── order.ts         排序口径：compareText（显式 zh-Hans-CN + 数值序，全序）
├── links.ts         关联增删/判重 + 改名/入链重写/断链/文件名计划
├── lint.ts          RULES 注册表（4 条）+ 报告 + 期望检查项解析
├── lintrules.ts     会话残留/代码块语言/外部资源判定 + 共享正则
├── vault.ts         扫描/跳过/路径安全/原子写/落盘解析/readNoteSource
├── state.ts         .study/progress.json
├── memory.ts        .study/memory.json
└── opener.ts        开场门禁（提示段 + 预步提醒）
```

### 2.1 `notemodel.ts` — 段落模型（地基）

```ts
interface DocSection { level: number; title: string; body: string; start: number; end: number }

splitSections(body): { lead: string; sections: DocSection[] }   // matchAll，无共享正则状态
renderSections(lead, sections): string
matchesTitle(heading, title): boolean      // 精确相等 或 规范标题 + 括号/冒号/破折号
findSection(sections, title) / hasSection(sections, title)
insertBlockBefore(body, block, beforeTitle = '关联'): string   // 找不到则追加到末尾
inlineText(value): string                 // 换行折成空格 + 压缩空白（SEC-1 渲染兜底）
makeLineOf(text): (index) => number       // 下标 → 行号（1 基），二分查找（PERF-4）
codeFenceLanguages(body): string[]        // 逐行状态机，返回每个代码块的语言标注（'' = 未标）
blankOutBlocks(body): string              // 代码块与 <details> 内容替换为空行（保留行号）
```

> `codeFenceLanguages` 用 `inFence` 状态机逐行扫描，**不能用正则全局匹配**——闭栅栏会被当成开栅栏（见 `docs/经验文档.md` 坑 1）。
> `inlineText` 是**纵深防御**，不替代校验：`validateBlock`/`validateSummary` 会直接拒绝含换行的字段。
> **迁移期残留**：`layerNumbers` / `countListItems` / `CardSection` 别名仍在文件中（模板类规则已删，
> 这两函数目前只有测试引用）；下次清理可一并删除。

### 2.2 `frontmatter.ts` — 契约解析

```ts
interface CardMeta { id?; title?; domain?; source?; status?; sourceSection?; order?; summary?; template? }
parseFrontmatter(raw): { meta: CardMeta | null; body: string; raw: string }
renderFrontmatter(meta): string           // 键序固定：ID→标题→领域→来源→状态→来源章节→顺序→简介
extractDefinition(body): string | null    // 引用块提取（简介缺省来源）
firstHeading(body): string | null
```

- `简介` 与 `定义` **双读**（同现时 `简介` 优先）；`模板` 读入但**不渲染**（迁移兼容，见 §5.1）。
- 渲染对每个值过 `inlineText`（防换行截断 frontmatter）；校验层另有一道 fail-loud。

### 2.3 `note.ts` — 块契约

```ts
type LinkKind = 'prev' | 'next' | 'sibling'
const LINKS_SECTION = '关联'
const VALID_STATUS = ['草稿', '已确认', '需更新']

generateId(now?) / todayLocal(now?)
validateSummary(summary): ValidateResult        // 只拒换行；**无长度上限**（需求 R7）
validateBlock(input): ValidateResult            // 必填/状态枚举/标签空白/顺序数字/正文非空
renderNote(doc: BlockDoc): string               // frontmatter → 引用块定位 → 正文 → 关联小节
appendToSection(body, section, changes): string // 命中小节追加；未命中新建小节
applyUpdate(raw, id, { action, changes?, section?, summary?, block? }): { text, warnings }
inverseKind(kind): LinkKind                     // prev↔next 互反，sibling 同向
wikilinkTarget(name) / wikilinkOf(fileName)     // 清洗 [[ ]] # | ^
parseLinkLine(line): { kind, target } | null
```

- `applyUpdate` 三动作：`append`（追加，不产生版本块）/ `replace`（重渲染，**旧正文由调用方先存档**）/ `definition`（只替换首个引用块）。
- `renderNote` 的 `简介` 缺省时从正文首个引用块提取（`extractDefinition`）；**提取到就不再另写一遍引用块**——
  只有显式传 `summary` 才在正文前补 `> …`，否则"frontmatter 一遍 + 正文首行一遍"会让同一句话连着出现两次（2026-09-15 真机检查实测 4 篇全中）。

### 2.4 `dirs.ts` — 目录模型

```ts
const TOC_FILE = '微目录.md' / const EXPECT_FILE = '笔记期望.md' / const MAX_NEST_HINT = 6

normRel / dirOfRel / parentDir / dirSegments / depthOf / isTocRel
expectPathFor(vaultRoot) / dirPathFor(vaultRoot, dir) / assertDirPath(dir)   // 越界与非法名 fail-loud
nestHint(dir): string                                  // 超过 6 层给人文案（软约束）
interface DirStat { blocks; legacy; notes; hasToc }
class DirIndex {
  add(rel, kind) / remove(rel, kind)                   // O(1) 增删（只记目录自身）
  statOf(dir) / countAt(dir)                           // countAt = 子树累加
  childrenOf(dir) / dirs() / hasTocIn(dir)
}
buildDirIndex(files, kinds): DirIndex
listDir(vaultRoot, dir, { headerBytes = 4096 }): Promise<DirListing>   // 只读头，不读正文
compareOrder(a, b)                                     // 顺序键 → 标题字典序
readNoteHeader(absPath, headerBytes) / parseHeaderFields(text)
resolveNoteDir(layout, { plannedDir?, domain? })        // 规划 > domainFolders > fallbackDir
vaultRelOf(vaultRoot, absPath)
```

- `listDir` 跳过 `.` 开头条目与微目录自身；`readNoteHeader` 在**头读失败（frontmatter 超长）时回退读全文一次**（架构选型 C4）。
- `DirIndex` 的计数与"有无微目录"都必须按**子树**判断（`countAt` / `hasTocIn`）——父级目录通常只放章节子目录。

### 2.5 `search.ts` — 索引与召回

```ts
type NoteKind = 'block' | 'legacy' | 'note'
indexNote(file, raw): IndexedCard            // **不含正文**，只留元数据 + 四路 token 计数
kindOfNote(meta): NoteKind                   // 有 ID 且有来源章节 = block
snippetOf(body, queryTokens): string         // 调用方现读正文后调用
class SearchIndex {
  rebuild(cards, multiRoot) / all() / size / roots()
  byId(id) / byTitle(title) / candidatesForRef(ref) / underDir(dir)
  search(query, opts): SearchHit[]           // opts: domain/status/kind/dirPath/limit
  static queryTokens(query): string[]
}
```

- **字段权重**：标题 4 / 简介 3 / 领域 2 / 正文 1；单字 CJK token ×0.2。
- `kind` 排序：`block` → `legacy` → `note`，再按 `fullRel` 字典序。
- `SearchHit.snippet` 初值为 `null`，由调用方对**命中前 N 篇**现读正文填充（A4 的代价面）。
- `indexNote` 仍对整个正文做 token 化（读盘量不变），只是**不留原文**。

### 2.6 `gate.ts` — 硬门禁

```ts
interface GateInput { vaultRoot; stateDir; session; expectSignature; requireExpect?; targetRel?; requirePlan?; planTtlHours? }
checkExpect(input): GateResult        // 文件缺失 / 未读 / 签名变化 三态
checkPlan(input): Promise<GateResult> // 无规划 / 记录不存在 / 未确认 / 已过期
checkPathInPlan(record, rel): GateResult
checkWrite(input): Promise<GateResult> // 按序短路：期望 → 规划 → 路径
formatPlanProposal(record, { reusedDirs }): string   // 对话内提案（不落盘）
```

每条失败都返回 `{ ok: false, reason: '问题——修复步骤' }`。`note_write` 直接把 `reason` 拼进抛错文本。

### 2.7 `planstore.ts` — 规划凭据

```ts
generatePlanId(now?) / planFileFor(vaultRoot, planId, stateDir)   // id 格式 [0-9]{12}_[0-9a-f]{6}（各字段必须补零，见下）
readPlan(file): Promise<PlanRecord | null>      // 宽容：损坏返回 null（不抛错阻断）
writePlan(file, record)
buildPlanRecord(input, planId?): PlanRecord     // 校验：路径在根下、标题唯一、items 非空；**confirmed 恒为 false**
isPlanExpired(record, ttlHours, now?)
consumePlanItem(file, title, rel, { ttlHours, now }): Promise<ConsumeResult>   // 消费记账（写盘失败即失败）
abandonPlan(file) / pathInPlan(record, rel)
```

- `confirmed` 只由 `note_plan(action=confirm)` 置位：确认时写 `confirmed: true` + `confirmedAt`，并把 `createdAt` **重置为确认时刻**
  （有效期从凭据生效时刻起算；搁置超期的提案要先重新提案，不把过期确认做成"改了时间就能过"）。
- **`generatePlanId` 的每个两位字段都必须补零**：`planFileFor` 的校验式要求恰好 12 位时间戳，漏一处（如小时位）就会让
  00:00~09:59 生成的 id 只有 11 位，同一个 id 传给 confirm / note_write 被自己的校验拒绝——"凭据刚发出去就读不回来"。

### 2.8 `archive.ts` — 历史存档

```ts
archiveStamp(now?) / archiveDirFor(vaultRoot, fromId, stateDir)   // 时间戳 YYYYMMDDHHmmssSSS
renderArchive(meta, original) / parseArchive(raw, id, file) / archiveBody(raw)
writeArchive(vaultRoot, { fromId, oldRel, reason, title?, content, now? }): Promise<ArchiveEntry>
listArchives(vaultRoot, fromId, stateDir) / readArchive(vaultRoot, fromId, archiveId, stateDir)
archiveThenWrite(input): Promise<ArchiveEntry>   // **先存档、后写正文**的唯一入口
```

### 2.9 `store.ts` — 会话门禁状态

```ts
interface SessionState { expect?: { signature; rel; readAt? }; activePlanId?; updatedAt? }
sessionFileFor(vaultRoot, stateDir) / signatureOf(file)   // mtime|ctime|size
readSession(file) / writeSession(file, state)             // 读取**永不抛错**（损坏回空态）
markExpectRead(file, { signature, rel }) / clearExpectMark(file)
```

### 2.10 `overview.ts` — 覆盖度

```ts
summarizeOverview(notes, { material? }): OverviewResult
formatOverview(result, { scope? }): string
```

返回 `{ chapters, unclassified, materials, counted }`；节号按**数值**排序，跳号只在同一父节下相邻间隔 >1 时提示。

### 2.11 `sourceSection.ts` — 来源章节

```ts
normalizeSourceSection(input): { material; chapter; chapterTitle; section; raw }
normalizeSourceSectionText(input): string
isSourceRefComplete(ref): boolean
```

### 2.12 `links.ts` — 关联与改名

```ts
addLink(raw, kind, label) / removeLink(raw, label) / listLinks(body) / parseLinkTarget(line) / linkTargetOf(label)
replaceNoteTitle(raw, newTitle) / noteTitleOf(raw)
rewriteLinkLines(body, { oldTitle, newTitle, targetId? }): LinkRewrite
rewriteWikilinks(body, oldBase, newBase): LinkRewrite
detectBrokenLinks(body, { oldTitle, oldId?, newTitle?, checkFormat? }): BrokenLinkHit[]
planRename({ fileName, oldTitle, newTitle }): { renameFile, oldBase, newBase, reason }
formatRenameReport(input): string
```

### 2.13 `lint.ts` / `lintrules.ts` — 质量体检

```ts
interface Rule { id; title; severity: 'error'|'warn'|'info'; run(ctx: RuleCtx): LintFinding[] }
export const RULES: Rule[]        // 唯一权威：加规则 = 加一个数组元素
lintNote({ title?, summary?, body, kind? }, ctx?): LintReport
interface LintReport { title; kind: 'block'|'legacy'|'note'; chars; findings; passed; notRun }
parseExpectRules(text): ExpectRule[]        // `- [检查] 禁止/必须 …`（支持 理由：/严重：）
formatReport(report) / summarizeLint(reports) / formatBatch(batch, limit)
ruleIds() / ruleTitle(id) / ruleCatalog() / ruleTable()
```

**规则与级别**（`RULES` 是唯一权威）：

| rule id | 中文 | 级别 | 判据 |
| :-- | :-- | :-- | :-- |
| `session-residue` | 会话残留 | warn（可配 off/error） | 6 类命中（路径/行号/第二人称/时间词/阶段代号/会话口吻），只扫代码块与折叠块之外 |
| `code-language` | 代码块语言 | warn | 有未标语言的代码块（报块序号，不是行号） |
| `external-resource` | 外部资源 | info | `<iframe>`/`<script>`/`<img src="http…">` |
| `expect-rule` | 期望检查项 | 按期望文件 | `- [检查] 禁止/必须 …` 命中或缺失 |

- **无分值**：`score` / `ERROR_SCORE_CAP` / `SCORE_BUCKET` 已随 100 分制删除；`LintBatch` 也**不再有 `average`**——
  "平均问题数"同属分值制残留，报告只给"有问题的文档数 + 问题数分布 + 规则命中 + 问题最多的文档"。
- `passed` **只收录零发现的规则**；判断"某规则跑过没有"必须同时看 `passed` 与 `findings`
  （`tests/tools.spec.ts` 与 `index.ts` 的 `lintOne` 都按此口径——这是 v1.0 修正过的一个静默错答，见经验文档第二轮坑 1）。
- `expect-rule` 在未提供 `expectRules` 时列入 `notRun`（不得当成通过）。
- 共享正则常量（代码与文档同源）：`RESIDUE_PATH_RE` / `RESIDUE_LINE_RE` / `RESIDUE_PERSON_RE` /
  `RESIDUE_TIME_RE` / `RESIDUE_PHASE_RE` / `RESIDUE_SESSION_RE` / `LINE_WHITELIST_RE` / `LECTURE_REF_RE` / `EXTERNAL_RESOURCE_RE`。

### 2.14 `vault.ts` — vault 适配

```ts
const SKIP_DIRS = new Set(['.obsidian','.trash','.study','.git','node_modules'])
const MAX_FILENAME = 80 / MAX_WALK_FILES = 20000 / MAX_WALK_DEPTH = 16 / MAX_INDEX_BYTES = 262144

skipSetFor(extra?) / sanitizeFilename(title) / findSimilarDomainKeys(domain, keys)
withinRoot(root, p) / ensureDir(p) / atomicWrite(file, content) / exists(p)
walk(root, ...) / walkRoots(roots, skip, onSkip, maxFiles) / readNoteSource(path, maxBytes?)
canonicalRootKey(p) / containsRoot(outer, inner) / dedupeRoots / dedupeFiles
resolveSearchRoots(vaultRoot, raw?, writable?) / isFsRoot(p)
cardDirFor(layout, domain) / notePathFor(vaultRoot, dir, title) / uniqueNotePath(dir, title, id)
```

> `cardDirFor` 是**迁移期残留**（`note_write` 已改走规划路径与 `planstore`）；
> 下次清理时确认无引用后删除。
> `uniqueNotePath` 的三档冲突策略：`标题.md` → `标题_末6位ID.md` → `标题_完整ID.md` → 报错。

### 2.15 `order.ts` — 排序口径

```ts
compareText(a, b): number      // 唯一允许出现在 src/ 的文本比较
```

`Intl.Collator('zh-Hans-CN', { numeric: true })`（模块级常量，不每次构造）：中文按拼音、数字按数值（`第2章` 在 `第10章` 之前）；
排序器对"等价但不同"的串返回 0 时回落码位比较，保证**严格全序**（反对称 + 传递）。

- **为什么不用裸 `localeCompare`**：不传 locale 时它按宿主默认 locale 比较——同一份 vault 在不同机器/CI 上顺序不同。
  v1.0.0 就是这么在 GitHub runner（en-US，根排序按部首）上红掉的，而本机 zh-CN（拼音）是绿的。
- **为什么不做"纯 ASCII 走码位"的快路径**：两种比较器混用会破坏传递性（`a < A < B < a` 成环），排序结果不再确定。
- 守卫：`tests/order.spec.ts` 扫描 `src/` 禁止裸 `localeCompare`/`Intl.Collator`，并把 `String.prototype.localeCompare`
  换成 en-US 实现复现 CI 环境，断言聚合与目录顺序不变。

---

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

所有工具 `output.schema.type = 'string'`，返回纯文本（含固定前缀回显行）；
`execute(args, exec)` 中 `exec.agent.session.header.cwd` 用于 `includeSessionCwd` 与只读根。

| 工具 | 必填 | 可选 | 返回要点 |
| :-- | :-- | :-- | :-- |
| `note_library` | `action(check)` | — | vault 可写性 / 期望三态 / 块·存量卡·旧笔记计数 / 待消费规划 |
| `note_expect_get` | — | — | 期望全文 + **按签名标记已读**；缺失时给创建指引 |
| `note_list` | — | `path` / `depth`(1~4, 默认 2) | 子目录（子树计数 + 缺微目录 ⚠）+ 笔记行（`标题 · 类型（来源章节）—— 简介`） |
| `note_get` | `ref` | — | `路径：…` + 完整原文 |
| `note_search` | `query` | `domain` / `status` / `kind` / `path` / `limit`(默认 5, 上限 50) | 命中行（标题[ID]/类型/路径/领域状态来源来源章节/简介/片段）；未命中强制重扫后给换词提示 |
| `note_overview` | — | `path` / `material` | 按 `来源章节` 的章节清单 + 未归类 + 节号跳号提示（不虚构章节） |
| `note_plan` | `rootPath` `items[]` | `action(create\|confirm\|abandon)` / `material` / `notes` | create：提案（规划根/新建复用目录/块清单表）+ `planId`；confirm：置位凭据（`rootPath` 传 planId，有效期从确认时刻起算）；abandon：放弃。**提案只在对话里，不落盘** |
| `note_write` | `planId` `title` `path` `source` `content` | `sourceSection` / `order` / `domain` / `status` / `summary` / `tags` / `links` / `dryRun` | 门禁三连校验 → `已写入：rel` + `ID：…` + 规划归属 + 缺微目录提醒 + 整篇；目标已存在则拒绝 |
| `note_update` | `ref` `action` | `changes` / `section` / `newContent` / `summary` / `sourceSection` / `targetPath` / `dryRun` | `append` 追加（可指定小节）/ `replace` 先存档再写 / `move` 迁目录 / `definition` 只改定位 |
| `note_toc` | `dir` | `title` / `dryRun` | 只重写 `note_toc:begin/end` 之间的生成段；`已生成：rel（收录 N 块）` + 全文 |
| `note_link` | `from` `to` `kind(prev\|next\|sibling)` | — | 两侧 wikilink；重复关联返回"无改动"；只读根先校验后写 |
| `note_unlink` | `from` `to` | — | 两侧移除；小节空了连标题一起删 |
| `note_rename` | `ref` `title` | `dryRun` | frontmatter 标题 + 文件名（条件同步）+ 全库 wikilink + 断链检测；冲突零写入 |
| `note_history` | `ref` | `action(list\|read)` / `archiveId` | 存档清单（时间/原因/原路径）或某份全文 |
| `note_restore` | `ref` | `archiveId` / `dryRun` | 恢复（当前版本先存档，可来回） |
| `note_lint` | — | `ref` / `scope(vault\|all)` / `limit`(默认 20) / `rule` | 问题清单 + 严重级（**无分数、无均分**）；批量给"有问题的文档数/问题数分布/规则命中/问题最多的文档" |
| `study_progress` | `action(get\|set\|clear)` | `material` / `section` / `pendingQuestions[]` / `touchedIds[]` | `位置/追问/卡片`；`set` 无字段不写盘；队列上限 50 条 × 200 字 |
| `study_memory` | `action(get\|set\|append\|remove\|clear)` | `key` / `value` | 单键或整份（`_autoPrefs` 状态行置顶、`lastSummary` 置顶）；保留键拒绝 `__proto__` 等 |

### 3.1 `note_write` 的门禁顺序（实现口径）

```
1) gate.checkExpect   ：.study/session.json 的签名 == 当前《笔记期望.md》签名
2) gate.checkPlan     ：.study/plans/<planId>.json 存在 && confirmed（由 note_plan(action=confirm) 置位）&& 未过 planTtlHours
3) gate.checkPathInPlan：path 在 rootPath 之下 && title ∈ items
4) planstore.consumePlanItem：标题未被消费 → 追加 consumed 并写盘（写盘失败即拒绝）
5) validateBlock → 目标不存在校验 → atomicWrite → invalidate()
```

`dryRun: true` 时在第 4 步之前返回，**不消费凭据**。

---

## 4. 配置参考（`StudyConfig` → `VaultLayout`）

`StudyConfig` 是 `VaultLayout` 的"可省略默认值"视图；类型定义只有 `src/vault.ts` 一处，`src/config.ts` 的 `resolveLayout()` 负责**来源链 + 默认值填充**（`src/index.ts` 只调用它并打印回显）。

**来源链（后者覆盖前者，逐键合并）**：

| 序 | 来源 | 说明 |
| --: | :-- | :-- |
| 1 | 内置默认值 | 下表"默认"列 |
| 2 | `<DSH_HOME>/study-buddy.json` | 键名与下表**完全一致**；不是合法 JSON / 未知键只 `⚠` 告警，不阻断挂载 |
| 3 | 环境变量 `DSH_STUDY_VAULT`（别名 `DSH_VAULT_ROOT`） | **只管 `vaultRoot`** |
| 4 | 预设声明行 `presets/study.patch.yml` 的 `study` 行 `config` | 部署侧覆盖，最高优先级 |

四层都拿不到 `vaultRoot` → **挂载 fail-loud**（错误里列出上面四种给法）。挂载时会打印一行
`[dsh-study-buddy] vaultRoot ← <来源>：<路径>（宿主适配：…）`，排障第一问不必再翻配置文件。

| 键 | 默认 | 说明 |
| :-- | :-- | :-- |
| `vaultRoot` | — | vault 绝对路径；**包内不写**（机器相关），由上面 2/3/4 任一层提供；为空或**文件系统根** → 挂载失败（fail-loud） |
| `expectFile` | `笔记期望.md` | 期望文件名（vault 根下）。**读取路径、门禁签名、回显文案都用它**；含路径分隔符会抛错（越界防御） |
| `planTtlHours` | `24` | 规划凭据有效期；非正数回落默认 |
| `stateDir` | `.study` | 进度/记忆/会话/规划/存档目录（相对 vaultRoot） |
| `fallbackDir` | `未分类` | 未映射领域且规划未给路径时的兜底（实际写入 `未分类/<领域>/`） |
| `domainFolders` | `{}` | 领域键 → 目录的**快捷方式**（v1.0 起落盘目录以规划的 `path` 为主） |
| `skipDirs` | `[]` | 额外跳过扫描的顶层目录名（内置见 §2.14） |
| `includeSessionCwd` | `false` | 把会话工作目录纳入检索（与 vault 相同/嵌套自动去重） |
| `searchRoots` | `[]` | 额外检索根（绝对或相对 vaultRoot）；不存在 → **构造时**抛错；默认只读 |
| `linkIntoNotes` | `false` | 是否允许写无 ID 的旧笔记（同时决定只读根是否可写） |
| `lint.residueLevel` | `warn` | `off` / `warn` / `error`；`off` 时该规则进 `notRun`（不给"✓ 通过"） |
| `lint.rulesOff` | `[]` | 禁用规则 id 列表；**未知 id 在挂载时抛错**并列出可用 id |
| `indexTtlMs` | `2000` | 索引缓存 TTL；`0` = 每次调用都重扫。TTL 命中且未命中/找不到时强制重扫一次 |
| `maxWalkFiles` | `20000` | 每根扫描文件数上限；超限**截断并 `⚠` 上报**（不抛错） |

> **v1.0 已删除的键**：`mocDir`、`templateHints`（写进 preset 不生效；`tests/preset.spec.ts` 断言其不存在）。

---

## 5. 数据与文件格式

### 5.1 笔记 frontmatter

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

- 只认这些键；**渲染键序固定**（git diff 无噪声）。
- `定义` 作为 `简介` 别名可读；`模板` 读入不渲染（迁移兼容）。
- 校验侧对 `title/domain/source/status/简介` **拒绝换行**；`tags` 拒绝含空白。
- `简介` **无长度上限**（v0.9 的 ≤60 字硬拒绝已删除）。

### 5.2 过程状态（`.study/`，删掉不丢笔记）

| 文件 | 结构 | 损坏行为 |
| :-- | :-- | :-- |
| `progress.json` | `{ currentMaterial, currentSection, pendingQuestions[], touchedCardIds[], updatedAt }` | 抛错（含文件名与原因） |
| `memory.json` | `{ notes: Record<string,string>, updatedAt }`；保留键 `lastSummary`、`_autoPrefs`(on/off) | 同上 |
| `session.json` | `{ expect?: { signature, rel, readAt? }, activePlanId?, updatedAt? }` | **读不抛错**（回空态 → 门禁要求重做一步） |
| `plans/<planId>.json` | `{ planId, createdAt, confirmed, confirmedAt?, rootPath, material?, notes?, items[], createdDirs[], consumed[] }` | 读返回 `null`（视为无规划） |
| `archive/<ID>/<时间戳>.md` | 存档头（存档自/原路径/存档时间/原因/标题）+ **原文一字不改** | `listArchives` 跳过读失败项 |

记忆键 ≤64 字符、值 ≤4000 字符；`_autoPrefs` 只接受 `set/remove`；键名拒绝 `__proto__`/`prototype`/`constructor`。

### 5.3 落盘与命名

- 目录：规划给的 `path` → `domainFolders[domain]` → `fallbackDir/<领域>/`。
- 文件名：`sanitizeFilename(标题)`（Windows 非法字符、引号、`[]` 清洗，≤80 字符，设备名加 `_`）；冲突三档后缀。
- 写入：`atomicWrite` = 临时文件 + `rename`（失败清理临时文件）。
- 路径安全：所有落盘路径经 `withinRoot` 校验，越界即抛错；写前 `assertWritable` 复核根可写性。

### 5.4 微目录格式

```markdown
# <目录名>

<用户手写的导读段（保留）>

<!-- note_toc:begin -->
1. [[块标题]]（2.1节） —— 一句话简介
<!-- note_toc:end -->
```

---

## 6. 错误语义（fail-loud）

| 场景 | 行为 |
| :-- | :-- |
| `vaultRoot` 四层来源都没有/为文件系统根 | 挂载抛错 → 预设行带 diagnostic（`agent-preset-invalid`） |
| 预设声明行缺失（bundle 未装 / 未在 profile 选中 / patch 路径写错） | **不报错**：预设整行不出现在名单里；用 `plugin_manager list_bundles` + `list_plugins` 定位（见 §9） |
| `searchRoots` 目录不存在 | **构造 store 时**抛错 |
| `ctx.tools.register` 不可用 / 注册半途失败 | 抛错（先 dispose 已注册工具） |
| `lint.rulesOff` 含未知 id | 挂载抛错并列出可用 id |
| **期望文件不存在** | `note_write` 拒绝 + 创建指引（`复制 presets/study/assets/笔记期望.md`） |
| **期望未读 / 签名变化** | 拒绝 + `请先 note_expect_get` / `请重新读取` |
| **无规划** | 拒绝 + `请先调用 note_plan 输出提案，用户拍板后用 note_plan(action=confirm) 确认` |
| **规划未确认** | 拒绝 + `请让用户拍板后用 note_plan({ action: "confirm", rootPath: "<planId>" }) 确认`（文案里的 planId 就是本次凭据） |
| **规划已过期** | 拒绝 + `请重新调用 note_plan 提案并确认（确认后有效期重新起算）` |
| **路径越界 / 标题不在规划 / 重复消费** | 拒绝 + 回显规划根与允许项；磁盘零改动 |
| **目标已存在** | `note_write` 拒绝（改用 `note_update`） |
| 笔记校验失败（缺字段/非法 status/字段含换行） | 抛错，不落盘 |
| 存档写入失败 | 抛错且**不修改正文**（`archiveThenWrite` 先存档） |
| `move` / `rename` 目标已存在 | **写入前**抛错并提示"未做任何写入" |
| `rename` 落盘中途失败 | 按写前缓存逆序回滚，抛"改名失败并已回滚：…" |
| 写入只读根 | 抛错；`note_link` 在**写入前**校验两侧（不留半写盘） |
| `.study/progress.json` / `memory.json` 损坏 | 抛错含文件名与原因 |
| `session.json` / `plans/*.json` 损坏 | **不抛错**：回空态 / 视为无规划（门禁要求重做一步） |
| 扫描超过安全阀 | 不抛错：截断 + `⚠` 上报（按原因分组） |
| 文件读取失败（锁定/断链符号链接/stat 失败） | 不静默：计入跳过清单并在报告里按原因回显 |
| **`本轮运行失败 format v4 message requires a producer-owned source kind`** | **不是本插件的业务错误**：平台 v4 写盘拒收注入消息的 `source.kind`（必须非空且 ≠ `'plugin'`）。本插件的来源恒定是 `plugin:dsh-study-buddy`（`src/opener.ts` 的 `OPENER_SOURCE_KIND`，契约点 `messageSourceKind`）；见到它 = 跑的是旧产物，处理见 §9 |

---

## 7. 性能与缓存

- 索引缓存键 = `sessionCwd` + 每文件 `root|rel|mtimeMs|ctimeMs|size`；签名不变直接复用。
- **TTL** 默认 2000ms：TTL 内且 cwd 未变时跳过 `walk + stat`；写操作显式失效。
  TTL 命中的索引在**未命中/找不到**的失败路径上强制重扫一次（`{ force: true }`）。
- **单次重建的读盘量**：`walkRoots` + 每文件 `readNoteSource`（全文，256KB 上限）做 token 化。
  **但索引不保存正文**（A4）：内存从"全库正文"降到"倒排表 + 元数据"。
- **snippet**：只对命中前 N 篇现读正文（`SearchIndex.queryTokens` 复用同一分词口径）。
- **目录导航**：`listDir` 只读每个文件前 4KB（`headerBytes`），头读失败回退全文一次。
- **批量体检**：逐篇按需读盘（低频重操作）；每篇只 `splitSections` 一次、`blankOutBlocks` 一次。
- **`titleHints`**：`Map<小写标题, {title, fullRel, id}>` 为写入时的同名提示提供 O(1) 查询，
  索引重建时整体填充、写入后增量维护——**写路径不触发全库扫描**。
- **排序口径**：全部文本排序走 `order.ts` 的 `compareText`（显式 `zh-Hans-CN` + `numeric`），
  结果只由内容决定、与宿主 locale 无关；排序器是模块级常量（不是每次比较都 `new Intl.Collator`）。
- 已知边界：单次重建仍要读全库正文；10 万篇级需要改懒加载 + LRU（未做）。

---

## 8. 测试布局（23 文件 / 293 项）

| 文件 | 项 | 覆盖 |
| :-- | --: | :-- |
| `tests/noteflow.spec.ts` | 20 | **端到端门禁与闭环**：三条门禁各自拒绝且磁盘零改动、期望改动须重读、规划提案 → `confirm` → 落块、未确认/过期凭据的各分支、闭环（期望→规划→落块→微目录→覆盖度）、replace 存档与 restore 往返、wikilink 双向关联、dryRun、落盘正文的定位去重 |
| `tests/gate.spec.ts` | 18 | 规划状态机（未确认/过期/标题不在规划/重复消费/放弃）、`generatePlanId` 补零不变量、三连校验分支、存档顺序不变量（**存档失败时正文零改动**） |
| `tests/overview.spec.ts` | 9 | 聚合与排序（`2.10` 在 `2.2` 后）、不虚构章节、跳号提示、未归类、material 过滤 |
| `tests/order.spec.ts` | 6 | **排序口径**：拼音序、数字按数值、严格全序（反对称 + 传递）、换 en-US locale 后聚合与目录顺序不变（CI 故障回归）、`src/` 无裸 `localeCompare` |
| `tests/note.spec.ts` | 24 | 块校验/渲染/三动作更新/wikilink 关联/来源章节归一 |
| `tests/notemodel.spec.ts` | 10 | 段落切分、往返、标题兼容、块抹除、inlineText、makeLineOf |
| `tests/dirsession.spec.ts` | 19 | 路径模型、DirIndex 增删与子树计数、`listDir` 头读与回退、`session.json` 容错 |
| `tests/links.spec.ts` | 9 | 标题替换、wikilink 重写、断链（含"新标题包含旧标题"反例）、文件名计划 |
| `tests/frontmatter.spec.ts` | 12 | 六键 + 三文档键往返、`定义` 别名、`模板` 只读不渲染、键序固定 |
| `tests/lint.spec.ts` | 14 | 4 条规则 + 白名单反例 + 期望检查项解析 + 批量汇总（**无分值、无均分**） |
| `tests/search.spec.ts` | 14 | 分词加权、多根、kind 三态、**A4 守门（IndexedCard 与命中都不含 body）** |
| `tests/store.spec.ts` | 13 | 多根检索与歧义、fail-loud、跳过项回显、TTL、进度与记忆、自迭代开关 |
| `tests/vault.spec.ts` | 18 | 原子写、路径越界、`isFsRoot`、扫描安全阀（截断）、`readNoteSource` |
| `tests/state.spec.ts` / `memory.spec.ts` / `opener.spec.ts` | 32 | 进度/记忆持久化与容错、开场门禁纯函数（事件读取经 `host.sessionEventsOf`、**v4 来源准入**：kind 非空且 ≠ `plugin`） |
| `tests/tools.spec.ts` | 13 | 18 个工具名字集合与 schema 契约、`card_*` 必须不存在、cwd 透传 |
| `tests/apply.spec.ts` | 15 | fail-loud、工具注册与卸载、开场门禁接线、`rulesOff` 校验、配置键漂移告警（已退场键点名但不抛错）、**来源链**（环境变量顶替行 config、行 config 覆盖环境变量） |
| `tests/config.spec.ts` | 12 | **配置来源链单测**（注入 env/readFile，不碰真实文件系统）：逐键合并与优先级、别名环境变量、损坏/非对象/未知键只告警、文件系统根拒绝、默认值兜底、`DSH_HOME` 口径 |
| `tests/contract.spec.ts` | 9 | **宿主契约**：18 个工具名/字段/`output` 形状、apply 接线（注册→卸载零残留、提示段形状、预步四条分支与两条降级路径）；与 `tools/verify-contract.mjs` 的分工写在 `tools/README.md` |
| `tests/skills.spec.ts` | 15 | 技能 frontmatter、集合恰为 6 个、note-format/domain-adaptation 口径、领域键表 == 声明 patch、规则注册表自洽 |
| `tests/preset.spec.ts` | 8 | **声明式预设卫生**：目录式预设已退场、声明行四字段、行 id/模块名唯一、persona `prefix` 键、config 键与插件 schema 一致且**不含 `vaultRoot`**、技能资产从包内解析、persona 不得提旧工具、默认期望模板可解析 |
| `tests/docs.spec.ts` | 3 | 文档相对链接/锚点可解析；现行文档头部版本基线 == `package.json`（两 manifest 同版本）；**文档里的模块数/测试文件数/项数 == 从 `src/`、`tests/` 现算的值** |

**写测试的三条约定**：① 白名单反例优先于正例；② 断言用带引号的精确子串；③ 改行为时改断言，不改实现迁就断言。

---

## 9. 调试与排障

| 现象 | 排查 |
| :-- | :-- |
| 会话里没有任何 `note_*` 工具 | ① 预设行在不在：`plugin_manager list_plugins` 看 `include:preset-study`（不在 = bundle 没装/没选中，见 §9.2；在但 `failed` = 看它的 diagnostic）② 代码是否是新的：核对 `<profileDir>/node_modules/dsh-study-buddy/lib/index.js` ③ 预设层是否被 `cordis.patch.yml` 里的同名行覆盖 |
| 挂载报 `agent-preset-invalid` | 四层来源都没有 `vaultRoot`、`vaultRoot` 为文件系统根，或 `searchRoots` 目录不存在 |
| 配置改了不生效 | `vaultRoot` 是**挂载期不变量**：改 `<DSH_HOME>/study-buddy.json` 后需重启 DSH（或让预设重新挂载）；声明 patch 的改动走 profile 的 `patchReload: live` 即时生效 |
| 报「笔记期望文件不存在」 | 复制 `presets/study/assets/笔记期望.md` 到 vault 根（**有意不自动创建**：回退会造成两处口径） |
| 写入总是被拒 | 依次核对：`note_expect_get` 读过没 → `note_plan` 确认过没 → 路径在规划根下没 → 该标题消费过没 |
| 搜索不到刚改的笔记 | TTL 默认 2s；**未命中会强制重扫一次**，通常已即时可见 |
| 报告出现 `⚠ 跳过 N 项未完整处理` | 按括号里的原因处理：文件被锁 → 解锁重跑；断链符号链接 → 修/删；深度超限 → `skipDirs`；文件数达上限 → 调高 `maxWalkFiles` |
| `note_get` 报"找不到笔记" | 用 ID 或根限定路径（`vault/…`、`工作目录/…`、`<标签>/…`） |
| `note_lint rule=X` 报"未启用或不适用于此类文档" | 该规则在 `lint.rulesOff` 里，或（对 `expect-rule`）期望文件里没写检查项 |
| `note_lint` 报会话残留但看起来没问题 | `rule:'session-residue'` 单看命中行；必要时 `lint.residueLevel:'off'` 或 `rulesOff:['session-residue']` |
| 改名后 Obsidian 里有断链 | 看 `note_rename` 报告的"断链检测"段；旧笔记侧不自动改写（按文件名寻址） |
| 微目录丢了手写导读 | 手写内容必须在 `<!-- note_toc:begin -->` **之前**；生成段会被重写 |
| `lib/types` 里还有已删模块的 `.d.ts` | 跑一次 `pnpm run build`（构建前会清空该目录） |
| `本轮运行失败 format v4 message requires a producer-owned source kind` | 跑的是 v1.1.0 或更早的产物（开场门禁的来源用了退场的 `{kind:'plugin'}` 包装，被平台 v4 写盘准入拒绝）→ 升级到 ≥ v1.1.1 并刷新安装副本（§9.2）；来源契约见 §6 与 `src/opener.ts` 的 `OPENER_SOURCE_KIND` |

### 9.1 已知实现边界（留给下一轮）

- `notemodel.ts` 的 `layerNumbers` / `countListItems` / `CardSection` 别名、`vault.ts` 的 `cardDirFor` / `mocPathFor` 是迁移期残留，确认无引用后删除。
- `state.ts` 与 `memory.ts` 未合并（判定为不做，见 `docs/refactor/重构计划.md` §九）。
- 索引单次重建仍要读全库正文做 token 化（内存已不常驻正文）；10 万篇级需要懒加载 + LRU。
- `dsh.plugin.json` 是仓库内部清单（**当前 DSH 不读它**）：DSH 0.1.7 判定的清单是 `package.json`
  （`dsh.bundle.patch` 决定交付形态，`peerDependencies` 决定兼容门禁）。保留它只为版本/描述同步的测试与人工核对。

### 9.2 交付形态：声明式预设（DSH 0.1.7 起）

**目录式预设已被平台删除**（提交 `d1e22a7e24` / PR #4569）：`$DSH_HOME/.agent-presets/<id>/`
再没有任何读者（在 `T:\deepseek-harness\packages` 全量 grep `.agent-presets` 零命中），
官方技能 `cordis-composition-reference` 的迁移一节原文是 *"Nothing reads that directory any more"*。
**失效形态是"行消失"而不是报错**：预设不在名单里、`study` 行不挂载、18 个工具一个不剩，
而插件代码与平台契约探针全绿——本仓库 2026-09-24 就是这样被咬的。

现在的唯一形态：

```
package.json
└── dsh.bundle.patch: ./presets/study.patch.yml     ← 包被 profile 选中后由 DSH 读入
    └── insert: preset-study                        ← 行 id 约定 preset-<id>
        name: '@deepseek-ai/dsh-agent-preset'
        config: { id, name, description, order, plugins: [...] }
```

自查顺序：`plugin_manager list_bundles`（本包在不在、enabled）→ `list_plugins`（`include:preset-study`
的 `fiberPhase`，以及它的 diagnostic）→ 新会话看工具面。改声明后跑
`node tools/verify-contract.mjs`（交付形态断言）与 `pnpm run verify:deploy`（仓库 ↔ 已安装副本
的 patch 哈希 + bundle 选中状态）。

> 技能与期望模板随包发（`presets/study/skills/`、`presets/study/assets/`），声明里用
> `createRequire(baseUrl).resolve('dsh-study-buddy/package.json')` 从**已安装包**解析路径——
> 这是官方 `@deepseek-ai/dsh-web-app` 的 `presets/cordis.patch.yml` 同款惯用法。

> **已修**：`expectFile` 曾是"配了不生效"的静默陷阱（路径写死常量）。现已贯通
> `dirs.expectPathFor` → `VaultStore.expectPath()` → 门禁签名 → 回显文案，
> 并对含路径分隔符的文件名做越界防御（`tests/noteflow.spec.ts` 有用例）。