40 lines
2.3 KiB
Org Mode
40 lines
2.3 KiB
Org Mode
#+TITLE: Root Cause Analysis: Playwright-Python Bridge (High-Fidelity Browsing)
|
|
#+DATE: 2026-04-11
|
|
#+FILETAGS: :rca:intelligence:browsing:automation:psf:
|
|
|
|
* Executive Summary
|
|
Successfully implemented a high-fidelity browsing bridge using Playwright and Python. This allows the `org-agent` to interact with modern, JavaScript-rendered web applications that were previously inaccessible via simple HTTP clients.
|
|
|
|
* 1. Architectural Strategy: The I/O Bridge
|
|
** Problem
|
|
Common Lisp lacks a mature, native Playwright implementation. Direct bindings are complex and fragile.
|
|
** Resolution
|
|
Implemented a **JSON-over-STDIO Bridge**.
|
|
- A standalone Python script (`browser-bridge.py`) manages the Playwright lifecycle and Chromium instance.
|
|
- The Lisp kernel communicates with this script using `uiop:run-program`, passing parameters via `stdin` and receiving structured results via `stdout`. This provides a stable, decoupled interface.
|
|
|
|
* 2. Environment & Dependency Management
|
|
** Issue
|
|
Playwright requires a specific version of Chromium and several system-level libraries not present in the base Debian image.
|
|
** Resolution
|
|
Updated the `Dockerfile` to:
|
|
1. Install Python3, pip, and venv.
|
|
2. Create a virtual environment for isolated dependency management.
|
|
3. Install the `playwright` package and execute `playwright install --with-deps chromium` during the image build. This ensures the production container is ready for high-fidelity browsing immediately upon startup.
|
|
|
|
* 3. Cognitive Tooling
|
|
Created the `:browser` cognitive tool, which exposes three primary capabilities to System 1:
|
|
- **Navigation:** Full JS rendering and waiting for network idle.
|
|
- **Extraction:** Targeted text retrieval via CSS selectors.
|
|
- **Vision:** Base64-encoded screenshot capture for future multimodal processing.
|
|
|
|
* 4. PSF Mandate Alignment
|
|
** Zero-Bloat (Managed)
|
|
While adding Playwright increases the image size, it is a "Complexity Earned" trade-off that dramatically expands the agent's capability frontier.
|
|
** Literate Granularity
|
|
The `org-skill-playwright.org` file strictly follows the "one definition per block" mandate.
|
|
|
|
* 5. Permanent Learnings
|
|
- **Inter-Process JSON:** JSON is the ideal lingua franca for Lisp-Python bridges.
|
|
- **Path Portability:** Always use `uiop:native-namestring` when passing Lisp paths to external shell commands to ensure OS compatibility.
|