本机适配注记（非 AMD 原文；2026-10-18 由 DSH 会话追加）
- 工具链不同：本机用第三方 vivado-mcp（现役安装
<vivado-mcp>，32 个工具），不是官方vivado-mcp-server；仓库内<EIF 仓库>\vivado-mcp是零改动随仓副本、不是运行实例（客户端必须显式设PYTHONPATH=<vivado-mcp>\site，否则 venv 的_mcp_pilot_paths.pth会命中.mcp-pilot中文路径副本 →start_session静默失败）。- 工具映射：
vivadoExecute/vivado_execute→run_tcl/safe_tcl；vivado_start→start_session；vivado_stop→stop_session；vivado_list_sessions→list_sessions；vivado_status→get_run_progress；vivado_log_messages→get_critical_warnings（仅 runme.log）或read/grep；read_file→read；create_file→write；replace_string_in_file→edit；file_search→glob；grep_search→grep；run_in_terminal→pwsh；runSubagent→subagent。- 会话没挂 MCP 工具时走 CLI 桥：
python <vivado-mcp>\mcp_ctl.py session "<多行 Tcl>"（等价 run_tcl）、call <tool> --args-file <json>、list。一次调用一个 MCP 进程，多步会话必须写成单次session。（2026-10-24 已在 desktop profile 配置mcp__vivado__*，需重启宿主生效；未生效时 CLI 桥仍是唯一通路。）- 版本事实：Vivado 2023.1（官方基线 2026.1）；Python 用
<python 解释器：见 config.yml 的 python（install.ps1 写入实际值）>。- 文档检索：本机无
vivado_doc_search，改用web_fetch（docs.amd.com / 官方 docs）或本项目<project_root>\docs。- 硬约束：MCP 安装路径必须纯 ASCII（中文路径经 Vivado Tcl GBK 解码会坏）；Vivado 会话与综合/实现/仿真全局串行。
Vivado 版本控制技能
此技能通过一个5步流水线（以及一个可选的交互式 Step 2.5 以保留现有生成输出）自动完成 Vivado 项目的版本控制设置。它适用于标准 RTL-only 项目、IPI 块设计（包括块设计容器）、DFX（部分重配置）以及 Versal 分段配置项目。
流水线检测项目类型、分析源文件位置、导出组件、捕获设置并生成构建脚本——最终产生一个自包含的目录，可以从头开始重建项目。
何时使用此技能
- 为任何 Vivado 项目设置版本控制
- 使项目可移植以方便团队成员或 CI/CD 使用
- 导出并组织所有项目源文件
- 创建用于可重现构建的自动化构建脚本
- 处理 DFX、BDC 或分段配置的版本控制
何时不使用此技能
- 项目尚未创建（不存在 .xpr 文件）
- 仅需修改现有的构建脚本（直接编辑它）
- 需要进行时序分析或设计调试（使用基线分析或其他技能）
前提条件
运行前，Vivado 项目必须已打开，并满足以下条件：
- 设置有效的 PART 属性
- 已将源文件添加到项目
- 已配置 TOP 模块
- 对于 DFX：已启用 PR_FLOW 属性
- 对于分段配置：已设置 SEGMENTED_CONFIGURATION 属性（或使用 Versal Gen2 器件）
5步流水线（+ 可选的 Step 2.5）
所有 Tcl 过程都位于 helper-procedures/helper_scripts.tcl 中。首先在 Vivado 中加载此文件，然后按顺序执行每个步骤。
source <skill-path>/helper-procedures/helper_scripts.tcl
步骤 1：检测项目流程
运行 detect_project_flow 以识别项目类型。这会返回一个 flow_info 字典，供步骤 3 使用。
set flow_info [detect_project_flow]
set flow_type [dict get $flow_info flow_type]
返回以下之一："Standard"、"DFX (Partial Reconfiguration)"、"Segmented Configuration"、"DFX + Segmented Configuration"——如果检测到块设计容器，则带有可选的 "+ IPI BDC" 后缀。
有关检测逻辑和边缘情况的详细信息，请阅读 detect-project-flow/REFERENCE.md。
步骤 2：分析源文件位置
运行 analyze_source_locations 将源文件分类为推按钮（全部本地）、远程（全部外部）或混合。
set scenario_info [analyze_source_locations]
set scenario [dict get $scenario_info scenario]
如果 scenario 为 "Remote"，则跳过步骤 3——源文件位于外部仓库中，不应重复。
有关详细信息，请阅读 analyze-source-locations/REFERENCE.md。
步骤 2.5：保留生成输出？（可选，交互式）
询问是否保留选定 IP/BD 的现有 .gen 输出，而不是在重建时让它们从 Tcl 完全重新生成。此步骤在此技能的旧版本中不存在，完全为可选加入。如何运行它取决于谁在驱动流水线：
直接在实时 Vivado 会话中键入的人类（GUI Tcl 控制台，或手动驱动的具有真实 tty 的批处理会话）——截至 2026-09-21，你无需执行任何特殊操作：如果你调用步骤 3（export_all_sources）而尚未自行回答此问题，它会检测 stdin 上的真实 tty，并且如果项目有任何符合条件的项，它会在继续之前自动提示你。如果你希望精确控制提示发生的时间，仍然可以显式调用 prompt_preserve_outputs：
set preserve_selection [prompt_preserve_outputs]
- 回答 "n"（或仅按 Enter）返回
{enabled 0 ips {} bds {} cache_dir {}}——步骤 3 和 5 的行为与此功能存在前完全相同。 - 回答 "y" 会列出每个符合条件的独立 IP 和用户创建的 BD（通过
list_preservable_outputs）——包括位于任何块设计外部的 XCI——并让你选择要保留哪些（all或逗号列表）。此选择在不同的顶层项之间是混合/部分的（一些独立 IP/BD 被保留，其他不保留）——这是主要支持的用例。它不是在单个 BD 内部 的部分保留：一个 BD 作为一个整体单元被保留，你无法挑选其中哪些定制的 IP 被保留或重新生成（已确认为有意的作用域截断，不是错误——标记为可能的 Q4 增强）。 - 如果选定的项还没有
.gen输出（从未生成/综合），export_all_sources会发出警告并正常导出它，而不是保留它——尚无东西可保留不是硬故障，但也不会静默地创建不完整的缓存条目。 - 保留仅支持远程缓存：此项目外部的一个目录。选择 IP/BD 后，系统会提示你输入该缓存目录的绝对路径。无效路径（相对路径、空路径或嵌套在项目内部）会为此导出禁用保留。
此过程阻塞于 gets stdin，因此仅在连接了真实 tty 时有效——这正是 export_all_sources 现在在自动调用它之前检查的条件（_rc_stdin_is_tty）。
自动化 CI / 回归流水线（run_pipeline.tcl 风格的框架）——完全跳过此步骤，并将 {}（默认值）传递给步骤 3 和 5。这保持了旧的完全自动化 5 步行为不变。
智能体（AI 代理通过 Bash/批处理模式 Tcl 调用驱动 Vivado，与人类聊天）——不要调用 prompt_preserve_outputs：它的 gets stdin 没有真实的 tty 可以阻塞，只会读取 EOF，静默地禁用保留且没有任何可见提示。相反：
- 调用
list_preservable_outputs（纯查询，无 stdin）查看哪些项符合条件。 - 如果它返回任何 IP 或 BD，直接在对话中询问人类他们想要保留哪些（如果有）以及用于存储保留输出的项目外部缓存目录的绝对路径。
- 使用人类的回答调用
build_preserve_selection $chosen_ips $chosen_bds $cache_dir以获取preserve_selection字典。 - 如果
list_preservable_outputs没有返回任何内容，则跳过询问——无需保留任何内容。
set items [list_preservable_outputs]
# ... 在对话中询问人类，然后：
set preserve_selection [build_preserve_selection $chosen_ips $chosen_bds $cache_dir]
将返回的 preserve_selection 传递给步骤 3（export_all_sources）。有关详细信息，请阅读 helper-procedures/REFERENCE.md。
步骤 3：导出所有源文件（条件性）
如果步骤 2 返回 "Remote"，则跳过此步骤。否则，将 RTL、约束、IP（通过 write_ip_tcl 作为 Tcl）、块设计（通过 write_bd_tcl 作为 Tcl）、仿真文件和数据文件导出到有组织的目录。
传递来自步骤 1 的 flow_info 以启用 DFX/分段配置特定的导出（pblock、DCP、NoC 解决方案）。传递来自步骤 2.5 的 preserve_selection（或省略它）以控制每个 IP/BD 的输出保留。如果你省略它并且 stdin 是真实 tty，export_all_sources 会自行提示（参见上面的步骤 2.5），而不是静默地跳过保留。对于 preserve_selection 中指定的任何 IP/BD，其自身的 .srcs/.gen 子树（仅此而已）会被复制到该选择指定的外部 cache_dir——绝不复制到 export_dir/RevisionControl/ 内部。
if {$scenario ne "Remote"} {
export_all_sources "RevisionControl" $flow_info $preserve_selection
}
有关过滤规则、BD-IP 处理以及 DFX 导出的详细信息，请阅读 export-all-sources/REFERENCE.md。
步骤 4：捕获项目设置
将所有非默认项目属性保存到 Tcl 脚本，该脚本可以在重建期间恢复它们。
file mkdir RevisionControl/Scripts
capture_project_settings "RevisionControl/Scripts/project_settings.tcl"
捕获内容包括：PART、BOARD_PART、TARGET_LANGUAGE、PR_FLOW、SEGMENTED_CONFIGURATION、TOP、VERILOG_DEFINE、综合/实现指令以及文件特定属性（VHDL LIBRARY、IS_GLOBAL_INCLUDE）。
有关详细信息，请阅读 capture-project-settings/REFERENCE.md。
步骤 5：生成构建脚本
创建用于一键重建项目的 build.tcl。
generate_build_script "RevisionControl/Scripts/build.tcl" "RevisionControl" $scenario_info
生成的脚本使用相对路径，导入本地源文件（import_files），原地引用远程源文件（add_files），从 Tcl 脚本重新创建 IP 和 BD，创建 OOC IP 运行，生成 BD 目标，加载 project_settings.tcl，并最终确定编译顺序。对于在步骤 2.5 中保留的任何 IP/BD，它改为从外部缓存目录恢复该项的 .srcs/.gen 并直接 add_files/read_ip/read_bd——不进行 write_ip_tcl/write_bd_tcl 重播，不重新综合——而每个未保留的 IP/BD 仍然经过标准的 Tcl 重新生成路径。此分支是每个 IP/BD 级别的，绝不是在项目全局范围内进行。如果在重建时缓存目录（或其中特定保留项的数据）丢失，生成的脚本会硬错误退出，而不是静默地回退到重新生成。
有关 DFX RM 排序和 .gen 缺失处理的详细信息，请阅读 generate-build-script/REFERENCE.md。
流水线数据流
步骤 1：detect_project_flow
→ flow_info 字典（传递给步骤 3）
步骤 2：analyze_source_locations
→ scenario（"Push Button" / "Remote" / "Mixed"）
→ 如果是 Remote：跳过步骤 3
步骤 2.5：prompt_preserve_outputs（可选，仅交互式）
→ preserve_selection 字典 {enabled, ips, bds, cache_dir}（传递给步骤 3）
→ 省略/拒绝 ⇒ {} ⇒ 步骤 3 和 5 的行为与此功能存在前完全相同
→ 如果省略且 stdin 是真实 tty 并且有符合条件的项，步骤 3
会自动代你调用此函数（2026-09-21 添加）而不是静默地默认不保留 — 无 tty（CI/智能体）⇒ 不变
→ cache_dir 必须是项目外部的绝对路径（仅远程缓存）— 无效/缺失路径会为此导出禁用保留
步骤 3：export_all_sources(dir, flow_info, preserve_selection)
→ Sources/ 目录，包含 RTL、IP、BD、约束（dir 本身绝不因 preserve_selection 而改变形状）
→ （仅当 preserve_selection 选择了某些内容时）每个保留项的自身 .srcs/.gen 子树被复制到 cache_dir — 绝不复制到 dir 本身
步骤 4：capture_project_settings(file)
→ project_settings.tcl
步骤 5：generate_build_script(file, dir, scenario_info)
→ build.tcl（自动重建；在重建时从 cache_dir 恢复任何保留项的 .srcs/.gen — 如果 cache_dir 或其中保留项的数据丢失，则硬错误退出）
输出结构
RevisionControl/ 导出到实时 Vivado 项目旁边，其自身形状绝不因是否使用了步骤 2.5 保留而改变——它绝不包含来自原始项目的 <proj>.gen/、<proj>.srcs/ 或 <proj>.xpr（它们原地不动，保持原样），并且 XPR 在任何流程中都不受版本控制。
project_1.gen/ # 实时原始 Vivado 项目 — 同级，保持不变
project_1.srcs/
project_1.xpr
RevisionControl/
├── Sources/
│ ├── RTL/ # Verilog/SV/VHDL 源文件
│ ├── Constraints/ # XDC 文件（对于 DFX 还包括 pblocks.xdc）
│ ├── IP/ # write_ip_tcl 脚本 — 仅限未保留的独立
│ │ # IP（不复制 .xci）；保留的 IP 完全在此处跳过
│ │ # （见下文）
│ ├── BD/ # write_bd_tcl 脚本 — 仅限未保留的 BD
│ │ # （不复制 .bd）；保留的 BD 完全在此处跳过，
│ │ # 无 Tcl 回退（见下文）
│ ├── Simulation/ # 测试平台
│ ├── Data/ # .mem, .coe, .mif, .hex, .elf, .csv 文件
│ ├── Scripts/ # Tcl 前/后处理钩子脚本
│ ├── Checkpoints/ # （仅 DFX）锁定的静态 DCP
│ └── NoC/ # （仅分段配置）.ncr 文件
└── Scripts/
├── project_settings.tcl
└── build.tcl
保留的输出（步骤 2.5 回答“是”，选择了 ≥1 个 IP/BD）
如果步骤 2.5 保留了任何内容，唯一的工件是外部远程缓存目录——用户提供的项目外部路径（preserve_selection 中的 cache_dir），绝不复制到 RevisionControl/ 中且绝不纳入 git 跟踪：
<cache_dir>/
└── project_1/
├── ip/
│ └── <ip_name>/
│ ├── srcs/ # 该 IP 自身 .srcs 目录的副本（.xci
│ …