alphamao1 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-converterskill 转换 - 运行
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/（readreferences/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 获取污染控制规则和晋升条件。