Imported from AlphaMao1/kk-vault (SKILL.md). Install upstream with npx skills add AlphaMao1/kk-vault. Copyright stays with the author.

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

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 直接输出下表：

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]

子命令：

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

外部依赖

目录契约

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

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