# ZfPilot v2.1 需求规格书 (SRS)

> **版本**: v2.1 (增补版)  
> **日期**: 2026-03-10  
> **定位**: 基于 MCP 协议的 ZYNQ FPGA 开发 AI Agent 工具集  
> **支持版本**: Vivado/SDK 2018.3 · Vivado/Vitis 2025.2 及其他  
> **支持系统**: Windows 10 及以上（64 位）

---

## 1. 项目概述

### 1.1 产品定义

ZfPilot 是一个基于标准化 MCP (Model Context Protocol) 的本地代理服务器（Agent Server）。它作为一座桥梁，将任意支持 MCP 协议的大语言模型（LLM）客户端与底层的 Xilinx/AMD FPGA 开发工具链深度连接，实现从硬件逻辑设计、综合实现到嵌入式软件开发（SDK/Vitis）的全流程自动化。

支持的 AI 宿主客户端生态包括但不限于：

**原生支持 MCP 的平台（可直接接入）：**

| 平台 | 类型 | MCP 接入方式 | 上下文窗口 | FPGA 开发适配度 | 说明 |
|------|------|-------------|-----------|----------------|------|
| **Claude Desktop** | 独立桌面端 | 原生 stdio | 200K | ⭐⭐⭐ | MCP 标准制定者，配置最简单 |
| **Claude Code** | CLI 工具 | 原生 stdio | 200K | ⭐⭐⭐⭐ | 命令行 Agent，适合脚本化/CI 集成 |
| **VS Code + Copilot** | IDE 集成 | `mcp.json` | 取决于模型 | ⭐⭐⭐⭐⭐ | 直接读写工作区 RTL 源码 + 调用 ZfPilot |
| **VS Code + Cline** | IDE 扩展 | `mcp_settings.json` | 200K (Claude) | ⭐⭐⭐⭐⭐ | 开源 Agent 扩展，支持自动审批工具调用 |
| **VS Code + Roo Code** | IDE 扩展 | MCP 配置 | 200K | ⭐⭐⭐⭐ | 支持自定义 Agent Mode，可定制 FPGA 专属流程 |
| **VS Code + Continue** | IDE 扩展 | MCP 配置 | 取决于模型 | ⭐⭐⭐ | 开源，支持本地/云端多模型自由切换 |
| **Cursor** | AI IDE | 内置 MCP | 取决于模型 | ⭐⭐⭐⭐ | Composer Agent 模式可自动多步执行 |
| **Windsurf** | AI IDE | MCP 配置 | 取决于模型 | ⭐⭐⭐ | Cascade 流式 Agent |
| **Zed** | 轻量编辑器 | MCP (实验) | 取决于模型 | ⭐⭐ | MCP 处于早期阶段 |

**可通过适配层桥接的平台：**

| 平台 | 接入方案 | 可行性 |
|------|---------|--------|
| **ChatGPT (OpenAI)** | MCP-to-Function-Calling 桥接层 | 中等，需自建网关 |
| **Gemini (Google)** | Google A2A 协议 + MCP 桥接 | 中等，生态正在追赶 |
| **本地模型 (Ollama/LM Studio)** | Continue / Open WebUI + MCP 插件 | 可行，需 70B+ 模型才能可靠生成 TCL |
| **JetBrains AI** | JetBrains MCP 插件 | 可行，适合偏好 JetBrains 生态的用户 |
| **自建 Web UI** | MCP SSE/Streamable HTTP 模式 | 需额外开发，可做 B/S 架构供团队使用 |

**推荐组合：**
- **个人开发**：VS Code + Copilot/Cline + Claude Sonnet（IDE 直接读取 Verilog/VHDL + 调用 ZfPilot，闭环最短）
- **自动化/CI**：Claude Code CLI（可嵌入 Makefile 或 CI pipeline）
- **团队协作**：MCP SSE 模式 + Web 前端（内网共享 Vivado License）

### 1.2 核心架构

采用"经验书 + 工具"双层架构：

```
┌─────────────────────────────────────────────────────────────┐
│  AI 宿主客户端 (Claude Desktop / Cursor / VS Code + Cline)  │
│            用户用自然语言描述 → AI 调用 MCP 工具             │
└──────────────────────────┬──────────────────────────────────┘
                           │ MCP Protocol (stdio)
┌──────────────────────────▼──────────────────────────────────┐
│                  ZfPilot MCP Server (Python)                 │
│  ┌──────────────┐  ┌───────────────┐  ┌──────────────────┐  │
│  │ knowledge/   │  │  MCP 工具层   │  │  version_        │  │
│  │ 静态知识库   │  │  (45 工具)    │  │  detector        │  │
│  │ + 动态 IP 库 │  │              │  │  + sandbox       │  │
│  │ + 开发板字典 │  │              │  │  + logger        │  │
│  └──────┬───────┘  └──────┬───────┘  └──────────────────┘  │
└─────────┼─────────────────┼─────────────────────────────────┘
          │ read             │ execute (3 模式)
          ▼                  ▼
  ┌──────────────┐   ┌────────────────────────────────────────┐
  │  .md / .json │   │  Socket → Vivado GUI (TCP:9900) 实时   │
  │  知识库文件  │   │  Persistent → vivado -mode tcl 常驻    │
  └──────────────┘   │  Batch → vivado -mode batch 兜底       │
                     └────────────────────────────────────────┘
```

#### MCP 传输模式

| 模式 | 场景 | 说明 |
|------|------|------|
| **stdio**（当前默认） | 桌面端单用户 | Server 进程由客户端拉起，通过 stdin/stdout 通信。覆盖上述所有原生 MCP 平台 |
| **SSE / Streamable HTTP**（v3.0 规划） | 团队/Web 场景 | Server 作为独立 HTTP 服务运行，多客户端并发连接。MCP SDK 原生支持，改动量小 |

### 1.3 三种执行模式

| 模式 | 原理 | 速度 | GUI | 适用场景 |
|------|------|------|-----|---------|
| **Socket** ★推荐 | TCP 连接已打开的 Vivado GUI | 秒级 | ✅ 实时可见 | 日常开发 |
| **Persistent** | 常驻 vivado -mode tcl 进程 | 秒级 | ❌ 无 | 无需看 GUI |
| **Batch** | 每次启动 vivado -mode batch | 30-60 秒 | ❌ 无 | 兜底/CI |

自动优先级: Socket > Persistent > Batch。当 Socket 断开时自动降级，无需用户干预。

### 1.4 跨代版本适配与工具链路由 (SDK vs Vitis)

Xilinx 的嵌入式开发工具链在 2019.2 版本前后由 SDK 切换为 Vitis，工程结构和自动化脚本语言均有巨大差异。

ZfPilot 采用 **"环境探针 + AI 智能路由"** 的策略：

1. **自动化版本探测**：启动时强制执行 `detect_toolchain_version()`，扫描宿主机环境变量与默认安装路径，返回确切的工具链画像。
2. **双向管道路由**：AI 收到版本画像后，自主决定生成 XSCT TCL 或 Vitis Python 脚本，通过对应管道执行。
3. **跨版本沙箱隔离**：`init_workspace()` 时自动建立版本隔离的配置目录（如 `.zfpilot/env_2018.3.json`），确保后续指令路由到正确的 bin 目录。

| 功能 | 2018.3 (SDK) | 2025.2 (Vitis) |
|------|-------------|----------------|
| 硬件导出 | `write_hwdef` + `write_sysdef` → `.sysdef` | `write_hw_platform` → `.xsa` |
| 软件脚本 | XSCT TCL: `xsct script.tcl` | Vitis Python: `vitis -s script.py` |
| 创建工程 | `createhw` + `createbsp` + `createapp` | `create_platform_component` + `create_app_component` |
| 调试连接 | `connect` → `targets` → `fpga` → `dow` → `con` | `session.connect()` → `session.fpga()` → `session.dow()` → `session.con()` |

### 1.5 动态 IP 知识库

#### 1.5.0 核心机制

**IP 知识库不是预先写死的固定文件，而是用户动态投喂的。**

- **启动自动发现 (Auto-Scan)**：进入工作空间时，后台递归扫描 `ip_repo/` 下的 `.pdf` 文件。
- **指纹去重 (Hash Caching)**：计算 PDF 的 MD5 指纹与 `ip_index.json` 比对，命中缓存则跳过解析。
- **热加载 (Hot-Reload)**：开发中途放入新手册时，调用 `refresh_ip_knowledge(dir_path)` 触发增量解析。

#### 1.5.1 IP 参数 Schema 化存储与校验

为节省 Token 并保证配置合法性，缓存 JSON 采用 Schema（规则与约束）形式：

1. **连续范围约束**：`{"type": "integer", "range": {"min": 1, "max": 50}, "default": 16}`
2. **动态公式依赖**：`{"type": "formula", "dependencies": ["DATA_WIDTH", "CHANNELS"], "expression": "DATA_WIDTH * CHANNELS"}`
3. **条件生效机制**：`{"condition": "c_include_sg == 1"}`

AI 在生成 TCL 命令前，必须先通过 `get_ip_schema(vlnv)` 获取规则，在本地完成越界拦截和依赖计算。

#### 1.5.2 非标 IP 的知识注入与信息蒸馏

针对第三方商业 IP、自研非标封装 IP 等 LLM 训练数据未覆盖的 IP：

1. **数据清洗**：自动过滤 PDF 中的原理说明、时序波形图、免责声明等冗余内容。
2. **高价值提取**：仅提取接口定义（引脚名/位宽/AXI 映射）、配置规则（寄存器基地址/参数范围/枚举/公式）、硬性约束（时钟频率/复位极性）。
3. **静态化固化**：转换为精简 JSON Schema，永久固化到 `knowledge/ip/cache/`。

### 1.6 安全沙箱与路径隔离

- **Workspace Sandbox**：所有涉及文件系统读写的 MCP 工具，执行前必须通过 `os.path.abspath` 解析路径，严格校验最终路径是否以 `init_workspace()` 设定的根目录为前缀。任何 `../../` 逃逸操作直接抛出权限异常。
- **网络隔离**：MCP Server 仅监听 `localhost (127.0.0.1)`，建议通过 stdio 方式与宿主 AI 客户端通信，不对外暴露 HTTP/SSE 端口。
- **Vivado Socket 限制**：Socket 模式的 TCL Server 仅接受本地连接，绑定 `127.0.0.1:9900`。

### 1.7 全局配置管理

ZfPilot 在根目录维护 `zfpilot_config.yaml` 或 `.env` 文件：

| 配置项 | 说明 | 示例值 |
|--------|------|--------|
| `vivado_install_path` | 覆盖自动检测，手动指定 Vivado bin 路径 | `D:\Xilinx\Vivado\2018.3\bin` |
| `default_workspace` | 默认工程生成根目录 | `D:\FPGA_Projects` |
| `max_log_lines` | 日志截断上限（防撑爆上下文） | `200` |
| `tcl_server_port` | Socket 模式端口 | `9900` |
| `max_retry_count` | AI 自动重试上限（综合/编译失败） | `3` |
| `auto_socket_listen` | 启动时自动开始 Socket 端口探测 | `true` |
| `socket_ports` | 各工具链的 Socket 监听端口字典 | `{vivado: 9900, xsct: 9901, vitis: 9902}` |
| `socket_retry_interval` | Socket 自动探测间隔（秒） | `5` |
### 1.8 运行环境要求

| 项目 | 要求 |
|------|------|
| **操作系统** | Windows 10 及以上（64 位） |
| **Python** | ≥ 3.10 |
| **uv** | 最新版 |
| **Vivado** | 2018.3 或 2025.2（含对应 SDK/Vitis） |
| **AI 客户端** | 任何支持 MCP 的平台（详见 §1.1 平台兼容性清单） |
| **推荐模型** | Claude Sonnet 3.5+ 或同等能力模型，上下文窗口 ≥ 100K |

**路径约定**：基于 Windows 环境，默认使用 `\` 或 `\\` 作为路径分隔符，通过 `.bat` 文件拉起 Xilinx 工具。跨平台 Linux 支持作为 v3.0 迭代目标。

### 1.9 Agent 运行日志与异常追踪

ZfPilot 在本地生成运行日志，存放于 `~/.zfpilot/logs/server.log`：

| 记录事件 | 说明 |
|---------|------|
| MCP 客户端连接/断开 | 含时间戳和客户端标识 |
| TCP Socket 握手状态 | Socket 模式连接/断开/降级 |
| 每次工具调用耗时 | 工具名 + 参数摘要 + 耗时(ms) |
| Token 截断警告 | 当日志/报告超过 `max_log_lines` 时警告 |
| 错误降级 | Socket 失败自动降级到 Persistent/Batch |
| Socket 自动探测记录 | 每次探测结果、工具上线/下线事件 |
| 多端口监听状态变化 | Vivado/XSCT/Vitis 各端口上线/离线切换 |

**防呆设计**：当 Socket 连接 Vivado 失败时，Agent 向大模型返回明确指导文本（如"Vivado GUI 未启动或端口 9900 被占用"），而非抛出 Python 异常。

---

## 2. 目录结构

```
ZfPilot/
├── knowledge/                     ← 📚 AI 知识库
│   ├── SKILL.md                   ← 总入口索引
│   ├── cache/                     ← 版本缓存（运行时生成）
│   │   ├── detected_version.json
│   │   └── ip_index.json
│   ├── tcl/                       ← Vivado TCL 命令参考
│   │   ├── 01_project.md
│   │   ├── 02_bd.md
│   │   ├── 03_synthesis.md
│   │   └── 04_constraints.md
│   ├── sdk/                       ← SDK/Vitis 命令参考
│   │   ├── xsct.md
│   │   └── vitis_python.md
│   ├── board/                     ← 开发板引脚资源
│   │   └── alientek_alpha.md
│   └── ip/                        ← 动态 IP 文档缓存
│       ├── cache/*.json
│       └── source/*.pdf
│
├── src/zfpilot/                   ← 🔧 源代码
│   ├── server.py                  ← MCP 入口（工具注册）
│   ├── version_detector.py        ← 版本检测与缓存
│   ├── ip_doc_parser.py           ← IP PDF 解析引擎
│   ├── sandbox.py                 ← 🆕 工作空间沙箱管理
│   ├── logger.py                  ← 🆕 日志系统
│   ├── vivado/
│   │   ├── tcl_engine.py          ← TCL 执行引擎（3 模式）
│   │   ├── project.py             ← 工程管理
│   │   ├── block_design.py        ← Block Design
│   │   ├── synthesis.py           ← 综合/实现/比特流
│   │   ├── export.py              ← 版本自适应硬件导出
│   │   ├── constraints.py         ← XDC 约束生成
│   │   ├── simulation.py          ← 🆕 仿真控制
│   │   └── report_parser.py       ← 🆕 日志/报告解析
│   └── sdk/
│       ├── xsct.py                ← 2018.3 XSCT 引擎
│       ├── vitis_python.py        ← 2025.2 Vitis Python 引擎
│       ├── workspace.py           ← 版本分支工程管理
│       ├── debug.py               ← 调试下载工具
│       └── drivers.py             ← Aurora/DMA 驱动生成
│
├── vivado_server.tcl              ← Socket 模式初始化脚本
├── zfpilot_config.yaml            ← 🆕 全局配置文件
├── pyproject.toml                 ← Python 项目配置
└── .mcp.json                      ← MCP 配置样例
```
```
D:/FPGA_Projects/my_project/          ← 工程根目录（沙箱边界）
├── src/                               ← 用户 RTL 源码 (Verilog/VHDL/SV)
├── tb/                                ← Testbench 激励文件
├── ip_repo/                           ← IP 核参考资料
│   ├── docs/                          ← IP 官方 PDF 手册（投喂入口）
│   └── custom/                        ← 自定义 IP 源码
├── constraints/                       ← XDC 约束文件
├── schematics/                        ← 原理图/硬件参考文档
├── sdk_workspace/                     ← SDK/Vitis 软件工程目录
├── export/                            ← 导出的 .sysdef/.xsa/.bit
├── docs/                              ← 项目文档/设计说明
├── .zfpilot/                          ← ZfPilot 工程级配置（隐藏）
│   ├── env.json                       ← 版本隔离配置
│   ├── ip_cache/                      ← 本工程的 IP Schema 缓存
│   └── logs/                          ← MCP 工具调用日志
└── vivado_project/                    ← Vivado .xpr 工程目录

```
---

## 3. 标准开发流程

### 3.1 流程总览

```
① detect_version()          → 检测底层工具链版本 (2018.3 / 2025.2)
                              同时启动 Socket 多端口监听（9900/9901/9902），等待工具链就绪
② init_workspace(path)      → 设定沙箱边界 + 扫描 IP + 创建标准工程子目录
③ create_vivado_project()   → 新建项目
   或 open_vivado_project()  → 打开已有项目
```

### 3.2 路径 A：纯 FPGA 逻辑开发流 (RTL-Centric)

适用于传统纯逻辑开发、算法验证或自定义模块设计。

```
步骤 1: add_design_sources()          → 导入 Verilog/VHDL/SystemVerilog/.coe
步骤 2: add_ip_core() (可选)          → 在 RTL 中例化基础 IP (PLL/FIFO)
步骤 3: generate_testbench()          → AI 生成激励文件
        run_simulation()              → XSIM 行为级仿真
        read_simulation_console()     → 读取 $display 输出验证逻辑
步骤 4: generate_xdc()                → 时序与引脚约束
步骤 5: run_synthesis() → run_implementation()
步骤 6: generate_bitstream()
```

### 3.3 路径 B：ZYNQ SoC 软硬协同开发流 (BD-Centric)

适用于需要 ARM 处理器 (PS) 介入、使用 AXI 总线互联的系统级开发。

```
步骤 1: create_block_design()
        add_zynq_ps()                 → 配置 PS 参数
        add_ip_core() × N             → 调取 JSON Schema 精准配置 IP
        connect_axi_interface()       → 建立总线连接
        auto_assign_address()         → 分配内存映射地址
步骤 2: validate_and_save_bd()        → 验证 + HDL Wrapper
步骤 3: generate_xdc() → 综合实现 → 生成 Bitstream
步骤 4: export_hardware()             → .sysdef (2018) 或 .xsa (2025)
步骤 5: create_sw_project()           → BSP + 应用工程
        build_sw_project()            → 编译 ELF
步骤 6: debug_connect()               → JTAG 连接
        download_and_run()            → 下载运行
```

### 3.4 AI 异常处理与微调环路

在任意路径中，若综合/实现/编译步骤报错，AI Agent 自动切入恢复流程：

```
失败 → read_log_summary(filter="ERROR")    → 提取错误摘要
     → get_timing_summary()                → 提取时序违例（如适用）
     → AI 修改源码/约束/配置
     → 重新执行失败节点
     → 若连续失败 ≥ max_retry_count 次
       → 强制中断，交还用户："已达最大重试次数，请人工介入"
```

### 3.5 异步长任务处理

综合/实现/比特流生成可能耗时数十分钟。为防止 MCP 协议超时：

```
AI 调用 run_synthesis()
  → 后台启动异步任务，立即返回 job_id
  → AI 调用 check_job_status(job_id) 轮询进度
  → 等待期间 AI 可执行其他任务（如分析报告、准备软件代码）
  → 任务完成后 AI 读取结果
```

---

## 4. 环境变量配置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `ZFPILOT_VIVADO_EXE` | `C:\Xilinx\Vivado\2018.3\bin\vivado.bat` | Vivado 路径 |
| `ZFPILOT_XSCT_EXE` | `C:\Xilinx\SDK\2018.3\bin\xsct.bat` | XSCT 路径（2018.3） |
| `ZFPILOT_VITIS_EXE` | （空） | Vitis 路径（2025.2） |
| `ZFPILOT_TCL_HOST` | `127.0.0.1` | Socket 连接 IP |
| `ZFPILOT_TCL_PORT` | `9900` | Vivado Socket 端口 |
| `ZFPILOT_XSCT_PORT` | `9901` | XSCT Socket 端口（2018.3） |
| `ZFPILOT_VITIS_PORT` | `9902` | Vitis Socket 端口（2025.2） |
| `ZFPILOT_WORKSPACE` | （空） | 默认工作空间根目录 |
| `ZFPILOT_LOG_DIR` | `~/.zfpilot/logs` | 日志输出目录 |
| `ZFPILOT_MAX_RETRY` | `3` | AI 自动重试上限 |

---

## 5. 依赖

| 组件 | 版本要求 | 用途 |
|------|---------|------|
| Python | ≥ 3.10 | 运行时 |
| uv | 最新版 | 包管理 |
| mcp[cli] | ≥ 1.0.0 | MCP 协议 |
| pdfplumber | ≥ 0.10.0 | IP PDF 解析 |
| PyYAML | ≥ 6.0 | 配置文件解析 |
| Vivado | 2018.3 或 2025.2 | FPGA 工具链 |
| Claude Desktop / Cursor / Claude Code | 最新版 | AI 宿主客户端 |

---

## 6. 核心 MCP 工具与知识库规范

### 6.1 架构设计理念

ZfPilot 秉持 **"AI 负责原生生成，Agent 负责搬运与降噪"** 的极简原则：

- **零基础语法占用**：不将 UG835 的数千条 TCL 指令列入静态知识库。充分信任大模型预训练的 Vivado/Vitis 语法能力。
- **知识库仅存私有数据**：静态与动态知识库仅存储 AI 无法预知的私域数据（自定义 IP Schema、开发板引脚字典）。
- **高带宽管道**：提供底层"万能 TCL 执行器"，让 AI 一次性下发组合脚本，Agent 负责执行、监控超时并过滤冗长日志以保护 Token。

### 6.2 核心 MCP 工具接口清单

精简为 **5 大类工具**：

#### 一、核心执行引擎 (Core Pipeline)

| 工具 | 功能 | 说明 |
|------|------|------|
| `execute_vivado_tcl(script)` | 向 Vivado 提交任意 TCL 脚本 | 万能执行器，Socket/Persistent/Batch 自动选择 |
| `execute_xsct_tcl(script)` | 向 XSCT 提交 TCL 脚本 | 2018.3 SDK 管道，Socket(9901)/Batch 自动选择 |
| `execute_vitis_python(script)` | 向 Vitis 提交 Python 脚本 | 2025.2 跨代支持 |
| `run_os_command(cmd)` | 受限沙箱内系统命令 | 如 make、运行本地脚本 |

#### 二、环境与任务控制 (Environment & Async)

| 工具 | 功能 |
|------|------|
| `detect_toolchain_version()` | 扫描本地环境，返回 Vivado/Vitis 版本画像 |
| `init_workspace(path)` | 设定沙箱边界 + 触发 IP 扫描 + 版本隔离+自动创建标准工程目录结构 |
| `check_job_status(job_id)` | 异步任务轮询（综合/实现/比特流进度） |
| `get_execution_status()` | 查询当前引擎模式（Socket/Persistent/Batch） |
| `get_vivado_server_script(port)` | 获取 Socket 模式初始化 TCL 脚本 |
|  `get_socket_listen_status()`|返回当前各端口的监听状态（Vivado 是否在线、XSCT 是否在线、Vitis 是否在线）|
#### 三、动态上下文提取 (Context Fetching)

| 工具 | 功能 |
|------|------|
| `get_ip_schema(vlnv)` | 读取 IP 配置范围 + 公式约束 |
| `get_board_constraints(board)` | 获取开发板引脚分配字典 |
| `scan_workspace_for_ips()` | 显式触发 IP 目录全盘扫描（热重载） |
| `read_knowledge(file_path)` | 读取静态知识库文档 |

#### 四、结果反馈与降噪 (Feedback & Linter)

| 工具 | 功能 | Token 保护 |
|------|------|-----------|
| `read_log_summary(log_path, filter)` | 仅提取 ERROR/CRITICAL WARNING 行 | 拒绝返回 INFO |
| `get_timing_summary(rpt_path)` | 解析时序报告，仅返回 WNS/WHS/TNS 摘要 | 不返回全量路径 |
| `read_simulation_console(max_lines)` | 捕获 Testbench 的 `$display` 输出 | 限制行数 |

#### 五、高层语义工具 (High-Level Semantic)

在万能执行器之上封装的便捷工具，减少 AI 生成完整 TCL 脚本的负担：

| 工具 | 功能 |
|------|------|
| `create_vivado_project(name, path, part)` | 创建项目 |
| `open_vivado_project(xpr_path)` | 打开项目 |
| `add_design_sources(files, file_type)` | 添加源文件（含 .coe 识别） |
| `create_block_design(bd_name)` | 创建 BD |
| `add_zynq_ps(config)` | 添加并配置 ZYNQ PS |
| `add_ip_core(vlnv, cell_name, config)` | 通用 IP 添加 |
| `connect_axi_interface(master, slave)` | 连接 AXI 接口 |
| `connect_signal(pins)` | 连接信号线 |
| `auto_assign_address()` | 自动分配地址 |
| `auto_connect_clk_rst()` | 自动连接时钟复位 |
| `validate_and_save_bd()` | 验证保存 BD + 生成 Wrapper |
| `generate_xdc(constraints)` | 生成引脚约束 |
| `generate_gtx_xdc(refclk, gt_loc)` | 生成 GTX 约束 |
| `run_synthesis(jobs)` | 运行综合 |
| `run_implementation(jobs)` | 运行实现 |
| `generate_bitstream()` | 生成比特流 |
| `export_hardware()` | 版本自适应导出 (.sysdef/.xsa) |
| `check_timing()` | 时序检查 (WNS/WHS) |
| `generate_testbench(module)` | 🆕 生成 Testbench 模板 |
| `run_simulation(testbench)` | 🆕 运行 XSIM 行为级仿真 |
| `create_sw_project(workspace, app)` | 版本自适应创建软件工程 |
| `build_sw_project(workspace, app)` | 编译 |
| `import_sources(app, source_path)` | 导入源文件 |
| `debug_connect(host, port)` | JTAG 调试连接 |
| `download_and_run(elf, bit)` | 下载程序运行 |
| `read_memory(address, count)` | 读取目标板内存 |
| `generate_aurora_driver(config)` | Aurora 驱动代码生成 |
| `generate_dma_driver(config)` | DMA 驱动代码生成 |

---

## 7. 测试与验收标准

### 7.1 基础通信测试

大模型能通过 `execute_vivado_tcl` 成功创建一个空的 Vivado 工程并正确保存。

### 7.2 完整流程测试

AI 能在无人工干预下完成：创建项目 → 添加 PS → 添加 DMA IP → 连接 → 综合 → 实现 → 生成比特流 → 导出硬件。

### 7.3 高阶算法集成基准 (Benchmark)

让 ZfPilot 导入 MATLAB HDL Coder 生成的算法模块，使用非工程模式一键跑通综合，并让 AI 提取 DSP 资源消耗报告。

### 7.4 异常恢复率

人为在 XDC 约束文件中植入一个语法错误，验收大模型是否能在 `max_retry_count` 次重试内通过读取错误摘要自动发现并修复。

### 7.5 版本兼容性

同一套 AI 对话流程分别在 Vivado 2018.3 和 2025.2 环境下执行，验证版本自适应路由的正确性。

### 7.6 大模型能力基线

建议使用 Claude Sonnet 3.5+ 或 GPT-4o 级别模型。要求宿主客户端至少分配 100K 以上上下文窗口，以应对复杂的 IP Schema 解析和多文件联合审查。

---

## 8. 软件授权与商业化控制

### 8.1 授权时效体系

| 类型 | 有效期 |
|------|--------|
| 试用版 (Trial) | 7 天 |
| 月度订阅 (Monthly) | 30 天 |
| 年度订阅 (Annually) | 365 天 |
| 永久授权 (Lifetime) | 无限制 |

### 8.2 客户端激活流程

**在线激活（推荐）**：输入 License Key → 自动提取 Machine ID → HTTPS 发送至鉴权服务器 → 接收签名证书 (.lic) → 静默保存到 `.zfpilot/license/`。

**离线激活（涉密/内网环境）**：终端打印 Machine ID → 用户在可联网设备访问 `https://your-website.com/offline` 获取离线授权文件 → 放置到指定目录 → 本地公钥验签。

### 8.3 管理端发卡与管控

- **定向发卡**：管理员收集客户 Machine ID + 选择有效期 → 私钥签名生成专属激活码（机器绑定，防分享）。
- **可用性管理**：在线模式下可一键吊销 (Revoke) 任何激活码。
- **续费延期**：基于原 Machine ID 重新生成叠加新有效期的激活码。

### 8.4 安全防破解

- 采用 RSA/Ed25519 非对称加密，客户端仅内置公钥。
- 每次启动校验系统时间与硬件指纹，检测到篡改时间行为触发授权自毁保护。
- 本地验签是唯一真理——即使伪造服务器响应，无私钥也无法生成合法授权文件。

---

## 9. 版本路线图

| 版本 | 目标 | 优先级 |
|------|------|--------|
| **v2.0** | 核心 34 工具 + Socket/Persistent/Batch 三模式 + 动态 IP 知识库 | P0 |
| **v2.1** | 仿真工具 + 日志解析 + 异步任务 + 沙箱管理 | P1 |
| **v2.2** | 授权系统 + 配置管理 + 多开发板支持 | P2 |
| **v3.0** | Linux 跨平台 + 非工程模式 + Boot Image 生成 + SSE/HTTP 传输模式 | P3 |
