项目概览

wssocks-plugin-ustb 是一个基于 wssocks 的 USTB 内网访问插件项目。它将 SOCKS5 代理能力承载在 WebSocket 协议之上，并提供命令行客户端、跨平台 GUI 客户端以及 macOS 原生客户端形态。

Purpose and Scope

本页介绍项目的整体定位、客户端组成、与 wssocks 的关系，以及已从仓库源码确认的插件选项入口。页面范围限定在项目级概览，不展开 VPN 登录、二维码认证、GUI 页面或 SwiftUI 客户端的独立实现细节；这些能力应由对应的子页面分别说明。

仓库 README 明确说明，该项目用于在无法直接访问 USTB 内网的环境（例如家庭网络）中访问 USTB 内部网络，并依赖 wssocks 提供 WebSocket 上的 SOCKS5 代理能力。README.md

Overview

项目由两层能力组成：

通用代理底座：外部 wssocks 项目负责 SOCKS5 代理和 WebSocket 传输。
USTB 插件与客户端分发：本仓库提供 USTB 场景的插件能力，并把插件打包进 CLI、Fyne GUI 和 macOS 客户端。

README 将可用客户端划分为三类：

cli：面向多平台的命令行客户端；
client-ui：从 v0.5.0 开始提供的 Windows/macOS GUI 客户端；
swiftui-client：从 v0.6.0 和 v0.7.0 开始提供的 macOS 原生客户端。

README 同时强调，wssocks 与本插件都会包含在 CLI 和 client-ui 客户端中。因此客户端不是三套完全独立的代理实现，而是不同的交互和打包入口，共享同一套代理/插件基础能力。README.md

Architecture

Loading diagram...

图中的客户端分类和 wssocks 依赖来自 README；UstbVpn 与 OnOptionSet 来自已读取的 VPN 插件源码。源码当前明确展示的是选项写入入口，完整的连接建立、认证和传输调用链未在本次范围内读取，因此不能据此推断更多内部关系。

组成与职责

客户端分发层

CLI 客户端通过 wssocks-ustb 命令提供使用入口。README 给出的安装方式是使用 Go 安装命令获取该程序，或从 release 页面下载与操作系统和架构对应的二进制文件。GUI 客户端则以 client-ui-$OS-$ARCH 形式发布。README.md

README 给出的 CLI 使用入口如下：

bash

go get -u github.com/genshen/wssocks-plugin-ustb/wssocks-ustb
wssocks-ustb --help

Source: README.md

README 还记录了客户端平台范围：CLI 支持 Windows x64、macOS x64/arm64 和 Linux x64/arm64；client-ui 支持 Windows x64、macOS x64/arm64；macOS 原生客户端只面向 macOS x64/arm64。README.md

VPN 插件选项入口

plugins/vpn/option_plugin.go 中的 UstbVpn.OnOptionSet 实现了 OptionPlugin 的选项回调。该方法接收 client.Options，将它直接保存到 UstbVpn.ConnOptions，然后返回 nil：

package vpn

import "github.com/genshen/wssocks/client"

// implementation of interface OptionPlugin
func (v *UstbVpn) OnOptionSet(options client.Options) error {
	v.ConnOptions = options
	return nil
}

Source: option_plugin.go

这一实现体现了一个明确的设计边界：选项设置阶段只负责把外部 client.Options 传递给 VPN 对象，不在该方法中执行网络连接、校验或转换。由于源码片段没有展示 UstbVpn 的定义和 ConnOptions 的后续读取位置，具体选项字段、默认值和连接时机需要结合其他实现文件确认。

Core Flow

Loading diagram...

Sources:

README.md

option_plugin.go

上图中，客户端到 OnOptionSet 的选项传递是源码直接证实的；wssocks 提供 SOCKS5 over WebSocket、最终访问 USTB 内网则来自 README 的项目定位。源码证据不足以确认连接建立是否同步、是否有重试、认证如何完成，因而这些行为不在本页做确定性描述。

Usage Examples

查看 CLI 帮助

仓库文档将 wssocks-ustb --help 作为安装后的基本验证入口：

bash

wssocks-ustb --help

Source: README.md

设置 VPN 连接选项

以下是插件层面对 client.Options 的实际处理逻辑。它适合用于理解客户端配置如何进入 UstbVpn，而不是一个独立的命令行调用示例：

func (v *UstbVpn) OnOptionSet(options client.Options) error {
	v.ConnOptions = options
	return nil
}

Source: option_plugin.go

Configuration Options

本次读取到的源码没有声明配置文件、环境变量或 client.Options 的字段定义，因此无法可靠列出具体选项名、类型默认值或环境变量映射。已确认的选项边界如下：

项目	类型	默认值	说明
`OnOptionSet` 入参	`client.Options`	未在本源码片段声明	由调用方传入，并整体保存到 `UstbVpn.ConnOptions`
`UstbVpn.ConnOptions`	与 `client.Options` 对应	未在本源码片段声明	当前实现只展示赋值，不展示后续消费逻辑

API Reference

`OnOptionSet(options client.Options) error`

UstbVpn 的选项设置回调。方法将传入的 client.Options 原样写入 v.ConnOptions，成功后返回 nil。option_plugin.go

参数：

options (client.Options)：客户端连接选项；该方法不对字段进行局部处理。

返回值：

error：当前实现固定返回 nil。

异常与错误：

源码中没有显式返回错误或抛出异常的分支。

Failure Modes, Edge Cases & Concurrency

从已读取的 OnOptionSet 实现看，选项设置路径没有显式校验、错误转换或重试逻辑。它还会直接替换 ConnOptions，因此重复调用时以后一次传入的值为准。源码片段没有锁、原子操作或并发控制；但这并不等同于整个项目不存在并发机制，因为 UstbVpn 定义和调用生命周期未在本次源代码范围内读取。

以下实现细节目前无法从已读取材料确认：

client.Options 的字段、必填约束和默认值；
ConnOptions 是否会被多个 goroutine 同时读取或写入；
WebSocket 连接失败时的重试和超时策略；
USTB 认证失败、网络不可达和代理断开时的错误呈现方式。

Performance / Operational Notes

README 只确认项目使用 WebSocket 承载 SOCKS5 代理，并提供多平台客户端发行物。源码材料不足以确认连接池、缓存、重试、超时、资源释放或吞吐优化策略。运维上应首先根据目标平台选择对应的 release 产物，并通过 wssocks-ustb --help 检查 CLI 是否可执行。

Extension Points

当前可直接确认的扩展点是 OptionPlugin 的 OnOptionSet 实现：它以 client.Options 为输入，以 error 为统一回调结果，并把选项保存到 UstbVpn。如果扩展选项处理，应先核对 client.Options 的定义及 UstbVpn 对 ConnOptions 的消费位置；仅修改该回调无法证明新选项已经影响连接行为。