SwarmVault

核心定位

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网络暴露等选项需显式启用

核心用法

SwarmVault 是一个遵循「LLM Wiki」三层架构（原始数据源 → Wiki → Schema）的本地优先知识库管理工具。用户通过 CLI 工具 swarmvault 完成知识库的初始化、数据摄入、编译生成和查询检索全流程。

快速上手：使用 swarmvault quickstart <目录或GitHub链接> 可一键完成初始化+摄入+编译+图谱可视化；swarmvault scan 或 swarmvault clone 适合快速预览仓库内容而无需完整配置。

数据摄入：支持本地文件/目录、公开GitHub仓库、文档站点、音视频文件（需 ffmpeg/yt-dlp）、YouTube 字幕等多种来源。swarmvault source add 用于注册 recurring 数据源，swarmvault ingest 用于一次性摄入。

知识编译：swarmvault compile 将原始数据转化为结构化的 Wiki 页面和知识图谱。支持 --approve 审核模式、--max-tokens 预算控制，以及 guided 引导模式确保质量。

查询与探索：swarmvault query 支持自然语言问答并保存结果；swarmvault chat 提供多轮持久化对话；swarmvault explore 支持多步研究循环，可输出报告、幻灯片、图表等形式。

Agent 协作：swarmvault context build 构建带预算限制的上下文包供其他 Agent 使用；swarmvault task start/update/finish 维护任务账本记录决策和变更；swarmvault export ai 导出 llms.txt 等标准格式供外部 AI 工具消费；swarmvault mcp 暴露 MCP 协议接口实现工具互通。

健康维护：swarmvault doctor 全面检查图谱、检索、审核队列等状态；swarmvault lint 检测 schema 漂移；swarmvault watch 实现自动化监控刷新。

显著优点

本地优先，隐私安全：所有数据存储在用户本地文件系统，支持完全离线运行（Ollama + Gemma 等本地模型），从源头消除数据外泄风险。

架构清晰，分层治理：raw/（原始数据）、wiki/（生成页面）、state/（索引状态）三层分离，配合 swarmvault.schema.md 作为「操作契约」，实现人机协作的可控知识管理。

多模态支持，格式丰富：覆盖 30+ 种代码语言、Office 全家档、PDF/EPUB/音视频/图片、Slack/邮件/日历导出等，提取结构化内容并构建统一知识图谱。

Agent 原生设计：内置 context-pack、task ledger、chat session、static AI export 等 Agent 协作原语，无缝融入 AI 驱动的工作流。

可视化与可分享：自动生成图谱报告、1200x630 SVG 分享卡片、HTML 交互预览、Obsidian/Neo4j 等导出格式，降低知识传播摩擦。

丰富的集成生态：支持 40+ IDE/Agent 的专用规则安装（Codex、Claude、Cursor、Aider 等），MCP 协议标准接口，以及 git hook 自动化触发。

潜在缺点与局限性

外部 CLI 依赖：Skill 本身为纯文档，实际功能依赖 @swarmvaultai/cli npm 包，需 Node.js 环境，且版本兼容性需独立管理。

本地资源消耗：完整功能（embedding、编译、图谱服务）对本地计算资源有一定要求，大规模知识库可能需要性能调优。

配置复杂度：schema 设计、provider 配置、profile 定制等提供高度灵活性的同时，也带来了一定的学习曲线，初学者可能感到信息过载。

音视频处理依赖：需额外安装 ffmpeg、yt-dlp 等系统工具，且 whisper.cpp 模型首次下载需要网络连接。

MCP 安全风险：虽然 Skill 本身安全，但 MCP 接口暴露后可能被其他 Agent 调用，需自行配置权限边界。

适合的目标群体

• 研究者与知识工作者：需要管理大量文献、笔记、会议记录，构建个人/团队知识图谱
• AI 应用开发者：需要为 Agent 提供结构化上下文、任务追踪和知识检索能力
• 开源项目维护者：需要快速理解代码库结构、生成技术文档、维护项目知识
• 企业知识管理团队：需要在私有环境中构建可审计、可版本控制的知识资产库
• 隐私敏感用户：不愿将知识数据上传云端，追求完全本地化的 AI 增强工作流

使用风险

性能风险：大规模知识库编译和图谱生成可能消耗较长时间和内存，建议在 CI/CD 或专用环境中运行。

依赖项风险：CLI 工具、Node.js 版本、本地模型、ffmpeg/yt-dlp 等外部工具需要持续维护和版本对齐。

数据一致性：--commit 自动提交、watch 模式自动刷新等自动化功能需配合 git 工作流使用，避免意外覆盖。

MCP 权限：启用 MCP 服务时，建议遵循最小权限原则，定期审查暴露的工具能力和调用日志。

schema 漂移：长期演进的知识库需要定期运行 swarmvault lint 和 swarmvault doctor，维护 schema 与实例的一致性。