# ZfPilot v2.1 使用手册

> 包含: 使用方法 + 全部 45 个工具详细信息表

---

## 第一部分：使用方法

### 1. 基本工作流

在 Claude Desktop 中用自然语言描述你想做的事，AI 会自动调用对应工具：

```
你: "帮我创建一个 ZYNQ 项目叫 my_design，芯片 xc7z020clg400-2"
AI: → detect_version() → create_vivado_project(...)
    → Vivado GUI 中项目出现

你: "创建 Block Design，加一个 PS，启用 GP0 和 HP0"
AI: → read_knowledge("tcl/02_bd.md")
    → create_block_design() → add_zynq_ps(...)
    → GUI 中 PS 块出现，DDR/FIXED_IO 自动连接

你: "参考这个 PG021.pdf，帮我加一个 AXI DMA"
AI: → load_ip_doc("PG021.pdf", "axi_dma")    [首次加载]
    → read_ip_knowledge("axi_dma", "params")  [查参数]
    → add_ip_core(vlnv=..., config={...})      [添加IP]
    → GUI 中 DMA 块出现

你: "连接好所有接口，分配地址，验证保存"
AI: → connect_axi_interface(...) × N
    → auto_assign_address()
    → auto_connect_clk_rst()
    → validate_and_save_bd()

你: "综合、实现、生成比特流、导出硬件"
AI: → run_synthesis() → run_implementation()
    → generate_bitstream() → export_hardware()
```

### 2. Socket 模式（推荐）

Socket 模式下，AI 的每条命令都在你眼前的 Vivado GUI 中实时执行。

**启用方式**: 打开 Vivado → Tcl Console 输入 `source 你的路径/vivado_server.tcl`

**效果**: 你说"加一个 AXI DMA"，GUI 上就真的多出一个 DMA 的 IP 块。

### 3. IP 知识库用法

首次使用某个 IP 时需要投喂文档，之后永久可用：

```
你: "用这个 PG021.pdf 加载 AXI DMA 的知识"
AI: → load_ip_doc → 解析完成，缓存到 knowledge/ip/cache/axi_dma.json

你: "帮我查看已有的 IP 知识库"
AI: → list_ip_knowledge → 显示所有已缓存的 IP

你: "帮我配置 AXI DMA，64 位宽带 SG"
AI: → read_ip_knowledge("axi_dma", "params") → 确认参数范围
    → add_ip_core(config={"CONFIG.c_m_axi_mm2s_data_width": "64", ...})
```

### 4. 常用对话示例

| 你说 | AI 调用的工具 |
|------|-------------|
| "检测 Vivado 版本" | `detect_version` |
| "查看引擎状态" | `get_execution_status` |
| "给我 Socket 初始化脚本" | `get_vivado_server_script` |
| "创建项目 TEST01" | `create_vivado_project` |
| "打开 D:/proj/test.xpr" | `open_vivado_project` |
| "创建 Block Design" | `create_block_design` |
| "加 PS，开 GP0 HP0 100MHz" | `add_zynq_ps` |
| "加一个 AXI DMA" | `add_ip_core` |
| "连接 PS 的 GP0 到 DMA" | `connect_axi_interface` |
| "自动分配地址" | `auto_assign_address` |
| "验证并保存 BD" | `validate_and_save_bd` |
| "生成 LED 约束" | `generate_xdc` |
| "综合" | `run_synthesis` |
| "实现" | `run_implementation` |
| "生成比特流" | `generate_bitstream` |
| "导出硬件" | `export_hardware` |
| "检查时序" | `check_timing` |
| "创建软件工程" | `create_sw_project` |
| "编译" | `build_sw_project` |
| "下载到板子上运行" | `download_and_run` |
| "生成 DMA 驱动代码" | `generate_dma_driver` |
| "生成 testbench" | `generate_testbench` |
| "运行仿真" | `run_simulation` |
| "查看仿真输出" | `read_simulation_console` |
| "查看日志摘要" | `read_log_summary` |
| "查看时序报告" | `get_timing_summary` |
| "初始化工作空间" | `init_workspace` |
| "查看沙箱状态" | `get_sandbox_status` |
| "执行原始 TCL" | `run_tcl` |
| "查看 Socket 状态" | `get_socket_listen_status` |
| "执行系统命令" | `run_os_command` |

---

## 第二部分：工具详细信息表（34 个）

### 分类 1：系统知识库（2 个）

#### 1.1 detect_version

| 属性 | 内容 |
|------|------|
| **功能** | 检测 Vivado 版本，确定工具链配置 |
| **输入** | `force_redetect` (bool, 默认 false) |
| **输出** | `{ version, major_year, vivado_exe, sdk_exe/vitis_exe, export_format, sw_engine }` |
| **实现** | 执行 `vivado -version`，解析版本号，写入缓存 |
| **缓存** | `knowledge/cache/detected_version.json` |
| **触发** | MCP 启动时自动调用一次 |

#### 1.2 read_knowledge

| 属性 | 内容 |
|------|------|
| **功能** | 读取静态知识库文档 |
| **输入** | `file_path` (str) |
| **可选值** | `SKILL.md`, `tcl/01_project.md`, `tcl/02_bd.md`, `tcl/03_synthesis.md`, `tcl/04_constraints.md`, `sdk/xsct.md`, `sdk/vitis_python.md`, `board/alientek_alpha.md` |
| **输出** | 文档文本内容 |
| **规则** | 创建BD前→02_bd.md，综合前→03_synthesis.md，写XDC前→board/+04_constraints.md |

---

### 分类 2：引擎管理（3 个）

#### 2.1 get_vivado_server_script

| 属性 | 内容 |
|------|------|
| **功能** | 获取 Vivado GUI 端的 Socket 服务器 TCL 脚本 |
| **输入** | `port` (int, 默认 9900) |
| **输出** | TCL 脚本文本 + 使用说明 |
| **用途** | 用户粘贴到 Vivado Tcl Console 启动 Socket 模式 |

#### 2.2 get_execution_status

| 属性 | 内容 |
|------|------|
| **功能** | 查询当前执行引擎状态 |
| **输入** | 无 |
| **输出** | `{ active_mode, socket_available, socket_endpoint, persistent_alive, vivado_exe }` |

#### 2.3 start_persistent_vivado

| 属性 | 内容 |
|------|------|
| **功能** | 启动常驻 Vivado 进程（无 GUI 的 Tcl 模式） |
| **输入** | 无 |
| **输出** | 启动状态 |
| **说明** | 比 batch 快，但没有 GUI 可视化 |

---

### 分类 3：IP 知识库（3 个）

#### 3.1 load_ip_doc

| 属性 | 内容 |
|------|------|
| **功能** | 解析 IP 官方 PDF 文档，缓存为 JSON。只需调用一次 |
| **输入** | `pdf_path` (str), `ip_name` (str), `overwrite` (bool, 默认 false) |
| **输出** | `{ ip_name, vlnv, param_count, interfaces, cache_path, status }` |
| **解析内容** | VLNV、全部 CONFIG.xxx 参数（名称/类型/范围/默认值）、接口列表、驱动要点 |
| **缓存路径** | `knowledge/ip/cache/{ip_name}.json` |

#### 3.2 list_ip_knowledge

| 属性 | 内容 |
|------|------|
| **功能** | 列出所有已缓存的 IP 文档 |
| **输入** | 无 |
| **输出** | `[{ ip_name, vlnv, param_count, parsed_at }]` |

#### 3.3 read_ip_knowledge

| 属性 | 内容 |
|------|------|
| **功能** | 读取某个 IP 的缓存知识 |
| **输入** | `ip_name` (str), `section` (str: all/params/interfaces/typical/driver) |
| **输出** | 对应缓存内容 |
| **用途** | AI 确认参数后再调用 add_ip_core |

---

### 分类 4：Vivado 工程（3 个）

#### 4.1 create_vivado_project

| 属性 | 内容 |
|------|------|
| **功能** | 创建新的 Vivado 项目 |
| **输入** | `project_name` (str), `project_path` (str), `part` (str, 默认 "xc7z020clg400-2"), `board_part` (str, 可选) |
| **TCL** | `create_project {name} {path} -part {part}` |
| **输出** | `{ success, project_name, xpr_file, part }` |

#### 4.2 open_vivado_project

| 属性 | 内容 |
|------|------|
| **功能** | 打开已有 Vivado 项目 |
| **输入** | `project_file` (str, .xpr 完整路径) |
| **TCL** | `open_project {file}` |

#### 4.3 add_source_file

| 属性 | 内容 |
|------|------|
| **功能** | 添加源文件到项目 |
| **输入** | `file_name` (str), `content` (str), `project_path` (str), `file_type` (verilog/vhdl/xdc/tcl) |
| **TCL** | 写文件 → `add_files -norecurse {file}` → `update_compile_order` |

---

### 分类 5：Block Design（8 个）

#### 5.1 create_block_design

| 属性 | 内容 |
|------|------|
| **功能** | 创建 Block Design |
| **输入** | `project_xpr` (str), `bd_name` (str, 默认 "system") |
| **TCL** | `create_bd_design "{bd_name}"` |
| **前置** | `read_knowledge("tcl/02_bd.md")` |

#### 5.2 add_zynq_ps

| 属性 | 内容 |
|------|------|
| **功能** | 添加并配置 ZYNQ PS 处理系统 |
| **输入** | `project_xpr`, `bd_name`, `enable_axi_gp0/gp1` (bool), `enable_axi_hp0/hp1` (bool), `enable_uart0/uart1` (bool), `fclk0_mhz/fclk1_mhz` (float), `apply_preset` (bool) |
| **TCL** | `create_bd_cell -type ip -vlnv xilinx.com:ip:processing_system7:5.5` → `apply_bd_automation` → `set_property -dict [...]` |
| **前置** | `read_knowledge("tcl/02_bd.md")` |

#### 5.3 add_ip_core

| 属性 | 内容 |
|------|------|
| **功能** | 添加通用 IP 核（配合 IP 知识库） |
| **输入** | `project_xpr`, `vlnv` (str, 如 "xilinx.com:ip:axi_dma:7.1"), `cell_name` (str), `config` (dict), `bd_name` |
| **TCL** | `create_bd_cell -type ip -vlnv {vlnv} {cell_name}` → `set_property -dict [list CONFIG.xxx {val}]` |
| **前置** | `read_ip_knowledge("{ip_name}", "params")` |

#### 5.4 connect_axi_interface

| 属性 | 内容 |
|------|------|
| **功能** | 连接 AXI 接口 |
| **输入** | `project_xpr`, `master` (str, 如 "processing_system7_0/M_AXI_GP0"), `slave` (str), `bd_name` |
| **TCL** | `connect_bd_intf_net [get_bd_intf_pins {master}] [get_bd_intf_pins {slave}]` |

#### 5.5 connect_signal

| 属性 | 内容 |
|------|------|
| **功能** | 连接信号线 |
| **输入** | `project_xpr`, `pins` (list[str], ≥2 个引脚路径), `bd_name` |
| **TCL** | `connect_bd_net [get_bd_pins pin1] [get_bd_pins pin2]` |

#### 5.6 auto_assign_address

| 属性 | 内容 |
|------|------|
| **功能** | 自动分配地址空间 |
| **输入** | `project_xpr`, `bd_name` |
| **TCL** | `assign_bd_address` |

#### 5.7 auto_connect_clk_rst

| 属性 | 内容 |
|------|------|
| **功能** | 自动连接时钟和复位信号 |
| **输入** | `project_xpr`, `bd_name` |
| **TCL** | `apply_bd_automation -rule xilinx.com:bd_rule:clkrst` |

#### 5.8 validate_and_save_bd

| 属性 | 内容 |
|------|------|
| **功能** | 验证并保存 Block Design，可选生成 HDL Wrapper |
| **输入** | `project_xpr`, `bd_name`, `make_wrapper` (bool, 默认 true) |
| **TCL** | `validate_bd_design` → `save_bd_design` → `make_wrapper -files [...] -top` |

---

### 分类 6：约束生成（2 个）

#### 6.1 generate_xdc

| 属性 | 内容 |
|------|------|
| **功能** | 生成 XDC 引脚约束文件 |
| **输入** | `output_path` (str), `constraints` (list[{port, package_pin, iostandard, comment, group}]), `project_path` (可选) |
| **输出** | 生成 .xdc 文件 |
| **前置** | `read_knowledge("board/alientek_alpha.md")` + `read_knowledge("tcl/04_constraints.md")` |

#### 6.2 generate_gtx_xdc

| 属性 | 内容 |
|------|------|
| **功能** | 生成 GTX 高速收发器约束 |
| **输入** | `output_path`, `refclk_pin_p/n` (str), `refclk_freq_mhz` (float), `gt_location` (str, 可选), `protocol` (str) |
| **输出** | 生成 GTX .xdc 文件（含参考时钟、跨时钟域约束） |

---

### 分类 7：综合实现（5 个）

#### 7.1 run_synthesis

| 属性 | 内容 |
|------|------|
| **功能** | 运行综合 |
| **输入** | `project_xpr`, `jobs` (int, 默认 4), `timeout` (int, 默认 1800) |
| **TCL** | `reset_run synth_1` → `launch_runs synth_1 -jobs {jobs}` → `wait_on_run synth_1` |
| **输出** | `{ success, status, progress, warnings, elapsed_seconds }` |
| **前置** | `read_knowledge("tcl/03_synthesis.md")` |

#### 7.2 run_implementation

| 属性 | 内容 |
|------|------|
| **功能** | 运行实现 (Place & Route) |
| **输入** | `project_xpr`, `jobs` (int), `timeout` (int, 默认 3600) |
| **TCL** | `launch_runs impl_1 -jobs {jobs}` → `wait_on_run impl_1` |

#### 7.3 generate_bitstream

| 属性 | 内容 |
|------|------|
| **功能** | 生成比特流 |
| **输入** | `project_xpr`, `timeout` (int) |
| **TCL** | `launch_runs impl_1 -to_step write_bitstream` |
| **输出** | `{ success, bit_file, elapsed_seconds }` |

#### 7.4 export_hardware

| 属性 | 内容 |
|------|------|
| **功能** | 导出硬件定义（★版本自适应★） |
| **输入** | `project_xpr`, `export_path` (str, 可选), `include_bitstream` (bool) |
| **2018.3** | `write_hwdef` + `write_sysdef` → `.sysdef` |
| **2025.2** | `write_hw_platform -fixed -force -include_bit` → `.xsa` |
| **输出** | `{ success, file, format(sysdef/xsa), version }` |

#### 7.5 check_timing

| 属性 | 内容 |
|------|------|
| **功能** | 检查时序 |
| **输入** | `project_xpr` |
| **TCL** | `report_timing_summary -max_paths 10` |
| **输出** | `{ wns, whs, passed(bool) }` |
| **判定** | WNS ≥ 0 且 WHS ≥ 0 为通过 |

---

### 分类 8：SDK/Vitis 软件（3 个）

#### 8.1 create_sw_project

| 属性 | 内容 |
|------|------|
| **功能** | 创建软件工程（★版本自适应★） |
| **输入** | `workspace` (str), `app_name` (str), `hw_file` (str, 2018→.sysdef, 2025→.xsa), `processor` (默认 "ps7_cortexa9_0"), `os_type` (默认 "standalone"), `template` (默认 "Empty Application") |
| **2018.3** | `setws` → `createhw` → `createbsp` → `createapp` |
| **2025.2** | `set_workspace` → `create_platform_component` → `create_app_component` |

#### 8.2 build_sw_project

| 属性 | 内容 |
|------|------|
| **功能** | 编译软件工程 |
| **输入** | `workspace`, `app_name`, `build_config` ("Debug"/"Release") |
| **2018.3** | `projects -build -type app -name {app_name}` |
| **2025.2** | `component.build()` |

#### 8.3 import_sources

| 属性 | 内容 |
|------|------|
| **功能** | 导入源文件到软件工程 |
| **输入** | `workspace`, `app_name`, `source_path` |
| **2018.3** | `importsources -name {app_name} -path {source_path}` |
| **2025.2** | 复制文件到组件 src 目录 |

---

### 分类 9：调试（3 个）

#### 9.1 debug_connect

| 属性 | 内容 |
|------|------|
| **功能** | JTAG 调试连接 |
| **输入** | `host` (默认 "localhost"), `port` (默认 3121), `target_filter` (默认 "ARM*#0") |
| **2018.3** | `connect -host {host}` → `targets -set -filter {name =~ "ARM*#0"}` |
| **2025.2** | `session.connect(url="TCP:...")` → `session.targets(...)` |

#### 9.2 download_and_run

| 属性 | 内容 |
|------|------|
| **功能** | 下载比特流/程序并运行 |
| **输入** | `elf_file` (str), `bit_file` (可选), `hdf_file` (仅2018.3), `reset_processor` (bool), `host`, `port`, `target_filter` |
| **2018.3** | `fpga {bit}` → `loadhw {hdf}` → `rst -processor` → `dow {elf}` → `con` |
| **2025.2** | `session.fpga()` → `session.rst()` → `session.dow()` → `session.con()` |

#### 9.3 read_memory

| 属性 | 内容 |
|------|------|
| **功能** | 读取目标板内存 |
| **输入** | `address` (str, 十六进制), `count` (int, 默认 1), `host`, `port` |
| **实现** | `mrd {address} {count}` |

---

### 分类 10：驱动生成（2 个）

#### 10.1 generate_aurora_driver

| 属性 | 内容 |
|------|------|
| **功能** | 生成 Aurora 驱动代码 |
| **输入** | `output_path`, `protocol` ("8b10b"/"64b66b"), `mode` ("simplex_tx"/"simplex_rx"/"duplex"), `use_dma` (bool), `use_interrupt` (bool) |
| **输出** | `aurora_driver.c` + `aurora_driver.h` |
| **前置** | `read_ip_knowledge("aurora_8b10b")` |

#### 10.2 generate_dma_driver

| 属性 | 内容 |
|------|------|
| **功能** | 生成 AXI DMA 驱动代码 |
| **输入** | `output_path`, `device_id` (int), `buffer_size` (int), `use_interrupt` (bool) |
| **输出** | `dma_driver.c` + `dma_driver.h` |
| **前置** | `read_ip_knowledge("axi_dma")` |

---

### 分类 11：仿真（3 个）— v2.1 新增

#### 11.1 generate_testbench

| 属性 | 内容 |
|------|------|
| **功能** | 自动生成 Testbench 文件 |
| **输入** | `project_xpr` (str), `top_module` (str), `clock_period_ns` (float, 默认 10.0), `sim_time_us` (float, 默认 100.0) |
| **输出** | `{ success, tb_file, top_module }` |
| **说明** | 根据顶层模块端口自动生成激励，包含时钟和复位逻辑 |

#### 11.2 run_simulation

| 属性 | 内容 |
|------|------|
| **功能** | 运行行为仿真 |
| **输入** | `project_xpr` (str), `sim_set` (str, 默认 "sim_1"), `timeout` (int, 默认 600) |
| **TCL** | `launch_simulation -mode behavioral` |
| **输出** | `{ success, status, log_summary }` |

#### 11.3 read_simulation_console

| 属性 | 内容 |
|------|------|
| **功能** | 读取仿真控制台输出 |
| **输入** | `project_xpr` (str), `max_lines` (int, 默认 100) |
| **输出** | 仿真运行期间的控制台文本（`$display` 输出等） |

---

### 分类 12：报告与日志解析（2 个）— v2.1 新增

#### 12.1 read_log_summary

| 属性 | 内容 |
|------|------|
| **功能** | 读取并汇总 Vivado 日志文件 |
| **输入** | `log_path` (str), `max_lines` (int, 默认 200) |
| **输出** | `{ total_lines, errors, critical_warnings, warnings, info, summary_lines }` |
| **说明** | 自动提取 ERROR/CRITICAL WARNING/WARNING 行，截断长日志防撑爆上下文 |

#### 12.2 get_timing_summary

| 属性 | 内容 |
|------|------|
| **功能** | 解析时序报告，提取关键指标 |
| **输入** | `report_path` (str) |
| **输出** | `{ wns, whs, tns, ths, failing_endpoints, passed }` |
| **判定** | WNS ≥ 0 且 WHS ≥ 0 为通过 |

---

### 分类 13：系统与沙箱（5 个）— v2.1 新增

#### 13.1 init_workspace

| 属性 | 内容 |
|------|------|
| **功能** | 初始化 ZfPilot 工作空间，设定路径隔离根目录 |
| **输入** | `workspace_path` (str) |
| **输出** | `{ success, workspace_path, created }` |
| **沙箱** | 后续所有文件操作不得逃逸此目录 |

#### 13.2 get_sandbox_status

| 属性 | 内容 |
|------|------|
| **功能** | 查询当前沙箱状态 |
| **输入** | 无 |
| **输出** | `{ workspace, initialized, path_isolation }` |

#### 13.3 run_tcl

| 属性 | 内容 |
|------|------|
| **功能** | 直接执行原始 TCL 命令（高级用户） |
| **输入** | `command` (str), `timeout` (int, 默认 30) |
| **输出** | TCL 执行结果文本 |
| **安全** | 仅限 localhost Socket 通道执行 |

#### 13.4 get_socket_listen_status

| 属性 | 内容 |
|------|------|
| **功能** | 检测 Vivado Socket 服务器连接状态 |
| **输入** | `port` (int, 默认 9900) |
| **输出** | `{ connected, host, port, latency_ms }` |
| **用途** | 诊断连接问题，确认 Socket 模式可用 |

#### 13.5 run_os_command

| 属性 | 内容 |
|------|------|
| **功能** | 在沙箱内执行操作系统命令 |
| **输入** | `command` (str), `cwd` (str, 可选), `timeout` (int, 默认 30) |
| **输出** | `{ stdout, stderr, returncode }` |
| **安全** | 工作目录受沙箱路径限制 |

---

## 工具总览表

| # | 工具名 | 分类 | 版本适配 |
|---|--------|------|---------|
| 1 | `detect_version` | 系统知识库 | 通用 |
| 2 | `read_knowledge` | 系统知识库 | 通用 |
| 3 | `get_vivado_server_script` | 引擎管理 | 通用 |
| 4 | `get_execution_status` | 引擎管理 | 通用 |
| 5 | `start_persistent_vivado` | 引擎管理 | 通用 |
| 6 | `load_ip_doc` | IP 知识库 | 通用 |
| 7 | `list_ip_knowledge` | IP 知识库 | 通用 |
| 8 | `read_ip_knowledge` | IP 知识库 | 通用 |
| 9 | `create_vivado_project` | Vivado 工程 | 通用 |
| 10 | `open_vivado_project` | Vivado 工程 | 通用 |
| 11 | `add_source_file` | Vivado 工程 | 通用 |
| 12 | `create_block_design` | Block Design | 通用 |
| 13 | `add_zynq_ps` | Block Design | 通用 |
| 14 | `add_ip_core` | Block Design | 通用 |
| 15 | `connect_axi_interface` | Block Design | 通用 |
| 16 | `connect_signal` | Block Design | 通用 |
| 17 | `auto_assign_address` | Block Design | 通用 |
| 18 | `auto_connect_clk_rst` | Block Design | 通用 |
| 19 | `validate_and_save_bd` | Block Design | 通用 |
| 20 | `generate_xdc` | 约束 | 通用 |
| 21 | `generate_gtx_xdc` | 约束 | 通用 |
| 22 | `run_synthesis` | 综合实现 | 通用 |
| 23 | `run_implementation` | 综合实现 | 通用 |
| 24 | `generate_bitstream` | 综合实现 | 通用 |
| 25 | `export_hardware` | 综合实现 | ★自适应 |
| 26 | `check_timing` | 综合实现 | 通用 |
| 27 | `create_sw_project` | SDK/Vitis | ★自适应 |
| 28 | `build_sw_project` | SDK/Vitis | ★自适应 |
| 29 | `import_sources` | SDK/Vitis | ★自适应 |
| 30 | `debug_connect` | 调试 | ★自适应 |
| 31 | `download_and_run` | 调试 | ★自适应 |
| 32 | `read_memory` | 调试 | ★自适应 |
| 33 | `generate_aurora_driver` | 驱动生成 | 通用 |
| 34 | `generate_dma_driver` | 驱动生成 | 通用 |
| 35 | `generate_testbench` | 仿真 | 通用 |
| 36 | `run_simulation` | 仿真 | 通用 |
| 37 | `read_simulation_console` | 仿真 | 通用 |
| 38 | `read_log_summary` | 报告解析 | 通用 |
| 39 | `get_timing_summary` | 报告解析 | 通用 |
| 40 | `init_workspace` | 系统沙箱 | 通用 |
| 41 | `get_sandbox_status` | 系统沙箱 | 通用 |
| 42 | `run_tcl` | TCL 引擎 | 通用 |
| 43 | `get_socket_listen_status` | TCL 引擎 | 通用 |
| 44 | `run_os_command` | 系统工具 | 通用 |
| 45 | `refresh_ip_knowledge` | IP 知识库 | 通用 |

> **★自适应** = 根据 detect_version 结果，自动选择 2018.3(XSCT) 或 2025.2(Vitis Python) 的命令路径

---

## 版本变更记录

### v2.1.0 新增功能

| 新增工具 | 分类 | 说明 |
|---------|------|------|
| `generate_testbench` | 仿真 | 自动生成 Testbench |
| `run_simulation` | 仿真 | 运行行为仿真 |
| `read_simulation_console` | 仿真 | 读取仿真输出 |
| `read_log_summary` | 报告解析 | 日志文件汇总分析 |
| `get_timing_summary` | 报告解析 | 时序报告解析 |
| `init_workspace` | 系统沙箱 | 工作空间初始化与隔离 |
| `get_sandbox_status` | 系统沙箱 | 沙箱状态查询 |
| `run_tcl` | TCL 引擎 | 原始 TCL 命令执行 |
| `get_socket_listen_status` | TCL 引擎 | Socket 连接诊断 |
| `run_os_command` | 系统工具 | 沙箱内命令执行 |
| `refresh_ip_knowledge` | IP 知识库 | 增量刷新 IP 缓存 |
