home / skills / dcjanus / prompts / pwdebug

pwdebug skill

safe

This skill enables debugging a real browser via a Playwright-based CLI, reusing a single session to navigate, evaluate JS, screenshot, and inspect elements.

npx playbooks add skill dcjanus/prompts --skill pwdebug

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

1.7 KB

---
name: pwdebug
description: 用于需要通过命令行操作真实浏览器实例进行前端调试（如导航、执行 JS、截图、元素拾取、控制台日志）且希望跨多次命令复用同一浏览器会话的场景。
---

# Playwright 浏览器调试 CLI

## 概览

该技能提供一个基于 Playwright 的命令行工具，用于启动浏览器服务并执行导航、评估 JS、截图、元素拾取与日志监听等调试操作。当前仅支持 Chromium（通过 CDP 连接）。

## 快速开始

> 工作目录应为本文件所在目录，示例命令默认从该目录执行。
> 说明：必须直接执行脚本，不要用 `uv run python` 或 `python`。

脚本调用方式示例：
```bash
cd skills/pwdebug && ./scripts/pwdebug.py start
```
错误示例：
```bash
uv run python skills/pwdebug/scripts/pwdebug.py start
python skills/pwdebug/scripts/pwdebug.py start
```

1. 启动浏览器服务（常驻进程）：

```bash
./scripts/pwdebug.py start
```

2. 在新标签页打开页面：

```bash
./scripts/pwdebug.py nav https://example.com --new
```

3. 执行 JS 表达式：

```bash
./scripts/pwdebug.py evaluate "document.title"
```

4. 截图：

```bash
./scripts/pwdebug.py screenshot --full
```

5. 交互式拾取元素：

```bash
./scripts/pwdebug.py pick "点击登录按钮"
```

6. 监听控制台日志：

```bash
./scripts/pwdebug.py watch-logs
```

7. 查看最近日志：

```bash
./scripts/pwdebug.py logs 100
```

## 说明

- CLI 入口：`./scripts/pwdebug.py`
- 日志路径：`~/.cache/pwdebug/console.log.jsonl`
- 状态路径：`~/.cache/pwdebug/server.json`

## 依赖与安装

- 脚本依赖通过 `uv --script` 管理。

Overview

This skill provides a Playwright-based command-line debugger for driving a real Chromium browser instance via CDP. It keeps a persistent browser service so you can run multiple commands that reuse the same browser session. The tool supports navigation, JS evaluation, screenshots, interactive element picking, and console log capture for front-end debugging.

How this skill works

A resident browser service is started by the CLI and listens for subsequent commands that control the same browser session. Commands include nav, evaluate, screenshot, pick, watch-logs and logs; each command connects to the running service and issues the requested CDP/Playwright actions. Logs and server state are persisted to the user cache so you can inspect recent console output and server status between runs.

When to use it

When you need to interact with a real browser from the shell and preserve state across commands.
When reproducing UI bugs that require navigation, DOM inspection or JS evaluation over multiple steps.
When you want automated screenshots or full-page captures from an interactive session.
When you need to collect console logs or watch runtime logs while exercising a page.
When you want to pick page elements interactively and run targeted script snippets.

Best practices

Run the CLI from its containing directory and invoke the script directly (e.g., ./scripts/pwdebug.py start).
Always start the resident browser service first, then run navigation or other commands to reuse the session.
Use --new when you need a fresh tab and --full for full-page screenshots to avoid cropping.
Monitor console logs with watch-logs during test steps, and inspect recent logs via logs N for troubleshooting.
Keep the environment secure when running a long-lived browser service and avoid exposing it on untrusted networks.

Example use cases

Start the service, open a site, reproduce a UI flow, then evaluate document state to debug a failing assertion.
Capture a full-page screenshot of a SPA route after interactive navigation to validate visual regressions.
Pick a page element interactively to obtain selectors, then run JS snippets against that element for quick fixes.
Stream console logs while running a user scenario to capture errors and network-related messages in real time.
Run short ad-hoc scripts (evaluate) against the live page to inspect variables or invoke client-side utilities.

FAQ

Which browser engines are supported?

Currently only Chromium is supported via a CDP connection.

How do I start the browser service?

Run the CLI entry directly from the skill directory: ./scripts/pwdebug.py start

Where are logs and state stored?

Console logs are saved to ~/.cache/pwdebug/console.log.jsonl and server state to ~/.cache/pwdebug/server.json