支持 macOS arm64/x86_64 与 Linux x86_64/arm64。单二进制文件，无运行时依赖。

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

---

**面向 AI 智能体的浏览器自动化与网页爬取。使用 Zig 编写。零 Node.js 依赖。**

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

[快速开始](#-quick-start) · [基准测试](#-benchmarks) · [kuri-agent](#-kuri-agent) · [安全测试](#-security-testing) · [API](#-http-api) · [技能](#-skills) · [更新日志](https://github.com/justrach/kuri/blob/HEAD/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 倍的观察** — 同一 Google Flights 页面，使用 `/page/state`（48 个 token）对比完整快照（2,124 个 token）。
- **批量执行** — `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、标题、滚动百分比、计数） |
| 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/HEAD/benchmarks/libretto_comparison.md)**）。诚实的对比结果：

| 维度 | 胜者 | 详情 |
|---|---|---|
| 每次调用的延迟 | **kuri** | 4–117 ms 对比 1,344–1,500 ms（**快 13–376 倍** — 常驻服务器对比每条命令一个 Node 进程） |
| 快照 token 数，典型页面 | **kuri** | 简单页面 61 对比 151（2.5 倍），文章 265 对比 363（1.37 倍）— 更紧凑的语法 |
| 快照 token 数，大型列表 | 平分 | kuri 默认 4,424 对比 813 — kuri 输出全部 259 个引用，libretto 默认截断。使用 `limit=5` 时 kuri 渲染 555 个 token（**比 libretto 少 1.46 倍**），34 个引用 + `… +45 more` 标记 |
| 轨迹（feed，9 次点击） | **kuri**，勉强 | 898 对比 939 个 token（`limit=5` 基线 + 差异循环对比执行循环）— 持平到微弱优势；早间 5.1 倍的劣势来自未截断的基线 |
| 重复运行 | **libretto** | 将轨迹编译为 Playwright 脚本 → 0 token 重放；kuri 每次运行都要重新支付循环成本 |

**kuri 从研究 libretto 中获得的改进**（均随本版本发布）：差异优先循环（`take_snapshot_diff`，约 38 个 token/步）；自适应差异在导航时回退为带 `! page replaced` 头部的完整快照；只含身份信息的删除行；截图写入磁盘（返回路径，字节永不进入上下文）；通过 MCP 提供 `get_page_state`；以及在将 `parseA11yNodes` 重写为真正的 DFS 树遍历之后 — **可选列表截断**（`/snapshot?limit=N`，每次截断运行输出一行 `… +K more`）、**限定作用域的重新捕获**（`scope=@ref`）和**层级缩进**，这些同时以 `uid`/`limit` 形式暴露在 MCP `take_snapshot` 中。那个用朴素的完整重新快照需要 44,285 个 token 的 9 次点击 feed 轨迹，使用截断基线 + 差异后只需 **898** 个 token — 便宜 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 迁移期间保持平稳

以当前 `v0.4.3` `ReleaseFast` 构建为基准，使用 `/usr/bin/time -l` 测量。

| 命令 | `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)

检测您的平台，下载正确的二进制文件，并安装到 `~/.local/bin`。
下载内容来自 Kuri 自行管理的 `release-channel` 分支。macOS 二进制文件使用开发者 ID 证书进行本地签名。GitHub Release 资产镜像了这些相同的 tarball。

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

The manifest includes exact asset URLs plus SHA-256 checksums for `aarch64-linux`, `x86_64-linux`, `aarch64-macos`, and `x86_64-macos`.

### Platform support

| Platform | Status |
|---|---|
| macOS (`aarch64`, `x86_64`) | Prebuilt binaries, signed + notarized |
| Linux (`aarch64`, `x86_64`) | Prebuilt binaries |
| Windows (`x86_64`) | **Experimental — cross-compile only.** `zig build -Dtarget=x86_64-windows-gnu` is CI-verified, but Chrome automation, daemonization, signal-based shutdown, HAR recording, and the file-backed auth store are all stubbed with `error.UnsupportedOnWindows` at runtime. Use **WSL2** if you need the real feature set. Tracked at [#153](https://github.com/justrach/kuri/issues/153). |

Kuri leans on POSIX primitives (`fork`, `clock_gettime`, raw sockets) in several spots, so a full native Windows port is real work. The compile-level baseline above lets the `--version`/`--help` paths and pure in-memory operations run; the gnarly bits (Chrome, sockets, daemonize) need real Win32 implementations before they come off the stub list. If you want to take any of those on, +1 [#153](https://github.com/justrach/kuri/issues/153) or open a PR.

### Build from source

Requires [Zig ≥ 0.16.0](https://ziglang.org/download/).

The manifest includes exact asset URLs plus SHA-256 checksums for `aarch64-linux`, `x86_64-linux`, `aarch64-macos`, and `x86_64-macos`.

### 平台支持

| 平台 | 状态 |
|---|---|
| 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 实现才能从桩列表中移除。如果你想承担其中任何一项，请给 [#153](https://github.com/justrach/kuri/issues/153) +1 或提交 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

### 首次运行，最短路径```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

在 `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

---

## 🌐 HTTP API

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

### 核心

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

### 浏览器控制

| Path | 参数 | 描述 |
|------|--------|-------------|
| `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 的代理循环。 |
| `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` | 按引用执行点击/输入/填充/选择/滚动/悬停/双击/勾选/取消勾选/失焦 |
| `GET /evaluate` | `tab_id`、`expression` | 执行 JavaScript |
| `GET /evalhandle` | `tab_id`、`expression` | 执行 JS，返回 objectId 句柄（而非值） |
| `GET /close` | `tab_id` | 关闭标签页 + 清理 |
| `GET /bringtofront` | `tab_id` | 将标签页置于前台 |

### 操作

| Path | 参数 | 描述 |
|------|--------|-------------|
| `GET /clear` | `ref` | 清空输入字段的值 |
| `GET /selectall` | `ref` | 选中输入框/可编辑内容中的所有文本 |
| `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` | 使用覆盖层高亮元素 |

### 鼠标与触摸

| Path | 参数 | 描述 |
|------|--------|-------------|
| `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` | 将元素拖到目标位置 |

### 键盘

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

### 内容提取

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

### 等待

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

### 对话框处理

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

### 网络与 HAR

| Path | 描述 |
|------|-------------|
| `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` | 触发文件下载 |

### 导航与状态

| Path | 描述 |
|------|-------------|
| `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） |

### 认证配置文件

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

在 macOS 上，认证配置文件机密存储在用户钥匙串（Keychain）中。

### 模拟

| Path | 参数 | 描述 |
|------|--------|-------------|
| `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` | 授予/拒绝权限（地理位置、通知、剪贴板） |

### 脚本与注入

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

### React 检查

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

### 录制与性能

| Path | 描述 |
|------|-------------|
| `GET /recording/start` | 记录用户操作（点击、输入、导航） |
| `GET /recording/stop` | 停止录制并返回操作日志 |
| `GET /vitals` | 核心 Web Vitals（LCP、CLS、FID、TTFB、FCP、domInteractive） |
| `GET /perf/lcp` | Largest Contentful Paint 时间 |
| `GET /trace/start` | 开始性能跟踪 |
| `GET /trace/stop` | 停止跟踪 |
| `GET /profiler/start` | 启动 JS 分析器 |
| `GET /profiler/stop` | 停止分析器 |

### 调试

| Path | 描述 |
|------|-------------|
| `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（导航、快照、差异） |

### 流式传输

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

### 代理友好的循环

最简单顺畅的服务器循环是：

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 代理技能
- `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 的 fetch/文本提取
- `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

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

### 高级

| Path | 描述 |
|------|-------------|
| `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 特定检查的存根

### 机器人拦截检测

Navigate 自动检测拦截并返回结构化回退：```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

### 已测试站点

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

---

## 🔧 kuri-fetch

独立的 HTTP 抓取器 — 无需 Chrome、无需 Playwright、无需 npm。以约 2 MB 的二进制文件发布，内置 QuickJS 用于执行 JavaScript。```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

I'm ready to translate the content, but no actual Markdown content was provided in the input after "INPUT:". Please provide the chunk text to translate, and I'll proceed with the translation into Chinese following all the specified rules.```
🌰 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

### 命令

| 命令 | 描述 |
|---------|-------------|
| `tabs [--port N]` | 列出 Chrome 标签页 |
| `use <ws_url>` | 附加到一个标签页（保存会话） |
| `open [url] [--port N]` | 打开新标签页（可选择导航至 url） |
| `status` | 显示当前会话 |
| `go <url>` | 导航至 URL |
| `snap [--interactive] [--json] [--text] [--depth N]` | A11y 快照，保存 `eN` 引用 |
| `click <ref>` | 按引用点击元素（CDP 鼠标事件，兼容 React） |
| `type <ref> <text>` | 向元素输入文本（逐字符按键事件，兼容 React） |
| `fill <ref> <text>` | 填充输入值 |
| `select <ref> <value>` | 选择下拉选项 |
| `hover <ref>` | 悬停在元素上 |
| `focus <ref>` | 聚焦元素 |
| `scroll` | 滚动页面 |
| `viewport [width height]` | 获取或设置视口尺寸 |
| `eval <js>` | 执行 JavaScript |
| `text [selector]` | 获取页面文本 |
| `shot [--out file.png]` | 截图 |
| `back` | 后退 |
| `forward` | 前进 |
| `reload` | 重新加载当前页面 |
| `cookies` | 列出带安全标志的 Cookie |
| `headers` | 检查安全响应头 |
| `audit` | 完整安全审计 |
| `storage [local\|session\|all]` | 导出 localStorage / sessionStorage |
| `jwt` | 从 Cookie 和存储中提取并解码 JWT |
| `fetch <method> <url> [--data <json>]` | 使用页面 Cookie 进行带认证的 fetch |
| `probe <url-template> <start> <end>` | IDOR 探测：遍历 URL 中的数字 ID |
| `grab <ref>` | 点击引用，拦截 `window.open`，在标签页内跟随重定向 |
| `wait-for-tab [--port N]` | 轮询新标签页，自动切换会话 |
| `stealth` | 应用反检测补丁 |
| `set-header <name> <value>` | 为所有请求添加自定义标头 |
| `show-headers` | 显示已存储的额外标头 |
| `clear-headers` | 移除所有额外标头 |
---

## 📱 kuri-mobile（iOS + Android）

用于驱动 iOS 模拟器、真实 iPhone（列出 + 启动/终止）以及 Android 设备/模拟器的原生 Zig CLI——灵感来自 [`mobile-device-mcp`](https://github.com/srmorete/mobile-device-mcp)，使用 Zig 重新实现，构建路径中不涉及 Bun/Node/Gradle/Xcode。```bash
cd kuri-mobile && zig build && cp zig-out/bin/kuri-mobile ../zig-out/bin/

# The main `kuri` binary forwards android/ios subcommands to kuri-mobile:
kuri ios list-devices                              # sims + real devices (usbmuxd, native)
kuri ios openurl https://example.com               # navigate Safari
kuri ios screenshot out.png                        # auto-picks booted sim
kuri ios launch com.apple.Preferences

kuri android list-devices                          # native Zig adb wire-protocol client
kuri android tap 540 1200
kuri android swipe 100 1500 100 500
kuri android screenshot phone.png
kuri android uitree                                # flat element list via uiautomator dump

**标头审计** — 检查目标发送了哪些安全标头：```bash
kuri-agent go https://target.example.com
kuri-agent headers
# → {"url":"https://...","status":200,"headers":{
#     "content-security-policy":"default-src 'self'",
#     "strict-transport-security":"max-age=31536000",
#     "x-frame-options":"(missing)",
#     "x-content-type-options":"nosniff", ...}}

**跨账户轨迹** — 使用 `eval` 以不同令牌重放 API 调用：```bash
# After login, grab the auth token from localStorage
kuri-agent eval "localStorage.getItem('token')"

# Probe a resource ID with the current session
kuri-agent eval "fetch('/api/assessments/42').then(r=>r.status)"

# Check for IDOR: does a different user's resource return 200 or 403?
kuri-agent eval "fetch('/api/assessments/99').then(r=>r.status)"

---


## 🏗 架构```
┌──────────────────────────────────────────────────────────┐
│                     HTTP API Layer                        │
│         (std.http.Server, thread-per-connection)          │
├──────────────┬──────────────────┬────────────────────────┤
│   Browser    │  Crawler Engine  │   kuri-fetch / browse   │
│   Bridge     │                  │   (standalone CLIs)     │
├──────────────┼──────────────────┼────────────────────────┤
│ CDP Client   │ URL Validator    │ std.http.Client         │
│ Tab Registry │ HTML→Markdown    │ QuickJS JS Engine       │
│ A11y Snapshot│ Link Extractor   │ DOM Stubs (Layer 3)     │
│ Ref Cache    │ Text Extractor   │ SSRF Validator          │
│ HAR Recorder │                  │ Colored Renderer        │
│ Stealth JS   │                  │ History + REPL          │
├──────────────┴──────────────────┴────────────────────────┤
│  Chrome Lifecycle Manager                                 │
│  (launch, health-check, auto-restart, port detection)     │
└──────────────────────────────────────────────────────────┘

---

## ⚙️ 配置

| Env Var | 默认值 | 描述 |
|---------|---------|-------------|
| `HOST` | `127.0.0.1` | 服务器绑定地址 |
| `PORT` | `8080` | 服务器端口 |
| `CDP_URL` | *(none)* | 连接到现有的 Chrome（`ws://...` 或 `http://127.0.0.1:9222`） |
| `KURI_SECRET` | *(none)* | API 请求的认证密钥 |
| `STATE_DIR` | `.kuri` | 会话状态目录 |
| `REQUEST_TIMEOUT_MS` | `30000` | HTTP 请求超时 |
| `NAVIGATE_TIMEOUT_MS` | `30000` | 导航超时 |
| `STALE_TAB_INTERVAL_S` | `30` | 过期标签页清理间隔 |
| `NO_COLOR` | *(none)* | 禁用彩色 CLI 输出 |

---

## 💰 Token 成本

对于一个 50 页的监控任务（来自 Pinchtab 基准测试）：

| 方法 | Tokens | 成本（$） | 最适合 |
|--------|--------|----------|----------|
| `/text` | ~40,000 | $0.20 | 适合阅读为主（比截图便宜 13 倍） |
| `/snapshot?filter=interactive&format=compact` | ~40,000 | $0.20 | 低 Token 元素交互 |
| `/snapshot` (完整) | ~525,000 | $2.63 | 完整页面理解 |
| `/screenshot` | ~100,000 | $1.00 | 视觉验证 |

---

## 🤝 贡献

在提交大型 PR 之前，请先打开一个 issue，以便我们就方案达成一致。

---```bash
git clone https://github.com/justrach/kuri.git
cd kuri
zig build test         # 252+ tests must pass
zig build test-fetch   # kuri-fetch tests (69 tests)
zig build test-browse  # kuri-browse tests (22 tests)