SwarmVault

本地优先的 LLM Wiki、知识图谱构建器和面向 AI Agent 的 RAG 知识库。 SwarmVault 将文档、代码、转录文本、笔记和 URL 转换为持久的 Markdown Wiki 以及一个可检查、可查询、可交给 Agent 的本地图谱。使用一条命令开始，当需要时再学习更深入的图谱、审查、上下文打包和自动化工作流。

网站文档目前以英文为主。如果翻译版本与原文存在措辞偏差，以 README.md 为准。

30 秒尝试

swarmvault quickstart ./your-repo

quickstart 在当前目录初始化一个 Vault，摄取本地文件、目录或公共 GitHub 仓库，编译 Wiki 和图谱，写入分享产物，并打开本地图谱查看器。它是 swarmvault scan 的初学者友好别名。

没有现成的仓库？

swarmvault demo

首次编译后，最有用的后续命令是：

swarmvault next
swarmvault query "What are the key concepts?"
swarmvault graph serve
swarmvault doctor
swarmvault candidate list

不确定 Vault 的状态？swarmvault next 是只读的，会告诉你是否需要初始化、摄取、编译、查询、审查或刷新。

首次运行不需要任何 API 密钥。内置的 heuristic 提供程序在本地离线运行。

磁盘上你会得到：

• raw/ - 摄取材料的不可变副本
• wiki/ - 生成的 Markdown 页面、保存的输出、图谱报告、上下文包和任务笔记
• state/graph.json - 机器可读的知识图谱
• state/retrieval/ - 本地搜索索引
• wiki/graph/share-card.md、wiki/graph/share-card.svg 和 wiki/graph/share-kit/ - 可复制和可视化的首次运行摘要

三层架构

SwarmVault 使用三层架构，遵循 Andrej Karpathy 描述的模式：

1. 原始源（raw/）——你精心收集的源文档集合。书籍、文章、论文、转录文本、代码、图像、数据集。这些是不可变的：SwarmVault 从中读取但从不修改。
2. Wiki（wiki/）——LLM 生成和人工编写的 Markdown。源摘要、实体页面、概念页面、交叉引用、仪表盘和输出。Wiki 是持久且不断累积的产物。
3. Schema（swarmvault.schema.md）——定义 Wiki 的结构、遵循的约定以及领域中的重要内容。你和 LLM 会随时间共同演化它。

遵循 Vannevar Bush 的 Memex（1945）传统——一个个人化的、精心策划的知识存储库，包含文档之间的关联路径——SwarmVault 将源之间的连接视为与源本身同等重要。Bush 无法解决的问题是谁来维护。LLM 负责处理。

将书籍、文章、笔记、转录文本、邮件导出、日历、数据集、幻灯片、截图、URL 和代码转化为持久的 Vault，包含知识图谱、本地搜索、仪表盘和可审查的产物，所有这些都保存在磁盘上。用于个人知识管理、研究深度挖掘、书籍伴侣、代码文档、商业智能，或任何你随时间积累知识并希望其有条理而非散乱的领域。

SwarmVault 将 LLM Wiki 模式转化为本地工具链，具备图谱导航、搜索、审查、自动化以及可选的模型支持的合成。你也可以从独立的 Schema 模板 开始——零安装，任何 LLM Agent 都可以使用——当超出其能力时再升级到完整 CLI。

为什么选择 SwarmVault

如果你喜欢 Karpathy 的 LLM Wiki gist，SwarmVault 是其生产级版本。以下是它如何解决社区最常见的担忧：

“幻觉不会累积吗？” ——每条边都被标记为 extracted、inferred 或 ambiguous。矛盾检测会标记冲突的声明。compile --approve 将所有更改暂存到可审查的审批包中。新概念首先进入 wiki/candidates/。lint --conflicts 按需审计矛盾。

“它能扩展到 100 页以上吗？” ——是的。混合搜索将 SQLite 全文搜索与语义嵌入结合，因此查询无需将每一页都放入上下文。compile --max-tokens 修剪输出以适应有界窗口。图谱导航（graph query、graph path、graph explain、graph callers）让你遍历而非搜索。

“它只适合个人使用吗？” ——基于 Git 的工作流（--commit）、监视模式与 Git 钩子、定时自动化以及 MCP 服务器使其适用于团队。Agent 集成涵盖直接规则目标以及扩展的技能包名单。

“需要 API 密钥吗？” ——不需要。内置的 heuristic 提供程序完全离线。如需更精确的提取，可搭配免费本地 LLM（通过 Ollama）。云提供商是可选的。

从 Gist 到生产级

	Karpathy 的 Gist	SwarmVault
三层架构	描述	已实现
摄取/查询/检查	手动	CLI 命令
一键设置	—	swarmvault quickstart
类型化知识图谱	—	是
交互式图谱查看器	—	是
可视化 + 可分享套件	—	是
Agent 就绪的上下文包	—	是
Agent 任务台账	—	是
Vault 诊断 + 工作台	—	是
30+ 输入格式	—	是
代码感知（tree-sitter AST）	—	是
离线/无需 API 密钥	—	是
矛盾检测	提及	自动
审批队列	—	是
Agent 集成	—	是
Neo4j / 图谱导出	—	是
MCP 服务器	—	是
监视模式 + Git 钩子	—	是
混合搜索 + 重排序	index.md	SQLite FTS + 嵌入

安装

SwarmVault 需要 Node >=24。全局 CLI 已包含图谱查看器工作流和 MCP 服务器流。最终用户无需单独安装 @swarmvaultai/viewer。

快速开始

快速路径

从空文件夹或你希望 Vault 产物存放的草稿文件夹中运行：

mkdir my-vault
cd my-vault
swarmvault quickstart ../your-repo
swarmvault next

这是新用户最简单的路径。它完成与 swarmvault scan 相同的工作：初始化 Vault，摄取本地文件、目录或公共 GitHub 仓库，编译 Wiki 和图谱，写入分享产物，并打开图谱查看器（除非你传递 --no-serve 或 --no-viz）。交互式运行会在 stderr 上显示有界的摄取进度，包括当前处理的文件，因此大型 PDF 和文档文件夹在提取运行时不会显得静默。

my-vault/
├── swarmvault.schema.md       用户可编辑的 Vault 指令
├── raw/                       不可变的源文件和本地化资源
├── wiki/                      编译后的 Wiki：源、概念、实体、代码、输出、图谱
├── state/                     graph.json、retrieval/、embeddings、sessions、approvals
├── .obsidian/                 可选的 Obsidian 工作区配置
└── agent/                     生成的面向 Agent 的辅助文件

如果你希望将生成的产物放在源代码树之外，使用 SWARMVAULT_OUT=.swarmvault-out 运行。swarmvault.config.json 和 swarmvault.schema.md 仍留在项目根目录；raw/、wiki/、state/、agent/ 和 inbox/ 会在输出目录下解析。

学习主循环

理解快速路径后，相同的工作流也可以逐步执行：

swarmvault init --obsidian --profile personal-research
swarmvault ingest ./src --repo-root .
swarmvault ingest ./meeting.srt --guide
swarmvault add https://arxiv.org/abs/2401.12345
swarmvault compile
swarmvault next
swarmvault query "What is the auth flow?"
swarmvault graph serve

当相同的仓库、文件夹或文档中心需要保持注册并支持刷新时，使用 swarmvault source add https://github.com/karpathy/micrograd、swarmvault source add https://example.com/docs/getting-started、swarmvault source list、swarmvault source reload --all 和 swarmvault source session transcript-or-session-id。对于公共 GitHub 仓库，swarmvault clone https://github.com/owner/repo --no-viz 和 swarmvault source add https://github.com/owner/repo --branch main --checkout-dir .swarmvault-checkouts/repo 是可复用的检出路径。

常用后续命令

目标	命令
查看此文件夹的下一个最佳命令	swarmvault next
运行初学者路径但不打开查看器	swarmvault quickstart ./path --no-serve
使用旧的简洁别名	swarmvault scan ./path --no-viz
检查图谱新鲜度	swarmvault graph status ./src 或 swarmvault check-update ./src
刷新代码衍生的图谱产物	swarmvault update ./src
重新计算图谱社区	swarmvault graph cluster 或 swarmvault cluster-only
打印图谱计数并验证导出	swarmvault graph stats 和 swarmvault graph validate --strict
分享首次运行摘要	swarmvault graph share --post、swarmvault graph share --svg ./share-card.svg 或 swarmvault graph share --bundle ./share-kit
导出给 Agent 或其他工具	swarmvault export ai --out ./exports/ai
构建有界的 Agent 上下文	swarmvault context build "Implement the auth refactor" --target ./src --budget 8000
记录任务历史	swarmvault task start "Implement the auth refactor" --target ./src --agent codex
基于 Vault 保持对话	swarmvault chat "How should the next agent use this vault?"
打开健康与修复指南	swarmvault doctor --repair
构建图谱导出	swarmvault graph export --report ./exports/report.html、swarmvault graph export --callflow ./exports/callflow.html、swarmvault graph export --obsidian ./exports/graph-vault 或 swarmvault graph export --neo4j ./exports/graph.cypher
合并或检查源/模块树	swarmvault tree --output ./exports/tree.html 和 swarmvault merge-graphs ./exports/graph.json ./other-graph.json --out ./exports/merged-graph.json
推送图谱数据到 Neo4j	swarmvault graph push neo4j --dry-run

想要最小化的 LLM-Wiki 启动器？swarmvault init --lite 只创建 raw/、wiki/、wiki/index.md、wiki/log.md 和 swarmvault.schema.md - 无配置、无状态、无 Agent 安装。普通的 init、quickstart、scan 和 clone 默认也不会写入 Agent 规则文件；当你需要项目本地的 Agent 指令时，运行 swarmvault install --agent <agent>。

当 Vault 位于 Git 仓库内时，ingest、compile 和 query 支持 --commit。compile --max-tokens <n> 修剪低优先级页面以适应有界上下文窗口。swarmvault ingest ./customer-call.mp3、swarmvault ingest https://www.youtube.com/watch?v=dQw4w9WgXcQ 和 swarmvault ingest --video https://example.com/product-demo.mp4 涵盖音频、YouTube 转录和视频工作流（需要相应的提供程序或辅助二进制文件）。

可选：添加模型提供程序

你不需要 API 密钥或外部模型提供程序即可开始使用 SwarmVault。内置的 heuristic 提供程序支持本地/离线的 Vault 设置、摄取、编译、图谱/报告/搜索工作流以及轻量级查询或检查默认值。

推荐：通过 Ollama + Gemma 使用本地 LLM

如果你想要完全本地的设置，并具备精确的概念、实体和声明提取，可搭配免费的 Ollama 运行时与 Google 的 Gemma 模型。无需 API 密钥。

{
  "providers": {
    "llm": {
      "type": "ollama",
      "model": "gemma4",
      "baseUrl": "http://localhost:11434/v1"
    }
  },
  "tasks": {
    "compileProvider": "llm",
    "queryProvider": "llm",
    "lintProvider": "llm"
  }
}

当你仅使用 heuristic 提供程序运行编译/查询时，SwarmVault 会显示一次通知，指向此处。设置 SWARMVAULT_NO_NOTICES=1 可静默该通知。任何其他受支持的提供程序（OpenAI、Anthropic、Gemini、OpenRouter、Groq、Together、xAI、Cerebras、openai-compatible、自定义）也可以使用。

本地语义嵌入

如需无需 API 密钥的本地语义图谱查询，使用支持嵌入的本地后端（如 Ollama）替代 heuristic：

{
  "providers": {
    "local": {
      "type": "heuristic",
      "model": "heuristic-v1"
    },
    "ollama-embeddings": {
      "type": "ollama",
      "model": "nomic-embed-text",
      "baseUrl": "http://localhost:11434/v1"
    }
  },
  "tasks": {
    "compileProvider": "local",
    "queryProvider": "local",
    "embeddingProvider": "ollama-embeddings"
  }
}

当有支持嵌入的提供程序可用时，SwarmVault 默认也会将语义页面匹配合并到本地搜索中。tasks.embeddingProvider 是选择该后端的显式方式，但 SwarmVault 也可以回退到支持嵌入的 queryProvider。当你希望配置的 queryProvider 在回答前对合并后的顶部结果进行重排序时，设置 retrieval.rerank: true。

云 API 提供程序

对于云托管模型，使用你的 API 密钥添加一个提供程序块：

{
  "providers": {
    "primary": {
      "type": "openai",
      "model": "gpt-4o",
      "apiKeyEnv": "OPENAI_API_KEY"
    }
  },
  "tasks": {
    "compileProvider": "primary",
    "queryProvider": "primary",
    "embeddingProvider": "primary"
  }
}

有关可选后端、任务路由和特定能力配置示例，请参阅提供程序文档。

你也可以通过 CLI 管理提供程序路由，无需手动编辑 JSON：

swarmvault provider add router --type openrouter --model openrouter/auto --api-key-env OPENROUTER_API_KEY --capability chat --capability structured --task queryProvider
swarmvault provider list
swarmvault provider show router
swarmvault provider remove router --fallback local

提供程序命令会保留 swarmvault.config.json 中未知的字段，并通过 apiKeyEnv 存储密钥引用；它们不接受字面 API 密钥值。

语音优先捕获（本地 Whisper）

对于音频文件（语音备忘录、会议录音、访谈），安装 whisper.cpp 并让 SwarmVault 本地驱动它——无需 API 密钥，无需网络流量：

swarmvault provider setup --local-whisper --apply

该命令会验证二进制文件，将 base.en ggml 模型（约 147 MB）下载到 ~/.swarmvault/models/，并在 swarmvault.config.json 中将提供程序注册为 providers.local-whisper，同时将 tasks.audioProvider 指向它。之后，swarmvault add voice-memo.m4a（或将音频拖入 raw/inbox/）会完全离线转录；现有的摄取时审查器会在内容到达 raw/ 或 wiki/ 之前清除口述的秘密。使用 --model {tiny.en,small.en,medium.en,large-v3} 调整准确性，使用 localWhisper.threads 调整线程数，通过 localWhisper.binaryPath / localWhisper.modelPath / SWARMVAULT_WHISPER_BINARY 覆盖二进制文件/模型发现路径。local-whisper 提供程序类型在 1.1.0 版本的 STABILITY.md 中被记录为实验性。

更喜欢托管转录提供程序？将 tasks.audioProvider 指向任何具有 audio 能力的提供程序（OpenAI、Groq 等）。YouTube 转录摄取不需要模型提供程序。

指向定期源

让 SwarmVault 发挥最大作用的最快方式是托管源流程：

swarmvault source add ./exports/customer-call.srt --guide
swarmvault source add https://github.com/karpathy/micrograd
swarmvault source add https://example.com/docs/getting-started
swarmvault source list
swarmvault source session file-customer-call-srt-12345678
swarmvault source reload --all

source add 注册源，将其同步到 Vault，编译一次，并在 wiki/outputs/source-briefs/ 下写入一个源范围的简要。添加 --guide 可在 wiki/outputs/source-sessions/ 下获得一个可恢复的引导式会话、一个分阶段源审查和源指南，以及当 profile.guidedSessionMode 为 canonical_review 时包含审批捆绑的规范页面编辑。使用 insights_only 的配置档会将引导式合成保留在 wiki/insights/ 中。在 swarmvault.config.json 中设置 profile.guidedIngestDefault: true 可使引导模式成为 ingest、source add 和 source reload 的默认值；对于特定运行需要轻量路径时，使用 --no-guide。它现在也适用于定期本地文件以及目录、公共仓库和文档中心。使用 ingest 处理有意识的一次性文件或 URL，使用 add 进行研究/文章规范化。

Agent 和 MCP 设置

设置你的编码 Agent，使其了解 Vault：

swarmvault install --agent claude --hook --mcp  # Claude Code + 图谱优先钩子 + MCP 服务器
swarmvault install --agent codex --hook     # Codex + 图谱优先钩子
swarmvault install --agent cursor           # Cursor
swarmvault install --agent copilot --hook   # GitHub Copilot CLI + 钩子
swarmvault install --agent gemini --hook    # Gemini CLI + 钩子
swarmvault install --agent trae             # Trae
swarmvault install --agent claw             # Claw / OpenClaw 技能目标
swarmvault install --agent droid            # Droid / Factory 规则目标
swarmvault install --agent kiro             # Kiro IDE + 始终开启的引导
swarmvault install --agent kilo --hook       # Kilo 项目规则 + 插件
swarmvault install --agent hermes           # Hermes 用户范围技能
swarmvault install --agent antigravity      # Google Antigravity 规则 + /swarmvault 工作流
swarmvault install --agent vscode           # VS Code Copilot Chat 聊天模式
swarmvault install status --agent kilo --hook

对于支持钩子的 Agent，安装的钩子会引导图谱优先读取，强制执行是可选的。对于 Claude Code，--hook 在会话开始时注入图谱优先指令——使用纯文本的 swarmvault graph query|explain|path 命令（避免 --json，它会产生更大的输出）、swarmvault query、swarmvault context build 或 wiki/graph/report.md 回答代码理解问题，仅在编辑时读取源文件——同时附带图谱过时性提示。swarmvault graph query "<seed>" 打印顶部匹配项的页面路径以及最佳匹配 Wiki 页面的内联摘录，因此一个命令通常可以回答“在哪里/什么调用”的问题，无需后续文件读取。对于“谁调用”和“变更影响”问题，钩子指南推荐 swarmvault graph callers <symbol>，它会列出图谱调用边的所有调用者，并附有精确的 file:line 调用点证据——仅扫描图谱标识为调用者的文件——而不是整个仓库的 grep。默认情况下，钩子以建议模式（context）运行：每个会话的第一次广泛 Grep/Glob/Bash 搜索会收到一次引导提示，指向那些纯文本图谱命令，且不会拒绝任何操作。在安装时传递 --graph-first 可选择强制执行模式，其中每个会话的第一次广泛搜索会被拒绝一次，并引导到那些纯文本图谱命令及其返回的内联摘录（重复相同的搜索随后会被允许，因此工作永远不会被阻塞）。该标志接受可选值——deny（传递标志时的默认值）、context 或 off——并将所选模式持久化为 swarmvault.config.json 中的 hooks.graphFirst；SWARMVAULT_GRAPH_FIRST=deny|context|off 仍可覆盖每个会话。在 Edit/Write 工具之后，钩子会在后台启动 swarmvault graph update --file <path> 刷新，以便图谱跟踪你的编辑。限定在 Vault 产物目录（wiki/、raw/、state/）或单个文件内的搜索永远不会被拦截，仅过滤管道输出的搜索工具（例如 some-command | grep …）不计为广泛搜索。Codex、Gemini、Copilot、OpenCode 和 Kilo 钩子携带相同的图谱优先引导——一个会话提示加上一个符合每个工具钩子 API 的一次性搜索重定向。

SwarmVault

SwarmVault 摄取多种输入类型（PDF、Word、代码、图片、YouTube 等），并编译成带有溯源、矛盾检测、语义自动标签和智能体上下文包的知识图谱。它支持智能体集成、检索和导出为多种格式。

适用于任意输入类型的混合

输入	扩展名 / 来源	提取方式
PDF	.pdf	本地文本提取
Word 文档	.docx .docm .dotx .dotm	本地提取 + 元数据（包含宏启用和模板变体）
富文本	.rtf	基于解析器遍历的本地 RTF 文本提取
OpenDocument	.odt .odp .ods	本地文本 / 幻灯片 / 表格提取
EPUB 电子书	.epub	本地按章节拆分 HTML 转 Markdown 提取
数据集	.csv .tsv	本地表格摘要 + 有限预览
电子表格	.xlsx .xlsm .xlsb .xls .xltx .xltm	本地工作簿和表格预览提取（现代、宏启用、二进制和旧版格式）
幻灯片	.pptx .pptm .potx .potm	本地幻灯片和演讲者备注提取（包含宏启用和模板变体）
Jupyter 笔记本	.ipynb	本地单元格 + 输出提取
BibTeX 库	.bib	基于解析器的引用条目提取
Org-mode	.org	基于 AST 的标题、列表和块提取
AsciiDoc	.adoc .asciidoc	基于 Asciidoctor 的章节和元数据提取
转录文本	.srt .vtt	本地带时间戳的转录文本提取
聊天导出	Slack 导出 .zip，解压后的 Slack 导出目录	本地频道/日对话提取
电子邮件	.eml .mbox	本地消息提取和邮箱展开
日历	.ics	本地 VEVENT 展开
音频	.mp3 .wav .m4a .aac .ogg .webm 及其他 audio/* 文件	本地 Whisper（swarmvault provider setup --local-whisper）或通过 tasks.audioProvider 由提供商支持的转录
视频	.mp4 .mov .m4v .mkv .avi 及带 --video 的 URL 输入	ffmpeg 或 yt-dlp 提取音频，然后 tasks.audioProvider 转录
HTML	.html，URL	Readability + Turndown 转 Markdown（URL 摄取）
YouTube URL	youtube.com/watch，youtu.be，youtube.com/embed，youtube.com/shorts	直接获取字幕，提取标题和视频元数据
图片	.png .jpg .jpeg .gif .webp .bmp .tif .tiff .svg .ico .heic .heif .avif .jxl	视觉提供商（如果配置）
研究资料	arXiv、DOI、文章、X/Twitter	通过 swarmvault add 标准化为 Markdown
文本文档	.md .mdx .txt .rst .rest	直接摄取，轻量 .rst 标题归一化
配置 / 数据	.json .jsonc .json5 .toml .yaml .yml .xml .ini .conf .cfg .properties .env	结构化预览，带键/值模式提示
开发者清单	package.json tsconfig.json Cargo.toml pyproject.toml go.mod go.sum Dockerfile Makefile LICENSE .gitignore .editorconfig .npmrc（以及类似文件）	内容嗅探文本摄取——不会静默丢弃纯文本开发文件
代码	.js .mjs .cjs .jsx .ts .mts .cts .tsx .sh .bash .zsh .py .go .rs .java .kt .kts .scala .sc .dart .lua .zig .cs .c .cc .cpp .cxx .h .hh .hpp .hxx .php .rb .ps1 .psm1 .psd1 .ex .exs .ml .mli .m .mm .res .resi .sol .vue .svelte .jl .v .vh .sv .svh .r .R .css .html .htm .sql，以及带有 `#!/usr/bin/env node	python
浏览器剪辑	收件箱捆绑包	通过 inbox import 重写资产为 Markdown
托管源	本地目录、公共 GitHub 仓库根目录、文档中心	通过 swarmvault source add 进行注册表支持的同步

你将获得什么

带有溯源的知识图谱 - 每条边都追溯到特定的来源和声明。节点带有新鲜度、置信度和社区成员信息。

关键节点与社区 - 自动识别连接度最高的桥梁节点。图谱报告页面以通俗英语解释令人惊讶的关联。

矛盾检测 - 自动检测跨来源的冲突声明，并在图谱报告中呈现。使用 lint --conflicts 进行集中的矛盾审计。

语义自动标签 - 在分析过程中提取广泛的领域标签，并出现在页面前置元数据、图谱节点和搜索中。

模式引导编译 - 每个仓库都带有 swarmvault.schema.md，因此编译器遵循领域特定的命名规则、类别和基础要求。

保存优先的查询 - 答案默认写入 wiki/outputs/，因此有用的工作会积累而不是消失。支持 markdown、report、slides、chart 和 image 输出格式。

智能体上下文包 - swarmvault context build "<goal>" --target <path|node|page> 为编码或研究智能体编写一个带引用、受 token 限制的交接文档。包包括图谱导向、包含的证据、当预算过小时显式省略的内容，以及 wiki/context/ 和 state/context-packs/ 下的持久化制品。

智能体任务账本 - swarmvault task start|update|finish|resume 将任务目标、关联的上下文包、决策、图谱证据、触及的路径、结果和后续行动记录为 git 友好的 JSON 和 Markdown，存储在 state/memory/tasks/ 和 wiki/memory/tasks/ 下。编译包括图谱中的任务节点和决策，查看器显示任务历史。现有的 memory 命令保持兼容性别名。

仓库诊断与工作台 - swarmvault doctor [--repair] 检查图谱制品、检索、审查队列、监视状态、迁移、托管源、源/页面计数和任务状态。图谱查看器工作台显示优先的下一步行动、每个检查的详细信息、可复制的建议命令、安全修复、显式捕获模式、标题/标签捕获字段、带预算的上下文包创建和任务启动操作。

可审查的变更 - compile --approve 将变更分阶段放入审批包。新概念和实体首先进入 wiki/candidates/。任何内容都不会静默变更。

可配置的配置文件 - 在 swarmvault.config.json 中使用 profile.presets、profile.dashboardPack、profile.guidedSessionMode、profile.guidedIngestDefault、profile.deepLintDefault 和 profile.dataviewBlocks 组合仓库行为，而不是等待硬编码的产品模式。personal-research 是一个内置的预设别名。

引导式会话 - ingest --guide、source add --guide、source reload --guide、source guide <id> 和 source session <id> 在 wiki/outputs/source-sessions/ 下创建可恢复的源会话，暂存源审查和源指南，并根据配置的引导会话模式将审批包更新路由到规范源/概念/实体页面或 wiki/insights/。在 swarmvault.config.json 中设置 profile.guidedIngestDefault: true 使引导模式成为 ingest 和 source 命令的默认模式；使用 --no-guide 覆盖。

深度 lint 默认值 - 在 swarmvault.config.json 中设置 profile.deepLintDefault: true，使 swarmvault lint 默认包含 LLM 驱动的建议性检查。当你想只运行一次结构性的 lint 而不更改配置文件时，使用 --no-deep。

网络搜索增强的 lint — lint --deep --web 通过配置的网络搜索提供商（http-json 或 custom）用外部证据丰富深度 lint 结果。网络搜索目前仅限于深度 lint；其他命令只查询本地仓库状态。

知识仪表板 - wiki/dashboards/ 提供最近来源、阅读日志、时间线、源会话、源指南、研究地图、矛盾和未解决问题。这些页面首先作为纯 Markdown 工作，profile.dataviewBlocks 可以附加 Dataview 块，当你想要更 Obsidian 原生视图时。

检索、混合搜索和重排序 - 本地检索将其 SQLite FTS 分片和清单存储在 state/retrieval/ 下。当有支持嵌入的提供商时，它可以合并全文命中与语义页面匹配。tasks.embeddingProvider 是选择该后端的显式方式，但 SwarmVault 也可以回退到支持嵌入的 queryProvider。设置 retrieval.rerank: true 以在 query 答案之前让配置的 queryProvider 对合并后的候选集进行重排序。使用 swarmvault retrieval status|rebuild|doctor 检查或修复索引。

带 token 预算的编译和自动提交 - compile --max-tokens <n> 修剪优先级较低的页面，使生成的 wiki 输出保持在有界的 token 预算内，并且 ingest|compile|query --commit 可以在仓库位于 git 仓库中时立即提交 wiki/ 和 state/ 的更改。

图谱报告健康信号 - 图谱报告制品现在包括社区凝聚力摘要、孤立节点和歧义警告，以及当图谱存在弱连接或模糊区域时更尖锐的跟进问题。

可视化 + 可发布的分享套件 - 每次编译都写入 wiki/graph/share-card.md、wiki/graph/share-card.svg 和 wiki/graph/share-kit/；swarmvault graph share --post 打印简洁文本，swarmvault graph share --svg [path] 写入 1200x630 视觉卡片，swarmvault graph share --bundle [dir] 写入 Markdown、帖子文本、SVG、HTML 预览和 JSON 元数据，便于发布、链接或截图。

图谱影响范围、循环、状态、统计、验证、刷新、查询过滤、树、合并、聚类和报告导出 - graph blast <target> 通过模块依赖追踪反向导入影响，graph cycles [--relation imports] 查找确定性有向循环，graph status [path] 对图谱/报告制品和跟踪的仓库更改执行只读过期检查，check-update [path] 是用于相同 cron 安全状态检查的顶层兼容性别名。graph stats 打印轻量级计数和关系组合，graph validate [graph] --strict 在导出/合并/推送工作流之前检查重复 id、悬空引用、置信度边界和冲突边证据，graph update [path] / graph refresh [path] 对图谱制品运行仅代码的仓库刷新周期，除非显式使用 --force，否则有 25% 收缩保护；update [path] 是顶层兼容性别名。watch [path] --once 可以针对一个仓库根目录而不持久化监视配置。graph query 可以按关系、上下文组、证据类别、节点类型或语言过滤遍历，graph tree 编写一个交互式的源/模块/符号 HTML 树，具有展开/折叠控件和节点检查器，tree 是顶层别名。graph merge 将 SwarmVault 或 node-link JSON 图合并为一个命名空间制品，merge-graphs 是顶层别名。graph cluster [--resolution <n>] 从现有图谱重新计算社区、度、关键节点标志和图谱报告页面，无需重新摄取源，cluster-only [vault] 是顶层兼容性别名。graph export --report 编写一个自包含的 HTML 报告，包含图谱统计、关键节点、社区和警告；graph export --callflow <path> 编写一个紧凑的有向关系 HTML 视图；graph export --neo4j <path> 是用于 Neo4j 导入前的 Cypher 导出的别名。

图谱差异 - swarmvault diff 将当前知识图谱与上次提交的版本进行比较，显示添加/删除的节点、边和页面，因此你可以确切看到编译更改了什么。

工作树制品根目录 - SWARMVAULT_OUT=<dir> 将生成的 raw/、wiki/、state/、agent/ 和 inbox/ 制品重新定位，同时将 swarmvault.config.json 和 swarmvault.schema.md 保留在项目根目录。用于隔离的烟雾测试、共享源树和仓库工作树，其中生成的仓库状态不应与源文件放在一起。

Obsidian 图谱导出 - graph export --obsidian 编写一个 Obsidian 友好的捆绑包，保留 wiki 文件夹，为 Breadcrumbs/Juggl 附加带有类型化链接前置元数据的图谱连接，发出社区笔记和孤立节点存根，复制资产，生成 Dataview 仪表板页面，并包含带有 types.json、节点类型颜色组和每个页面 cssclasses 的完整 .obsidian 配置。

自适应图谱社区 - SwarmVault 自动调整 Louvain 社区分辨率，适用于非常小或稀疏的图，然后拆分过大或凝聚力低的社区，使图谱报告在更大的仓库上保持可扫描性。你可以在 swarmvault.config.json 中使用 graph.communityResolution 固定特定值，或使用 swarmvault graph cluster --resolution <n> 覆盖一次重新计算。

可选模型提供商 - OpenAI、Anthropic、Gemini、Ollama、OpenRouter、Groq、Together、xAI、Cerebras、通用 OpenAI 兼容、自定义适配器或内置启发式方法用于离线/本地使用。

智能体集成 - 显式安装 Codex、Claude Code、Cursor、Goose、Pi、Gemini CLI、OpenCode、Aider、GitHub Copilot CLI、Trae、Claw/OpenClaw、Droid、Kiro、Kilo、Hermes、Google Antigravity、VS Code Copilot Chat、Devin 和扩展技能包名册的规则。init、quickstart、scan 和 clone 不会修改项目本地规则文件，除非你选择配置的安装。可选的图谱优先钩子引导支持智能体的图谱读取——会话开始的图谱指导（含过期说明）、首次广泛搜索的一次性建议说明（或使用 --graph-first 强制执行选项，一次拒绝重定向，重试相同搜索始终允许），以及对于 Claude Code，编辑后自动后台每文件图谱刷新，可通过 SWARMVAULT_GRAPH_FIRST 或 hooks.graphFirst 配置。Antigravity 安装在 .agents/rules/ 和 .agents/workflows/ 下；旧的完全托管的 .agent/ 文件在重新安装时被清理。

MCP 服务器 - swarmvault mcp 通过 stdio 将仓库暴露给任何兼容的智能体客户端，包括图谱统计、只读图谱新鲜度（graph_status）、仅代码的图谱刷新（update_graph，可选每文件）、图谱聚类刷新、社区查找、超边、上下文包、任务账本、兼容性内存任务、仓库诊断和检索健康工具。该仓库还附带 Docker/注册表元数据，用于验证 stdio 容器入口点的 MCP 服务器注册表。

内置浏览器剪藏器 - graph serve 暴露一个本地 /api/bookmarklet 页面和 /api/clip 端点，因此运行中的仓库可以从工作台或书签小工具捕获当前浏览器 URL、页面标题、选中文本、Markdown、HTML 摘录和标签。仅 URL 的书签小工具剪辑使用标准化的 add；选中文本通过收件箱路径导入。

自动化 - 监视模式、git 钩子、定期计划和收件箱导入使仓库保持最新，无需手动干预。

托管源 - swarmvault source add|list|reload|review|guide|session|delete 将重复文件、目录、公共 GitHub 仓库和文档中心转换为命名的同步源，注册表状态在 state/sources.json，源摘要在 wiki/outputs/source-briefs/，可恢复的会话锚点在 wiki/outputs/source-sessions/，引导集成制品在 wiki/outputs/source-guides/。公共 GitHub 仓库源支持 --branch、--ref 和 --checkout-dir 用于固定的分支/标签/提交扫描和可重用的检出。

源制品类型：

制品	创建者	用途
源摘要	source add，ingest（始终）	自动摘要写入 wiki/outputs/source-briefs/
源审查	source review，source add --guide	较轻的阶段性评估，位于 wiki/outputs/source-reviews/
源指南	source guide，source add --guide	带审批包更新的引导式走查，位于 wiki/outputs/source-guides/
源会话	source session，source add --guide	可恢复的工作流状态，位于 wiki/outputs/source-sessions/ 和 state/source-sessions/

外部图谱接收器 - 导出为完整 HTML、轻量级独立 HTML、自包含报告 HTML、有向调用流 HTML、SVG、GraphML、Cypher、JSON、Obsidian 笔记包或 Obsidian 画布，或通过 Bolt/Aura 将实时图谱直接推送到 Neo4j，使用共享数据库安全的 vaultId 命名空间。

交互式摄取反馈 - 文件和目录摄取在 stderr 上发出有界进度，显示活动文件和已处理内容大小，而 JSON、MCP、监视和 CI 风格流程保持静默。

大型仓库加固 - 长仓库摄取和编译过程保持有界，提供商支持的非代码分析在模型调用之前对长提取文本进行分块，嵌套的 .gitignore 和 .swarmvaultignore 文件被尊重，带有 .swarmvaultinclude 允许列表用于有意例外，解析器兼容性失败仅限于受影响的源并带有显式诊断，仅代码的仓库监视周期跳过非代码重新分析，并且图谱报告合并微小碎片化社区以提高可读性。

每条边都标记为 extracted、inferred 或 ambiguous——你始终知道什么是被发现的 vs 猜测的。

平台支持

支持的智能体：Codex、Claude Code、Cursor、Goose、Pi、Gemini CLI、OpenCode、Aider、GitHub Copilot CLI、Trae、Claw / OpenClaw、Droid、Kiro、Kilo、Hermes、Google Antigravity、VS Code Copilot Chat、Amp、Augment、AdaL、IBM Bob、Cline、CodeBuddy、Command Code、Continue、Cortex Code、Crush、Deep Agents、Devin、Firebender、iFlow CLI、Junie、Kilo Code、Kimi Code CLI、Kode、MCPJam、Mistral Vibe、Mux、Neovate、OpenClaw、OpenHands、Pochi、Qoder、Qwen Code、Replit、Roo Code、TRAE CN、Warp、Windsurf、Zencoder。

SwarmVault

SwarmVault 是一个用于从多种来源构建知识库的 CLI 工具。它可以摄取、编译、查询、检查并监视文件，生成图谱、报告和知识库。默认在本地进行处理，并可选集成外部提供商进行语义抽取。

适用场景

• 研究深度分析 — 从论文和文章中构建不断演进的论点，并跨来源进行矛盾检测。
• 个人知识库 — 将日记、健康笔记、播客编译为带有仪表盘的个人 Memex。
• 书籍阅读 — 按章节创建粉丝维基，包含角色和主题页面，随着阅读不断累积。
• 代码仓库分析 — 摄取仓库，生成模块页面、图谱报告和基准测试。
• 研究感知式捕获 — 从 arXiv、DOI 和 URL 添加规范化元数据。
• 混合语料处理 — 跨混合输入类型进行编译、审查和保存输出。

核心能力

• 本地代码处理 — 代码文件在您的机器上通过 TypeScript 编译器 API、tree-sitter 或 SQL 解析器进行解析。源代码内容永远不会发送到外部 API。
• 文档和文本提取 — 文档和文本会发送到您配置的提供商进行语义抽取。使用内置的 heuristic 提供商时，所有处理均在本地完成。
• 图像处理 — 仅当配置了视觉能力提供商时，图像才会发送到该提供商。
• 启发式模式（默认） — 完全离线，无需 API 密钥，无需网络调用。
• 图谱构建、社区检测和报告生成 — 全部在本地完成。
• 多种提供商支持 — heuristic、openai、anthropic、gemini、ollama、openrouter、groq、together、xai、cerebras、openai-compatible、custom。
• CLI 选项 — --hook 用于图谱优先的读取指导，--graph-first 用于强制执行，--mcp 用于 MCP 服务器注册，--scope user 用于用户级安装，--scope project 用于项目级技能包。

工作方式

1. 您提供输入文件（代码、文档、图像、URL 或数据）。
2. SwarmVault 在本地处理它们，或将非代码内容发送到您配置的提供商进行语义分析。
3. 它构建图谱、检测社区并生成报告。
4. 您可以查询、检查、监视更改，或使用 MCP 集成。

您需要提供

• 输入文件（代码、文档、图像、URL 或数据）。
• （可选）如果您想使用外部 LLM 分析，则需要提供提供商 API 密钥和配置。
• （可选）CLI 选项，如 --hook、--graph-first、--mcp、--scope。

您将获得

• 编译后的知识库，包含图谱和报告。
• 仪表盘、粉丝维基、Memex 风格的个人知识库。
• 代码仓库的模块页面、图谱报告、基准测试。
• 来自研究来源的规范化元数据。
• 混合语料的编译输出。

使用示例

每个示例文件夹包含真实的输入文件和实际输出，您可以自行运行和验证。

示例	展示内容
research-deep-dive	从论文和文章中构建不断演进的论点，并跨来源进行矛盾检测
personal-knowledge-base	将日记、健康笔记、播客编译为带有仪表盘的个人 Memex
book-reading	按章节创建粉丝维基，包含角色和主题页面，随着阅读不断累积
code-repo	仓库摄取、模块页面、图谱报告、基准测试
capture	研究感知式 add 捕获，从 arXiv、DOI 和 URL 添加规范化元数据
mixed-corpus	跨混合输入类型的编译、审查、先保存后输出循环

请参阅示例指南了解分步说明。

重要说明

• 隐私与数据流：SwarmVault 默认在本地处理您的数据。代码文件在您的机器上解析，永远不会发送到外部 API。文档和文本仅发送到您配置的提供商进行语义抽取。使用内置的 heuristic 提供商时，所有处理均在本地完成。仅当配置了视觉能力提供商时，图像才会发送到该提供商。所有图谱构建、社区检测和报告生成均在本地完成。
• 启发式模式完全离线 — 无需 API 密钥，无需网络调用。
• 当您添加模型提供商（OpenAI、Anthropic、Ollama 等）时，仅非代码内容会发送到 LLM 进行分析。
• CLI 选项：--hook（默认为建议性；添加 --graph-first 可选择强制执行），--mcp 用于项目 .mcp.json MCP 服务器注册，--scope user 用于在 ~/.claude 下一次性安装 skill/hook/设置，--scope project 用于项目级安装，也可为具有 skill 目录的智能体编写技能包。
• 提供商是可选的，按能力而非品牌路由。请参阅提供商文档了解配置示例。
• 如需帮助，请参阅文档和故障排除指南。