核心定位
SwarmVault 是一款本地优先、LLM 驱动的知识库系统，采用 Karpathy 提出的 "LLM Wiki" 三层架构模式——原始源（raw sources）、维基层（wiki）、模式层（schema）——在用户与原始资料之间建立持久的结构化知识中间层。
核心用法
初始化与快速上手：swarmvault init 创建仓库，swarmvault quickstart <路径或GitHub地址> 一键完成初始化+摄取+编译+图谱可视化。swarmvault next 提供只读状态诊断，推荐下一步操作。
知识摄取：swarmvault source add 注册周期性源（本地目录、GitHub 仓库、文档站点），swarmvault ingest 处理一次性输入。支持音频（需配置 audioProvider）、视频（本地需 ffmpeg，公开 URL 需 yt-dlp）、YouTube 直接转录、以及 30+ 文档格式（PDF、Office 全家桶、Jupyter、图片 OCR 等）。--guide 模式支持人工审核的单源集成流程。
编译与查询：swarmvault compile 生成维基页面与图谱，--max-tokens 可限定预算，--approve 启用审核队列。swarmvault query 基于编译后的维基回答问题并持久化结果；配置嵌入模型后可融合语义搜索与重排序。
图谱优先的代码理解：编译代码库后，优先通过 swarmvault graph query/explain/blast/path 回答"X 在哪/谁调用了 Y/修改 Z 的影响"，避免直接 grep 源文件。graph serve 启动实时工作台，含健康检查、待办优先级、书签剪辑器等。
会话与协作：swarmvault chat 支持多轮持久对话，--resume 续接会话。context build 为下游 agent 生成带引用和预算控制的证据包。task start/update/finish 建立可审计的任务台账，记录决策、变更路径与后续行动。
导出与集成：export ai 生成 llms.txt、JSON-LD 图谱、清单等静态交接包；mcp 子命令暴露 MCP 服务器接口供外部工具调用。支持 30+ IDE/agent 的 install --agent 集成，包括 Claude/Cursor/Aider 等带 hooks 或 MCP 注册。
显著优点
1. 离线可用、数据自主：默认本地运行，支持 Ollama+Gemma 等完全离线配置，原始源与生成产物均为本地 Markdown/JSON。
2. 三层架构解耦：schema 层定义编译规则与质量约束，wiki 层为 LLM 优化的持久化知识，raw 层保持源数据不可变，便于迭代与溯源。
3. 代码图谱深度：支持 25+ 语言的静态分析，模块、符号、导入关系入图，提供反向依赖分析（blast）、调用链、社区聚类等代码理解能力。
4. 协作连续性：chat 会话、context packs、task ledgers、AI 导出包均为持久化 markdown/json，支持跨会话、跨工具、跨 agent 的手递手协作。
5. 渐进式工作流：从 scan/clone 快速试探，到 source add 长期追踪，再到 watch/hook 自动化刷新，适应不同成熟度需求。
潜在局限
- 初始配置门槛：音频/视频/嵌入/重排序等能力需额外配置 provider 与外部工具（ffmpeg、yt-dlp）。
- 编译成本：大型代码库的全量编译可能耗时且消耗 token，
--max-tokens和 code-only 更新可缓解但需权衡完整性。 - 图谱新鲜度：自动刷新依赖
watch或 git hooks 配置，否则需手动graph update/compile。 - R 语言支持：当前仅输出诊断信息，待安全打包解析器。
- agent hooks：graph-first 强制模式为 opt-in，团队需主动安装以统一工作流。
适合人群
- 需要本地知识库的研究者、开发者、技术写作者
- 维护大型代码库、需要跨模块影响分析的开发团队
- 追求LLM 协作连续性、需跨会话保留上下文的多 agent 工作流
- 重视数据主权、需在离线或受限网络环境运行知识管理的组织
常规风险
- 数据增长：
raw/、wiki/、state/随摄取源持续增长，需定期归档或设置SWARMVAULT_OUT分离存储。 - 模式漂移：
swarmvault.schema.md与配置不同步可能导致编译质量下降，建议lint/doctor定期自检。 - 敏感数据：摄取含 PII 的文档、邮件、Slack 导出时需评估本地存储与备份策略。
- 模型依赖：非 heuristics 的 provider 配置可能涉及 API 密钥管理，需遵循最小权限原则。
- 图谱验证：合并、发布图谱前建议使用
graph validate --strict检查引用完整性，避免下游消费失败。