abp2204/vibe-splain

◈ vibe-splain
映射复杂代码库中的架构 DNA 和行为调用链。

安装 · 工作原理 · MCP 工具 · Dossier UI · 开发

vibe-splain 是一个高保真的**静态分析引擎**和 MCP server。它使用 [Tree-Sitter](https://tree-sitter.github.io/tree-sitter/) 来提取代码库的结构和行为模式——识别高引力组件，映射语义操作，并追踪入口点和副作用之间的调用链。 虽然 vibe-splain 构建于语言无关的基础之上，但当前的工具集**针对 TypeScript 和 JavaScript 进行了高度优化**（特别是 Next.js、Prisma 和 tRPC 环境）。 **零 LLM 调用。零 API 密钥。纯静态分析。** 你的编程 agent 负责所有的思考——而 vibe-splain 只是为它提供正确的数据。 ## 安装 ``` npx vibe-splain install ``` 就是这样。这会修改你的编程 agent 的 MCP 配置，以便它可以调用 vibe-splain 的工具。重启你的 agent。 ### 运行分析 你不需要编写复杂的 prompt。vibe-splain 提供了一个名为 `build_dossier` 的内置 MCP Prompt，它会自动准确告诉你的 agent 该做什么。 **在 Claude Code / Gemini CLI 中：** 输入 `/prompt build_dossier` 并按回车键。 **在 Cursor / Windsurf 中：** 打开 MCP 面板或 agent 聊天，从 vibe-splain server 中选择 `build_dossier` prompt，然后运行它。 你的 agent 将循环遍历高引力文件，逐一分析，并生成一份**架构档案**——这是一组结构化的**决策卡片**，用于解释代码背后的技术逻辑。 ### 支持的 Agents | Agent | 配置文件 | |-------|------------| | Claude Code | `~/.claude/claude_desktop_config.json` | | Gemini CLI | `~/.gemini/settings.json` | | Cursor | `~/.cursor/mcp.json` | | Windsurf | `~/.codeium/windsurf/mcp_config.json` | ## 工作原理 ``` ┌─────────────────────────────────────────────────────────┐ │ Your Coding Agent (Claude / Gemini / Cursor) │ │ │ │ "Scan this project" ──► scan_project ──► get_file_ctx │ │ │ │ │ │ Agent synthesizes ◄──────┘ ◄──────────────┘ │ │ narratives + diagrams │ │ │ │ │ ▼ │ │ write_decision_card ──► .vibe-splainer/dossier.json │ │ │ │ │ ▼ │ │ file:// Dossier UI │ └─────────────────────────────────────────────────────────┘ ``` ### 三个分析级别 1. **Level 0 — 语义分类**：使用导入路径启发式算法和库签名，将文件映射到架构“支柱”（如 Auth、Payments、Database 等）。 2. **Level 1 — 结构与行为引力**：核心基于链接密度、嵌套深度和变更次数，利用 Tree-Sitter AST 分析计算 `staticGravity`。**内置适配器**（如 Cal.com 和 n8n）会解析产品语义，为关键的动态执行路径增加 `behavioralLift`。最终的 `gravity` 是静态证据和适配器解释的结合。 3. **Level 2 — 行为可追溯性**：基于 Tree-Sitter 的调用图分析。它映射函数级别的依赖关系，并识别**关键函数**（入口点、语义操作或高外部调用者）。 ### Claude Code PreToolUse Hook `vibe-splain` 直接与 Claude Code 的 hook 系统集成，以防止 AI agents 意外破坏你的代码库： - **超快的本地拦截**：安装一个独立的入口点（`dist/hook.js`），运行时间**< 15ms**，零网络调用，避免了繁重的 WASM/tree-sitter 加载开销。 - **混合爆炸半径逻辑**：结合静态引力和基于实质的直接依赖项来保护重要文件（例如动态加载的执行节点或核心工具模块），即使它们缺少标准入口点也能得到保护。 - **减少开发者阻碍**：自动将生成的、压缩的或 vendor 的文件降级为`低`爆炸半径，确保 agent 在编辑构建目标或 lockfiles 时永远不会被阻挡。 - **单次会话警告行为**：如果缺少 `.vibe-splainer/gate.json`，hook 会在每次会话中仅通知你一次以运行项目扫描，然后自动让步。 ## MCP 工具 vibe-splain 通过 MCP stdio 暴露了 **8 个工具**： | 工具 | 用途 | |------|---------| | `scan_project` | **首先调用此工具。** 扫描代码库，返回按支柱分组的高引力文件。启动文件监视器。 | | `get_file_context` | 返回特定文件的完整源码 + 导入图邻居。 | | `write_decision_card` | 保存决策卡片（叙述 + 证据 + 可选的 Mermaid 图表）。 | | `get_strategic_overview` | 返回不带证据片段的档案状态（节省 token）。 | | `inspect_pillar` | 返回某个支柱的所有决策卡片及其完整证据。 | | `get_wild_discoveries` | 返回不符合标准模式的最复杂文件。 | | `mark_stale` | 当你在会话期间修改文件时将卡片标记为过期。 | ### 推荐的 Agent 工作流 ``` 1. scan_project → get high-gravity files 2. For each file: get_file_context → read source + neighbors 3. Synthesize: "WHY does this code exist?" 5. write_decision_card → persist the narrative 6. Share the file:// UI link with the user ``` ## 工作原理 ### 深度分析流水线 与简单的 regex 扫描器不同，vibe-splain 运行一个确定性的 **13 阶段流水线**——从 AST 清单和别名解析，到语义分类和函数级评分——以确保每张决策卡片都建立在真实的代码路径之上。 ### 语义规则集 vibe-splain 使用专门的规则集来理解框架特定的语义。当前的优化包括： - **Next.js**：Server Actions、`cookies()`、`headers()` 和 App Router 约定。 - **Database**：Prisma 模型变更和原生查询模式。 - **API**：tRPC 过程调用（`mutate`/`query`）和标准的 `fetch`/`axios` 模式。 - **Auth**：Clerk、NextAuth 和自定义的速率限制/验证逻辑。 ## Dossier UI 在你的 agent 写入决策卡片后，在浏览器中打开生成的文件： ``` file:///path/to/your/project/.vibe-splainer/ui/index.html ``` UI 特性包括： - **深色主题**，带有毛玻璃效果和细腻的网格纹理 - **支柱选项卡**，用于导航各个架构区域 - **决策卡片**，带有全新/过期状态徽章 - **Mermaid 图表**，以 SVG 格式内联渲染 - **证据侧边栏**，带有 Shiki 语法高亮（tokyo-night） - **Wild Discoveries** 选项卡，展示最复杂的异常文件 - 完全通过 `file://` 离线工作——无需服务器 ## 架构 ``` packages/ ├── brain/ # @vibe-splain/brain — repo-agnostic analysis core + bundled adapters │ └── src/ │ ├── pipeline/ │ │ └── adapters/ # Bundled product adapters (Cal.com, n8n) │ ├── scanner.ts # Tree-Sitter AST analysis (static analysis, graph building) │ ├── dossier.ts # Atomic persistence + UI regeneration │ ├── graph.ts # Import graph read/write │ └── watcher.ts # Chokidar file watcher ├── cli/ # vibe-splain — MCP server + CLI │ └── src/ │ ├── index.ts # #!/usr/bin/env node entry │ ├── commands/ │ │ ├── install.ts # Agent config patcher │ │ └── serve.ts # MCP server launcher │ └── mcp/ │ ├── server.ts # @modelcontextprotocol/sdk setup │ └── tools/ # 7 tool handlers └── ui/ # @vibe-splain/ui — React dossier viewer └── src/ ├── App.tsx # Main app (reads window.__VIBE_DOSSIER__) ├── components/ # Header, PillarTabs, DecisionCard, etc. └── index.css # Design system ``` ### 关键设计决策 - **无 LLM 调用**：vibe-splain 是一个纯粹的静态分析工具。编程 agent 提供所有的综合分析。 - **`async-mutex`**：所有档案写入都由 mutex 保护，采用原子 tmp+rename 操作。 - **`startLoad: false`**：Mermaid 是手动初始化的——从不自动扫描 DOM。 - **`base: './'`**：Vite 使用相对路径构建，因此 UI 可以从 `file://` URL 工作。 - **禁止 `console.log`**：Brain 和 CLI 仅使用 `console.error`，以避免破坏 MCP stdio。 - **Tree-Sitter WASM**：从 `tree-sitter-wasms` npm 包加载——无网络调用。 ## 开发 ### 前置条件 - Node.js ≥ 18 - npm ≥ 9（用于 workspaces） ### 设置 ``` git clone https://github.com/abp2204/vibe-splain.git cd vibe-splain npm install ``` ### 构建 ``` npm run build ``` 按以下顺序运行：brain → cli → ui → bundle-ui（将 UI dist 复制到 CLI dist 中）。 ### 开发 UI ``` npm run dev:ui ``` 在 `http://localhost:5173` 启动 UI 包的 Vite 开发服务器。 ### 本地测试安装 ``` node packages/cli/dist/index.js install ``` ### 测试 MCP Server ``` node packages/cli/dist/index.js serve ``` 然后通过 stdin 发送 JSON-RPC 消息（参见 [MCP 规范](https://modelcontextprotocol.io)）。 ### 发布 ``` npm run release ``` 构建所有内容，并将 `vibe-splain` CLI 包发布到 npm。 ## 档案如何保持最新 当运行 `scan_project` 时，它会启动一个 [Chokidar](https://github.com/paulmillr/chokidar) 文件监视器。当源文件发生更改时： 1. 监视器检测到更改 2. 匹配的决策卡片被标记为**过期**（在 UI 中显示为琥珀色徽章） 3. 档案中的 `stalePaths` 数组会跟踪哪些文件需要重新分析 4. 你的 agent 可以调用 `get_strategic_overview` 查看过期的内容，然后重新扫描 如果你在会话期间修改了代码，也可以使用 `mark_stale` 手动将文件标记为过期。 ## 许可证 [MIT](LICENSE)

标签：MCP服务器, MITM代理, TypeScript, 代码可视化, 安全专业人员, 安全插件, 架构分析, 自动化攻击, 调用链追踪, 错误基检测, 静态代码分析