Srvquery Vibe 项目

Srvquery 是一款完全类型化的 TypeScript 游戏服务器查询工具包，提供从底层二进制数据传输原语到高级协议客户端的完整技术栈。开发者可以用它查询游戏服务器的运行状态、玩家列表和规则配置，也可以基于现有传输层自行实现新的游戏协议。项目采用 monorepo 结构，核心包 @srvquery/core 负责 UDP/HTTP 传输和二进制解析，上层协议包则负责请求包的构造、响应的解码与验证，各层均可独立使用。

核心架构

Srvquery 的技术栈分为三个层次：最底层的 @srvquery/core 包处理所有与协议无关的通用逻辑，包括连接的建立与关闭、请求与响应的匹配、失败重试机制以及 Buffer 级别的二进制读写操作；中间层是各协议实现包，每个协议包都基于 core 提供的基础功能构建请求包、使用 core 的原语对响应进行重组和解码；最上层是应用程序，协议包会先对响应数据进行 Zod 模式验证再返回结构化对象，保证数据可靠性。架构清晰的三层设计使开发者可以在任意层级进行深度定制。

支持的游戏协议

目前 Srvquery 已支持的协议覆盖了市面上绝大多数主流游戏：Valve 协议包（@srvquery/protocol-valve）支持 Counter-Strike 2、Counter-Strike: Source、Team Fortress 2、Garry's Mod、Left 4 Dead 1/2、Half-Life 2: Deathmatch、Day of Defeat: Source、DayZ、Arma 2/3、Rust、ARK: Survival Evolved、ARK: Survival Ascended、7 Days to Die、Conan Exiles、Squad 等二十余款游戏；SA-MP/open.mp 协议包支持圣安地列斯多人版和 open.mp 服务器；FiveM/RedM 协议包支持 GTA V 的著名私服框架 FiveM 及 RedM；Minecraft Java 版和 Bedrock 版也有专门的协议包。这种广泛的协议覆盖使 Srvquery 能满足几乎所有主流多人游戏的服务器查询需求。

可靠的重试机制

协议客户端默认对每个 UDP 请求进行最多三次尝试，相邻两次尝试之间使用指数退避策略，初始间隔为 100 毫秒。开发者可以通过参数自定义重试次数、间隔策略和终止条件。例如将重试次数设为 1 即可完全禁用重试；可以提供自己的间隔策略函数实现线性退避、抖动退避或固定间隔；fatal 回调函数可在遇到无法通过重试解决的错误时（如目标不可达）立即停止重试流程。这种灵活的设计使开发者可以根据具体网络环境和应用场景进行精细调优。

完整的类型安全

作为 TypeScript 原生项目，Srvquery 在整个技术栈上实现了完整的类型安全。所有查询操作的返回值类型都通过 TypeScript 泛型自动推断，开发者无需手动声明类型即可获得完整的 IDE 类型提示和类型检查支持。Zod 模式验证在运行时确保数据结构符合预期，如果服务器返回格式错误或意外的数据负载，query 方法会抛出 ZodError 而不是向应用程序交付损坏的数据。这一设计从根本上消除了隐式数据错误导致应用程序异常的风险。

适用人群

Srvquery 主要服务于以下开发者群体：游戏服务器管理工具和面板的开发者在构建服务器状态监控和玩家管理功能时可直接使用现成的协议客户端；游戏社区网站和服务器排行榜的运营者可以用它快速获取各服务器的实时数据；游戏发行商的运维团队可以用它构建分布式的服务器监控系统；此外任何需要在应用中集成游戏服务器信息查询功能的开发者都可以利用该工具包的模块化设计快速实现需求。