پلاگین opencode-browser-agent

opencode-browser-agent یک پلاگین OpenCode برای agent-browser است: اتوماسیون مرورگر برای ایجنت‌های AI با sessionهای persistent، ابزار توسعه‌دهنده، نصب‌کننده‌های چندپلتفورم (Windows / دسکتاپ Linux / VPS headless) و یک skill بازنویسی‌شده و policy-first.

پاسخ مستقیم

به Chrome درحال اجرایت از طریق --auto-connect متصل می‌شود (لاگین‌ها و تب‌هایت سرجایشان می‌مانند)، کشتن یا بستن مرورگر را ممنوع می‌کند، و اسکریپت‌های نصب/به‌روزرسانی یک‌دستوری برای Windows PowerShell و Linux/macOS دارد. یک backend اختیاری Obscura یک موتور CDP محلی سبک ارائه می‌دهد؛ Chrome پیش‌فرض می‌ماند.

چرا وجود دارد

• از مرورگر واقعی‌ات استفاده می‌کند، نه یک مرورگر دورریختنی. Chrome درحال اجرا را بازاستفاده کن — لاگین‌ها دست‌نخورده، پروفایل جدید نمی‌سازد.
• policy-first. یک skill بازنویسی‌شده نحوهٔ هدایت مرورگر توسط ایجنت را محدود می‌کند (pkill ممنوع، تب‌های نامرتبط را ندزدد، پیش‌فرض حریم خصوصی) به‌جای اینکه مدل خودش تصمیم بگیرد.
• نصب یک‌دستوری همه‌جا. Windows PowerShell، دسکتاپ Linux و VPS headless، با مسیر به‌روزرسانی یک‌دستوری هم‌تراز.
• موتور Obscura اختیاری. فقط opt-in، هرگز خودکار؛ به docs مراجعه کن.

نصب

پیش‌نیازها: OpenCode ≥ 2.0.0، agent-browser CLI (npm i -g agent-browser)، Chromium (agent-browser install؛ روی Linux با --with-deps).

از npm (ساده‌ترین):

{ "plugins": ["opencode-browser-agent"] }

از build محلی (Windows PowerShell):

powershell -ExecutionPolicy Bypass -File .\install.ps1        # نصب اولیه
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Update  # به‌روزرسانی

از build محلی (Linux / macOS):

bash install.sh            # نصب اولیه
bash install.sh --update   # به‌روزرسانی

Linux VPS (headless):

npm i -g agent-browser
agent-browser install --with-deps
agent-browser doctor
bash install.sh

سپس OpenCode را دوباره راه‌اندازی کن — پلاگین‌ها در startup بارگذاری می‌شوند.

اتصال به Chrome (CDP)

Chrome فقط وقتی با --remote-debugging-port=9222 راه‌اندازی شده باشد CDP را نمایش می‌دهد؛ آن پورت متعلق به یک پروسهٔ مرورگر است (پس پروفایل را هم مشخص می‌کند).

agent-browser --auto-connect open <url>            # بازاستفاده از Chrome درحال اجرا
agent-browser --auto-connect false --cdp 9222 open <url>  # اتصال با پورت

نکات شناخته‌شده:

• اگر ~/.agent-browser/config.json مقدار "autoConnect": true داشته باشد، هر فراخوانی --cdp با خطای “Cannot use –auto-connect and –cdp together” می‌افتد — با --auto-connect false جفتش کن.
• Chrome جدید ممکن است به GET /json/version با 404/empty پاسخ دهد در حالی که CDP کار می‌کند — هرگز با /json* تشخیص نده.
• یک DevToolsActivePort قدیمی باعث hang و سپس os error 10060 می‌شود — بررسی کن پورت واقعاً listen است.
• chrome://inspect «Target discovery settings» پورت debugging روی Chrome محلی باز نمی‌کند.

تشخیص read-only: ss -ltnp | grep 9222 (Linux) / Get-NetTCPConnection -LocalPort 9222 (Windows).

عیب‌یابی

• خطای “Browser not launched”: اول agent-browser doctor؛ روی Linux/container headless با agent-browser install --with-deps و agent-browser open --args "--no-sandbox" <url>.
• console/cookies خالی: همیشه --json بزن (agent-browser console --json).
• cookie banner شناسایی نشد: agent-browser snapshot -i سپس کلیک روی @ref متناظر.
• session از دست رفت: agent-browser close را اجرا نکن (cookieها پاک می‌شوند)؛ به URLهای جدید برو یا --auto-connect استفاده کن.
• element پیدا نشد: پس از ناوبری دوباره snapshot -i بزن برای @refهای تازه.

محدودیت‌ها

• اتصال CDP نیازمند Chrome راه‌اندازی‌شده با --remote-debugging-port است؛ --auto-connect فقط تأیید می‌کند یک Chrome پاسخ داده، نه اینکه کدام پروفایل/حساب. پیش از اقدام وابسته به حساب، هویت (پورت، PID، تب‌ها، حساب قابل‌مشاهده) را بررسی کن.
• VPS headless Chrome GUI ندارد؛ --auto-connect آنجا بی‌فایده است — مرورگر تازه راه‌اندازی کن.
• ورود بدون دسکتاپ: export cookieها / بازیابی auth.json / استفاده از --session-name.
• مشتق‌شده از opencode-agent-browser (MIT، Nicola Crotti)؛ به NOTICE مراجعه کن.

لینک‌ها

• بستهٔ npm: https://www.npmjs.com/package/opencode-browser-agent
• مخزن: https://github.com/BTF-Kabir-2020/opencode-browser-agent
• مستندات Obscura: https://github.com/BTF-Kabir-2020/opencode-browser-agent/blob/main/docs/obscura.md