用途:在开发 apps/desktop 且用户正运行同一应用(hgui / npm run dev)时,直接读取其窗口的实时渲染 DOM,包括计算样式、几何信息、实际生效的 CSS 规则和控制台输出,避免仅凭 .tsx 推断而出错。它只回答事实性问题(计算后的 padding、元素是否渲染、哪个选择器匹配),不能判断视觉效果好坏,配色、间距观感仍需用户肉眼或截图确认。
主要能力:开发服务器运行时会自动在 127.0.0.1:9222 打开 CDP 端口,渲染进程是 Chromium 页面,DevTools 能读的脚本都能读。可用于验证 UI 改动是否生效、排查“元素为何仍是 X”并找到胜出规则、为待改组件定位稳定选择器、读取设计令牌在真实节点上的计算值、获取用户无法复制的控制台错误。不适用于性能剖析或堆分析。
使用方式:先检查端口,curl -s --max-time 3 http://127.0.0.1:${HERMES_DESKTOP_CDP_PORT:-9222}/json/version,为空表示无端口,不要静默猜测其他端口。单条查询用 cd apps/desktop 后执行 node scripts/eval.mjs "document.querySelectorAll('[data-slot]').length";多步操作用共享客户端 import { CDP, SELECTORS } from './scripts/perf/lib/cdp.mjs',通过 CDP.connect({ port: 9222, match: '5174' }) 连接并调用 cdp.eval,优先使用 SELECTORS 中的稳定 data-slot 钩子。
限制与注意:打包构建始终关闭端口,无 HERMES_DESKTOP_DEV_SERVER 时也关闭;HERMES_DESKTOP_CDP_PORT 可改端口(=9333)或禁用(=off)。不要重启用户的应用去获取端口,应启动自己的隔离实例,使用独立 HERMES_HOME、--user-data-dir 和非 9222 端口。不要杀掉用户的开发服务器;临时 HERMES_HOME 没有后端,可能记录 ECONNREFUSED 并自行退出,但渲染进程仍可读。应轮询而非只探测一次,不要整体 dump DOM,连接时传入 match 以免附着到错误目标。cdp.eval 返回的是值,原始 Runtime.evaluate 会双重嵌套。