DSH 数学笔记助手（dsh-math-memory）

把 DeepSeek Harness 变成一个住在 Obsidian 右侧栏里的长期数学笔记助手。

一个双组件仓库：

Obsidian 社区插件（id dsh-math-assistant，仓库根 manifest.json + main.js）：右侧栏嵌入 dsh web、自动检测并启动 dsh 服务、首次运行自动初始化 dsh 侧配置与 vault 模板；另有记忆面板、捕获策略设置与确定性维护。
dsh 插件（npm 包 dsh-math-memory，dsh/）：把同一套 notes-assistant agent preset / profile 与 vault 模板安装进 $DSH_HOME。

三种安装方式（原生 bundle / --direct 离线拷贝 / Obsidian 内置直写）产出等价配置，靠 owner marker 避免互相覆盖。只装 Obsidian 插件即可使用；纯 CLI 用 dsh-math-memory install（含 uninstall）。

为什么做这个插件

数学学习是长周期积累：记号习惯、理论偏好、半成品证明、技巧、反例、想法都需要持续收集并打磨成关联体系。普通对话式 AI 把每次聊天当孤立问答；本插件给 agent 一套跨会话分层记忆（五层结构 + 记号体系 + 备忘录生命周期）、统一检索（笔记+记忆一次查清）与长期协议（AGENTS.md），让新会话从上次结束的地方开始。

这个项目解决到哪一步了（与 1.0 的距离）

说清楚边界，比堆特性重要：

已经解决的：「agent 记不住用户问过什么」。原文证据（episodes）确定性落盘、类型化原子记录（records）带来源链、五层结构 + 导航索引、统一检索（note_recall）一次查清、每轮按需注入而不是全量塞进上下文、每日体检 + 用户反馈闭环做确定性维护。也就是说：跨会话的"记得住、找得到、可纠正"这条线是通的。
还差得多的：「辅助用户打磨一套数学理解，并建立对理解、技巧等的调用体系」。现在记的是"用户问过什么/结论是什么"，不是"用户理解到哪、卡在哪、下一步该练什么"；技巧层只有存储与检索，没有调用体系（什么时候该用哪条、适用边界怎么判、失败了换哪条、几条如何组合）；也没有主动的教学闭环（诊断 → 提示 → 检验 → 复盘的长期档案）与复习调度。
因此：真正实现了后一条，才叫 1.0。 当前是 0.7.x 试做型——记忆基础设施可用、控制面可见可纠正，但离"学习伙伴"这个目标还差一代设计（缺什么、按什么顺序补，见 docs/handoff.md §7 与 docs/memory/assessment.md）。

特性

检索（v3：统一入口、粗筛-精读）

note_recall 统一检索：一次 BM25 排序覆盖用户笔记 + 全部记忆层（记忆卡带 hook 字段加权、备忘录、主题、定理/事件索引）；Unicode 连字符归一 + 中文字符包含桥接词形差异；命中带 coverage（查询词覆盖率，<0.35 视为词面巧合弱信号）。
精读挑选协议：蒸馏查询（挑战描述 + 候选技巧）→ 读前 2-3 篇全文逐条判适用 → 空结果改写重试一次 → 仍无则明说「库里没有」，不编造；同一轮 ≤2 次检索、≤3 篇全文。
导航式注入：系统提示只注入导航层（画像/记号/主题/记录/模板/事件索引），相关内容按需拉取——每轮注入有硬上限（≤18000 字符；各层预算见 docs/memory/design.md §3）。
note_strategy（证明/构造类问题的方法层）、note_links（反链/顺链扩读）、note_create（拒绝覆盖）配合使用。按 tag 枚举合并进了 note_recall（只给 tag、不给 query）：列出带该 tag 的笔记，按 updated 降序、不计相关性分数。note_search 已退役——只保留一个内容发现入口。

记忆（五层 + 维护闭环）

五层记忆：profile（语义层）/ topics（导航）/ records（类型化原子卡，带 hook 检索特征与验证等级 ✅⚖️❓）/ episodes（原始证据，append-only）/ inbox（想法备忘录，inbox→polishing→done）。
记号体系：memory/notation.md 三表（已采纳/候选/已否决 + 修订历史），「收集→统一→维护」——发现记号不一致时主动提议统一（用户无统一习惯时先观察再提）。
每日体检：确定性扫描 strong/weak/unused/疑似重复/unverified + 结构校验（缺 source/断链/未入索引）；note_recall 命中统计回写 uses/success_rate。
备忘录提醒：陈旧（inbox>7 天、polishing>3 天）或与当前讨论相关时提醒打磨，相关性×新鲜度排序。
捕获策略分级：idea/fact/preference/structure × auto/ask/off——一个档位对应一组记忆层（想法→inbox、事实→records、偏好→profile/记号、结构→主题/定理索引/模板/策略）；设置页下拉框或在任一记忆面板的「捕获策略」一行点选即可（都写回 capture-policy.md）；auto 档写入后回复末尾注明，ask 档提案含「一句话想法+为什么+拟写入位置」。
跨会话上下文：解析本机历史 dsh 会话（zstd JSONL），注入最近问答线索（自动排除当前会话，按 vault 过滤）。

控制面（Obsidian 侧）

记忆面板：首屏一行状态条（画像/记录/模板/主题/定理/策略/备忘录/事件 + 上次体检）；⚠️ 待处理（体检的「待重审 / 建议归档」直接摆在可点的归档按钮旁）；五层卡片合并浏览 + 搜索（标题/主题/类型/算子）；逐卡 ✅ 确认 / ❌ 有错 / 过期 / 归档（归档二次确认）并给出中文回执；事件时间线显示人类标题 + 主题（默认折叠 8 条）；记忆体检显示中文摘要（模型版清单折叠在「查看模型版清单」里）；面板内直接编辑保存（mtime 冲突防护）。
反馈闭环：回复内 依据的记忆：<卡标题> — [✅ 这条对] [❌ 这张卡有错] 链接经 loopback /feedback 端点确定性改写卡片（CSRF token 保护）；笔记引用可点击跳转 Obsidian（/open）。
回复质量协议：直觉先行、认知锚定（新内容挂钩你的笔记）、难度自适应、苏格拉底式纠错、低频检查性收尾。
默认不挂载 @linxin666 UI 插件（独立性）：profile 只 bundle dsh-web-app 以嵌入聊天 UI，默认不挂载 @linxin666/dsh-web-all 聚合的那一族 UI 插件（皮肤中心/任务看板/SSH/aionui 面板/git-graph/宠物/统计等）——因此没有 @linxin666 UI 包需要解析，有/无 web profile 都能干净启动。皮肤中心（皮肤选择 + 背景透明度）可在插件设置里选择性开启，而现在这两个包需要真的装进笔记 profile：设置页有一个按钮跑一次 dsh plugin add（需要 pnpm/网络；两个包连其运行时依赖约 1.9 MB）。装好之前那个开关不生效——挂一个解析不到的包会让这个 profile 起不来。插件因此不再创建任何目录链接：过去让这件事"隐式成立"的 junction 镜像已于 2026-09-26 退役，而皮肤本体也不再依赖全局 cordis.patch.yml 的插入（皮肤中心 0.4.x 已不再改写那个文件）。要注意那个安装动作的连带含义：dsh plugin add 会把这两个包登记成 profile 的 bundle，而它们各自自带挂载声明——所以装好之后它们会一直挂着，上面那个皮肤中心开关不再控制它们（插件会检测到这一点、什么都不插，而不是把行重复插一遍）。若本机 web profile 装的是 @linxin666/dsh-web-all 聚合包，这个开关在功能上是冗余的——聚合包已自带皮肤中心行。

安全（fail-closed）

工具面：文件读写/搜索 + 四个笔记工具（note_recall / note_strategy / note_create / note_links）+ ask_user；无 shell/web/子代理/删除工具。不挂载任何 @linxin666 UI 插件——保持最小 agent 工具面。
写操作限定 vault（workspace-write）；交互式提权默认禁用（approval: never）；DSH_PERMISSION_MODE=danger-full-access 仅重开提权询问、沙箱不变。
记忆全部是 vault 内 markdown；归档代替删除；模型不得修改策略/统计字段。

要求

Obsidian 桌面版；Node.js ≥ 22.5；DeepSeek Harness（npm 全局 @deepseek-ai/dsh，要求 ≥ 0.1.7-rc.2——本版适配了 0.1.7 的 preset 声明机制，见 docs/dsh-0.1.7-adaptation.md；会话数据格式 V3 的适配见 docs/dsh-0.1.5-adaptation.md）；已配置的 DeepSeek 模型。
- 同时已在 0.2.0-rc.2 上实测（当前 npm latest），而下限有意留在 0.1.7-rc.2：那个版本仍然可用，本轮审计没有发现破坏性变更、只做了契约修正。逐接口的核对与证据见 docs/dsh-0.2.0-adaptation.md。⚠️ 不要把这个范围收紧成 >=0.2.0 或 ^0.2.0——在 0.2.0-rc.2 这类 prerelease 运行时上它不匹配，dsh 会静默跳过插件的 bundle 层（退出码 0，只有一行 stderr）。
默认端口 3180（与 dsh web 的 3080 并存不冲突，可在设置里改）。

安装

方式 A（推荐）：Obsidian 设置 → 第三方插件 → 搜索 DSH Math Notes Assistant 安装启用；或手动把 main.js/manifest.json/styles.css 放进 <vault>/.obsidian/plugins/dsh-math-assistant/。首次运行自动检测 dsh、初始化 preset/profile/vault 模板、启动服务。

方式 B（CLI）：

npm install -g dsh-math-memory
dsh-math-memory install --vault "<你的 vault 路径>"
dsh --profile notes-assistant --port 3180                  # 启动（原生：bundle 已提供 panel/workspace，无需 --patch）

插件设置项：端口、dsh 安装目录、DSH_HOME、自动启动、自动初始化、自动归档（>90 天事件）、ribbon 按钮、关闭 Obsidian 时保留服务、皮肤中心开关（进阶；聚合包已自带皮肤中心）、侧栏性能模式（默认开启：代理把皮肤在侧栏里的高开销特效去掉，并把皮肤客户端脚本 hooks.mjs 的两处热循环减速——实测那才是侧栏卡顿的主因）、侧栏加载皮肤动态装饰（默认开启；关掉则侧栏不加载皮肤脚本，实测最流畅，代价是 hero 场景/状态角色消失）、捕获策略四档下拉框。详细原因与实测数据见 docs/memory/sidebar-performance.md。

完整指引：安装原理、冲突解决（owner marker / --force 接管）与卸载（三级删除、--purge-data 确认短语）见 docs/installation.md；发版与商店更新通道见 docs/release.md。更新随商店与插件管理器走——只要存在 tag 等于 manifest.json 版本的 Release，就不必手动换文件。

vault 布局

vault/
  AGENTS.md                       工作协议（自动加载）
  .deepseek/
    memory/profile.md             语义层（画像）
    memory/notation.md            记号体系（收集→统一→维护）
    memory/topics/                导航层
    memory/records/               记录层（原子卡 + hook）
    memory/theorems/              定理索引（个人 Matlas）
    memory/templates/             问题模板库（题型↔定理图）
    memory/episodes/              证据层（append-only + archive/）
    inbox/                        想法备忘录
    capture-policy.md             捕获策略（用户维护）
    cache/                        机器生成缓存（勿动）

开发与质量

npm test          # 语法 + 455 项零 token 回归 + 路由回归（62 项路由断言） + 侧栏认证握手回归（8 项，对真实 dsh）+ 侧栏反代回归（32 项）+ 安装器 e2e（漂移检测）
npm run qa        # 引擎探针：真实 vault 12 组召回断言 + 可达性分层/A-B 测量（零 token）
npm run qa:e2e    # 真实会话端到端验收（烧真实 tokens，报告 API 级 usage）
node scripts/build-obsidian.mjs   # 重建 main.js（改共享文件后必跑）
node scripts/deploy-local.mjs     # 本机一键部署

仓库结构：ARCHITECTURE.md——目录职责、双组件数据流、记忆↔检索边界、落地清单。
记忆系统知识库：docs/memory/——design（实现规格）、retrieval-v3（检索提案 + §7 GraphMemix 吸纳决策与 A/B 实测）、testing（QA 方法论）、assessment、references（论文笔记）、sidebar-performance（侧栏卡顿的原因清单与处置）、changelog、handoff。
宿主版本适配：docs/dsh-0.1.5-adaptation.md——dsh 0.1.5-rc.1 / 会话格式 V3 / [email protected] 的影响取证、修复清单与「刻意不改」的理由。
验收记录：两个探针都改为调用产品自己的排序管线（buildRecallDoc / rankRecallDocuments / rankStrategyCards），不再各自复刻公式——仿真 vault 探针 8/8，真实 vault 探针 12/12（导航索引已降权，因此「库里没有答案 → 弱信号」这条控制项成立）。引擎探针另打印 GraphMemix 式可达性分层（Direct / Recoverable / No access）与单袋 vs 多视图的有符号净恢复 Δ、目标排名——正是这次测量把多视图 max-pool 挡在默认路径之外（docs/memory/retrieval-v3.md §7.2）。真实会话 E2E 共 5 个用例（含「无答案不编造」「改写重试」行为验证）。
版本：0.8.1（试做型；记忆架构未经长期使用测试，会继续演进）。

隐私与安全

全部本地运行：服务绑定 127.0.0.1，记忆是 vault 内 markdown，历史会话索引不出本机。

License

MIT

dsh-math-memory

安装

源码

标签

作者

说明文档