obsidian-vault-pipeline 0.7.0

全自动Obsidian知识管理Pipeline - 生产级知识管理流水线

---

schema_version: "1.0.0" note_id: readme-dc2a69e8 title: "Obsidian Vault Pipeline" description: "六层 Obsidian 知识流水线" date: 2026-04-07 type: meta

Obsidian Vault Pipeline

面向 Obsidian Vault 的生产级知识流水线
Ingest → Interpret → Absorb → Refine → Canonical → Derived

🇬🇧 English

这是什么

这不是一个“多脚本拼装包”，而是一套围绕 Obsidian Vault 构建的知识编排系统：

• 输入层负责接收 Pinboard、Clippings、Raw Markdown
• 解释层负责生成深度解读
• 吸收层负责把解读编入 Evergreen 生命周期
• 整形层负责 cleanup / breakdown
• 规范层负责 registry / alias / Atlas / MOC
• 派生层负责 knowledge.db、graph、lint、daily delta

当前版本已经把这 6 层真正接入到了日常运行链路里：

• ovp --full 默认跑到 knowledge_index
• ovp --full --with-refine 会在 moc 后追加 refine
• ovp-autopilot 默认实时跑 absorb -> moc -> knowledge_index
• ovp-autopilot --with-refine 会在实时链路里追加 refine

真实运行模型

Source of Truth

这套系统当前坚持以下边界：

• canonical truth：Vault Markdown + concept registry
• derived views：Atlas、MOC、graph、knowledge.db、lint、daily delta
• 不是 source of truth：knowledge.db

knowledge.db 是借鉴 GBrain 思路加入的派生索引层，用来承载：

• FTS 页面索引
• 结构化链接
• raw sidecar 镜像
• timeline / audit 事件
• deterministic section embeddings
• 只读 query / serve 接口

它可以被重建，不参与 canonical 身份决策。

六层职责

层	职责	代表命令	是否允许 LLM 直接做重大判断
Ingest	采集并规范化输入	ovp --step pinboard ovp --step clippings ovp-article	否
Interpret	把输入变成深度解读	ovp-article ovp-github ovp-paper	是，但输出受格式约束
Absorb	把解读编入概念生命周期	ovp-absorb ovp-evergreen	是，但要输出结构化结果
Refine	对现有知识页做 cleanup / breakdown	ovp-cleanup ovp-breakdown	是，但执行受控
Canonical	维护 registry / alias / Atlas / MOC	ovp-rebuild-registry ovp-moc ovp-promote-candidates	否
Derived	派生检索、图谱和检查	ovp-knowledge-index ovp-graph ovp-lint	否

ovp --full 现在到底跑什么

默认完整流程：

pinboard
→ pinboard_process
→ clippings
→ articles
→ quality
→ fix_links
→ absorb
→ registry_sync
→ moc
→ knowledge_index

带整形批处理：

pinboard
→ pinboard_process
→ clippings
→ articles
→ quality
→ fix_links
→ absorb
→ registry_sync
→ moc
→ refine
→ knowledge_index

关键点：

• absorb 现在走的是 openclaw_pipeline.commands.absorb
• refine 是 cleanup + breakdown 的批处理包装
• knowledge_index 永远放最后，保证 knowledge.db 反映最终 canonical 状态
• --step evergreen / --from-step evergreen 仍然接受，内部会映射到 absorb

ovp-autopilot 现在到底跑什么

默认实时链路：

interpretation
→ quality
→ absorb
→ moc
→ knowledge_index
→ auto_commit(optional)

启用整形：

ovp-autopilot --watch=inbox --with-refine --yes

这会把链路变成：

interpretation
→ quality
→ absorb
→ moc
→ refine
→ knowledge_index
→ auto_commit(optional)

默认不打开 refine 的原因不是“还没接上”，而是为了避免每来一篇新内容就自动重写全库结构；现在它已经接进编排，但需要显式 opt-in。

命令速览

日常主入口

命令	说明
ovp --check	检查运行环境
ovp --full	完整日常流水线
ovp --full --with-refine	完整流水线 + cleanup/breakdown
ovp --step absorb	单独跑吸收层
ovp --step refine	单独跑批处理整形
ovp --from-step absorb	从吸收层之后继续跑

内容处理

命令	说明
ovp-article --process-inbox --vault-dir <vault>	处理 Raw 文档
ovp-github --process-single <file> --vault-dir <vault>	处理 GitHub 类型输入
ovp-paper --process-single <file> --vault-dir <vault>	处理论文类型输入

Absorb / Refine / Canonical

命令	说明
ovp-absorb --recent 7 --json	吸收最近解读
ovp-evergreen --recent 7 --json	ovp-absorb 的兼容别名
ovp-cleanup --all --json	生成 cleanup proposal
ovp-cleanup --all --write --json	执行确定性 cleanup
ovp-breakdown --all --json	生成 breakdown proposal
ovp-breakdown --all --write --json	执行增量 breakdown
ovp-rebuild-registry --json	对账 Evergreen 与 registry
ovp-promote-candidates review	审核 candidate 生命周期
ovp-moc --scan --vault-dir <vault>	更新 MOC / Atlas

Derived 层

命令	说明
ovp-knowledge-index --json	重建 knowledge.db
ovp-knowledge-index --search "query" --json	FTS 搜索
ovp-knowledge-index --query "question" --json	embedding chunk query
ovp-knowledge-index --get slug --json	读取 canonical 页面
ovp-knowledge-index --stats --json	查看索引统计
ovp-knowledge-index --audit-recent --json	查看最近审计事件
ovp-knowledge-index --tools-json	输出工具发现 JSON
ovp-knowledge-index --serve	启动只读 stdio JSONL 服务
ovp-graph daily today --vault-dir <vault>	生成 daily delta
ovp-lint --check --vault-dir <vault>	运行链接/结构检查

AutoPilot

命令	说明
ovp-autopilot --watch=inbox --parallel=1 --yes	默认实时链路
ovp-autopilot --watch=inbox,pinboard --yes	同时监听多个来源
ovp-autopilot --with-refine --yes	在实时链路追加 refine
ovp-autopilot --no-commit --yes	禁用自动提交

目录结构

vault/
├── 50-Inbox/
│   ├── 01-Raw/
│   ├── 02-Pinboard/
│   └── 03-Processed/
├── 10-Knowledge/
│   ├── Evergreen/
│   └── Atlas/
│       ├── Atlas-Index.md
│       ├── concept-registry.jsonl
│       └── alias-index.json
├── 20-Areas/
│   └── {AI-Research, Investing, Programming, Tools}/Topics/YYYY-MM/
├── 60-Logs/
│   ├── pipeline.jsonl
│   ├── refine-mutations.jsonl
│   ├── transactions/
│   ├── quality-reports/
│   ├── daily-deltas/
│   └── knowledge.db
└── 70-Archive/

knowledge.db 提供什么

knowledge.db 是可重建的本地派生索引，当前包含：

• pages_index
• page_fts
• page_links
• raw_data
• timeline_events
• audit_events
• page_embeddings

它由 ovp-knowledge-index 重建，供以下读取场景使用：

• 关键词搜索
• embedding 检索
• canonical slug 读取
• 审计事件浏览
• 工具发现与只读服务

快速开始

pip install obsidian-vault-pipeline

mkdir -p my-vault
cd my-vault

ovp --check
ovp --full

如果你要显式看到整形层：

ovp --full --with-refine

如果你要开守护进程：

ovp-autopilot --watch=inbox --parallel=1 --yes

配置

在 vault 根目录放 .env：

AUTO_VAULT_API_KEY=your_key_here
AUTO_VAULT_API_BASE=https://api.minimaxi.com/anthropic

# Optional
PINBOARD_TOKEN=username:token
HTTP_PROXY=http://127.0.0.1:7897

设计原则

• 先保证身份系统一致，再增加功能
• registry 与文件系统共同定义 canonical 状态
• knowledge.db 只做 derived retrieval，不做第二真相源
• 吸收是日常自动化的一部分；整形是强能力，但默认 opt-in
• 文档必须描述“现在真实能跑的东西”，不是未来路线图

相关资源

• Showcase Vault
• PyPI
• Karpathy LLM Wiki

---

当前文档对应版本：v0.7.x