karuo-ai/运营中枢/参考资料/浏览器使用规范.md

浏览器使用规范

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

---

一、核心原则

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

---

二、操作方式优先级

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

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

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

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

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

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

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

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

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 自动化操作时使用，且必须连接已运行的浏览器：

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

---

三、检测系统默认浏览器

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：需要用户登录后操作

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

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

# 优先用 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：需要获取浏览器中的数据

# 用 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	初版，明确默认浏览器优先、禁止新建实例