kk-vault

name	kk-vault
description	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'。

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 获取污染控制规则和晋升条件。