用途：排查使用 Microsoft Agents SDK（@microsoft/agents-hosting 及相关包）构建的智能体故障，按顺序检查构建、启动、端口监听、配置、凭据与本地测试。
主要能力：提供分步清单——先确保代码构建成功（npm run build），再启动应用（DEBUG=agents:* npm start 或 DEBUG=agents:* node ./dist/index.js），确认端口监听（默认 3978），校验 .env 配置，向 Azure AD 验证机器人凭据，最后用 Agents Playground 做本地端到端测试。DEBUG 命名空间可按需缩小范围，如 agents:authorization:*、agents:msal、agents:cloud-adapter、agents:app、agents:state、agents:streamingResponse、agents:agent-client 等，分别输出授权连接、MSAL 取令牌、请求分发、路由生命周期、状态读写、流式响应与智能体间调用日志。
使用方式：用 curl 向 http://localhost:3978/api/messages 发 POST 判断可达性（401 表示运行且启用鉴权，200 表示匿名本地开发，000 或拒绝连接表示未运行或端口错误）。.env 需通过 node --env-file .env 加载；推荐现代 connections__ 双下划线格式，避免与旧扁平格式混用；多连接需配置 connectionsMap 并以 serviceUrl=* 兜底；使用用户登录时需设置 OAuth 连接名且处理器 ID 与代码一致。凭据可用 curl 请求 login.microsoftonline.com 的 token 端点验证，常见错误有 AADSTS700016、AADSTS7000215、AADSTS90002。Agents Playground 可安装 npm install -g agentsplayground，支持 -c msteams、webchat、directline、emulator、agents 等渠道。
适用场景与限制：适用于本地开发与联调阶段的智能体排障。OAuth 连接名只能通过 Azure 门户的 Test Connection 端到端验证；若问题未解决，可按模板整理信息到 microsoft/agents 仓库提交 issue。具体版本要求与更多细节以官方资料为准。