Void Stack

Void Stack

手头有 10 个包含后端、前端、工作进程和数据库的项目，却记不清该如何启动它们？你的 AI Agent 还得读完半个代码库才能弄懂一个项目？

Void Stack 可以解决这两个问题：

• 一条命令启动整个开发技术栈——包括后端、前端、数据库、Docker、WSL。无需记忆端口或命令，无需打开 5 个终端，也无需阅读过时的 README。
• 通过 MCP 为 AI Agent 提供本地上下文引擎——支持混合搜索（BM25 + 精确向量搜索 + Tree-sitter 调用图）、项目地图和入口点。要达到同样的项目理解深度，Agent 读取的文本比手动阅读文件减少约 91 %（实测）。

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

就是这么简单。Void Stack 会扫描你的项目，检测所用的框架（FastAPI、Vite、Express、Django……），生成合适的命令并运行。如果有 Python 虚拟环境，它会找到它。如果缺少 node_modules，它会告诉你。

高性能——使用 Rust 构建。运行时开销为零，启动迅速，占用内存极少。

Agent 工作流——MCP 服务提供 75 种工具，让 Claude Desktop / Claude Code 能够自主管理服务、搜索和绘制代码地图、跨项目检查 API 契约并审计安全性。只需要代码上下文？void-stack-mcp --tools context 可提供 20 种代码上下文工具，并将每个会话中的工具定义减少 64 %（55,147 → 20,025 个字符）。

云原生路线图——通过同一份配置部署到 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)

推动重构的发现：

发现	采取的措施
上帝类：cli/main.rs（1202 LOC，25 fn）	拆分为 6 个命令模块（main 约 250 LOC）
上帝类：mcp/server.rs（1197 LOC，35 fn）	拆分为 10 个工具模块（server 约 340 LOC）
上帝类：manager.rs（30 fn）	拆分为 4 个子模块（process、state、logs、url）
上帝类 + 臃肿控制器：vuln_patterns.rs（789 LOC）	按类别拆分为 5 个模块（injection、xss、network、crypto、config）
上帝类：db_models.rs（1065 LOC）	按数据库格式拆分为 7 个子模块（python、sequelize、gorm、drift、proto、prisma）
上帝类：generate_dockerfile.rs（821 LOC）	按语言拆分为 6 个子模块（python、node、rust、go、flutter）
上帝类：api_routes.rs（747 LOC）	按协议拆分为 5 个子模块（python、node、grpc、swagger）
上帝类：architecture.rs（788 LOC）	拆分为 4 个子模块（externals、crates、infra）
上帝类：classifier.rs（759 LOC，44 fn）	拆分为 3 个子模块（logic、signals/data tables、tests）
臃肿控制器：cli/analysis.rs（580 LOC）	拆分为 4 个子模块（analyze、diagram、audit、suggest）
CC=42：analyze_best_practices	改为表驱动的 lint 工具注册表（CC 约 15）
CC=41：cmd_analyze	提取 11 个辅助函数（CC 约 10）

技术债务跟踪

void analyze void-stack --compare --label v0.31.0
# Pattern: Layered (80% confidence)
# Coverage: 83.0% (latest lcov snapshot — core at 90.6%)
# Explicit debt: 34 markers (TODO: 11, TEMP: 10, OPTIMIZE: 6, BUG: 3, XXX: 2, FIXME: 1, HACK: 1)
# 2313 tests passing across the workspace (desktop app not included)

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

---

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

大多数 AI 工具都迫使你二选一：语义搜索（查找相关概念）或结构图（追踪调用链）。Void Stack 将两者结合起来。向量嵌入可查找概念相关的内容。Tree-sitter 图可显示哪些结构会被破坏。最终结果是：精准的上下文，单一方法的工具无法企及。

方法	查询	结果
仅语义	“auth middleware flow”	概念相关的代码块
仅结构	“callers of validateToken”	直接调用链
混合（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

# Get the lay of the land first: packages, entry files, key docs; then every entry point
void map my-project
void entrypoints my-project --kind rest,cli

# Search by concept, not by filename
void search my-project "authentication middleware flow"
# Returns the 5 most relevant hits, compact: path:lines, symbol, the matching lines
# (--detail full for whole chunks; MCP agents expand a hit with get_chunk)

# 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, 14 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)

默认情况下，结果是精简的——位置、符号和匹配的行；同一连接上已发送过的命中结果会以带 ↺ 标记的精简形式返回，而不是返回完整内容（不会隐藏：共享同一连接的子 Agent 仍然能看到）。仅包含导入语句的代码块会被跳过；除非查询中提及，否则测试、文档和变更日志的排名会较低。

默认采用混合搜索：BM25（SQLite FTS5，完整保留 snake_case 标识符）与向量结果通过 Reciprocal Rank Fusion 融合——即使嵌入未能匹配，stop_unix_process_group 这类精确标识符也能命中。模式：hybrid | vector | lexical。

0.36 与 0.35 对比（Windows，已注册 70 个项目，通过 MCP 服务执行相同查询）

指标	0.35	0.36	变化
理解一个项目（morrocoy，一个含 430 个文件的 Flutter 应用）：相同的 5 个问题	10,586 个字符	10,556 个字符	比手动阅读所需的 13 个文件（114,236 个字符）少 91 %
get_api_contracts iunci（Flutter）	410,176 个字符	33,222 个字符	减少 92 %
get_api_contracts iunci-backend（Go）	234,464 个字符	30,527 个字符	减少 87 %
list_entrypoints iunci	23,139 个字符，41 个实际路由	4,701 个字符，97 个实际路由	减少 80 %（移除了 1,475 份 vendored .proto 副本）
check_contracts（3 个项目的平均值）	20.5 秒	0.89 秒	快 23 倍
每个会话的工具定义（0.36 使用 --tools context）	55,147 个字符	20,025 个字符	减少 64 %
build_structural_graph morrocoy	2.9 秒	0.8 秒	更快

将 project_map 和 list_entrypoints 加入这 5 个问题后，总计为 18,055 个字符（比手动操作少 84 %），并列出了该应用的 70 个 MCP 工具。在 0.33 中，相同的 5 个问题返回约 49,000 个字符（估算值，测于较早的一台机器）。check_contracts 变快，是因为大小和修改时间未变化的文件会跳过，不再重新读取；同时，生产者会并行扫描。

在 GPU 上编制索引（0.36 新增；Windows、DirectML、RTX 4070 Ti SUPER）：

项目	区块数	CPU	GPU	加速比
iunci	12,206	740–1,003 秒	73–75 秒	约 10–13 倍
void-stack	6,467	623 秒	40 秒	约 16 倍
morrocoy	1,371	101–281 秒	22 秒（新二进制文件首次运行时为 38 秒，因为 DirectML 正在编译着色器）	—

生成的嵌入与 CPU 生成的完全相同（全部 12,206 个区块的余弦相似度均为 1.000000），搜索返回的结果也相同。

0.35 与 0.34 对比（11 个真实项目，同一台机器，通过 MCP 服务执行相同查询）

会话	0.34 令牌数	0.35 令牌数	减少量
“列出每项功能”（映射 + 入口点 + 8 次搜索），8 个项目	177,136	48,586	减少 3.6 倍
从 git 历史记录中提取的 140 次搜索（7 个项目）	332,233	60,494	减少 5.5 倍
在一个会话中重复询问相同的 4 个问题	37,992	4,358	减少 8.7 倍
跨项目（3 个主题 × 3 个项目 + 跨项目 GraphRAG + 合约）	109,391	7,833	减少 14 倍

检索质量相同或更好（在 140 个 git 历史记录查询中，hit@5 从 0.679 升至 0.686，recall@5 从 0.514 升至 0.538）；排名前 5 的噪声结果（测试、仅导入代码块、变更日志）从 180 个降至 54 个；搜索延迟不变（p50 约 10 毫秒）。此外，在一个包含 21 个 crate 的工作区中，project_map 找到了全部 21 个包，而仅搜索的清单只找到了 8 个。编制索引的时间和峰值 RAM 与 0.34 相同。运行 void bench <project> --task queries.txt 可复现每个查询的数据。

基准测试（在 void-stack 本身上测得）

操作	不使用索引	使用 void-stack	减少比例
semantic_search（平均）	约 170 行 / 文件	约 4 行 / 结果	97.5 %
理解一个模块	读取 5-10 个文件	1 条搜索查询	约 10 倍
变更的影响范围	手动，耗时数小时	get_impact_radius	即时

97.5 % 的数据由 void stats --days 90 报告，统计了 135 次 semantic_search 操作——23 868 行源代码从未进入大模型上下文。

占用空间（v0.33，Windows，从头为 void-stack 建立索引，约 3,000 个分块）：耗时约 110 s，峰值 RAM 约 650 MB；v0.31 为 193 s 和 4.2 GB。向量搜索为精确搜索（int8 向量，召回率 1.0），索引在内存中占用 7.3 MB。详情见 CHANGELOG。

GPU 索引（0.36）：在 Windows 上，void index 通过 DirectML 使用 GPU 生成嵌入（适用于任何 DirectX 12 GPU：NVIDIA、AMD、Intel），无需额外安装；如果没有 GPU，则回退到 CPU。搜索仍在 CPU 上为查询生成嵌入（耗时几毫秒）。VOID_STACK_EMBED_DEVICE=cpu 可强制使用 CPU。GPU 批次大小默认为 32（可通过 VOID_STACK_EMBED_BATCH 覆盖；批次大小为 32 时使用 +2.5 GB 显存，128 时使用 +8.8 GB，速度相同）。macOS 和 Linux 目前使用 CPU 建立索引。索引完成后，CLI 会打印 embeddings: GPU (DirectML) 或 embeddings: CPU。

支持的语言

• 语义索引（嵌入）：CODE_EXTENSIONS 中的所有源代码扩展名——Rust、Python、JS/TS、Go、Dart、Java、PHP、C/C++、C#、Ruby、Swift、Kotlin、Lua、Zig、Elixir、Verse、GDScript、MQL4/MQL5、Vue、Svelte、Astro，以及 md/proto/sql/dockerfile。
• 结构图（Tree-sitter）：Rust、Python、JavaScript、TypeScript（+ TSX）、Go、Dart、Java、PHP、C、C++、Elixir、C#、Swift、GDScript、MQL4/MQL5（C++ 语法）。
• 依赖图（导入）：Python、JS/TS、Go、Dart、Rust、Verse、C#、Swift、GDScript、C/C++、MQL4/MQL5——C# 会将 using 链接到声明相应命名空间的文件，Swift 会将 import 链接到 SwiftPM 目标，GDScript 会解析 res:// 路径和 class_name，C/C++ 会像 Unreal 的模块包含路径一样解析 #include "…"，MQL 会根据终端的 Include/ 文件夹解析 #include <…>。
• 游戏引擎：可根据标记识别 Unity（C#）、Unreal Engine（C++ / UEFN Verse）和 Godot（GDScript / C#）项目；所有扫描器都会跳过其缓存 / 构建文件夹（Library/、Intermediate/、.godot/ 等），并在 Space 面板中提供清理选项。
• MetaTrader：可识别 MQL4/MQL5 项目（.mq4/.mq5/.mqh，或 MQL4/MQL5 数据文件夹）；会自动读取 MetaEditor 的 UTF-16 源文件，终端事件处理程序（OnInit、OnTick、OnCalculate 等）不会被报告为死代码，并排除已编译的 .ex4/.ex5 文件。

结构分析受 code-review-graph（MIT）启发——AST 节点映射和 BFS 查询逻辑已使用 Rust 原生重写。

---

接口

Void Stack 有 4 个接口——任选其一：

接口	描述
CLI（void）	在终端中运行快速命令
TUI（void-stack-tui）	交互式终端仪表板：服务、分析、安全审计、技术债务、空间
桌面版（void-stack-desktop）	带 GUI 的桌面应用（Tauri + React）——Windows（.msi）、macOS（.dmg）、Linux（.deb）
MCP Server（void-stack-mcp）	与 Claude Desktop / Claude Code 集成

端到端示例：30 秒搭建 FastAPI + 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

安装

二进制文件（推荐）

从 Releases 页面下载预构建的二进制文件——无需 Rust。

平台	文件
Windows	.msi / .exe（NSIS）
macOS	.dmg
Linux	.deb / .AppImage

Claude Desktop Extension — 每个版本还包含 .mcpb 文件（每个平台一个）。将 .mcpb 拖入 Claude Desktop，即可零配置安装 MCP 服务。

二进制文件包含向量搜索 — Releases 中的预构建二进制文件包含由 BAAI/bge-small-en-v1.5 提供支持的语义代码搜索（本地运行，无需 API 密钥）。嵌入模型（约 130MB）会在首次使用 void index 时自动下载。若要在不含向量搜索的情况下构建：cargo build --release -p void-stack-cli

**macOS 提示：**如果遇到 “无法打开，因为无法验证开发者”，请运行：

xattr -cr /Applications/Void\ Stack.app

从源代码构建（Cargo）

# 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

前置要求：Rust + Protobuf 编译器（Windows 上运行 winget install Google.Protobuf）

从源代码构建

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/

以差异为中心的工作流：测试选择与适用于大模型的代码审查

两个工具可缩短大型代码库中的实现 → 测试 → 审查循环：

suggest_tests_for_diff — 只运行覆盖你所做差异的测试。反向覆盖映射（测试 → 结构图上的 BFS 被调用函数，缓存在 SQLite 中）会将变更的符号映射到覆盖它们的测试，并按调用距离排序，同时提供明确的 未覆盖 列表和可直接粘贴的命令：

$ void suggest-tests void-stack
## Suggested tests (3 for 7 changed symbols)
- `test_stop_one_waits_for_child_exit` — crates/void-stack-core/src/manager/process.rs:441 (hop 1)
## Uncovered (1)
- ⚠️ `render_html` — crates/void-stack-core/src/diagram/graph_html.rs:289 has NO covering tests
## Run
cargo test -p void-stack-core test_stop_one_waits_for_child_exit

review_diff — 为当前差异生成精简（≤4k 个 token）的审查负载，作为 LLM 审查者的输入：摘要、仅针对变更行的审计发现（考虑抑制规则）、带跳数标签的影响范围、测试覆盖情况，以及最关键符号的 1 跳调用上下文：

$ void review void-stack --git-base main
# Review — void-stack (vs `main`)
## Summary
- 12 files changed, +840 / -95 lines
## Findings on changed lines (1) | Suppressed: 2
- [medium] Use of .unwrap() in production code — `crates/.../db.rs:44` → Replace with '?'
## Blast radius (depth 2)
- `crates/void-stack-mcp/src/tools/search.rs`: semantic_search (hop 1) ...

工作流：每批编辑后运行建议的测试（而非完整测试套件）；每次提交前运行 review_diff，并处理 Critical/High 级发现以及未覆盖列表。skills/skill-void-stack 技能会在 Claude Code 会话中贯彻这些规则。

安全与信任模型

Void Stack 是一个服务启动器：void-stack.toml（以及已注册服务）中的 command 字符串会通过平台 Shell（Unix 上为 sh -c，Windows 上为 cmd /c）以你的权限原样执行。这是有意设计的——但这意味着项目配置属于可信输入。

• 切勿启动尚未审查过的仓库中的服务：恶意的 void-stack.toml 可以运行任意代码。
• 守护进程会在执行新加载项目的服务命令前请求一次性确认。批准记录保存在用户配置目录中（Linux 上为 ~/.config/void-stack/trusted-projects.json，macOS 上为 ~/Library/Application Support/void-stack/）——不会保存在项目内；并且记录与确切命令集的哈希绑定，因此命令发生任何变化都会再次请求批准。使用 void-daemon start --yes 可进行非交互式批准（CI、脚本）。
• 批准前请检查列出的命令；删除 trusted-projects.json 中的项目条目，即可再次收到询问。

在 MCP 客户端中注册

void setup            # detects Claude Desktop/Code, Cursor, Windsurf, Cline, VS Code
void setup --dry-run  # see what would change first

从分析中排除文件

在项目根目录创建 .voidignore，以从 void analyze 中排除路径：

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

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

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

功能

• 多服务 — 可同时或单独启动／停止所有服务
• 跨平台 — Windows（cmd）、macOS、WSL（bash）、Docker 容器、SSH（未来支持）
• 自动检测 — 扫描目录并识别 Python、Node、Rust、Go、Flutter、Docker、Elixir、Unreal Engine / UEFN（.uproject、.uplugin、.verse）、Unity（ProjectSettings/ProjectVersion.txt）、Godot（project.godot）和 Swift（Package.swift、.xcodeproj）
• 智能命令 — 检测 FastAPI、Flask、Django、Vite、Next.js、Express、Air（Go 热重载），并生成合适的命令
• 启动前钩子 — 启动每项服务前自动创建 venv、安装依赖（pip install、npm install、go mod download）。开箱即用，无需配置
• 依赖检查 — 验证 Python、Node、CUDA、Ollama、Docker、Rust、.env
• 实时日志 — 显示所有服务的 Stdout/stderr，并自动检测 URL
• 看板 — 经过 Git 版本管理的 BOARD.md（命令行、MCP 和桌面应用）：提供每项任务的历史记录和工作时间线，通过一次批量 Git 读取从看板的 git 日志重建（速度快，即使在 Windows 上也如此；此前逐次提交启动进程可能耗时数秒）；也支持托管在 WSL 中的项目（\\wsl.localhost\… 路径会通过 wsl.exe 调用 git）
• 图表 — 使用统一扫描器，根据项目结构生成 Mermaid 和 Draw.io 图表（架构、API 路由及 Swagger/OpenAPI 补充信息、内部／外部 API 分离、gRPC/Protobuf 服务、采用 FK 邻近布局的数据库模型——Prisma、Sequelize、GORM、Django、SQLAlchemy、Drift）
• 代码分析 — 依赖关系图、反模式、圈复杂度、覆盖率
• 最佳实践 — 使用原生代码检查工具（react-doctor、ruff、clippy、golangci-lint、dart analyze）并统一评分
• 技术债务 — 指标快照及趋势对比
• AI 集成 — MCP 服务包含 75 个工具，可供 Claude Desktop / Claude Code 使用；通过 Ollama（本地 LLM）提供 AI 驱动的重构建议，并在无法使用时优雅回退。存在语义索引时，会使用复杂度热点和上帝类中的实际代码片段补充提示词
• 语义代码搜索 — 使用 BAAI/bge-small-en-v1.5 嵌入向量在本地为任意项目建立索引（完全离线，仅需一次性下载约 130 MB）。void search 和 semantic_search MCP 工具只返回相关代码块——相比直接读取文件，Token 数量减少 97.5 %（基于对 void-stack 自有代码库执行 135 次查询所得的测量结果）。
• 结构化调用图 — 基于 Tree-sitter 的函数级分析，支持 Rust、Python、JS、TS、Go、Dart、Java、PHP、C、C++（包括 Unreal Engine）、Elixir、C#（Unity / Godot .NET）、Swift 和 GDScript（Godot）。Verse（UEFN）由导入分析器、语义索引和债务扫描器支持（目前尚无对应的 Tree-sitter 语法）。数据持久化至 .void-stack/structural.db（WSL 托管项目则存储在 %LOCALAPPDATA%\void-stack\structural\<project>\）。影响范围 BFS（get_impact_radius）可在修改任何代码之前回答 “如果我更改此文件，哪些内容会受影响？”
• 增量索引 — 使用 Git diff 和 SHA-256 哈希：--git-base HEAD~1 只会为上次提交以来实际更改的文件重新建立索引。watch_project（MCP）会在保存文件后自动重新建立索引，并采用 500 ms 防抖；install_index_hook（MCP）会配置提交后钩子，确保每次提交后索引都是最新的。
• 磁盘空间扫描器 — 扫描并清理项目依赖项（node_modules、venv、target）和全局缓存（npm、pip、Cargo、Ollama、HuggingFace、LM Studio）
• 桌面 GUI — Tauri 应用，采用赛博朋克任务控制中心风格，具有清晰的视觉层级（KPI 卡片、发光效果、严重程度渐变），并提供服务、日志、依赖项、图表、分析、文档、安全、债务和磁盘空间功能
• 守护进程 — 可选的 gRPC 守护进程，用于持久化管理
• 安全审计 — 检查依赖项漏洞、硬编码密钥、不安全配置和代码漏洞模式（SQL 注入、命令注入、路径遍历、XSS、SSRF 等），并通过智能误报过滤进行筛选（借助花括号深度跟踪，跳过自引用检测模式、正则表达式定义、模板、JSX 元素、Git 历史中的重构提交和测试模块）
• Docker 运行器 — target = "docker" 的服务会在 Docker 容器中运行。提供四种模式：原始 docker 命令、镜像引用（postgres:16 → 自动执行 docker run）、Compose 自动检测和 Dockerfile 构建。Compose 会作为单个 docker compose up 服务导入，并一次性启动所有容器。docker: 前缀用于区分 Docker 服务和本地服务。可按服务配置端口、卷和额外参数。进程退出监视器会自动检测失败并更新状态
• Docker 智能功能 — 解析 Dockerfile 和 docker-compose.yml，按框架自动生成 Dockerfile（Python、Node、Rust、Go、Flutter），并根据自动检测到的基础设施（PostgreSQL、Redis、MongoDB 等）生成 docker-compose.yml
• 基础设施智能功能 — 检测 Terraform 资源（AWS RDS、ElastiCache、S3、Lambda、SQS、GCP Cloud SQL、Azure PostgreSQL）、Kubernetes 清单（Deployments、Services、Ingress、StatefulSets）和带依赖项的 Helm 图表——全部集成到架构图中
• 安全 — 从不读取 .env 的值；集中保护敏感文件

CLI

Command	Description
void add <n> <path> [--tag T]	注册项目（自动检测服务）
void tag <project> [TAGS…] [--remove T] [--clear]	将项目标记为自己的（own / propio）或他人的（third-party / tercero），也可添加任意标签
void add-service <project> <n> <cmd> -d <dir>	手动添加服务
void edit-service <project> <svc> [-c CMD] [-d DIR] [-t TARGET] [--rename N] [--enable|--disable]	编辑服务（例如，修正自动检测到的无效命令）
void remove-service <project> <svc>	从项目中移除服务
void remove <n>	注销项目
void list [--tag T]	列出项目和服务（仅显示带有标签的项目）
void scan <path>	预览检测结果，但不注册
void start <project> [-s service]	启动所有服务或指定服务
void stop <project> [-s service]	停止所有服务或指定服务
void status <project>	实时状态：PID、URL、运行时长
void check <project>	验证依赖项
void diagram <project> [-f mermaid|drawio] [--print-content]	生成图表
void audit <project> [-o file]	安全审计
void analyze <project> [--compare] [--cross-project] [--best-practices]	代码分析
void docker <project> [--generate-dockerfile] [--generate-compose] [--save]	Docker 智能分析
void suggest <project> [--model <m>] [--service <s>] [--raw]	AI 重构建议（Ollama）
void read-file <project> <path>	读取任意项目文件（会阻止读取 .env 和凭据）
void logs <project> <service> [-n lines] [--compact] [--raw]	显示筛选后的服务日志
void index <project> [--force] [--generate-voidignore] [--git-base <ref>]	为语义搜索建立代码库索引（--git-base HEAD~1 使用 git diff）
void search <project> "<query>" [-t top_k] [--detail compact|full|auto]	语义代码搜索（默认以紧凑形式显示命中结果：位置、符号、匹配行）
void map <project> [--depth N]	项目地图：包、入口文件、各目录中的代码、关键文档
void entrypoints <project> [--kind rest,grpc,mcp,cli,routes,jobs]	所有入口点：HTTP 路由、RPC、MCP 工具、CLI 命令、UI 路由、作业
void contracts check <project>	将所消费的 API 路由/RPC 与提供这些接口的已注册项目进行核对（发现偏差时以非零状态码退出）
void bench <project> --task <file> [--json]	每次查询的 Token 数：比较紧凑输出、完整分块与读取整个文件
void stats [--project <p>] [--days <d>] [--json]	Token 节省统计
void claudeignore <project> [--dry-run] [--force]	根据技术栈生成优化的 .claudeignore 文件

标志： --wsl（WSL 路径）、--daemon（连接到守护进程）、--compare（比较快照）、--cross-project（跨项目依赖）、--label <tag>（为快照添加标签）

MCP 专用工具（Claude Desktop / Claude Code / OpenCode）

这些不是命令行命令，而是由 void-stack-mcp 提供：

工具	描述
get_chunk	展开精简的搜索结果：文件中 line_start..=line_end 行
watch_project / unwatch_project	文件更改时自动重新索引（防抖约 500 ms）
install_index_hook	安装 post-commit 钩子，为更改的文件重新建立索引
build_structural_graph	跨 14 种语言的 Tree-sitter 调用图——Rust、Python、JS、TS、Go、Dart、Java、PHP、C、C++、Elixir、C#、Swift、GDScript + MQL4/MQL5（--features structural）
get_impact_radius	影响范围 BFS——文件更改会影响哪些对象
query_graph	在结构图中查询调用方 / 被调用方 / 测试 / 模糊搜索
full_analysis	在一份报告中汇总审计 + 架构 + 语义热点（quick/standard/deep）
manage_suppressions	列出 / 添加 / 移除审计抑制规则，无需手动编辑文件
setup_project	一键上手：注册 + 生成忽略规则 + 建立索引 + 审计 + 分析

结构分析的灵感来自 code-review-graph（MIT）。

TUI 仪表板

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

按键	操作
a	启动所有服务
s	启动选定的服务
k	停止选定的服务
K	停止所有服务
1-5	切换标签页（服务/分析/安全/债务/空间）
R	在当前标签页运行操作（分析、审计、扫描）
j/↓	向下导航
l	切换日志面板
Tab	切换面板
r	刷新状态
L	切换语言（ES/EN）
?	帮助
q	退出（停止服务）

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

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

桌面应用（Tauri）

桌面应用采用四区布局（顶栏 + 侧边栏）、⌘K 命令面板和项目智能脉搏线。面板分为 运行（服务、日志、Docker）、智能（搜索、审查、测试、死代码、分析、安全、技术债）、地图（图谱、图表、统计）和 项目（依赖、文档、磁盘空间）。

• 顶栏：项目选择器，支持就地重命名/移动（保留索引）和快速添加；⌘K 命令面板（服务 + 操作 + 语义搜索回退）；索引/图谱新鲜度指标（点击即可重建图谱）；语言切换（ES/EN）
• 脉搏线：一行展示项目智能信息——审查发现、建议/未覆盖的测试、死代码数量、审计风险；并行获取，并按项目缓存
• 服务：卡片网格，显示状态圆点、语言徽标、端口链接（在浏览器中打开）、运行时长、最后一行日志，并提供启动/停止和移除操作；另有幽灵样式的“添加服务”卡片
• 日志：结构化查看器（级别筛选、搜索、跟随模式、换行/原始内容切换、在包含检测到的路径的错误行上显示“影响”），另有可折叠抽屉，位于服务网格下方
• 搜索：可从 UI 使用语义搜索、GraphRAG（语义 + 结构化调用图）和跨项目 GraphRAG；点击结果可在编辑器中跳转到对应行
• 图谱：应用内交互式依赖图查看器（Cytoscape）——按重要性调整节点大小、高亮邻域、切换布局、按层/社区着色；点击文件即可在 VS Code / Cursor / Windsurf 中打开
• 图表：使用 Mermaid + 原生 Draw.io XML 渲染（自定义 SVG 渲染器，搭配 DOMPurify），用于架构、API 路由和数据库模型
• 分析 / 安全 / 技术债：架构模式、反模式、复杂度、覆盖率；风险评分、漏洞/机密信息发现；指标快照及趋势对比
• 文档 / 磁盘空间 / Docker：Markdown 文档；扫描并清理缓存；解析/生成 Docker 工件，并检测 Terraform/Kubernetes/Helm
• 用户体验：Geist + JetBrains Mono 字体、focus-visible 焦点环、减少动态效果支持、教学提示工具、复制按钮

MCP 服务（AI 集成）

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

Windows — 添加到 %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"
    }
  }
}

OpenCode（免费模型——无需 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 费用，完整集成 void-stack MCP。

macOS 提示：Claude Desktop 和 OpenCode 启动时使用精简 PATH，其中不包含 ~/.cargo/bin。请使用二进制文件的完整绝对路径。在终端运行 which void-stack-mcp 获取路径。另外，请移除隔离标记，否则 macOS 会静默阻止该二进制文件：

xattr -d com.apple.quarantine ~/.cargo/bin/void-stack-mcp

远程客户端：流式 HTTP（--http）

上面的每个配置都会通过 stdio 启动服务——每个客户端对应一个进程，运行在同一台机器上。--http 则通过 MCP 流式 HTTP 提供相同的工具，这样其他机器上的客户端（或 WSL 内的客户端）可以共用一个服务和一个项目注册表：

void-stack-mcp --http 127.0.0.1:7400   # localhost only
void-stack-mcp --http 7400             # same thing, bare port = loopback
void-stack-mcp --http 0.0.0.0:7400     # reachable from your tailnet/LAN

任何支持 HTTP 的 MCP 客户端都可以注册它——/ 和 /mcp 均可：

claude mcp add --transport http void-stack http://localhost:7400

典型用法：在 Windows 上运行服务，并从 WSL（设置 networkingMode=mirrored 后，localhost 可以互通）或通过 Tailscale 从其他机器访问。工具会读取其所在主机上的注册表，因此所有客户端看到的项目都相同。

无身份验证。 HTTP 传输按设计不提供身份验证：任何能访问该端口的人都可以完全访问你的项目。请将其限制在环回地址或 tailnet 中——如果绑定地址既不是环回地址，也不属于 Tailscale 地址范围（100.64.0.0/10、fd7a:115c:a1e0::/48），服务会在启动时记录警告。不要将其暴露到公网上；请在其前面配置 Tailscale（或经过身份验证的反向代理）。

一个进程只能提供 stdio 或 HTTP，不能同时提供两者。如需同时使用，请运行第二个进程。

更少的工具，更少的令牌（--tools）

每个客户端都会在上下文中收到所有工具的定义：每次会话共 75 个工具，合计 55,147 个字符。使用配置档、逗号分隔的工具名称列表，或两者结合，只提供客户端所需的工具——--tools context 可将每次会话的工具定义减少 64 %（从 55,147 减至 20,025 个字符）：

void-stack-mcp --tools context            # 20 code-context tools, 20,025 characters
void-stack-mcp --tools devops,get_chunk   # services + one extra tool
VOID_STACK_MCP_TOOLS=review void-stack-mcp

配置档：context（映射、入口点、搜索、图、契约、文档）、devops（项目、服务、日志、依赖项、Docker）、review（审计、分析、技术债、差异审查、看板）。默认配置和 full：包含所有工具。

在客户端配置中，将配置档传入 args：

{
  "mcpServers": {
    "void-stack": {
      "command": "void-stack-mcp",
      "args": ["--tools", "context"]
    }
  }
}

可用工具（75 个）： list_projects、project_status、start_project、stop_project、start_service、stop_service、get_logs、add_project、read_project_docs、read_all_docs、read_project_file、list_project_files、generate_diagram、check_dependencies、analyze_project、audit_project、remove_project、update_project、scan_directory、add_service、update_service、remove_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、get_token_stats、index_project_codebase、semantic_search、get_chunk、project_map、list_entrypoints、get_index_stats、watch_project、unwatch_project、install_index_hook、build_structural_graph、get_impact_radius、query_graph、generate_voidignore、cluster_project_index、get_cluster_stats、get_communities、graph_rag_search、find_dead_code、review_diff、check_env、check_contracts、suggest_commit_message、session_handoff、daily_briefing、doctor、session_context、board_list、board_add_task、board_move_task、sync_todos、board_archive_done、board_history、board_timeline、commit_detail、board_link_task、suggest_tests_for_diff、get_api_contracts、graph_rag_search_cross、generate_graph_html、full_analysis、manage_suppressions、setup_project

依赖项检测

检测器	检查内容
Python	二进制文件、版本、venv、pip check
Node	二进制文件、node_modules 新鲜度
CUDA	nvidia-smi、驱动、GPU、VRAM、PyTorch
Ollama	二进制文件、API 健康状态、已下载的模型
Docker	二进制文件、守护进程状态、compose
Rust	rustc 和 cargo 版本
Go	go version、是否存在 go.mod
Flutter	flutter --version、dart --version、pubspec.yaml
.env	比较 .env 与 .env.example

代码分析

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、Istanbul、Go 覆盖率配置文件
• 图表 — 展示模块关系的 Mermaid 图
• 趋势 — 带对比功能的历史快照

图表

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

检测内容：服务架构、外部服务（通过从源代码和 .env 提取 URL 识别）、内部服务间调用（通过端口交叉引用 localhost）、经 Swagger/OpenAPI 丰富的 API 路由（FastAPI、Flask、Express、gRPC/Protobuf）、内部 API 与公共 API 的区分、数据库模型（SQLAlchemy、Django、Prisma、Sequelize、GORM、Drift、Protobuf 消息）、Rust crate 关系。

架构

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"]

全局配置

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

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

每个服务都有一个绝对路径的 working_dir，支持 monorepo 和分布式布局。

安全

• .env 只读取变量名，绝不存储或显示变量值
• 敏感文件（.env、credentials.json、私钥、secrets.*）禁止用于分析和 MCP
• security.rs 中的集中式拒绝列表涵盖所有文件读取路径

许可证

本项目采用 Apache License 2.0 许可。详情请参阅 LICENSE 文件。