Azure Web PubSub 实时通信技能
为 TypeScript 应用构建 WebSocket 实时消息、群组通信和通知功能。
示例展示了 Microsoft Entra、托管身份和连接字符串等认证方式，并包含权限配置与连接管理；但未明确最小权限、敏感数据保护或用户确认要求，且将包含 access_token 的 token.url 直接 console.log，可能造成凭据泄露风险，因此扣分。
安装、服务端、客户端和 Express 路径结构清晰，异常与重连仅有简短提示；但 Express 示例引用未定义的 serviceClient 和 req.user，缺少输入校验、失败处理、版本兼容说明及可复现测试，静态证据不足，按上限保守评分。
名称、描述和触发场景明确，覆盖 WebSocket、发布订阅、群聊和实时通知；但未声明非适用范围、具体输入输出边界、浏览器与 Node.js 限制，也没有中文使用或中国大陆网络可达性说明，因此扣分。
文档按安装、认证、服务端、客户端、事件处理、类型和最佳实践分层，含 MIT、作者和版本元数据；但缺少变更记录、维护责任与更新路径、故障排查、已知限制和完整端到端示例，因此未满分。
示例覆盖令牌、广播、用户和连接发送、群组、连接管理、客户端事件与 Express 处理器，能够支持核心编码任务；但关键示例不完整且存在未定义变量，输出仍需较多人工核验和整合，静态评估不能证明可直接运行，因此扣分。
源文件提供固定修订上下文，仓库存在通用 CI、Vally 工作流和测试代码；但所给材料没有该技能专属 acceptance criteria、专属测试结果或第三方执行证据，无法独立复现关键路径，故仅给有限分数。
- 不要在日志中输出 token.url 或任何包含 access_token 的完整 URL；应避免记录令牌并采用安全的密钥管理。
- Express 协商示例中的 serviceClient 和 req.user 未定义，部署前必须补充认证中间件、服务客户端初始化、输入校验和错误响应。
- 群组关闭、踢出连接和权限变更会产生外部影响；生产使用前应明确授权边界、审计和恢复策略。
- 应根据实际 SDK 版本核对 API 签名、事件类型和包兼容性，并补充可运行测试。
它能做什么 & 适用场景
该技能面向使用 Azure Web PubSub TypeScript SDK 的开发者，涵盖服务端管理、客户端连接和 Express 事件处理。它提供身份验证、客户端访问令牌、广播、用户与连接定向消息、群组管理以及连接生命周期处理示例。内容也说明了 Microsoft Entra 凭据、自动重连、事件处理器注册和连接校验等实践。适合需要在 JavaScript 或 TypeScript 应用中加入聊天、频道通信或实时通知的团队。
指导开发者安装 @azure/web-pubsub、@azure/web-pubsub-client、@azure/identity 和 @azure/web-pubsub-express；配置 Web PubSub 连接字符串、端点及凭据环境变量；创建 WebPubSubServiceClient 和 WebPubSubClient；生成客户端访问令牌；向全部连接、指定用户、指定连接或群组发送消息；管理群组、连接和权限；注册 connected、disconnected、group-message、server-message 等事件处理器；通过 Express 中间件处理连接、用户事件及协商端点。
- TypeScript 后端开发者需要为聊天应用生成 WebSocket 客户端访问令牌并向用户或群组发送消息。
- 前端开发者需要让浏览器客户端连接 Azure Web PubSub、加入群组并接收实时群组消息。
- 产品团队需要实现按频道组织的群聊、主题通信或实时协作功能。
- 应用开发者需要向在线客户端推送实时通知，并根据用户、连接或 OData 条件筛选接收者。
- Express 应用需要在连接建立和自定义用户事件发生时执行授权与业务处理。
优缺点一览
- 覆盖服务端、客户端和 Express 事件处理器三类常见集成面。
- 包含广播、用户消息、连接消息、群组、权限和连接关闭等具体 API 示例。
- 提供连接字符串、Microsoft Entra Token Credential 和 AzureKeyCredential 三种认证示例。
- 给出聊天、群组通信、实时通知和自定义事件处理的可复制 TypeScript 模式。
- 内容聚焦 SDK 集成，没有提供 Azure Web PubSub 资源创建或基础设施部署步骤。
- 源材料未提供该单个技能的测试覆盖结果、错误重试策略或性能基准。
- 未指定 SDK 或 Node.js 版本，采用前需要自行确认项目版本兼容性。
- 示例依赖有效的 Azure Web PubSub 资源、端点或连接字符串以及相应凭据。
如何安装
安装整个技能集合：运行 npx skills add microsoft/skills，在向导中选择 azure-web-pubsub-ts。技能会安装到所选 Agent 的目录，例如 GitHub Copilot 使用 .github/skills/。在项目中安装运行时包：npm install @azure/web-pubsub @azure/identity；客户端使用 npm install @azure/web-pubsub-client；Express 事件处理器使用 npm install @azure/web-pubsub-express。源材料未提供该单个技能的独立安装命令或包版本。
如何使用
将技能加载到支持 Agent Skills 的编码代理后，可用类似“为我的 TypeScript 应用实现 Azure Web PubSub 群聊，包括服务端令牌协商、客户端自动重连、群组消息和 Express 连接鉴权”的提示触发。随后按技能示例创建服务端与客户端 SDK、设置 WEBPUBSUB_CONNECTION_STRING 或 WEBPUBSUB_ENDPOINT，并在调用 start() 前注册客户端事件处理器。生产环境可使用 ManagedIdentityCredential 或其他指定凭据。