# Kk Vault

> LLM 驱动的个人研究型知识库（Karpathy+kepano 方法论）。将原始来源编译为结构化 wiki，基于 wiki 做 Q&A 与健康检查，经人工认可的产物晋升到个人 Obsidian vault。触发词：'kk-vault'、'kk init'、'kk ingest'、'kk compile'、'kk ask'、'kk maintain'、'kk promote'、'kk link'、'kk help'、'研究知识库'、'知识编译'、'编译wiki'。

- Skill: `alphamao1/kk-vault` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add alphamao1/kk-vault`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alphamao1/kk-vault/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: alphamao1 (https://skillmd.com/u/alphamao1)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alphamao1/kk-vault

---


# KK-Vault

LLM 编译的个人研究知识库。数据层完全在 Obsidian 外的独立目录，防止 agent 产物污染个人 vault。

## Design Philosophy

1. **权威层优先**：`raw/` 永远是 source of truth，`wiki/` 是可重建的派生层
2. **探索即积累**：每次 ask/maintain 的产出回灌系统，而非一次性消耗
3. **隔离晋升**：agent 产物默认不可信，只有显式 promote 才能跨越边界
4. **主库联动**：隔离保护"写入"，但"读取"方向开放——主 vault 的已有知识可拉入增强

## 硬规则

1. `raw/` 永远视为权威层
2. `wiki/` 永远视为派生层，不得伪装成原始来源
3. `outputs/` 默认不可信，只是任务结果
4. `curated/` 才是可考虑长期保留的层
5. 不允许直接把 agent 产物写入个人主 vault
6. 所有非平凡断言必须可回链到 source manifest 或 raw 文档
7. schema 保持简单扁平，让 LLM 轻松读懂
8. `log.md` 是 append-only 记录，LLM 禁止手动修改此文件；各命令由脚本自动写入

## Decision Tree

| 用户意图 | 路由 |
|:---|:---|
| "命令列表" / "怎么用" / "kk help" | → **help** |
| "建一个研究库" / "kk init X" | → **init** |
| "把这个文件加到研究库" / "收录这篇" / "kk ingest" | → **ingest** |
| "编译一下" / "更新 wiki" / "kk compile" | → **compile** |
| 直接提研究问题 / "kk ask" | → **ask** |
| "检查 wiki" / "有什么遗漏" / "kk maintain" | → **maintain** |
| "晋升" / "推到主库" / "kk promote" | → **promote** |
| "关联主库" / "检索主 vault" / "kk link" | → **link** |

## Workspace 上下文

所有 workspace 存放在 base 目录下（默认 `D:\KK-Vault\`，可通过环境变量 `KK_VAULT_BASE_DIR` 覆盖），当前活跃 workspace 记录在 base 目录的 `.active_workspace` 文件中。

每次命令执行前：
1. 读 `.active_workspace` 确定目标 workspace
2. 读该 workspace 的 `AGENTS.md` 获取 schema 和状态
3. 如果用户明确提到了项目名（如"在 X 里查"），临时切换
4. 无活跃 workspace 或歧义时，列出现有 workspace 让用户选择

每次命令执行后自动打印状态行：`[kk-vault] <workspace> | 来源: N | wiki: M 页 | outputs: K`

## 命令

### help

列出所有可用命令和用法，不需要脚本，由 LLM 直接输出下表：

| 命令 | 说明 | 示例 |
|------|------|------|
| `kk help` | 显示此帮助 | `kk help` |
| `kk init <name>` | 新建研究 workspace | `kk init quantum-computing` |
| `kk init <name> --seed "<词>"` | 新建 workspace 并从主 vault 拉取种子笔记 | `kk init llm-safety --seed "LLM 安全"` |
| `kk ingest <path>` | 将文件纳入研究库 | `kk ingest ~/papers/` |
| `kk ingest --inbox` | 处理 inbox 中所有文件 | `kk ingest --inbox` |
| `kk compile` | 增量编译 wiki | `kk compile` |
| `kk compile --full` | 全量重编译 | `kk compile --full` |
| `kk ask "<问题>"` | 基于 wiki 回答研究问题 | `kk ask "transformer 的核心创新是什么"` |
| `kk ask "<问题>" --format marp` | 生成幻灯片格式 | `kk ask "..." --format marp` |
| `kk maintain` | 快速巡检 wiki 质量 | `kk maintain` |
| `kk maintain --full` | 深度巡检（含重复建议） | `kk maintain --full` |
| `kk promote <path>` | 将产物晋升到 curated/ | `kk promote outputs/answers/xxx.md` |
| `kk promote <path> --target obsidian` | 进一步推送到主 vault | `kk promote ... --target obsidian` |
| `kk link` | 检索 wiki 实体在主 vault 的关联（摘要） | `kk link` |
| `kk link --detail` | 完整关联报告 | `kk link --detail` |
| `kk link seed --topic "<词>"` | 从主 vault 拉取相关笔记到 inbox | `kk link seed --topic "注意力机制"` |
| `kk link discover` | 跨 workspace 知识关联发现 | `kk link discover` |

---

### init `<project-name>` [--seed `"<关键词>"`]

创建新研究项目 workspace。

```
python scripts/init_workspace.py <project-name> [--seed "<关键词>"]
```

- 在 `D:\KK-Vault\<project-name>\` 创建完整目录结构
- 生成 AGENTS.md（schema + 命名规则 + 来源规则）
- 设为 `.active_workspace`
- `--seed "<关键词>"`（可选）：init 完成后自动调用 `vault_bridge.py seed`，从 Obsidian 主 vault 搜索相关笔记，复制到 `raw/inbox/`，等待 ingest

---

### ingest `<path>` [--inbox]

将已有文件纳入研究库。

- `<path>` 可以是单文件或文件夹（批量处理所有支持的文件类型）
- `--inbox`：处理 `raw/inbox/` 里所有文件（快捷模式）
- 对非 .md 文件调用 `docugenius-converter` skill 转换
- 运行 `python scripts/ingest_source.py <workspace-path> <source-path>` 完成：
  - 复制原文件到 `raw/sources/`
  - 写 source manifest（ID、标题、来源URL、日期、摘要、hash）
  - 更新 `source_index.csv`
- **ingest 后**：LLM 应为每个新来源生成一句话 `summary` 并写入 manifest（直接编辑 JSON 文件即可）

---

### compile [--full]

将原始来源编译为结构化 wiki。

```
python scripts/compile_wiki.py <workspace-path> [--full]
```

默认增量（只处理新/变更来源）。`--full` 重建全部 wiki。

**两阶段架构**：
1. **Per-source pass**：逐篇读来源 → 按来源 `type` 路由到对应 prompt 变体（见 `compile-prompts.md` 类型路由表） → 提取 JSON → 写入 manifest：
   ```
   # Step 1: 把提取的 JSON 写到临时文件
   # Step 2: 调用脚本持久化
   python scripts/compile_wiki.py <workspace> --write-summary <SRC-ID> <json-file>
   ```
2. **Cross-source pass**：读所有摘要 → 生成/更新 concept pages、entity pages、theme pages → 补 backlinks → 更新 indexes
   ```
   python scripts/compile_wiki.py <workspace> --write-page <subdir> <filename> <content-file>
   python scripts/compile_wiki.py <workspace> --update-index
   ```

**compile 完成后自动触发 crossref 摘要**（见 link 命令），输出主 vault 覆盖情况摘要。
`--update-index` 完成后通过 log_entry.py 自动记录 compile 日志。

Read `references/compile-prompts.md` for page generation templates.

---

### ask `"<question>"` [--format md|marp|chart]

基于 wiki 回答研究问题。此命令不需要脚本，由 LLM 直接执行。

1. 读 `wiki/indexes/` 定位相关 wiki 页面
2. 读相关 wiki 页面（需要时回读 raw 来源验证）
3. 生成回答：
   - `md`（默认）→ `outputs/answers/`
   - `marp` → `outputs/slides/`（read `references/marp-template.md` 获取模板）
   - `chart` → `outputs/charts/`（生成 matplotlib 脚本 + PNG）
4. **wiki 回灌**：检查回答中是否包含新概念、新洞察或新关联：
   - 如有：先展示将要修改的 wiki 页面 diff（增/删/改行），确认后再写入
   - 新建页面不需要 diff，直接写入
   - 回灌内容来源标注使用 `(ASK-YYYY-MM-DD)` 格式，与来源文件 `(SRC-NNNN)` 区分
   - 更新 master_index.md
5. 运行 `python scripts/log_entry.py <workspace> ask "<问题摘要，输出类型>"` 记录
6. 产出后提示："此结果已回灌至相关 wiki 页面。是否将回答本身保留到 curated？可 `kk promote`。"

---

### maintain [--full]

巡检 wiki 的结构质量和知识缺口。

```
python scripts/maintain_check.py <workspace-path> [--full]
```

- 默认 quick：断链、无来源断言、缺失字段
- `--full`：+ 重复概念合并建议、新 article candidates、待探索问题
- 产出写入 `maintain/` 对应子目录
- 有自动修复能力的问题（如补 backlink）可选自动修复

---

### promote `<path>` [--target obsidian]

将经过验证的产物晋升。

```
python scripts/promote_artifact.py <workspace-path> <artifact-path> [--target obsidian]
```

- 默认：检查来源完整性 → 检查非噪音 → 移到 `curated/promoted/`
- `--target obsidian`：通过直接文件写入将产物放入 Obsidian 主 vault（需用户确认）

---

### link [--detail] [seed --topic `"<词>"`] [discover]

Obsidian 主 vault 与 kk-vault research workspace 的联动命令。

```
python scripts/vault_bridge.py <workspace-path> crossref [--detail]
python scripts/vault_bridge.py <workspace-path> seed --topic "<关键词>" [--max 10]
python scripts/vault_bridge.py <workspace-path> discover [--scope all|vault]
```

**子命令**：

| 子命令 | 说明 |
|--------|------|
| `kk link` | 对 wiki 所有概念/实体在主 vault 中检索，输出命中摘要 |
| `kk link --detail` | 详细报告：每个命中显示匹配笔记路径 |
| `kk link seed --topic "<词>"` | 从主 vault 搜索相关笔记 → 复制到 inbox（走 1级 wikilink 追踪） |
| `kk link discover` | 扫描所有 workspace，输出跨 workspace 共享实体/概念 + 当前 workspace 主 vault 覆盖率 |

报告写入 `maintain/findings/<date>_crossref.md` 或 `_discover.md`。

---

## 外部依赖

| 依赖 | 何时使用 |
|------|---------|
| `docugenius-converter` skill | ingest 非 .md 来源时 |
| `obsidian` CLI | link 命令检索 / promote --target obsidian 时 |
| `obsidian-markdown` skill | compile 生成 wiki 页面时参考 wikilink/callout 语法 |

## 目录契约

读 `references/schema.md` 获取完整的 workspace 目录结构、文件命名规则和 AGENTS.md schema。

读 `references/policies.md` 获取污染控制规则和晋升条件。