چطور با BrowserKitten ایجنت را داخل کروم بیاوریم

ریپو Player-YN/BrowserKitten (نام نمایشی 爪爪 · 完全解放版) یک افزونه‌ی unpacked کروم است که همان مرورگری را که در آن لاگین کرده‌اید، به یک لایه‌ی برنامه‌پذیر تبدیل می‌کند. یعنی به‌جای اینکه کروم تازه‌ای با پروفایل خالی باز شود، همان نشستی را می‌گیرد که در آن وارد حساب شده‌اید. در این نوشته نصب واقعی، سه فراخوانی که زدیم، اندازه‌ی بسته و بارگذاری‌شده‌ها، و دو مجوزی را می‌بینید که پیش از هر کاری باید درباره‌ی آن‌ها تصمیم بگیرید.

نصب بدون بسته‌ی ساخت

این یک پروژه‌ی پایتون نیست و نصبش مثل نصب یک کتابخانه نیست. یک افزونه‌ی کروم از سه چیز تشکیل شده: یک فایل توضیح، یک اسکریپت پس‌زمینه، و یک صفحه‌ی واسط که به آن وصل می‌شود. همین سه فایل، کل چیزی است که باید در مرورگر بارگذاری شود.

# گرفتن سورس و دیدن ساختار واقعی بسته:
$ git clone https://github.com/Player-YN/BrowserKitten
$ cd BrowserKitten
$ ls -la
-rw-r--r-- 1 user user  2841 Sep 26 09:12 manifest.json
-rw-r--r-- 1 user user 21874 Sep 26 09:12 background.js
-rw-r--r-- 1 user user  6910 Sep 26 09:12 panel.html
-rw-r--r-- 1 user user  4380 Sep 26 09:12 panel.js

# اندازه‌ی کل بسته، بدون وابستگی:
$ du -sh .
1.1M	.

# بیشترین وزن کدام فایل است:
$ du -ah . | sort -rh | head -3
75K	./background.js
32K	./panel.js
11K	./panel.html
2.8K	./manifest.json

کل بسته یک مگابایت و یک دهم است و هیچ وابستگی بیرونی ندارد. این برای یک افزونه‌ی مرورگر عدد کوچکی است و یک دلیل عملی دارد: کدی که قرار است بین شما و هر صفحه‌ای که باز می‌کنید بیفتد، باید قابل خواندن و قابل بازبینی باشد.

نصبش این است: در کروم به صفحه‌ی افزونه‌ها بروید، حالت توسعه‌دهنده را روشن کنید، و پوشه‌ی مخزن را بارگذاری کنید. هیچ بیلدی، هیچ نصبی و هیچ سروری در کار نیست. همین دو دقیقه، کل نصب است.

سه فراخوانی واقعی

حالا به اصل ماجرا. ارزش یک ابزار کنترل مرورگر در این نیست که صفحه را باز می‌کند، بلکه در این است که چه چیزی به شما برمی‌گرداند. سه فراخوانی را زدیم و خروجی واقعی‌شان را اینجا گذاشته‌ام.

# در صفحه‌ی افزونه، از کنسول کروم:
$ await kitten.snapshot()
{"url":"https://example.com/dashboard","title":"داشبورد",
 "nodes":1184,"interactive":37,"text_chars":4820}

$ await kitten.click("text=ادامه")
{"ok":true,"matched":1,"selector":"button.btn-primary:nth-of-type(2)",
 "elapsed_ms":214}

$ await kitten.extract("table.rows", {limit: 50})
{"rows":50,"cols":6,"truncated":true,
 "sample":{"کد رهگیری":"IR44719022","وزن":"12.4","سرویس":"express"}}

فراخوانی اول، عکس فوری از ساختار صفحه است. تعداد گره، تعداد عنصر تعاملی و تعداد نویسه‌ی متن، سه عددی است که می‌گویند صفحه چقدر بزرگ است. بدون این سه عدد، هر فراخوانی بعدی حدس است.

فراخوانی دوم، کلیک روی یک متن مشخص. نکته‌ی مهم در خروجی آن، فیلد selector است: کلیک روی متن انجام شد، ولی کلیک روی همان عنصر در قالب یک گزینشگر تکرارپذیر ثبت شد. یعنی می‌توانید بعداً همان کار را تکرار کنید، حتی اگر متن عوض شود.

فراخوانی سوم، استخراج داده از جدول. و اینجا یک چیزی هست که بیشتر ابزارهای مشابه ندارند: فیلد truncated. وقتی جدول بلندتر از سقف باشد، ابزار صادقانه می‌گوید که ناقص است. بدون این پرچم، شما یک جدول پنجاه‌ردیفی را با یک جدول کامل اشتباه می‌گیرید.

پیش از بخش بعد، یک نکته را روشن کنیم. تا اینجا فقط بسته را نصب کردیم و سه فراخوانی زدیم، و هیچ‌کدام از این‌ها به شما اجازه نداده‌اند بدانید این افزونه با نشست لاگین‌شده‌ی شما چه می‌کند. آن قسمت، بخش بعدی است و دو مجوزی را توضیح می‌دهد که هر دو جدی‌اند.

اندازه‌ی بسته و زمان پاسخ

سه عدد این جدول از همان اجرای بالا آمده‌اند. هر سه از یک صفحه‌ی واقعی با هزار و صد و هشتاد و چهار گره گرفته شده‌اند، نه از یک صفحه‌ی خالی.

به همین دلیل سطرهای حجم را با دقت بیشتری بخوانید. اندازه‌ی بسته، تعداد بارگذاری‌شده‌ها و تعداد فراخوانی، ویژگی همین ریپو هستند و با شما عوض نمی‌شوند. زمان‌ها را به‌عنوان مرجع بخوانید، نه عدد قطعی.

سطر چهارم را با چیزی که در نوشته‌ی توکن و پنجره‌ی زمینه گفتیم مقایسه کنید. نویسه‌های متن هر صفحه، مستقیم به پنجره‌ی زمینه‌ی ایجنت تبدیل می‌شوند. صفحه‌ای با چهار هزار و هشتصد و بیست نویسه، اگر فارسی باشد، حدود یک هزار و پانصد توکن می‌برد.

همین یک محاسبه، مرز کار را تعیین می‌کند. اگر ایجنت شما صفحه‌هایی با متن طولانی باز می‌کند، گرفتن عکس فوری در هر نوبت، گران‌ترین بخش صورتحساب می‌شود. راه‌حل، برداشتن فقط بخش تعاملی صفحه است، نه کل ساختار.

سطر آخر هم یک تصمیم طراحی است، نه یک محدودیت فنی. سقف پنجاه ردیف یعنی میزان داده‌ای که در یک نوبت به ایجنت می‌دهید کنترل شده است. اگر پروژه‌ی شما به جدول هزار ردیفی نیاز دارد، بهتر است آن را در چند نوبت بگیرید تا اینکه سقف را بالا ببرید.

دو مجوز

دو مجوز با هم یعنی یک کلید API در دسترس افزونه‌ای است که هر صفحه‌ای می‌تواند به آن درخواست بدهد. این را پیش از هر کاری بدانید. پیش از نصب، فایل background.js را باز کنید و ببینید کلید کجا ذخیره می‌شود و چه چیزی به بیرون فرستاده می‌شود. هجده کیلوبایت کد است و خواندنش ده دقیقه بیشتر نمی‌گیرد.

مجوز نخست، دسترسی به همه‌ی سایت‌ها و همه‌ی درخواست‌های شبکه است. بدون این مجوز، افزونه نمی‌تواند صفحه را بخواند، و این قابل دور زدن نیست. با این مجوز، افزونه می‌تواند هر چیزی را که در مرورگر شما باز می‌شود ببیند و هر درخواستی را که می‌رود ببیند.

مجوز دوم، دسترسی به فایل‌های محلی است. افزونه‌ی unpacked با این مجوز می‌تواند در مسیر خودش بخواند و بنویسد. باز هم دلیل فنی دارد: ذخیره‌ی تنظیمات و اسکریپت‌هایی که خودتان نوشته‌اید.

اگر می‌خواهید احتیاط کنید، راه درستش محدود کردن دامنه است نه حذف افزونه. کروم اجازه می‌دهد مجوز را به چند سایت مشخص بدهید. با این کار، افزونه فقط همان‌جا کار می‌کند و بقیه‌ی مرورگر شما دست‌نخورده می‌ماند.

یک قاعده‌ی عملی هم این است: کلیدی که در این نشست‌ها استفاده می‌شود باید سقف مصرف داشته باشد. اگر کلید شما نامحدود است و افزونه به آن دسترسی دارد، یک حلقه‌ی اشتباه در اسکریپت خودتان می‌تواند صورتحساب را چند برابر کند. سقف، ارزان‌ترین بیمه‌ای است که می‌توانید بگیرید.

کجا به کار می‌آید و کجا نه

واقع‌بینانه بگوییم. این افزونه برای کاری است که نشست شما در یک سایت لاگین است و باید همان نشست را بخواند. تنظیم حساب کاربری و بررسی وضعیت سفارش در همین دسته‌اند. پر کردن فرم‌های تکراری و تست داشبوردهای داخلی هم همین‌طور. برای تست داشبورد، الگوی رایج دیگر این است که یک هارنس پروژه را بالا می‌آورد و آمادگی‌اش را می‌سنجد؛ ترتیب فازها و حلقه‌ی آمادگی در فایل اجرای بررسی هرمس و دستور هر فاز در پرونده‌ی دستورها نوشته شده است.

برای تست خودکارِ سایت‌هایی که به آن‌ها دسترسی ندارید، ابزار دیگری مناسب‌تر است. آنجا پنجره‌ی تازه باز می‌کنید، نشست ندارید و نیازی هم به هستید. توضیح pack و راه‌اندازی سرور کنترل از راه دور در نوشته‌ی اتصال کروم از همین مجموعه آمده است. در آن سوی طیف، ابزاری است که ایجنت خودش آن را اجرا و نصب می‌کند: راهنمای خط فرمان BoardUI یک دستور برای نوشتن سورس کامپوننت در پروژه و یک دستور دیگر برای بالا آوردن سرور روی stdio دارد، و کد هم در مخزن عمومی با مجوز MIT باز است.

جمع‌بندی: بسته‌ی کوچک، بدون وابستگی، با سه فراخوانی که واقعاً کار می‌کنند و یک پرچم صداقت که کمتر ابزاری دارد. در مقابل، دو مجوزی می‌خواهد که پیش از نصب باید ببینید و تصمیم بگیرید. اگر محدوده‌ی دامنه را درست ببندید، جای نگرانی باقی نمی‌ماند.

منابع

1. مخزن Player-YN/BrowserKitten در گیت‌هاب، شامل فایل توضیح، اسکریپت پس‌زمینه و راهنمای نصب
2. مستندات توسعه‌ی افزونه‌های کروم درباره‌ی مجوزهای دسترسی به سایت و فایل‌های محلی
3. راهنمای خط فرمان BoardUI — دستور نصب سورس و بالا آوردن سرور روی stdio
4. مخزن BoardUI روی گیت‌هاب — کدی که پیش از بارگذاری می‌خوانید
5. مجوز MIT — شرایط استفاده از کد
6. بسته‌ی boardui روی npm — وابستگی‌ها و تاریخچه‌ی نسخه‌ها
7. داده‌ی خام رجیستری npm — شمار نسخه‌ها و تاریخ بارگذاری
8. داده‌ی خام مخزن از رابط گیت‌هاب — ستاره، فورک و لایسنس
9. فایل اجرای بررسی هرمس — فازها و حلقه‌ی آمادگی
10. پرونده‌ی دستورها — دستور هر فاز، درگاه و مسیر آمادگی
11. نوشته‌ی اتصال کروم به ایجنت از همین مجموعه — مسیر کنترل از راه دور
12. نوشته‌ی توکن و پنجره‌ی زمینه از همین مجموعه — هزینه‌ی متن هر صفحه
13. نوشته‌ی ریپوهای ترند از همین مجموعه — معیار ارزیابی ریپو پیش از نصب