| 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
- 权威层优先：
raw/ 永远是 source of truth，wiki/ 是可重建的派生层
- 探索即积累：每次 ask/maintain 的产出回灌系统，而非一次性消耗
- 隔离晋升：agent 产物默认不可信，只有显式 promote 才能跨越边界
- 主库联动：隔离保护"写入"，但"读取"方向开放——主 vault 的已有知识可拉入增强
硬规则
raw/ 永远视为权威层wiki/ 永远视为派生层，不得伪装成原始来源outputs/ 默认不可信，只是任务结果curated/ 才是可考虑长期保留的层- 不允许直接把 agent 产物写入个人主 vault
- 所有非平凡断言必须可回链到 source manifest 或 raw 文档
- schema 保持简单扁平，让 LLM 轻松读懂
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 文件中。
每次命令执行前：
- 读
.active_workspace 确定目标 workspace
- 读该 workspace 的
AGENTS.md 获取 schema 和状态
- 如果用户明确提到了项目名（如"在 X 里查"），临时切换
- 无活跃 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。
两阶段架构：
- 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>
- 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 直接执行。
- 读
wiki/indexes/ 定位相关 wiki 页面
- 读相关 wiki 页面（需要时回读 raw 来源验证）
- 生成回答：
md（默认）→ outputs/answers/marp → outputs/slides/（read references/marp-template.md 获取模板）chart → outputs/charts/（生成 matplotlib 脚本 + PNG）
- wiki 回灌：检查回答中是否包含新概念、新洞察或新关联：
- 如有：先展示将要修改的 wiki 页面 diff（增/删/改行），确认后再写入
- 新建页面不需要 diff，直接写入
- 回灌内容来源标注使用
(ASK-YYYY-MM-DD) 格式，与来源文件 (SRC-NNNN) 区分
- 更新 master_index.md
- 运行
python scripts/log_entry.py <workspace> ask "<问题摘要，输出类型>" 记录
- 产出后提示："此结果已回灌至相关 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 获取污染控制规则和晋升条件。
