Browser4 Plugin

Browser4 Plugin Development

Quick Start

mvn -pl browser4-pdk install          # install the PDK parent POM once
mvn archetype:generate -DarchetypeGroupId=ai.platon.pulsar \
    -DarchetypeArtifactId=browser4-plugin-archetype   # scaffold the plugin project
mvn -f <artifactId>/pom.xml package   # build the plugin JAR

Deploy the JAR to the server's plugins/ directory (or POST it to http://localhost:18182/api/plugins/install) and restart — the plugin is auto-discovered. Prerequisites: JDK 17+, Maven 3.9+, and access to the browser4-pdk parent POM.

For the full walkthrough — requirements clarification, mount-point implementation, services/config, manifest, tests, build & deploy — see Step-by-Step Workflow.

When to Use

Use this skill when the user wants to create, build, scaffold, or extend a Browser4 plugin — CAPTCHA solving, media processing, content conversion, page-category detection, custom RPA actions, or new LLM agent tools. It is the deep guide (mount points, services, tests, deployment); for plugin code scaffolding inside this repo use the browser4-coding skill.

Do NOT create a plugin for: simple data extraction from a known site (use the browser4-cli HTML snapshot / X-SQL instead), one-off browser automation (the CLI or a quick script is faster), or modifying core Browser4 behavior (that belongs in the main source tree, not a plugin).

How It Works

A plugin is a thin JAR built against the browser4-pdk parent POM: you scaffold the project from the archetype, implement the relevant PluginMount interfaces (Browse/Load/Crawl event mounts, ToolMount, PageSnifferMount), wire Spring auto-configuration, and build. The server auto-discovers the JAR from plugins/ on restart and logs the mounted beans.

Patterns

1. Event-handling plugin (BrowseEventMount)

Scaffold with mountPoints=["BrowseEventMount"], implement the browse handler, and register it via auto-configuration. The key hook is onDocumentSteady — see Step 4a for the full code.

2. Plugin with LLM agent tools (ToolMount)

Scaffold with mountPoints=["ToolMount"] and hasCustomTools=true, implement a ToolExecutor extending AbstractToolExecutor, and declare the tool in plugin.json — see Step 4d.

3. Full-featured plugin (all major patterns)

Model it on the first-party plugins — browser4-plugins/browser4-images/ implements BrowseEventMount + ToolMount + Browser4Plugin + Config + Service + BrowseEventHandler + ToolExecutor.

4. Summary algorithm plugin (PageSummaryAlgorithmMount)

Scaffold with mountPoints=["PageSummaryAlgorithmMount"], implement PageSummaryAlgorithm (id/displayName/description + generate(PageSummaryInput)), and expose it via the mount bean. The algorithm becomes selectable with browser4-cli htmlsnapshot summary --algorithm <id> and visible in browser4-cli htmlsnapshot algorithms — see Contributing a summary algorithm.

Flags

The archetype takes named parameters — there are no CLI flags:

When to Create a Plugin

Create a plugin when you need to:

• Hook into the browse lifecycle — execute custom logic on page-navigation events (before navigation, after DOM is steady, before tab close). Examples: CAPTCHA detection and solving, ad blocking, custom RPA workflows.
• Hook into the load lifecycle — intercept or transform page content during loading. Examples: URL normalization and stripping tracking parameters, content extraction, HTML post-processing.
• Hook into the crawl lifecycle — accept or reject URLs during crawling. Examples: domain allowlists, duplicate URL filtering, paywall detection and skip.
• Register custom tools for LLM agents — expose new capabilities as callable functions. Examples: image download, PPTX generation, database queries, API integrations.
• Add page category sniffers — teach Browser4 to recognize new page types so it can adapt its behavior. Examples: CAPTCHA pages, login pages, paywalls, shopping carts.
• Contribute page summary algorithms — add alternative htmlsnapshot summary generators (domain-specific, readability-focused, LLM-based) selected via --algorithm <id>.

Errors & Recovery