Mbbrowser ApiServer Rules 패키지

이 부분은 이 섹션에서 가장 중요한 부분입니다. 다음 Rules 패키지를 Cursor나 Antigravity에 주입하면, AI 모델이 모든 Mbbrowser ApiServer 인터페이스, 오류 코드 및 부록 매개변수를 완전히 마스터하게 되어 스크립트 작성 시 "환각(Hallucination)" 현상을 방지하고 정확한 코드를 생성할 수 있습니다.

---

IMPORTANT

Mbbrowser 자동화의 핵심 조언: 자동화 스크립트를 실행할 때 Mbbrowser 클라이언트 설정의 작동 모드가 **"로컬 모드(Local Mode)"**로 전환되어 있는지 확인하세요.

• 성능 향상: 로컬 모드는 네트워크 데이터 동기화(환경 데이터 업로드/다운로드)를 건너뛰어 자동화 시작 및 스크립트 실행 효율을 수십 배 향상시킵니다.
• 보안 팁: 매일 로컬 데이터를 백업하는 습관을 들이세요. 핵심 비즈니스 데이터(환경, 핑거프린트, 쿠키 등)는 MBDATA 디렉토리에 저장됩니다. 이 폴더를 정기적으로 외부 저장소에 백업해 두시기 바랍니다.

---

사용 방법

Cursor 사용자의 경우

1. Mbbrowser 스크립트 프로젝트 루트에 .cursor/rules/mbbrowser.mdc 파일을 생성합니다.
2. 아래의 전체 내용을 해당 파일에 복사하여 붙여넣고 저장합니다.
3. Cursor Chat을 다시 시작하거나(Restart) 새로운 Chat을 시작합니다.
4. 이후의 모든 대화에서 AI가 자동으로 이 지식을 활용하게 됩니다.

Antigravity 사용자의 경우

Antigravity(Google의 에이전트 우선 IDE)는 자체적인 규칙 시스템을 가지고 있으며 독립적인 .agent/rules/ 디렉토리를 사용합니다.

단계:

1. 프로젝트 루트(워크스페이스 또는 git 루트)에 .agent/rules/ 폴더를 생성합니다 (이미 있는 경우 그대로 사용).
2. 해당 폴더에 mbbrowser.md 파일을 생성합니다 (확장자는 반드시 .md여야 하며 순수 마크다운 형식이어야 함).
3. "Mbbrowser ApiServer Rules 패키지"의 사양, 인터페이스 세부 정보 및 코드 템플릿을 파일에 복사하여 붙여넣고 저장합니다.
4. Antigravity를 다시 시작하거나 프로젝트를 다시 엽니다 → 에이전트가 .agent/rules/ 하위의 모든 .md 파일을 자동으로 로드하여 시스템 프롬프트에 주입합니다(워크스페이스 수준에서 유효).

파일 구조 예시:

your-project/
└── .agent/
    └── rules/
        └── mbbrowser.md   ← 여기에 사양을 붙여넣으세요

추가 팁:

• 완전 동기화: 두 도구를 모두 사용하는 경우 .cursor/rules/mbbrowser.mdc(Cursor용) + .agent/rules/mbbrowser.md(Antigravity용) 두 경로를 모두 유지할 수 있습니다.
• 글자 수 제한: 규칙 파일 크기 제한은 약 12,000자입니다. 내용이 너무 많으면 여러 개의 .md 파일로 나누는 것이 좋습니다.
• 글로벌 적용: 모든 프로젝트에 글로벌하게 적용하려면 ~/.gemini/GEMINI.md에 배치하세요.

---

Mbbrowser ApiServer Rules 패키지

아래의 전체 내용을 복사하여 위에서 언급한 파일의 내용을 대체해 주세요.

# Mbbrowser (MBBrowser) + ApiServer 완전 개발 사양서

## 1. 제품 개입

> [!IMPORTANT]
> **성능의 비밀**: 대규모 자동화를 실행하기 전에 Mbbrowser 클라이언트가 **"로컬 모드"**인지 확인하세요. 클라우드 데이터 동기화를 건너뛰어 환경 실행 속도가 수십 배 빨라집니다. 동시에 **`MBDATA`** 비즈니스 데이터베이스 폴더를 정기적으로 수동 백업하세요.

Mbbrowser (MBBrowser)는 다중 계정 환경 격리를 위한 전문 안티 디텍션(Anti-association) 핑거프린트 브라우저입니다. 각 "환경(Session)"은 고유한 브라우저 핑거프린트, 프록시 IP, 쿠키, User-Agent, 시간대 및 언어를 가집니다.
ApiServer (apiserver.exe)는 Mbbrowser가 상주하는 로컬 HTTP API 서비스로, 스크립트가 프로그래밍 방식으로 브라우저 환경을 제어할 수 있게 해줍니다.

## 2. ApiServer 시작

```bash
apiserver.exe --port=8186 \
  --account=your_email@qq.com \
  --app_id=YOUR_APP_ID \
  --app_key=YOUR_APP_KEY \
  --hide=off \
  --return=on \
  --logs=on
```

매개변수 설명:
- port: 리스닝 포트, 기본값 8186.
- account: Mbbrowser 로그인 계정 (이메일).
- app_id: Mbbrowser 클라이언트 "개인 센터 → API 설정"에서 획득.
- app_key: Mbbrowser 클라이언트 "개인 센터 → API 설정"에서 획득.
- hide=off: 헤드 모드(디버깅 권장); hide=on은 헤드리스 백그라운드 모드.
- return=on: 콘솔에 API 응답 데이터 표시.
- logs=on: JSON 데이터를 로그 파일에 기록.

시작 성공 후 API 주소는 http://127.0.0.1:8186 입니다.

## 3. 통신 표준

- 모든 인터페이스는 HTTP POST 요청입니다.
- Content-Type: application/json.
- Base URL: http://127.0.0.1:8186.
- 성공 시 code=0; 실패 시 code는 음수이며 message에 오류 세부 정보가 포함됩니다.

표준 응답 형식:
```json
{
  "message": "Success",
  "code": 0,
  "data": { ... }
}
```

## 4. 계정 인증

### 4.1 계정 로그인 (계정 전환 시 사용)
POST /login
```json
{
  "APP_ID": "7e147176e1d756eb03c0e18e7b640c23",
  "APP_KEY": "YOUR_APP_KEY",
  "Account": "test01@qq.com",
  "return": "on",
  "logs": "on",
  "hide": "off"
}
```
성공 응답: {"msg": "Login Success", "status": 0, "data": "Login Account: test01@qq.com"}
참고: ApiServer는 시작 시 이미 인증 정보를 포함하고 있으므로 이 호출은 대개 불필요합니다.

### 4.2 ApiServer 종료
POST /api/v1/quit
요청 매개변수 없음. 성공 시 code=0을 반환하고 ApiServer를 닫습니다.

## 5. 핵심 인터페이스: 환경 수명 주기 관리

### 5.1 환경 열기 (가장 중요한 인터페이스)
POST /api/v1/browser/start
[최대 빈도: 무제한이나 --interval-seconds 제어 권장]

요청 매개변수:
```json
{
  "Session_ID": ["373808cb37bd63f5f7d92415e736e85f"],
  "isHeadless": false,
  "args": [
    "--disable-extensions",
    "--blink-settings=imagesEnabled=false",
    "--interval-seconds=2"
  ]
}
```

중요 사항:
- Session_ID는 배열(Array)이며, 다중 환경 동시 시작을 지원합니다.
- isHeadless=false는 창이 보이는 모드(Headed)이며, 기본값은 true입니다.
- --interval-seconds는 여러 환경 시작 시 사이 간격(초)을 제어합니다.
- --blink-settings=imagesEnabled=false는 이미지 로딩을 비활성화합니다(속도 향상).
- --disable-extensions는 브라우저 확장 프로그램을 비활성화합니다(자동화 시 일반적).

성공 응답 주요 필드:
```json
{
  "message": "Success",
  "code": 0,
  "data": {
    "listid": [{
      "Session_Name": "비즈니스 환경 01",
      "Session_ID": "373808cb37bd63f5f7d92415e736e85f",
      "browser_CDP_Port": 46973,
      "webdriver": "C:\\Users\\Admin\\houniao\\Driver\\100\\chromedriver.exe",
      "status": 0
    }],
    "total": 1
  }
}
```

[매우 중요] 프레임워크별 올바른 연동 방법:

Python Playwright:
```python
port = env_data["browser_CDP_Port"]
ws_endpoint = f"ws://127.0.0.1:{port}/json/version"
from playwright.sync_api import sync_playwright
pw = sync_playwright().start()
browser = pw.chromium.connect_over_cdp(ws_endpoint)
context = browser.contexts[0]          # 반드시 기존 컨텍스트를 사용해야 함! new_context() 사용 금지
page = context.pages[0] if context.pages else context.new_page()
```

JavaScript Playwright:
```javascript
const { chromium } = require('playwright');
const port = envData.browser_CDP_Port;
const wsEndpoint = `ws://127.0.0.1:${port}/json/version`;
const browser = await chromium.connectOverCDP(wsEndpoint);
const context = browser.contexts()[0];  // 반드시 기존 컨텍스트를 사용해야 함!
const page = context.pages()[0] || await context.newPage();
```

Python Selenium:
```python
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.chrome.service import Service
options = Options()
# debuggerAddress는 ws:// 없이 "IP:PORT" 형식입니다.
options.add_experimental_option("debuggerAddress", f"127.0.0.1:{env_data['browser_CDP_Port']}")
service = Service(executable_path=env_data['webdriver'])
driver = webdriver.Chrome(service=service, options=options)
```

JavaScript Puppeteer:
```javascript
const puppeteer = require('puppeteer');
const port = envData.browser_CDP_Port;
const wsEndpoint = `ws://127.0.0.1:${port}/json/version`;
const browser = await puppeteer.connect({
  browserWSEndpoint: wsEndpoint,
  defaultViewport: null
});
```

### 5.2 환경 닫기
POST /api/v1/browser/stop
```json
{
  "Session_ID": "373808cb37bd63f5f7d92415e736e85f"
}
```
참고: 이 인터페이스에서 Session_ID는 문자열(String)입니다.
성공: {"message": "Success", "code": 0, "data": {"action": "StopSession_ID", "status": 0}}

### 5.3 강제 종료
POST /api/v1/browser/kill
```json
{
  "Session_ID": "373808cb37bd63f5f7d92415e736e85f"
}
```
참고: 일반적인 중지(stop)는 일부 확장 프로그램 사용 시 프로세스가 남을 수 있으므로, 할당량 회수를 보장하기 위해 강제 종료(kill)를 권장합니다.

### 5.4 실행 상태 확인
POST /api/v1/browser/status
```json
{
  "Session_ID": ["4e6d0dca26ef42be9bc4472779d2550f"],
  "Actived_Type": 0
}
```
Actived_Type: 0=전체, 1=실행 중만, 2=미실행만.
Session_Actived=1이면 실행 중, 0이면 실행 중이 아님을 의미합니다.

## 6. 환경 쿼리 인터페이스

### 6.1 환경 목록 가져오기 (다차원 필터링)
POST /api/v1/session/listid
필터 매개변수 (전부 선택 사항):
- Session_Name, Session_GroupName, Proxy_Ip, Proxy_Type 등.
- CurrentPage, ListNum (기본 50, 최대 500).

성공:
```json
{
  "code": 0,
  "data": {
    "listid": ["373808...", "705cc..."],
    "total": 2
  }
}
```

### 6.2 특정 Session_ID의 설정 데이터 조회
POST /api/v1/session/id_container
```json
{
  "Session_ID": ["373808cb37bd63f5f7d92415e736e85f"],
  "Session_container_type": 1
}
```
Session_container_type: 1 = 전체 세부 정보 (browser_CDP_Port, webdriver, 전체 핑거프린트 포함).

## 7. 생성 및 업데이트 인터페이스

### 7.1 환경 생성
POST /api/v1/session/create
[최대 빈도: 분당 40회]
중요 매개변수 `Automatic_Configure`:
- `0` (권장): 빠른 생성 (Mbbrowser 비즈니스 라이브러리에서 핑거프린트 자동 매칭, 프록시 검증 안 함).
- `1`: IP 검증 포함; 생성 시간이 훨씬 더 오래 걸립니다 (요청 타임아웃을 68초 이상으로 설정).

### 7.2 기본 정보 업데이트
POST /api/v1/session/update
Session_Name, Session_Desc, Session_Group, Cookie (JSON 형식 문자열) 등을 포함합니다.

### 7.3 프록시 업데이트
POST /api/v1/session/proxy/update
[최대 빈도: 분당 50회]
지원 프로토콜: HTTP, HTTPS, SSH, SOCKS4/5, Oxylabs, Luminati, smartproxy, noproxy.

### 7.4 환경 삭제
POST /api/v1/session/delete
`Is_Delete_All: 1` 설정 시 전체 삭제를 수행합니다.

## 8. 쿠키(Cookie) 관리

### 8.1 쿠키 가져오기 (파일로부터)
POST /api/v1/session/import-cookie
```json
{
  "Session_ID": "session_id",
  "Cookie_File": "C:\\cookies\\account1.txt"
}
```
.txt (Netscape) 및 .json 형식을 지원합니다.

### 8.2 쿠키 내보내기 (파일로)
POST /api/v1/session/export-cookie
`Export_Cookie_File` 경로를 사용합니다. 확장자가 .json이면 JSON으로, 그렇지 않으면 Netscape로 내보냅니다.

## 9. 플러그인 관리
- POST /api/v1/plugin/list (전체 계정 플러그인 목록)
- POST /api/v1/session/id_plugin_list (환경 내 플러그인 목록)
- POST /api/v1/session/plugin_install (플러그인 설치)
- POST /api/v1/session/plugin_delete (플러그인 삭제)

## 10. 자동화 스크립트 관리
- POST /api/v1/session/id_script_list (환경 스크립트 확인)
- POST /api/v1/session/id_script_add (라이브러리에서 스크립트 할당)
- POST /api/v1/session/id_script_active (스크립트 활성화)

---

## 11. 전체 오류 코드표

### CODE (요청 레벨)
0 성공; -1 로그인 실패; -105 프록시 검증 실패; -106 유효하지 않은 시간대; -108 해상도 오류.

### Status (환경 열기 상태 필드)
0 성공; -7 이미 실행 중; -22 Session_ID를 찾을 수 없음.

## 12. 부록: 허용되는 값 (Legal Values)

### 12.1 SystemOS
Windows | iPhone | iPad | MacIntel | Android | Linux x86_64 등.

### 12.2 LanguageCode
zh-CN;zh;q=0.9 | en-US;en;q=0.9 | ja;q=0.9 | fr-FR;fr;q=0.9 등.

### 12.3 Session_Resolution
1920x1080 | 1440x900 | 1366x768 | 2560x1440 | 375x812 (iPhone X) 등.

## 13. 개발 개발 시 주의 사항

1.  **Session_ID 형식**: /start 및 /id_container는 배열(Array)을 사용하고, /stop, /update, /proxy/update는 문자열(String)을 사용합니다.
2.  **Playwright 컨텍스트**: 반드시 `browser.contexts[0]`을 사용하세요. 절대 `new_context()`를 사용하지 마세요.
3.  **Selenium**: `debuggerAddress` ("IP:PORT")를 사용하세요. ws를 사용하지 마세요.
4.  **동시성**: 일괄 실행 시 한 번에 최대 20개 환경까지 권장합니다.
5.  **상태 확인**: /start 이후 반드시 `data.listid[0].status`를 확인하세요.
6.  **프록시 검증**: /start 응답의 `Public_ip`를 사용하여 프록시 적용 여부를 확인하세요.
7.  **허용값 준수**: 해상도/언어/시간대는 부록의 허용값만을 사용하여 -106/-107/-108/-110 오류를 방지하세요.

## 14. 전체 Python 스크립트 템플릿

```python
"""
Mbbrowser + Playwright Python 자동화 템플릿
"""
import requests, threading
from playwright.sync_api import sync_playwright

def start_env(session_id: str):
    resp = requests.post("http://127.0.0.1:8186/api/v1/browser/start", 
                         json={"Session_ID": [session_id]}).json()
    return resp["data"]["listid"][0] if resp["code"] == 0 else None

def do_task(session_id):
    env_data = start_env(session_id)
    if not env_data: return
    with sync_playwright().start() as pw:
        # CDP를 통해 연결
        browser = pw.chromium.connect_over_cdp(f"ws://127.0.0.1:{env_data['browser_CDP_Port']}/json/version")
        context = browser.contexts[0] # 중요: 기존 컨텍스트 사용
        page = context.pages[0] if context.pages else context.new_page()
        page.goto("https://example.com")
        print(f"[{session_id}] 타이틀: {page.title()}")
        browser.close()
    requests.post("http://127.0.0.1:8186/api/v1/browser/stop", json={"Session_ID": session_id})

if __name__ == "__main__":
    sids = ["yoursid1", "yoursid2"]
    threads = [threading.Thread(target=do_task, args=(sid,)) for sid in sids]
    for t in threads: t.start()
    for t in threads: t.join()
```

---

구성 확인

구성을 마친 뒤 Chat에 다음과 같이 입력해 보세요:

Mbbrowser ApiServer를 사용하여 "TestGroup" 그룹의 모든 ID를 가져와서, 
최대 10개까지 동시 실행하고, Playwright를 사용하여 각 환경에서 https://example.com에 접속한 후 
스크린샷을 찍고 종료하는 Python 스크립트를 작성해 줘. 전체 오류 처리를 포함해서.

AI가 다음을 올바르게 사용하는지 확인하면 성공입니다:

• ✅ POST /api/v1/session/listid 사용
• ✅ /start 호출 시 Session_ID를 배열(Array)로 전달
• ✅ browser.contexts[0] 사용
• ✅ /stop 호출 시 Session_ID를 문자열(String)로 전달