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:
Pageis the only global.new Page()makes a page andawait 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 withpage.extract(...), run page-side JS only viapage.evaluate("..."). - No
require,process,fs, npm. Standard ECMAScript built-ins only (JSON,Map, template literals, …). page.goto(...)is async — alwaysawaitit. Page methods are synchronous:const data = page.extract({...}), neverawait page.extract(...). The script body runs as an async function, so top-levelawaitis allowed.- Re-navigating reuses the same page:
await page.goto(url2)keepspagevalid and points it at the new URL, discarding the old page — read it before navigating away. Independent URLs don't share a page: make anew 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 withreturn page.extract({...});orreturn results;. A bare trailing expression is NOT printed; neither isconsole.log(JSON.stringify(...)).
Primitives
Page is the only global; new Page() makes a page and everything else is a method on it.
| Call | Notes |
|---|---|
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 aslp.<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: Ncaps 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