性能采样
「脉动之间，洞察性能」
/pulsegrasp 命令用于对服务器线程进行采样分析，生成性能热点报告，帮助定位卡顿根源。
基本用法:
/pulsegrasp start
权限:
youer.command.pulsegrasp
语言限制:
PulseGrasp 仅面向中文用户提供，判定依据是服务器语言配置 youer.lang：
zh/zh_CN/zh_TW/zh_HK等中文变体 → 正常可用。- 其他语言（
en_US、de_DE、ru_RU、fr_FR…）→ 命令被拒绝，并提示自行安装 spark。
控制台与所有玩家统一按此配置判定，一处开关控制全服。修改 youer.lang 后需重启生效。
-> start
/pulsegrasp start
开始一次把脉采样，不接受任何参数。
运行方式
一次采样固定持续 30 秒，到点后自动结束并生成报告，没有手动停止命令。这样设计是为了让每次采样时长一致，报告之间可直接横向对比；也避免忘记停止导致长时间采样带来的额外开销。
- 重复执行
start不会重新计时，而是提示「正在运行中」。 - 采样期间由玩家发起时，该玩家的动作栏（物品栏上方的状态条）会实时显示进度：一条进度条、剩余秒数与已采集的 tick 数，每秒刷新一次。
- 后台 / 控制台发起（或非玩家来源）不显示任何进度——动作栏只服务于主动执行命令的那个人，不会打扰其他在线玩家。
报告输出
30 秒结束后会在服务端工作目录生成一个报告文件 pulse_grasp_<时间戳>.json —— 原始结构化数据，供上传、二次分析或自定义工具消费。
报告生成完成后，PulseGrasp 会自动把这个 JSON 上传到在线报告服务，并在控制台与发起者处输出可分享的链接（形如 https://<域名>/tools/pulse-grasp/<10位ID>）。聊天栏里的链接是可点击的（带下划线，鼠标悬停会提示「点击打开在线报告」），点一下即用客户端浏览器打开，无需手动复制。打开链接即可查看完整图表，无需在服务端本地打开任何文件。
上传失败不会丢数据：JSON 总是先写入本地磁盘再尝试上传，且无论上传成功与否都不会删除它。上传失败只会在控制台记一条日志，并提示发起者「本地报告已保留」，直接到服务端工作目录取该文件即可。若上传地址留空（未配置），则只生成本地报告、跳过上传。
配置上传地址
在 youer.yml 中配置报告服务地址：
接口约定：POST {url}/api/tools/pulse-grasp，请求头 Content-Type: application/json，请求体为报告 JSON 原文；成功返回 HTTP 201 与包含 10 位报告 ID 的 JSON，服务端据此拼接分享链接。
上传失败排查
上传失败时控制台会额外打印一行 [PulseGrasp] upload failed: url=... size=... cause=...，含目标地址、报告体积与完整堆栈。玩家侧看到的提示语对应关系如下：
| 提示 | 含义与排查方向 |
|---|---|
| 上传服务未返回任何响应（连接被对端关闭） | 服务端接受了 TCP 连接却一个字节都没回。最常见是协议/端口不匹配：url 写 http:// 而该端口只提供 HTTPS（或反之），其次是反向代理 / WAF / CDN 直接掐断连接。请先确认域名、端口与 http/https 前缀 |
| 无法解析上传域名 | DNS 解析失败，检查域名拼写与服务端 DNS |
| 无法连接上传服务 | 目标端口没有服务在监听，或被防火墙拦截 |
| 连接或上传超时 | 网络过慢或报告体积过大，检查带宽与报告大小 |
| 与上传服务的 TLS 握手失败 | HTTPS 证书问题（自签名 / 过期 / 域名不匹配） |
HTTP 4xx / 5xx | 服务端已响应但拒绝：4xx 多为路径或鉴权问题，413 多为报告超出体积限制 |
报告内容
报告按「定位 TPS 低 / MSPT 高根因」的目标组织，重点包含：
- 瓶颈判定 — 自动给出结论（
GC_MEMORY/TICK_PHASE/OVERALL_LOAD/TRANSIENT_SPIKE/HEALTHY）与一句话说明，并区分「计算热点」与「GC 停顿」两类完全不同的成因。 - 关键指标 — 平均 / P95 / P99 / 最大 MSPT、慢 tick（≥50ms）次数与占比、GC 累计暂停与占比、峰值堆与 CPU。
- 慢 tick 成因证据 — 最慢的若干 tick 的逐 tick 阶段耗时、实体类型耗时、方块实体类型耗时，直接回答「MSPT 尖峰那一刻到底在跑什么」。
- tick 耗时分布 — 直方图与百分位，避免偶发尖峰被平均值掩盖。
- 时间线 — TPS / MSPT / Ping、CPU / 堆 / GC、网络流量。
- 方法级热点 — 按 self 时间排序的最热方法（含调用栈）、插件 / 模组归属、调用树（火焰图）与线程状态分布。
- 维度与网络 — 各维度 tick 耗时、按类型 / 玩家聚合的数据包流量。