Void Stack

Void Stack

  ](https://github.com/Mague/void-stack/releases/latest)    

有10个包含后端、前端、工作人员和数据库的项目，但你不记得如何开始其中的任何一个了？

Void Stack解决了这个问题。在Windows、WSL或Docker上启动整个开发堆栈（后端、前端、数据库、workers）的一个命令。没有记忆端口，没有打开5个终端，没有阅读过时的README。

void add my-app F:\projects\my-app    # Auto-detects services
void start my-app                      # Starts everything

就是这样。Void Stack扫描您的项目，检测您正在使用的框架（FastAPI、Vite、Express、Django……），生成正确的命令并运行它们。如果有一个Python venv，它会找到它。如果 node_modules 不见了，它告诉你。

高性能 --用Rust构建。零运行时开销，即时启动，最小内存占用。

代理工作流 --配备43个工具的MCP服务器使Claude Desktop/Claude Code能够自主管理您的服务、分析代码和审计安全性。

云原生路线图 --从同一配置部署到Vercel、DigitalOcean等（即将推出）。

西班牙语阅读 | void-stack.dev

______________________________________________________________________

狗食：Void Stack分析自己

Void Stack自己的分析和审计工具用于维护其代码库的质量。这就是跑步 void analyze void-stack --compare 和 void audit void-stack 关于项目本身所揭示的内容，以及我们如何利用这些发现来改进代码：

安全审计

void audit void-stack
# Risk Score: 2/100
# 2 low findings (innerHTML usage — already mitigated with DOMPurify)

初步审计发现了6个问题（风险评分25/100），但有4个是误报——检测代码中标记为“机密”的正则表达式模式和模板。这促使我们添加了智能误报过滤（自引用文件分配列表、正则表达式元字符检测、模板行过滤），将误报率从83%降至0%。

代码分析

void analyze void-stack --compare
# Pattern: Layered (80% confidence)
# 214 modules, 32,453 LOC, 37 external deps
# Max complexity: 152 (i18n en/es — data tables, not logic)
# Anti-patterns: 26 (4 medium God Class, 13 Fat Controller, 8 Excessive Coupling)

推动重构的发现：

技术债务跟踪

void analyze void-stack --compare --label v0.23.6
# Pattern: Layered (80% confidence)
# Coverage: 80.5% (latest lcov snapshot)
# Explicit debt: 34 markers (TODO: 11, TEMP: 10, OPTIMIZE: 6, BUG: 3, XXX: 2, FIXME: 1, HACK: 1)
# 960 tests passing (936 core + 21 analyzer + 3 mcp)

v0.2.0中的新功能：现在从源代码注释中扫描显式债务标记（TODO/FIXME/HAK/XXX/OPTIMIZE/BUG/TEMP/WORKAROUND），并在CLI输出、降价报告和桌面债务选项卡中显示。复杂函数（CC≥10）与覆盖率数据交叉引用——未覆盖的关键函数 [!] CLI中的警告和🔴 降价指标。

______________________________________________________________________

混合上下文引擎——语义+结构

大多数人工智能工具迫使你做出选择：语义搜索（查找相关概念）或结构图（跟踪调用链）。Void Stack将两者结合在一起。向量嵌入查找 *什么在概念上相关*树形图显示 *什么结构断裂*结果：没有一种单一的手术方法可以匹配的手术环境。

Void Stack使用BAAI/bge-small-en-v1.5嵌入对您的代码库进行本地索引，并构建一个Tree sitter调用图——这样您的AI助手就只读取重要的内容，而不是扫描每个文件。

运作原理

# Index once (runs in background, ~30s for 250 files)
void index my-project

# Search by concept, not by filename
void search my-project "authentication middleware flow"
# Returns the 3-5 most relevant code chunks — not the whole file

# Incremental re-index driven by git, not timestamps
void index my-project --git-base HEAD~1   # only files changed since last commit
void index my-project --force             # full rebuild

# From Claude Desktop / Claude Code via MCP:
#   build_structural_graph my-project          (Tree-sitter, 11 languages)
#   get_impact_radius      my-project          (blast radius BFS)
#   query_graph            my-project callers  (who calls this function)
#   watch_project          my-project          (auto re-index on save)
#   install_index_hook     my-project          (post-commit re-index)

基准（在空隙堆本身上测量）

*97.5%的数字由 void stats --days 90 135 semantic_search 操作——23 868行从未进入LLM上下文的源代码。*

支持的语言

• 语义索引 （嵌入）：中的每个源扩展 CODE_EXTENSIONS --Rust、Python、JS/TS、Go、Dart、Java、PHP、C/C++、Ruby、Swift、Kotlin、Lua、Zig、Elixir、Vue、Svelte、Astro等 md/proto/sql/dockerfile.
• 结构图 （树保姆）：Rust、Python、JavaScript、TypeScript（+TSX）、Go、Dart、Java、PHP、C、C++、Elixir。

结构分析灵感来自 代码审查图 （MIT）--AST节点映射和BFS查询逻辑在Rust中重新实现。

______________________________________________________________________

接口

无效堆栈具有 4个接口 --使用您喜欢的任何一种：

端到端示例：30秒内快速API+React

假设你有一个带有FastAPI后端和React前端的项目：

my-app/
├── backend/       # FastAPI with venv
│   ├── main.py    # from fastapi import FastAPI
│   └── .venv/
├── frontend/      # React with Vite
│   ├── package.json
│   └── src/
└── .env

# 1. Register the project (scans and detects services)
void add my-app F:\projects\my-app

# Void Stack detects:
#   ✓ backend  → uvicorn main:app --host 0.0.0.0 --port 8000
#   ✓ frontend → npm run dev
#   ✓ .venv    → auto-resolves python to virtualenv

# 2. Check dependencies
void check my-app
#   ✅ Python 3.11 (venv detected)
#   ✅ Node 20.x (node_modules up to date)
#   ✅ .env complete vs .env.example

# 3. Start everything
void start my-app
#   [backend]  → http://localhost:8000
#   [frontend] → http://localhost:5173

# 4. Or open the interactive dashboard
void-tui my-app

安装

二进制文件（推荐）

从下载预构建的二进制文件 发布 page——不需要Rust。

Claude桌面扩展 --每个版本还包括 .mcpb 文件（每个平台一个）。放下 .mcpb 在Claude Desktop中安装MCP服务器，无需配置。

二进制文件包括矢量搜索 -发行版的预构建二进制文件包括由BAAI/bge-small-en-v1.5（本地，无API密钥）提供支持的语义代码搜索。嵌入模型（~130MB）首先自动下载 void index 使用。要在不进行矢量搜索的情况下进行构建，请执行以下操作： cargo build --release -p void-stack-cli

macOS注意事项： 如果你得到 *“无法打开，因为无法验证开发人员”*，运行： ``bash xattr -cr /Applications/Void\ Stack.app ``

来源（货物）

# Core CLI (the main tool)
cargo install --git https://github.com/mague/void-stack void-stack-cli

# TUI Dashboard
cargo install --git https://github.com/mague/void-stack void-stack-tui

# MCP Server (for AI integration with Claude Desktop / Claude Code)
cargo install --git https://github.com/mague/void-stack void-stack-mcp

# gRPC Daemon (optional, for persistent management)
cargo install --git https://github.com/mague/void-stack void-stack-daemon

先决条件： 锈 +Protobuf编译器(winget install Google.Protobuf 在Windows上）

从源代码构建

git clone https://github.com/mague/void-stack.git
cd void-stack

# With vector search (recommended):
cargo build --release --features vector

# Minimal build (no ONNX dependency):
cargo build --release

# Binaries in target/release/
#   void              — CLI
#   void-stack-tui    — Terminal dashboard
#   void-stack-daemon — gRPC daemon
#   void-stack-mcp    — MCP server for AI (always includes vector search)

桌面应用程序（Tauri）

cd crates/void-stack-desktop
cargo tauri build
# Generates installer in target/release/bundle/

从分析中排除文件

创建 .voidignore 在项目根目录中排除路径 void analyze:

# Generated code
internal/pb/
vendor/
**/*.pb.go
**/*.pb.gw.go

# Mocks
**/mocks/
**/*_mock.go

语法与 .gitignore （简化）。支持前缀路径， **/ glob后缀和目录名。

特性

• 多业务 --一起或单独启动/停止所有服务
• 跨平台 --窗户(cmd)、macOS、WSL(bash)Docker容器、SSH（未来）
• 自动检测 --扫描目录并识别Python、Node、Rust、Go、Flutter、Docker
• 智能命令 --检测FastAPI、Flask、Django、Vite、Next.js、Express、Air（Go hot reload）并生成正确的命令
• 发射前挂钩 --自动创建venvs，安装deps(pip install, npm install, go mod download)每次服务开始前。无需配置即可开箱即用
• 依赖性检查 --验证Python、Node、CUDA、Ollama、Docker、Rust、， .env
• 实时日志 --来自所有服务的Stout/stderr，具有自动URL检测功能
• 图表 -使用统一的扫描仪从项目结构生成Mermaid和Draw.io（架构、具有Swagger/OpenAPI丰富的API路由、内部/外部API分离、gRPC/Protobuf服务、具有FK-最大布局的DB模型-Prisma、Sequelize、GORM、Django、SQLAlchemy、Drift）
• 代码分析 --依赖图、反模式、圈复杂度、覆盖率
• 最佳实践 --统一评分的本土短绒（反应医生、头领、夹子、golangci棉绒、飞镖分析）
• 技术债务 --带有趋势比较的度量快照
• 人工智能集成 --MCP服务器，配备43个克劳德桌面/克劳德代码工具；通过Ollama（本地LLM）提供AI支持的重构建议，并具有优雅的回退功能。当语义索引存在时，用来自复杂性热点和上帝类的实际代码片段丰富提示
• 语义代码搜索 --使用BAAI/bge-small-en-v1.5嵌入在本地索引任何项目（100%离线，约130 MB一次性下载）。 void search 和那个 semantic_search MCP工具只返回相关的块——比直接读取文件少97.5%的令牌（在135个查询的void堆栈自己的代码库上测量）。
• 结构调用图 --基于树的函数级分析，适用于Rust、Python、JS、TS、Go、Dart、Java、PHP、C、C++和Elixir。坚持 .void-stack/structural.db （或 `%LOCALAPPDATA%\void-stack\structural\

\ WSL主办的项目）。爆炸半径BFS(get_impact_radius`)答案 *“如果我更改此文件，会有什么问题？”* 在你触碰到线之前。

• 增量索引 --Git差异+SHA-256哈希： --git-base HEAD~1 仅重新索引自上次提交以来实际更改的文件。 watch_project （MCP）保存时自动重新索引，500毫秒去抖动； install_index_hook （MCP）连接了一个提交后钩子，这样每次提交都会保持索引的新鲜。
• 磁盘空间扫描仪 --扫描并清理项目deps（node_modules、venv、target）和全局缓存（npm、pip、Cargo、Ollama、HuggingFace、LM Studio）
• 桌面图形用户界面 --Tauri应用程序具有赛博朋克任务控制美学、视觉层次结构（KPI卡、发光效果、严重程度梯度）、服务、日志、依赖关系、图表、分析、文档、安全性、债务和磁盘空间
• 守护进程 --用于持久管理的可选gRPC守护进程
• 安全审计 --依赖漏洞、硬编码秘密、不安全配置、具有智能误报过滤的代码漏洞模式（SQL注入、命令注入、路径遍历、XSS、SSRF等）（跳过自引用检测模式、正则表达式定义、模板、JSX元素、git历史重构提交，以及通过大括号深度跟踪测试模块）
• Docker运行程序 --服务与 target = "docker" 在Docker容器中运行。四种模式：原始docker命令、镜像引用(postgres:16 → auto docker run)，编写自动检测和Dockerfile构建。将导入组合为单个 docker compose up 同时启动所有容器的服务。 docker: 前缀将Docker服务与本地服务分开。根据端口、卷和额外参数的服务配置。进程退出监视器检测故障并自动更新状态
• Docker智能 --解析Dockerfiles和docker-compose.yml，根据框架（Python、Node、Rust、Go、Flutter）自动生成Dockerfiles，使用自动检测的基础架构（PostgreSQL、Redis、MongoDB等）生成docker-compose.yml
• 基础设施智能 --检测Terraform资源（AWS RDS、ElastiCache、S3、Lambda、SQS、GCP Cloud SQL、Azure PostgreSQL）、Kubernetes清单（Deployment、Services、Ingress、StatefulSets）和具有依赖关系的Helm图表——所有这些都集成到架构图中
• 安全 --从不阅读 .env 价值观；集中式敏感文件保护

命令行界面

|读取任何项目文件（blocks.env、credentials）| | void logs [-n lines] [--compact] [--raw] |显示筛选后的服务日志| | void index [--force] [--generate-voidignore] [--git-base ] |语义搜索的索引代码库(--git-base HEAD~1 使用git diff）| | void search "" [-t top_k] |语义代码搜索| | void stats [--project ] [--days ] [--json] |代币储蓄统计| | void claudeignore [--dry-run] [--force] |生成 .claudeignore` 针对技术栈进行了优化|

旗帜： --wsl （WSL路径）， --daemon （连接到守护进程）， --compare （比较快照）， --cross-project （项目间deps）， --label （标签快照）

MCP专用工具（克劳德桌面/克劳德代码/OpenCode）

这些不是CLI命令——它们由 void-stack-mcp:

结构分析灵感来自 代码审查图 （麻省理工学院）。

TUI仪表板

void-tui                # All projects
void-tui my-project     # Specific project
void-tui --daemon       # Via daemon

i18n： 西班牙语（默认）和英语。按 L 切换。

选项卡： 服务（管理/监控）、分析（架构模式、层、反模式、复杂性+覆盖交叉引用）、安全（风险评分、漏洞发现）、债务（TODO/FIXME/HACK标记）、空间（项目+全局磁盘使用）

桌面（Tauri）

带有深色GUI的桌面应用程序：

• 服务：带有状态（正在运行/已停止/失败）、PID、正常运行时间、URL（在浏览器中打开）、启动/停止控制、运行服务上带有品牌颜色发光的技术图标、具有自动平台检测功能的操作系统特定目标徽章（Windows/MOSC/Linux/Docker）、两步服务删除
• 日志：带有服务选择器和自动滚动的实时日志查看器
• 依赖项：检查表的状态、版本、修复建议
• 图表：Mermaid渲染+原生Draw.io XML渲染（带有DOMPurify的自定义SVG渲染器），用于架构、API路由、DB模型
• 分析：架构模式、反模式、圈复杂度、覆盖率可视化
• 文档：使用markdown样式渲染项目README和文档文件
• 磁盘空间：扫描项目+全局缓存、视图大小、删除以释放空间
• 安全：风险评分、漏洞发现、秘密检测、配置审计
• 技术债：带有趋势比较的度量快照，可扩展的细节（上帝类、复杂函数、反模式、循环deps）
• 码头工人：解析和分析现有的Docker工件，生成Dockerfiles和Docker-compose.yml，保存到项目中，检测Terraform/Kubents/Helm基础设施
• 侧边栏：项目导航、添加/删除项目、WSL发行版浏览器
• 用户体验：结果上的复制按钮、教育工具提示、图表缩放控件、Material Design 3排版

MCP服务器（AI集成）

让Claude Desktop、Claude Code或OpenCode直接管理您的项目。

视窗 --添加到 %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "void-stack": {
      "command": "void-stack-mcp.exe"
    }
  }
}

macOS --添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "void-stack": {
      "command": "/Users/YOUR_USERNAME/.cargo/bin/void-stack-mcp"
    }
  }
}

Linux --添加到 ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "void-stack": {
      "command": "void-stack-mcp"
    }
  }
}

开源代码 （免费模型-不需要API密钥）-添加到 ~/.config/opencode/opencode.json:

{
  "mcp": {
    "void-stack": {
      "type": "local",
      "command": ["void-stack-mcp"],
      "enabled": true
    }
  }
}

在macOS上使用完整路径： ["~/.cargo/bin/void-stack-mcp"]

OpenCode优势： 适用于免费型号（MiniMax、Qwen、DeepSeek）-API成本为零，完全无效堆栈MCP集成。

macOS注意事项： Claude Desktop和OpenCode以最小的PATH启动，不包括 ~/.cargo/bin.使用 完全绝对路径 到二进制。跑 which void-stack-mcp 在终端中获取它。还要删除隔离标志，否则macOS将自动阻止二进制文件： ``bash xattr -d com.apple.quarantine ~/.cargo/bin/void-stack-mcp ``

可用工具（42）： list_projects, project_status, start_project, stop_project, start_service, stop_service, get_logs, add_project, remove_project, check_dependencies, read_project_docs, read_all_docs, read_project_file, list_project_files, generate_diagram, analyze_project, audit_project, scan_directory, add_service, save_debt_snapshot, list_debt_snapshots, compare_debt, analyze_cross_project, scan_project_space, scan_global_space, docker_analyze, docker_generate, suggest_refactoring, generate_claudeignore, generate_voidignore, get_token_stats, index_project_codebase, semantic_search, get_index_stats, watch_project, unwatch_project, install_index_hook, build_structural_graph, get_impact_radius, query_graph, full_analysis, manage_suppressions

依赖性检测

代码分析

void analyze my-app -o analysis.md
void analyze my-app --compare --label v2.0
void analyze my-app --cross-project
void analyze my-app --best-practices
void analyze my-app --bp-only         # Only linters, skip architecture

• 模式 --MVC、分层、干净/自信的六边形
• 反模式 --上帝类，循环依赖，脂肪控制，过度耦合
• 圈复杂度 --每个函数（Python、JS/TS、Go、Dart、Rust）
• 覆盖 --LCOV、Cobertura、伊斯坦布尔、Go封面简介
• 图表 --模块关系的美人鱼图
• 趋势 --历史快照与比较

图表

void diagram my-app                 # Draw.io (default)
void diagram my-app -f mermaid      # Mermaid markdown

检测：服务架构、外部服务（通过从源代码和.env中提取URL）、内部服务到服务调用（通过端口交叉引用本地主机）、带有Swagger/OpenAPI丰富的API路由（FastAPI、Flask、Express、gRPC/Protobuf）、内部与公共API分离、DB模型（SQLAlchemy、Django、Prisma、Sequelize、GORM、Drift、Protobuf消息）、Rust机箱关系。

建筑

void-stack/
├── crates/
│   ├── void-stack-core/       # Core library: models, config, runners, detectors, analyzers
│   ├── void-stack-proto/      # Protobuf definitions + gRPC client
│   ├── void-stack-daemon/     # Daemon with gRPC server (tonic)
│   ├── void-stack-tui/        # Terminal dashboard (ratatui)
│   ├── void-stack-mcp/        # MCP server for AI assistants
│   ├── void-stack-desktop/    # Tauri v2 app (React + TypeScript)
│   └── void-stack-cli/        # CLI interface (clap)
├── example-void-stack.toml
└── CHANGELOG.md

配置

void-stack.toml （每个项目）

name = "my-fullstack-app"
description = "Full stack app"
project_type = "node"

[hooks]
install_deps = true

[[services]]
name = "backend-api"
command = "npm run dev"
target = "wsl"
working_dir = "./backend"

[[services]]
name = "web-frontend"
command = "npm run dev"
target = "windows"
working_dir = "./frontend"

[[services]]
name = "database"
command = "docker compose up postgres redis"
target = "docker"

[[services]]
name = "cache"
command = "redis:7-alpine"
target = "docker"
[services.docker]
ports = ["6379:6379"]

全局配置

所有项目都存储在特定于平台的位置：

• 窗户： %LOCALAPPDATA%\void-stack\config.toml
• macOS： ~/Library/Application Support/void-stack/config.toml
• Linux： ~/.config/void-stack/config.toml

每个服务都有一个绝对 working_dir，支持单仓库和分布式布局。

安全

• .env 被阅读为 仅变量名 --值从不存储或显示
• 敏感文件(.env, credentials.json私钥， secrets.*)阻止分析和MCP
• 集中拒绝列表 security.rs 覆盖所有文件读取路径

许可证

该项目根据 Apache许可证2.0。有关详细信息，请参阅LICENSE文件。