本機適応注記（非 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。1 回の呼び出しで 1 つの 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 / 公式ドキュメント）または当プロジェクト <project_root>\docs を使用してください。

ハード制約：MCP インストールパスは純粋な ASCII である必要があります（中華文字パスは Vivado Tcl GBK デコードで破損します）。Vivado セッションと合成/実装/シミュレーションはグローバルにシリアル化されます。

Vivado リビジョン管理スキルは何をしますか？

このスキルは、5 ステップのパイプラインと、オプションの対話型ステップ 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 を実行して、ソースを「プッシュボタン」（すべてローカル）、「リモート」（すべて外部）、または「混合」に分類します。

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 は 1 つのユニットとして保持され、内部でカスタマイズされた 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（Tcl として write_ip_tcl 経由）、ブロックデザイン（Tcl として write_bd_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 の場合、その 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：ビルドスクリプトの生成

1 コマンドでプロジェクトを再作成するための 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 をお読みください。

パイプラインデータフロー

Step 1: detect_project_flow
  → flow_info ディクショナリ（ステップ 3 に渡される）

Step 2: analyze_source_locations
  → scenario ("Push Button" / "Remote" / "Mixed")
  → Remote の場合：ステップ 3 をスキップ

Step 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 はプロジェクトの**外部**の絶対パスである必要がある（リモートキャッシュのみ）
    — 無効/存在しないパスは、このエクスポートでの保持を無効にする

Step 3: export_all_sources(dir, flow_info, preserve_selection)
  → Sources/ ディレクトリ（RTL、IP、BD、制約を含む）（ディレクトリ自体は
    preserve_selection に基づいて形状が変わることはない）
  → （preserve_selection が何かを選択した場合のみ）保持された各項目の
    自身の .srcs/.gen サブツリーが cache_dir にコピーされる。dir 自体にコピーされることは**ない**

Step 4: capture_project_settings(file)
  → project_settings.tcl

Step 5: generate_build_script(file, dir, scenario_info)
  → build.tcl（自動再構築；再構築時に保持された項目の .srcs/.gen を cache_dir から復元する
    — 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
    │

…

Vivado リビジョン管理スキル