surf-codebase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

surf-cli Codebase

surf-cli代码库

Architecture

架构

cli.cjs --socket:/tmp/surf.sock--> host.cjs --native-msg--> service-worker/index.ts --CDP/chrome-APIs--> browser

cli.cjs --socket:/tmp/surf.sock--> host.cjs --native-msg--> service-worker/index.ts --CDP/chrome-APIs--> browser

Add CLI Command

添加CLI命令

Add to
```
TOOLS
```
in native/cli.cjs:158 (args, opts, examples)
Add handler in src/service-worker/index.ts:50
```
handleMessage()
```
switch
CDP op? → add method src/cdp/controller.ts:60
DOM interaction? → add handler src/content/accessibility-tree.ts:99

在native/cli.cjs的第158行
```
TOOLS
```
中添加（参数、选项、示例）
在src/service-worker/index.ts的第50行
```
handleMessage()
```
的switch语句中添加处理函数
需要CDP操作？→ 在src/cdp/controller.ts的第60行添加方法
需要DOM交互？→ 在src/content/accessibility-tree.ts的第99行添加处理函数

Add CDP Operation

添加CDP操作

Add method to
```
CDPController
```
class src/cdp/controller.ts:60

Use

this.send(tabId, "Domain.method", params)

Handle events in
```
handleCDPEvent()
```
if needed

在src/cdp/controller.ts的第60行
```
CDPController
```
类中添加方法

使用

this.send(tabId, "Domain.method", params)

如有需要，在
```
handleCDPEvent()
```
中处理事件

Core Files

核心文件

src/service-worker/index.ts (~2500L) - Central msg router, CDP ops, screenshot cache, tab registry

Msg types: EXECUTE_CLICK, EXECUTE_TYPE, READ_PAGE, EXECUTE_SCREENSHOT
Screenshot cache: generateScreenshotId(), cacheScreenshot(), getScreenshot()
Tab names: tabNameRegistry Map<name,tabId>

src/cdp/controller.ts (~1000L) - CDP wrapper, CDPController class

Mouse: click(), rightClick(), doubleClick(), hover(), drag()
Keyboard: type(), pressKey(), pressKeyChord()
Screenshots: captureScreenshot(), captureRegion()
Network/Console: enableNetworkTracking(), getNetworkRequests(), getResponseBody(), subscribeToNetwork(), enableConsoleTracking(), getConsoleMessages()
Emulation: emulateNetwork(), emulateCPU(), emulateGeolocation()

src/content/accessibility-tree.ts (~1900L) - Content script, generates a11y tree YAML, element interactions

Handlers: GENERATE_ACCESSIBILITY_TREE, CLICK_ELEMENT, FORM_INPUT, GET_ELEMENT_COORDINATES, WAIT_FOR_ELEMENT, WAIT_FOR_URL
Element refs: e1, e2... in window.__piRefs for stable references

native/cli.cjs (~2100L) - CLI parser, socket client

TOOLS: command defs with args/opts
ALIASES: shortcut→command map
AUTO_SCREENSHOT_TOOLS: commands that auto-capture
parseArgs(), sendRequest()

native/host.cjs (~2100L) - Socket server, AI integration

handleToolRequest(): main dispatcher
mapToolToMessage(): tool→extension msg converter
queueAiRequest(): AI request serialization
AI clients: chatgptClient, geminiClient, perplexityClient

src/native/port-manager.ts - Extension↔native messaging, auto-reconnect, request/response tracking

src/service-worker/index.ts（约2500行）- 中央消息路由器、CDP操作、截图缓存、标签页注册表

消息类型：EXECUTE_CLICK、EXECUTE_TYPE、READ_PAGE、EXECUTE_SCREENSHOT
截图缓存：generateScreenshotId()、cacheScreenshot()、getScreenshot()
标签页名称：tabName注册表 Map<name,tabId>

src/cdp/controller.ts（约1000行）- CDP封装器、CDPController类

鼠标操作：click()、rightClick()、doubleClick()、hover()、drag()
键盘操作：type()、pressKey()、pressKeyChord()
截图：captureScreenshot()、captureRegion()
网络/控制台：enableNetworkTracking()、getNetworkRequests()、getResponseBody()、subscribeToNetwork()、enableConsoleTracking()、getConsoleMessages()
模拟：emulateNetwork()、emulateCPU()、emulateGeolocation()

src/content/accessibility-tree.ts（约1900行）- 内容脚本，生成无障碍树YAML、元素交互

处理函数：GENERATE_ACCESSIBILITY_TREE、CLICK_ELEMENT、FORM_INPUT、GET_ELEMENT_COORDINATES、WAIT_FOR_ELEMENT、WAIT_FOR_URL
元素引用：A11y树分配e1、e2...，存储在window.__piRefs中以保持引用稳定

native/cli.cjs（约2100行）- CLI解析器、Socket客户端

TOOLS：带参数/选项的命令定义
ALIASES：快捷方式→命令映射
AUTO_SCREENSHOT_TOOLS：自动捕获截图的命令
parseArgs()、sendRequest()

native/host.cjs（约2100行）- Socket服务器、AI集成

handleToolRequest()：主调度器
mapToolToMessage()：工具→扩展消息转换器
queueAiRequest()：AI请求序列化
AI客户端：chatgptClient、geminiClient、perplexityClient

src/native/port-manager.ts - 扩展↔原生消息通信、自动重连、请求/响应跟踪

Message Flow

消息流程

CLI:
```
surf click e5
```
cli.cjs parses → socket → host.cjs
host.cjs routes to EXECUTE_CLICK msg
Native msg → service-worker/index.ts
Service worker: CDP (cdp/controller.ts) or content script (chrome.tabs.sendMessage)
Response flows back to CLI

CLI：
```
surf click e5
```
cli.cjs解析 → Socket → host.cjs
host.cjs路由到EXECUTE_CLICK消息
原生消息 → service-worker/index.ts
服务工作线程：调用CDP（cdp/controller.ts）或内容脚本（chrome.tabs.sendMessage）
响应结果返回至CLI

Debug

调试

Extension logs: chrome://extensions → Service Worker → Console
Host logs: /tmp/surf-host.log
CLI raw output:
```
--json
```
flag

扩展日志：chrome://extensions → Service Worker → 控制台
主机日志：/tmp/surf-host.log
CLI原始输出：使用
```
--json
```
参数

Test

测试

bash

npm run build            # Build ext
npm test                 # Run tests
npm run test:coverage    # Coverage

bash

npm run build            # 构建扩展
npm test                 # 运行测试
npm run test:coverage    # 生成覆盖率报告

Element Refs

元素引用

A11y tree assigns e1, e2... during READ_PAGE. Stored window.__piRefs. Reset each

read

command.

执行READ_PAGE时，A11y树会分配e1、e2...，存储在window.__piRefs中。每次执行

read

命令时会重置。

Network Capture

网络捕获

CDP captures via Network.* events cdp/controller.ts:73
Storage: /tmp/surf/requests.jsonl
Formatters: native/formatters/network.cjs:259

CDP通过Network.*事件捕获，位于cdp/controller.ts的第73行
存储路径：/tmp/surf/requests.jsonl
格式化工具：native/formatters/network.cjs的第259行

Build/Install

构建/安装

bash

npm run dev              # Watch mode
npm run build            # Prod → dist/

bash

npm run dev              # 监听模式
npm run build            # 生产构建 → 输出至dist/

Load dist/ as unpacked ext

将dist/作为未打包扩展加载

surf install <ext-id> # Register native host

undefined

surf install <ext-id> # 注册原生主机

undefined

Gotchas

注意事项

CDP attach: 100-500ms first time/tab
chrome:// pages restricted
Content script needs page refresh on existing tabs
Screenshots auto-resize 1200px unless --full

CDP首次连接标签页需要100-500ms
chrome://页面受限制
现有标签页需要刷新才能加载内容脚本
截图默认自动调整为1200px，除非使用--full参数