ZigNet 的
用于Zig的MCP服务器 --由微调的LLM提供支持的智能代码分析、验证和文档
ZigNet与Claude(和其他兼容MCP的LLM)集成,在不离开聊天界面的情况下提供实时Zig代码分析。
🎯 特性
MCP工具
🔍 analyze_zig — Syntax and type checking with official Zig compiler
使用以下工具分析Zig代码的语法错误、类型不匹配和语义问题 zig ast-check.
示例用法:```typescript
User: "Analyze this Zig code"
Claude: [calls analyze_zig tool]
Response: "✅ Syntax: Valid | Type Check: PASS | Warnings: 0"
**能力:**
- 词汇分析(标记化)
- 语法解析(AST生成)
- 类型检查和验证
- 语义错误检测
- 行/列错误报告
✨ compile_zig — Format and validate Zig code
使用验证和格式化Zig代码 `zig fmt`,生成干净、地道的输出。
**例子:**```zig
// Input (messy)
fn add(a:i32,b:i32)i32{return a+b;}
// Output (formatted)
fn add(a: i32, b: i32) i32 {
return a + b;
}
能力:
- 代码格式化(2空格缩进)
- 语法验证
- 最佳做法执行
- 保留语义
📖 get_zig_docs — AI-powered documentation lookup (coming soon)
使用微调的LLM检索Zig文档和语言功能的解释。
例子:```typescript
Query: "comptime"
Response: "comptime enables compile-time evaluation in Zig..."
**技术支持:**
- 微调Qwen2.5-Coder-7B型号
- Zig 0.13-0.15中的13756个示例
- 专注于高级Zig习惯用法(编译时间、泛型、错误处理)
🔧 suggest_fix — Intelligent error fix suggestions (coming soon)
使用人工智能分析获取Zig错误的智能代码修复建议。
**例子:**```zig
// Error: "Type mismatch: cannot assign string to i32"
var x: i32 = "hello";
// Suggestions:
// Option 1: var x: []const u8 = "hello"; // If you meant string
// Option 2: var x: i32 = 42; // If you meant integer
特征:
- 情境感知建议
- 多种修复选项
- 问题的解释
- Zig成语推荐
📖 用法
ZigNet是一个 MCP服务器 --在MCP客户端中配置一次,然后在对话中自然使用。
🖥️ Claude Desktop
配置文件位置:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json - 视窗:
%APPDATA%\Claude\claude_desktop_config.json
添加以下内容:```json
{
"mcpServers": {
"zignet": {
"command": "npx",
"args": ["-y", "zignet"]
}
}
}
**然后重新启动克劳德桌面** 并开始使用:```
You: "Analyze this Zig code for errors"
[paste code]
Claude: [uses analyze_zig tool]
"Found 1 type error: variable 'x' expects i32 but got []const u8"
🔧 VS Code (with GitHub Copilot)
方法1:VS代码市场(即将推出)
- 开放VS代码扩展(
Ctrl+Shift+X/Cmd+Shift+X) - 搜索
@mcp zignet - 点击 安装
- 重新启动VS代码
方法2:手动配置(现在可用)
- 安装GitHub Copilot扩展(如果尚未安装)
- 打开副驾驶设置
- 添加到MCP服务器配置:```json
{
"mcpServers": {
"zignet": {
"command": "npx",
"args": ["-y", "zignet"]
}
}
}
**然后重新启动VS Code** Copilot将能够访问ZigNet工具。
### 配置后会发生什么?
1. **首次使用**: `npx` 自动下载和缓存ZigNet
1. **Zig编译器**:按需下载(支持Zig 0.13、0.14、0.15)
1. **可用工具**: `analyze_zig`, `compile_zig` (+ `get_zig_docs`, `suggest_fix` 即将到来)
1. **零维护**:通过自动更新 `npx -y zignet`
______________________________________________________________________
## ⚙️ 配置
### GPU选择(多GPU系统)
如果你有多个GPU(例如AMD+NVIDIA),你可以通过环境变量控制ZigNet使用哪个GPU。
**Windows(PowerShell):**```powershell
$env:ZIGNET_GPU_DEVICE="0"
npx -y zignet
macOS/Linux:```bash
export ZIGNET_GPU_DEVICE="0"
npx -y zignet
**VS代码MCP配置与GPU选择:**```json
{
"mcpServers": {
"zignet": {
"command": "npx",
"args": ["-y", "zignet"],
"env": {
"ZIGNET_GPU_DEVICE": "0"
}
}
}
}
带GPU选择的Claude桌面配置:
macOS/Linux (~/.config/Claude/claude_desktop_config.json):```json
{
"mcpServers": {
"zignet": {
"command": "npx",
"args": ["-y", "zignet"],
"env": {
"ZIGNET_GPU_DEVICE": "0"
}
}
}
}
**视窗** (`%APPDATA%\Claude\claude_desktop_config.json`):```json
{
"mcpServers": {
"zignet": {
"command": "npx",
"args": ["-y", "zignet"],
"env": {
"ZIGNET_GPU_DEVICE": "0"
}
}
}
}
GPU设备值:
"0"-仅使用第一个GPU(例如RTX 4090)"1"-仅使用第二个GPU"0,1"-使用两个GPU- 未设置-使用所有可用GPU(默认)
识别您的GPU:```bash
NVIDIA GPUs
nvidia-smi
Output shows GPU indices:
GPU 0: NVIDIA RTX 4090
GPU 1: AMD Radeon 6950XT (won't be used by CUDA anyway)
### 高级配置
所有配置选项都可以通过环境变量进行设置:
|变量|默认值|描述|
|----------|---------|-------------|
| `ZIGNET_GPU_DEVICE` |自动| GPU设备选择(CUDA_VISIBLE_DEDEVICES)|
| `ZIGNET_GPU_LAYERS` |35|GPU上的模型层数(0=仅CPU)|
| `ZIGNET_MODEL_PATH` | `~/.zignet/models/...` |自定义模型路径|
| `ZIGNET_MODEL_AUTO_DOWNLOAD` |true | HuggingFace自动下载模型|
| `ZIGNET_CONTEXT_SIZE` |4096|LLM上下文窗口大小|
| `ZIGNET_TEMPERATURE` |0.7 |法学硕士创造力(0.0-1.0)|
| `ZIGNET_TOP_P` |0.9 | LLM采样参数|
| `ZIG_SUPPORTED` |0.13.0、0.14.0、0.15.2 |支持的Zig版本|
| `ZIG_DEFAULT` |0.15.2 |默认Zig版本|
看 .env.示例 以获取详细示例。
______________________________________________________________________
## 🏗️ 建筑```
┌─────────────────────────────────────────────────────┐
│ Claude / MCP Client │
└────────────────────┬────────────────────────────────┘
│ MCP Protocol (JSON-RPC)
┌────────────────────▼────────────────────────────────┐
│ ZigNet MCP Server (TypeScript) │
│ ┌──────────────────────────────────────────────┐ │
│ │ Tool Handlers │ │
│ │ - analyze_zig │ │
│ │ - compile_zig │ │
│ │ - get_zig_docs │ │
│ │ - suggest_fix │ │
│ └─────────────┬────────────────────────────────┘ │
│ ▼ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Zig Compiler Integration │ │
│ │ - zig ast-check (syntax + type validation) │ │
│ │ - zig fmt (official formatter) │ │
│ │ - Auto-detects system Zig installation │ │
│ │ - Falls back to downloading if needed │ │
│ └─────────────┬────────────────────────────────┘ │
│ ▼ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Fine-tuned LLM (Qwen2.5-Coder-7B) │ │
│ │ - Documentation lookup │ │
│ │ - Intelligent suggestions │ │
│ └──────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
为什么是这种架构?
- 官方Zig编译器 (100%准确,始终保持最新)而不是自定义解析器
- 系统集成 (使用现有的Zig安装(如果可用))
- LLM提供的建议 (get_zig_docs,suggest_fix)代表智力
- 没有外部API调用 (通过Node-Calma-CPP进行本地推理)
- 快速 (验证时间\<100ms,LLM建议时间\<2s)
注: 当Zig发布新版本(例如0.16.0)时,ZigNet将需要根据更新的文档和示例重新训练LLM模型。
🧪 开发状态
组件 · 状态 · 注释
Zig编译器包装器 · ✅ 完成 · ast检查+fmt集成
系统Zig检测 · ✅ 完成 · 自动检测已安装的Zig版本
多版本缓存 · ✅ 完成 · 按需下载Zig 0.13-0.15
MCP服务器 · ✅ 完成 · 所有4个工具均已完全实施
LLM微调 · ✅ 已完成 · 已对13756个Zig示例进行了培训
get_zig_docs · ✅ 完成 · LLM驱动的文档查找
suggest_fix · ✅ 完整 · LLM智能建议
GGUF转换 · ✅ 完整 · Q4_K_M量化(4.4GB)
E2E测试✅ 完成 · 27/27测试通过(8.7s)
克劳德集成 · ⏳ 计划 · 最终部署到Claude Desktop
当前阶段: 准备部署-所有核心功能均已完成
🧪 测试
运行测试```bash
Run all tests (unit + E2E)
pnpm test
Run only E2E tests
pnpm test tests/e2e/mcp-integration.test.ts
Run deterministic tests only (no LLM required)
SKIP_LLM_TESTS=1 pnpm test tests/e2e
Watch mode for development
pnpm test:watch
### 测试覆盖率
**E2E测试套件:** 涵盖所有MCP工具的27项测试
|工具|测试|类型|通过率|
| ------------ | ----- | ------------- | --------- |
|analyze_zig|4|确定性|100%|
|compile_zig|3|确定性|100%|
|get_zig_docs | 5 | LLM供电| 100%|
|suggest_fix | 5 | LLM供电| 100%|
|整合|3|混合|100%|
|性能|3|压力测试|100%|
|边缘情况|4|错误路径|100%|
**执行时间:** 8.7秒(无LLM模型,仅确定性)\
**使用LLM模型:** ~60-120秒(包括模型加载+推理)
### 测试行为
- **确定性测试** (12个测试):始终运行,直接使用Zig编译器
- **LLM测试** (15次测试):如果找不到模型,则自动跳过,优雅降级
- **CI/CD就绪**:在GitHub Actions上运行,不需要GPU
有关详细的测试指南,请参阅 tests/e2e/README.md
______________________________________________________________________
## 📦 项目结构```
zignet/
├── src/
│ ├── config.ts # Environment-based configuration
│ ├── mcp-server.ts # MCP protocol handler
│ ├── zig/
│ │ ├── manager.ts # Multi-version Zig download/cache
│ │ └── executor.ts # zig ast-check + fmt wrapper
│ ├── llm/
│ │ ├── model-downloader.ts # Auto-download GGUF from HuggingFace
│ │ └── session.ts # node-llama-cpp integration
│ └── tools/
│ ├── analyze.ts # analyze_zig tool (COMPLETE)
│ ├── compile.ts # compile_zig tool (COMPLETE)
│ ├── docs.ts # get_zig_docs tool (COMPLETE)
│ └── suggest.ts # suggest_fix tool (COMPLETE)
├── scripts/
│ ├── train-qwen-standard.py # Fine-tuning script (COMPLETE)
│ ├── scrape-zig-repos.js # Dataset collection
│ ├── install-zig.js # Zig version installer
│ └── test-config.cjs # Config system tests
├── data/
│ ├── training/ # 13,756 examples (train/val/test)
│ └── zig-docs/ # Scraped documentation
├── models/
│ └── zignet-qwen-7b/ # Fine-tuned model + LoRA adapters
├── tests/
│ ├── *.test.ts # Unit tests (lexer, parser, etc.)
│ └── e2e/
│ ├── mcp-integration.test.ts # 27 E2E tests
│ └── README.md # Testing guide
├── docs/
│ ├── AGENTS.md # Detailed project spec
│ ├── DEVELOPMENT.md # Development guide
│ └── TESTING.md # Testing documentation
└── README.md # This file
🤖 模型详情
基本型号: Qwen/Qwen2.5码-7B-说明书\
微调: 13756 Zig示例上的QLoRA(4位)\
数据集: 97%的真实世界仓库(Zig 0.13-0.15),3%的文档\
培训: RTX 3090(24GB VRAM),3个历元,约8小时\
输出:
fulgidus/zignet-qwen2.5-coder-7b (拥抱的脸)\
量化: Q4_K_M(节点llama cpp约4GB GGUF)
为什么选择Qwen2.5-Coder-7B?
- 最佳Zig语法理解(与14个模型进行基准测试)
- 现代习语(comptime、泛型、错误处理)
- 快速推理(量化后每个查询约15-20s)
📊 基准测试
| 型号 | 通过率 | 平均时间 | 质量 | 备注 |
|---|---|---|---|---|
| Qwen2.5-Coder-7B | 100% | 29.58s | ⭐⭐⭐⭐⭐ | 精选 -最佳成语 |
| DeepSeek-Coder-6.7B | 100% | 27.86秒 | ⭐⭐⭐⭐⭐ | 说教,冗长 |
| 美洲狮3.2-3B | 100% | 12.27秒 | ⭐⭐⭐⭐ | 良好的平衡 |
| CodeLlama-7B | 100% | 24.61秒 | ⭐⭐⭐ | 混淆Zig/Rust |
| Qwen2.5码-0.5B | 100% | 3.94秒 | ❌ | 发明语法 |
完整基准测试: scripts/test-results/
🛠️ 发展```bash
Run tests
pnpm test
Run specific component tests
pnpm test -- lexer
pnpm test -- parser
pnpm test -- type-checker
Watch mode
pnpm test:watch
Linting
pnpm lint
pnpm lint:fix
Build
pnpm build
```
🤝 贡献
看 代理商.md 详细的项目规范和开发阶段。
当前需求:
- 在各种Zig代码库上进行测试
- 边缘案例发现(解析器/类型检查器)
- 性能优化
- 文档改进
📄 许可证
WTFPL v2 --做他妈的你想做的事公共许可证
🔗 链接
- 存储库: https://github.com/fulgidus/zignet
- 模型(岗位培训): https://huggingface.co/fulgidus/zignet-qwen2.5-coder-7b
- MCP协议: https://modelcontextprotocol.io
- Zig语言: https://ziglang.org
状态: ✅ 第4阶段完成-准备部署(微调完成,E2E测试通过)
