本機適配註記（非 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 版本控制技能
此技能透過一個五步驟管道（加上一個可選的互動式步驟 2.5，用於保留現有已產生的輸出）自動化處理 Vivado 專案的版本控制設定。它適用於標準純 RTL 專案、IPI 區塊設計（包括區塊設計容器）、DFX（部分重構）以及 Versal 分段組態專案。
該管道會偵測專案類型、分析原始碼位置、匯出元件、擷取設定並產生建置腳本——產生一個可以從頭開始重建專案的、自成一體的目錄。
何時使用此技能
- 為任何 Vivado 專案設定版本控制
- 使專案可移植，以便團隊成員或 CI/CD 使用
- 匯出並整理所有專案原始碼
- 為可重複的建置建立自動化建置腳本
- 處理 DFX、BDC 或分段組態的版本控制
何時不應使用此技能
- 專案尚未建立（尚無 .xpr 檔案）
- 僅需修改現有的建置腳本（直接編輯它）
- 需要時序分析或設計除錯（請使用基線或其他技能）
先決條件
執行前，Vivado 專案必須已開啟，並符合以下條件：
- 設定了有效的 PART 屬性
- 已將原始碼檔案加入專案
- 已配置 TOP 模組
- 對於 DFX：啟用了 PR_FLOW 屬性
- 對於分段組態：設定了 SEGMENTED_CONFIGURATION 屬性（或使用 Versal Gen2 裝置）
5 步驟管道（+ 可選步驟 2.5）
所有 Tcl 程序都位於 helper-procedures/helper_scripts.tcl 中。在 Vivado 中先載入此檔案，然後依序執行每個步驟。
source <skill-path>/helper-procedures/helper_scripts.tcl
步驟 1：偵測專案流程
執行 detect_project_flow 以識別專案類型。這會回傳步驟 3 所需的 flow_info 字典。
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 將原始碼分類為 Push Button（全部在本機）、Remote（全部在外部）或 Mixed。
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/分段組態特定的匯出（pblobks、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
│ │ # 包含在內）
│ └── gen/ # 該 IP 自身 .gen 輸出目錄的副本
│ # （未壓縮）
└── bd/
└── <bd_name>/
├── srcs/ # 該 BD 自身 .srcs 目錄的副本
└── gen/ # 該 BD 自身 .gen 輸出目錄的副本
無保留（步驟 2.5 跳過、拒絕或無符合條件的項目）
則不建立任何快取目錄。RevisionControl/ 的結構與上文完全相同。步驟 5 產生的 build.tcl 將所有 IP 和 BD 視為應從頭重新產生的項目。