历史版本

` 块 | | **行为契约** | 由工具强制的前置条件（如"未读期望不写、未确认规划不写"），不靠 Agent 自觉 | 新增（硬门禁的落点） | | **只读根** | 会话工作目录与 `searchRoots`（旧笔记库）：可检索、不可写 | 不变 | --- ## 三、决策表（需求基线） > 状态 = 已确认（需求方拍板）／待确认（本文件提出、架构阶段定稿）。 > 逐条问答原文见 [附录 A](#附录-a决策溯源)。 | # | 决策点 | 结论 | 状态 | | :-- | :-- | :-- | :-- | | R1 | 块落盘形态 | 完整 frontmatter + ID（沿用现有五键） | 已确认 | | R2 | frontmatter 契约 | 沿用 `ID/标题/领域/来源/状态`，**扩展文档键**（如 `来源章节`） | 已确认 | | R3 | 文件夹层级 | 理论支持 N 级；课程笔记四层 `资料 / 章 / 节 / 块`，项目类笔记可只用三层 | 已确认 | | R4 | 拆分口径 | 按**可独立阅读的知识单元**切分，不设字数上下限；拒绝"大块搬小文件"的伪拆分 | 已确认 | | R5 | 内容形态 | 百科全书式/文档式：尽细尽全、完整推导、术语定义、交叉引用、图表公式 | 已确认 | | R6 | 块内结构模板 | **彻底取消**三型模板与必填小节强制 | 已确认 | | R7 | 字数与模块约束 | 笔记生成前的唯一约束来源是 `笔记期望.md`；代码中不得内建字数/模块硬编码 | 已确认 | | R8 | 笔记期望的形态 | vault 根一份自由 Markdown；默认模板由仓库提供，用户复制后自定义 | 已确认 | | R9 | 领域侧重口径 | 领域侧重亦写入期望文件；`domain-adaptation` 技能不再定义侧重（单一来源） | 已确认 | | R10 | 文件夹规划 | Agent 先提案、用户拍板后落盘（硬门禁） | 已确认 | | R11 | 规划产物位置 | **只在对话中给出提案**（不落盘、不新增 vault 可见文件）；写入需携带已确认的规划凭据 | 已确认 | | R12 | 微目录适用面 | 每个主题目录都必须有 `微目录.md` | 已确认 | | R13 | 微目录产生方式 | 由工具扫描目录实况生成（可重跑刷新），杜绝手写漂移 | 已确认 | | R14 | 检索形态 | ① 按主题目录列块 + 读微目录；② 按父级逐层导航；③ 块间前置/后续/兄弟关联；④ 主题级总览（块清单 + 覆盖度） | 已确认 | | R15 | 完整性口径 | 按**来源章节**对照：以 `来源章节` 为题录，以实际存在的章节文件为完整性基线；**不虚构**全章节清单 | 已确认 | | R16 | 跨主题引用 | 统一用 Obsidian wikilink（`[[…]]`），不再以 ID 作正文引用主形式 | 已确认 | | R17 | 重建边界 | **对外工具集全新，底层引擎保留**（原子写、路径越界防护、多根索引、CJK 分词） | 已确认 | | R18 | 卡片概念是否退场 | 是：「卡片」语义退场；旧的 `card_*` 工具面由新工具集取代 | 已确认 | | R19 | 存量卡片 | 原地保留、不自动改写；提供**显式升级路径**（用户命令才迁移） | 已确认 | | R20 | 旧笔记/工作目录 | 保留多根**只读**检索（`includeSessionCwd` / `searchRoots`）；写入仍只允许 vault 内 | 已确认 | | R21 | 命名与排序 | 块文件名**不加序号前缀**；阅读顺序由微目录 + frontmatter 顺序键承担 | 已确认 | | R22 | vault 根总目录 | 不新增；导航靠各级微目录 | 已确认 | | R23 | 增量更新 | 推翻/替换时旧内容**另存历史文件**，正文不堆叠历史块 | 已确认 | | R24 | 四步闭环 | 读取 → 讲解 → 问答 → 归档保留；归档阶段插入"读期望 + 规划确认"前置步 | 已确认 | | R25 | 硬门禁落点 | 工具侧强制校验（未读期望 / 未确认规划 → 拒绝写入），而非仅写进 persona | 已确认 | | R26 | 新工具集合命名 | 候选：`note_*` / `study_*`（见 §五）；具体命名与拆分待架构阶段定稿 | 待确认 | | R27 | 历史存档位置 | 候选 `.study/history/.md`（内置跳过扫描，可用工具恢复） | 待确认 | | R28 | 期望文件缺失时行为 | 候选：**fail-loud 提示创建**，不静默回退到内建默认写法 | 待确认 | | R29 | 覆盖度依据的语法 | 候选：`来源章节` 遵循 `《资料名》第N章标题 / N.N节` 规范，工具按章聚合 | 待确认 | | R30 | 领域键（`domainFolders`）去留 | 候选：`domainFolders` 退为"常用目录快捷方式"，落盘目录主键改为用户在规划中确认的路径 | 待确认 | ### 3.1 三条不变量（不得破坏） 1. **磁盘是唯一真相**——块就是普通 `.md`，Obsidian 手改、git 回滚永远有效；索引按签名重扫，不与用户编辑打架。 2. **决定权在用户**——讲不讲、写不写、落到哪个目录、改不改旧内容，都由用户下令；Agent 只给提案与对比。 3. **fail-loud**——配置错误、状态文件损坏、前置条件未满足一律抛错并给出修复步骤，不静默降级。 --- ## 四、现状与差距 ### 4.1 现状基线（v0.9.1 实测） | 维度 | 现状 | | :-- | :-- | | 工具 | 12 个：`card_search/get/id/create/update/link/moc/lint/history/rename` + `study_progress/memory` | | 内容模型 | 「卡片 = 可独立复读的微课程」；三型模板（理论型 6 节 / 工程型 8 节 / 对比型 7 节）**必填小节**；单卡 = 单原子知识点 | | 长度约束 | 正文不设上下限；**一句话定义 ≤60 字硬拒绝**（31~60 字提示放行） | | 归档约束 | 理论型/工程型/对比型分型推断（领域表 + 标题词表，可在 `templateHints` 覆盖） | | 目录约束 | 领域键 → 目录映射 `domainFolders`（40+ 键）；未映射落 `未分类/<领域>/`；**无层级规划、无目录内导航** | | 质量约束 | `card_lint` 14 条规则（13 警告 + 1 info），100 分制；模板必填小节占 5 分/节 | | 更新约束 | `append-version` / `errata` / `replace`（旧正文压入 `

` 折叠块） | | 检索 | 多根（vault + 会话工作目录 + `searchRoots`）、CJK 双字组 + 英文分词、字段加权（标题 4 / 定义 3 / 领域 2 / 正文 1）、默认 limit 5 上限 50；索引 TTL 2s（未命中强制重扫）、`maxWalkFiles` 20000、深度 16 | | 状态 | `.study/progress.json`、`.study/memory.json`（含 `_autoPrefs` 自迭代开关） | | 规模 | `src/` 16 模块、`tests/` 18 文件 265 项、CI `pnpm run check`；零运行时依赖 | ### 4.2 差距（需求方反馈 → 症状 → 差距） | 反馈 | 现状症状 | 差距 | | :-- | :-- | :-- | | ① 卡片式笔记过于简陋 | 内容是"骨架"：固定小节 + 要点式条目，信息密度低；读者仍需回头找原始资料才能真懂 | 缺"尽细尽全"的承载形态：完整推导、术语定义、举例与对比、交叉引用、公式与图表都没有位置 | | ② 笔记被无脑堆叠 | 一块一块按领域键丢进目录，目录靠领域映射被动生成；同一主题的块彼此无阅读顺序、无入口 | 缺"先规划后落盘"的约束：没有目录结构规划、没有主题内的导航入口（微目录）、没有完整性视角 | | ③ 约束过多 | 三型模板 + 必填小节 + 定义 ≤60 字硬拒绝 + 分型推断 + 14 条 lint 评分，全部硬编码在代码里 | 缺"热配置"入口：用户的写作期望（受众/详略/文风/领域侧重）无法表达，只能被代码里的模板牵着走 | ### 4.3 保留与重做的分界（对应 R17/R18） | 处理 | 内容 | 理由 | | :-- | :-- | :-- | | **保留（底层引擎）** | 原子写（临时文件 + rename）、路径越界校验、多根扫描与去重、CJK 分词 + 加权召回 + 索引 TTL、`.study` 状态持久化、fail-loud 错误语义、零运行时依赖与构建/测试骨架 | 已验证、与"文档式笔记"无冲突；重写只增加回归面 | | **重做（对外能力面）** | 工具集（命名、粒度、前置条件）、内容模型（文档式块，无模板）、目录模型（层级 + 规划 + 微目录）、约束来源（期望文件取代代码内模板）、历史模型（外部存档取代折叠块）、检索形态（目录导航 + 覆盖度总览） | 需求 ①②③ 全部落在这里 | | **退场** | 三型模板与分型推断、模板必填小节 lint 规则、`

` 历史折叠、`card_moc`（由微目录承担）、`card_id`（并入写入流程） | 与"解除约束/拒绝库房式堆叠"直接冲突 | | **降级** | `domain-adaptation` 技能（不再定义领域侧重，仅说明默认值与触发场景）、`domainFolders`（退为常用目录快捷方式） | 避免与期望文件形成两套口径 | --- ## 五、功能需求 ### 5.0 候选工具面（F0 · 待架构阶段定稿） > 下表是需求层对"能力"的划分，工具名与拆分方式（如写入与更新是否合一）属架构决策，标注为候选。 | 能力 | 候选工具 | 必填 | 可选 | 契约要点 | | :-- | :-- | :-- | :-- | :-- | | 笔记库与期望状态 | `note_library` | `action(check)` | — | 返回 vault 可写性、**期望文件是否存在**、顶层目录清单、块统计；期望缺失 → 明确提示创建（R28） | | 逐层导航 | `note_list` | — | `path`（缺省 = 顶层）、`depth`、`withSummary` | 目录树：子目录 + 主题目录 + 块清单 + 是否有微目录 | | 读取 | `note_get` | `ref` | — | 完整原文；`ref` 支持 ID / 相对路径 / 文件名的现有解析口径 | | **规划（硬门禁入口）** | `note_plan` | `rootPath`、`items[]` | `material`、`notes` | 生成「目录结构 + 块清单」提案；用户确认后返回 **planId**；不落盘（R11） | | 写入块 | `note_write` | `planId`、`title`、`source`、`content` | `path`、`sourceSection`、`order`、`domain`、`status`、`links` | 校验链：期望已读 → 规划已确认 → 路径在规划范围内；**无字数与模块硬拒**；违规抛错并列修复步骤（R25） | | 更新块 | `note_update` | `id`、`mode` | `changes`/`source`/`newContent` | `append`（补充，正文内追加）／`replace`（替换，旧正文转历史）／`move`（迁目录） | | 历史存档 | `note_history` | `action(list\|restore)` | `ref`、`dryRun` | 列出/恢复 `.study/history/` 的存档（R23） | | 生成微目录 | `note_toc` | `dir` | `dryRun`、`title` | 扫描该目录块实况生成 `微目录.md`；重跑覆盖同段（R13/R21） | | 主题总览与覆盖度 | `note_overview` | — | `path`、`material` | 每主题的块清单 + 按 `来源章节` 聚合的覆盖情况；**不虚构未出现的章节**（R15） | | 关联 | `note_link` | `from`、`to`、`kind` | — | `kind = prev`/`next`/`sibling`；落盘为 **wikilink**（R16）；旧笔记按路径寻址 | | 质量体检 | `note_lint` | — | `ref`/`scope`/`rule` | 只保留通用规则（会话残留 / 代码块语言 / 外部资源），可扩展为**期望一致性**检查（见 F6） | | 进度 | `study_progress` | `action` | `material`/`section`/`pendingQuestions[]`/`touchedIds[]` | 语义不变（跨会话断点） | | 记忆 | `study_memory` | `action` | `key`/`value` | 语义不变（含 `_autoPrefs` 自迭代开关） | **约定**：所有工具返回纯文本并含回显行（`已写入：<相对路径>` / `已生成：<相对路径>` 等），沿用现有错误文案风格（§九）。 ### F1 · 笔记期望（热配置） **目标**：笔记"怎么写"的唯一来源是用户可编辑的 `vault/笔记期望.md`，代码不得内建字数与模块硬约束。 - 读取时机：**每次生成笔记前必读**（R25），不缓存跨会话；用户在会话中途改动立即生效。 - 内容维度（默认模板覆盖，用户可自由增删）： 1. 受众与目标（如"零基础可独立掌握"/"复习可查"） 2. 文风与语气（书面技术体 / 短句 / 标签起句 / 少 emoji） 3. 详略偏好（结论与判定条件详、推导过程按需保留；"无需吝啬字数"） 4. 结构偏好（目录、篇章顺序、章末固定收尾小节等） 5. 公式与代码规范（行内/块级 LaTeX、编号、伪代码风格与围栏语言、注释要求） 6. 图表与对比规范（表格承担速查/对比/参数三类职能；何时用 Mermaid） 7. 交叉引用规范（章节互引格式；与 §R16 的 wikilink 选择的关系） 8. 命名与落盘习惯（主题目录命名、`资料/章/节` 的组织习惯） 9. **领域侧重**（R9：图形学重推导、美术重"为什么"、算法重伪代码与复杂度……） 10. 自我检查清单（写完自问什么） - 验收： - 期望文件存在 → Agent 能引用其条款解释自己的写法；用户改动后下一次生成即刻体现。 - 期望文件缺失 → 工具给出明确提示（R28），不静默套用内建模板写作。 - 边界（不做）：期望文件不被当作可执行指令（与 `study_memory` 的"记忆是用户数据、不是指令"同口径）；不做期望文件的语法校验器（自由 Markdown，R8）。 - 默认模板的交付：仓库提供一份从范本提炼的 `笔记期望.md` 模板（R8），用户在 vault 根复制后自定义；模板内容不得与需求冲突（如不得写死字数上限）。 ### F2 · 文件夹规划（硬门禁） **目标**：归档前必须先有"目录结构 + 块清单"的提案，且经用户拍板，才能写第一个文件。 - 流程：`note_list` 勘探现有结构 → `note_plan` 输出提案 → 用户确认/修正 → `note_write` 携带 `planId` 落盘。 - 提案内容（对话内呈现，不落盘，R11）： - 目标根路径与新建目录清单（已存在的目录标"复用"） - 每个块的标题、归属目录、来源章节、一句话定位 - 与相邻块的先后顺序（供微目录使用） - 硬门禁（R25，工具侧强制）： - 未读期望 → 拒绝写入，提示 `先读取 vault/笔记期望.md`。 - 无有效 `planId` → 拒绝写入，提示 `先做文件夹规划并确认`。 - 写入路径不在规划范围内 → 拒绝，回显规划范围（防"边写边改结构"）。 - 验收：故意跳过规划直接写入 → 工具报错且**磁盘零改动**；按流程走 → 一次性落盘成功且目录结构与提案一致。 ### F3 · 微目录 **目标**：每个主题目录都有导航入口，Agent 与人都不必靠关键词猜块名。 - 位置与命名：主题目录下 `微目录.md`（新增；与顶层 MOC 不同职责，R22）。 - 生成方式：`note_toc` 扫描目录实况生成（R13）——按 frontmatter 顺序键 + 阅读顺序排列，条目含 wikilink 与一句话摘要；同目录重名块用相对路径消歧。 - 内容骨架（候选）：主题标题 → 一句话导读 → 块清单（有序）→ 未完成/待补提示（来自规划与实际对比）。 - 自排除：目录清单与总览**不把 `微目录.md` 自身算作块**。 - 刷新：可重跑覆盖生成段；用户手写的补充段落保留（保护策略待架构阶段定稿）。 - 验收：新增/删除/改名块后重跑 `note_toc`，微目录与目录实况一致；导航从微目录一跳可达任一块。 ### F4 · 块内容生成（解除约束） **目标**：生成自由度由期望文件界定；内容"尽细尽全、拒绝简陋"。 - 内容要求（来自需求与范本特征，须写入技能与 persona，但**不得成为代码硬拒绝**）： - 术语首现给完整定义（引用块） - 重要定理/公式保留完整推导步骤 - 抽象概念配 1~2 个简例；算法给带注释的伪代码 - 易混概念用表格对比；复杂关系用表格或 Mermaid - 已出现过的概念加章节互引（与 R16 的 wikilink 口径统一） - 段落短、留白足；不吝啬篇幅 - 明确删除的约束： - 三型模板与必填小节（R6）→ 代码中不再存在；`note_write` 不对小节做任何检查 - 一句话定义 ≤60 字硬拒绝 → 删除（仅可由期望文件自行提出偏好） - 分型推断（领域表 / 标题词表）→ 删除；`templateHints` 配置键随之删除 - `card_lint` 的 `definition-length` / `template-sections` / `mainline` / `prereq-check` / `reentry-point` / `verify-experiment` / `troubleshoot-criteria` / `selftest-answer` / `layer-number` / `links-format` 等模板类规则 → 删除 - 保留的通用校验（与内容自由度无关，属数据安全与可读性）：字段含换行拒绝、状态枚举、路径安全、代码块语言标注（可配置关闭）、会话残留（可配置级别）、外部资源提示。 ### F5 · 归档流程（四步闭环的第四步改造） **目标**：归档成为"读期望 → 规划 → 落盘 → 微目录 → 覆盖度"的闭环，且每步可审计。 ``` 用户："整理笔记 / 生成笔记 / 归档" 1. study_progress(get) 查未答追问（未闭环先提示；红线不变） 2. note_library(check) + 读取 vault/笔记期望.md（硬门禁：未读不写） 3. note_list 勘探层级 → note_plan 提案 → 用户确认（硬门禁：未确认不写） 4. note_write × N（按块落盘；只重组去重，不加新知识） 5. note_link 建块间关联（wikilink） 6. note_toc 生成/刷新各级微目录 7. note_overview 输出本次覆盖情况（含缺口） 8. study_progress(set touchedIds, 清已答追问) + study_memory(set lastSummary) ``` - 讲解阶段仍可出"笔记预览"，但预览形态改为**文档式块预览**（不再按三型模板分型）。 - 增量场景：新内容与既有块相关 → `note_update(append/replace)`；推翻旧结论时旧正文转历史存档（R23）；仅补充时直接追加到对应小节，**不产生版本块**。 ### F6 · 质量体检（降级但保留价值） - 保留：会话残留（本机路径/行号/会话口吻）、代码块语言、外部资源提示——这三类与"内容自由"无关，仍是可判定的质量问题。 - 新增（候选）：**期望一致性检查**（只在期望文件里写了明确规则时才启用，如"正文不得出现 emoji"），避免把检查写死在代码里——与 F1 的"热配置"精神一致。 - 删除：全部模板类规则与 100 分制中的模板扣分；总分体系是否保留（或改为"问题清单"）属架构决策。 ### F7 · 检索与导航 | 能力 | 行为 | 验收 | | :-- | :-- | :-- | | 逐层导航 | `note_list(path)` 返回子目录 / 主题目录 / 块 / 是否已有微目录 | 从顶层到任一主题不超过 3 次调用 | | 主题列块 | `note_list(path=<主题目录>)` 列出块（标题 + 一句话 + 来源章节 + 顺序） | 不需要关键词即可枚举主题全部块 | | 读微目录 | `note_get(微目录)` 直接读导航文件 | 微目录中的 wikilink 与块实况一致 | | 块间关联 | `note_link` 建 prev/next/sibling，落盘 wikilink | 关联双向可追踪；重名块不误连 | | 主题总览 | `note_overview(path)` 输出块清单 + 按 `来源章节` 聚合的覆盖情况 | 缺口显式列出；不虚构未出现的章节 | | 全库检索 | `note_search` 保留关键词召回（CJK 双字组 + 英文，字段加权） | 与检索能力不退化：旧笔记与多根仍可命中 | - 多根只读（R20）不变：vault 可写，会话工作目录与 `searchRoots` 只读；命中仍标注类型与根限定路径。 ### F8 · 兼容与迁移（存量资产） - **存量卡片**：不自动改写、不批量迁移；检索、读取、关联照常可用（R19）。 - **显式升级路径**（用户命令才执行）：把一张卡升级为块（补齐 `来源章节` 等文档键、落到规划目录、纳入微目录）；把一篇旧笔记升级（保留原文，重写为文档式块）。升级过程必须：先 dryRun 报告将改什么 → 用户确认 → 再落盘。 - **状态文件**：`.study/progress.json` / `.study/memory.json` 结构不变，向后兼容；新增 `.study/history/`（存档）与规划凭据存储（候选同名目录）。 - **配置**：`vaultRoot` 语义不变；`domainFolders` 降为便捷映射（R30）；`templateHints` 删除；`lint` 配置项收敛为通用规则。 - **默认不回退**：旧卡与新块并存的库，`note_overview` 明确标注"存量卡片"不属于任何主题目录的完整性口径。 --- ## 六、非功能需求 ### N1 数据安全（不可谈判） - 写入仍走原子写（临时文件 + rename），失败不留半成品。 - 所有落盘路径经 `withinRoot` 校验；只读根永不写入。 - 硬门禁失败、校验失败 → **磁盘零改动**，报错给出修复步骤。 - 破坏性操作（`replace`、`note_history restore`、升级路径）支持 `dryRun` 预演。 ### N2 性能与成本 - 每请求固定开销不得显著上升（现行 ~15.0 KB / 21 工具为基线）；新增工具应合并能力而非逐一加工具。 - 索引侧沿用签名（mtime/ctime/size）+ TTL（默认 2s）+ 未命中强制重扫；微目录生成不得触发全库写盘。 - 大规模库（1000+ 块）导航仍需可控：`note_list` 按需分级读取，不一次性吐全库。 ### N3 兼容性 - 既有 vault 不被破坏：无新文件覆盖用户的同名文件（冲突走现有同名后缀策略）。 - 旧笔记零改动默认不变（`linkIntoNotes` 语义保留）。 - 索引跳过清单不变（`.obsidian` / `.trash` / `.study` / `.git` / `node_modules` + `skipDirs`）。 ### N4 可观测性 - 每次写入都回显：`已写入：<相对路径>` + `ID：…` + 规划归属 + 微目录是否需刷新。 - 跳过项按原因分组回显（沿用 `⚠ 跳过 N 项未完整处理：<原因>`），不静默吞掉。 ### N5 开发风格保持（需求方明示） | 保持项 | 具体 | | :-- | :-- | | 架构形态 | 插件（`src/`，零运行时依赖，`@deepseek-ai/*` external）+ 预设（`presets/study/`：persona + 技能）不动 | | 代码风格 | 中文注释写"为什么"（含踩坑编号引用）、纯函数优先、模块单一职责、类型只有一处定义 | | 测试风格 | `tests/*.spec.ts` 同构分文件；① 白名单反例优先于正例 ② 断言用带引号的精确子串 ③ 改行为改断言不改实现迁就断言 | | 文档纪律 | 口径单一来源；"能被解析的就不靠自觉"（文档链接/版本基线/规则清单由测试钉住）；改代码要同步的文档对照表 | | 交付纪律 | `pnpm run check`（typecheck + vitest + esbuild）全绿；`package.json` 与 `dsh.plugin.json` 版本一致 | ### N6 文档同步（重构完成后必须齐备） - `docs/README.md` 登记本文件并把 `设计文档.md` / `技术文档.md` / `用户使用指南.md` 更新到新基线。 - 新模板文件（`笔记期望.md` 默认模板）需有使用说明，并纳入部署步骤。 - 验证脚本 `docs/check/prompt-verify-all-features.md` 覆盖：期望读取、规划确认、块落盘、微目录、总览、历史存档六条主路径。 --- ## 七、工具面变化对照 | 现有 | 去向 | 说明 | | :-- | :-- | :-- | | `card_search` | `note_search`（保留能力） | 检索口径不变 | | `card_get` | `note_get`（保留能力） | ref 解析口径不变 | | `card_create` | `note_write`（重做） | 新增规划凭据与期望前置；删除分型/小节/定义长度校验 | | `card_update` | `note_update`（重做） | 模式收敛为 `append`/`replace`/`move`；历史转外部存档 | | `card_link` | `note_link`（重做） | `kind` 改为 `prev/next/sibling`；落盘改 wikilink | | `card_moc` | **删除** | 由 `note_toc`（微目录）+ `note_overview`（总览）承担 | | `card_id` | **删除** | ID 由写入流程内生成并回显 | | `card_lint` | `note_lint`（降级） | 只留通用规则（+候选的期望一致性检查） | | `card_history` | `note_history`（重做） | 从"文件内折叠块"改为"外部存档文件" | | `card_rename` | `note_rename`（保留能力） | 改名同步文件名 + wikilink 入链 + 断链检测 | | （新） | `note_library` | 期望文件与库状态检查（硬门禁第一环） | | （新） | `note_list` | 逐层导航 + 主题列块 | | （新） | `note_plan` | 文件夹规划提案与确认（硬门禁第二环） | | （新） | `note_toc` | 微目录生成 | | （新） | `note_overview` | 主题总览与覆盖度 | | `study_progress` / `study_memory` | **保留** | 语义不变 | > 工具总数需在架构阶段核算：目标是不显著增加每请求固定开销（N2），能力拆分以"一个工具一个动词"为准。 --- ## 八、验收总纲 | 门 | 标准 | 验证方式 | | :-- | :-- | :-- | | **功能闭环** | 空库到可用：建期望 → 规划 → 落块 → 微目录 → 导航 → 覆盖度，全链路一次通过 | 临时 vault 端到端测试 + 手工走查 | | **约束解除** | 代码中不存在三型模板、必填小节、定义字数硬拒绝、分型推断；生成行为随 `笔记期望.md` 变化 | 单测 + 改期望文件后的行为对比 | | **硬门禁** | 未读期望 / 未确认规划 / 越界路径 → 拒绝写入且磁盘零改动 | 失败路径测试（断言文件不存在） | | **导航正确** | 每个主题目录都有微目录；增删改名块后重跑即一致 | 单测 + 真实库抽样 | | **完整性可用** | 覆盖度按 `来源章节` 聚合，缺口显式；不虚构章节 | 单测（含缺章节、跨资料、章节号不规范的样例） | | **存量兼容** | 存量卡片可被检索/读取；显式升级路径可预演、可回滚 | 复制真实 vault 子集做回归 | | **不退化** | 原子写、路径越界防护、多根只读、跳过项回显全部保留 | 现有 store/vault/search 用例迁移后必须全绿 | | **工程质量** | `pnpm run check` 全绿；两个 manifest 版本一致；文档链接与版本基线守卫通过 | CI | | **风格一致** | 新代码与文档沿用既有模块划分、注释习惯、测试约定（N5） | 评审 | --- ## 九、范围边界 ### 9.1 本轮做 - 工具面重建（§七）。 - 内容模型从"卡片微课程"改为"百科全书式文档块"，删除全部模板类硬约束。 - 目录模型：`资料 / 章 / 节 / 块` 层级 + 硬门禁规划 + 微目录 + 覆盖度总览。 - `笔记期望.md` 热配置（含默认模板交付）+ 前置读取门禁。 - 历史存档模型（外部文件）。 - 存量卡片的显式升级路径。 - 配套：preset（persona + 6 个技能改写/裁剪）、配置键收敛、文档同步、测试补齐。 ### 9.2 本轮不做（明确排除） - 语义检索（嵌入向量）——路线图项，不在本轮。 - 卡片浏览面板（客户端 Slot UI）。 - 复习测验子模式、遗忘曲线元数据。 - 多 vault 支持。 - 把工作目录变成可写落盘目标（R20 明确只读）。 - 自动批量迁移存量卡片（R19 明确只保留显式路径）。 - 期望文件的语法校验器／DSL（R8 保持自由 Markdown）。 ### 9.3 文案与报错风格 - 沿用现有风格：中文、短句、含修复步骤；回显行以固定前缀开头（`已写入：` / `已生成：` / `已更新：` / `未命中（共检索 N 篇）`）。 - 引号与标点沿用现行（中文引号、全角冒号），不引入 emoji（`⚠` 保留为唯一警示符）。 --- ## 十、风险与对策 | # | 风险 | 影响 | 对策 | | :-- | :-- | :-- | :-- | | 1 | 期望文件写得太笼统，生成质量漂移 | 回到"简陋" | 默认模板给出可操作条款（受众/详略/公式/收尾小节）；`note_overview` 与讲解阶段暴露偏差，用户随时补条款 | | 2 | 微目录只列链接，信息量不足 | 导航价值低 | 条目携带一句话摘要与来源章节；允许在生成段外保留用户手写的导读段 | | 3 | 硬门禁增加摩擦（每次归档多两步） | 用户嫌麻烦 | 规划提案尽量简短（仅新增目录 + 块清单）；复用现有目录时一键确认；规划只在"结构有变化"时才要求 | | 4 | 门禁死锁（期望文件丢失/只读/vault 不可写） | 工具全面不可用 | fail-loud 且给出修复步骤；`note_library(check)` 单点自检；期望缺失不静默回退（R28） | | 5 | 覆盖度口径依赖 `来源章节` 书写规范 | 总览失真 | 写入时工具校验并归一（R29）；解析不出章节的块列入"未归类"而非丢弃 | | 6 | 无序号前缀导致同名块 | 链接歧义 | 沿用冲突后缀策略（`_ID末6位`）；微目录用相对路径消歧 | | 7 | 存量卡片与新块双形态长期并存 | 一致性差 | 总览分层标注；提供显式升级路径；不强制迁移 | | 8 | 历史存档落在 `.study/` 导致用户不易发现 | 误以为内容丢失 | 工具报告与文档明确路径；`note_history(list)` 可列、可恢复 | | 9 | 工具面变大使固定开销上升 | 每轮成本上升 | 能力合并（见 §七注）；工具描述由注册表派生；核算每请求字节数不高于现行基线太多 | --- ## 附录 A：决策溯源四轮问答共 26 问，逐条落点如下（问答原文见会话记录）。 | 轮次 | 主题 | 决策点 | | :-- | :-- | :-- | | 第一轮（9 问） | 块的形态、层级、拆分口径、期望形态、卡片去留、规划主导、微目录产生、检索形态、默认模板 | R1 R3 R4 R8 R17（先"保留工具链"）R10 R13 R14 R8 | | 第二轮（5 问） | 工具语义、块内模板、微目录适用面、门禁强度、增量历史 | R18（改为推倒重建）R6 R12 R25 R23 | | 第三轮（5 问） | 重建边界、frontmatter、规划产物、完整性口径、引用格式 | R17 R2 R11 R15 R16 | | 第四轮（5 问） | 存量卡、多根范围、命名排序、顶层索引、领域侧重口径 | R19 R20 R21 R22 R9 | | 第五轮（2 问） | 知识点与章节的层级关系、领域侧重单一来源 | R3 R9 | **决策变更留痕**：R17 在第二轮曾被选为"推倒重建为全新文档工具集"，第三轮细化为"对外工具集全新、底层引擎保留"——需求以第三轮结论为准（R17）。 ## 附录 B：范本特征 → 需求映射需求方给定的 22 篇范本特征（`笔记特征分析.md`）在需求上的落点： | 范本特征 | 落点 | | :-- | :-- | | 首行章标题 → 目录 → 小节 → 章末固定收尾小节 | F1（结构偏好写入期望）+ F3（微目录承担目录职能） | | 结论详、过程略；保留定义/推导/伪代码/复杂度/对比/例题/易错点/归纳 | F4（内容要求清单） | | 书面技术体、短句、`**标签**：` 起句、中英并置、纯客观 | F1（文风与语气条款） | | 加粗/表格/引用块/公式/伪代码/`→` 箭头/序号圈号；不用高亮与删除线 | F1（格式规范条款） | | 对比、举例、公式化、伪代码、类比、自问自答、跨章互引、归纳收束 | F4 + R16（互引统一 wikilink） | | 文末 `### Q：` 问答、⭐ 难度分级、章末固定仪式、元信息自标注 | F1（可自定义的个性化习惯，不进代码） | | 项目类笔记：保留决策过程与被否方案、微计划表、问答附录 | F1 + R3（项目类笔记可只用三层） | ## 附录 C：待确认项汇总 | # | 待确认 | 决策时点 | | :-- | :-- | :-- | | R26 | 工具集命名与拆分（`note_*` 是否最终采用；写入与更新是否合一） | 架构选型 | | R27 | 历史存档目录（`.study/history/`）与规划凭据存储位置 | 架构选型 | | R28 | 期望文件缺失时的具体行为（fail-loud 提示的文案与是否允许一次性临时回退） | 架构选型 | | R29 | `来源章节` 的规范语法与工具归一策略 | 架构选型 | | R30 | `domainFolders` 的收敛程度（删除 / 保留为快捷方式 / 改造为"目录模板"） | 架构选型 | | — | `note_lint` 总分体系是否保留（或改为问题清单） | 架构选型 |