项目定位与目标用户

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"），维护者表示将根据需求反馈决定后续投入。

资料来源：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/脚本接口 → 核心运行时 → 浏览器进程"的单向数据流：

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 平台支持仍是当前最显著的社区关注点，建议潜在用户在评估时将其纳入考量。

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. 组件交互流程

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

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 内部，实现了轻量级入口与重型执行体之间的平衡。

工具集架构

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。

安全机制

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

平台差异提醒：当前 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。

工具调用时序

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/ 下的模块则在反检测与上下文效率上提供额外能力，可在稳定性满足要求后逐步并入主工具集。

1. 组件划分与产物概览

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

资料来源：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

Pitfall Log / 踩坑日志

项目：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