kuri

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/13639/7915bba5fb25229c11f59482cfcd4a0eaf2945ee066dbf5cec395df880b53268.png" alt="Kuri" width="200" />
</p>

<h1 align="center">Kuri 🌰</h1>

<p align="center">
  <a href="https://kuri.trilok.ai/download/latest.json"><img src="https://img.shields.io/badge/stable-v0.6.1-brightgreen?style=flat-square" alt="Stable release"></a>
  <a href="https://github.com/justrach/kuri/blob/main/LICENSE"><img src="https://img.shields.io/github/license/justrach/kuri?style=flat-square" alt="License"></a>
  <img src="https://img.shields.io/badge/zig-0.16.0-f7a41d?style=flat-square" alt="Zig">
  <img src="https://img.shields.io/badge/node__modules-0_files-brightgreen?style=flat-square" alt="node_modules">
  <img src="https://img.shields.io/badge/status-stable-brightgreen?style=flat-square" alt="status">
</p>

## 安装

```sh
curl -fsSL https://kuri.trilok.ai/download | sh
```

macOS arm64/x86_64 和 Linux x86_64/arm64。单一二进制文件，无运行时依赖。

直接下载：[macOS arm64](https://kuri.trilok.ai/download/v0.6.1/kuri-v0.6.1-aarch64-macos.tar.gz) · [macOS x86_64](https://kuri.trilok.ai/download/v0.6.1/kuri-v0.6.1-x86_64-macos.tar.gz) · [Linux x86_64](https://kuri.trilok.ai/download/v0.6.1/kuri-v0.6.1-x86_64-linux.tar.gz) · [Linux arm64](https://kuri.trilok.ai/download/v0.6.1/kuri-v0.6.1-aarch64-linux.tar.gz)

---

**面向 AI 代理的浏览器自动化与网页抓取。使用 Zig 编写。零 Node.js。**

CDP 自动化 · A11y 快照 · HAR 录制 · 独立抓取器 · 交互式终端浏览器 · 代理式 CLI · 安全测试 · iOS + Android 设备控制

[快速开始](#-quick-start) · [基准测试](#-benchmarks) · [kuri-agent](#-kuri-agent) · [安全测试](#-security-testing) · [API](#-http-api) · [技能](#-skills) · [更新日志](https://github.com/justrach/kuri/blob/main/CHANGELOG.md)

> **团队为何转向 Kuri：** 当前 Apple Silicon `ReleaseFast` 构建的每个二进制文件均保持在 2 MB 以下，2026-04-23 重新运行 Google Flights 测得完整 `kuri-agent` 循环（`go→snap→click→snap→eval`）消耗 **3,392 个 token**。在引用百分比之前，应在相同环境中重新运行跨工具对比数据。

---

## 为什么 Kuri 在代理场景中胜出

大多数浏览器工具是为 QA 工程师构建的。Kuri 是为代理循环构建的：读取页面、保持低 token 成本、基于稳定引用执行操作，然后继续。

- **135 个 HTTP 端点** — 与 agent-browser 和 browser-use 完全对等，从 React 检查到 Core Web Vitals。
- **比 agent-browser 少 7-12% 的 token**，得益于 `@eN` 引用格式和零前缀渲染。
- **观测数据轻 44 倍**，使用 `/page/state`（48 个 token）对比完整快照（2,124 个 token），针对同一 Google Flights 页面。
- **批量执行** — `POST /batch` 在一次 HTTP 调用中发送 N 条命令，消除 N-1 次往返和 N-1 轮 LLM 交互。
- **React 兼容** — 可信的 CDP 鼠标事件和逐字符键盘事件可触发 React 18/19 的 `onClick` 和 `onChange`。

### 快照 token：Google Flights `SIN → TPE`

2026-05-24 在此工作区重新运行，使用 `wc -c` 和 `chars/4` 近似值测量。

| 工具 / 模式 | 字符数 | ~Token 数 | 备注 |
|---|---:|---:|---|
| `kuri snap`（完整） | 8,499 | **2,124** | 所有节点 + 交互引用 |
| `kuri snap`（仅交互） | ~3,000 | **~750** | 最适合代理循环 |
| `kuri /page/state` | 190 | **48** | 轻量观测（url、title、scroll%、计数） |
| agent-browser snap（估算） | ~9,183 | **~2,295** | `[ref=e0]` 格式开销 |

### Token 效率：kuri vs agent-browser

| 页面 | kuri token 数 | agent-browser token 数 | 节省 |
|---|---:|---:|---|
| example.com | 40 | 35 | -13%（简单页面，agent-browser 跳过根节点） |
| Hacker News | 386 | ~440 | **少 12%** |
| Google Flights SIN→TPE | 2,124 | ~2,295 | **少 7%** |

节省来自 kuri 的紧凑格式：
- `@e0` 引用（3 字符）对比 `[ref=e0]`（9 字符）
- 每行无 `- ` 前缀（节省 2 字符 × 行数）
- 相同的缩进，相同的节点过滤

### 完整工作流成本：`go → snap → click → snap → eval`

| 工具 | 每周期 token 数 |
|---|---:|
| **kuri-agent** | **~3,400** |
| 使用 `/page/state` 替代第二次 snap | **~1,700** |
| 使用 `POST /batch`（全部在一次调用中） | **~1,700**（相同 token 数，1 次 HTTP 调用而非 5 次） |

### kuri vs libretto

[libretto](https://github.com/saffron-health/libretto)（Playwright + Node）是每步 token 成本方面最接近的竞争对手。2026-07-04 进行头对头测量 — 相同 Chrome、相同标签页、真实 `tiktoken` `o200k_base` 计数（完整方法和复现：**[benchmarks/libretto_comparison.md](https://github.com/justrach/kuri/blob/main/benchmarks/libretto_comparison.md)**）。诚实的对比：

| 维度 | 胜者 | 详情 |
|---|---|---|
| 每次调用延迟 | **kuri** | 4–117 ms vs 1,344–1,500 ms（**快 13–376 倍** — 持久服务器 vs 每条命令启动 Node） |
| 快照 token，典型页面 | **kuri** | 简单页面 61 vs 151（2.5 倍），文章 265 vs 363（1.37 倍）— 更紧凑的语法 |
| 快照 token，大型列表 | 各有胜负 | kuri 默认 4,424 vs 813 — kuri 输出全部 259 个引用，libretto 默认截断。使用 `limit=5` 时 kuri 渲染 555 个 token（**比 libretto 少 1.46 倍**），34 个引用 + `… +45 more` 标记 |
| 轨迹（信息流，9 次点击） | **kuri**，微弱优势 | 898 vs 939 个 token（`limit=5` 基础 + diff 循环 vs exec 循环）— 持平至微弱优势；早上的 5.1 倍差距是未截断的基础快照 |
| 重复运行 | **libretto** | 将轨迹编译为 Playwright 脚本 → 0 token 重放；kuri 每次运行都重新支付循环成本 |

**kuri 从研究 libretto 中获得的改进**（均在本版本中发布）：diff 优先循环（`take_snapshot_diff`，约 38 token/步）；自适应 diff，在导航时回退到带 `! page replaced` 头的完整快照；仅身份移除行；截图写入磁盘（返回路径，字节永不进入上下文）；MCP 上的 `get_page_state`；以及 — 在将 `parseA11yNodes` 重写为真正的 DFS 树遍历之后 — **可选列表截断**（`/snapshot?limit=N`，每个被截断的运行一行 `… +K more`）、**范围重新捕获**（`scope=@ref`）和**层级缩进**，也作为 MCP `take_snapshot` 上的 `uid`/`limit` 暴露。9 次点击的信息流轨迹，使用朴素完整重新快照时消耗 44,285 个 token，使用截断基础 + diff 后仅消耗 **898** 个 — 便宜 49 倍，且超过 libretto 的 939。

> 上述较旧的表格使用 `chars/4` token 近似值；libretto 对比使用真实的 `tiktoken` 计数。在引用百分比之前，请在自己的环境中重新运行跨工具数据。

### 二进制大小和内存

在 Apple M4 Pro、macOS 26.4.1 上测量。当前二进制文件使用 `-Doptimize=ReleaseFast` 构建。

| 二进制文件 | 当前大小 |
|---|---:|
| `kuri` | 1,093,840 B (1.04 MiB) |
| `kuri-agent` | 629,904 B (615 KiB) |
| `kuri-browse` | 1,089,120 B (1.04 MiB) |
| `kuri-fetch` | 2,063,488 B (1.97 MiB) |

### RSS 在 Zig 0.16 迁移期间保持平稳

使用 `/usr/bin/time -l` 针对当前 `v0.4.3` `ReleaseFast` 构建测量。

| 命令 | `v0.4.3` 平均最大 RSS |
|---|---:|
| `kuri-fetch --version` | ~2.45 MiB |
| `kuri-browse --version` | ~2.45 MiB |
| `kuri-fetch --quiet --dump markdown http://example.com/` | ~9.17 MiB |

## 问题所在

每个浏览器自动化工具都会拖入 Playwright（约 300 MB）、Node.js 运行时以及一连串 npm 依赖。你的 AI 代理只想读取页面、点击按钮，然后继续。
**Kuri 是一个单一的 Zig 二进制文件。** 四种模式，零运行时：

```
kuri           →  CDP server (Chrome automation, a11y snapshots, HAR)
kuri-fetch     →  standalone fetcher (no Chrome, QuickJS for JS, ~2 MB)
kuri-browse    →  interactive terminal browser (navigate, follow links, search)
kuri-agent     →  agentic CLI (scriptable Chrome automation + security testing)
```

---
## 📦 安装

### 一行安装（macOS / Linux）

```sh
curl -fsSL https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/install.sh | sh
```

检测你的平台，下载对应的二进制文件，安装到 `~/.local/bin`。
下载来自 Kuri 自行管理的 `release-channel` 分支。macOS 二进制文件使用 Developer ID 证书进行本地签名。GitHub Release 资产与这些 tarball 相同。

### bun / npm

```sh
bun install -g kuri-agent
# or: npm install -g kuri-agent
```

在安装时下载适用于你平台的正确原生二进制文件。

### 发布渠道

Kuri 的稳定二进制文件位于 `release-channel` 分支，并直接从 GitHub raw URL 提供。

- 稳定版安装脚本：`https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/install.sh`
- 稳定版清单：`https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/latest.json`
- 分支视图：`https://github.com/justrach/kuri/tree/release-channel/stable`
- 直接下载模式：`https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/<version>/kuri-<version>-<target>.tar.gz`

### 手动安装

从[稳定版发布清单](https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/latest.json)或 [GitHub Releases 页面](https://github.com/justrach/kuri/releases)下载适用于你平台的 tarball，并将其解压到你的 `$PATH` 中。

稳定版安装 URL：

```sh
curl -fsSL https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/install.sh | sh
```

清单包含精确的资源 URL 以及针对 `aarch64-linux`、`x86_64-linux`、`aarch64-macos` 和 `x86_64-macos` 的 SHA-256 校验和。

### 平台支持

| 平台 | 状态 |
|---|---|
| macOS（`aarch64`、`x86_64`） | 预构建二进制文件，已签名并公证 |
| Linux（`aarch64`、`x86_64`） | 预构建二进制文件 |
| Windows（`x86_64`） | **实验性——仅限交叉编译。** `zig build -Dtarget=x86_64-windows-gnu` 已通过 CI 验证，但 Chrome 自动化、守护进程化、基于信号的关闭、HAR 录制以及基于文件的认证存储均在运行时以 `error.UnsupportedOnWindows` 打桩。如果你需要完整功能集，请使用 **WSL2**。跟踪于 [#153](https://github.com/justrach/kuri/issues/153)。 |

Kuri 在多个地方依赖 POSIX 原语（`fork`、`clock_gettime`、原始套接字），因此完整的原生 Windows 移植是实打实的工作。上述编译级基线允许 `--version`/`--help` 路径和纯内存操作运行；那些棘手的部分（Chrome、套接字、守护进程化）需要真正的 Win32 实现才能从打桩列表中移除。如果你想接手其中任何一项，请 +1 [#153](https://github.com/justrach/kuri/issues/153) 或提交 PR。

### 从源码构建

需要 [Zig ≥ 0.16.0](https://ziglang.org/download/)。

```bash
git clone https://github.com/justrach/kuri.git
cd kuri
zig build -Doptimize=ReleaseFast
# Binaries in zig-out/bin/: kuri  kuri-agent  kuri-fetch  kuri-browse
```

---

## ⚡ 快速开始

**环境要求：** [Zig ≥ 0.16.0](https://ziglang.org/download/) · Chrome/Chromium（用于 CDP 模式）

```bash
git clone https://github.com/justrach/kuri.git
cd kuri

zig build              # build everything
zig build test         # run 252+ tests

# CDP mode — launches Chrome automatically
./zig-out/bin/kuri

# Standalone mode — no Chrome needed
./zig-out/bin/kuri-fetch https://example.com

# Interactive browser — browse from your terminal
./zig-out/bin/kuri-browse https://example.com

# Experimental standalone browser runtime — separate build, not production
(cd kuri-browser && zig build run -- render https://example.com)
(cd kuri-browser && zig build run -- bench --offline)
```

### 首次运行，最短路径

```bash
# start the server; if CDP_URL is unset, kuri launches managed Chrome for you
./zig-out/bin/kuri

# discover tabs from that managed browser
curl -s http://127.0.0.1:8080/discover

# inspect the discovered tab list
curl -s http://127.0.0.1:8080/tabs
```

### 会话优先的代理循环

对于代理风格的 HTTP 用法，优先使用会话头加上 `/tab/new`、`/page/info` 和 `/snapshot`，而不是在每次调用时重复 `tab_id`。

```bash
SESSION=hn-demo
BASE=http://127.0.0.1:8080

curl -s -H "X-Kuri-Session: $SESSION" \
  "$BASE/tab/new?url=https%3A%2F%2Fnews.ycombinator.com"

curl -s -H "X-Kuri-Session: $SESSION" "$BASE/page/info"
SNAP=$(curl -s -H "X-Kuri-Session: $SESSION" "$BASE/snapshot?filter=interactive&format=compact")
MORE_REF=$(printf '%s' "$SNAP" | python3 -c 'import re,sys; print(re.search(r"\"More\" @(e\\d+)", sys.stdin.read()).group(1))')
curl -s -H "X-Kuri-Session: $SESSION" "$BASE/action?action=click&ref=$MORE_REF"
curl -s -H "X-Kuri-Session: $SESSION" "$BASE/page/info"
```

`tools/kuri_harness.py` 中还有一个轻量级实验性封装，如果你想在相同的 HTTP 接口之上使用 Python 辅助工具。

如果你已经运行着启用了远程调试的 Chrome，请将 `CDP_URL` 设置为 WebSocket 或 HTTP 端点：

```bash
CDP_URL=ws://127.0.0.1:9222/devtools/browser/... ./zig-out/bin/kuri
# or
CDP_URL=http://127.0.0.1:9222 ./zig-out/bin/kuri
```

### 用 4 条命令浏览 vercel.com

```bash
# 1. Discover Chrome tabs
curl -s http://localhost:8080/discover
# → {"discovered":1,"total_tabs":1}

# 2. Get tab ID
curl -s http://localhost:8080/tabs
# → [{"id":"ABC123","url":"chrome://newtab/","title":"New Tab"}]

# 3. Navigate
curl -s "http://localhost:8080/navigate?tab_id=ABC123&url=https://vercel.com"

# 4. Get accessibility snapshot (token-optimized for LLMs)
curl -s "http://localhost:8080/snapshot?tab_id=ABC123&filter=interactive"
# → [{"ref":"e0","role":"link","name":"VercelLogotype"},
#    {"ref":"e1","role":"button","name":"Ask AI"}, ...]
```

---

## 🌐 HTTP API

所有端点均返回 JSON。可通过 `KURI_SECRET` 环境变量进行可选认证。**135 个端点** —— 与 agent-browser 和 browser-use 完全对等。

### 核心

| 路径 | 描述 |
|------|-------------|
| `GET /health` | 服务器状态、标签页数量、版本 |
| `GET /tabs` | 列出所有已注册的标签页 |
| `GET /discover` | 通过 CDP 自动发现 Chrome 标签页 |
| `GET /tab/current` | 获取或设置 `X-Kuri-Session` 的当前标签页 |
| `GET /page/info` | 活动标签页的实时 URL/标题/就绪状态/视口/滚动位置 |
| `GET /page/state` | 紧凑页面观察：url、title、scroll%、viewport、表单/链接/图片/输入框数量 |
| `POST /batch` | 在一次 HTTP 调用中执行多个命令 —— 返回结果数组 |
| `GET /browdie` | 🌰（彩蛋） |

### 浏览器控制

| 路径 | 参数 | 描述 |
|------|--------|-------------|
| `GET /navigate` | `tab_id`、`url` | 将标签页导航至 URL |
| `GET /tab/new` | `url`、`activate`、`wait` | 创建新标签页，并可选地水合/设为当前标签页 |
| `GET /tab/close` | `tab_id` | 关闭标签页 |
| `GET /window/new` | `url`、`activate`、`wait` | 创建新窗口/标签页目标 |
| `GET /snapshot` | `tab_id`、`filter`、`format` | 带 `eN` 引用的 A11y 树快照。使用 `filter=interactive&format=compact` 实现低 token 的 agent 循环。 |
| `GET /text` | `tab_id` | 提取页面文本 |
| `GET /screenshot` | `tab_id`、`format`、`quality`、`save` | 捕获截图（base64）；`save=true` 则将 PNG 写入 `STATE_DIR/screenshots` 并返回 `{path,bytes}` |
| `GET /screenshot/annotated` | `tab_id` | 带编号元素标签的截图 |
| `GET /screenshot/diff` | `tab_id`、`baseline` | 当前截图与基线截图之间的视觉差异 |
| `GET /action` | `tab_id`、`ref`、`action`、`value` | 通过 ref 执行点击/输入/填充/选择/滚动/悬停/双击/勾选/取消勾选/失焦 |
| `GET /evaluate` | `tab_id`、`expression` | 执行 JavaScript |
| `GET /evalhandle` | `tab_id`、`expression` | 执行 JS，返回 objectId 句柄（而非值） |
| `GET /close` | `tab_id` | 关闭标签页 + 清理 |
| `GET /bringtofront` | `tab_id` | 将标签页置于前台 |

### 操作

| 路径 | 参数 | 描述 |
|------|--------|-------------|
| `GET /clear` | `ref` | 清除输入框的值 |
| `GET /selectall` | `ref` | 全选输入框/contenteditable 中的文本 |
| `GET /setvalue` | `ref`、`value` | 直接设置输入值（绕过按键事件） |
| `GET /dispatch` | `ref`、`type` | 在元素上派发自定义 DOM 事件 |
| `GET /boundingbox` | `ref` | 获取元素边界矩形（x、y、width、height、centerX、centerY） |
| `GET /getattribute` | `ref`、`name` | 按名称获取元素属性 |
| `GET /inputvalue` | `ref` | 获取当前输入元素的值 |
| `GET /element/state` | `ref`、`check` | 快速布尔值：`exists`、`visible`、`enabled`、`checked` |
| `GET /find-element` | `text`/`role`/`label`/`placeholder`/`testid` | 语义定位器 —— 无需快照即可查找元素 |
| `GET /highlight` | `ref` 或 `selector` | 用叠加层高亮元素 |

### 鼠标与触摸

| 路径 | 参数 | 描述 |
|------|--------|-------------|
| `GET /mouse/move` | `x`、`y` | 将鼠标移动到坐标 |
| `GET /mouse/down` | `x`、`y`、`button` | 鼠标按键按下 |
| `GET /mouse/up` | `x`、`y`、`button` | 鼠标按键抬起 |
| `GET /mouse/wheel` | `x`、`y`、`deltaX`、`deltaY` | 鼠标滚轮滚动 |
| `GET /tap` | `x`、`y` | 触摸点击（touchStart + touchEnd） |
| `GET /swipe` | `startX`、`startY`、`endX`、`endY` | 触摸滑动手势 |
| `GET /drag` | `src_ref`、`tgt_ref` | 将元素拖拽至目标 |

### 键盘

| 路径 | 参数 | 描述 |
|------|--------|-------------|
| `GET /keyboard/type` | `tab_id`、`text` | 通过按键事件输入文本 |
| `GET /keyboard/inserttext` | `tab_id`、`text` | 直接插入文本 |
| `GET /keydown` | `tab_id`、`key` | 按键按下事件 |
| `GET /keyup` | `tab_id`、`key` | 按键抬起事件 |

### 内容提取

| 路径 | 描述 |
|------|-------------|
| `GET /markdown` | 将页面转换为 Markdown |
| `GET /links` | 提取所有链接 |
| `GET /dom/query` | CSS 选择器查询 |
| `GET /dom/html` | 获取元素 HTML |
| `GET /dom/attributes` | 获取元素属性 |
| `GET /pdf` | 将页面打印为 PDF |
| `GET /find` | 页面内文本搜索 |

### 等待

| 路径 | 参数 | 描述 |
|------|--------|-------------|
| `GET /wait` | `selector`、`text`、`url`、`state`、`visible`、`timeout` | 等待选择器/文本/URL 模式/networkidle/加载状态 |
| `GET /wait/function` | `expression`、`timeout` | 等待任意 JS 表达式为真 |
| `GET /wait/download` | `timeout` | 等待文件下载完成 |

### 对话框处理

| 路径 | 描述 |
|------|-------------|
| `GET /dialog/auto` | 自动处理所有 JS 对话框（接受或关闭） |
| `GET /dialog/accept` | 接受当前对话框（可带提示文本） |
| `GET /dialog/dismiss` | 关闭当前对话框 |

### 网络与 HAR

| 路径 | 描述 |
|------|-------------|
| `GET /har/start` | 开始记录网络流量 |
| `GET /har/stop` | 停止 + 返回 HAR 1.2 JSON |
| `GET /har/status` | 记录状态 + 条目数量 |
| `GET /har/replay` | 带 curl/fetch/python 代码片段的 API 映射 |
| `GET /cookies` | 获取 cookies |
| `GET /cookies/set` | 设置 cookies |
| `GET /cookies/delete` | 删除 cookies |
| `GET /cookies/clear` | 清除所有 cookies |
| `GET /headers` | 设置自定义请求头 |
| `GET /intercept/start` | 开始请求拦截 |
| `GET /intercept/stop` | 停止请求拦截 |
| `GET /intercept/requests` | 列出已拦截的请求 |
| `GET /request/detail` | 获取请求 ID 的响应体 |
| `GET /response/body` | 获取 URL 并返回响应体 |
| `GET /network` | 网络流量统计 |
| `GET /download` | 触发文件下载 |

### 导航与状态

| 路径 | 描述 |
|------|-------------|
| `GET /back` | 浏览器后退 |
| `GET /forward` | 浏览器前进 |
| `GET /reload` | 重新加载页面 |
| `GET /stop` | 停止页面加载 |
| `GET /pushstate` | 通过 history.pushState 进行 SPA 导航 |
| `GET /storage/local` | 获取/设置 localStorage |
| `GET /storage/session` | 获取/设置 sessionStorage |
| `GET /storage/local/clear` | 清除 localStorage |
| `GET /storage/session/clear` | 清除 sessionStorage |
| `GET /session/save` | 保存浏览器会话 |
| `GET /session/load` | 恢复浏览器会话 |
| `GET /session/list` | 列出已保存的会话 |
| `GET /setcontent` | 直接设置页面 HTML（POST） |

### 认证配置文件

| 路径 | 描述 |
|------|-------------|
| `GET /auth/profile/save` | 将 cookies + storage 保存为命名认证配置文件 |
| `GET /auth/profile/load` | 将命名认证配置文件恢复到标签页 |
| `GET /auth/profile/list` | 列出已保存的认证配置文件 |
| `GET /auth/profile/delete` | 删除已保存的认证配置文件 |
| `GET /auth/extract` | 提取认证令牌（JWT、cookies、headers） |
| `GET /set/credentials` | 设置 HTTP 基本认证凭据 |

在 macOS 上，认证配置文件密钥存储在用户 Keychain 中。

### 模拟

| 路径 | 参数 | 描述 |
|------|--------|-------------|
| `GET /emulate` | 设备类型、屏幕尺寸 | 设备模拟 |
| `GET /set/viewport` | `width`、`height` | 设置视口大小 |
| `GET /set/useragent` | `ua` | 设置用户代理 |
| `GET /set/media` | `media` | 模拟媒体类型 |
| `GET /set/offline` | `offline` | 切换离线模式 |
| `GET /geolocation` | `lat`、`lng` | 覆盖地理位置 |
| `GET /timezone` | `timezone` | 覆盖时区（例如 `America/New_York`） |
| `GET /locale` | `locale` | 覆盖区域设置（例如 `en-US`） |
| `GET /permissions` | `name`、`state` | 授予/拒绝权限（geolocation、notifications、clipboard） |

### 脚本与注入

| 路径 | 描述 |
|------|-------------|
| `GET /script/inject` | 向页面注入 JavaScript（跨导航持久化） |
| `GET /initscript/remove` | 移除先前注入的初始化脚本 |
| `GET /addstyle` | 注入 CSS 样式表 |
| `GET /expose` | 向页面 JS 上下文暴露命名函数 |

### React 检查

| 路径 | 描述 |
|------|-------------|
| `GET /react/tree` | 通过 DevTools hook 获取 React 组件树 |
| `GET /react/inspect` | React 组件 props 和 state |
| `GET /react/renders` | React 渲染跟踪（开始/停止） |
| `GET /react/suspense` | React Suspense 边界状态 |

### 录制与性能

| 路径 | 描述 |
|------|-------------|
| `GET /recording/start` | 记录用户操作（点击、输入、导航） |
| `GET /recording/stop` | 停止录制 + 返回操作日志 |
| `GET /vitals` | 核心 Web 指标（LCP、CLS、FID、TTFB、FCP、domInteractive） |
| `GET /perf/lcp` | 最大内容绘制时间 |
| `GET /trace/start` | 开始性能跟踪 |
| `GET /trace/stop` | 停止跟踪 |
| `GET /profiler/start` | 启动 JS 性能分析器 |
| `GET /profiler/stop` | 停止性能分析器 |

### 调试

| 路径 | 描述 |
|------|-------------|
| `GET /debug/enable` | 启用页面内调试 HUD 和可选的冻结模式 |
| `GET /debug/disable` | 禁用页面内调试 HUD |
| `GET /inspect` | 元素检查 |
| `GET /errors` | 收集 JS 错误 |
| `GET /console` | 读取控制台日志 |
| `GET /frames` | 列出页面框架 |
| `GET /frame` | 按名称或 URL 切换到 iframe 上下文 |
| `GET /mainframe` | 切换回主框架 |
| `GET /diff/snapshot` | 与此标签页上一次调用相比的紧凑 `+`/`~`/`-` 差异 —— 节省 token 的操作循环（别名为 `/snapshot/changes`）。在大量变更时回退为带 `! page replaced` 标头的完整快照。 |
| `GET /diff/url` | 并排比较两个 URL（导航、快照、差异） |

### 流式传输

| 路径 | 描述 |
|------|-------------|
| `GET /screencast/start` | 开始屏幕录制 |
| `GET /screencast/stop` | 停止屏幕录制 |
| `GET /video/start` | 开始视频捕获 |
| `GET /video/stop` | 停止视频捕获 |
| `GET /ws/start` | WebSocket 隧道启动 |
| `GET /ws/stop` | WebSocket 隧道停止 |

### Agent 友好的循环

最低摩擦的服务器循环是：

1. `GET /tab/new?url=...`
2. `GET /page/state`（轻量）或 `GET /snapshot?filter=interactive&format=compact`（完整）
3. `GET /action?action=click&ref=eN`
4. 重复 —— 或使用 `POST /batch` 在一次调用中执行多步操作

`url` 和 `expression` 查询参数会进行百分号解码。发送 `X-Kuri-Session: my-agent` 以在服务器端持久化标签页上下文。
---

## 🧠 技能

该仓库包含一个用户可扩展的技能区域：

- `skills/kuri-skill.md` 是基础 Kuri HTTP-agent 技能
- `skills/custom/` 保留用于你自己的项目特定技能
- `skills/custom/hackernews-page-2.md` 是一个具体的自定义技能示例
- `.claude/skills/kuri-server/SKILL.md` 与 Claude 风格的仓库技能保持同步

基础技能现在还说明了应使用哪种浏览器路径：

- `kuri` HTTP API：带会话、快照、操作、HAR、cookies 和截图的生产级 Chrome/CDP 自动化
- `kuri-fetch`：独立的无 Chrome 获取/文本提取
- `kuri-browse`：交互式终端浏览
- `kuri-agent`：针对 Kuri 服务器的可脚本化 CLI 自动化
- `kuri-browser/`：用于对等性工作的实验性独立 Zig 原生浏览器运行时

对于实验性浏览器 CLI：

```bash
cd kuri-browser
zig build run -- render https://news.ycombinator.com --selector ".titleline a" --dump text
zig build run -- render https://todomvc.com/examples/react/dist/ --js --wait-eval "document.querySelectorAll('.todo-list li').length >= 1"
zig build run -- parity --offline
zig build run -- bench --offline
zig build run -- serve-cdp --port 9333
```

`kuri-browser serve-cdp` 暴露了 Chrome 风格的 HTTP 发现机制以及一个用于协议冒烟测试的最小 WebSocket JSON-RPC 路由器。运行时 eval 返回由 QuickJS 支持的 V8 形态 CDP 远程对象；这不会增加 V8 依赖，且目前尚不完全兼容 Playwright/Puppeteer。

`kuri-browser` 中的截图目前委托给主 Kuri/CDP 渲染器。请先启动 `./zig-out/bin/kuri`，然后：

```bash
cd kuri-browser
zig build run -- screenshot https://example.com --out example.jpg --compress --kuri-base http://127.0.0.1:8080
```

`--compress` 捕获 PNG 基线图像和 JPEG 候选图像，写入较小的文件，并报告节省的字节数。当前在 `https://example.com` 上的本地测量结果：从 `20,523` 字节的 PNG 到 `18,183` 字节的 JPEG 质量 50，节省 `2,340` 字节，即 `11%`。

### 高级

| 路径 | 描述 |
|------|-------------|
| `GET /diff/snapshot` | 与上一个快照的紧凑 `+`/`~`/`-` 增量对比（代理操作循环） |
| `GET /emulate` | 设备模拟 |
| `GET /geolocation` | 设置地理位置 |
| `POST /upload` | 文件上传 |
| `GET /script/inject` | 注入 JavaScript |
| `GET /intercept/start` | 开始请求拦截 |
| `GET /intercept/stop` | 停止拦截 |
| `GET /screenshot/annotated` | 带元素注释的截图 |
| `GET /screenshot/diff` | 截图之间的视觉差异 |
| `GET /screencast/start` | 开始屏幕录制 |
| `GET /screencast/stop` | 停止屏幕录制 |
| `GET /video/start` | 开始视频录制 |
| `GET /video/stop` | 停止视频录制 |
| `GET /console` | 获取控制台消息 |
| `GET /stop` | 停止页面加载 |
| `GET /get` | 直接 HTTP 获取（服务器端） |
| `GET /scrollintoview` | 将引用的元素滚动到视图中 |
| `GET /drag` | 从一个引用拖动到另一个引用 |
| `GET /keyboard/type` | 通过按键事件输入文本 |
| `GET /keyboard/inserttext` | 直接插入文本 |
| `GET /keydown` | 派发 keydown 事件 |
| `GET /keyup` | 派发 keyup 事件 |
| `GET /wait` | 等待就绪状态或元素条件 |
| `GET /tab/close` | 关闭标签页 |
| `GET /highlight` | 通过引用或选择器高亮元素 |
| `GET /errors` | 获取页面/运行时错误 |
| `GET /set/offline` | 切换离线网络模拟 |
| `GET /set/media` | 设置模拟媒体特性 |
| `GET /set/credentials` | 设置 HTTP 基本认证凭据 |
| `GET /find` | 在当前页面中查找文本匹配项 |
| `GET /trace/start` | 开始 Chrome 跟踪 |
| `GET /trace/stop` | 停止跟踪并返回跟踪数据 |
| `GET /profiler/start` | 启动 JS 性能分析器 |
| `GET /profiler/stop` | 停止 JS 性能分析器 |
| `GET /inspect` | 检查元素或页面状态 |
| `GET /set/viewport` | 设置视口大小 |
| `GET /set/useragent` | 覆盖用户代理 |
| `GET /dom/attributes` | 获取元素属性 |
| `GET /frames` | 列出框架树 |
| `GET /network` | 检查网络状态/请求 |

---

## 🛡️ 隐蔽性与机器人规避

Kuri 在启动时自动应用反检测补丁——无需手动配置。

### 已应用的内容

- **`Page.addScriptToEvaluateOnNewDocument`** — 隐蔽性补丁在任何页面 JS 之前运行
- **navigator.webdriver = false** — 在 Chromium 层面隐藏自动化标志（`--disable-blink-features=AutomationControlled`）
- **WebGL/Canvas/AudioContext 欺骗** — 击败基于指纹的检测
- **UA 轮换** — 5 个逼真的 Chrome/Safari/Firefox 用户代理
- **chrome.csi/chrome.loadTimes** — 针对 Akamai 特定检查的桩代码

### 机器人拦截检测

导航会自动检测拦截并返回结构化回退：

```bash
curl -s "http://localhost:8080/navigate?tab_id=ABC&url=https://protected-site.com"
# If blocked:
# {"blocked":true,"blocker":"akamai","ref_code":"0.7d...",
#  "fallback":{"suggestions":["Open URL directly in browser","Use KURI_PROXY"]}}
# If ok: normal CDP response
```

检测：**Akamai**、**Cloudflare**、**PerimeterX**、**DataDome**、通用验证码。

### 代理支持

```bash
KURI_PROXY=socks5://user:pass@residential-proxy:1080 ./zig-out/bin/kuri
KURI_PROXY=http://proxy:8080 ./zig-out/bin/kuri
```

### 已测试站点

| 站点 | 防护 | 结果 |
|------|-----------|--------|
| Singapore Airlines | Akamai WAF | ✅ 已绕过（v0.4.0 之前被拦截） |
| Shopee SG | 自定义反欺诈 | ✅ 页面加载，重定向至登录 |
| Google Flights | 无 | ✅ 完整交互 |
| Booking.com | PerimeterX | ⚠️ 需要代理 |

---

## 🔧 kuri-fetch

独立 HTTP 抓取器——无需 Chrome、无需 Playwright、无需 npm。以约 2 MB 的二进制文件形式发布，内置 QuickJS 用于 JS 执行。

```bash
zig build fetch    # build + run

# Default: convert to Markdown
kuri-fetch https://example.com

# Extract links
kuri-fetch -d links https://news.ycombinator.com

# Structured JSON output
kuri-fetch --json https://example.com

# Execute inline scripts via QuickJS
kuri-fetch --js https://example.com

# Write to file, quiet mode
kuri-fetch -o page.md -q https://example.com

# Pipe-friendly: content → stdout, status → stderr
kuri-fetch -d text https://example.com | wc -w
```

### 功能特性

- **5 种输出模式** — `markdown`、`html`、`links`、`text`、`json`
- **QuickJS JS 引擎** — `--js` 执行内联 `<script>` 标签
- **DOM 桩** — `document.querySelector`、`getElementById`、`window.location`、`document.title`、`console.log`、`setTimeout`（SSR 风格）
- **SSRF 防御** — 阻止私有 IP、元数据端点、非 HTTP 协议
- **彩色输出** — 遵循 `NO_COLOR`、`TERM=dumb`、`--no-color`、TTY 检测
- **文件输出** — `-o` / `--output` 附带字节数 + 耗时摘要
- **自定义 UA** — `--user-agent` 标志
- **静默模式** — `-q` 抑制 stderr 状态输出

---

## 🌐 kuri-browse

交互式终端浏览器 — 在终端中浏览网页。无需 Chrome。

```bash
zig build browse   # build + run

kuri-browse https://example.com
```

```
🌰 kuri-browse — terminal browser
→ loading https://example.com

# Example Domain
This domain is for use in documentation examples...
Learn more [1]

───── Links ─────
  [1] https://iana.org/domains/example

✓ 528 bytes, 1 links (133ms)
[nav] https://example.com> 1     ← type 1 to follow the link
```

### 命令

| 命令 | 操作 |
|---------|--------|
| `<number>` | 跟随链接 [N] |
| `<url>` | 导航（如果包含 `.`） |
| `:go <url>` | 导航到 URL |
| `:back`、`:b` | 在历史记录中后退 |
| `:forward`、`:f` | 前进 |
| `:reload`、`:r` | 重新获取当前页面 |
| `:links`、`:l` | 显示链接索引 |
| `/<term>` | 在页面中搜索（高亮匹配项） |
| `:search <t>` | 在页面中搜索 |
| `:n`、`:next` | 重新高亮搜索 |
| `:history` | 显示导航历史 |
| `:help`、`:h` | 显示所有命令 |
| `:quit`、`:q` | 退出 |

### 功能

- **彩色 markdown 渲染** — 标题、链接、代码块、粗体、引用块
- **编号链接** — 每个链接都会获得 `[N]`，输入编号即可跟随

---

[Read more](https://github.com/justrach/kuri)