dsh-mindvault
v0.2.2
Published
Multi-workspace knowledge & memory system for DeepSeek Harness. v0.2 adds the governance layer: batch knowledge extraction from workspace docs into the vault, frontmatter validation (broken links, orphans, duplicates, core budget), and a dry-run cleanup p
Maintainers
Readme
dsh-mindvault
面向 DeepSeek Harness 生态的多工作区知识与记忆系统(零运行时依赖,仅 Node 内置模块)。
- v0.1 先期:收集、存储、保存——扫描多个工作区的构建产物与文档资产;把知识与记忆写成 Markdown 页面(frontmatter:title / summary / layer / added / related / sources),存入 core / wiki / raw 三层 vault
- v0.2 中期:治理、管理——批量从工作区文档提炼知识页入库(内容哈希去重)、vault 规范校验(断链/孤页/重复/core 字数)、dry-run 清理计划(只列不删)
后续版本沿「记忆治理(蒸馏衰减、冲突检测)→ 后期查询利用复用(倒排检索、双链图谱、上下文组装)」演进,见 RoadMap。
- 源码:https://github.com/geeklei/dsh-plugins/tree/main/dsh-mindvault
- npm:https://www.npmjs.com/package/dsh-mindvault
- 协议:MIT
功能说明
六个工具:
| 工具 | 作用 | 关键能力 |
|---|---|---|
| scan_artifacts | 扫描单个工作区的产物与文档资产 | 22 种已知产物目录分类(deps/build/cache/test/env)、不下钻产物内部、剪枝 .git、跳过符号链接防环、文件预算防失控(默认 20 万)、陈旧度(mtime 距今天数) |
| asset_report | 多工作区(1~8 个)横向对比报告 | 工作区总览表、各工作区 Top 产物、同名产物跨工作区分布、文档类型分布,CJK 对齐纯文本 |
| mem_save | 记忆页写入三层 vault | create / append / patch(原文唯一匹配替换)三种写入;core 层正文 ≤3000 字护栏;标题自动净化;related/sources 双链与溯源字段;路径越界防护 |
| ingest_docs | 知识提取:批量文档 → 知识页 | 标题取 H1(否则文件名)、自动摘要、sources 指向原文件、正文哈希跨库去重、剪枝产物与 vault 自身、max_files 上限 |
| validate_vault | vault 规范校验与治理体检 | frontmatter 必填字段、layer 与目录一致性、日期格式、标题文件名一致、related 断链、wiki 孤页(无入链无溯源)、重复内容页、core 字数护栏 |
| clean_plan | dry-run 清理计划(永不删除) | 产物按风险分级(缓存/测试=低风险、构建=中风险、依赖=可重装)+ 陈旧标记 + 可回收体积估算;vault 空页与重复页合并建议 |
三层 vault 结构(默认 .mindvault/,可配置):
.mindvault/
├── core/ # 每轮必读的核心短规则(正文 ≤3000 字符)
├── wiki/ # 主题知识页(默认层)
└── raw/ # 溯源凭证(来源指针与摘要,不存全文)安装
# 从 npm 安装
dsh plugin --profile web add dsh-mindvault# 本地开发调试(Debug patch):新建 debug.patch.yml
# - insert:
# - id: mindvault
# name: "E:/dsh-plugins/dsh-mindvault/index.js"使用说明
1. scan_artifacts —— 扫描单个工作区
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| root | string | 必填 | 工作区根目录 |
| max_depth | number | 6 | 非产物目录最大下钻深度(1~20) |
| stale_days | number | 30 | 陈旧判定阈值(天) |
| top | number | 10 | 返回体积最大的前 N 个产物 |
返回 JSON:产物列表(分类/体积/文件数/mtime/陈旧天数)、文档资产分类型汇总、陈旧产物清单。
2. asset_report —— 多工作区对比报告
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| roots | string[] | 必填 | 1~8 个工作区根目录 |
| stale_days | number | 30 | 陈旧判定阈值 |
| top | number | 5 | 每工作区列出的最大产物数 |
输出 CJK 对齐文本报表:总览 → 各工作区 Top 产物 → 同名产物分布 → 文档类型分布。
3. mem_save —— 记忆页写入
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| title | string | 必填 | 页面标题(净化为文件名,去路径分隔符与非法字符,≤80 字符) |
| content | string | create/append 必填 | 页面正文 |
| layer | string | "wiki" | core / wiki / raw |
| vault | string | .mindvault | vault 根目录 |
| action | string | "create" | create / append / patch |
| summary | string | 无 | 一句话摘要(写入 frontmatter) |
| old_content | string | patch 必填 | 被替换原文(须在页面中唯一匹配) |
| related | string[] | 无 | 相关页面(双链) |
| sources | string[] | 无 | 溯源来源,如 raw/页面名#条目 |
写入的页面示例:
---
title: SQLite 优化笔记
summary: 索引与事务要点
layer: wiki
added: 2026-10-18
related: [wiki/数据库]
sources: [raw/笔记#条目一]
---
正文第一段。4. ingest_docs —— 批量知识提取
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| root | string | 必填 | 要提取的工作区目录 |
| vault | string | .mindvault | vault 根目录 |
| layer | string | "wiki" | 目标层(wiki / raw,core 不接受批量导入) |
| exts | string[] | [".md", ".txt"] | 提取的扩展名(v0.2 白名单:.md / .markdown / .txt) |
| max_files | number | 100 | 最多处理文件数(1~1000) |
提取规则:标题取正文首个 H1(否则文件名),摘要取首个正文段落(截断 100 字符),正文原样保留;sources 指向原文件;正文哈希跨库去重——同内容不重复入库;同名页面自动避让(追加 -2、-3)。遍历时剪枝产物目录与 .git,跳过 vault 自身。
5. validate_vault —— vault 治理体检
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| vault | string | .mindvault | vault 根目录 |
检查项(只读):frontmatter 必填字段(title/layer/added)、layer 与目录一致性、added 日期格式、标题与文件名一致性、related 断链、wiki 层孤页(无入链且无溯源)、重复内容页(正文哈希成对)、core 层字数护栏。输出文本报告,零问题时显示「全部通过 ✓」。
6. clean_plan —— dry-run 清理计划
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| scope | string | "all" | all / artifacts / vault |
| roots | string[] | scope 含 artifacts 时必填 | 产物扫描的工作区目录 |
| vault | string | .mindvault | vault 根目录 |
| stale_days | number | 30 | 陈旧判定阈值 |
产物部分按风险分级:cache/test = 低风险(可再生)、build/env = 中风险(可再生,确认后删)、deps = 可重装;陈旧产物单独标记,并汇总「预计可回收」体积。vault 部分列出空页(正文 <10 字符)与重复内容页的合并建议(保留最新)。本工具永不执行删除,删除由人工确认后自行执行。
典型场景
- 磁盘清理前盘点:"扫一下 E:/proj-a 和 E:/proj-b 有哪些构建产物、多大、多久没动了"——
asset_report一次给出横向对比,陈旧产物一目了然,人工确认后自行删除 - 多仓库体积对比:8 个微服务仓库谁最臃肿、node_modules 合计多少——同名产物跨工作区分布直接给答案
- 给 AI 装记忆:让 Agent 把本次会话的结论
mem_save成 wiki 页;偏好与铁律存 core 层(≤3000 字自动护栏);资料出处存 raw 层。换会话后读回 vault 即可接续上下文 - 批量知识入库:仓库里几十篇设计笔记(md),
ingest_docs一条命令全部提炼成带 frontmatter 的知识页,重复内容自动跳过;再用validate_vault体检断链与孤页 - 知识库起步:vault 就是纯 Markdown 目录树,可以直接用 Obsidian 打开浏览,后续版本在此基础上加检索与图谱
安全边界
- 全部只读或只写自己的目录:
scan_artifacts/asset_report纯只读;mem_save只在 vault 目录内写文件 - 永不删除:包括 v0.2 的
clean_plan在内全部工具只列清单不删任何文件;删除由人工确认后自行执行 - 批量导入不碰 core:
ingest_docs拒绝写入 core 层(核心记忆须人工精炼),且白名单外扩展名、超量文件、超大文档(>200KB)均拒绝 - 路径越界防护:标题净化去掉路径分隔符与
..,页面路径强制校验落在 vault 内 - core 层护栏:正文超 3000 字符拒绝写入,防止核心记忆膨胀
- 遍历防护:不跟随符号链接(防环)、剪枝 .git、产物目录不下钻、20 万文件预算上限(超出标记
truncated) - patch 唯一匹配:old_content 匹配 0 处或多处都拒绝,不做模糊替换
版本说明
v0.2.1(2026-10-20)
- 修复:数值参数 schema 误声明为
type:"string",真实 dsh-tools 包装层下运行时会报"须为数字"——全部改为type:"number"(先例:dsh-sql-query),execute 内加字符串数字防御转换 - 与 dsh-qrcode-gen 同日发现同类问题,一并修正
v0.2.0(2026-10-18)
- 中期「治理、管理」第一站:知识提取与整理
ingest_docs:批量文档 → 知识页(标题/摘要/正文自动提炼,正文哈希去重,同名避让,sources 溯源)validate_vault:vault 体检(frontmatter 规范、断链、孤页、重复内容、core 字数护栏)clean_plan:dry-run 清理计划(产物风险分级 + 陈旧标记 + 可回收估算;vault 空页/重复页合并建议),永不删除- 184 项测试断言全绿;v0.1 全部 115 项断言保留兼容
v0.1.0(2026-10-18)
- 首个版本:三阶段演进路线的先期「收集、存储、保存」层
scan_artifacts:22 种产物分类规则、陈旧度启发式、文档资产统计asset_report:多工作区对比报表(总览/Top 产物/同名分布/类型分布)mem_save:三层 vault 记忆页写入(create/append/patch),frontmatter 规范- 115 项测试断言全绿;零运行时依赖
RoadMap
- v0.3 记忆治理(中期):raw → wiki 蒸馏辅助、core 常驻页维护、冲突检测(同一事实多种说法)、断链/孤儿页检测、容量与时间衰减(
mem_gc) - v0.4 检索与图谱(后期):
mem_search倒排索引 + CJK bigram、双链解析(related/backlinks)、mem_graph - v0.5 跨工作区复用(后期):按主题组装上下文包、模板复用、Obsidian 兼容导出
其他插件集成说明
- dsh-xlsx-lite / dsh-markdown-render:
mem_save的正文可由这两个插件生成——xlsx 读出来的表格、Markdown 渲染前的原稿,都可以作为知识页内容存入 vault - dsh-sql-query:vault 是 Markdown 文件树,配合 sql-query 对结构化清单做分析;后续版本将提供结构化索引
- dsh-fulltext-index(四期 D11):未来
mem_search的倒排索引与其同源;D11 也可直接对 vault 目录建索引,两者互补 - dsh-file-search:内容级 grep 检索可直接作用于 vault;mindvault 后续提供的是"带评分与双链"的记忆检索,维度不同
- dsh-credential-scan:vault 若要进 git,建议先跑一遍密钥扫描,防止敏感信息入库
FAQ
Q: 与 dsh-memory 类插件(KV 记忆/语义检索)的区别? A: 生态里已有多个"存取记忆"插件(扁平 KV、向量检索、FTS5 文档库)。dsh-mindvault 定位是记忆治理层:分层结构(core/wiki/raw)、frontmatter 规范、双链与溯源、先收集再治理再复用的演进路线。纯 Markdown 存储,无 embedding API、无向量库、无 Python 依赖。
Q: vault 放在哪里?
A: 默认 .mindvault/(相对工作目录)。建议放工作区根目录并纳入 git;也可以指定到独立目录供多工作区共享。
Q: 为什么 core 层限 3000 字? A: core 层的设计语义是"每轮必读的短规则"。太长的核心记忆会稀释注入价值,长内容应拆去 wiki 层并在 core 里留指针。
Q: 扫描大仓库会慢吗?
A: 产物目录(node_modules 等)只做整体统计不下钻文件树;非产物目录按 max_depth 剪枝;全局限 20 万文件预算,超出会标记 truncated 而不是死循环。
Q: patch 模式失败怎么办? A: 报错会说明是"未找到"还是"匹配多处"。多处匹配时请加长 old_content 片段使其唯一;找不到时先读取页面确认当前内容。
Q: 生成的报告是 Markdown 表格吗?
A: 是 CJK 对齐的纯文本表格(scan_artifacts 输出 JSON),可直接贴进会话或存为 wiki 页。
许可证
MIT
