# ZfPilot v2.1 安装手册

> 适用系统: Windows 10/11 (64位) | 预计耗时: 10 分钟  
> 版本: v2.1.0 | 工具数: 45+

---

## 目录

1. [前提条件](#前提条件)
2. [安装 uv 包管理器](#step-1安装-uv-包管理器)
3. [解压 ZfPilot](#step-2解压-zfpilot)
4. [一键安装 / 手动安装](#step-3安装-zfpilot)
5. [配置 AI 客户端](#step-4配置-ai-客户端)
6. [启用 Socket 模式](#step-5启用-socket-模式实时-gui)
7. [验证安装](#验证安装)
8. [常见问题](#常见问题)

---

## 前提条件

| 项目 | 最低要求 | 推荐 |
|------|---------|------|
| **操作系统** | Windows 10 (64位) | Windows 11 |
| **Python** | ≥ 3.10 | 3.12+ |
| **uv** | 最新版 | 最新版 |
| **Vivado** | 2018.3 或 2025.2 (含对应 SDK/Vitis) | — |
| **AI 客户端** | 任何支持 MCP 的平台 | VS Code + Copilot / Cline |
| **推荐模型** | Claude Sonnet 3.5+ 或同等能力，上下文 ≥ 100K | — |

---

## Step 1：安装 uv 包管理器

打开 PowerShell（Win+X → Windows PowerShell），执行：

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**关闭 PowerShell 再重新打开**，验证：

```powershell
uv --version       # 应显示版本号
where.exe uv       # 记下完整路径，后面要用
```

记下 `where.exe uv` 输出的路径，例如 `C:\Users\你的用户名\.local\bin\uv.exe`。

---

## Step 2：解压 ZfPilot

将 `ZfPilot.zip` 解压到任意位置，例如 `D:\ZfPilot`。

确认解压后 `pyproject.toml` 所在的目录路径，例如：

```
D:\ZfPilot\ZfPilot_test\pyproject.toml   ← 这一层就是项目根目录
```

---

## Step 3：安装 ZfPilot

### 方式 A：一键安装（推荐）

```powershell
cd D:\ZfPilot\ZfPilot_test

# 如果遇到执行策略限制，先运行:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 一键安装
.\install.ps1
```

脚本将自动:
1. ✅ 检测 Python 版本 (≥ 3.10)
2. ✅ 检测/安装 uv 包管理器
3. ✅ 安装 ZfPilot 及所有依赖
4. ✅ 验证安装结果
5. ✅ 生成配置模板 `zfpilot_config.yaml`

### 方式 B：手动安装

```powershell
cd D:\ZfPilot\ZfPilot_test
uv pip install -e .
```

看到 `Successfully installed` 即成功。

---

## Step 4：配置 AI 客户端

ZfPilot 是一个 MCP Server，需要在你的 AI 客户端中注册。以下列出各平台的配置方法。

### 4.1 VS Code + GitHub Copilot

在工作区根目录创建 `.vscode/mcp.json`:

```json
{
  "servers": {
    "zfpilot": {
      "command": "uv",
      "args": ["run", "--directory", "D:\\ZfPilot\\ZfPilot_test", "zfpilot"],
      "env": {
        "ZFPILOT_WORKSPACE": "D:\\FPGA_Projects",
        "ZFPILOT_VIVADO_MODE": "socket"
      }
    }
  }
}
```

### 4.2 VS Code + Cline

在 Cline 设置中编辑 `mcp_settings.json`:

```json
{
  "mcpServers": {
    "zfpilot": {
      "command": "uv",
      "args": ["run", "--directory", "D:\\ZfPilot\\ZfPilot_test", "zfpilot"],
      "env": {
        "ZFPILOT_WORKSPACE": "D:\\FPGA_Projects",
        "ZFPILOT_VIVADO_MODE": "socket"
      }
    }
  }
}
```

### 4.3 Claude Desktop

按 `Win+R`，输入 `%APPDATA%\Claude`，回车。找到或新建 `claude_desktop_config.json`:

**注意**：路径是 `%APPDATA%\Claude\`（即 `Roaming\Claude`），不是 `Local\AnthropicClaude`。

#### Vivado 2018.3 用户：

```json
{
  "mcpServers": {
    "zfpilot": {
      "command": "C:\\Users\\你的用户名\\.local\\bin\\uv.exe",
      "args": ["run", "--directory", "D:\\ZfPilot\\ZfPilot_test", "zfpilot"],
      "env": {
        "ZFPILOT_VIVADO_EXE": "D:\\Xilinx\\Vivado\\2018.3\\bin\\vivado.bat",
        "ZFPILOT_XSCT_EXE": "D:\\Xilinx\\SDK\\2018.3\\bin\\xsct.bat"
      }
    }
  }
}
```

#### Vivado 2025.2 用户：

```json
{
  "mcpServers": {
    "zfpilot": {
      "command": "C:\\Users\\你的用户名\\.local\\bin\\uv.exe",
      "args": ["run", "--directory", "D:\\ZfPilot\\ZfPilot_test", "zfpilot"],
      "env": {
        "ZFPILOT_VIVADO_EXE": "D:\\Xilinx\\Vivado\\2025.2\\bin\\vivado.bat",
        "ZFPILOT_VITIS_EXE": "D:\\Xilinx\\Vitis\\2025.2\\bin\\vitis.bat"
      }
    }
  }
}
```

### 4.4 Cursor

在项目根目录创建 `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "zfpilot": {
      "command": "uv",
      "args": ["run", "--directory", "D:\\ZfPilot\\ZfPilot_test", "zfpilot"],
      "env": {
        "ZFPILOT_WORKSPACE": "D:\\FPGA_Projects",
        "ZFPILOT_VIVADO_MODE": "socket"
      }
    }
  }
}
```

### 4.5 必须修改的地方

| 项目 | 改为你的实际值 |
|------|-------------|
| `command` (Claude Desktop) | Step 1 中 `where.exe uv` 的输出路径 |
| `--directory` 后的路径 | Step 2 中 `pyproject.toml` 所在目录 |
| `ZFPILOT_VIVADO_EXE` | 你的 `vivado.bat` 实际路径 |
| `ZFPILOT_XSCT_EXE` / `VITIS_EXE` | 你的 `xsct.bat` 或 `vitis.bat` 实际路径 |
| `ZFPILOT_WORKSPACE` | 你的 Vivado 工程存放目录 |

### 4.6 关键注意事项

- 所有路径用**双反斜杠** `\\`
- `args` 最后一项必须是**全小写** `"zfpilot"`（不是 `"ZfPilot"`）
- 如果已有其他 MCP 配置，把 `zfpilot` 块加到 `mcpServers` 对象里
- JSON 最后一个键值对后面**不能有逗号**

### 4.7 重启 AI 客户端

- **Claude Desktop**: 右下角托盘 → 右键 → Quit → 重新打开
- **VS Code**: 重新加载窗口 (Ctrl+Shift+P → "Reload Window")
- **Cursor**: 重新加载窗口

---

## Step 5：启用 Socket 模式（实时 GUI）

Socket 模式是推荐的 Vivado 通信方式。AI 的每条命令都在你眼前的 Vivado GUI 中实时执行。

### 5.1 打开 Vivado GUI

正常方式打开 Vivado（双击桌面快捷方式）。

### 5.2 加载 Socket 服务器

在 Vivado 窗口底部的 **Tcl Console** 中输入：

```tcl
source D:/ZfPilot/ZfPilot_test/vivado_server.tcl
```

（路径改成你实际的 `vivado_server.tcl` 位置，用**正斜杠** `/`）

### 5.3 确认成功

看到以下输出即成功：

```
========================================
  ZfPilot Vivado TCL Server
  Port: 9900
  Status: Listening
========================================
Waiting for connection...
```

### 5.4 开机自启（可选）

编辑 `%APPDATA%\Xilinx\Vivado\Vivado_init.tcl`，添加:
```tcl
source {D:/ZfPilot/ZfPilot_test/vivado_server.tcl}
```

---

## 验证安装

在 AI 客户端中新建对话，输入：

```
查看一下 ZfPilot 执行引擎状态
```

如果返回 `"active_mode": "socket"` 和 `"socket_available": true`，则全部配置成功。

你也可以尝试:
```
检测当前 Vivado 版本和工具链信息
```

---

## 常见问题

| 症状 | 原因 | 解决 |
|------|------|------|
| AI 客户端没有工具图标 | 配置文件位置或格式错误 | 确认配置文件路径正确；用 jsonlint.com 检查语法 |
| 工具图标在但调用报错 | `command` 路径找不到 uv | 用 `where.exe uv` 查完整路径填入 |
| detect_version 失败 | Vivado 路径不对 | 在资源管理器中确认 `vivado.bat` 存在 |
| Socket 连不上 | Vivado 未执行 server 脚本 | 在 Tcl Console 中重新 `source` |
| `args` 最后写了 `"ZfPilot"` | 大小写敏感 | 必须全小写 `"zfpilot"` |
| 安装脚本"执行策略"错误 | PowerShell 执行策略限制 | 运行 `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser` |
| 端口 9900 被占用 | 其他程序占用 | 用增强脚本 `scripts/start_server.tcl` 指定其他端口 |

---

## 附录: 环境变量一览

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `ZFPILOT_WORKSPACE` | `C:/ZfPilot_workspace` | 工作空间根目录 |
| `ZFPILOT_VIVADO_MODE` | `socket` | TCL 执行模式 (socket/persistent/batch) |
| `ZFPILOT_SOCKET_PORT` | `9900` | Socket 端口 |
| `ZFPILOT_LOG_LEVEL` | `INFO` | 日志级别 |
| `ZFPILOT_VIVADO_EXE` | 自动检测 | vivado.bat 路径 |
| `ZFPILOT_XSCT_EXE` | 自动检测 | xsct.bat 路径 (2018.3) |
| `ZFPILOT_VITIS_EXE` | 自动检测 | vitis.bat 路径 (2025.2) |
