SwiftUI 客户端界面与系统集成

本页记录仓库中 macOS 原生 SwiftUI 客户端的公开定位、交付方式、平台范围，以及它与其他客户端形态的边界。当前仓库快照未包含 SwiftUI 客户端的 Swift/Xcode 源码，因此无法从源代码确认具体视图层级、菜单栏实现、系统 API 调用或运行时进程控制细节。

Purpose and Scope

本页聚焦 swiftui-client：一个使用 SwiftUI 构建的 macOS 原生客户端，以及仓库对其发布物、支持架构和产品定位的说明。它适合用于确认以下问题：

• SwiftUI 客户端是否属于仓库支持的客户端形态；
• 目标操作系统与 CPU 架构；
• 应从哪里获取可分发的 macOS 应用；
• SwiftUI 客户端与跨平台 client-ui、命令行 cli 的产品边界。

网络代理协议、wssocks 核心机制和 USTB 插件业务不在本页展开；这些能力的实现细节应分别查看对应的客户端或协议/插件文档。尤其需要注意：当前仓库目录中没有 swiftui-client、Swift 源文件或 Xcode 工程，因此“界面与系统集成”的实现级细节只能标记为源代码未找到，不能据此推断菜单栏、状态栏图标、权限申请、启动项或系统网络扩展行为。

Overview

仓库 README 将客户端分为三种形态：跨平台命令行客户端 cli、基于 Fyne 的跨平台 GUI client-ui，以及 macOS 原生、使用 SwiftUI 构建的 swiftui-client。README 明确说明 SwiftUI 客户端从 v0.6.0 和 v0.7.0 开始提供，并以 wssocks-ustb-client-macOS-*.app.zip 的文件名发布。

该定位意味着 SwiftUI 客户端的主要价值是 macOS 原生用户体验，而不是扩大平台覆盖范围：README 将其支持平台限定为 macOS x64/arm64。与此相对，client-ui 面向 Windows、macOS 和 Linux 的不同架构，是跨平台 GUI 方案。

仓库 README 还说明 wssocks 与 wssocks-plugin-ustb 会被包含在 cli 和 client-ui 客户端中；对于 SwiftUI 客户端是否以相同方式静态打包、嵌入或调用这些组件，当前 README 没有给出足够证据，本文不作扩展结论。

Architecture

在当前可见源材料中，能够确认的是“产品形态—平台—发布物”的关系，而不是应用内部的 SwiftUI 组件架构。下图只表达仓库明确记录的事实：SwiftUI 客户端是 macOS 原生应用，并通过带有固定命名模式的 zip 发布物提供给用户。

Source: README.md

已确认的组件边界

Main Content

macOS 原生定位

README 使用“mac native app”描述 SwiftUI 客户端，并明确将其与基于 Fyne 的 client-ui 区分开。这里的“原生”在仓库材料中至少可以确认两点：实现技术选型是 SwiftUI，支持目标是 macOS；但没有 Swift 源码可用于确认它是否使用 AppKit、菜单栏应用生命周期、LaunchAgent、Network Extension 或其他 macOS 系统集成机制。

因此，下面这些实现级问题在当前仓库快照中没有证据：

• SwiftUI App 类型和 scene 配置；
• macOS 菜单栏或 Dock 行为；
• 状态图片、窗口管理和设置页面；
• 与本地代理进程的启动、停止、重启和日志通信；
• Keychain、沙盒 entitlement、系统代理设置或网络扩展；
• Intel/Apple Silicon 的构建配置与签名流程。

版本与历史线索

README 将 SwiftUI 客户端的可用版本写为 v0.6.0 和 v0.7.0。CHANGELOG 还记录了 SwiftUI 相关的菜单栏、等待行为、状态图片颜色和 macOS arm 支持等历史条目。这些条目可以作为功能演进线索，但它们是变更摘要，不是实现契约；不能据此恢复具体类名、调用顺序或配置键。

发布物命名与安装边界

macOS 客户端的发布物命名模式是 wssocks-ustb-client-macOS-*.app.zip。仓库 README 没有提供解压后的安装步骤、签名/公证说明、最低 macOS 版本或自动更新机制。因此运维文档可以确认“从 release 获取 zip”，但不应把未在仓库说明的安装行为写成必需步骤。

Core Flow

源材料支持的端到端流程是“识别客户端形态 → 根据平台选择发布物 → 从 releases 获取 macOS 应用”。它不是应用内部运行时流程；运行时启动代理、连接 wssocks 或修改系统网络配置的代码在当前仓库快照中未找到。

Sources:

• README.md

如果要记录真实的启动、连接或系统集成时序，需要补充 swiftui-client 目录、Swift 源文件、Xcode 工程和相关 entitlements；这些材料在本次仓库扫描中不存在。

Usage Examples

CLI 客户端安装对照

下面是仓库 README 中实际给出的 CLI 安装示例。它不代表 SwiftUI 客户端的安装方式，而是用于说明 SwiftUI 客户端与 CLI 的交付边界：CLI 可以通过 Go 工具链安装，而 SwiftUI 客户端通过 release 应用包分发。

Source: README.md

macOS SwiftUI 发布物

以下文件名模式直接取自 README，用于在发布页筛选 macOS 原生客户端。仓库没有提供可复制执行的 SwiftUI 启动命令，因此不能伪造一个安装脚本或运行参数示例。

Source: README.md

当前不可提供的 Swift 代码示例

No code example available：当前仓库快照中未找到 Swift、SwiftUI、Xcode 工程或 macOS 集成源代码。任何 struct ContentView, @main, MenuBarExtra 或 AppKit/NetworkExtension 示例都会超出已验证的源材料范围，因此本页不提供伪造代码。

Configuration Options

当前仓库没有可见的 SwiftUI 客户端配置文件、Info.plist、entitlements 或构建设置。能够确认的发布相关值如下：

API Reference

当前没有可从 SwiftUI 源码确认的公开 API、Swift 类型、协议、方法签名或系统集成接口。实现细节未在源代码中找到，因此不记录推测性的 API reference。

Failure Modes, Edge Cases & Concurrency

从现有源材料只能确认以下文档边界，而不能确认应用内部的错误处理：

• 架构选择错误：README 将 SwiftUI 客户端限定为 macOS x64/arm64；下载其他平台或架构的发布物可能不匹配，但仓库没有记录具体错误提示。
• 发布物查找错误：macOS 应用使用 wssocks-ustb-client-macOS-*.app.zip 命名模式；README 未记录 release 资产缺失、校验失败或解压失败时的处理方式。
• 运行时连接失败：未找到 SwiftUI 客户端运行时代码，无法确认连接超时、重试、等待状态或并发控制策略。
• 系统集成失败：未找到 entitlements、权限申请或系统服务调用代码，无法确认其处理方式。

并发、线程模型、Swift Concurrency、任务取消、进程生命周期和资源释放行为均属于实现细节未在源代码中找到的范围。

Performance / Operational Notes

可验证的运维注意事项只有发布维度：SwiftUI 客户端面向 macOS x64/arm64，发布物是 .app.zip。仓库未提供体积、启动时间、CPU/内存、连接性能、日志位置、签名与公证状态、更新策略或崩溃收集配置，因此这些指标不应从本页推导。

Extension Points

没有 SwiftUI 源码、协议或构建工程可用于确认扩展点。若要安全扩展该客户端，首先需要在仓库中补充或定位 SwiftUI 工程，并以实际的 App、View、Model、系统适配器和构建配置为准；本页不假设任何未出现的架构。

Tests

本次扫描未找到 SwiftUI 测试文件或 macOS 客户端测试配置。因此无法从源代码确认界面快照测试、连接流程测试、架构矩阵测试或系统集成测试覆盖范围。

Related Links

• README.md：客户端类型、平台与发布物说明
• README.md：CLI 安装示例
• CHANGELOG.md：SwiftUI 与客户端历史变更摘要