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:8182/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.

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.

Errors & Recovery

Critical Warnings

Warning: All browser4-* and Spring Boot dependencies must use <scope>provided</scope>. Using compile scope causes ClassNotFoundException at runtime because the host application provides these classes. The plugin JAR should only bundle your own code and true third-party libraries (use compile scope for those).

Warning: Always annotate the auto-configuration class with @Lazy. Plugin beans depend on services that may not be available until the application context is fully initialized. Without @Lazy, startup may fail with BeanCreationException.

Warning: The browser4-plugin.json manifest and the Browser4Plugin.manifest property must stay in sync. The JSON file is always required for JAR discovery; the Browser4Plugin interface is optional. If both are present, the JSON manifest is authoritative for the plugin registry.

Warning: Event handlers run on the browser event loop. Never perform blocking I/O (HTTP calls, file writes) directly in a handler — use coroutines. For ToolMount executors, the framework handles coroutine dispatch automatically.

Warning: An uncaught exception in one event handler can break the entire handler chain. Always wrap handler bodies in try-catch and log failures.

Note: For lightweight plugin development without cloning the full Browser4 repo, the browser4-pdk parent POM extends pulsar-parent from Maven Central. Third-party developers only need the archetype and a Maven installation.

Tip: Build and test incrementally. After scaffolding, immediately run mvn package to verify the build works before writing any custom code. Then implement one mount point at a time, rebuilding and testing after each.

Tip: Read the browser4-pdk-test-plugin source before writing complex handlers. It demonstrates every mount point and serves as the compatibility canary.

Tip: When using @ConditionalOnProperty, prefer matchIfMissing = true so the plugin is enabled by default unless explicitly disabled. This matches the convention used by all first-party plugins.

Tip: The browser4-plugins/browser4-images/ plugin is the best all-around reference — it implements BrowseEventMount + ToolMount + Browser4Plugin with a config data class, service layer, browse event handler, and tool executor.

Reference Map

Key source files to read for patterns and examples:

See Also

• Plugin Development Guide — Official plugin development documentation
• AGENTS.md — Project architecture, build commands, code style, and testing conventions
• PDK Test Plugin — Minimal reference plugin implementing all mount points
• Built-in Plugins — Five first-party plugin implementations (captcha, images, media, pptx, markdown)