הגדרה טכנית — browser-use · דאשבורד thelaw

חלק א׳ — גישה ל-Cloudflare KV

הבסיס: הקרדנציאלים נמצאים לוקלית

הקובץ ~/.secrets/cloudflare-kv.env קיים על המחשב של נדב ומכיל את ה-CF_API_TOKEN עם KV scope. זה ה-source of truth — לא שרת ספארק, לא nvision, לא משתנה סביבה גלובלי.

מה לא לעשות

לא להשתמש ב-/root/.spark_master_key בנvision — הטוקן שם חסר KV scope
לא להניח ש-spark_secrets.get_secret() מחזיר הכל — חלק מהמפתחות חסרים מה-cache
לא לבזבז זמן על SSH אם הצורך הוא רק קריאת KV

שלב 1 — טעינת קרדנציאלים

# טעינת משתני סביבה (CF_API_TOKEN, CF_ACCOUNT_ID)
source ~/.secrets/cloudflare-kv.env

מגדיר שני משתנים: CF_API_TOKEN (טוקן עם KV read/write scope) ו-CF_ACCOUNT_ID (חשבון אלון/Tal: 5bf57396a7de9b1331d2ed6093af01c9)

KV namespaces חשובים

Namespace	ID	תוכן	סטטוס
spark-secrets	215100443225476ab32bea1e6411ac69	כל המפתחות של Spark/nvision: LLMs, BROWSER_USE, GitHub, Supabase, Telegram ועוד	פעיל

שלב 2 — שליפת ערך ספציפי מ-KV

# helper function לשליפת ערך
get_kv() {
  local ns="$1" key="$2"
  curl -sS -H "Authorization: Bearer $CF_API_TOKEN" \
    "https://api.cloudflare.com/client/v4/accounts/$CF_ACCOUNT_ID/storage/kv/namespaces/$ns/values/$key"
}

# שליפת מפתח browser-use
BU_KEY=$(get_kv 215100443225476ab32bea1e6411ac69 BROWSER_USE_API_KEY)
echo "${BU_KEY:0:12}..."
# → bu_X4zK9go...

המפתח מתחיל ב-bu_ — בדיקה פשוטה לאימות: [[ "$BU_KEY" == bu_* ]] && echo "OK"

רשימת כל המפתחות ב-namespace (debug)

curl -sS -H "Authorization: Bearer $CF_API_TOKEN" \
  "https://api.cloudflare.com/client/v4/accounts/$CF_ACCOUNT_ID/storage/kv/namespaces/215100443225476ab32bea1e6411ac69/keys" | python3 -c "import sys,json; [print(k['name']) for k in json.load(sys.stdin)['result']]"

מחזיר רשימה של כל שמות המפתחות ב-namespace. שימושי כשרוצים לגלות מה זמין.

חלק ב׳ — שימוש ב-browser-use API

browser-use cloud מריץ דפדפן אמיתי + LLM (Claude Opus 4.7) פנימית. אין צורך במפתח LLM נפרד. הטיר החינמי כולל 3 דפדפנים מקבילים, proxies, ו-captcha solving.

שלב 3 — פתיחת session

curl -sS -X POST https://api.browser-use.com/api/v3/sessions \
  -H "X-Browser-Use-API-Key: $BU_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task":"נתח את האתר https://example.co.il — מבנה ניווט, hero, trust signals, CTAs. כתוב דוח מפורט."}'

# תשובה:
{"id":"ses_abc123","status":"running","liveUrl":"https://live.browser-use.com/session/ses_abc123",...}

שדות חשובים ב-body:

task — התיאור בשפה טבעית (עברית/אנגלית). ככל שמפורט יותר, תוצאה טובה יותר.
maxCostUsd — ברירת מחדל $5 לsession. אפשר להוריד: "maxCostUsd": 1
recordSession — ברירת מחדל true. לסשנים רגישים: "recordSession": false

שלב 4 — polling עד לסיום

SID=ses_abc123
# בדיקה חד-פעמית
curl -sS -H "X-Browser-Use-API-Key: $BU_KEY" \
  "https://api.browser-use.com/api/v3/sessions/$SID"

# polling loop — עד 120 שניות
for i in $(seq 1 12); do
  sleep 10
  STATUS=$(curl -sS -H "X-Browser-Use-API-Key: $BU_KEY" \
    "https://api.browser-use.com/api/v3/sessions/$SID" | \
    python3 -c "import sys,json; d=json.load(sys.stdin); print(d['status'], '|', (d.get('output') or '')[:100])")
  echo "[$i] $STATUS"
  echo "$STATUS" | grep -qE '^(stopped|finished|failed)' && break
done

שדות התשובה החשובים: status (running/finished/stopped/failed), output (תוצאת המשימה), lastStepSummary (מה הסוכן עשה לאחרונה), llmCostUsd (עלות), isTaskSuccessful (boolean).

Endpoints נוספים

# רשימת כל ה-sessions
curl -sS -H "X-Browser-Use-API-Key: $BU_KEY" https://api.browser-use.com/api/v3/sessions

# עצירת session
curl -sS -X DELETE -H "X-Browser-Use-API-Key: $BU_KEY" \
  https://api.browser-use.com/api/v3/sessions/$SID

# OpenAPI spec המלא
# https://docs.browser-use.com/cloud/openapi/v3.json

ה-liveUrl בכל session מאפשר צפייה בשידור חי בדפדפן. שימושי לדיבוג כשמשהו לא עובד.

מה מומלץ לשלוח כ-task

# ניתוח UX של אתר מתחרה
"בקר ב-https://www.example-law.co.il/ ונתח: (1) מבנה הניווט ומסע משתמש, (2) ה-hero — כותרת, CTA, תמונות, (3) trust signals — ביקורות, ניסיון, תעודות, (4) האם יש מחשבון/כלי אינטראקטיבי, (5) כתוב 3 המלצות שיפור. כתוב ב-Markdown."

# בדיקת redirect
"בקר ב-https://thelaw.co.il/old-url/ ובדוק לאן מגיעים אחרי כל ה-redirects. דווח על ה-URL הסופי וסטטוס HTTP."

# smoke test פשוט
"Navigate to https://example.com and return the H1 text"

זהירות: thelaw.co.il הוא read-only מוחלט — לא ללחוץ על שום כפתור שמשנה state (טפסים, login, wp-admin).

התקנה במחשב חדש — שחזור מלא

סקציה זו מספיקה לשחזור מלא של כל סביבת browser-use במחשב חדש, בלי להיכנס למחשב הנוכחי. כל מה שצריך נמצא כאן.

דרישות מוקדמות

Python 3.13+ — הגרסה שנדרשת לתאימות browser-use 0.12.x. במכונה הנוכחית: C:\Users\nadav\tools\python-3.13\python.exe. במחשב חדש — אפשר לנסות python --version; אם הגרסה נמוכה, להתקין מ-python.org/downloads.
Z.AI API Key — ZAI_API_KEY. הערך הנוכחי שמור ב-~/.secrets/cloudflare-kv.env (מחשב נדב) וב-Cloudflare KV תחת namespace spark-secrets (ראה חלק א׳). להוציא key חדש: z.ai → הרשמה → API Keys.
~600MB שטח דיסק — Playwright + Chromium ~179MB + חבילות Python.

שים לב

GLM-4.x → שגיאה 400 (חסר vision support). חייב להשתמש ב-glm-5.1 בלבד.
GLM-5 (הישן) עובד אך glm-5.1 זול יותר ומהיר יותר — אומת 2026-05-09.

שלב 1 — התקנת חבילות Python

# PowerShell — במחשב Windows
# $PY = נתיב ל-Python שלך (בדוק ב-"where python" / "python --version")
$PY = "C:\Users\nadav\tools\python-3.13\python.exe"  # שנה לנתיב שלך

# התקנת browser-use (כולל את כל ה-dependencies)
& $PY -m pip install browser-use

# התקנת Playwright runner
& $PY -m pip install playwright

# הורדת Chromium — ~179MB, פעם אחת בלבד
& $PY -m playwright install chromium

מה כל פקודה עושה:

pip install browser-use — מתקין browser-use 0.12.x + langchain + openai SDK (נדרש לממשק LLM)
pip install playwright — מתקין את ה-Python bindings לדפדפנים
playwright install chromium — מוריד את Chromium (~179MB) לתיקיית Playwright הלוקלית. חד פעמי.

שלב 2 — קונפיגורציית LLM: Z.AI / glm-5.1

למה glm-5.1 ולא Claude / GPT? browser-use שולח screenshot בכל צעד — חייב מודל עם vision support. glm-5.1 תומך ב-vision, עולה פחות מ-GPT-4o, מהיר, ואומת על עשרות tasks מ-thelaw. GLM-4.x — לא תומך ב-vision → שגיאה 400.

להוציא ZAI_API_KEY: z.ai → הרשמה → "API Keys" → צור key חדש.
איפה לשים: צור קובץ ~/.secrets/cloudflare-kv.env ובו שורה:

# קובץ: ~/.secrets/cloudflare-kv.env
ZAI_API_KEY=הכנס-כאן-את-המפתח-שלך
CF_API_TOKEN=...     # נדרש לגישה ל-BU Cloud (ראה חלק א׳)
CF_ACCOUNT_ID=5bf57396a7de9b1331d2ed6093af01c9

שלב 3 — דוגמת קוד מינימלית (smoke test)

שמור בקובץ test_bu.py והרץ:

# test_bu.py — smoke test ל-browser-use OSS
import asyncio, sys, io
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')

from browser_use import Agent, ChatOpenAI

ZAI_API_KEY = "הכנס-כאן-את-המפתח-שלך"  # או קרא מ-env: os.getenv("ZAI_API_KEY")

llm = ChatOpenAI(
    model="glm-5.1",                   # glm-5.1 — vision support, זול, מהיר
    api_key=ZAI_API_KEY,
    base_url="https://api.z.ai/api/paas/v4/",
    add_schema_to_system_prompt=True,   # GLM מחזיר JSON בתוך markdown
    dont_force_structured_output=True,  # GLM לא תומך ב-response_format=json_schema
    max_completion_tokens=None,         # GLM מכיר max_tokens, לא max_completion_tokens
)

async def main():
    agent = Agent(task="Go to https://example.com and return the exact text of the H1 heading.", llm=llm)
    result = await agent.run()
    print(result.final_result())

asyncio.run(main())

# הרצה ב-PowerShell
$env:PYTHONIOENCODING="utf-8"
& "C:\Users\nadav\tools\python-3.13\python.exe" test_bu.py
# תוצאה צפויה: "Example Domain"

תוצאה של smoke test מוצלח: הפלט יכיל "Example Domain" לאחר ~5-10 שניות. אם מוצלח — כל הסביבה עובדת.

תקלות נפוצות

תסמין	סיבה	פתרון
שגיאה 400 מה-API	שימוש ב-glm-4.x שלא תומך ב-vision	model="glm-5.1"
TypeError: max_completion_tokens	GLM מכיר רק max_tokens	max_completion_tokens=None
JSON parse error / output ריק	GLM מחזיר JSON בתוך markdown	dont_force_structured_output=True add_schema_to_system_prompt=True
playwright not installed	הותקן browser-use אבל לא Chromium	python -m playwright install chromium
UnicodeEncodeError בWindows	stdout לא UTF-8	$env:PYTHONIOENCODING="utf-8" + sys.stdout = io.TextIOWrapper(...)

להעתקה לקלוד אחר

הדבק את הטקסט כהודעה ראשונה לקלוד חדש — הוא יידע לעשות את כל הסטאפ בעצמו. (זהה לתוכן ב-LG Handoff)

# הוראות לקלוד — Setup browser-use

## הקשר
פרויקט thelaw.co.il — בנייה מחדש של אתר משרד עורכי דין. יש לנו גישה ל-browser-use cloud דרך Cloudflare KV.

## שלב 1 — טעינת קרדנציאלים
source ~/.secrets/cloudflare-kv.env
# מגדיר: CF_API_TOKEN, CF_ACCOUNT_ID

## שלב 2 — שליפת מפתח BU
BU_KEY=$(curl -sS -H "Authorization: Bearer $CF_API_TOKEN" \
  "https://api.cloudflare.com/client/v4/accounts/$CF_ACCOUNT_ID/storage/kv/namespaces/215100443225476ab32bea1e6411ac69/values/BROWSER_USE_API_KEY")
[[ "$BU_KEY" == bu_* ]] && echo "OK: ${BU_KEY:0:12}..." || echo "FAILED: $BU_KEY"

## שלב 3 — שגור session
curl -sS -X POST https://api.browser-use.com/api/v3/sessions \
  -H "X-Browser-Use-API-Key: $BU_KEY" -H "Content-Type: application/json" \
  -d '{"task":"<תיאור המשימה בשפה טבעית>"}'

## הערות חשובות
- WP הקיים (thelaw.co.il) = read-only מוחלט. לא ללחוץ על שום דבר שמשנה state.
- maxCostUsd ברירת מחדל = $5/session
- CF_ACCOUNT_ID = 5bf57396a7de9b1331d2ed6093af01c9 (אלון/Tal)
- KV namespace spark-secrets ID = 215100443225476ab32bea1e6411ac69

איך זה עובד — מ-KV ועד session