SwarmVault

核心用法

SwarmVault 是一个本地优先（local-first）的知识库构建工具，采用三层架构（原始源 → Wiki → Schema）将分散的文档、代码、媒体转化为可查询、可关联、可持久化的结构化知识网络。

初始化与快速开始：

• swarmvault init — 创建新仓库
• swarmvault quickstart <path/url> — 一键完成初始化+摄取+编译+图谱预览
• swarmvault scan <path> 或 swarmvault clone <url> — 零配置快速扫描本地或GitHub资源

内容摄取：支持 Markdown、PDF、Office 全家桶、Jupyter、音视频（需 ffmpeg/yt-dlp）、代码库（20+语言）、YouTube 字幕、Slack/邮件导出、图片 OCR 等。通过 source add 管理持续同步的源，ingest 处理一次性输入，--guide 模式支持逐源人工审核。

知识编译与查询：

• swarmvault compile — 将原始源转化为 Wiki 页面与图谱
• swarmvault query "question" — 持久化问答，结果保存至 wiki/outputs/
• swarmvault chat "question" — 多轮对话，支持 --resume 续聊
• swarmvault explore "topic" — 多步研究循环，可输出报告/幻灯片/图表

高级工作流：

• 上下文打包：context build 为 Agent 交接生成 token 受限的证据包
• 任务账本：task start/update/finish 记录决策、变更路径与后续跟进
• AI 导出：export ai 生成 llms.txt、JSON-LD 图谱等静态交接格式
• MCP 服务：swarmvault mcp 暴露标准协议接口供外部工具调用
• 图谱服务：graph serve 提供实时工作台、Memory 仪表板、书签剪藏

运维与治理：

• swarmvault doctor [--repair] — 健康检查与自动修复
• swarmvault lint — 模式校验与深度审计（可选联网证据）
• swarmvault review/candidate — 人工审核队列管理
• swarmvault watch — 自动监控代码变更并增量更新

显著优点

1. 真正的数据主权：所有原始内容与生成产物以 Markdown/JSON 明文存储于本地磁盘，无vendor锁定，可git版本控制，支持 SWARMVAULT_OUT 自定义输出根目录。

2. LLM Wiki 模式创新：借鉴 Andrej Karpathy 的三层架构理念，LLM 作为"维基管理员"维护原始源与用户之间的持久化知识层，实现"一次编译，多次查询"的成本优化。

3. 工程化成熟度：支持20+编程语言的AST级代码索引、SQL表关系图谱、模块依赖分析；提供代码专属加速路径（--code-only）与AST感知增量更新。

4. 开放生态集成：原生支持MCP协议、Obsidian/Neo4j导出、静态AI交接格式；为30+主流Agent（Claude、Cursor、Aider、Copilot等）提供项目级规则注入与hook集成。

5. 多模态能力完整：音视频转录（本地Whisper/yt-dlp）、图片OCR、YouTube直接字幕捕获，覆盖个人知识管理的全媒介类型。

6. 工作流灵活性：从--approve审核模式到--guide人工介入，从watch自动监控到task结构化任务追踪，适配从个人研究到团队协作的多场景需求。

潜在缺点与局限性

1. 本地计算资源依赖：完整功能需要Node.js、可选Python环境、ffmpeg、yt-dlp等二进制依赖；大型代码库的全量编译可能消耗显著本地LLM tokens或API成本。

2. 初期配置复杂度：swarmvault.config.json与swarmvault.schema.md的双层配置体系虽有强大表达能力，但新用户理解"profile行为层"与"schema意图层"的分工需要学习成本。

3. Provider配置陷阱：默认的heuristicProvider功能受限，完整体验需手动配置Ollama/OpenAI等后端；多Provider路由、embedding、rerank等高级能力配置繁琐。

4. 音频/视频门槛：本地视频处理依赖ffmpeg，公开视频URL需要yt-dlp，且部分平台可能有反爬限制；大规模媒体库的转录成本不可忽视。

5. 图谱可视化局限：虽然支持SVG/HTML导出，但交互式图谱浏览依赖graph serve本地服务，无内置云端协作视图（需自行部署或导出到Obsidian/Neo4j）。

6. R语言支持缺口：文档明确标注R语言"emit an explicit diagnostic until a safe packaged parser exists"，科学计算用户需注意。

适合人群

• 研究者与知识工作者：需要整合论文、笔记、网页、会议记录为可查询知识库
• 开发者与技术写作者：维护大型代码库文档、API参考、架构决策记录（ADR）
• AI辅助工作流用户：希望为Claude/Cursor等Agent提供结构化上下文，实现跨会话 continuity
• 数据隐私敏感者：拒绝SaaS知识库，要求本地明文存储与完全可控的AI交互
• 开源/个人知识管理爱好者：偏好Markdown原生、git友好、可hack的工具体系

常规风险

• 生成内容准确性：LLM编译与查询可能产生"幻觉"或过时信息，关键决策需人工核实
• 配置漂移：schema或profile变更若未同步执行lint/doctor，可能导致查询与编译行为不一致
• 存储膨胀：raw/、wiki/、state/多层产物可能快速占用磁盘，需定期candidate archive或清理
• API成本失控：大规模自动编译/探索若配置高成本Provider，可能产生意外费用
• 版本兼容性：快速迭代版本（当前3.16.0）可能存在配置格式迁移需求，升级前建议doctor检查
• MCP安全风险：swarmvault mcp暴露的 tools/resources 若被恶意Agent调用，可能读取敏感本地数据，需控制MCP服务器访问范围