Metadata-Version: 2.4
Name: obsidian-vault-pipeline
Version: 0.7.0
Summary: 全自动Obsidian知识管理Pipeline - 生产级知识管理流水线
Project-URL: Homepage, https://github.com/fakechris/obsidian_vault_pipeline
Project-URL: Documentation, https://github.com/fakechris/obsidian_vault_pipeline#readme
Project-URL: Repository, https://github.com/fakechris/obsidian_vault_pipeline
Project-URL: Issues, https://github.com/fakechris/obsidian_vault_pipeline/issues
Author-email: OpenClaw <openclaw@example.com>
License-Expression: MIT
License-File: LICENSE
Keywords: evergreen,knowledge-management,llm,markdown,moc,obsidian,pipeline,zettelkasten
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Groupware
Classifier: Topic :: Text Processing :: Markup
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.21.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: feedparser>=6.0.0
Requires-Dist: litellm>=1.0.0
Requires-Dist: networkx>=3.0
Requires-Dist: openai>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.28.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: watchdog>=3.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

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

# Obsidian Vault Pipeline

<div align="center">

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/obsidian-vault-pipeline.svg)](https://pypi.org/project/obsidian-vault-pipeline/)

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

[🇬🇧 English](README_EN.md)

</div>

## 这是什么

这不是一个“多脚本拼装包”，而是一套围绕 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` 现在到底跑什么

默认完整流程：

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

带整形批处理：

```text
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` 现在到底跑什么

默认实时链路：

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

启用整形：

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

这会把链路变成：

```text
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` | 禁用自动提交 |

## 目录结构

```text
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 读取
- 审计事件浏览
- 工具发现与只读服务

## 快速开始

```bash
pip install obsidian-vault-pipeline

mkdir -p my-vault
cd my-vault

ovp --check
ovp --full
```

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

```bash
ovp --full --with-refine
```

如果你要开守护进程：

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

## 配置

在 vault 根目录放 `.env`：

```bash
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](https://github.com/fakechris/obsidian_vault_showcase)
- [PyPI](https://pypi.org/project/obsidian-vault-pipeline/)
- [Karpathy LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)

---

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