docs(skill): Clarify Node 24 ESM imports, captureScreenshot signature, and asset cache invalidation

Description / 问题描述

Hi team,

When using coding agents to execute browser tasks via ego-browser nodejs <<'EOF', agents frequently encounter unnecessary friction and repeated failures due to underspecified guidance in skills/ego-browser/SKILL.md:

1. Node 24 Module Format Collision: The embedded Node runtime (v24.x) supports top-level await. When agents try to import standard modules with CommonJS (const fs = require('fs')), Node throws: ReferenceError: Cannot determine intended module format because both 'require' and top-level await are present. Agents often burn multiple rounds before realizing they must use import fs from 'node:fs'.

2. Undocumented captureScreenshot helper: captureScreenshot is listed in the helper overview, but lacks a dedicated signature or usage example. Agents frequently assume it is incomplete or requires raw CDP handling (cdp('Page.captureScreenshot')) and manual base64 buffer conversion to disk.

3. Asset Cache Invalidation in Local Dev: When developing/testing local modern frontends (Astro, Vite, Next.js), asset bundles frequently update hashes (e.g. index.[hash].css). Reusing existing tabs with openOrReuseTab silently preserves old DOM and cached CSS, leading agents to falsely believe their CSS updates did not take effect.

4. Dynamic Code Injection via js(...): Passing multiline dynamic strings with nested template literals into js(...) often breaks syntax parsing.

Solution / 解决建议

We have prepared the fix in our fork: Branch / Commit: https://github.com/qian-123456/ego-lite/commit/7cf90ac (Direct PR from fork was blocked due to repository interaction/PR permissions, so opening an issue with the diff below)

--- a/skills/ego-browser/SKILL.md
+++ b/skills/ego-browser/SKILL.md
@@ -150,6 +150,15 @@
 ```js
 await uploadFile('input[type="file"]', "/absolute/path/to/file.pdf")

+### captureScreenshot + +js +const path = await captureScreenshot() +cliLog('Screenshot saved to: ' + path) + + +await captureScreenshot() captures the visible viewport / page and automatically writes it to an OS temporary image file, resolving to its local file path as a string. Do not manually invoke cdp('Page.captureScreenshot') and write base64 buffers to disk unless custom CDP parameters (e.g. clipping rects) are strictly required. +

js

@@ -207,3 +216,6 @@

• Always call completeTaskSpace(name, { keep }) when the task is done — do not leave the space hanging. Default to { keep: false }; use { keep: true } only for the concrete live-page cases described in Task spaces.
• When the user explicitly asks to use ego-browser, assume both ego-browser and the repo runtime are ready. Do not pre-check which ego-browser, node -v, package metadata, or help output. Only investigate environment issues if the first run produces an error.
• If the first run reports command not found / a missing environment (most likely ego lite isn't installed yet), or the user explicitly asks to install ego lite, first read references/install.md and follow its flow to complete the install, then return to the original task — do not give up, and do not keep retrying the same heredoc. +- Node 24 Module Imports: The heredoc body runs in Node 24 with top-level await. If Node standard libraries (fs, path, etc.) are needed, always use ES imports (import fs from 'node:fs'). Mixing CommonJS require(...) with top-level await throws ReferenceError: Cannot determine intended module format because both 'require' and top-level await are present. +- Asset updates and cache invalidation: When rebuilding local web projects (Vite, Astro, Webpack, etc.), static asset hashes frequently change. If reusing an existing tab with openOrReuseTab, the browser retains the old document and cached CSS/JS bundles. Force a clean reload using await gotoAndWait(url, { timeout: 10 }) or await js('location.reload()') rather than relying on silent tab reuse. +- Dynamic code injection via js(...): Avoid assembling complex multi-line strings or nested backticks inside js(...) template literals. Instead, serialize payloads with JSON.stringify(...) or maintain clean single-line IIFEs to avoid syntax parse errors.