zignet (Fulgidus)

ZigNet 的

用于Zig的MCP服务器 --由微调的LLM提供支持的智能代码分析、验证和文档

ZigNet与Claude（和其他兼容MCP的LLM）集成，在不离开聊天界面的情况下提供实时Zig代码分析。

______________________________________________________________________

🎯 特性

MCP工具

🔍 analyze_zig — Syntax and type checking with official Zig compiler

使用以下工具分析Zig代码的语法错误、类型不匹配和语义问题 zig ast-check.

示例用法：

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，生成干净、地道的输出。

例子：

// 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文档和语言功能的解释。

例子：

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错误的智能代码修复建议。

例子：

// 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

添加以下内容：

{
  "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代码市场（即将推出）

1. 开放VS代码扩展(Ctrl+Shift+X / Cmd+Shift+X)
2. 搜索 @mcp zignet
3. 点击 安装
4. 重新启动VS代码

方法2：手动配置（现在可用）

1. 安装GitHub Copilot扩展（如果尚未安装）
2. 打开副驾驶设置
3. 添加到MCP服务器配置：

{
  "mcpServers": {
    "zignet": {
      "command": "npx",
      "args": ["-y", "zignet"]
    }
  }
}

然后重新启动VS Code Copilot将能够访问ZigNet工具。

配置后会发生什么？

1. 首次使用: npx 自动下载和缓存ZigNet
2. Zig编译器：按需下载（支持Zig 0.13、0.14、0.15）
3. 可用工具: analyze_zig, compile_zig (+ get_zig_docs, suggest_fix 即将到来）
4. 零维护：通过自动更新 npx -y zignet

______________________________________________________________________

⚙️ 配置

GPU选择（多GPU系统）

如果你有多个GPU（例如AMD+NVIDIA），你可以通过环境变量控制ZigNet使用哪个GPU。

Windows（PowerShell）：

$env:ZIGNET_GPU_DEVICE="0"
npx -y zignet

macOS/Linux：

export ZIGNET_GPU_DEVICE="0"
npx -y zignet

VS代码MCP配置与GPU选择：

{
  "mcpServers": {
    "zignet": {
      "command": "npx",
      "args": ["-y", "zignet"],
      "env": {
        "ZIGNET_GPU_DEVICE": "0"
      }
    }
  }
}

带GPU选择的Claude桌面配置：

macOS/Linux (~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "zignet": {
      "command": "npx",
      "args": ["-y", "zignet"],
      "env": {
        "ZIGNET_GPU_DEVICE": "0"
      }
    }
  }
}

视窗 (%APPDATA%\Claude\claude_desktop_config.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：

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

高级配置

所有配置选项都可以通过环境变量进行设置：

看 .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模型。

______________________________________________________________________

🧪 开发状态

当前阶段： 准备部署-所有核心功能均已完成

______________________________________________________________________

🧪 测试

运行测试

# 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项测试

执行时间： 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）

______________________________________________________________________

📊 基准测试

完整基准测试： scripts/test-results/

______________________________________________________________________

🛠️ 发展

# 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测试通过）