Skip to content

Commit f737afb

Browse files
libilibi
committed
update README
1 parent ba34391 commit f737afb

2 files changed

Lines changed: 196 additions & 12 deletions

File tree

‎README-CN.md‎

Lines changed: 104 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,33 @@
1+
<p align="center">
2+
<h1 align="center">kbr (ko-browser)</h1>
3+
<p align="center">一个简单、快速、节省 Token 的 AI Agent 浏览器工具，支持 CLI 和 Go Library。</p>
4+
</p>
5+
6+
<p align="center">
7+
<a href="README.md">English</a> •
8+
<a href="#-快速开始">快速开始</a> •
9+
<a href="#-命令速查">命令速查</a> •
10+
<a href="#agent-notes-cn">Agent 阅读说明</a> •
11+
<a href="docs/snapshot-format.md">快照格式规范</a>
12+
</p>
13+
14+
<p align="center">
15+
<a href="https://github.com/libi/ko-browser/releases"><img src="https://img.shields.io/github/v/release/libi/ko-browser?style=flat-square" alt="Release"></a>
16+
<a href="https://github.com/libi/ko-browser/actions"><img src="https://img.shields.io/github/actions/workflow/status/libi/ko-browser/ci.yml?style=flat-square" alt="CI"></a>
17+
<a href="https://pkg.go.dev/github.com/libi/ko-browser"><img src="https://pkg.go.dev/badge/github.com/libi/ko-browser.svg" alt="Go Reference"></a>
18+
<a href="https://goreportcard.com/report/github.com/libi/ko-browser"><img src="https://goreportcard.com/badge/github.com/libi/ko-browser?style=flat-square" alt="Go Report Card"></a>
19+
</p>
120

221
---
322

4-
<a name="-中文文档"></a>
23+
## 简介
524

6-
# 🇨🇳 中文文档
25+
**kbr** (ko-browser) 是一个使用 Go 开发的浏览器自动化工具，专为 AI Agent 设计。它同时提供两种使用方式：
726

8-
## 简介
27+
- **CLI 命令行工具**，适合 shell 驱动的 agent 工作流
28+
- **Go Library 库**，适合嵌入到 Agent Runtime、工具层或服务端程序中
929

10-
**kbr** (ko-browser) 是简单,快速,节省Token的浏览器自动化工具，使用Go语言开发, 专为 AI Agent 设计。它同时提供 **CLI 命令行工具** 和 **Go Library 库**，自定义的无障碍树快照格式比同类工具**节省 46% 以上 token**。
30+
它的自定义无障碍树快照格式，相比更冗长的同类输出可**节省 46% 以上 token**。
1131

1232
### ✨ 核心优势
1333

@@ -17,14 +37,22 @@
1737
- ⚡ **启动飞快** — ~50ms（Go 二进制）对比 ~500ms（Node.js 方案）
1838
- 🔢 **简洁的元素引用** — `click 5`
1939
- 🔍 **可选 OCR** — 通过 `-tags=ocr` 编译启用 Tesseract，处理图片密集页面
20-
- 🌐 **~86 个命令** — 完整对标 agent-browser v0.19.0
40+
- 🌐 **~86 个命令** — 覆盖常见浏览器自动化工作流
2141

2242
> 📖 阅读完整的[快照格式规范](docs/snapshot-format.md)，了解详细的设计决策、BNF 语法和示例。([English Version](docs/snapshot-format-en.md))
2343
2444
---
2545

2646
## 📦 安装
2747

48+
### 安装方式选择
49+
50+
| 使用场景 | 推荐方式 | 说明 |
51+
|---------|----------|------|
52+
| macOS 本地使用 | Homebrew | 默认安装带 OCR 的版本，并自动拉取 `tesseract` |
53+
| Linux / macOS 手动部署 | GitHub Releases | 下载预编译压缩包，并确保系统里有 Tesseract 运行时 |
54+
| Go 项目集成或自定义构建 | 源码编译 | 适合把 `kbr` 集成进自己的工具链或服务中 |
55+
2856
### Homebrew
2957

3058
```bash
@@ -76,10 +104,32 @@ kbr install # 检查并下载 Chromium
76104
kbr install --with-deps # 同时安装系统依赖（Linux）
77105
```
78106

107+
### 运行依赖
108+
109+
- 必须有可用的 Chrome 或 Chromium；如果本机没有，先执行 `kbr install`
110+
- 带 OCR 的发布版本依赖宿主机上的 Tesseract 运行时库
111+
- 在 Linux CI 或受限沙箱环境中，Chrome 可能需要无沙箱模式等兼容参数才能启动
112+
79113
---
80114

81115
## 🚀 快速开始
82116

117+
### Agent 常用循环
118+
119+
这是最常见的 shell 驱动 Agent 工作流：
120+
121+
```bash
122+
kbr open https://example.com
123+
kbr snapshot
124+
kbr click 5
125+
kbr type 8 "hello world"
126+
kbr press Enter
127+
kbr wait load
128+
kbr get text 12
129+
```
130+
131+
思路就是：先 `snapshot` 读页面结构，再根据数字 ID 操作元素；页面变化后重新获取快照。
132+
83133
### CLI 使用
84134

85135
```bash
@@ -145,6 +195,16 @@ func main() {
145195

146196
## 📖 命令速查
147197

198+
### 常见任务入口
199+
200+
| 目标 | 常用命令 |
201+
|------|----------|
202+
| 打开页面并读取信息 | `open`、`snapshot`、`get title`、`get url` |
203+
| 表单和交互操作 | `click`、`type`、`fill`、`select`、`check`、`press` |
204+
| 等待页面变化 | `wait load`、`wait selector`、`wait text`、`wait url` |
205+
| 调试和核对结果 | `screenshot`、`console messages`、`errors list`、`highlight` |
206+
| 会话与状态管理 | `tab *`、`cookies *`、`storage *`、`state *` |
207+
148208
### 核心交互
149209

150210
| 命令 | CLI 用法 | Library API |
@@ -361,6 +421,45 @@ kbr
361421

362422
---
363423

424+
<a name="agent-notes-cn"></a>
425+
426+
## Agent 阅读说明
427+
428+
如果你是正在阅读本 README 的 Agent，可以把 `kbr` 理解成一个带紧凑文本接口的可交互浏览器。
429+
430+
- 优先使用 `kbr snapshot` 获取页面结构。它最省 token，也会返回稳定的数字引用。
431+
- 拿到快照后，优先用数字 ID 操作元素，例如 `kbr click 5`、`kbr type 8 "hello"`、`kbr get text 12`。
432+
- 页面跳转或 DOM 变化后要重新获取快照。元素 ID 只在当前快照内有效，不是永久选择器。
433+
- 优先使用 `kbr get`、`kbr find`、`kbr wait` 做定向读取，不要反复依赖整页截图。
434+
- 只有在页面内容主要存在于图片中，或 DOM / 无障碍树拿不到信息时，再启用 OCR。
435+
- 当你已经明确知道目标元素，或当前上下文里没有快照 ID 时，再退回使用 CSS / XPath 选择器。
436+
- 通过 Homebrew 或 GitHub Release 安装的发布版本都带 OCR，因此宿主机需要可用的 Tesseract 运行时库。
437+
438+
### 作为 Agent 技能安装
439+
440+
如果你的 Agent 框架支持本地技能，先安装 `kbr`，再把仓库里的 `skills/ko-browser` 目录复制到 Agent 的技能目录中，并命名为 `ko-browser/`。
441+
442+
```yaml
443+
<agent-skills-dir>/
444+
ko-browser/
445+
SKILL.md
446+
```
447+
448+
仓库里的技能文件在这里：
449+
450+
- [`skills/ko-browser/SKILL.md`](https://github.com/libi/ko-browser/blob/main/skills/ko-browser/SKILL.md)
451+
452+
示例：
453+
454+
```bash
455+
mkdir -p <agent-skills-dir>/ko-browser
456+
cp skills/ko-browser/SKILL.md <agent-skills-dir>/ko-browser/SKILL.md
457+
```
458+
459+
复制完成后，再确保 Agent 运行环境的 `PATH` 中可以找到 `kbr` 二进制。如果 Agent 宿主还支持直接注册可执行工具，也可以同时把 `kbr` 暴露为可调用工具。
460+
461+
---
462+
364463
## 🤝 参与贡献
365464

366465
欢迎提交 Pull Request！

‎README.md‎

Lines changed: 92 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
11
<p align="center">
22
<h1 align="center">kbr (ko-browser)</h1>
3-
<p align="center">A simple, fast, token-efficient browser for AI agents — CLI + Go Library</p>
3+
<p align="center">A simple, fast, token-efficient browser for AI agents — CLI + Go Library.</p>
44
</p>
55

66
<p align="center">
7+
<a href="README-CN.md">中文文档</a> •
78
<a href="#-quick-start">Quick Start</a> •
9+
<a href="#agent-notes">Agent Notes</a> •
810
<a href="#-commands">Commands</a> •
9-
<a href="#-library-usage">Library</a> •
10-
<a href="docs/snapshot-format-en.md">Snapshot Format Spec</a> •
11-
<a href="#-中文文档">中文文档</a>
11+
<a href="#-library-api">Library</a> •
12+
<a href="docs/snapshot-format-en.md">Snapshot Format Spec</a>
1213
</p>
1314

1415
<p align="center">
@@ -20,7 +21,12 @@
2021

2122
---
2223

23-
**ko-browser** is a browser automation tool built in Go, designed for AI agents. It provides both a **CLI tool** and a **Go library** with a custom accessibility tree snapshot format that saves **46%+ tokens** compared to alternatives.
24+
**ko-browser** is a browser automation tool built in Go for AI agents. It exposes the same core model in two forms:
25+
26+
- a **CLI** for shell-driven agent workflows
27+
- a **Go library** for embedding browser control into agent runtimes and tools
28+
29+
Its custom accessibility-tree snapshot format reduces prompt footprint by **46%+** compared with more verbose alternatives.
2430

2531
### ✨ Key Features
2632

@@ -30,12 +36,12 @@
3036
- ⚡ **Fast startup** — ~50ms (Go binary) vs ~500ms (Node.js-based tools)
3137
- 🔢 **Simple element references** — `click 5`
3238
- 🔍 **Optional OCR** — Tesseract integration via `-tags=ocr` build flag for image-heavy pages
33-
- 🌐 **~86 commands** — full parity with agent-browser v0.19.0
39+
- 🌐 **~86 commands** — broad coverage for browser automation workflows
3440

3541
### Snapshot Format Comparison
3642

3743
```
38-
┌─ kbr (46% fewer tokens) ──────────┐ ┌─ agent-browser ────────────────────┐
44+
┌─ kbr (46% fewer tokens) ──────────┐ ┌─ verbose snapshot output ──────────┐
3945
│ Page: "Example" │ │ - document "Example" │
4046
│ │ │ - navigation "main": │
4147
│ 1: link "Home" │ │ - link "Home" [ref=@e1] │
@@ -50,6 +56,14 @@
5056

5157
## 📦 Installation
5258

59+
### Choose an install path
60+
61+
| Use case | Recommended path | Notes |
62+
|---------|------------------|-------|
63+
| macOS local usage | Homebrew | Installs an OCR-enabled build and pulls in `tesseract` |
64+
| Linux/macOS manual deployment | GitHub Releases | Download the prebuilt archive and make sure Tesseract runtime libraries are present |
65+
| Go-based integration or custom builds | From source | Best when embedding `kbr` into your own toolchain |
66+
5367
### Homebrew
5468

5569
```bash
@@ -101,10 +115,32 @@ kbr install # check & download Chromium
101115
kbr install --with-deps # also install system dependencies (Linux)
102116
```
103117

118+
### Runtime requirements
119+
120+
- Chrome or Chromium is required. Run `kbr install` if you do not already have a compatible browser.
121+
- OCR-enabled builds expect Tesseract runtime libraries on the host.
122+
- On Linux CI or sandboxed environments, Chrome may require `--no-sandbox`-style fallbacks depending on the runner configuration.
123+
104124
---
105125

106126
## 🚀 Quick Start
107127

128+
### Agent loop
129+
130+
This is the most common shell-driven agent workflow:
131+
132+
```bash
133+
kbr open https://example.com
134+
kbr snapshot
135+
kbr click 5
136+
kbr type 8 "hello world"
137+
kbr press Enter
138+
kbr wait load
139+
kbr get text 12
140+
```
141+
142+
Use `snapshot` to get the current page structure, act on numeric refs, then re-snapshot after the page changes.
143+
108144
### CLI
109145

110146
```bash
@@ -171,6 +207,16 @@ func main() {
171207

172208
## 📖 Commands
173209

210+
### Common flows
211+
212+
| Goal | Commands |
213+
|------|----------|
214+
| Navigate and inspect | `open`, `snapshot`, `get title`, `get url` |
215+
| Interact with forms | `click`, `type`, `fill`, `select`, `check`, `press` |
216+
| Wait for state changes | `wait load`, `wait selector`, `wait text`, `wait url` |
217+
| Debug and verify | `screenshot`, `console messages`, `errors list`, `highlight` |
218+
| Work with sessions | `tab *`, `cookies *`, `storage *`, `state *` |
219+
174220
### Core Interaction
175221

176222
| Command | CLI Usage | Library API |
@@ -733,6 +779,45 @@ The `browser/`, `axtree/`, `selector/`, and `ocr/` packages are all public and i
733779

734780
---
735781

782+
<a name="agent-notes"></a>
783+
784+
## Agent Notes
785+
786+
If you are an agent reading this README, use `kbr` as an interactive browser with a compact text interface.
787+
788+
- Prefer `kbr snapshot` as the primary page representation. It is the most token-efficient output and gives stable numeric refs.
789+
- Use numeric refs like `kbr click 5`, `kbr type 8 "hello"`, and `kbr get text 12` after taking a fresh snapshot.
790+
- Re-snapshot after navigation or DOM mutations. Element IDs are snapshot-local, not permanent selectors.
791+
- Use `kbr get`, `kbr find`, and `kbr wait` for targeted reads instead of repeatedly taking full screenshots.
792+
- Use OCR only when the page content is image-heavy or inaccessible through the DOM/accessibility tree.
793+
- Prefer CSS/XPath selectors only when you already know the target precisely or when numeric refs are unavailable.
794+
- The published Homebrew package and release binaries are built with OCR enabled, so Tesseract runtime libraries are expected on the host.
795+
796+
### Install as an agent skill
797+
798+
If your agent framework supports local skills, install `kbr` first, then copy the repository skill directory into your agent's skills directory as `ko-browser/`.
799+
800+
```yaml
801+
<agent-skills-dir>/
802+
ko-browser/
803+
SKILL.md
804+
```
805+
806+
The source skill lives here:
807+
808+
- [`skills/ko-browser/SKILL.md`](https://github.com/libi/ko-browser/blob/main/skills/ko-browser/SKILL.md)
809+
810+
Example:
811+
812+
```bash
813+
mkdir -p <agent-skills-dir>/ko-browser
814+
cp skills/ko-browser/SKILL.md <agent-skills-dir>/ko-browser/SKILL.md
815+
```
816+
817+
After that, make sure the `kbr` binary is available in the agent runtime `PATH`. For agent hosts that also support executable-tool registration, you can expose `kbr` directly in addition to the skill file.
818+
819+
---
820+
736821
## 🤝 Contributing
737822

738823
Contributions are welcome! Please feel free to submit a Pull Request.

0 commit comments

Comments
 (0)