# https://github.com/LiquidBuiltIt/Supersurf 项目说明书

生成时间：2026-07-28 01:22:33 UTC

## 目录

- [项目概览与设计理念](#page-1)
- [系统架构与组件交互](#page-2)
- [MCP 工具集、扩展内容脚本与安全机制](#page-3)
- [部署、平台支持与运维](#page-4)

<a id='page-1'></a>

## 项目概览与设计理念

### 相关页面

相关主题：[系统架构与组件交互](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/LiquidBuiltIt/Supersurf/blob/main/README.md)
- [CHANGELOG.md](https://github.com/LiquidBuiltIt/Supersurf/blob/main/CHANGELOG.md)
- [package.json](https://github.com/LiquidBuiltIt/Supersurf/blob/main/package.json)
- [LICENSE](https://github.com/LiquidBuiltIt/Supersurf/blob/main/LICENSE)
</details>

# 项目概览与设计理念

Supersurf 是一个面向 macOS 与 Linux 用户的自动化工具项目，旨在为开发者提供轻量级、可脚本化的"后台保活"与浏览器会话管理能力。项目以 Node.js 生态为基础构建，整体保持单一职责、易于集成的设计原则。

## 项目定位与目标用户

Supersurf 的核心定位是作为开发者的"辅助运行时"，而非一个完整的产品级应用。它假定使用者具备基本的命令行操作能力，并将工具链与现有开发环境无缝融合。资料来源：[README.md:1-40]()

目标用户群体包括：

- 需要长时间维持浏览器会话的前后端工程师
- 在 CI/CD 或本地调试环境中需要可重复浏览器行为的团队
- 希望以代码方式控制 Chrome/Chromium 实例的自动化测试人员

项目刻意避免重型 GUI 与复杂的服务端部署，强调"开箱即用、配置透明"。

## 设计理念

### 单一职责与模块化

Supersurf 遵循"做一件事并做好"的原则，将浏览器自动化、进程保活与脚本接口清晰分层。`package.json` 中声明的依赖保持精简，避免引入与核心目标无关的重量级框架。资料来源：[package.json:1-40]()

### 可脚本化优先

项目以 CLI 与 Node.js API 作为主要交互面，而非图形界面。这种设计让 Supersurf 易于嵌入到 npm scripts、Shell pipeline 与持续集成流程中。资料来源：[README.md:40-80]()

### 透明与可预测

所有运行时行为由显式配置驱动，不引入隐式的全局状态或副作用。版本演进通过语义化版本控制记录在 `CHANGELOG.md` 中，便于使用者评估升级风险。资料来源：[CHANGELOG.md:1-20]()

## 平台支持与已知限制

Supersurf 目前**仅支持 macOS 与 Linux 操作系统**，Windows 平台未在官方支持范围内。社区中已有用户就此提出过相关讨论（见 Issue #1 "Windows Support"），维护者表示将根据需求反馈决定后续投入。

| 平台 | 支持状态 | 说明 |
|------|---------|------|
| macOS | ✅ 完全支持 | 主要开发与测试平台 |
| Linux | ✅ 完全支持 | 主流发行版均可运行 |
| Windows | ❌ 未支持 | 取决于社区需求反馈 |

资料来源：[README.md:1-40]()，社区 Issue #1 "Windows Support"

对于 Windows 用户，建议通过 WSL（Windows Subsystem for Linux）以 Linux 子系统形式间接使用，但这并非官方推荐的部署路径。

## 许可与版本演进

项目采用开源许可证发布，详情见根目录下的 `LICENSE` 文件。版本演进遵循语义化版本规范（SemVer），主要变更、修复与破坏性更新均在 `CHANGELOG.md` 中明确记录，使用者可据此判断兼容性影响。资料来源：[LICENSE:1-20]()，[CHANGELOG.md:1-40]()

## 架构总览

下图概括了 Supersurf 的高层模块划分，体现"CLI/脚本接口 → 核心运行时 → 浏览器进程"的单向数据流：

```mermaid
flowchart LR
    A[CLI / Node API] --> B[核心运行时]
    B --> C[浏览器进程管理]
    B --> D[会话与状态保持]
    C --> E[Chrome / Chromium]
    D --> E
```

整体架构保持扁平与单向，便于调试与扩展。资料来源：[package.json:1-60]()，[README.md:40-100]()

## 总结

Supersurf 以"轻量、可脚本、跨 Unix 平台"为核心设计理念，为开发者提供可靠的浏览器会话管理能力。其模块化结构与透明的版本演进策略降低了集成成本，但 Windows 平台支持仍是当前最显著的社区关注点，建议潜在用户在评估时将其纳入考量。

---

<a id='page-2'></a>

## 系统架构与组件交互

### 相关页面

相关主题：[项目概览与设计理念](#page-1), [MCP 工具集、扩展内容脚本与安全机制](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [server/src/bin/supersurf.ts](https://github.com/LiquidBuiltIt/Supersurf/blob/main/server/src/bin/supersurf.ts)
- [server/src/bin/supersurf-daemon.ts](https://github.com/LiquidBuiltIt/Supersurf/blob/main/server/src/bin/supersurf-daemon.ts)
- [server/src/bridge.ts](https://github.com/LiquidBuiltIt/Supersurf/blob/main/server/src/bridge.ts)
- [daemon/src/main.ts](https://github.com/LiquidBuiltIt/Supersurf/blob/main/daemon/src/main.ts)
- [daemon/src/scheduler.ts](https://github.com/LiquidBuiltIt/Supersurf/blob/main/daemon/src/scheduler.ts)
- [daemon/src/session.ts](https://github.com/LiquidBuiltIt/Supersurf/blob/main/daemon/src/session.ts)
</details>

# 系统架构与组件交互

## 1. 总体架构概览

Supersurf 是一个由两个主要子系统构成的分布式代理（proxy）工具：**Server（服务端）** 与 **Daemon（守护进程）**。Server 负责接收来自客户端浏览器的代理请求并提供用户交互入口；Daemon 作为常驻后台服务，承担调度与浏览器会话管理的职责。两端通过本地 IPC（进程间通信）通道进行协作，构成一个跨进程的浏览器自动化基础设施。

整个项目目前仅在 macOS 与 Linux 平台上提供官方支持；Windows 平台的支持因相关需求尚未达到预期阈值而被推迟，社区已就此创建了跟踪议题（参考社区热门问题 #1 "Windows Support"）。

## 2. Server 端：入口与桥接层

Server 端的可执行入口定义在 `server/src/bin/supersurf.ts` 中，它负责启动 CLI 进程并向用户暴露交互界面。资料来源：[server/src/bin/supersurf.ts]()。

与 Daemon 子进程对接的命令则定义于 `server/src/bin/supersurf-daemon.ts`，该文件封装了对 Daemon 进程的拉起、状态查询与生命周期管理逻辑。资料来源：[server/src/bin/supersurf-daemon.ts]()。

Server 与 Daemon 之间的通信协议与消息序列化逻辑集中在 `server/src/bridge.ts` 中。该模块充当**桥接层（bridge）**，将 Server 接收到的外部请求转换为 Daemon 可识别的内部指令，并将执行结果回传给调用方。资料来源：[server/src/bridge.ts]()。

## 3. Daemon 端：调度与会话管理

Daemon 的进程入口由 `daemon/src/main.ts` 提供。该模块负责初始化运行时环境、注册信号处理并加载配置，随后启动调度器与会话管理器。资料来源：[daemon/src/main.ts]()。

`daemon/src/scheduler.ts` 实现**任务调度器（scheduler）**，负责按策略分发来自 Server 的请求、维护任务队列并协调会话实例的复用与回收。资料来源：[daemon/src/scheduler.ts]()。

`daemon/src/session.ts` 定义**浏览器会话（session）**的抽象，封装了浏览器实例的创建、页面导航、Cookie 隔离以及与目标站点的实际交互。Scheduler 通过调用 Session 模块来完成具体的代理动作。资料来源：[daemon/src/session.ts]()。

## 4. 组件交互流程

下图展示了从用户触发到浏览器实际执行代理动作的完整调用链：

```mermaid
sequenceDiagram
    participant U as 用户/客户端
    participant S as Server (supersurf.ts)
    participant B as Bridge (bridge.ts)
    participant D as Daemon (main.ts)
    participant Sch as Scheduler (scheduler.ts)
    participant Sess as Session (session.ts)

    U->>S: 发起代理请求
    S->>B: 转发并编码请求
    B->>D: IPC 调用守护进程
    D->>Sch: 提交任务
    Sch->>Sess: 分配或复用浏览器会话
    Sess-->>Sch: 返回执行结果
    Sch-->>D: 任务结果汇总
    D-->>B: IPC 响应
    B-->>S: 解码并回传
    S-->>U: 响应客户端
```

交互过程的关键设计要点：

- **职责分离**：Server 关注用户面与协议适配，Daemon 关注调度与会话生命周期，二者通过桥接层解耦。
- **进程隔离**：调度与浏览器会话运行在独立进程中，重启 Daemon 不会影响 Server 已建立的连接。
- **会话复用**：Scheduler 通过 Session 模块管理浏览器实例池，避免每次请求都启动新的浏览器进程，从而降低延迟与资源占用。
- **平台限制**：由于依赖类 Unix 的进程与信号机制（详见 [daemon/src/main.ts]() 中的初始化逻辑），当前架构在 Windows 上的移植需要重新评估进程间通信方案，这也是社区所关注的 Windows 支持议题的核心技术障碍。

通过以上分层与组件协作，Supersurf 在保证用户面灵活性的同时，把开销较大的浏览器自动化操作隔离在 Daemon 内部，实现了轻量级入口与重型执行体之间的平衡。

---

<a id='page-3'></a>

## MCP 工具集、扩展内容脚本与安全机制

### 相关页面

相关主题：[系统架构与组件交互](#page-2), [部署、平台支持与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [server/src/tools.ts](https://github.com/LiquidBuiltIt/Supersurf/blob/main/server/src/tools.ts)
- [server/src/tools/interaction/index.ts](https://github.com/LiquidBuiltIt/Supersurf/blob/main/server/src/tools/interaction/index.ts)
- [server/src/tools/browser_evaluate/secure-eval.ts](https://github.com/LiquidBuiltIt/Supersurf/blob/main/server/src/tools/browser_evaluate/secure-eval.ts)
- [server/src/experimental/mouse-humanization/index.ts](https://github.com/LiquidBuiltIt/Supersurf/blob/main/server/src/experimental/mouse-humanization/index.ts)
- [server/src/experimental/page-diffing.ts](https://github.com/LiquidBuiltIt/Supersurf/blob/main/server/src/experimental/page-diffing.ts)
- [server/src/experimental/fingerprinting/index.ts](https://github.com/LiquidBuiltIt/Supersurf/blob/main/server/src/experimental/fingerprinting/index.ts)
</details>

# MCP 工具集、扩展内容脚本与安全机制

Supersurf 通过 MCP（Model Context Protocol）向 LLM 客户端暴露一组浏览器操作工具，使模型能够像真人一样与网页交互。这些工具在服务端实现，配合浏览器扩展中的内容脚本，构成了完整的"工具—内容脚本—安全沙箱"栈。本页梳理该栈的组成、调用流程与安全约束。

## 工具集架构

`server/src/tools.ts` 是 MCP 工具的统一注册中心。所有对外暴露的工具都在此聚合，并通过 MCP 协议以 JSON Schema 形式声明输入输出，被客户端模型发现与调用。 资料来源：[server/src/tools.ts]()。

工具按职责拆分到 `server/src/tools/` 下的子目录：

- **交互类**：`interaction/index.ts` 实现点击、滚动、键盘输入等基础人机交互原语。
- **求值类**：`browser_evaluate/secure-eval.ts` 提供受限的页面内 JavaScript 执行能力。

### 交互工具

`server/src/tools/interaction/index.ts` 实现的工具并非直接调用 Playwright/Puppeteer 的底层 API，而是通过消息通道把事件转发给浏览器扩展的内容脚本，由脚本在真实视口内派发 DOM 事件，从而降低被网站反机器人机制识别的概率。 资料来源：[server/src/tools/interaction/index.ts]()。

## 扩展内容脚本

每个具体工具在浏览器侧都有对应的内容脚本。内容脚本在页面上下文（隔离世界或主世界）中执行，把工具调用转化为真实的 DOM 事件，并把结果以结构化形式回传给服务端。`browser_evaluate` 工具借助 `secure-eval.ts` 在受限沙箱中执行模型提交的 JavaScript 片段，并把返回值序列化后送回调用方。 资料来源：[server/src/tools/browser_evaluate/secure-eval.ts]()。

## 安全机制

由于工具直接驱动浏览器，安全设计至关重要，主要体现在以下三层：

| 层级 | 实现位置 | 作用 |
| --- | --- | --- |
| 沙箱求值 | `secure-eval.ts` | 限制可访问的全局对象与 API，防止破坏宿主页面 |
| 消息边界 | `interaction/index.ts` 和扩展侧 | 校验消息结构与来源，限制可操作的页面方法 |
| 工具注册收敛 | `tools.ts` | 工具必须显式注册，避免内部能力被隐式暴露 |

> 平台差异提醒：当前 Supersurf 仅支持 macOS 与 Linux，社区中已有 "Windows Support" 讨论（[#1]），Windows 上的路径分隔符、浏览器驱动差异可能影响部分工具的可用性。

## 实验性功能

`server/src/experimental/` 目录下集中放置尚未稳定的增强模块：

- **鼠标拟人化**：`mouse-humanization/index.ts` 为鼠标移动引入随机抖动、贝塞尔轨迹和停顿，使行为更接近真人。 资料来源：[server/src/experimental/mouse-humanization/index.ts]()。
- **页面差分**：`page-diffing.ts` 对两次页面快照做差分，仅返回变化部分，用于减少上下文窗口占用。 资料来源：[server/src/experimental/page-diffing.ts]()。
- **指纹管理**：`fingerprinting/index.ts` 生成或轮换浏览器指纹，缓解被风控系统关联。 资料来源：[server/src/experimental/fingerprinting/index.ts]()。

## 工具调用时序

```mermaid
sequenceDiagram
    participant LLM as LLM 客户端
    participant MCP as MCP 服务 (tools.ts)
    participant Tool as 具体工具
    participant CS as 扩展内容脚本
    participant Page as 浏览器页面
    LLM->>MCP: 调用工具 (JSON Schema)
    MCP->>Tool: 路由至实现
    Tool->>CS: 通过消息通道下发指令
    CS->>Page: 触发 DOM 事件 / 求值
    Page-->>CS: 返回结果
    CS-->>Tool: 结构化响应
    Tool-->>MCP: 工具结果
    MCP-->>LLM: 最终响应
```

## 小结

MCP 工具集、扩展内容脚本与安全机制共同构成了 Supersurf 在"模型—浏览器"之间的安全桥梁。`tools.ts` 负责注册与协议层职责，`interaction/index.ts` 提供主要交互原语，`secure-eval.ts` 负责安全执行任意 JS，三层防护把模型对浏览器的控制限制在可控范围内。`experimental/` 下的模块则在反检测与上下文效率上提供额外能力，可在稳定性满足要求后逐步并入主工具集。

---

<a id='page-4'></a>

## 部署、平台支持与运维

### 相关页面

相关主题：[系统架构与组件交互](#page-2), [MCP 工具集、扩展内容脚本与安全机制](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [server/package.json](https://github.com/LiquidBuiltIt/Supersurf/blob/main/server/package.json)
- [daemon/package.json](https://github.com/LiquidBuiltIt/Supersurf/blob/main/daemon/package.json)
- [extension/manifest.json](https://github.com/LiquidBuiltIt/Supersurf/blob/main/extension/manifest.json)
- [shared/config/defaults.ts](https://github.com/LiquidBuiltIt/Supersurf/blob/main/shared/config/defaults.ts)
- [shared/config/scaffold.ts](https://github.com/LiquidBuiltIt/Supersurf/blob/main/shared/config/scaffold.ts)
- [scripts/publish.ts](https://github.com/LiquidBuiltIt/Supersurf/blob/main/scripts/publish.ts)
</details>

# 部署、平台支持与运维

SuperSurf 是一个由多个相互协作的组件构成的代理工具，其部署、平台支持与运维涉及三类核心产物：浏览器扩展（extension）、本地守护进程（daemon）以及后端服务（server）。本页整理了在生产或开发环境中进行构建、打包、发布与跨平台支持时需要关注的内容，并指明当前平台矩阵的边界。

## 1. 组件划分与产物概览

SuperSurf 仓库由 `extension/`、`daemon/`、`server/` 三个子包构成，每个子包都通过独立的清单文件声明其入口、权限与依赖，并通过 `shared/` 目录共享通用配置与脚手架逻辑。这种结构使得扩展、守护进程与服务器可以独立发布和独立升级，但在运行时仍保持配置一致性。

| 子包 | 主要清单 | 主要产物 | 运行平台 |
|------|---------|---------|---------|
| 浏览器扩展 | `extension/manifest.json` | Chrome MV3 扩展包 | macOS、Linux（Windows 未支持）|
| 本地守护进程 | `daemon/package.json` | Node 脚本或封装二进制 | macOS、Linux（Windows 未支持）|
| 后端服务 | `server/package.json` | Node.js 服务进程 | macOS、Linux |

资料来源：[extension/manifest.json:1-30]() [daemon/package.json:1-30]() [server/package.json:1-30]()

## 2. 平台支持现状

SuperSurf 目前明确仅支持 macOS 与 Linux 操作系统。仓库维护者已经在社区中开列了 "Windows Support" 议题以评估需求，但由于守护进程依赖类 Unix 特性（例如 POSIX 信号处理、`launchd`/`systemd` 集成路径、以及部分原生绑定），Windows 平台尚未被纳入正式支持矩阵。社区中该议题的反馈将决定是否启动 Windows 适配工作。

在 Windows 上运行会遇到以下限制：
- `daemon/` 子包中的依赖与脚本假设类 Unix 文件系统权限与进程模型；
- 浏览器扩展在 Windows 主机上仍可加载，但配套的代理握手流程依赖守护进程；
- `scripts/publish.ts` 的发布流程使用 `bash` 假设，CI 流水线仅在 Linux runner 上验证。

若您的开发或部署环境是 Windows，请关注 "Windows Support" issue 并通过点赞表达诉求，以便维护者评估投入产出比。资料来源：[daemon/package.json:1-50]() [scripts/publish.ts:1-80]()

## 3. 配置脚手架与默认值

部署 SuperSurf 时，`shared/config/` 目录提供两类配置：`defaults.ts` 给出开箱即用的默认参数（如默认代理端口、TLS 设置、上游回退策略），`scaffold.ts` 负责在首次运行时生成用户级配置文件。这两个文件共同决定了守护进程与扩展在多平台上的行为一致性，并降低了运维配置错误的风险。

运维中的常见做法是：
1. 通过 `defaults.ts` 了解默认值，避免在用户配置中重复声明；
2. 通过 `scaffold.ts` 在用户机器上生成配置文件并避免覆盖已有设置；
3. 在升级扩展或守护进程时，注意默认值的变化可能需要迁移用户配置。

资料来源：[shared/config/defaults.ts:1-120]() [shared/config/scaffold.ts:1-120]()

## 4. 发布与持续交付

`scripts/publish.ts` 是项目统一发布的入口脚本，负责协调三个子包的版本号同步、构建产物生成以及可选的包上传逻辑。该脚本通常被 CI 调用，并假定运行在类 Unix 环境中。

发布工作流的关键步骤：
- 解析 `server/package.json`、`daemon/package.json` 与 `extension/manifest.json` 中的当前版本号；
- 在必要时执行构建（构建脚本由各 `package.json` 中的 `scripts.build` 字段声明）；
- 将构建产物发布到对应的分发渠道（浏览器扩展市场、内部更新服务、Node 包仓库等）。

由于发布流程绑定到类 Unix 工具链，Windows 贡献者目前在本地无法直接执行完整的发布流程，需要在 WSL、macOS 或 Linux 主机上进行。资料来源：[scripts/publish.ts:1-150]() [server/package.json:1-40]() [extension/manifest.json:1-40]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：LiquidBuiltIt/Supersurf

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/LiquidBuiltIt/Supersurf | host_targets=claude, mcp_host

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/LiquidBuiltIt/Supersurf | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/LiquidBuiltIt/Supersurf | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/LiquidBuiltIt/Supersurf | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/LiquidBuiltIt/Supersurf | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/LiquidBuiltIt/Supersurf | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/LiquidBuiltIt/Supersurf | release_recency=unknown

<!-- canonical_name: LiquidBuiltIt/Supersurf; human_manual_source: deepwiki_human_wiki -->