疑難排解¶

本頁提供 Agent HQ 示範中各類問題、原因與解決方法的實用參考，重點放在儲存庫檔案所呈現的問題，而非一般性的 .NET 或 GitHub Actions 行為。

`MSB3923: failed to download Copilot CLI`¶

原因：GitHub.Copilot.SDK 會在建置時從 registry.npmjs.org 下載相符的 Copilot CLI 二進位檔。企業 Proxy 或離線開發電腦可能會阻擋此下載。

解決方法：在全域安裝 CLI，並讓 Directory.Build.props 自動偵測：

npm install -g @github/copilot
dotnet build src/AgentOrchestrator/AgentHQDemo.slnx

如有需要，可明確覆寫設定：

dotnet build src/AgentOrchestrator/AgentHQDemo.slnx \
  -p:CopilotCliBinaryPath=/path/to/copilot

若要停用本機偵測並恢復 SDK 的一般下載行為：

dotnet build src/AgentOrchestrator/AgentHQDemo.slnx \
  -p:CopilotUseLocalCli=false

CodeQL Analysis 顯示 `skipped`¶

原因：這是私人儲存庫中的預期情況。除非儲存庫為公開狀態，否則上傳程式碼掃描結果需要 GitHub Advanced Security。

解決方法：請將跳過的作業視為刻意的設計，而非儲存庫失敗。此工作流程受下列條件保護：

if: github.event.repository.visibility == 'public' || vars.ENABLE_CODEQL == 'true'

僅當目標組織具備所需的程式碼掃描權益時，才設定儲存庫變數 ENABLE_CODEQL=true。

`Model ... is not available`¶

原因：目前登入的 Copilot 帳戶無法使用該模型 ID，或該 ID 已過時。

解決方法：請勿在新程式碼中硬式編碼模型 ID。應用程式會從 /api/chat/models 取得即時清單；該端點會呼叫 CopilotChatService.ListModelsAsync，且僅在無法連線至 CLI 時，才改用小型靜態目錄。

JSON-RPC 或 `PingResponse` 還原序列化錯誤¶

原因：Copilot SDK 與 Copilot CLI 版本不相符，可能導致 JSON-RPC 還原序列化失敗。

解決方法：請同時升級 GitHub.Copilot.SDK 與 Copilot CLI。此儲存庫使用 SDK v1.0.9；另請檢查 v1.0.0 的 API 變更：

命名空間已從 GitHub.Copilot.SDK 移至 GitHub.Copilot
session.On<T>(...) 現在需要明確指定型別引數

連接埠已在使用中：5050 或 5051¶

原因：另一個處理程序已繫結 API 連接埠 5050 或 Blazor 連接埠 5051。先前執行所留下的舊伺服器可能會在未提示的情況下提供舊版程式碼。

解決方法：找出並停止該處理程序：

lsof -ti:5050
lsof -ti:5051

接著停止傳回的處理程序 ID，並重新啟動相關應用程式：

kill 12345  # replace 12345 with the process id returned by lsof
dotnet run --project src/AgentOrchestrator/AgentHQDemo.Api --urls "http://localhost:5050"
dotnet run --project src/AgentOrchestrator/AgentHQDemo.Web --urls "http://localhost:5051"

Blazor 使用者介面顯示舊模型或無效模型¶

原因：選取的模型儲存在 Web 應用程式的瀏覽器 localStorage 中，而該值可能比可用模型清單保留得更久。

解決方法：當選取的模型不再出現在執行階段模型清單中時，應用程式會在 Home.razor 重設儲存值。若使用者介面仍顯示舊內容，請清除 localhost:5051 的網站資料。

`GitHub Actions hosted runners are disabled`¶

原因：組織或企業原則已停用託管執行器。這不是儲存庫建置或工作流程語法問題。

解決方法：請要求組織或企業系統管理員啟用託管執行器，或為此儲存庫提供已核准的執行器選項。

建置成功，但測試找不到解決方案¶

原因：解決方案不在儲存庫根目錄，而是位於 src/AgentOrchestrator/AgentHQDemo.slnx。

解決方法：請明確傳入解決方案路徑：

dotnet restore src/AgentOrchestrator/AgentHQDemo.slnx
dotnet build src/AgentOrchestrator/AgentHQDemo.slnx
dotnet test src/AgentOrchestrator/AgentHQDemo.slnx

這也是 .github/workflows/ci.yml 進行還原、建置與測試時所使用的路徑。

疑難排解¶

MSB3923: failed to download Copilot CLI¶

CodeQL Analysis 顯示 skipped¶

Model ... is not available¶

JSON-RPC 或 PingResponse 還原序列化錯誤¶