Skip to content

Commit bc8c22a

Browse files
22348392234839
committed
更新文档
1 parent 353cc44 commit bc8c22a

3 files changed

Lines changed: 95 additions & 181 deletions

File tree

‎README.md‎

Lines changed: 26 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,7 @@ A Vite plugin that lets AI agents (Claude Code, Cursor, etc.) **see, interact wi
1616
- **Zero Config** — Drop-in Vite plugin, works with any Vite project (Vue, React, vanilla JS, etc.)
1717
- **Compact Snapshot** — Page state serialized into ~80 lines of text, optimized for LLM context windows
1818
- **Multi-Instance** — Each browser tab is independently tracked, switch freely with `PILOT_INSTANCE`
19-
- **Dual Channel** — File I/O CLI (`bin/pilot.js`) + HTTP API (`/__pilot/*`)
20-
- **Auto Reload** — Browser auto-refreshes when dev server restarts (v132)
19+
- **Auto Reload** — Browser auto-refreshes when dev server restarts
2120
- **Vue/React Aware** — `typeByPlaceholder` dispatches input events for v-model compatibility
2221

2322
## Installation
@@ -48,105 +47,42 @@ pnpm dev
4847
# Open http://localhost:5173 in your browser
4948
```
5049

51-
### 3. Use the CLI to interact
50+
### 3. Configure your AI agent
5251

53-
```bash
54-
# See the current page state (compact snapshot)
55-
node bin/pilot.js page
56-
57-
# Execute JS and see the result + updated page
58-
node bin/pilot.js run '__pilot_clickByText("Submit")' page
59-
60-
# Execute JS and see console logs
61-
node bin/pilot.js run 'document.title' logs
62-
```
63-
64-
That's it! The agent can now read the compact snapshot, decide what to do, execute actions, and verify results — all in a single tool call.
52+
Copy the following into your AI agent's instruction file:
6553

66-
## Compact Snapshot Format
67-
68-
The page is serialized into a compact text format designed for LLM consumption:
69-
70-
```
71-
# url: http://localhost:5173/
72-
# title: My App
73-
sections Overview|Settings|Users
74-
button #3 Save|#4 Cancel
75-
input #10 ph:Username
76-
select #12 check=1 <Admin|Editor|Viewer>
77-
checkbox check=agree I agree
78-
textarea #15 ph:Description...
79-
th Name|Role|Actions
80-
tr Alice|Admin|Delete
81-
```
54+
**Claude Code** → paste into project `CLAUDE.md`:
8255

83-
Format: `tag#idx[val=V][check=N][type:T][ph=P][disabled] text`
56+
```markdown
57+
<!-- vite-plugin-pilot:start -->
58+
# vite-plugin-pilot
8459

85-
- `#idx` — Element index for precise operations: `__pilot_click(10)`
86-
- `[val=V]` — Current value
87-
- `[check=N]` — Selected option index (0-based)
88-
- `[ph=P]` — Placeholder text
89-
- `[disabled]` — Element is disabled
60+
辅助 AI agent 测试浏览器页面。通过文件 I/O 在浏览器执行 JS。`pnpm dev` 启动，浏览器打开页面即可使用。
9061

91-
## CLI Reference
62+
## 工作流
9263

9364
```bash
94-
node bin/pilot.js page # View page (compact snapshot)
95-
node bin/pilot.js page cached # View cached snapshot (0.03s, no browser round-trip)
96-
node bin/pilot.js run 'code' page # Execute JS + view result + page (one step, recommended)
97-
node bin/pilot.js run 'code' logs # Execute JS + view result + logs
98-
node bin/pilot.js logs # View recent console logs
99-
node bin/pilot.js status # List connected browser tabs
100-
101-
# Target a specific tab
102-
PILOT_INSTANCE=xxxxxxxx node bin/pilot.js page
65+
npx pilot page # 看页面（compact 格式）
66+
npx pilot run '代码' page # 操作+看结果（一步完成）
67+
npx pilot run '代码' logs # 操作+看日志
68+
npx pilot logs # 看最近日志
69+
npx pilot status # 查看连接的 tab 列表
70+
npx pilot help # 查看辅助函数列表
10371
```
10472

105-
**Recommended pattern**: `page` → read snapshot → `run 'code' page` → verify. Prefer `run 'code' page` (one step) to avoid two ~5s polling delays.
106-
107-
## Helper Functions
108-
109-
### Text Matching (recommended, refreshes element references each time)
110-
111-
| Function | Description |
112-
|----------|-------------|
113-
| `__pilot_clickByText(text, nth?)` | Click element by text content |
114-
| `__pilot_typeByPlaceholder(ph, value)` | Type into input (triggers input events for v-model) |
115-
| `__pilot_setValueByPlaceholder(ph, value, nth?)` | Set input value |
116-
| `__pilot_selectValueByText(text, nth?)` | Select dropdown option |
117-
| `__pilot_checkByText(text, nth?)` | Check checkbox |
118-
| `__pilot_findByText(text)` | Find elements → `[{idx, tag, text}]` |
119-
| `__pilot_waitFor(text, timeout?, disappear?)` | Wait for text to appear/disappear |
120-
| `__pilot_waitEnabled(text, timeout?)` | Wait for disabled element to become enabled |
73+
**使用模式**：`page` 看 compact → 读取 `#idx` 或用文本匹配 → `run '操作代码' page` → 验证结果。优先用 `run 'code' page` 一步完成（避免两次 ~5s 轮询延迟）。
12174

122-
### Index-Based (read `#N` from compact)
123-
124-
| Function | Description |
125-
|----------|-------------|
126-
| `__pilot_click(i)` | Click element by index |
127-
| `__pilot_setValue(i, value)` | Set input value |
128-
| `__pilot_type(i, value)` | Type into input by index |
129-
| `__pilot_dblclick(i)` | Double-click element |
130-
| `__pilot_hover(i)` | Hover over element |
131-
132-
### Other
133-
134-
| Function | Description |
135-
|----------|-------------|
136-
| `__pilot_wait(ms)` | Wait for milliseconds |
137-
| `__pilot_snapshot()` | Get full JSON snapshot |
138-
| `__pilot_scrollIntoView(i)` | Scroll element into view |
139-
| `__pilot_getRect(i)` | Get element bounding rect |
140-
| `__pilot_checkMultipleByText([t1, t2])` | Check multiple checkboxes |
141-
| `__pilot_uncheckByText(text, nth?)` | Uncheck checkbox |
142-
| `__pilot_keydownByText(text, key)` | Trigger keydown on element |
75+
**关键注意**：
76+
- **同一 exec 完成相关操作**（填写+提交），跨 exec Vue/React 状态可能丢失
77+
- 多步操作间 `await __pilot_wait(0)` 让 Vue scheduler 处理响应式更新
78+
- **始终用 `typeByPlaceholder`**：Vue/React v-model 需要 input 事件，`type` 触发 input 事件，`setValue` 只改 DOM
79+
- `page cached` 读缓存（0.03s），不需要最新状态时用
80+
<!-- vite-plugin-pilot:end -->
81+
```
14382

144-
## Important Notes
83+
**Cursor / Other agents** → paste into `.cursorrules` or project rules, content same as above.
14584

146-
- **Complete related operations in one exec** (fill + submit) — Vue/React state may be lost across execs
147-
- **Always use `typeByPlaceholder`** over `setValueByPlaceholder` — Vue/React v-model needs input events
148-
- **Use `await __pilot_wait(0)`** between multi-step operations to let Vue scheduler process reactive updates
149-
- **Use `__pilot_waitFor`** instead of `__pilot_wait(N)` — poll-based condition checking is more reliable than guessing wait times
85+
That's it! The agent can now autonomously develop and verify features for you.
15086

15187
## How It Works
15288

@@ -166,7 +102,7 @@ PILOT_INSTANCE=xxxxxxxx node bin/pilot.js page
166102

167103
## Playground
168104

169-
The project includes a multi-framework playground for dogfooding:
105+
The project includes a multi-framework playground:
170106

171107
```bash
172108
pnpm dev

‎README_zh.md‎

Lines changed: 37 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,14 @@
44
55
一个 Vite 插件，让 AI Agent（Claude Code、Cursor 等）通过紧凑快照格式和简单的 JS 辅助函数**查看、交互和验证**浏览器页面。无需 Puppeteer、无需 Playwright — 纯文件 I/O。
66

7-
English | **[English](./README.md)**
7+
English | **[简体中文](./README_zh.md)**
88

99
## 特性
1010

1111
- **零配置** — Vite 插件即插即用，支持任何 Vite 项目（Vue、React、原生 JS 等）
1212
- **紧凑快照** — 页面状态序列化为 ~80 行文本，针对 LLM 上下文窗口优化
1313
- **多实例** — 每个浏览器 tab 独立追踪，通过 `PILOT_INSTANCE` 自由切换
14-
- **双通道** — 文件 I/O CLI（`bin/pilot.js`）+ HTTP API（`/__pilot/*`）
15-
- **自动刷新** — Dev server 重启后浏览器自动刷新（v132）
14+
- **自动刷新** — Dev server 重启后浏览器自动刷新
1615
- **Vue/React 兼容** — `typeByPlaceholder` 触发 input 事件，兼容 v-model
1716

1817
## 安装
@@ -43,105 +42,42 @@ pnpm dev
4342
# 在浏览器中打开 http://localhost:5173
4443
```
4544

46-
### 3. 使用 CLI 交互
45+
### 3. 配置 AI Agent
4746

48-
```bash
49-
# 查看当前页面状态（紧凑快照）
50-
node bin/pilot.js page
51-
52-
# 执行 JS 并查看结果 + 更新后的页面
53-
node bin/pilot.js run '__pilot_clickByText("提交")' page
54-
55-
# 执行 JS 并查看控制台日志
56-
node bin/pilot.js run 'document.title' logs
57-
```
58-
59-
完成！Agent 现在可以读取紧凑快照、决定操作、执行动作并验证结果 — 全部在一次 tool call 中完成。
60-
61-
## 紧凑快照格式
47+
将以下指令复制到 AI Agent 的配置文件中：
6248

63-
页面被序列化为针对 LLM 消费优化的紧凑文本格式：
49+
**Claude Code** → 粘贴到项目 `CLAUDE.md`：
6450

65-
```
66-
# url: http://localhost:5173/
67-
# title: My App
68-
sections 概览|设置|用户
69-
button #3 保存|#4 取消
70-
input #10 ph:用户名
71-
select #12 check=1 <管理员|编辑|查看者>
72-
checkbox check=agree 我同意
73-
textarea #15 ph:描述...
74-
th 姓名|角色|操作
75-
tr Alice|管理员|删除
76-
```
77-
78-
格式：`tag#idx[val=V][check=N][type:T][ph=P][disabled] text`
51+
```markdown
52+
<!-- vite-plugin-pilot:start -->
53+
# vite-plugin-pilot
7954

80-
- `#idx` — 元素索引，用于精确操作：`__pilot_click(10)`
81-
- `[val=V]` — 当前值
82-
- `[check=N]` — 已选中的选项索引（从 0 开始）
83-
- `[ph=P]` — 占位符文本
84-
- `[disabled]` — 元素已禁用
55+
辅助 AI agent 测试浏览器页面。通过文件 I/O 在浏览器执行 JS。`pnpm dev` 启动，浏览器打开页面即可使用。
8556

86-
## CLI 参考
57+
## 工作流
8758

8859
```bash
89-
node bin/pilot.js page # 查看页面（紧凑快照）
90-
node bin/pilot.js page cached # 查看缓存快照（0.03s，无浏览器轮询）
91-
node bin/pilot.js run '代码' page # 执行 JS + 查看结果 + 页面（一步完成，推荐）
92-
node bin/pilot.js run '代码' logs # 执行 JS + 查看结果 + 日志
93-
node bin/pilot.js logs # 查看最近控制台日志
94-
node bin/pilot.js status # 列出已连接的浏览器 tab
95-
96-
# 指定目标 tab
97-
PILOT_INSTANCE=xxxxxxxx node bin/pilot.js page
60+
npx pilot page # 看页面（compact 格式）
61+
npx pilot run '代码' page # 操作+看结果（一步完成）
62+
npx pilot run '代码' logs # 操作+看日志
63+
npx pilot logs # 看最近日志
64+
npx pilot status # 查看连接的 tab 列表
65+
npx pilot help # 查看辅助函数列表
9866
```
9967

100-
**推荐模式**：`page` → 读取快照 → `run '代码' page` → 验证结果。优先使用 `run 'code' page`（一步完成，避免两次 ~5s 轮询延迟）。
101-
102-
## 辅助函数
103-
104-
### 文本匹配（推荐，每次搜索刷新元素引用）
68+
**使用模式**：`page` 看 compact → 读取 `#idx` 或用文本匹配 → `run '操作代码' page` → 验证结果。优先用 `run 'code' page` 一步完成（避免两次 ~5s 轮询延迟）。
10569

106-
| 函数 | 说明 |
107-
|------|------|
108-
| `__pilot_clickByText(text, nth?)` | 按文本内容点击元素 |
109-
| `__pilot_typeByPlaceholder(ph, value)` | 在输入框中输入（触发 input 事件，兼容 v-model） |
110-
| `__pilot_setValueByPlaceholder(ph, value, nth?)` | 设置输入框值 |
111-
| `__pilot_selectValueByText(text, nth?)` | 选择下拉框选项 |
112-
| `__pilot_checkByText(text, nth?)` | 勾选复选框 |
113-
| `__pilot_findByText(text)` | 查找元素 → `[{idx, tag, text}]` |
114-
| `__pilot_waitFor(text, timeout?, disappear?)` | 等待文本出现/消失 |
115-
| `__pilot_waitEnabled(text, timeout?)` | 等待禁用元素变为可用 |
116-
117-
### 按索引（从 compact 读取 `#N`）
118-
119-
| 函数 | 说明 |
120-
|------|------|
121-
| `__pilot_click(i)` | 按索引点击元素 |
122-
| `__pilot_setValue(i, value)` | 按索引设置值 |
123-
| `__pilot_type(i, value)` | 按索引输入 |
124-
| `__pilot_dblclick(i)` | 双击元素 |
125-
| `__pilot_hover(i)` | 悬停元素 |
126-
127-
### 其他
128-
129-
| 函数 | 说明 |
130-
|------|------|
131-
| `__pilot_wait(ms)` | 等待毫秒 |
132-
| `__pilot_snapshot()` | 获取完整 JSON 快照 |
133-
| `__pilot_scrollIntoView(i)` | 滚动元素到视口 |
134-
| `__pilot_getRect(i)` | 获取元素位置 |
135-
| `__pilot_checkMultipleByText([t1, t2])` | 勾选多个复选框 |
136-
| `__pilot_uncheckByText(text, nth?)` | 取消勾选 |
137-
| `__pilot_keydownByText(text, key)` | 在元素上触发按键事件 |
70+
**关键注意**：
71+
- **同一 exec 完成相关操作**（填写+提交），跨 exec Vue/React 状态可能丢失
72+
- 多步操作间 `await __pilot_wait(0)` 让 Vue scheduler 处理响应式更新
73+
- **始终用 `typeByPlaceholder`**：Vue/React v-model 需要 input 事件，`type` 触发 input 事件，`setValue` 只改 DOM
74+
- `page cached` 读缓存（0.03s），不需要最新状态时用
75+
<!-- vite-plugin-pilot:end -->
76+
```
13877

139-
## 注意事项
78+
**Cursor / 其他 Agent** → 粘贴到 `.cursorrules` 或项目规则中，内容同上。
14079

141-
- **在同一 exec 中完成相关操作**（填写+提交）— 跨 exec 时 Vue/React 状态可能丢失
142-
- **始终使用 `typeByPlaceholder`** 而非 `setValueByPlaceholder` — Vue/React v-model 需要 input 事件
143-
- **多步操作间使用 `await __pilot_wait(0)`** — 让 Vue scheduler 处理响应式更新
144-
- **使用 `__pilot_waitFor`** 替代 `__pilot_wait(N)` — 轮询检测比猜测等待时间更可靠
80+
完成！Agent 现在可以自行帮你开发并测试验证功能是否正确了。
14581

14682
## 工作原理
14783

@@ -158,6 +94,17 @@ PILOT_INSTANCE=xxxxxxxx node bin/pilot.js page
15894
3. 浏览器将结果写入 `result.txt`，紧凑快照写入 `compact-snapshot.txt`
15995
4. Agent 一次 tool call 读取结果 + 快照
16096

97+
## Playground
98+
99+
项目包含多框架 playground：
100+
101+
```bash
102+
pnpm dev
103+
# /vue/ — Vue 3 playground
104+
# /react/ — React playground
105+
# /html/ — 原生 JS playground
106+
```
107+
161108
## 许可证
162109

163110
MIT

‎bin/pilot.js‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -300,9 +300,40 @@ async function main() {
300300
page [cached] 读取页面快照（默认实时采集，cached=读缓存）
301301
logs 最近一次 exec 的控制台日志
302302
status 文件系统状态诊断
303+
help 显示此帮助信息
303304
304305
环境变量: PILOT_INSTANCE
305-
目录探测: cwd`)
306+
目录探测: cwd
307+
308+
--- 浏览器端辅助函数 (在 run 中执行) ---
309+
310+
文本匹配（推荐）:
311+
__pilot_clickByText(text, nth?) 按文本点击元素
312+
__pilot_typeByPlaceholder(ph, value) 在输入框输入（触发 input 事件）
313+
__pilot_setValueByPlaceholder(ph, value, nth?) 设置输入框值
314+
__pilot_selectValueByText(text, nth?) 选择下拉框选项
315+
__pilot_checkByText(text, nth?) 勾选复选框
316+
__pilot_findByText(text) 查找元素 → [{idx, tag, text}]
317+
__pilot_waitFor(text, timeout?, disappear?) 等待文本出现/消失
318+
__pilot_waitEnabled(text, timeout?) 等待禁用元素变为可用
319+
320+
按索引（compact 中的 #N）:
321+
__pilot_click(i) 点击元素
322+
__pilot_setValue(i, v) 设置值
323+
__pilot_type(i, v) 输入值
324+
__pilot_dblclick(i) 双击元素
325+
__pilot_hover(i) 悬停元素
326+
327+
其他:
328+
__pilot_wait(ms) 等待毫秒
329+
__pilot_snapshot() 获取完整 JSON 快照
330+
__pilot_scrollIntoView(i) 滚动到元素
331+
__pilot_getRect(i) 获取元素位置
332+
__pilot_checkMultipleByText([t1,t2]) 勾选多个复选框
333+
__pilot_uncheckByText(text, nth?) 取消勾选
334+
__pilot_keydownByText(text, key) 在元素上触发按键
335+
336+
compact snapshot 格式: tag#idx[val=V][check=N][type=T][ph=P][disabled] text`)
306337
break
307338
}
308339
}

0 commit comments

Comments
 (0)