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)

---

**أتمتة المتصفح والزحف إلى الويب لوكلاء الذكاء الاصطناعي. مكتوب بلغة Zig. بدون Node.js.**

أتمتة CDP · لقطات A11y · تسجيل HAR · مُجلب مستقل · متصفح طرفي تفاعلي · واجهة سطر أوامر وكيلية · اختبار أمني · التحكم بأجهزة 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:** تبقى إصدارات `ReleaseFast` الحالية لمعالجات Apple Silicon دون 2 ميغابايت لكل ملف تنفيذي، وقد قاس تشغيل جديد لـ Google Flights في 2026-04-23 **3,392 رمزًا** لحلقة `kuri-agent` كاملة (`go→snap→click→snap→eval`). يجب إعادة تشغيل فروقات الأدوات المتقاطعة في نفس البيئة قبل الاقتباس بنسبة مئوية.

---

## لماذا يتفوق Kuri مع الوكلاء

صُممت معظم أدوات المتصفح لمهندسي ضمان الجودة. أما Kuri فمصمم لحلقات الوكلاء: اقرأ الصفحة، أبقِ تكلفة الرموز منخفضة، تصرّف بناءً على مراجع مستقرة، ثم تابع.

- **135 نقطة نهاية HTTP** — تكافؤ كامل مع agent-browser و browser-use، من فحص React إلى Core Web Vitals.
- **رموز أقل بنسبة 7-12%** من agent-browser على صفحات حقيقية بفضل صيغة المراجع `@eN` والعرض بدون بادئة.
- **ملاحظات أخف بـ 44 ضعفًا** مع `/page/state` (48 رمزًا) مقابل اللقطة الكاملة (2,124 رمزًا) لنفس صفحة Google Flights.
- **تنفيذ دفعي** — يرسل `POST /batch` عدد N من الأوامر في نداء HTTP واحد، مما يلغي N-1 من الرحلات ذهابًا وإيابًا و N-1 من دورات LLM.
- **متوافق مع React** — أحداث فأرة CDP الموثوقة وأحداث المفاتيح لكل حرف تُشغّل `onClick` و `onChange` في React 18/19.

### رموز اللقطة: Google Flights `SIN → TPE`

تشغيل جديد في 2026-05-24 في مساحة العمل هذه، مقيس بـ `wc -c` وتقريب `chars/4`.

| الأداة / الوضع | الأحرف | ~الرموز | ملاحظة |
|---|---:|---:|---|
| `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]` |

### كفاءة الرموز: kuri مقابل agent-browser

| الصفحة | رموز kuri | رموز agent-browser | التوفير |
|---|---:|---:|---|
| 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 أحرف)
- بدون بادئة `- ` لكل سطر (توفير حرفين × عدد الأسطر)
- نفس الإزاحة، نفس تصفية العقد

### تكلفة سير العمل الكامل: `go → snap → click → snap → eval`

| الأداة | الرموز لكل دورة |
|---|---:|
| **kuri-agent** | **~3,400** |
| مع `/page/state` بدلًا من اللقطة الثانية | **~1,700** |
| مع `POST /batch` (الكل في نداء واحد) | **~1,700** (نفس الرموز، نداء HTTP واحد بدلًا من 5) |

### kuri مقابل libretto

[libretto](https://github.com/saffron-health/libretto) (Playwright + Node) هو أقرب منافس في تكلفة الرموز لكل خطوة. قيس وجهًا لوجه في 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 مللي ثانية مقابل 1,344–1,500 مللي ثانية (**أسرع بـ 13–376 ضعفًا** — خادم دائم مقابل Node لكل أمر) |
| رموز اللقطة، صفحة نموذجية | **kuri** | بسيطة 61 مقابل 151 (2.5×)، مقال 265 مقابل 363 (1.37×) — قواعد أكثر إحكامًا |
| رموز اللقطة، قائمة كبيرة | منقسم | kuri الافتراضي 4,424 مقابل 813 — kuri يصدر جميع المراجع الـ 259، وlibretto يقتطع افتراضيًا. مع `limit=5` يعرض kuri 555 رمزًا (**1.46× أقل من libretto**)، 34 مرجعًا + علامات `… +45 more` |
| المسار (تغذية، 9 نقرات) | **kuri**، بالكاد | 898 مقابل 939 رمزًا (قاعدة `limit=5` + حلقة الفرق مقابل حلقة التنفيذ) — تكافؤ إلى أفضلية طفيفة؛ خسارة الصباح بـ 5.1× كانت القاعدة غير المقتطعة |
| التشغيلات المتكررة | **libretto** | يترجم المسارات إلى سكربت Playwright → إعادات تشغيل بـ 0 رمز؛ kuri يعيد دفع الحلقة في كل تشغيل |

**ما كسبه kuri من دراسة libretto** (كله صدر في هذا الإصدار): حلقة الفرق أولًا (`take_snapshot_diff`، ~38 رمزًا/خطوة)؛ فرق تكيفي يتراجع إلى لقطة كاملة مع ترويسة `! page replaced` عند التنقل؛ أسطر إزالة للهوية فقط؛ لقطات شاشة تُكتب على القرص (يُعاد المسار، ولا تدخل البايتات السياق أبدًا)؛ `get_page_state` عبر MCP؛ وبعد إعادة كتابة `parseA11yNodes` كمشي شجرة DFS حقيقي — **اقتطاع القوائم الاختياري** (`/snapshot?limit=N`، سطر `… +K more` واحد لكل تشغيل مقتطع)، **إعادة الالتقاط النطاقي** (`scope=@ref`)، و**إزاحة التسلسل الهرمي**، مكشوفة أيضًا كـ `uid`/`limit` على MCP `take_snapshot`. مسار التغذية ذو النقرات التسع الذي كلف 44,285 رمزًا مع إعادات اللقطات الكاملة الساذجة يكلف **898** مع قاعدة مقتطعة + فروقات — أرخص بـ 49 ضعفًا، ويتجاوز 939 لدى libretto.

> تستخدم الجداول الأقدم أعلاه تقريب الرموز `chars/4`؛ بينما تستخدم مقارنة 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 ميغابايت)، وبيئة تشغيل Node.js، وسلسلة من تبعيات npm. وكيل الذكاء الاصطناعي لديك يريد فقط قراءة صفحة، والنقر على زر، ثم المتابعة.
**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`.
تأتي التنزيلات من فرع `release-channel` الذي يديره Kuri بنفسه. تُوقَّع ملفات 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.

- مثبّت الإصدار المستقر: `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`

### يدويًا

نزّل ملف tarball الخاص بمنصّتك من [بيان الإصدار المستقر](https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/latest.json) أو من [صفحة إصدارات GitHub](https://github.com/justrach/kuri/releases) وفكّ ضغطه إلى `$PATH` الخاص بك.

رابط التثبيت المستقر:

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

يتضمن المانيفست عناوين URL الدقيقة للأصول بالإضافة إلى مجاميع التحقق SHA-256 لمنصات `aarch64-linux` و`x86_64-linux` و`aarch64-macos` و`x86_64-macos`.

### دعم المنصات

| المنصة | الحالة |
|---|---|
| macOS (`aarch64`، `x86_64`) | ملفات ثنائية جاهزة، موقّعة وموثّقة |
| Linux (`aarch64`، `x86_64`) | ملفات ثنائية جاهزة |
| Windows (`x86_64`) | **تجريبي — الترجمة المتقاطعة فقط.** الأمر `zig build -Dtarget=x86_64-windows-gnu` مُتحقَّق منه في CI، لكن أتمتة Chrome، والتحوّل إلى خادم خفي (daemonization)، والإيقاف المعتمد على الإشارات، وتسجيل 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` إذا كنت تريد مساعدات Python فوق نفس واجهة HTTP.

إذا كان 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
```

### تصفح vercel.com في 4 أوامر

```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` | الاكتشاف التلقائي لتبويبات Chrome عبر CDP |
| `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` | لقطة شجرة A11y مع مراجع `eN`. استخدم `filter=interactive&format=compact` لحلقات الوكيل منخفضة الرموز. |
| `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` | إحضار التبويب إلى المقدمة |

### الإجراءات

| المسار | المعاملات | الوصف |
|------|--------|-------------|
| `GET /clear` | `ref` | مسح قيمة حقل الإدخال |
| `GET /selectall` | `ref` | تحديد كل النص في input/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` | خريطة API مع مقتطفات كود curl/fetch/python |
| `GET /cookies` | الحصول على ملفات تعريف الارتباط |
| `GET /cookies/set` | تعيين ملفات تعريف الارتباط |
| `GET /cookies/delete` | حذف ملفات تعريف الارتباط |
| `GET /cookies/clear` | مسح جميع ملفات تعريف الارتباط |
| `GET /headers` | تعيين رؤوس الطلبات المخصصة |
| `GET /intercept/start` | بدء اعتراض الطلبات |
| `GET /intercept/stop` | إيقاف اعتراض الطلبات |
| `GET /intercept/requests` | عرض الطلبات المعترضة |
| `GET /request/detail` | الحصول على جسم الاستجابة لمعرّف طلب |
| `GET /response/body` | جلب عنوان URL وإرجاع جسم الاستجابة |
| `GET /network` | إحصائيات حركة الشبكة |
| `GET /download` | تشغيل تنزيل ملف |

### التنقل والحالة

| المسار | الوصف |
|------|-------------|
| `GET /back` | الرجوع في المتصفح |
| `GET /forward` | التقدم في المتصفح |
| `GET /reload` | إعادة تحميل الصفحة |
| `GET /stop` | إيقاف تحميل الصفحة |
| `GET /pushstate` | تنقل SPA عبر history.pushState |
| `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` | حفظ ملفات تعريف الارتباط + التخزين كملف تعريف مصادقة مسمّى |
| `GET /auth/profile/load` | استعادة ملف تعريف مصادقة مسمّى في تبويب |
| `GET /auth/profile/list` | عرض ملفات تعريف المصادقة المحفوظة |
| `GET /auth/profile/delete` | حذف ملف تعريف مصادقة محفوظ |
| `GET /auth/extract` | استخراج رموز المصادقة (JWT، ملفات تعريف الارتباط، الرؤوس) |
| `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` | منح/رفض الأذونات (الموقع الجغرافي، الإشعارات، الحافظة) |

### السكربتات والحقن

| المسار | الوصف |
|------|-------------|
| `GET /script/inject` | حقن JavaScript في الصفحة (يستمر عبر التنقل) |
| `GET /initscript/remove` | إزالة سكربت تهيئة محقون مسبقًا |
| `GET /addstyle` | حقن ورقة أنماط CSS |
| `GET /expose` | كشف دالة مسمّاة لسياق JS في الصفحة |

### فحص React

| المسار | الوصف |
|------|-------------|
| `GET /react/tree` | شجرة مكونات React عبر خطاف DevTools |
| `GET /react/inspect` | خصائص وحالة مكون React |
| `GET /react/renders` | تتبع عرض React (بدء/إيقاف) |
| `GET /react/suspense` | حالة حدود React Suspense |

### التسجيل والأداء

| المسار | الوصف |
|------|-------------|
| `GET /recording/start` | تسجيل إجراءات المستخدم (نقر، إدخال، تنقل) |
| `GET /recording/stop` | إيقاف التسجيل + إرجاع سجل الإجراءات |
| `GET /vitals` | Core 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` | إيقاف المحلل |

### تصحيح الأخطاء

| المسار | الوصف |
|------|-------------|
| `GET /debug/enable` | تمكين HUD التصحيح داخل الصفحة ووضع التجميد الاختياري |
| `GET /debug/disable` | تعطيل HUD التصحيح داخل الصفحة |
| `GET /inspect` | فحص العنصر |
| `GET /errors` | جمع أخطاء JS |
| `GET /console` | قراءة سجلات وحدة التحكم |
| `GET /frames` | عرض إطارات الصفحة |
| `GET /frame` | التبديل إلى سياق iframe بالاسم أو عنوان URL |
| `GET /mainframe` | التبديل مرة أخرى إلى الإطار الرئيسي |
| `GET /diff/snapshot` | فرق مدمج `+`/`~`/`-` مقابل الاستدعاء السابق لهذا التبويب — حلقة الإجراءات الموفرة للرموز (يُشار إليها بـ `/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 |

### حلقة صديقة للوكيل

حلقة الخادم الأقل تعقيدًا هي:

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: أتمتة Chrome/CDP الإنتاجية مع الجلسات واللقطات والإجراءات وHAR وملفات تعريف الارتباط ولقطات الشاشة
- `kuri-fetch`: جلب/استخراج نص مستقل بدون Chrome
- `kuri-browse`: تصفح تفاعلي في الطرفية
- `kuri-agent`: أتمتة CLI قابلة للبرمجة النصية مقابل خادم Kuri
- `kuri-browser/`: وقت تشغيل متصفح Zig أصلي منفصل تجريبي لأعمال التكافؤ

---

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