DISTILL PROJECT / KNOWLEDGE GRAPH RUNTIME / v6

distill-vault

Graph-powered knowledge base runtime for Obsidian-compatible vaults

把你的 Obsidian 知识库变成可查询、可分析、可视化的知识图谱
+ 平台差异化 Skill 分发系统（Hermes / Codex / Claude 三端一键同步）

查看 GitHub 仓库 Quick Start

Objects

274

Markdown Files

342

Pipeline

0.70s

0.66s

为什么是 distill-vault

distill-vault 不是另一个笔记应用，而是一层知识运行时：读取兼容 Obsidian 的 vault，建立对象、关系、社区和查询能力，让你的知识库从静态文件系统升级成可搜索、可分析、可视化的图谱系统。

它服务的是 Distill 的核心目标：把日常积累的碎片知识，转成可被 AI 和人共同操作的结构化资产。

核心能力

6-Phase Pipeline DAG

Scan → Parse → Graph → Analyze → Promote → Export。Kahn 拓扑排序 + 增量执行（内容哈希 checkpoint）+ Worker Pool 并行解析，让大规模 vault 也能秒级重建索引。

KuzuDB 知识图谱

Object 节点 + wikilink / frontmatter 边，落入原生图数据库。支持 Cypher 查询、社区发现、影响分析，不是模拟图，是真图结构。

BM25 + TF-IDF 混合搜索

BM25 关键词、TF-IDF cosine、RRF-fused hybrid 三种模式，精确命中和模糊理解之间自由切换。当前不含 embedding / 向量搜索，适合结构化知识库查询。

社区发现 & 影响分析

Label-propagation 聚类自动识别主题社区；BFS 上下游风险传播分析，判断一条知识改动后会波及哪里（LOW → CRITICAL）。

MCP 集成（16 Tools · ✅ Stable）

通过 JSON-RPC 2.0 暴露 16 个工具（99 个测试覆盖协议层、工具层和端到端集成），Claude、Cursor、Hermes 等 Agent 直接把 vault 当作运行时知识后端查询、分析、修改。

Git 自动化钩子 · ✅ Stable

distill hook install 一键安装 pre-commit / post-commit / post-merge 钩子；distill commit 一键完成 lint → add → commit → pipeline → push。Hooks 默认不安装，需手动 opt-in；pre-commit 仅阻断 staged error-level issues，warning 只提示不拦截；出问题时 distill hook uninstall 一键清除。

Canonical Skill Specs + Platform Renderers · ✅ Stable

一个 canonical spec → 三种平台差异化产物。Hermes（YAML frontmatter）、Codex（纯 instruction markdown）、Claude（@-metadata 注释），一键 install --to all / reconcile --to all。不是三份手写文档，是一个源头三种格式。79 个测试覆盖 spec 解析、三端渲染、安装校验、drift 修复全链路。

Skill Lifecycle CLI

skill list 发现 → skill export 渲染 → skill install 部署 → skill verify 校验 → skill doctor 诊断 → skill reconcile 修复。完整的 skill 生命周期管理，支持 --format json 接入 CI。

这轮产品收口解决了什么

v6 · Platform Renderers

一个源头，三种格式

不再所有平台出同一份文档。Hermes 读 YAML frontmatter + 本地化章节，Codex 读纯 instruction markdown，Claude 读 @-metadata 注释 + 精简编号规则。语义一致，结构各异。install --to all 和 reconcile --to all 一键同步三个平台。

v5 · Reconcile State Machine

修复有了确定性路径

missing → install、drift → update、ok → noop。不再是"重新装一遍看看"，而是先诊断状态，再走确定性转移。JSON 模式区分 after（已写入）和 desired_after（dry-run 计划）。

v4 · Doctor

跨平台诊断一目了然

一条命令看 hermes / codex / claude 三个平台的 skill 健康状态：ok、drift、missing。退出码非零即有异常，可接入 CI。

Deterministic Export

Pipeline 产物可复现

导出产物不再包含时间戳、随机顺序等不确定字段。连续两次 distill run 输出完全一致——对 CI 和 diff review 来说这是硬性要求。

Obsidian 真实场景降噪

pseudo-link（如 GitHub:、站点:）、兼容层引用以及 .html / 图片 / 文档等附件型链接，不再被误报成 broken object link。健康检查开始反映真实问题。

Orphan 语义分层 + Frontmatter 收敛

orphan 区分 true_orphan 和 system_doc；frontmatter 检查默认只压对象层文件，系统/运维文档不再被当脏数据。

架构图

                    ┌──────────────────────────────────┐
                    │       CLI / Web / MCP / Skill     │
                    └────────────┬─────────────────────┘
                                 │
                    ┌────────────▼─────────────────────┐
                    │        Pipeline DAG Engine        │
                    │  (Kahn's Topo Sort + Incremental) │
                    └────────────┬─────────────────────┘
                                 │
          ┌──────────┬───────────┼───────────┬──────────┐
          │          │           │           │          │
     ┌────▼───┐ ┌───▼───┐ ┌────▼───┐ ┌────▼───┐ ┌───▼────┐
     │  Scan  │ │ Parse │ │ Graph  │ │Analyze │ │Export  │
     │+ Hash  │ │+ Pool │ │KuzuDB  │ │+Linter │ │+Report │
     └────────┘ └───────┘ └────┬───┘ └────────┘ └────────┘
                                │
                    ┌───────────▼───────────────────────┐
                    │         KuzuDB Knowledge Graph     │
                    │  ┌────────┐    ┌────────────────┐  │
                    │  │ Object │◄──►│     Links      │  │
                    │  │ Nodes  │    │ (wikilink/fm)  │  │
                    │  └────────┘    └────────────────┘  │
                    └───────────┬───────────────────────┘
                                │
          ┌──────────┬──────────┼──────────┬──────────┬──────────┐
          │          │          │          │          │          │
     ┌────▼────┐ ┌──▼───┐ ┌───▼────┐ ┌───▼───┐ ┌───▼────┐ ┌───▼────────────┐
     │ Hybrid  │ │Comm- │ │Impact  │ │Rename │ │MCP     │ │Skill System  │
     │ Search  │ │unity │ │Analysis│ │Graph  │ │Server  │ │┌─────┐┌──────┐ │
     │BM25+TF  │ │Label │ │BFS     │ │Smart  │ │16 Tools│ ││Spec ││Render│ │
     └─────────┘ └──────┘ └────────┘ └───────┘ └────────┘ │└─────┘└──────┘ │
                                                             │  ┌─┐┌─┐┌─┐   │
                                                             │  │H││C││C│   │
                                                             │  │e││o││l│   │
                                                             │  │r││d││a│   │
                                                             │  │m││e││u│   │
                                                             │  │e││x││d│   │
                                                             │  │s││  ││e│   │
                                                             │  └─┘└─┘└─┘   │
                                                             └───────────────┘

Quick Start

快速上手

git clone https://github.com/okbexx/distill-vault.git
cd distill-vault
pip install -e .
cd ~/my-obsidian-vault
distill status            # vault 概览
distill run               # 构建图谱（首次）
distill search "知识管理" --mode hybrid
distill lint --fix        # 检查并自动修复
distill health            # 完整健康报告

从源码开发（贡献者）

git clone https://github.com/okbexx/distill-vault.git
cd distill-vault
pip install -e ".[dev]"
python -m pytest tests/ -q -n 4    # 验证 97/97 测试通过

# 进入你的 Obsidian vault
cd ~/my-vault

# 查看 vault 概览
distill status

# 运行完整 6 阶段 pipeline
distill run

# 混合搜索
distill search "Agent工作流" --mode hybrid

# Lint 并自动修复
distill lint --fix

# 增量检查（staleness）
distill run --incremental

# ── Skill 分发（v6 新增）──

# 查看可用 skill
distill skill list

# 渲染 skill 为目标平台格式
distill skill export my-skill --to hermes
distill skill export my-skill --to codex
distill skill export my-skill --to claude

# 一键安装到所有平台
distill skill install my-skill --to all

# 跨平台诊断
distill skill doctor

# 检测 drift 并一键修复
distill skill reconcile my-skill --to all

# ── 可视化 & MCP ──

# 启动 Web UI（✅ Stable — 46 tests + 8 API endpoints）
distill web --port 8420

# 启动 MCP server（供 AI Agent 调用）
python -m distill.mcp_server --vault ~/my-vault

CLI 命令速查

Command	Description
distill status	Vault overview & statistics
distill index [--watch]	Build/rebuild index
distill lint [--fix]	Check/fix structural issues
distill health	Full health report
distill search QUERY [--mode hybrid]	Search objects
distill promote [--dry-run]	Show/apply promotions
distill run [--watch] [--incremental]	Full 6-phase pipeline
distill web [--port 8420]	Start Web UI
distill init NAME	Create new vault from template
distill hook install	Install git hooks
distill hook uninstall	Remove distill-managed hooks
distill hook status	Show hook installation status
distill commit MSG [--push] [--no-lint]	Lint → add → commit → pipeline → push
distill skill list	List canonical skill specs
distill skill export NAME [--to hermes\|codex\|claude]	Render skill for target platform
distill skill install NAME [--to hermes\|codex\|claude\|all]	Install skill to target platform(s)
distill skill reconcile NAME [--to all] [--dry-run]	Detect drift & repair
distill skill doctor	Cross-platform health check
distill skill verify NAME	Validate installed skill integrity

所有命令均支持 --format json 输出机器可读格式。

MCP Tools（16 个）

Tool	Description
vault_status	Vault overview & graph stats
vault_staleness	Check if index is stale
search	Hybrid search (BM25 + TF-IDF + RRF)
cypher_query	Run Cypher queries on the graph
object_context	360° view of an object (in/out refs)
list_objects	List/filter vault objects
impact_upstream	What depends on this object?
impact_downstream	What does this object depend on?
detect_changes	Analyze uncommitted changes
community_detect	Run community detection
community_info	Get community details
rename	Graph-assisted smart rename
lint_check	Check for issues
lint_fix	Auto-fix issues
pipeline_run	Trigger pipeline execution
pipeline_status	Get pipeline status

实测数据

Real Vault Benchmark

342 md files · 274 objects
Pipeline: 0.70s · Search: 0.66s

Test Suite

97/97

全部通过 · 覆盖 pipeline / skill / CLI / platform renderers

GitHub Actions
Python 3.10 / 3.11 / 3.12

边界与限制

Limitations

搜索基于 BM25 + TF-IDF cosine，不含 embedding / 向量搜索
单 vault 模式，不支持多 vault 联邦查询
KuzuDB 嵌入式，非 client-server 架构
推荐规模：1,000–5,000 markdown 文件
仅兼容 Obsidian 格式（wikilink + frontmatter）
Watch mode 实验性功能，需 watchdog

Non-goals

不替代 Obsidian 或任何编辑器
不是通用图数据库
不替代 Obsidian 插件生态
不含内置 LLM / AI 调用
不支持实时同步到图谱

distill-vault 的目标不是替代 Obsidian，而是给 Obsidian 增加一层图计算与 Agent 可调用的知识运行时。