核心用法
SwarmVault 是一款围绕 LLM Wiki 三层架构（原始来源 → Wiki 层 → Schema 层）构建的本地优先知识库工具。用户通过 CLI 命令完成从初始化到持续维护的完整工作流：
1. 快速启动：swarmvault quickstart 一键完成初始化、摄取、编译与图谱可视化的完整链路；swarmvault scan 支持对本地文件、GitHub 仓库或文档树进行零配置快速扫描。
2. 内容摄取：支持书籍、笔记、音视频转录、代码仓库、办公文档（PDF/Word/Excel/PowerPoint）、网页等 50+ 格式的结构化摄取。音频视频依赖 ffmpeg 和 yt-dlp，YouTube 支持直接转录捕获。
3. 智能编译：swarmvault compile 将原始内容转化为可查询的 Wiki 页面，支持 --approve 审核流、--max-tokens 预算控制，以及 guidedIngestDefault 引导模式实现人机协作式内容整合。
4. 多维查询：swarmvault query 提供自然语言问答，swarmvault chat 支持多轮持久化对话，swarmvault explore 实现多步研究循环，均可输出为报告、幻灯片或图表。
5. 图谱优先代码理解：针对代码库场景，图谱构建后优先使用 graph query、graph callers、graph blast 等命令进行依赖分析、调用链追踪和影响面评估，替代传统文件搜索。
6. Agent 协作：swarmvault context build 生成带预算的上下文包供下游 Agent 使用；swarmvault task start/update/finish 建立持久化任务账本；swarmvault export ai 输出 llms.txt 等标准格式供外部 AI 工作流消费；MCP 服务器支持让外部工具直接浏览、查询和管理 Vault。
7. 持续维护：swarmvault watch 实现自动化监控刷新，swarmvault doctor 进行健康诊断，swarmvault lint 执行模式校验，确保知识库长期一致性。
显著优点
- 数据主权：完全本地运行，原始素材、Wiki 内容、图谱状态均存储于本地文件系统，无云端依赖，满足隐私合规要求。
- 格式全覆盖：从传统办公文档到现代开发产物（Jupyter、Dockerfile、各类代码）再到多媒体内容，形成统一知识平面。
- LLM 原生设计：三层架构让 LLM 成为 "Wiki 维护者"，人与原始来源之间通过机器可读的中间层交互，大幅降低上下文消耗。
- 图谱驱动：代码库场景下，基于图结构的查询比文本搜索更高效精准，支持社区发现、循环检测、影响分析等高级操作。
- 生态集成：内置 30+ Agent 的专用规则安装器，支持 Claude、Cursor、Copilot、Aider 等主流工具的深度集成。
- 渐进式工作流：从
demo零配置体验、quickstart快速上手，到guided严格审核模式，适应不同严谨度需求。
潜在缺点与局限性
- 配置复杂度：功能矩阵庞大（provider 路由、音频视频处理、嵌入模型、重排序等），新手需要一定学习曲线才能发挥全部潜力。
- 外部依赖较重：核心功能依赖 Node.js CLI、可选功能需要
ffmpeg、yt-dlp、Ollama 等额外组件，完整本地部署涉及多工具链协调。 - 本地资源消耗：大型代码库或海量文档的编译、嵌入索引、图谱构建对 CPU/内存/磁盘有显著要求，无内置分布式能力。
- T3 来源风险：当前由个人开发者维护，长期更新承诺、企业级 SLA 需自行评估。
- 语言支持不均：部分语言（如 R）依赖 WASM 语法包，某些格式（如 R）会输出显式诊断警告直至安全解析器就绪。
适合的目标群体
- 知识工作者：研究人员、分析师、作家，需要长期维护个人或团队的领域知识库。
- 开发者与架构师：需要深入理解大型代码库、进行影响分析、维护技术文档的工程师。
- 隐私敏感型组织：金融、医疗、法律等行业，要求数据不出本地、满足合规审计的场景。
- AI 应用构建者：需要为 Agent 提供结构化、可检索、带引证的上下文数据源的产品团队。
- 终身学习者：希望将阅读、笔记、代码片段、课程资料统一管理的个人用户。
常规使用风险
- 性能风险：首次编译大型仓库或启用嵌入索引时可能出现长时间阻塞；建议分批次摄取或关闭非必要功能。
- 版本兼容性：CLI 与 Skill 版本需保持兼容，文档建议明确声明支持范围；MCP 服务器配置需关注各 Agent 的版本适配。
- 数据一致性：
raw/目录内容被设计为不可变，若手动修改可能导致溯源混乱；应通过 Schema 修订或新增来源实现更新。 - 检索质量依赖配置：默认的启发式 provider 仅为起点，生产环境需配置专用 LLM 和嵌入模型以获得满意效果。
- 外部 CLI 供应链：
npm install环节存在供应链风险，需确保从官方 registry 获取；yt-dlp等工具更新频繁，可能因平台变更失效。 - 图谱新鲜度：代码库修改后需手动或配置钩子触发
graph update，否则可能出现查询结果与源码不一致。