Aira Browser

راه‌اندازی یکپارچگی بتای اتوماسیون مرورگر برای مرورگرهای سازگار با Chrome.

Aira Browser به یک نشست تعاملی AiraCode اجازه می‌ده توی همون مرورگری که خودت باهاش کار می‌کنی تب باز کنه، صفحه بخونه، فرم پر کنه، کلیک و تایپ کنه، اسکرین‌شات بگیره و console و network رو بررسی کنه — از طریق افزونهٔ خودِ AiraCode و یک host بومی. نه کروم headless جدا لازم داره، نه به افزونهٔ فروشندهٔ دیگه‌ای وابسته‌ست.

مسیر ارتباط

CLI مستقیم با مرورگر حرف نمی‌زنه. tool‌های MCP رو صدا می‌زنه، adapter اون‌ها رو روی یک unix socket محلی می‌فرسته، host بومی (یک حالت از همون باینری aira که Chrome اجراش می‌کنه) با native messaging به افزونه می‌رسونه، و افزونه کار رو داخل صفحه انجام می‌ده و نتیجه رو از همون مسیر برمی‌گردونه.

aira (CLI)
  -> MCP server  "aira-browser"        tools: mcp__aira-browser__*
  -> unix socket (local only)
  -> native host  ir.airacode.browser_bridge   (aira --chrome-native-host)
  -> extension    dmfmaldegmmmnecpjjjkmcobbokcghpe
  -> your tabs

هیچ pairing، لاگین یا bridge راه‌دوری در کار نیست؛ کل مسیر روی همین ماشین می‌مونه.

پیش‌نیازها

  • گوگل کروم یا یک مرورگر Chromium پشتیبانی‌شدهٔ دیگه (Chromium، Brave، Edge، Arc، Vivaldi، Opera).
  • AiraCode نصب‌شده روی همین ماشین. افزونه به‌تنهایی هیچ کاری نمی‌کنه.
  • یک نشست ترمینال local. tool‌های مرورگر به‌صورت پیش‌فرض در print mode و CI غیرفعالن.

نصب

  1. افزونه رو نصب کن. هم manifest مربوط به host بومی رو توی همهٔ پروفایل‌های Chromium که پیدا کنه می‌نویسه، هم افزونه رو توی ~/.aira/chrome-extension باز می‌کنه:
    aira extensions install browser

    aira extensions install بدون آرگومان هم افزونهٔ مرورگر و هم افزونهٔ ویرایشگر رو نصب می‌کنه، و aira extensions status نشون می‌ده چی نصبه و کجا. اجرای aira --chrome هم همین کار رو به‌عنوان اثر جانبی انجام می‌ده، ولی این دستور همون کار رو صریح و قابل‌تکرار می‌کنه.

  2. توی مرورگر chrome://extensions رو باز کن، Developer mode رو روشن کن، Load unpacked رو بزن و همون پوشه رو انتخاب کن:
    ~/.aira/chrome-extension

    توی دیالوگ فایل مک با ⌘⇧G می‌تونی مسیر رو مستقیم تایپ کنی. اگه AIRA_CONFIG_DIR رو ست کرده باشی، پوشه زیر همون مسیره نه ~/.aira.

  3. Chrome رو یک‌بار ببند و باز کن تا manifest جدید رو ببینه.
  4. روی آیکن AiraCode توی toolbar کلیک کن. وقتی یک نشست CLI وصل بشه، نقطهٔ وضعیت فیروزه‌ای می‌شه.

این مسیر بین نسخه‌ها ثابت می‌مونه: هر بار AiraCode آپدیت بشه محتوای همون پوشه با بیلد جدید جایگزین می‌شه، پس لازم نیست دوباره Load unpacked بزنی — فقط توی chrome://extensions افزونه رو reload کن.

دانلود مستقیم افزونه

اگه اون پوشه رو نداری — مثلاً هنوز aira extensions install رو اجرا نکردی یا نصبت به اینترنت نرسیده — می‌تونی خود افزونه رو مستقیم از airacode.ir بگیری. لازم نیست مخزن رو clone کنی یا bun نصب کنی:

curl -fsSLO https://airacode.ir/download/chrome-extension.tar.gz
mkdir -p ~/.aira/chrome-extension
tar -xzf chrome-extension.tar.gz -C ~/.aira/chrome-extension

روی ویندوز هم همین کار می‌کنه؛ tar از ویندوز ۱۰ به بعد داخل خود سیستم هست:

curl.exe -fsSLO https://airacode.ir/download/chrome-extension.tar.gz
mkdir "$env:USERPROFILE\.aira\chrome-extension"
tar -xzf chrome-extension.tar.gz -C "$env:USERPROFILE\.aira\chrome-extension"

بعدش دقیقاً همون مرحلهٔ Load unpacked بالا رو روی همین پوشه انجام بده. عمداً همون ~/.aira/chrome-extension پیشنهاد شده: اگه بعداً aira extensions install browser رو بزنی، خودش همین پوشه رو با نسخهٔ همراه CLI به‌روز می‌کنه و چون مسیر عوض نشده، Chrome افزونه رو گم نمی‌کنه.

اگه می‌خوای مطمئن شی همون بایت‌هایی رو گرفتی که ما منتشر کردیم، هشش رو با latest.json مقایسه کن — همون فایلی که CLI هم موقع دانلود خودکار چک می‌کنه:

shasum -a 256 chrome-extension.tar.gz
curl -s https://airacode.ir/download/latest.json

نصب از روی مخزن

اگه روی خود افزونه کار می‌کنی، بیلد از روی سورس رو لود کن تا تغییرهات رو ببینی:

cd apps/airacode-chrome
bun install
bun run build     # -> dist/
bun run dev       # همون بیلد، با watch

بعد apps/airacode-chrome/dist رو به‌جای مسیر بالا لود کن.

شناسهٔ افزونه با فیلد key توی manifest پین شده، برای همین بیلد unpacked، فایل .crx که خودت host می‌کنی، و لیست آیندهٔ Web Store همگی یک id دارن: dmfmaldegmmmnecpjjjkmcobbokcghpe. CLI دقیقاً همین id رو توی allowed_origins مجاز می‌کنه. اگه با کلید خودت بیلد می‌کنی، قبل از اجرای CLI AIRA_BROWSER_EXTENSION_ID رو ست کن (چندتایی رو با کاما جدا کن) تا id تو هم مجاز بشه.

فعال‌سازی

این یکپارچگی پشت گیت بتاست و پیش‌فرض خاموشه. سه راه برای روشن کردنش هست:

  • پرچم --chrome موقع اجرا (و --no-chrome برای خاموش کردنش).
  • فرمان /chrome داخل یک نشست تعاملی.
  • متغیر محیطی AIRA_ENABLE_BROWSER_INTEGRATION=1.
aira --chrome
aira --no-chrome

AIRA_ENABLE_BROWSER_INTEGRATION=1 aira

# Accepted spellings, first one that is set wins:
AIRA_ENABLE_BROWSER_INTEGRATION
AIRACODE_ENABLE_BROWSER_INTEGRATION
AIRA_CODE_ENABLE_BROWSER_INTEGRATION
CLAUDE_CODE_ENABLE_CFC          # legacy / سازگاری با نصب‌های قدیمی

ترتیب اولویت: پرچم --chrome/--no-chrome بالاتر از متغیر محیطیه، متغیر محیطی بالاتر از تنظیم Enabled by default توی /chrome، و اگه هیچ‌کدوم ست نباشه خاموشه. در نشست‌های غیرتعاملی (print mode، SDK، CI) فقط با --chrome صریح روشن می‌شه. مقدارِ falsy همون متغیرها هم پذیرفته می‌شه و صریحاً خاموشش می‌کنه.

tool‌ها

وقتی یکپارچگی روشنه، سرور MCP با نام aira-browser بالا میاد و این ۱۳ تا tool با پیشوند mcp__aira-browser__ در دسترس قرار می‌گیرن. skill همراهش هم aira-browser نام داره.

tabs_context
لیست تب‌های باز با id، عنوان و URL. بقیهٔ tool‌ها یک tabId اختیاری از همین‌جا می‌گیرن.
tabs_create
باز کردن یک URL در تب جدید.
tabs_close
بستن یک تب.
navigate
فرستادن یک تب به یک URL و صبر تا load شدنش.
read_page
خلاصهٔ heading‌ها و المان‌های تعاملی، هرکدوم با یک ref مثل [e12].
get_page_text
متن قابل‌مشاهدهٔ صفحه.
find
پیدا کردن المان با متن، label یا attribute؛ ref برمی‌گردونه.
form_input
ست کردن مقدار input، textarea، select و checkbox با ref.
computer
اسکرین‌شات، کلیک، تایپ، کلید، اسکرول، drag و wait.
javascript_tool
اجرای JavaScript داخل صفحه و برگردوندن نتیجه.
read_console_messages
خروجی console، با فیلتر regex یا فقط error‌ها.
read_network_requests
request‌های همون تب، با فیلتر URL یا فقط ناموفق‌ها.
resize_window
تغییر اندازهٔ پنجره‌ای که تب داخلشه.

ref‌ها (مثل e12) از read_page و find میان و تا وقتی المان از document بیرون نره یا صفحه navigate نکنه معتبر می‌مونن.

permission سایت‌ها

AiraCode فقط به سایتی دسترسی داره که خودت توی popup افزونه تأییدش کرده باشی. تا قبل از اون، هر tool call روی اون origin با خطای permission_required شکست می‌خوره و به مدل می‌گه از تو اجازه بگیره.

  • تأیید per-origin — یک‌بار https://example.com رو Allow می‌کنی و می‌مونه.
  • Block — می‌تونی یک origin رو کامل بلاک کنی؛ بلاک همیشه بر allow اولویت داره.
  • Allow every site — پیش‌فرض خاموشه و عمداً به‌عنوان گزینهٔ توصیه‌نشده برچسب خورده.
  • bypass از سمت CLI — نشستی که در حالت bypass شروع شده با هر request مقدار skip_all_permission_checks می‌فرسته. این per-request ـه، پس از عمر همون نشست فراتر نمی‌ره و popup هم نشون می‌ده داره اتفاق می‌افته.

permission‌ها همه توی popup افزونه (آیکن toolbar) مدیریت می‌شن؛ صفحهٔ وبی برای این کار وجود نداره. وقتی درخواستی معطل تأیید بمونه، badge افزونه تعدادش رو نشون می‌ده.

AIRA_BROWSER_PERMISSION_MODE=ask
AIRA_BROWSER_PERMISSION_MODE=follow_a_plan
AIRA_BROWSER_PERMISSION_MODE=skip_all_permission_checks

چی از صفحه بیرون می‌ره

  • خروجی console داخل خود صفحه توی یک ring buffer با اندازهٔ محدود نگه داشته می‌شه و فقط وقتی read_console_messages روی یک تب تأییدشده اجرا بشه تحویل داده می‌شه.
  • request‌های network فقط برای تب‌هایی ضبط می‌شن که AiraCode قبلاً بهشون دست زده.
  • ورودی synthetic ـه (dispatchEvent)، نه در سطح سیستم‌عامل؛ چیزی که isTrusted بخواد کار نمی‌کنه.
  • فقط document سطح بالا خونده می‌شه؛ محتوای iframe‌های cross-origin خونده نمی‌شه.

عیب‌یابی

  • اگه /chrome نیست، مطمئن شو AIRA_ENABLE_BROWSER_INTEGRATION=1 ست شده و نشست تعاملیه.
  • اگه افزونه شناسایی نشد، مطمئن شو ~/.aira/chrome-extension رو unpacked لود کردی، بعد Chrome رو ری‌استارت کن، بعد /chrome رو باز کن و Reconnect extension رو انتخاب کن.
  • اگه مطمئن نیستی چی نصبه، aira extensions status رو بزن — مسیر پوشه، نسخهٔ نصب‌شده، و اینکه از CLI عقب‌تره یا نه رو می‌گه.
  • اگه اون پوشه اصلاً وجود نداره، aira extensions install browser رو بزن. اگه اون هم گفت چیزی برای نصب نداره، یعنی این بیلد افزونه رو همراهش نداره و به فایل منتشرشده هم نرسیده — سراغ دانلود مستقیم برو؛ بیلد از روی مخزن فقط وقتی لازمه که داری روی خود افزونه کار می‌کنی.
  • اگه CLI می‌گه افزونه وصل نیست، احتمالاً manifest مربوط به host بومی هنوز خونده نشده — یک‌بار aira رو با tool‌های مرورگر فعال اجرا کن و بعد Chrome رو ری‌استارت کن.
  • اگه سایتی بلاک شده یا خطای permission_required می‌گیری، popup افزونه رو باز کن و همون origin رو Allow کن.
  • اگه با کلید بیلد خودت کار می‌کنی و host بومی وصل نمی‌شه، AIRA_BROWSER_EXTENSION_ID رو با id واقعی افزونه‌ات ست کن و دوباره CLI رو اجرا کن تا manifest بازنویسی بشه.
  • javascript_tool در main world صفحه اجرا می‌شه، پس یک script-src سخت‌گیر می‌تونه eval رو ببنده؛ خطاش برمی‌گرده و قورت داده نمی‌شه.
← قبلی
حالت headless / CI
بعدی →
فرمان‌ها