STARWARCLOUD STARWAR.AI
返回市场
齐格耐特

齐格耐特

作者：fulgidus8 星标更新：2025-11-08
安装使用来源：spider==github.com

项目介绍

ZigNet

适用于Zig的MCP服务器 — 由微调过的LLM提供智能代码分析、验证和文档生成

ZigNet与Claude（以及其他兼容MCP的LLM）集成，提供实时的Zig代码分析，无需离开聊天界面。

🎯 特性

MCP工具

<details> <summary><b>🔍 analyze_zig</b> — 使用官方Zig编译器进行语法和类型检查</summary>

使用zig ast-check对Zig代码进行语法错误、类型不匹配和语义问题的分析。

示例用法：

用户: "分析这段Zig代码"
Claude: [调用analyze_zig工具]
响应: "✅ 语法: 正确 | 类型检查: 通过 | 警告: 0"

功能：

  • 词法分析（标记化）
  • 语法解析（AST生成）
  • 类型检查和验证
  • 语义错误检测
  • 行/列错误报告
</details> <details> <summary><b>✨ compile_zig</b> — 格式化和验证Zig代码</summary>

使用zig fmt验证并格式化Zig代码，生成干净、符合习惯的输出。

示例：

// 输入（杂乱）
fn add(a:i32,b:i32)i32{return a+b;}

// 输出（格式化）
fn add(a: i32, b: i32) i32 {
    return a + b;
}

功能：

  • 代码格式化（2个空格缩进）
  • 语法验证
  • 执行最佳实践
  • 保留语义
</details> <details> <summary><b>📖 get_zig_docs</b> — AI驱动的文档查找（即将推出）</summary>

使用微调过的LLM检索Zig语言特性的文档和解释。

示例：

查询: "comptime"
响应: "comptime允许在Zig中进行编译时评估..."

技术支持：

  • 微调过的Qwen2.5-Coder-7B模型
  • 13,756个来自Zig 0.13-0.15的例子
  • 高级Zig习惯用法（comptime、泛型、错误处理）
</details> <details> <summary><b>🔧 suggest_fix</b> — 智能错误修复建议（即将推出）</summary>

使用AI驱动的分析为Zig错误提供智能修复建议。

示例：

// 错误: "类型不匹配: 无法将字符串赋值给i32"
var x: i32 = "hello";

// 建议:
// 选项1: var x: []const u8 = "hello";  // 如果您指的是字符串
// 选项2: var x: i32 = 42;              // 如果您指的是整数

特性：

  • 上下文感知建议
  • 多种修复选项
  • 问题解释
  • Zig习惯用法推荐
</details>

📖 使用方法

ZigNet是一个MCP服务器 —— 在您的MCP客户端中配置一次，然后在对话中自然地使用它。

<details> <summary><b>🖥️ Claude桌面版</b></summary>

配置文件位置：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

添加以下内容：

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

然后重启Claude桌面版 并开始使用：

您: "分析这段Zig代码中的错误"
     [粘贴代码]

Claude: [使用analyze_zig工具]
        "发现1个类型错误: 变量'x'期望i32但得到[]const u8"
</details> <details> <summary><b>🔧 VS Code（带有GitHub Copilot）</b></summary>

方法1：VS Code市场（即将推出）

  1. 打开VS Code扩展（Ctrl+Shift+X / Cmd+Shift+X）
  2. 搜索@mcp zignet
  3. 点击安装
  4. 重启VS Code

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

  1. 安装GitHub Copilot扩展（如果尚未安装）
  2. 打开Copilot设置
  3. 添加到MCP服务器配置：
{
  "mcpServers": {
    "zignet": {
      "command": "npx",
      "args": ["-y", "zignet"]
    }
  }
}

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

</details>

配置后会发生什么？

  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 Code MCP配置带GPU选择：

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

Claude桌面版配置带GPU选择：

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

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

Windows (%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 GPU
nvidia-smi

# 输出显示GPU索引：
# GPU 0: NVIDIA RTX 4090
# GPU 1: AMD Radeon 6950XT（CUDA无论如何都不会使用）

高级配置

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

变量默认值描述
ZIGNET_GPU_DEVICE自动GPU设备选择（CUDA_VISIBLE_DEVICES）
ZIGNET_GPU_LAYERS35GPU上的模型层数量（0=仅CPU）
ZIGNET_MODEL_PATH~/.zignet/models/...自定义模型路径
ZIGNET_MODEL_AUTO_DOWNLOADtrue从HuggingFace自动下载模型
ZIGNET_CONTEXT_SIZE4096LLM上下文窗口大小
ZIGNET_TEMPERATURE0.7LLM创造力（0.0-1.0）
ZIGNET_TOP_P0.9LLM采样参数
ZIG_SUPPORTED0.13.0,0.14.0,0.15.2支持的Zig版本
ZIG_DEFAULT0.15.2默认Zig版本

参见 .env.example 获取详细示例。

🏗️ 架构

┌─────────────────────────────────────────────────────┐
│ Claude / MCP客户端                                  │
└────────────────────┬────────────────────────────────┘
                     │ MCP协议（JSON-RPC）
┌────────────────────▼────────────────────────────────┐
│ ZigNet MCP服务器（TypeScript）                      │
│  ┌──────────────────────────────────────────────┐   │
│  │ 工具处理器                                │   │
│  │ - analyze_zig                                │   │
│  │ - compile_zig                                │   │
│  │ - get_zig_docs                               │   │
│  │ - suggest_fix                                │   │
│  └─────────────┬────────────────────────────────┘   │
│                ▼                                    │
│  ┌──────────────────────────────────────────────┐   │
│  │ Zig编译器集成                             │   │
│  │ - zig ast-check（语法+类型验证）         │   │
│  │ - zig fmt（官方格式化器）               │   │
│  │ - 自动检测系统Zig安装                   │   │
│  │ - 如有需要则回退到下载                  │   │
│  └─────────────┬────────────────────────────────┘   │
│                ▼                                    │
│  ┌──────────────────────────────────────────────┐   │
│  │ 微调过的LLM（Qwen2.5-Coder-7B）            │   │
│  │ - 文档查找                           │   │
│  │ - 智能建议                          │   │
│  └──────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘

为什么采用这种架构？

  • 官方Zig编译器（100%准确，始终最新）而不是自定义解析器
  • 系统集成（如有可用，则使用现有的Zig安装）
  • LLM驱动的建议（get_zig_docs，suggest_fix）以实现智能
  • 无外部API调用（通过node-llama-cpp进行本地推理）
  • 快速（< 100毫秒用于验证，< 2秒用于LLM建议）

注意：当Zig发布新版本（例如0.16.0）时，ZigNet需要重新训练LLM模型以适应更新的文档和示例。

🧪 开发状态

组件状态备注
Zig编译器封装✅ 完成ast-check + fmt集成
系统Zig检测✅ 完成自动检测已安装的Zig版本
多版本缓存✅ 完成按需下载Zig 0.13-0.15
MCP服务器✅ 完成所有4个工具完全实现
LLM微调✅ 完成训练于13,756个Zig示例
get_zig_docs✅ 完成LLM驱动的文档查找
suggest_fix✅ 完成LLM驱动的智能建议
GGUF转换✅ 完成Q4_K_M量化（4.4GB）
端到端测试✅ 完成27/27测试通过（8.7秒）
Claude集成⏳ 计划最终部署至Claude桌面版

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

🧪 测试

运行测试

# 运行所有测试（单元+端到端）
pnpm test

# 仅运行端到端测试
pnpm test tests/e2e/mcp-integration.test.ts

# 仅运行确定性测试（不需要LLM）
SKIP_LLM_TESTS=1 pnpm test tests/e2e

# 开发模式监视
pnpm test:watch

测试覆盖率

端到端测试套件：27个测试覆盖所有MCP工具

工具测试类型通过率
analyze_zig4确定性100%
compile_zig3确定性100%
get_zig_docs5LLM驱动100%
suggest_fix5LLM驱动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             # 基于环境的配置
│   ├── mcp-server.ts         # MCP协议处理器
│   ├── zig/
│   │   ├── manager.ts        # 多版本Zig下载/缓存
│   │   └── executor.ts       # zig ast-check + fmt封装
│   ├── llm/
│   │   ├── model-downloader.ts  # 自动从HuggingFace下载GGUF
│   │   └── session.ts           # node-llama-cpp集成
│   └── tools/
│       ├── analyze.ts        # analyze_zig工具（已完成）
│       ├── compile.ts        # compile_zig工具（已完成）
│       ├── docs.ts           # get_zig_docs工具（已完成）
│       └── suggest.ts        # suggest_fix工具（已完成）
├── scripts/
│   ├── train-qwen-standard.py   # 微调脚本（已完成）
│   ├── scrape-zig-repos.js      # 数据集收集
│   ├── install-zig.js           # Zig版本安装器
│   └── test-config.cjs          # 配置系统测试
├── data/
│   ├── training/             # 13,756个示例（训练/验证/测试）
│   └── zig-docs/             # 抓取的文档
├── models/
│   └── zignet-qwen-7b/       # 微调过的模型+LoRA适配器
├── tests/
│   ├── *.test.ts             # 单元测试（词法分析器、解析器等）
│   └── e2e/
│       ├── mcp-integration.test.ts  # 27个端到端测试
│       └── README.md               # 测试指南
├── docs/
│   ├── AGENTS.md             # 详细的项目规范
│   ├── DEVELOPMENT.md        # 开发指南
│   └── TESTING.md            # 测试文档
└── README.md                 # 本文档

🤖 模型细节

基础模型：Qwen/Qwen2.5-Coder-7B-Instruct
微调：QLoRA（4位）在13,756个Zig示例上
数据集：97%真实世界仓库（Zig 0.13-0.15），3%文档
训练：RTX 3090（24GB VRAM），3个周期，约8小时
输出：fulgidus/zignet-qwen2.5-coder-7b（HuggingFace）
量化：Q4_K_M（~4GB GGUF用于node-llama-cpp）

为什么选择Qwen2.5-Coder-7B？

  • 对Zig语法理解最佳（与14个模型对比基准测试）
  • 现代习惯用法（comptime、泛型、错误处理）
  • 快速推理（量化后每个查询约15-20秒）

📊 基准测试

模型通过率平均时间质量备注
Qwen2.5-Coder-7B100%29.58秒⭐⭐⭐⭐⭐选定 - 最佳习惯用法
DeepSeek-Coder-6.7B100%27.86秒