跳到快速开始
INSTALL · CONNECT · BUILD

SynthPilot 文档

从安装到配置，一页搞定

快速开始

# 将这条命令发送给你的 AI 工具

$ curl -sL https://www.synthpilot.dev/llms.txt

# AI 会自动引导你完成安装、激活和配置

支持任何 AI 编程工具 — AI 读取后即可引导你完成全部流程

AI 指南 (llms.txt)

llms.txt 是一份专为 AI 设计的机器可读文档，包含 SynthPilot 的完整使用说明。

什么是 llms.txt？

llms.txt 是一份结构化的纯文本文档，AI 可以快速读取并理解 SynthPilot 的全部功能。当你将 curl 命令的输出发送给 AI 后，AI 能够：

  • 引导你完成安装和 License 激活
  • 选择 Vivado、Anlogic TD 或 Quartus 并配置 MCP
  • 了解所有 CLI 命令和使用方式
  • 排查常见问题（连接失败、端口冲突等）

使用方式

在任意 AI 编程工具中执行以下命令，然后告诉 AI 你想做什么：

Terminal 
$ curl -sL https://www.synthpilot.dev/llms.txt

你也可以直接访问 synthpilot.dev/llms.txt 查看完整内容。

MCP 配置

选择你使用的 AI 工具，按照对应说明完成配置。

推荐：synthpilot setup（自动注册，免手改 JSON）

推荐

用 --platform 选择 Vivado、Anlogic TD 或 Quartus；setup 会完成平台发现、授权、MCP 注册和健康检查。每个 MCP 进程只加载一个平台。

Terminal 
$ synthpilot setup --platform vivado

已经装好但出问题？运行 synthpilot doctor 自检，synthpilot doctor --fix 自动修复注册 / 连接问题。

手动配置（高级 / 其他客户端）

如果 setup 无法覆盖你的客户端（如 Trae、CodeBuddy、Cline），可手动编辑下列 JSON 配置。

配置文件位置

Windows: %APPDATA%\Claude\claude_desktop_config.json

uv 安装方式（复制即用）

claude_desktop_config.json 
{
  "mcpServers": {
    "synthpilot": {
      "command": "synthpilot"
    }
  }
}

uvx 方式（隔离 Python 环境）

claude_desktop_config.json 
{
  "mcpServers": {
    "synthpilot": {
      "command": "uvx",
      "args": ["synthpilot@latest"]
    }
  }
}
修改配置文件后需要重启 Claude Desktop 才能生效。

远程 Vivado over SSH

Beta

在远程 Linux 开发机上运行 SynthPilot，并连接同一台机器上已经启动的 Vivado。MCP 通过 SSH stdio 传输，Vivado Tcl 端口只监听远程回环地址。

当前状态：Beta

远程 profile、诊断和 MCP 注册已经提供；完整的远程 Linux + Vivado 端到端真机矩阵仍在验收。建议先用于受控开发环境。

远程主机需要

  • Linux 与可通过本机 SSH config 访问的可信主机别名
  • 已安装并激活 SynthPilot 1.4.0 或更高版本
  • 已在交互会话中启动 Vivado，并安装 SynthPilot Tcl Server
  • Tcl Server 使用 protocol 1，并且只监听 127.0.0.1

能力边界

  • MCP 工具中的文件路径均指向远程 Linux 文件系统
  • 不会自动同步源码或下载生成的工程目录
  • 不会自动启动 Vivado；请先在远程图形或交互会话中打开它
  • 不要把 Vivado Tcl 端口暴露到网络，远程访问只走 SSH

配置步骤

在本机终端运行 
# 1. Test the SSH alias
ssh vivado-lab

# 2. Add, diagnose, and register the remote MCP profile
synthpilot remote add lab vivado-lab
synthpilot remote doctor lab
synthpilot install-mcp --remote lab

连接详情、用户名、端口和密钥请放在本机 SSH config 中；不要把私钥或密码写进 MCP 配置。

CLI 命令参考

命令 说明
synthpilot setup --platform <name> 为 Vivado、Anlogic TD 或 Quartus 执行发现、授权、MCP 注册与健康检查
synthpilot doctor --platform <name> 诊断安装 / 注册 / 连接问题；--fix 自动修复
synthpilot install-mcp --platform <name> 把 MCP 自动注册进检测到的 AI 客户端（Claude Code/Desktop/Cursor/Codex）
synthpilot --platform <name> 启动指定平台的 MCP 服务（通常由 AI 工具自动调用）
synthpilot install 自动检测 Vivado 并安装集成
synthpilot install <path> --port <n> 指定 Vivado 路径和端口
synthpilot uninstall 移除 Vivado 集成
synthpilot activate <KEY> 激活 License
synthpilot deactivate 解绑当前设备
synthpilot --version 显示版本号

升级更新

当有新版本发布时，请及时更新以获取最新功能和修复。

uv 安装用户

# 升级到最新版

$ uv tool upgrade synthpilot

Windows 用户请先关闭 AI 工具（Claude Code / Cursor 等），再执行升级命令。运行中的 SynthPilot 进程会锁定 exe 文件导致更新失败。

uvx 用户

# 清除缓存并拉取最新版

$ uvx synthpilot@latest --version

uvx 会缓存已安装的包。直接运行 uvx synthpilot 可能使用旧版本，必须使用 synthpilot@latest 才能确保拉取最新版。

如果你曾通过 uv tool install synthpilot 安装过，全局版本会优先于 uvx @latest。请先运行 uv tool upgrade synthpilot 升级全局版本，或 uv tool uninstall synthpilot 移除后再使用 uvx。

如果 MCP 配置中使用了 synthpilot@latest，只需重启 AI 工具即可自动更新，无需手动操作。

# 强制重新安装（缓存异常时使用）

$ uvx --reinstall synthpilot@latest --version

验证版本

# 查看当前版本

$ synthpilot --version

也可以通过 MCP 工具 get_license_status 查看当前运行版本。

功能概览

FREE V43 · A4 · Q6
  • 项目管理
  • 综合 & 实现
  • 时序报告
  • 约束管理
  • 设备编程
  • 基础文件操作
PRO
PRO V475 · A90 · Q24
  • 以上全部功能
  • IP 配置（Clocking Wizard, FIFO, BRAM 等）
  • Block Design（AXI, Zynq PS, 调试核心等）
  • Linting & 代码质量（30 条规则）
  • 仿真引擎（xsim 流程）
  • 高级报告分析
查看价格
MAX
MAX V510 · A102 · Q24
  • 以上全部功能
  • Max 专属高级工具
  • Non-Project Mode
  • JTAG-AXI 调试
  • ILA 硬件调试
  • VIO 硬件调试
  • 3 台设备授权
查看价格

oh-my-fpga 方法论

oh-my-fpga 是一层免费的方法论 —— 命名的专家工作流（收敛时序、审查 CDC、搭 Zynq SoC），把资深工程师的经验沉淀成可复用的步骤。

Claude Code：安装插件

在 Claude Code 中依次运行下面两条命令安装插件，即可在 "/" 菜单里使用全部工作流。

Claude Code 
/plugin marketplace add LNC0831/oh-my-fpga
/plugin install oh-my-fpga

Cursor / Codex / Claude Desktop：内置 MCP prompts

同样这 13 个工作流作为内置 MCP prompts 随 SynthPilot 1.3.0+ 一起发布 —— 在客户端的 "/" 菜单里直接选用，无需额外安装。

需要 SynthPilot 1.3.0 或更高版本。

了解全部工作流：github.com/LNC0831/oh-my-fpga

工作原理

🤖
AI 工具
Claude / Cursor / Codex
MCP (stdio)
SynthPilot
SynthPilot
MCP Server
TCP:9999
🔧
Selected FPGA EDA
Vivado / Anlogic TD / Quartus
1

AI 工具通过 MCP 协议（标准输入输出）调用 SynthPilot

2

SynthPilot 将工具调用转为 Tcl 命令

3

通过对应平台的本地受管适配器执行结构化操作

4

结果原路返回给 AI 工具

所有数据本地传输，不经过任何云端

常见问题

安装后 AI 工具找不到 SynthPilot？

先运行 synthpilot doctor 自检（synthpilot doctor --fix 可自动修复大部分注册 / 连接问题）。

如仍未解决：检查系统 PATH，确保 synthpilot 命令在终端中可用。可以运行 synthpilot --version 验证。

如果提示找不到命令，运行以下命令找到 Scripts 目录并添加到 PATH：

python -c "import sysconfig; print(sysconfig.get_path('scripts'))"

替代方案：使用 python -m synthpilot 或 uvx synthpilot 代替直接调用 synthpilot。

平台发现或连接失败？

运行 synthpilot doctor --platform <name> 查看对应平台的诊断，再用 synthpilot setup --platform <name> 修复发现与 MCP 注册问题。

如何更新 SynthPilot？

uv tool upgrade synthpilot

详细的升级方法（包括 uvx 用户）请参阅 升级更新 章节。

端口冲突怎么办？

如果默认端口 9999 被占用，可以指定其他端口：

synthpilot install --port 9998

各版本有什么区别？

Free、Pro、Max 的工具数按平台分别计算，MCP 只注册当前选择的平台。查看完整工具目录。

升级许可证后新功能没有生效？

升级 License 后需要重新连接 MCP 服务以加载新权限。在 Claude Code 中执行 /mcp 重连；Cursor 等工具中重启 MCP 服务或重启编辑器即可。