# ZfPilot Socket 模式配置指南

## 概述

Socket 模式是 ZfPilot 与 Vivado 通信的推荐方式。通过 TCP Socket 连接到运行在 Vivado 控制台中的 TCL 服务器，实现低延迟、交互式的命令执行。

## 架构

```
┌──────────────┐    TCP:9900    ┌──────────────────┐
│   ZfPilot    │ ?───────────? │   Vivado TCL     │
│  (Python)    │    Socket      │   Server (TCL)   │
│              │                │                  │
│ tcl_engine   │   命令/结果     │ vivado_server.tcl│
└──────────────┘                └──────────────────┘
```

## 快速启动

### 步骤 1: 在 Vivado 中启动 TCL 服务器

打开 Vivado，在 TCL Console 中执行:

```tcl
source {C:/path/to/ZfPilot/vivado_server.tcl}
```

或使用增强版启动脚本（支持自定义端口）:

```tcl
source {C:/path/to/ZfPilot/scripts/start_server.tcl}
```

看到以下提示表示服务器已就绪:
```
========================================
  ZfPilot Vivado TCL Server
  Port: 9900
  Status: Listening
========================================
Waiting for connection...
```

### 步骤 2: 配置 ZfPilot 使用 Socket 模式

在 `zfpilot_config.yaml` 中设置:

```yaml
vivado:
  mode: socket
  socket:
    host: localhost
    port: 9900
    timeout: 30
```

或通过环境变量:
```powershell
$env:ZFPILOT_VIVADO_MODE = "socket"
$env:ZFPILOT_SOCKET_PORT = "9900"
```

## 通信协议

### 命令发送

ZfPilot 通过 TCP Socket 发送 TCL 命令，每条命令以换行符 `\n` 结尾。

### 结果接收

服务器执行命令后返回结果，以特殊标记结尾:
- `<<<DONE>>>` — 命令执行成功
- `<<<ERROR: ...>>>` — 命令执行出错

### 心跳检测

发送 `PING\n`，服务器回复 `PONG\n`。用于检测连接是否存活。

## 端口配置

| 配置方式 | 方法 |
|---------|------|
| 默认 | 9900 |
| TCL 脚本参数 | `source start_server.tcl 9901` |
| 环境变量 | `ZFPILOT_SOCKET_PORT=9901` |
| 配置文件 | `zfpilot_config.yaml` 中设置 |

## 防火墙说明

Socket 模式仅监听 `localhost` (127.0.0.1)，不接受外部连接。通常不需要防火墙配置。

如果遇到连接问题:
1. 确认 Vivado 中 TCL 服务器已启动
2. 检查端口是否被占用: `netstat -an | findstr "9900"`
3. 确认 Python 端与 TCL 端使用相同端口号

## 超时处理

默认超时时间为 30 秒。对于耗时操作（综合、实现），建议在 MCP 工具调用时传入更长的超时值。

## 多实例

如需同时操作多个 Vivado 实例，可使用不同端口:

```tcl
# Vivado 实例 1
source start_server.tcl 9900

# Vivado 实例 2
source start_server.tcl 9901
```

在 ZfPilot 工具调用时通过参数指定连接哪个实例。

## 故障排除

| 问题 | 可能原因 | 解决方案 |
|------|---------|---------|
| 连接被拒绝 | 服务器未启动 | 在 Vivado 中 source TCL 脚本 |
| 连接超时 | 端口不匹配 | 检查两端端口配置 |
| 命令无响应 | Vivado 卡死 | 重启 Vivado 并重新启动服务器 |
| 乱码结果 | 编码问题 | 确认 TCL 使用 UTF-8 编码 |
