chrome-devtools-axi Browser Automation

chrome-devtools-axi 浏览器自动化

Skill by ara.so — Devtools Skills collection.

由ara.so提供的Skill — Devtools Skills合集。

Overview

概述

chrome-devtools-axi

is an AXI-compliant CLI wrapper around

chrome-devtools-mcp

that provides token-efficient browser automation. It uses TOON-encoded output to reduce token usage by ~40% compared to raw JSON, combines operations (navigate + snapshot + suggestions in one command), and includes contextual next-step hints in every response.

Key features:

Accessibility tree snapshots with
```
uid=
```
refs for precise element targeting
Generation-based staleness detection prevents silent no-ops when page state changes
Persistent bridge process keeps Chrome session alive across commands
Combined operations reduce round-trips for agents

chrome-devtools-axi

是一个符合AXI标准的CLI封装工具，基于

chrome-devtools-mcp

构建，可提供令牌高效的浏览器自动化能力。它采用TOON编码输出，相比原始JSON能减少约40%的令牌消耗，支持组合操作（在一个命令中集成导航+快照+建议功能），且每个响应中都包含上下文相关的下一步提示。

核心特性：

可访问性树快照：通过
```
uid=
```
引用实现精准元素定位
基于生成版本的过期检测：页面状态变化时避免无提示的无效操作
持久化桥接进程：跨命令保持Chrome会话持续活跃
组合操作：减少Agent的往返请求次数

Installation

安装

For agents to install automatically:

bash

npx -y chrome-devtools-axi

For manual installation:

bash

npm install -g chrome-devtools-axi

Tell your agent:

Execute `npx -y chrome-devtools-axi` to get browser automation tools.

供Agent自动安装：

bash

npx -y chrome-devtools-axi

手动安装：

bash

npm install -g chrome-devtools-axi

告知你的Agent：

执行 `npx -y chrome-devtools-axi` 获取浏览器自动化工具。

Architecture

架构

The CLI communicates with a persistent bridge server (localhost:9224 by default) that maintains an MCP session with Chrome via DevTools Protocol. The bridge auto-starts on first command and writes state to

~/.chrome-devtools-axi/

.

CLI与持久化桥接服务器（默认端口localhost:9224）通信，该服务器通过DevTools Protocol维持与Chrome的MCP会话。桥接服务会在首次执行命令时自动启动，并将状态写入

~/.chrome-devtools-axi/

目录。

Core Commands

核心命令

Navigation and Snapshot

导航与快照

bash

undefined

bash

undefined

Navigate to a URL and capture accessibility tree

导航至指定URL并捕获可访问性树

chrome-devtools-axi open https://example.com

Capture current page state

捕获当前页面状态

chrome-devtools-axi snapshot

Navigate back

返回上一页

chrome-devtools-axi back

Scroll page

滚动页面

chrome-devtools-axi scroll down chrome-devtools-axi scroll top

Wait for time or content

等待指定时长或内容加载完成

chrome-devtools-axi wait 2000 chrome-devtools-axi wait "Welcome"

undefined

chrome-devtools-axi wait 2000 chrome-devtools-axi wait "Welcome"

undefined

Element Interaction

元素交互

Elements in snapshots are marked with

uid=g<generation>:<id>

refs. Always use refs exactly as printed:

bash

undefined

快照中的元素会标记为

uid=g<generation>:<id>

格式的引用，请严格按照输出内容使用这些引用：

bash

undefined

Click an element

点击元素

chrome-devtools-axi click @g1:1

Fill a form field

填写表单字段

chrome-devtools-axi fill @g2:5 "user@example.com"

Fill multiple fields at once

批量填写多个字段

chrome-devtools-axi fillform @g2:5=john @g2:6=doe @g2:7=john@example.com

Type text at current focus

在当前焦点位置输入文本

chrome-devtools-axi type "search query"

Press keyboard key

按下键盘按键

chrome-devtools-axi press Enter chrome-devtools-axi press Tab

Hover over element

悬停在元素上

chrome-devtools-axi hover @g1:3

Drag and drop

拖拽操作

chrome-devtools-axi drag @g1:4 @g1:8

Upload file

上传文件

chrome-devtools-axi upload @g1:2 /path/to/file.pdf

Handle browser dialogs

处理浏览器对话框

chrome-devtools-axi dialog accept chrome-devtools-axi dialog dismiss

undefined

chrome-devtools-axi dialog accept chrome-devtools-axi dialog dismiss

undefined

Screenshots

截图

bash

undefined

bash

undefined

Save screenshot to file

将截图保存至文件

chrome-devtools-axi screenshot output.png

Capture specific element

捕获指定元素的截图

chrome-devtools-axi screenshot element.png --uid @g1:5

Full-page screenshot

全页面截图

chrome-devtools-axi screenshot full.png --full-page

Specify format

指定截图格式

chrome-devtools-axi screenshot output.jpg --format jpeg

undefined

chrome-devtools-axi screenshot output.jpg --format jpeg

undefined

JavaScript Evaluation

JavaScript 执行

bash

undefined

bash

undefined

Evaluate expression (auto-wrapped)

执行表达式（自动包装）

chrome-devtools-axi eval "document.title"

Execute function

执行函数

chrome-devtools-axi eval "() => document.querySelectorAll('a').length"

Multi-statement logic

多语句逻辑执行

chrome-devtools-axi eval "() => { const rows = [...document.querySelectorAll('tr')]; return rows.map(row => row.textContent.trim()); }"

undefined

chrome-devtools-axi eval "() => { const rows = [...document.querySelectorAll('tr')]; return rows.map(row => row.textContent.trim()); }"

undefined

Multi-Step Scripts

多步骤脚本

bash

undefined

bash

undefined

Execute script from stdin

从标准输入执行脚本

cat << 'EOF' | chrome-devtools-axi run open https://example.com wait "Example Domain" click @g1:1 snapshot EOF

undefined

cat << 'EOF' | chrome-devtools-axi run open https://example.com wait "Example Domain" click @g1:1 snapshot EOF

undefined

Page Management

页面管理

bash

undefined

bash

undefined

List all tabs

列出所有标签页

chrome-devtools-axi pages

Open new tab

打开新标签页

chrome-devtools-axi newpage https://google.com

Open in background

在后台打开新标签页

chrome-devtools-axi newpage https://github.com --background

Switch tab

切换标签页

chrome-devtools-axi selectpage <id>

Close tab

关闭标签页

chrome-devtools-axi closepage <id>

Resize viewport

调整视口大小

chrome-devtools-axi resize 1920 1080

undefined

chrome-devtools-axi resize 1920 1080

undefined

Device Emulation

设备模拟

bash

undefined

bash

undefined

Emulate mobile viewport

模拟移动端视口

chrome-devtools-axi emulate --viewport "390x844x3,mobile"

Set color scheme

设置配色方案

chrome-devtools-axi emulate --color-scheme dark

Network throttling

网络节流

chrome-devtools-axi emulate --network "Slow 3G"

CPU throttling (1-20)

CPU节流（1-20）

chrome-devtools-axi emulate --cpu 4

Set geolocation

设置地理位置

chrome-devtools-axi emulate --geolocation "37.7749x-122.4194"

Custom user agent

自定义用户代理

chrome-devtools-axi emulate --user-agent "CustomBot/1.0"

Combine options

组合多个模拟选项

chrome-devtools-axi emulate --viewport "390x844x3,mobile" --color-scheme dark --network "Fast 3G"

undefined

chrome-devtools-axi emulate --viewport "390x844x3,mobile" --color-scheme dark --network "Fast 3G"

undefined

DevTools Debugging

DevTools 调试

Console Messages

控制台消息

bash

undefined

bash

undefined

List all console messages

列出所有控制台消息

chrome-devtools-axi console

Filter by type

按类型过滤

chrome-devtools-axi console --type error chrome-devtools-axi console --type warn

Pagination

分页显示

chrome-devtools-axi console --limit 10 --page 2

Get specific message

获取指定消息

chrome-devtools-axi console-get <id>


Available types: `log`, `debug`, `info`, `error`, `warn`, `dir`, `dirxml`, `table`, `trace`, `clear`, `assert`, `all`

chrome-devtools-axi console-get <id>


支持的类型：`log`, `debug`, `info`, `error`, `warn`, `dir`, `dirxml`, `table`, `trace`, `clear`, `assert`, `all`

Network Requests

网络请求

bash

undefined

bash

undefined

List network requests

列出网络请求

chrome-devtools-axi network

Filter by type

按类型过滤

chrome-devtools-axi network --type xhr chrome-devtools-axi network --type fetch

Get specific request

获取指定请求

chrome-devtools-axi network-get <id>

Save response body

保存响应体

chrome-devtools-axi network-get <id> --response-file response.json

Save request body

保存请求体

chrome-devtools-axi network-get <id> --request-file request.json


Available types: `document`, `stylesheet`, `image`, `media`, `font`, `script`, `xhr`, `fetch`, `websocket`, `manifest`, `other`, `all`

chrome-devtools-axi network-get <id> --request-file request.json


支持的类型：`document`, `stylesheet`, `image`, `media`, `font`, `script`, `xhr`, `fetch`, `websocket`, `manifest`, `other`, `all`

Performance

性能分析

Lighthouse Audits

Lighthouse 审计

bash

undefined

bash

undefined

Run Lighthouse audit

运行Lighthouse审计

chrome-devtools-axi lighthouse

Mobile device

针对移动端设备

chrome-devtools-axi lighthouse --device mobile

Snapshot mode (current state)

快照模式（基于当前页面状态）

chrome-devtools-axi lighthouse --mode snapshot

Save reports to directory

将报告保存至指定目录

chrome-devtools-axi lighthouse --output-dir ./reports

undefined

chrome-devtools-axi lighthouse --output-dir ./reports

undefined

Performance Tracing

性能追踪

bash

undefined

bash

undefined

Start trace

开始追踪

chrome-devtools-axi perf-start

Start without reload

不刷新页面直接开始追踪

chrome-devtools-axi perf-start --no-reload

Stop and save trace

停止追踪并保存结果

chrome-devtools-axi perf-stop --file trace.json

Analyze performance insight

分析性能指标

chrome-devtools-axi perf-insight lcp "Largest Contentful Paint"

undefined

chrome-devtools-axi perf-insight lcp "Largest Contentful Paint"

undefined

Heap Snapshots

堆快照

bash

undefined

bash

undefined

Capture heap snapshot

捕获堆快照

chrome-devtools-axi heap memory.heapsnapshot

undefined

chrome-devtools-axi heap memory.heapsnapshot

undefined

Configuration

配置

Environment Variables

环境变量

bash

undefined

bash

undefined

Change bridge server port (default: 9224)

修改桥接服务器端口（默认：9224）

export CHROME_DEVTOOLS_AXI_PORT=9225

Connect to existing Chrome instance (HTTP/HTTPS)

连接到已有的Chrome实例（HTTP/HTTPS）

export CHROME_DEVTOOLS_AXI_BROWSER_URL=http://127.0.0.1:9222

Connect via WebSocket directly

直接通过WebSocket连接

export CHROME_DEVTOOLS_AXI_BROWSER_URL=wss://cluster.example/launch

WebSocket authentication headers (JSON)

WebSocket认证头（JSON格式）

export CHROME_DEVTOOLS_AXI_WS_HEADERS='{"Authorization":"Bearer token"}'

Disable session hook auto-install

禁用会话钩子自动安装

export CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1

undefined

export CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1

undefined

State Files

状态文件

State stored in

~/.chrome-devtools-axi/

:

```
bridge.pid
```
— Running bridge PID and port
```
snapshot-generation
```
— Staleness detection counter

状态信息存储在

~/.chrome-devtools-axi/

目录下：

```
bridge.pid
```
— 运行中的桥接服务PID和端口
```
snapshot-generation
```
— 过期检测计数器

Common Patterns

常见使用模式

Login Flow

登录流程

bash

undefined

bash

undefined

Navigate and fill login form

导航至登录页面并填写表单

chrome-devtools-axi open https://app.example.com/login chrome-devtools-axi fillform @g1:1=user@example.com @g1:2=password chrome-devtools-axi click @g1:3 chrome-devtools-axi wait "Dashboard" chrome-devtools-axi snapshot

undefined

chrome-devtools-axi open https://app.example.com/login chrome-devtools-axi fillform @g1:1=user@example.com @g1:2=password chrome-devtools-axi click @g1:3 chrome-devtools-axi wait "Dashboard" chrome-devtools-axi snapshot

undefined

Form Scraping

表单数据提取

bash

undefined

bash

undefined

Extract form data with JavaScript

通过JavaScript提取表单数据

chrome-devtools-axi eval "() => { const form = document.querySelector('form'); const data = new FormData(form); return Object.fromEntries(data.entries()); }"

undefined

chrome-devtools-axi eval "() => { const form = document.querySelector('form'); const data = new FormData(form); return Object.fromEntries(data.entries()); }"

undefined

Multi-Page Workflow

多页面工作流

typescript

// In TypeScript/Node.js
import { execSync } from 'child_process';

function runCommand(cmd: string): string {
  return execSync(`chrome-devtools-axi ${cmd}`, { encoding: 'utf-8' });
}

// Navigate and extract data
runCommand('open https://example.com');
const title = runCommand('eval "document.title"');

// Take screenshot
runCommand('screenshot page.png');

// Fill and submit form
runCommand('fill @g1:1 "search term"');
runCommand('press Enter');
runCommand('wait 2000');

// Extract results
const results = runCommand('eval "() => [...document.querySelectorAll(\'.result\')].map(el => el.textContent)"');

typescript

// TypeScript/Node.js 示例
import { execSync } from 'child_process';

function runCommand(cmd: string): string {
  return execSync(`chrome-devtools-axi ${cmd}`, { encoding: 'utf-8' });
}

// 导航并提取数据
runCommand('open https://example.com');
const title = runCommand('eval "document.title"');

// 截取页面截图
runCommand('screenshot page.png');

// 填写并提交表单
runCommand('fill @g1:1 "search term"');
runCommand('press Enter');
runCommand('wait 2000');

// 提取结果
const results = runCommand('eval "() => [...document.querySelectorAll(\'.result\')].map(el => el.textContent)"');

Handling Dynamic Content

动态内容处理

bash

undefined

bash

undefined

Wait for element to appear, then interact

等待元素出现后再进行交互

chrome-devtools-axi open https://spa.example.com chrome-devtools-axi wait "Loading complete" chrome-devtools-axi snapshot chrome-devtools-axi click @g2:5

undefined

chrome-devtools-axi open https://spa.example.com chrome-devtools-axi wait "Loading complete" chrome-devtools-axi snapshot chrome-devtools-axi click @g2:5

undefined

Testing Responsive Design

响应式设计测试

bash

undefined

bash

undefined

Test mobile layout

测试移动端布局

chrome-devtools-axi emulate --viewport "390x844x3,mobile" chrome-devtools-axi open https://example.com chrome-devtools-axi screenshot mobile.png

Test desktop layout

测试桌面端布局

chrome-devtools-axi resize 1920 1080 chrome-devtools-axi snapshot chrome-devtools-axi screenshot desktop.png

undefined

chrome-devtools-axi resize 1920 1080 chrome-devtools-axi snapshot chrome-devtools-axi screenshot desktop.png

undefined

Understanding Refs and Staleness

理解引用与过期机制

Refs use a generation prefix (

g<N>:

) that increments with each snapshot. If you capture a snapshot at generation 1, get ref

@g1:5

, then the page re-renders and moves to generation 2, attempting to use

@g1:5

will fail with

STALE_REF

error.

Agent pattern:

Capture snapshot
Extract refs
Attempt action with ref
If
```
STALE_REF
```
error, re-snapshot and retry with new ref

bash

undefined

引用包含生成版本前缀（

g<N>:

），每次快照都会递增版本号。如果在版本1的快照中获取到引用

@g1:5

，之后页面重新渲染进入版本2，此时使用

@g1:5

会触发

STALE_REF

错误。

Agent使用模式：

捕获快照
提取引用
使用引用执行操作
如果触发
```
STALE_REF
```
错误，重新捕获快照并使用新引用重试

bash

undefined

First snapshot

首次捕获快照

chrome-devtools-axi snapshot

Output shows: uid=g1:1 link "Click here"

输出显示：uid=g1:1 link "Click here"

Page changes, generation bumps to g2

页面更新，版本号升级为g2

chrome-devtools-axi click @g1:1

Error: STALE_REF

错误：STALE_REF

Re-snapshot to get fresh refs

重新捕获快照获取最新引用

chrome-devtools-axi snapshot

Output shows: uid=g2:3 link "Click here"

输出显示：uid=g2:3 link "Click here"

chrome-devtools-axi click @g2:3

Success

操作成功

undefined

undefined

Troubleshooting

故障排查

Bridge Not Starting

桥接服务无法启动

bash

undefined

bash

undefined

Manually stop and restart bridge

手动停止并重启桥接服务

chrome-devtools-axi stop chrome-devtools-axi start

undefined

chrome-devtools-axi stop chrome-devtools-axi start

undefined

Port Conflicts

端口冲突

bash

undefined

bash

undefined

Use different port

使用其他端口

export CHROME_DEVTOOLS_AXI_PORT=9999 chrome-devtools-axi open https://example.com

undefined

export CHROME_DEVTOOLS_AXI_PORT=9999 chrome-devtools-axi open https://example.com

undefined

Stale Refs

引用过期

Always use refs exactly as printed in snapshot output. If you get

STALE_REF

, capture a new snapshot.

请严格按照快照输出内容使用引用。如果出现

STALE_REF

错误，重新捕获快照即可。

Element Not Found

元素未找到

If

uid

is valid but element doesn't respond:

Check if element is visible (scroll into view)
Wait for page to finish loading
Use
```
chrome-devtools-axi wait
```
before interaction

如果

uid

有效但无响应：

检查元素是否可见（可滚动至视图内）
等待页面加载完成
交互前使用
```
chrome-devtools-axi wait
```
命令

Full Output Needed

需要完整输出

bash

undefined

bash

undefined

Disable truncation for complete data

禁用截断以获取完整数据

chrome-devtools-axi snapshot --full chrome-devtools-axi console --full

undefined

chrome-devtools-axi snapshot --full chrome-devtools-axi console --full

undefined

Debugging JavaScript Eval

JavaScript执行调试

bash

undefined

bash

undefined

Check for errors in console

检查控制台中的错误信息

chrome-devtools-axi console --type error

Test simple eval first

先测试简单的执行命令

chrome-devtools-axi eval "2 + 2"

Use arrow function for complex logic

复杂逻辑使用箭头函数

chrome-devtools-axi eval "() => { console.log('debug'); return 42; }"

undefined

chrome-devtools-axi eval "() => { console.log('debug'); return 42; }"

undefined

Example: E2E Testing Workflow

示例：端到端测试工作流

bash

#!/bin/bash

bash

#!/bin/bash

Start fresh session

启动全新会话

chrome-devtools-axi stop chrome-devtools-axi start

Navigate to app

导航至应用

chrome-devtools-axi open https://app.example.com

Login

Take baseline screenshot

截取基准截图

chrome-devtools-axi screenshot baseline.png

Navigate to feature

导航至功能页面

chrome-devtools-axi click @g2:10 chrome-devtools-axi wait "Feature Page"

Interact with feature

与功能交互

chrome-devtools-axi fill @g3:5 "test data" chrome-devtools-axi click @g3:6

Verify result

验证结果

chrome-devtools-axi wait "Success" chrome-devtools-axi snapshot --full > result.txt

Capture performance

捕获性能数据

chrome-devtools-axi lighthouse --output-dir ./reports

Cleanup

清理会话

chrome-devtools-axi stop

undefined

chrome-devtools-axi stop

undefined

Best Practices for Agents

Agent最佳实践

Always re-snapshot after page changes — Don't reuse refs across navigation or mutations
Use combined operations —
```
open
```
gives snapshot automatically, reducing round-trips
Check help hints — Every response includes suggested next steps
Use
--full
sparingly — Default truncation saves tokens; only expand when needed
Prefer
fillform
over multiple
fill
— Batch form operations when possible
Wait strategically — Use
```
wait <text>
```
instead of arbitrary timeouts when possible
Leverage eval for extraction — JavaScript eval is more efficient than scraping via snapshots

页面更新后重新捕获快照 — 不要跨导航或页面变更复用引用
使用组合操作 —
```
open
```
命令会自动返回快照，减少往返请求
查看帮助提示 — 每个响应都包含建议的下一步操作
谨慎使用
--full
参数 — 默认截断可节省令牌，仅在需要时展开完整内容
优先使用
fillform
而非多次
fill
— 批量处理表单操作
策略性等待 — 尽可能使用
```
wait <text>
```
替代固定时长的超时等待
利用执行命令提取数据 — JavaScript执行比快照提取更高效

chrome-devtools-axi-browser-automation

Original

Translation

chrome-devtools-axi Browser Automation

chrome-devtools-axi 浏览器自动化

Overview

概述

Installation

安装

Architecture

架构

Core Commands

核心命令

Navigation and Snapshot

导航与快照

Navigate to a URL and capture accessibility tree

导航至指定URL并捕获可访问性树

Capture current page state

捕获当前页面状态

Navigate back

返回上一页

Scroll page

滚动页面

Wait for time or content

等待指定时长或内容加载完成

Element Interaction

元素交互

Click an element

点击元素

Fill a form field

填写表单字段

Fill multiple fields at once

批量填写多个字段

Type text at current focus

在当前焦点位置输入文本

Press keyboard key

按下键盘按键

Hover over element

悬停在元素上

Drag and drop

拖拽操作

Upload file

上传文件

Handle browser dialogs

处理浏览器对话框

Screenshots

截图

Save screenshot to file

将截图保存至文件

Capture specific element

捕获指定元素的截图

Full-page screenshot

全页面截图

Specify format

指定截图格式

JavaScript Evaluation

JavaScript 执行

Evaluate expression (auto-wrapped)

执行表达式（自动包装）

Execute function

执行函数

Multi-statement logic

多语句逻辑执行

Multi-Step Scripts

多步骤脚本

Execute script from stdin

从标准输入执行脚本

Page Management

页面管理

List all tabs

列出所有标签页

Open new tab

打开新标签页

Open in background

在后台打开新标签页

Switch tab

切换标签页

Close tab

关闭标签页

Resize viewport