故障排除¶

本页是 Agent HQ 演示的实用问题、原因和修复参考，重点介绍仓库文件所反映的问题，而不是通用的 .NET 或 GitHub Actions 行为。

`MSB3923: failed to download Copilot CLI`¶

原因： GitHub.Copilot.SDK 会在构建时从 registry.npmjs.org 下载匹配的 Copilot CLI 二进制文件。企业代理或离线开发计算机可能会阻止该下载。

修复方法：全局安装 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 反序列化错误¶