前言¶

在 DeepSeek Harness（DSH）里做 Web 客户端插件或调试会话界面时，常见困境不是「有没有 DevTools」，而是「刚刚那一下卡了，当时没开着 Performance」。DSH 自带的实验性开发者工具偏前台显微镜：断点、Host console、网络抓包、会话日志、Cordis 树；Client 侧 Performance 只采 Host CPU，不给页面渲染 trace 和帧数据。若你需要默认常开、事后能复盘「现在顺不顺、卡在谁身上、是插件还是宿主/链路」，就需要一块常驻的客户端行车记录仪。下面介绍社区插件 dsh-perf-hud（维护者 yanzhaohui1999，分类：客户端）。

这是什么¶

dsh-perf-hud 是纯客户端性能 HUD：右下角浮层回答「现在卡不卡、卡在谁身上」。它记录帧与最差帧、Longtask（含四条腿归因）、各插件回调速率与同步耗时、DOM 增长与写入者、JS 堆、宿主 event-loop 与链路 RTT，并提供隔离实验与一键导出 JSON。另有一层「守夜」：偶发卡顿时自动留存最差几次现场，可连证据一次性导出。当前 npm 版本为 v0.6.0，许可证 MIT；README 标明与 DSH 0.2.1-rc.1 兼容。

和 DSH 自带开发者工具的分工¶

两边不互相依赖。装了本插件也不会补全 DevTools 事故包里缺失的 devtools-trace；开发者工具抓全量 Host fetch（含密钥）与本插件「导出前减法脱敏」是两套口径。

快捷键：Cmd/Ctrl+Shift+U 展开/收起（macOS / Windows）；Linux Web 平台白名单未绑定该组合。收起/展开不抢输入框焦点。

核心功能¶

面板能回答什么¶

守夜层（偶发卡顿）¶

面板需要人盯着看，偶发卡顿往往发生在没看的时候。插件默认开着一层不插桩的记录器：

1. 每帧写入帧级环形缓冲（约 12000 条，60fps 下约 3.3 分钟），并挂载 LoAF 观察器（Chrome 123+）。
2. 单帧超过 100ms，或 LoAF 的 blockingDuration 超过 100ms，自动抓取：前 10 秒 + 后 3 秒原样切片。
3. 留存策略：全局最差 10 次 + 每天最差 1 条（最多最近 7 天）并集；落盘有 2MB 字节上限，超出从最弱条目裁切，裁掉条数在常显行「裁掉 N」中展示；刷新或重启浏览器后仍可读回，watch().restored 表示本次读回条数。
4. 「检测到」「同串触发（coalesced）」「已保存现场」「丢失」口径分开；折叠药丸上的「检测 N 次」指最近 24 小时（跨刷新），不等于留存份数。
5. 标签页隐藏造成的 rAF 挂起间隙不算卡顿，事故包标为 gap。该层不包装任何原型，只用 rAF 与 PerformanceObserver。

四条腿归因与取证明细¶

Longtask 与长动画帧可拆到脚本、任务、渲染、样式+布局+绘制等维度；脚本侧再按 LoAF 的 invoker（按来源）与包名（合并批靠 sourcemap 分段）归因。深录（精确归因）未开时，回调归因、DOM 写入等块会降级显示「要深录」，避免把未插桩状态误读为 0 开销。历史事故的帧时间轴数据来自事故包本身，刷新后仍有效且不增加采集成本。

隔离实验¶

隔离实验已移到控制台 API，用于逐个关闭插件约 60 秒并与基线对照（README 目录项「隔离实验(已移到控制台)」）。

安装与启用¶

v0.6.0 已发布到 npm。在 Web profile 下执行：

dsh plugin --profile web add dsh-perf-hud

插件在 package.json 中声明为 Web 客户端、immediately: true，并通过 Cordis patch 注入客户端槽位；安装后随 DSH Web 客户端加载，HUD 默认常开（含守夜层）。

典型用法¶

控制台 API¶

在浏览器控制台（插件暴露的全局对象）可查询守夜状态、事故摘要与导出：

__perfHud.watch()             // 在不在录、覆盖多少秒、LoAF 是否安装、抓到几次
__perfHud.incidents()         // 最差几次的摘要（索引 0 最差）
__perfHud.report(0)           // 完整事故包：帧序列 + LoAF + 窗口内 longtask + 环境读数
__perfHud.exportIncident(0)   // 下载 JSON，文件名形如 perf-hud-20261008-220358-i84.json
__perfHud.capture('切了视图')  // 手动标记「刚刚卡了一下」（自动回退约 3 秒）
__perfHud.clearIncidents()    // 只清事故；clear() 刻意不动守夜数据

统计口径与面板悬停一致时，可用 __perfHud.tally()。

面板操作要点¶

• 圆环上方 帧 1/12 · 530ms · ≥100ms ◀ ▶ ⟲：按 frameSeverity = max(blocking, 帧时长) 排序；◀ ▶ 钉住某条，⟲ 回到自动跟最差。
• 「取证明细」含 60 秒帧条：可点击有长动画帧的秒格跳转到对应帧；整秒 rAF 挂起为灰柱（间隙）。
• 从实时监控进入历史事故用「看这一帧」，回实时用「回到实时」；上下文会落盘，刷新后尽量保持同一事故与帧。

适用场景与注意¶

适合谁： 在 DSH Web 客户端里开发或排查插件、会话 UI、流式渲染与 event-loop 问题时，需要常驻帧级观测、Longtask 归因、插件回调与 DOM 写入统计，以及偶发卡顿事后导出 JSON 证据包的开发者。

权限与信任： 插件以当前 DSH 进程权限在客户端运行，会持续观测页面性能并可能持久化事故包到本地存储。安装前应阅读 GitHub 仓库 源码与 MIT 许可证，并阅读 README 中「风险与边界(必读)」：例如导出前脱敏与 DevTools 抓包口径不同、页面内无法替代 Chrome trace 的函数级采样、部分 UI 联动因稳定性原因已停用等。

环境边界： LoAF 依赖 Chrome 123+；Linux Web 未绑定 Cmd/Ctrl+Shift+U。守夜留存条数受容量限制，不能单靠清单条数回答「最近卡了几次」——被挤掉的卡顿仍可能发生在计数层。

链接¶

• 社区目录页：skillhub.cn/plugins/yanzhaohui1999/dsh-perf-hud（独立社区站点，与 DeepSeek / 幻方无官方从属关系）
• 源码与文档：github.com/yanzhaohui1999/dsh-perf-hud

DSH 生态理念是「一切皆插件」；dsh-perf-hud 补的是 Client 侧常开性能 HUD 与守夜事故包，与官方开发者工具分工明确，适合作为日常开发时的行车记录仪，在卡顿发生后再用 exportIncident 把现场交给人工或 agent 分析。