# 浏览器使用规范

> 📅 创建日期：2026-02-13
> 📋 全局强制规范：所有技能中涉及浏览器操作时，必须遵守本文档

---

## 一、核心原则

| 原则 | 说明 |
|:---|:---|
| **使用系统默认浏览器** | 不硬编码任何特定浏览器，用 `open` 命令自动调用 |
| **复用已有会话** | 使用用户已登录的浏览器实例，保留 Cookie/登录态 |
| **禁止新建实例** | 不创建无痕/隔离/Headless 浏览器窗口 |
| **API 优先** | 能用 API 完成的，绝不启动浏览器 |

---

## 二、操作方式优先级

### 优先级 1：命令行 API 调用（最优先）

```bash
# 直接用 curl 调用 API，完全不需要浏览器
curl -X POST "https://api.example.com/endpoint" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'
```

```python
# Python requests 直接调 API
import requests
resp = requests.post(url, headers=headers, json=data)
```

### 优先级 2：系统默认浏览器打开 URL

```bash
# macOS 用 open 命令（自动调用系统默认浏览器）
open "https://example.com"

# 如果需要指定应用（不推荐，仅特殊情况）
# open -a "Safari" "https://example.com"
```

```python
import subprocess
# 用系统默认浏览器打开 URL
subprocess.run(['open', 'https://example.com'])
```

### 优先级 3：AppleScript 控制已打开的浏览器

```python
import subprocess

def get_default_browser_name():
    """获取默认浏览器名称"""
    import json, os
    r = subprocess.run(['plutil', '-convert', 'json', '-o', '-',
        os.path.expanduser('~/Library/Preferences/com.apple.LaunchServices/com.apple.launchservices.secure.plist')],
        capture_output=True, text=True)
    if r.returncode == 0:
        data = json.loads(r.stdout)
        for h in data.get('LSHandlers', []):
            if h.get('LSHandlerURLScheme') == 'https':
                bundle_id = h.get('LSHandlerRoleAll', '')
                # bundle ID → 应用名映射
                mapping = {
                    'com.google.chrome': 'Google Chrome',
                    'com.apple.safari': 'Safari',
                    'com.brave.browser': 'Brave Browser',
                    'com.microsoft.edgemac': 'Microsoft Edge',
                    'company.thebrowser.browser': 'Arc',
                    'com.bot.pc.doubao.browser': '豆包浏览器',
                    'org.mozilla.firefox': 'Firefox',
                }
                return mapping.get(bundle_id, bundle_id)
    return 'Safari'

def open_url_in_default_browser(url):
    """用系统默认浏览器打开 URL（复用已有窗口）"""
    subprocess.run(['open', url])

def get_current_url():
    """获取默认浏览器当前标签页 URL（AppleScript）"""
    browser = get_default_browser_name()
    if browser == 'Google Chrome':
        script = 'tell application "Google Chrome" to get URL of active tab of front window'
    elif browser == 'Safari':
        script = 'tell application "Safari" to get URL of current tab of front window'
    else:
        # 通用方案：通过 System Events
        script = f'''
        tell application "System Events"
            tell process "{browser}"
                -- 尝试获取地址栏内容
            end tell
        end tell
        '''
    r = subprocess.run(['osascript', '-e', script], capture_output=True, text=True)
    return r.stdout.strip()
```

### 优先级 4：Cursor MCP Browser 工具

使用 Cursor 内置的 `cursor-ide-browser` MCP 服务进行浏览器交互。

### 优先级 5：CDP 连接已运行浏览器（最后手段）

仅在必须进行 DOM 自动化操作时使用，且必须连接已运行的浏览器：

```python
from playwright.sync_api import sync_playwright

# ⚠️ 仅连接已运行的浏览器，不启动新实例
# 需要浏览器已开启远程调试端口
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp("http://localhost:9222")
    context = browser.contexts[0]  # 使用已有的 context
    page = context.pages[0]        # 使用已有的 page
```

---

## 三、检测系统默认浏览器

```python
import subprocess, json, os

def get_default_browser():
    """获取 macOS 系统默认浏览器 bundle ID 和名称"""
    r = subprocess.run(['plutil', '-convert', 'json', '-o', '-',
        os.path.expanduser('~/Library/Preferences/com.apple.LaunchServices/com.apple.launchservices.secure.plist')],
        capture_output=True, text=True)
    
    bundle_id = 'com.apple.Safari'  # 默认 Safari
    if r.returncode == 0:
        data = json.loads(r.stdout)
        for h in data.get('LSHandlers', []):
            if h.get('LSHandlerURLScheme') == 'https':
                bundle_id = h.get('LSHandlerRoleAll', 'com.apple.Safari')
                break
    
    # 常见浏览器 bundle ID → 名称
    browser_names = {
        'com.google.chrome': 'Google Chrome',
        'com.apple.safari': 'Safari',
        'com.brave.browser': 'Brave Browser',
        'com.microsoft.edgemac': 'Microsoft Edge',
        'company.thebrowser.browser': 'Arc',
        'com.bot.pc.doubao.browser': '豆包浏览器',
        'org.mozilla.firefox': 'Firefox',
        'com.opera.opera': 'Opera',
    }
    
    return {
        'bundle_id': bundle_id,
        'name': browser_names.get(bundle_id, bundle_id),
    }

# 当前系统默认浏览器：豆包浏览器 (com.bot.pc.doubao.browser)
```

---

## 四、禁止行为清单

| 禁止行为 | 说明 |
|:---|:---|
| `playwright.chromium.launch()` | 会创建全新的隔离浏览器实例 |
| `playwright.chromium.launch_persistent_context()` | 虽然复用数据目录，但会锁定 profile 导致冲突 |
| `webdriver.Chrome()` | 创建新的 ChromeDriver 实例 |
| `--incognito` / `--inprivate` | 无痕模式，丢失所有登录态 |
| `headless=True` | 无界面模式，无法复用已有会话 |
| 硬编码浏览器路径 | 如 `/Applications/Google Chrome.app/...` |

---

## 五、各技能适配说明

| 技能 | 原方案 | 新方案 |
|:---|:---|:---|
| 网站逆向分析 | Playwright launch + Stealth | API 调用优先；需要浏览器时用 `open` + AppleScript |
| 流量自动化 | Selenium WebDriver | API 调用优先；需要浏览器时用 `open` + AppleScript |
| 飞书管理 | Playwright 无痕窗口 | API 调用（飞书 Open API）；需要浏览器时用 `open` |
| 存客宝 | 无浏览器依赖 | 无需修改 |

---

## 六、常见场景处理

### 场景1：需要用户登录后操作

```bash
# 直接用默认浏览器打开登录页（用户已有登录态则自动跳过）
open "https://project.feishu.cn/settings"
```

### 场景2：需要自动填表/点击

```python
# 优先用 API 完成
# 若必须用浏览器，用 AppleScript 操作已打开的页面
import subprocess

script = '''
tell application "System Events"
    tell process "豆包浏览器"
        -- 模拟键盘/鼠标操作
        keystroke "v" using command down  -- 粘贴
        delay 1
        keystroke return  -- 回车
    end tell
end tell
'''
subprocess.run(['osascript', '-e', script])
```

### 场景3：需要获取浏览器中的数据

```python
# 用 API 获取（最佳）
# 或用 AppleScript 获取当前页面信息
import subprocess

script = '''
tell application "Google Chrome"
    set pageSource to execute active tab of front window javascript "document.title"
    return pageSource
end tell
'''
result = subprocess.run(['osascript', '-e', script], capture_output=True, text=True)
print(result.stdout.strip())
```

---

## 七、版本记录

| 日期 | 版本 | 变更 |
|:---|:---|:---|
| 2026-02-13 | v1.0 | 初版，明确默认浏览器优先、禁止新建实例 |