核心定位
SwarmVault 是一个本地优先（local-first）的知识库构建引擎，由前OpenAI工程师Andrej Karpathy的LLM Wiki模式启发设计。它采用三层架构：原始资料层（raw/）→ 中间Wiki层（wiki/）→ 模式契约层（schema），让LLM在用户与原始资料之间维护一个持久化的、可查询的知识中枢。
核心工作流程
1. 初始化与定向：swarmvault next 快速诊断当前仓库状态，init 创建新库
2. 多模态摄取：支持本地文件、GitHub仓库、URL、音视频（需ffmpeg/yt-dlp）、PDF、Office文档、Jupyter笔记本等数十种格式
3. 结构化编译：swarmvault compile 将原始资料转化为Markdown页面、图谱（state/graph.json）、检索索引
4. 智能查询：swarmvault query 支持语义搜索+重排序；chat 支持多轮持久对话
5. 代理交接：context build 生成带引用的证据包；export ai 输出llms.txt等静态AI友好格式；task start 创建可追踪的任务台账
显著优点
- 真正本地优先：所有数据持久化到磁盘（raw/、wiki/、state/），不依赖云服务即可运行
- 广泛的格式支持：覆盖代码（20+语言）、文档、音视频、结构化数据、图像OCR等
- 代理原生设计：MCP服务器、多代理配置安装（Codex、Claude、Cursor等30+工具）、任务台账与上下文包专为AI协作设计
- 精细的版本控制：
--approve审核流程、review/candidate晋升机制、git钩子自动触发代码级刷新 - 图谱可视化：内置交互式图谱查看器、分享卡片（SVG/HTML）、社区聚类分析
潜在局限
- 模型依赖：核心质量取决于配置的LLM提供商（默认heuristic为离线起点，需Ollama等提升质量）
- 音视频处理复杂：本地Whisper需额外配置，视频处理依赖ffmpeg/yt-dlp
- 学习曲线：schema契约、三层架构、20+命令组合需要一定上手时间
- Node.js生态：依赖npm安装，对非Node环境用户不够友好
适合人群
- 需要长期知识管理的研究者、开发者、技术写作者
- 构建AI原生工作流的团队（RAG、多代理协作、持续集成）
- 希望数据自主可控、避免SaaS锁定的用户
- 需要处理多模态资料（代码+文档+音视频+论文）的复杂项目
常规风险
- 数据完整性：
swarmvault doctor可检测索引损坏，但大规模仓库的--repair需谨慎 - 成本意识：若配置外部API（OpenAI/Anthropic等），编译和查询可能产生费用；本地Ollama+Gemma为推荐低成本方案
- schema漂移：频繁变更
swarmvault.schema.md可能导致重新编译开销 - 隐私边界：虽为本地优先，但
--web深度检索、swarmvault mcp网络暴露等选项需显式启用