跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

pandascript

Write PandaScript agent scripts (.js) — Lightpanda's replayable browser-automation format, run token-free with `lightpanda agent script.js`.

lightpanda-io · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add lightpanda-io/agent-skill --skill pandascript

技能说明


name: pandascript description: Write PandaScript agent scripts (.js) — Lightpanda's replayable browser-automation format, run token-free with lightpanda agent script.js.

Writing Lightpanda agent scripts

Run with:

./lightpanda agent script.js

Mental model (get this right first)

The script runs in its own V8 context — neither the page nor Node.js:

  • Page is the only global. new Page() makes a page and await page.goto(url) navigates it; every other primitive is a method on that page: const page = new Page(); await page.goto(url); page.extract({...}); page.click(sel);.
  • No window, document, DOM, localStorage — read pages with page.extract(...), run page-side JS only via page.evaluate("...").
  • No require, process, fs, npm. Standard ECMAScript built-ins only (JSON, Map, template literals, …).
  • page.goto(...) is async — always await it. Page methods are synchronous: const data = page.extract({...}), never await page.extract(...). The script body runs as an async function, so top-level await is allowed.
  • Re-navigating reuses the same page: await page.goto(url2) keeps page valid and points it at the new URL, discarding the old page — read it before navigating away. Independent URLs don't share a page: make a new Page() for each and load them in parallel (fan-out, best practice 2).
  • Page evaluate("...") cannot see script variables — interpolate values into the string. Script code cannot see page variables.
  • Variables persist across navigations within one run, so cross-page aggregation is plain JS.
  • return <value> is the script's output, printed automatically (objects/arrays as JSON). End with return page.extract({...}); or return results;. A bare trailing expression is NOT printed; neither is console.log(JSON.stringify(...)).

Primitives

Page is the only global; new Page() makes a page and everything else is a method on it.

CallNotes
new Page()Makes a page object. No navigation yet — call page.goto(url) before any other method. Make several to navigate in parallel (fan-out, best practice 2).
page.close()Marks the page done; later method calls on it error. The page is otherwise reclaimed at script end.
await page.goto(url[, { timeout }])Async — must be awaited. Navigates the page (re-navigating reuses the same object). Waits for load. Rejects on navigation failure; a timeout does NOT reject (the page may still be usable). Default timeout 10000 ms.
page.evaluate(script[, { url, timeout, save }])Page-side JS escape hatch; returns text (JSON for objects/arrays).
page.extract(schema)The only primitive returning a real JS value (object/array). The schema is its only argument. See schema below.
page.click(selector)
page.fill(selector, value)
page.scroll([{ x, y }])
page.waitForSelector(selector[, { timeout }])waitFor* default timeout 5000 ms.
page.waitForScript(script[, { timeout }])Re-evaluates page JS until truthy.
page.waitForState(state[, { timeout }])state: one of "load", "domcontentloaded", "networkalmostidle", "networkidle", "done".
page.hover(selector)
page.press(selector, key)Selector first! page.press("Enter") binds "Enter" to selector and fails — use page.press(null, "Enter") or page.press({ key: "Enter" }).
page.selectOption(selector, value)
page.setChecked(selector[, checked])checked defaults to true.

Options (the trailing { … } object; every option may be omitted):

  • goto: timeout — Optional timeout in milliseconds. Defaults to 10000.
  • evaluate: url — Optional URL to navigate to before evaluating. timeout — Optional timeout in milliseconds. Defaults to 10000. save — Optional bridge-store key. The evaluate's return value is stored under this name and re-exposed as lp.<name> to subsequent evaluates. Objects, arrays, and strings are serialized automatically — no JSON.stringify needed.
  • scroll: x — Optional: The horizontal scroll offset. y — Optional: The vertical scroll offset.
  • waitForSelector: timeout — Optional timeout in milliseconds. Defaults to 5000.
  • waitForScript: timeout — Optional timeout in milliseconds. Defaults to 5000.
  • waitForState: timeout — Optional timeout in milliseconds. Defaults to 5000.

Calling convention: leading positionals + optional trailing options object, or one object with everything (page.waitForSelector("#row", { timeout: 2000 }) ≡ page.waitForSelector({ selector: "#row", timeout: 2000 })). A bare option positional (page.waitForSelector("#row", 2000)) and a field passed both ways are invalid arguments. null skips a positional. Arguments must be JSON-serializable.

CSS selectors only — backendNodeIds don't exist here. Standard CSS only: no jQuery :contains() or Playwright :has-text().

extract schema

Keys = output field names; values pick what to lift (not a JSON Schema):

const { stories } = page.extract({
  stories: [{
    selector: "tr.athing",          // one record per match
    limit: 5,
    fields: {                        // resolved relative to each match
      title: ".titleline > a",      // first match's text (null if missing)
      url: { selector: ".titleline > a", attr: "href" },
      text: ""                       // "" = the matched element's own text
    }
  }]
});
  • "sel" → first match's text; ["sel"] → all matches' text; { selector, attr } / [{ selector, attr }] → attribute(s); limit: N caps any array form.
  • Every value is a string or null — parse numbers in script logic.
  • Empty arrays are valid results; if every field misses, extract throws ("no schema selector matched any element") → your selectors are wrong, not the page empty.
  • An object schema always returns an object (destructure it); a bare array schema returns the array dire
阅读完整来源 ↗