CrawlForge MCP v6.6.0: sesi pelayar yang kekal terbuka

Sesuatu ejen tidak pernah melihat halaman yang bakal diklik olehnya. scrape_with_actions tetap memintanya menamakan sehingga 20 tindakan terlebih dahulu — taip ke dalam #user, klik .btn-primary, tunggu 1000ms — kemudian menutup pelayar sebaik panggilan itu pulang. Teka salah pada langkah 3, rantaian berhenti di situ, hasilnya pulang dengan success: false, dan 5 credits itu sudah pun hilang.

CrawlForge MCP v6.6.0 membetulkan gelungnya, bukan tekaannya. Alat browser_session baharu — alat kami yang ke-31 — mengekalkan satu halaman pelayar sebenar hidup antara panggilan alat, jadi ejen boleh membuka halaman, melihatnya, bertindak atas apa yang dilihatnya, melihat semula, dan membaca hasilnya. Bahagian melihat itulah yang penting, dan ia ada namanya: snapshot.

Isi kandungan

• Apa yang dihantar
• Mengapa rantaian sekali jalan bertindak membuta
• Snapshot: ejen melihat sebelum bertindak
• Gelung sesi, dari mula ke akhir
• Ref gagal dengan lantang, bukan senyap
• Snapshot turut masuk ke scrape_with_actions
• Berapa kos satu sesi
• Had, dinyatakan terus terang
• Satu sesi daripada CLI
• Bila guna yang mana
• Cara naik taraf

Apa yang dihantar

v6.6.0 ialah satu alat dan satu primitif:

• browser_session — satu alat tunggal dengan enum operation: open, snapshot, act, read, screenshot, close, list. Halaman itu, cookies-nya dan log masuknya kekal antara panggilan sehingga sesi tamat tempoh.
• snapshot — pepohon bergaya kebolehcapaian bagi halaman hidup, di mana setiap elemen interaktif membawa ref yang stabil (@e1, @e2). selector mana-mana tindakan menerima ref sebagai ganti pemilih CSS.
• Bilangan alat naik daripada 30 kepada 31, pada kedua-dua permukaan: MCP dan API REST.
• Sebuah skill ejen crawlforge-browser-sessions dan perintah CLI crawlforge browser turut dihantar bersamanya.

Tiada apa-apa dinamakan semula dan tiada alat sedia ada berubah bentuk atau harga, jadi ini naik taraf yang boleh terus pakai.

Mengapa rantaian sekali jalan bertindak membuta

scrape_with_actions ialah alat yang baik dengan satu had struktur: tatasusunan tindakan ditulis sebelum apa-apa sempat dimuatkan. Ejen memilih #login-email atau input[name="email"] atau .form-field:first-child daripada ingatan tentang rupa borang log masuk lazimnya, bukan daripada borang log masuk ini.

Apabila salah satu tekaan itu tersasar, ActionExecutor menghentikan rantaian — continueOnError lalai kepada false — dan alat itu memulangkan hasil yang membawa success: false beserta ralatnya, bukannya melontar. Pengebilan mengikut panggilan, bukan keputusannya, jadi 5 credits itu dibelanjakan pada rantaian yang sampai ke tindakan ketiga sahaja.

Mod kegagalannya bukan kosnya. Masalahnya, langkah ejen seterusnya ialah meneka semula, dengan maklumat yang tidak lebih daripada kali pertama. Alat sekali jalan tidak dapat memberitahunya apa yang ada dalam halaman itu, kerana pelayarnya sudah tiada apabila hasilnya sampai.

Snapshot: ejen melihat sebelum bertindak

snapshot menyusuri DOM hidup dan mengeluarkan satu baris berinden bagi setiap nod bermakna, dimodelkan pada pepohon kebolehcapaian — peranan, nama boleh capai, dan bagi nod interaktif satu ref:

[document] "Sign in"
  @e1 [textbox] "Email"
  @e2 [textbox] "Password"
  @e3 [button] "Sign in"
  [link] "Forgot password?"

Dua sifat menjadikannya berguna dan bukan sekadar hiasan. Nod struktur (tajuk, mercu tanda, borang) muncul sebagai konteks tetapi tidak mendapat ref, kerana ia bukan sasaran. Dan setiap ref disokong oleh atribut data-cf-ref yang dicap pada elemen semasa susuran itu, jadi @e1 menyelesai kepada pemilih [data-cf-ref="e1"] biasa dan berfungsi dengan setiap laluan tindakan sedia ada — termasuk kod tingkah laku manusia pelayar stealth, yang menerima rentetan pemilih mentah.

Kami menulis susuran itu sendiri dan bukannya membalut ariaSnapshot() Playwright, yang mengeluarkan YAML tanpa sebarang ref elemen, mahupun page._snapshotForAI(), iaitu API peribadi yang kami tidak akan bergantung padanya.

interactive_only lalai kepada true dan max_nodes lalai kepada 200, jadi halaman aplikasi dengan 4,000 elemen pulang sebagai senarai yang benar-benar boleh dibaca oleh ejen.

Gelung sesi, dari mula ke akhir

Ini satu log masuk dan satu bacaan, menggunakan pakej crawlforge-sdk. Lima panggilan, satu halaman pelayar, satu set cookies.

// npm install crawlforge-sdk
import { CrawlForge } from 'crawlforge-sdk';

const client = new CrawlForge({ apiKey: process.env.CRAWLFORGE_API_KEY });

// 1. Open the session (3 credits). One API key may hold one session at a time.
const opened = await client.browserSession({
  operation: 'open',
  url: 'https://app.example.com/login',
  ttl: 600
});

const { sessionId } = opened.data as { sessionId: string };

try {
  // 2. Look before acting (1 credit). Every interactive element comes back
  //    with a stable ref, so the next call targets what is actually there.
  const seen = await client.browserSession({ operation: 'snapshot', session_id: sessionId });
  console.log((seen.data as { snapshot: { tree: string } }).snapshot.tree);

  // 3. Act on those refs in a separate call (1 credit) — same page, same cookies.
  await client.browserSession({
    operation: 'act',
    session_id: sessionId,
    actions: [
      { type: 'type', selector: '@e1', text: 'user@example.com' },
      { type: 'type', selector: '@e2', text: 'secret123' },
      { type: 'click', selector: '@e3' },
      { type: 'wait', duration: 1000 }
    ]
  });

  // 4. Read the page the login landed on (2 credits) — the live DOM with the
  //    session's cookies, not a fresh fetch of the URL.
  const page = await client.browserSession({
    operation: 'read',
    session_id: sessionId,
    formats: ['markdown']
  });
  const { title, content } = page.data as { title: string; content: { markdown: string } };
  console.log(title, content.markdown.length);
} finally {
  // 5. Close it rather than waiting for the TTL (1 credit).
  await client.browserSession({ operation: 'close', session_id: sessionId });
}

Langkah 4 wajar direnung. read mengekstrak daripada halaman yang sedang dipegang oleh sesi itu, bukan daripada pengambilan semula URL-nya — pengambilan semula akan tiba tanpa cookies sesi itu dan sebelum segala yang telah diklik olehnya, iaitu seluruh sebab untuk memiliki satu sesi. Formatnya ialah markdown, html, text dan json, dan kamu boleh meminta beberapa sekali gus.

Ref gagal dengan lantang, bukan senyap

Ref dibatalkan oleh navigasi. Itu bukan kaveat, itu reka bentuknya: ref yang terselamat daripada pertukaran halaman akan menuding kepada elemen yang kebetulan ketiga dalam dokumen baharu, dan ejen akan mengkliknya tanpa sedar.

Jadi jadual ref itu tinggal dalam WeakMap berkunci halaman dan dikosongkan pada setiap navigasi bingkai utama. Bertindak atas ref basi dan kamu mendapat sebab serta penyelesaiannya, bukan misteri:

Stale element ref @e3: the page navigated since the last snapshot —
take a new snapshot before acting on refs.

Ref yang tidak dikenali sama jelasnya: "Unknown element ref @e9: the current snapshot has 4 refs (@e1-@e4) — take a new snapshot." Ejen boleh bertindak atas kedua-dua mesej itu sendiri. Klik tersilap yang senyap ialah kegagalan yang kami belanjakan bajet reka bentuk untuk mengelakkannya.

Snapshot turut masuk ke scrape_with_actions

Kamu tidak perlukan sesi untuk melihat dahulu. snapshot turut dihantar sebagai jenis tindakan di dalam scrape_with_actions, jadi rantaian sekali jalan pun boleh memerhati, kemudian bertindak atas ref yang dihasilkan oleh snapshot-nya sendiri, dalam panggilan 5 credits yang sama:

{
  "url": "https://news.ycombinator.com/login",
  "actions": [
    { "type": "snapshot" },
    { "type": "type", "selector": "@e1", "text": "reader" },
    { "type": "click", "selector": "@e3" }
  ]
}

Itu merangkumi kes biasa apabila ejen perlu melihat halaman tetapi keseluruhan aliran masih muat dalam satu panggilan. Capai sesi apabila aliran itu tidak muat: apabila keputusan kemudian bergantung pada apa yang dipulangkan oleh langkah terdahulu, atau apabila log masuk mesti bertahan merentasi beberapa bacaan.

Berapa kos satu sesi

browser_session berharga mengikut operasi, kerana satu sesi ialah banyak panggilan dan harga rata akan mengenakan siling kepada setiap operasi murah:

Aliran log masuk di atas berjumlah 8 credits: 3 + 1 + 1 + 2 + 1. Tambah snapshot semula yang dituntut oleh navigasi selepas log masuk, jadilah 9. Satu panggilan scrape_with_actions yang cuba melakukan perkara sama ialah 5 — dan, pada borang yang tidak pernah dilihatnya, jauh lebih berkemungkinan membelanjakan 5 itu untuk apa-apa pun tidak.

Rujukan alat menerbitkan browser_session pada kadar rata 3 credits. Itu harga open, dan ia siling dan bukan kadar: laluan REST menempah 3 sebelum badan permintaan sempat dibaca, kemudian menolak kos sebenar operasi itu setelah panggilan berjaya. Kamu tidak pernah dicaj melebihi angka yang diterbitkan, dan lazimnya kurang. Credits datang daripada kolam yang sama seperti setiap alat lain — lihat pelan dan pakej credits.

Had, dinyatakan terus terang

Satu sesi memegang infrastruktur sebenar, jadi hadnya juga nyata:

• Ia tamat tempoh. ttl lalai kepada 600 saat dari open (julat 30-3600) dan activity_ttl kepada 300 saat sejak penggunaan terakhir (julat 10-3600), mana-mana yang tiba dahulu. Tutup sesi apabila selesai, jangan biarkan ia luput sendiri.
• Satu pada satu masa pada API terhos. Satu API key REST boleh memegang satu sesi; pemasangan stdio dan hos sendiri mengekalkan lalai tiga. Itu aritmetik, bukan berhati-hati — seorang pelanggan yang memegang tiga sesi akan menduduki seluruh kapasiti sesi terhos.
• Tiada executeJavaScript pada permukaan terhos. Skrip sewenang-wenangnya dalam pelayar di atas infrastruktur kami ialah perkara berbeza daripada skrip sama pada komputer riba kamu, jadi ia ditolak melalui pengangkutan jauh. Guna tindakan click, type, select dan press, atau jalankan MCP server secara setempat melalui stdio.
• Setiap navigasi dipagar semula. Sesi berpanjangan ialah primitif navigasi yang boleh diulang, jadi setiap navigate dalam sesi menjalankan semula pengawal SSRF, senarai sekatan hos dan semakan robots.txt. Membuka sesi tidak membeli lompatan tanpa semakan.
• Log masuk tidak kekal antara sesi. Log masuk bertahan di dalam satu sesi. Tiada profil tersimpan yang dibawa daripada satu sesi ke sesi berikutnya.

Satu sesi daripada CLI

CLI menjalankan satu sesi lengkap bagi setiap invokasi — open, snapshot, langkah kamu, read, close — kerana sesi hidup dalam proses yang membukanya dan proses CLI berakhir apabila perintah itu berakhir:

# steps.json: [{"operation":"act","actions":[{"type":"click","selector":"@e2"}]}]
crawlforge browser https://news.ycombinator.com \
  --steps steps.json \
  --read --format markdown

Apabila sesi perlu hidup lebih lama daripada panggilan yang membukanya, guna alat MCP atau API REST. Tiada crawlforge browser open yang memulangkan id — halaman di sebalik id itu akan mati sebaik proses keluar.

Bila guna yang mana

Kedua-duanya tidak menggantikan scrape (2 credits), yang masih jawapan betul bagi halaman yang memapar tanpa disentuh. Dan browser_session paling sesuai untuk pasukan yang sasarannya ialah aplikasi dan bukan dokumen: papan pemuka di sebalik log masuk, bestari berbilang langkah, hasil carian bertapis yang hanya wujud selepas empat klik.

Cara naik taraf

npm install -g crawlforge-mcp-server@latest
crawlforge --version   # 6.6.0

Jika klien MCP kamu melancarkan pelayan dengan npx, ia akan mengambil v6.6.0 pada mula semula berikutnya. Tiada perubahan skema, bentuk output atau kos pada mana-mana alat sedia ada. Sejarah keluaran penuh ada pada changelog.

Mahukan ejen yang melihat sebelum mengklik? Mulakan percuma dengan 1,000 credits — 125 sesi log masuk dan bacaan penuh — dan baca rujukan API browser_session untuk setiap operasi, parameter dan medan respons.