inspecting-hermes-desktop-dom
Read the live Hermes desktop DOM/CSS over CDP.
- License 许可
- MIT
- 最近更新
- 2026-10-26
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- inspecting-hermes-desktop-dom
- author
- Hermes Agent
- license
- MIT
- version
- 1.0.0
- metadata
- { "hermes": { "tags": [ "desktop", "electron", "cdp", "dom", "ui-verification", "self-inspection" ], "related_skills": [ "node-inspect-debugger", "systematic-debugging", "dogfood" ] } }
- platforms
- [ "linux", "macos", "windows" ]
- description
- Read the live Hermes desktop DOM/CSS over CDP.
03 SKILL.md 正文
Inspecting the live Hermes desktop DOM
Overview
When you are developing apps/desktop and the user is running that same app
(hgui / npm run dev), you can read the live rendered DOM of the window
they are looking at — computed styles, geometry, which CSS rule actually won,
console output — instead of inferring it from .tsx and being wrong.
Dev-server runs open a Chrome DevTools Protocol port on 127.0.0.1:9222
automatically. The renderer is a Chromium page, so everything DevTools can read,
a script can read.
This does not replace looking at it. CDP answers factual questions ("what is the computed padding", "did this element render", "which selector matches"). It cannot tell you whether the result looks good. Colour balance, spacing feel, and "is this ugly" still need the user's eyes or a screenshot. Answer facts with CDP; hand aesthetics to the user.
When to Use
- Verifying a UI change actually took effect in the running app
- "Why is this element still X?" — find the winning rule before editing anything
- Locating a stable selector for a component you're about to change
- Checking a design token's computed value on a real node
- Reading renderer console errors the user mentions but can't copy out
Don't use for: perf profiling or heap work (node-inspect-debugger,
debugging-hermes-desktop), or anything where the real question is "does this
look right".
The port
Open on 127.0.0.1:9222 for any dev-server run. Closed in exactly two cases
(apps/desktop/electron/dev-cdp.ts):
- packaged builds — always, and no environment value overrides it;
- no
HERMES_DESKTOP_DEV_SERVER— an unpackagedelectron .againstdist/is how the packaged app gets smoke tested, so it behaves like one.
HERMES_DESKTOP_CDP_PORT moves the port (=9333) or disables it (=off).
Check before doing anything else:
curl -s --max-time 3 http://127.0.0.1:${HERMES_DESKTOP_CDP_PORT:-9222}/json/version
Empty → no port. Do not guess another port silently.
Never relaunch the user's app to get a port. That destroys their session and their state. Launch your own isolated instance instead (below).
Reading the DOM
apps/desktop/scripts/eval.mjs is the one-liner:
cd apps/desktop
node scripts/eval.mjs "document.querySelectorAll('[data-slot]').length"
For multi-step work use the shared client — it has target discovery and promise-aware eval:
import { CDP, SELECTORS } from './scripts/perf/lib/cdp.mjs'
const cdp = await CDP.connect({ port: 9222, match: '5174' })
const out = await cdp.eval(`JSON.stringify({
radius: getComputedStyle(document.documentElement).getPropertyValue('--radius-scalar').trim(),
composer: !!document.querySelector('[data-slot="composer-rich-input"]')
})`)
cdp.close()
SELECTORS in scripts/perf/lib/cdp.mjs holds the stable data-slot hooks
(composer, thread viewport, assistant message, turn pair, profile rail). Prefer
them over inventing a querySelector — they are updated as a unit when
components move.
The question this is best at: which rule won?
Editing every call site because a style "isn't applying" is the classic waste. Read the real node first:
const el = document.querySelector('[data-slot="aui_assistant-message-root"] a')
JSON.stringify({
ownClasses: el.className,
weight: getComputedStyle(el).fontWeight,
parents: (() => {
const out = []
let n = el
while ((n = n.parentElement) && out.length < 6) out.push(n.className)
return out
})()
})
If the node carries no class of its own, the value is inherited — sweeping
call sites will not fix it, and you need the ancestor rule. A plugin stylesheet
(e.g. @tailwindcss/typography's prose a { font-weight: 500 }) routinely beats
a utility class; override on the shared class, not at each usage.
Your own isolated instance
When there is no port, or you must not disturb the user's window:
cd apps/desktop
HERMES_HOME=$HOME/.hermes/cache/scratch/cdp-probe-home \
HERMES_DESKTOP_DEV_SERVER=http://127.0.0.1:5174 \
HERMES_DESKTOP_CDP_PORT=9333 \
npx electron . --user-data-dir=$HOME/.hermes/cache/scratch/cdp-probe-userdata
The separate --user-data-dir dodges Electron's single-instance lock, so it
cannot collide with a running hgui; the separate HERMES_HOME keeps it away
from real sessions. Pick a port other than 9222 for the same reason. Run it in
the background and kill it when done.
npm run perf:serve does the same with a temp HERMES_HOME baked in, if you
also want the perf harness.
Pitfalls
- Never kill the user's dev server or app to "free" anything. A mid-serve
kill nukes Chromium's socket pool, and the resulting
ERR_NETWORK_CHANGEDgets blamed on whatever you just changed. - A throwaway
HERMES_HOMEhas no backend. The app logsECONNREFUSEDforhermes:apiand may exit on its own. The renderer still mounts and the DOM is readable — read promptly, and don't mistake a self-exited probe for a broken port. Chromium logsDevTools listening on ws://127.0.0.1:<port>/…when it binds; that line is the proof the port opened. - Poll, don't probe once. A just-launched app needs a second or two before the port answers.
- Never dump the whole DOM. The desktop renders hundreds of nodes and
outerHTMLwill bury your context. Project down to a small JSON object inside the evaluated expression. - Pass
matchtoCDP.connect. Without it you may attach to the pet overlay, quick-entry window, or a devtools target instead of the main window. cdp.evalreturns the value; rawRuntime.evaluatedouble-nests it (.result.result.value). Use the wrapper.import.meta.env.DEVistrueundervite devin this repo. The note inapps/desktop/scripts/profile-typing-lag.mdclaiming otherwise is stale.
04 同仓库更多 Skills
blocked-page-recovery
Use when a fetch fails: 403/429, paywall, WAF, bot wall.
unreal-world-builder
开放世界与环境专家——精通 UE5 World Partition、Landscape、程序化植被、HLOD 和大规模关卡流式加载,打造无缝开放世界体验
unreal-technical-artist
Unreal Engine 视觉管线专家——精通材质编辑器、Niagara 特效、程序化内容生成和 UE5 项目的美术到引擎管线
unreal-systems-engineer
性能与混合架构专家——精通 C++/Blueprint 边界、Nanite 几何体、Lumen GI 和 Gameplay Ability System,面向 AAA 级 Unreal Engine 项目
unreal-multiplayer-architect
Unreal Engine 网络专家——精通 Actor 复制、GameMode/GameState 架构、服务端权威玩法、网络预测和 UE5 专用服务器配置
unity-shader-graph-artist
视觉效果与材质专家——精通 Unity Shader Graph、HLSL、URP/HDRP 渲染管线和自定义渲染 Pass,打造实时视觉效果