# Panda — Chế độ hỗ trợ TRÌNH DUYỆT từ xa (CDP relay)

> ## ⚡ DÀNH CHO CLAUDE CODE — điều khiển ngay
> Bạn được giao điều khiển trình duyệt từ xa tên `<TÊN>` (vd `gmpy`). Chạy trên máy có `ssh cloud`:
> ```bash
> ssh cloud "/opt/panda/panda browser ls"                 # kiểm tra <TÊN> có ONLINE không
> EP=$(ssh cloud "/opt/panda/panda browser url <TÊN>")    # lấy CDP endpoint (kèm token)
> ```
> **Cách 1 — cắm Playwright-MCP (khuyên dùng):** đăng ký rồi dùng các tool `browser_*`:
> ```bash
> claude mcp add panda-<TÊN> -- npx @playwright/mcp@latest --cdp-endpoint "$EP"
> ```
> **Cách 2 — Playwright trực tiếp:** `chromium.connectOverCDP(EP)` → `ctx=b.contexts()[0]` →
> dùng `ctx.pages()[0]` (tab người dùng đang mở) hoặc `ctx.newPage()`.
> **Lưu ý:** chụp `page.screenshot()` một tab MỚI phải gọi `page.bringToFront()` trước (tab nền không composite → treo).
> Khi đang điều khiển, Chrome máy đích hiện dải vàng "đang gỡ lỗi" — bình thường.


Điều khiển đầy đủ **trình duyệt Chrome** của máy đích từ xa (mở trang, click, gõ, đọc DOM,
screenshot, cookie/session) — **chỉ trong phạm vi trình duyệt**, không đụng chuột/bàn phím OS,
tệp hay ứng dụng khác. Tách biệt hoàn toàn với đường frp OS-level (RDP/SSH) của panda-support.

```
[Extension MV3 trên máy đích]  --WSS ra ngoài-->  [relay 127.0.0.1:8090 sau nginx]  <--CDP--  [Claude Code + Playwright-MCP]
   chrome.debugger.attach(tab)                       ghép cặp theo browser-id                    /cdp/<id>/<token>
```
Extension **chỉ gọi ra ngoài** (không mở cổng) → xuyên NAT, không cần IP tĩnh, không mở firewall.

---

## A. Cài trên máy đích (operator tự cài trên trình duyệt mình quản)

1. Mở https://connect.pandagamecenter.com/ → mục **③ 🌐 Điều khiển trình duyệt từ xa** → **Tải extension (.zip)**.
2. **Giải nén** → được thư mục `panda-browser-ext`.
3. Chrome → `chrome://extensions` → bật **Chế độ dành cho nhà phát triển** (Developer mode).
4. **Tải tiện ích đã giải nén** (Load unpacked) → chọn thư mục `panda-browser-ext`.
5. Bấm biểu tượng 🐼 → đặt **tên máy** (a–z 0–9 _ - , tối đa 32) → **Bật cho phép điều khiển**.

Popup báo *"Sẵn sàng — đã kết nối relay"* là xong. Không dùng Chrome Web Store, không cần policy.

> Chrome nhắc *"Tắt tiện ích ở chế độ nhà phát triển"* mỗi lần mở — bỏ qua được.
> Vài Chrome doanh nghiệp chặn dev-mode bằng policy → khi đó phải dùng Web Store/force-install (ngoài phạm vi bản này).

## B. Điều khiển (phía operator — Claude Code + Playwright-MCP)

Trên máy chủ panda (`ssh cloud`):

```bash
support browser ls              # liệt kê + trạng thái (ONLINE / DANG-DK / offline), số tab
support browser url  <tên>      # in endpoint CDP để cắm thẳng
support browser mcp  <tên>      # in lệnh Playwright-MCP (kèm dạng `claude mcp add`)
support browser rm   <tên>      # gỡ browser khỏi server
```

**Cắm vào Claude Code (khuyên dùng):**
```bash
claude mcp add panda-<tên> -- npx @playwright/mcp@latest --cdp-endpoint "$(support browser url <tên>)"
```
Sau đó trong Claude Code, các tool `browser_navigate`, `browser_click`, `browser_type`,
`browser_take_screenshot`, `browser_snapshot`… sẽ lái đúng trình duyệt đó.

**Hoặc dùng trực tiếp bằng Playwright:**
```js
const { chromium } = require('playwright');           // hoặc playwright-core
const b = await chromium.connectOverCDP('<endpoint từ: support browser url ...>');
const page = b.contexts()[0].pages()[0] ?? await b.contexts()[0].newPage();
await page.goto('https://…'); await page.screenshot({ path: 'x.png' });
```

Endpoint public dạng: `https://connect.pandagamecenter.com/cdp/<id>/<token>`
(chạy Claude Code trên panda-vps thì có thể thay bằng `http://127.0.0.1:8090/cdp/<id>/<token>`).

## C. Cách hoạt động (tóm tắt kỹ thuật)

- **Extension** attach `chrome.debugger` vào tab đang hoạt động → chỉ có phiên CDP **mức trang**.
- **Relay** *giả lập* domain `Target`/`Browser` mức trình duyệt (`Browser.getVersion`,
  `Target.setAutoAttach/getTargets/createTarget/attachToTarget`, định tuyến `sessionId`) để
  `Playwright.connectOverCDP` tin đang nói với một trình duyệt thật, rồi chuyển mọi lệnh mức-trang
  xuống `chrome.debugger`. Port từ `microsoft/playwright-mcp` (bản pre-V2 "raw CDP forward").
- Banner vàng chỉ hiện **khi đang có controller** (relay bảo extension attach lúc controller nối,
  detach khi rời).

## D. Định danh & bảo mật

- `browser-id` = UUID extension tự sinh, lưu `chrome.storage.local` (bền). Tên do người dùng đặt ở popup.
- `token` per-id sinh lúc enroll, lưu bảng `browsers` trong `/opt/panda/data/panda.db`.
  Điều khiển cần **cả id lẫn token** (nằm trong path `/cdp/<id>/<token>`).
- Extension nắm **toàn bộ phiên đăng nhập** của trình duyệt đó (Gmail, ngân hàng, admin…). Chỉ cài
  lên trình duyệt mình quản, có sự đồng ý. Tắt bất cứ lúc nào ở popup hoặc `support browser rm`.
- Chỉ chuyển **lệnh-dạng-dữ-liệu** CDP; không có interpreter chạy mã tuỳ ý từ server (tuân MV3).

## E. Sự cố thường gặp

| Hiện tượng | Nguyên nhân / xử lý |
|---|---|
| `support browser url` → connectOverCDP báo **offline / 503** | Extension chưa online. Kiểm `support browser ls`; mở popup bật lại; xem máy đích có mạng. |
| Không attach được tab | Tab đang là `chrome://…`, Web Store, PDF viewer → không gỡ lỗi được. Extension tự mở tab `about:blank` để điều khiển; hoặc chuyển sang một trang web thường. |
| Mất kết nối sau ~30s nhàn rỗi | Bình thường với MV3 (SW ngủ). Extension tự keepalive + reconnect; chờ vài giây. |
| Nhiều controller | Mỗi browser-id chỉ 1 controller tại một thời điểm; controller mới thay controller cũ. |

## F. Vận hành máy chủ (panda-vps)

- Relay: `systemctl status panda-cdp-relay` · log `journalctl -u panda-cdp-relay -f` · cổng `127.0.0.1:8090`.
- nginx: location `/ext` (extension WS + enroll) và `/cdp/` (controller WS + `/json/version`) trong site `connect`.
- Extension nguồn: `/opt/panda/browser/panda-browser-ext.zip` (phục vụ ở `/browser/ext.zip`).
- Bảng `browsers(id,name,token,created,last_seen)` trong `panda.db`. **Không** liên quan bảng `clients` (RDP/SSH).