SynthPilot 文档

从安装到配置，一页搞定

快速开始

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

$ curl -sL https://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 集成和 MCP 连接
  • 了解所有 CLI 命令和使用方式
  • 排查常见问题（连接失败、端口冲突等）

使用方式

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

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

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

MCP 配置

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

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

推荐

一条引导式命令即可检测 Vivado、安装 Tcl 服务器、激活授权，并把 SynthPilot 自动注册进 Claude Code、Claude Desktop、Cursor、Codex，最后跑一遍健康检查。无需手动编辑任何配置文件。

Terminal 
$ synthpilot setup

已经装好但出问题？运行 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 才能生效。

CLI 命令参考

命令 说明
synthpilot setup 引导式一键配置（Vivado + 授权 + MCP 自动注册 + 健康检查）
synthpilot doctor [--fix] 诊断安装 / 注册 / 连接问题；--fix 自动修复
synthpilot install-mcp 把 MCP 自动注册进检测到的 AI 客户端（Claude Code/Desktop/Cursor/Codex）
synthpilot 启动 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 40 个工具
  • 项目管理
  • 综合 & 实现
  • 时序报告
  • 约束管理
  • 设备编程
  • 基础文件操作
PRO
PRO 475+ 个工具
  • 以上全部功能
  • IP 配置（Clocking Wizard, FIFO, BRAM 等）
  • Block Design（AXI, Zynq PS, 调试核心等）
  • Linting & 代码质量（30 条规则）
  • 仿真引擎（xsim 流程）
  • 高级报告分析
查看价格
MAX
MAX 500+ 个工具
  • 以上全部功能
  • 自定义 Tcl 命令
  • 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
🔧
Vivado
tcl_server
1

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

2

SynthPilot 将工具调用转为 Tcl 命令

3

通过 TCP 发送到 Vivado 内运行的 tcl_server

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。

Vivado 连接失败？

先运行 synthpilot doctor（或 synthpilot doctor --fix 自动修复）。同时确认已执行 synthpilot setup / synthpilot install，且 Vivado 已打开并加载了项目。SynthPilot 需要 Vivado 的 tcl_server 在运行状态。

如何更新 SynthPilot？

uv tool upgrade synthpilot

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

端口冲突怎么办？

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

synthpilot install --port 9998

各版本有什么区别？

免费版包含 40 个基础工具，足够完成常规 FPGA 开发流程。Pro 版解锁 475+ 工具，包括 IP 配置、Block Design、Linter、仿真等。Max 旗舰版解锁全部 500+ 工具，额外提供自定义 Tcl、Non-Project Mode、硬件调试运行时等高级功能。查看价格详情。

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

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