kb/README.md

# KB — Personal Knowledge Base

> LLM 驱动的第二大脑。原则：**默认全存，人类筛选，Agent 编译。**
>
> 不再依赖 Obsidian，不再需要 Notion。就是一堆 markdown 文件 + git。

## 这是什么

KB 是一个三层知识管理系统：

```
你分享的任何东西 → raw/ (自动保存) → wiki/ (编译后的知识)
                       ↑                        ↑
                   Agent 即时写入          Agent + 你一起消化
```

- **raw/** — 源材料。你看过的每篇文章、分享的每个链接、聊过的每个话题，都存在这里。按月分桶，永久保留。
- **wiki/** — 编译后的知识。从 raw 中提炼出的结构化笔记：投资 thesis、技术 runbook、决策日志。
- **SCHEMA.md** — 约定和规范。告诉 Agent（和你）怎么写页面、用什么 tag。

## 目录结构

```
kb/
├── README.md              # 你正在看的
├── SCHEMA.md              # 约定：tag、frontmatter、模板
├── log.md                 # 操作日志（谁在什么时候做了什么）
│
├── raw/                   # 层1 — 不可变源材料
│   ├── links/             #   从 Links App 每日自动同步的新闻
│   └── YYYY-MM/           #   手动分享的文章、网页、对话提取
│
├── wiki/                  # 层2 — 编译后的知识
│   ├── investing/         #   投资：thesis、分析、税务
│   ├── tech/              #   技术：K3s、Cloudflare、部署笔记
│   ├── life/              #   生活：钢琴、健身、墨尔本
│   └── decisions/         #   决策日志：为什么选了 A 不选 B
│
├── scripts/               # 实用脚本
└── _archive/              # 已被取代的旧页面
```

## 不需要 Hermes Agent 也能用

KB 就是 markdown 文件 + git。你可以：

- **用 VS Code 打开** → 直接浏览、搜索、编辑
- **用 rg/grep 搜索** → `rg "NVIDIA" wiki/ raw/`
- **用 GitHub 看** → github.com/wahyd4/kb
- **用 Obsidian 打开**（可选）→ 直接作为 vault，`[[wikilinks]]` 即点即用

## 核心操作

### Ingest（采集）— Agent 自动做

你分享 URL 或粘贴内容给 Hermes → Agent 抓取 → 存 `raw/YYYY-MM/YYYY-MM-DD-slug.md`

raw 文件的 frontmatter：
```yaml
---
source_url: https://example.com
ingested: 2026-07-13
status: inbox       # inbox → absorbed → skipped
---
```

### Absorb（消化）— Agent + 你

把 raw 里的源材料编译成 wiki 页面：

1. Agent 读 raw 源
2. Agent 搜 wiki/ 找相关已有页面
3. **优先更新已有页面**（不铺新页）
4. 必要时建新页面
5. 改 status → `absorbed`

```bash
# 手动 absorb 辅助：列出所有 inbox 条目
./scripts/inbox.sh

# 手动 absorb 辅助：搜索 raw 中相关内容
./scripts/search.sh "NVIDIA" raw/

# 用 Hermes: "absorb raw/2026-07/2026-07-13-nvidia-article.md"
```

### Query（查询）

```bash
# 搜索所有 KB 内容
./scripts/search.sh "关键词"

# 或直接用 ripgrep
rg "NVIDIA" ~/Code/kb/wiki/ ~/Code/kb/raw/
```

结果会标注来源类型：wiki 页面是 **已编译**，raw 条目是 **源材料待编译**。

### Lint（健康检查）

```bash
# 检查断链
./scripts/lint.sh
```

Agent 会检查：断链 wikilinks、过期投资页面、孤儿页面。

## Frontmatter 规范

### Wiki 页面

```yaml
---
title: "页面标题"
created: 2026-07-13
updated: 2026-07-13
tags: [domain/subtag]
sources: [raw/YYYY-MM/file.md]  # 来源 raw 文件
---
```

### Raw 文件

```yaml
---
source_url: https://...
ingested: 2026-07-13
status: inbox | absorbed | skipped | failed_fetch
---
```

## Tag 系统

开放前缀制 — 新 tag 直接用，不审批：

| 前缀 | 示例 |
|------|------|
| `tech/` | `infra`, `k3s`, `cf-workers`, `llm`, `agent`, `homelab` |
| `inv/` | `semi`, `cloud`, `ai`, `thesis`, `earnings`, `tax`, `valuation` |
| `life/` | `music`, `piano`, `health`, `family`, `melbourne` |

## 页面模板

### 投资 Thesis
```markdown
# [Company] Thesis
- Conviction: high/medium/low
- Thesis: 3-5 个核心理由
- Risks: 什么会打破 thesis
- Catalysts: 近期催化剂
```

### 技术 Runbook
```markdown
# [Component] Runbook
- Purpose: 干什么的
- Location: repo/namespace
- Common issues: 常见问题 + 修复
```

### 决策日志
```markdown
# [Decision]
- Date: YYYY-MM-DD
- Context: 背景
- Options: 考虑过哪些方案
- Decision: 选了哪个 + 为什么
```

## 搜索技巧

```bash
# 找所有 inbox 待处理
rg "status: inbox" raw/

# 找所有 NVIDIA 相关内容
rg -l "NVIDIA" wiki/ raw/

# 找所有投资 thesis
rg "tags:.*inv/thesis" wiki/

# 统计
./scripts/stats.sh
```

## 自动化

| 时间 | 做什么 |
|------|--------|
| 每天 06:30 | Links App → `raw/links/YYYY-MM/` 同步 |
| 每天 22:00 | Hermes 对话扫描 → `raw/YYYY-MM/` 提取知识 |
| 每周日 | Review inbox → 决定 absorb 哪些 |

## 脚本参考

```bash
# 查看 inbox
./scripts/inbox.sh                    # 列出所有待处理
./scripts/inbox.sh --count            # 只看数量
./scripts/inbox.sh --recent 10        # 最近 10 条
./scripts/inbox.sh --month 2026-07    # 只看某月

# 搜索
./scripts/search.sh "NVIDIA"                    # 全文搜索（固定字符串）
./scripts/search.sh "k3s" --wiki-only           # 只搜 wiki
./scripts/search.sh "earnings" --raw-only       # 只搜 raw
./scripts/search.sh "C\+\+" --regex             # 使用正则
./scripts/search.sh "NVIDIA" --files-only       # 只列文件名

# 标记状态
./scripts/status.sh absorb raw/2026-07/article.md   # 标记为已吸收
./scripts/status.sh skip raw/2026-07/old-news.md    # 跳过
./scripts/status.sh inbox raw/2026-07/file.md       # 重置为待处理

# 统计
./scripts/stats.sh

# 健康检查（退出码非零 = 有问题）
./scripts/lint.sh
```

## 前置依赖

- `bash` 4+
- `ripgrep` (`rg`) — `apt install ripgrep` 或 `brew install ripgrep`
- `git`

## 不依赖 Hermes 的手动操作

### 手动 Ingest（你自己加一篇文章）

1. 创建文件 `raw/YYYY-MM/YYYY-MM-DD-slug.md`
2. 写 frontmatter：
```yaml
---
source_url: https://example.com/article
ingested: 2026-07-13
status: inbox
---
```
3. 正文放下面
4. `git add` + `git commit`

### 手动 Absorb（从 raw 编译到 wiki）

1. `./scripts/inbox.sh` 看看有哪些待处理
2. 读 raw 文件，理解内容
3. 搜 wiki 找相关页面：`./scripts/search.sh "关键词" --wiki-only`
4. 编辑或创建 wiki 页面
5. `./scripts/status.sh absorb raw/路径` 标记已完成
6. 更新页面 `[[wikilinks]]` 交叉引用

### Status 生命周期

```
inbox → absorbed  (内容已编译到 wiki/)
inbox → skipped   (看过但不值得编译)
inbox → failed_fetch (链接打不开/抓取失败)
```

raw 文件标记 absorbed/skipped 后不会再出现在 inbox，但文件保留在 raw/ 中可搜索。

## 隐私

- GitHub repo = **private**
- 不含具体持仓金额、家庭隐私
- 投资页面只记录 thesis/分析框架

## 与旧 one-knowledge 的关系

`~/junv/one-knowledge` 是旧版知识库。2,815 篇 links-posts 和 19 篇 tech notes 已迁移到 KB。旧 repo 保留但不再主动更新。