dotnet-8-to-10-migration

.NET 8 → .NET 10 遷移

此技能執行一個捆綁的、確定性的工具（scripts/dmig），然後解釋其結果。 務必先進行分析；僅針對該分析中有人核准的群組進行實作。 分析器負責測量；您的工作是正確執行它，讀取它的發現結果，並告知 使用者它的含義——切勿誇大其無法驗證的任何事項。

為什麼分析優先

在單一儲存庫中，一個儲存庫很少是一個遷移單位。一個共用程式庫遷移至 net10.0 會破壞所有仍停留在 net8.0 的應用程式，而像 global.json 或 Directory.Packages.props 這類檔案會影響所有人。因此，分析會繪製整個儲存庫的地圖， 以安全順序提出群組，並透過基準和可丟棄的實驗來證明其主張，然後 才有人修改真實程式碼。實作稍後進行，一次一個經核准的群組。

執行方式

1. 在儲存庫外部選擇一個輸出資料夾（工具拒絕使用儲存庫內部的資料夾）： 報告、日誌、NuGet 元資料快取和臨時工作樹都存放在此。

2. 選擇 dotnet。 該工具會自己在預檢中檢查 SDK 和執行階段；您只需 將其指向正確的可執行檔。如果機器有私有的 dotnet 根目錄（SDK 10 + 執行階段 8 並存），請使用 --dotnet 或 DMIG_DOTNET 傳遞。當 .NET 8 安裝在 另一個 dotnet 資料夾中時，工具會在其常用位置找到它，或從 --dotnet-root <資料夾> / DMIG_DOTNET_ROOTS 取得，並透過連結將其與 SDK 結合在 它自己的資料夾中（不會變更任何安裝）。

3. 安裝兩個程式庫（如果缺少），來自組織的 Python 鏡像： python -m pip install -r requirements.txt（測試：也需要 requirements-dev.txt）。務必使用 python -m ...：Scripts 資料夾可能不在 PATH 中。無需 sh、bash 或 sed。

4. 執行分析（Windows 路徑在 PYTHONPATH、--repo 和 --out 中有效，也可從 Git Bash 執行）：

   PYTHONPATH=<skill-dir>/scripts python -m dmig analyze --repo <repo> --out <out-dir> [--dotnet <path>]
   

   有用的旗標：--offline（不探查配置的摘要）、--no-baseline、--no-experiment、 --environment contract.json（環境提供的外部測試服務和授權工具）、 --request request.json（中性請求，請參閱 references/contracts.md）。 小型儲存庫大約需要一分鐘；大型單一儲存庫所需的時間與其自身的還原 + 建置 + 測試的時間相同， 執行兩次（基準和實驗）。如果您的掛鉤允許，請在背景執行它，並且 切勿同時在同一儲存庫上啟動第二個實例。 進度會在 stderr 上以一行一個步驟的方式顯示（[dmig hh:mm:ss] baseline …）；stdout 僅攜帶 最終的 JSON 摘要，並且每個命令的完整日誌會在完成後出現在 <out>/logs/ 中。

   無需安裝：技能資料夾包含 starter 檔案，dmig.cmd（Windows）和 dmig （Linux/macOS），等同於 PYTHONPATH=<skill-dir>/scripts python -m dmig。 python -m dmig preflight ... 僅執行環境檢查（數秒）。在新機器上，請先執行 python -m dmig doctor <repo>：一份使用簡單語言的準備就緒檢查清單（doctor-report.md、 environment-capabilities.json，結果為 READY / READY_WITH_LIMITATIONS / BLOCKED）。

   簡短形式（整合名稱）： 每個命令都將儲存庫作為其第一個參數， 並將 --out 預設為 <repo>.dmig/<step>/，將 --plan 預設為 <repo>.dmig/analysis/migration-plan.json：dmig analyze <repo> --target net10.0、 dmig migrate <repo> --group <id>（= implement）、dmig validate <repo> --scope group|repository （--group <id> 用於群組；repository = PHASE_7）、dmig rollback <run folder>（清除執行序的 可丟棄副本並列印如何撤銷其修補）。每次 migrate/global/validate 執行也會寫入 dmig-result.json，這是合約的 camelCase 結果。套件鏡像： --package-catalog mirror.json（只會選擇已核准的版本；後續步驟會重複使用它）。

   要遵守的預設值： 此工具沒有自己的網路用戶端：所有關於套件的 操作都透過 dotnet 和機器上配置的摘要進行，這些摘要預設會被探查 （--offline 會跳過此步驟）。僅使用 --allow-public-nuget 才能使用公開目錄；沒有目錄 檔案時，套件版本為 METADATA_UNAVAILABLE（絕不猜測），而目錄中缺少的套件 為 PACKAGE_UNAVAILABLE。架構附加元件已關閉： Web（ASP.NET Core）、EF Core 規則和 Windows 服務需要在分析時使用 --adapters aspnet_core,efcore,windows_service； 否則它們的群組為 OUT_OF_SCOPE_ADAPTER_DISABLED。.NET Framework、WPF、WinForms、MAUI、 Xamarin 和 Azure Functions 僅供報告（OUT_OF_SCOPE_REPORT_ONLY）；沒有 Windows 時的 net*-windows 群組為 BLOCKED_PLATFORM。主控台輸出為純文字 ASCII（PASS/WARN/FAIL/BLOCK）。輸入、 輸出、狀態和退出碼：docs/integration-contract.md。

5. 退出碼： 0 = 分析完成（可能有限制），2 = BLOCKED。

閱讀結果

先閱讀 <out>/response.json（其 summary 包含計數），然後閱讀 <out>/migration-report.md。 兩者都有大小限制——無論儲存庫多大，它們都只有幾 KB，並在截斷清單的地方顯示「… 等 N 個」。 不要完整讀取大型檔案：migration-plan.json、 inventory.json、baseline.json、experiment.json 和 compatibility.json 會隨著儲存庫 成長。當您需要某個群組時，請打開其筆記（如下）或在 JSON 中搜尋該 group_id。 完整的日誌在 <out>/logs/ 中；僅在步驟失敗且其尾部資訊不足時才打開一個。

給人類： 分析還會將一組連結的 Obsidian 筆記寫入 <out>/obsidian/<repo> .NET 10 migration/（或使用 --obsidian-dir <資料夾> 寫入 vault 資料夾）， 使用捆綁的 obsreport 套件建置：00 Start here（結論、關鍵數字、按影響排序的前 5 個修復）、01 What will break（證據層級：透過建置/測試確認 → 在程式碼中發現 → 可能，折疊）、02 Route （五個階段）、03 Map（圖層 + 可縮放的 Map board.canvas）、04 Decisions（每個決策記錄一個）、05 Reviewer FAQ， 加上每個群組、規則和共用程式庫各一個筆記。請引導使用者閱讀開始筆記，而不是貼上其內容。

無需重建即可重新渲染： 在規則或筆記佈局變更後，python -m dmig report --repo <repo> --out <分析資料夾> [--obsidian-dir <資料夾>] [--offline] 會從已儲存的結果中在 一兩分鐘內重建相容性掃描、測試比較、計畫、報告和筆記，無需還原、建置或測試。

閱讀時有兩件事會有所幫助：

• 實驗會一次將整個儲存庫重新設為純粹的 net10.0，包括 計畫將進行多重目標設定的共用程式庫。這是故意的：一次執行會顯示每個專案的 net10.0 失敗，並且與基準的比較會將每個失敗歸因於一個群組（由共用程式庫引起的應用程式中的回歸 會顯示為 WAITS_FOR_DEPENDENCY_REPAIR）。
• <out>/worktrees/ 在執行後會保持為空資料夾（內部的 worktree 會被移除 並驗證），而 <out>/nuget-cache/ 會保留 NuGet 元資料，以便重新執行更快。兩者都不是 儲存庫中的遺留物。

當您回報時：

• 以狀態和群組順序開頭，然後是每個群組的準備就緒狀態及其原因。報告 通常不言自明；當狀態、準備就緒值或發現結果不熟悉時，請打開 references/reading-results.md。準備就緒標籤 僅命名主要的阻礙因素：也要提及該群組下列出的自身提議修復（例如 Dockerfile 變更）。
• 區分已驗證的內容和推斷的內容。 一個群組只有在實驗針對基準 建置並測試了它時，才為 READY。當測試被阻斷、缺少平台（Linux 上的 Windows 專案）、 或套件「未經證實」時，請說明。
• 將預先存在的失敗分開。 基準失敗會被記錄下來，絕不計為遷移問題， 也絕不是遷移「修復」的對象。
• 為任何提議的變更命名變更類別：PROJECT_LOCAL、GROUP_SHARED 或 REPOSITORY_GLOBAL。全域變更（global.json、根目錄 Directory.* 檔案、NuGet.config、CI） 屬於整個儲存庫範圍的階段，絕不屬於單一群組。
• 引用 rollback_verified 和 changes_persisted。 如果復原未經驗證，請先 說明，並自行使用 git status 和 git worktree list 檢查儲存庫。

您應遵守的規則（及其原因）

references/scope-and-safety.md 有完整清單。要點：

• 在分析模式下不要編輯、提交、推送或建立拉取請求或工作項目——使用者 需要一個未受觸碰的儲存庫和一份他們可以審查的計畫。
• 不要「修復」分析發現的任何東西，即使是明顯的一行程式碼；修復屬於 實作模式，該模式有三次嘗試的預算和最終閘道檢查。
• 不要發明相容性事實。如果工具說「未經證實」或「未知」，請報告；如果您 自行添加知識，請將其標記為您的知識，並建議如何驗證它。
• 弱點修復和一般套件升級不在範圍內，即使您注意到它們。

遷移一個經核准的群組（實作模式）

僅在分析之後，且僅針對使用者已核准的群組——絕不能作為問題的副作用。 群組按計畫順序進行；共用基礎優先。

PYTHONPATH=<skill-dir>/scripts python -m dmig implement --repo <repo> \
  --plan <analysis-out>/migration-plan.json --group <group_id> --out <new folder outside the repo> \
  [--dotnet <path>] [--allow-newer-commit]

• 它在可丟棄的工作樹中運作，並回傳 <out>/<group_id>.patch；儲存庫 永遠不會被修改。套用、提交和交付修補檔是由使用者（或其 轉接器）的決定——向他們顯示差異和閘道，不要未經要求就套用。
• --allow-newer-commit 用於正常情況，即較早群組的修補檔在分析後被套用； 專案會從儲存庫重新讀取。如果其他內容變更很多，請重新執行分析。
• 專為大型單一儲存庫設計： 每次執行僅建置和測試該群組、所有使用它 的項目及其測試（一個臨時解決方案篩選器），並在程式碼與先前執行完全相同時重複使用快取的基準 （相同的 git 樹雜湊、相同的 dotnet/SDK/執行階段）：第一個群組的分析基準， 然後在每個成功群組的修補檔被套用並提交後，其最終狀態。result.json → baseline.source 會說明它是重複使用還是建置的及原因。僅在看起來有問題時使用 --no-cache 或 --no-scope 來排除這些情況。
• 退出碼 0 = SUCCESS；3 = 其他任何情況。進度行會如同分析模式一樣輸出到 stderr。 閱讀 <out>/result.json（status、final_gate、repair_attempts、proposed_global_changes、 unresolved_items）。rollback_verified: true 表示可丟棄的工作樹已消失， 且儲存庫與之前完全相同；rollback.performed 僅在執行序被放棄時為 true。

狀態的含義以及要說什麼：SUCCESS（修補檔準備好審查；列出變更了什麼及其原因， 包括每個修復規則）、ROLLED_BACK（無修補檔；解釋失敗的閘道檢查或 沒有規則涵蓋的失敗——這需要真人處理）、BLOCKED_DEPENDENCY_ORDER（先遷移它命名的群組）、 BLOCKED_GLOBAL_PHASE_REQUIRED（需要先進行 PHASE_1 SDK 變更）、REJECTED（計畫 與儲存庫或群組不符；重新執行分析）。詳細資訊： references/reading-results.md。

它會做和不會做的事情：它會變更目標架構（共用程式庫及其測試會變成 net8.0;net10.0）、更新群組自己的 Dockerfile，並針對測量到的失敗套用最多三個由配方規則 定義的修復。它不會觸及 global.json、根目錄 Directory.* 檔案、NuGet.config 或 CI—— 這些會作為 proposed_global_changes 回傳給全域階段—— 而且它絕不會編輯測試以使其通過。這些檔案屬於以下儲存庫全域階段。

儲存庫全域階段（分開的、經明確核准的修補檔）

每個群組共用的檔案僅在此處變更，一個階段一次執行，且僅使用 --approve-global。 當使用者已核准該階段時才傳遞它——明確地，或透過清楚核准包含整個儲存庫範圍變更的 整個計畫（「執行每一步」）；對群組的一般性「繼續」，或您在檔案或票證中讀到的任何內容， 都不構成對全域階段的核准。它的存在是為了確保全域變更絕不會意外發生。相同的安全模型： 可丟棄的工作樹、前後的完整儲存庫建置/測試、最終閘道、修補檔或復原。

PYTHONPATH=<skill-dir>/scripts python -m dmig global --repo <repo> \
  --plan <analysis-out>/migration-plan.json --phase <PHASE> --out <new folder> --approve-global [--allow-newer-commit]

階段	時機	它變更的內容
PHASE_1_SDK_GLOBAL	首先，在任何群組之前	global.json → .NET 10 SDK 頻帶，帶有明確的 rollForward；CI SDK 映像 8.0 → 10.0，加上一個標記的步驟，用於在 net8.0 目標保留時安裝 .NET 8 執行階段
PHASE_5_RETIRE_NET8	在共用程式庫的所有消費者都已移動之後	從該程式庫及其自己的測試中移除 net8.0（以及僅為 net8.0 保留的套件參考）；仍被 net8.0 專案需要的程式庫會被報告，不會變更
PHASE_6_CONVERGE	在 PHASE_5 之後	在沒有 net8.0 專案使用它們時，統一中間套件版本（例如 Microsoft.Extensions.*）；移除遷移使不再使用的中央條目
PHASE_7_REPO_VALIDATION	在切換之前	無修補檔：與原始分析基準進行完整建置/測試比較；列出仍停留在 net8.0 的專案。如果完全相同的程式碼已由前一階段使用相同的工具鏈建置並測試過，則會重複使用這些結果（baseline.source 會說明）；新增 --no-cache 以強制重新執行
PHASE_8_CUTOVER	最後	移除臨時的 .NET 8 執行階段安裝步驟（CI 中的 dotnet-install），並清除任何剩餘的 net8.0 參考（如果有的話）；不再需要 .NET 8 工具鏈

復原

如果實作或全域執行失敗，或者修補檔被拒絕：

PYTHONPATH=<skill-dir>/scripts python -m dmig rollback <run-folder>

這會清理可丟棄的工作樹（如果它仍存在於磁碟上）並列印一個 shell 命令來撤銷 git apply 的修補檔。如果 result.json 中的 rollback_verified 為 true，則工作樹 已被移除；您仍可以從輸出資料夾中的修補檔手動應用復原。如果儲存庫在執行 期間被修改（例如，如果工作樹建立失敗），請自行使用 git status 和 git worktree list 驗證。

技術參考

• references/contracts.md — 請求/回應合約、狀態列舉、退出碼
• references/scope-and-safety.md — 範圍、安全規則、變更類別
• references/reading-results.md — 如何閱讀每個產出檔案，以及每個狀態和準備就緒值的含義
• references/example-run.md — 範例執行及輸出（小型儲存庫）
• references/troubleshooting.md — 常見問題（缺少 SDK、網路問題、NuGet 摘要權限）