ShadowSpace

台灣用語友善的 macOS 代理工具：選單列常駐、SwiftUI 介面、支援原生與完整引擎雙路線

ShadowSpace 是一款 Shadowrocket 風格的 macOS 代理工具。它保留簡單的一鍵連線體驗，以 Developer ID 簽章與 Apple 公證的 DMG 對外發佈，並內建兩種可在「設定」隨時切換的代理引擎：

引擎	用途	技術
sing-box（完整）	需要完整協議、TUN、系統代理控制、GeoIP / Geosite 與 DNS 分流	內嵌或自動下載官方 sing-box 核心
原生	純 Apple 框架、不依賴外部核心，啟動輕量	ShadowCore（SS / Trojan / VLESS / SOCKS5）

下載

到 Releases 下載最新 .dmg，拖進「應用程式」即可。直發版使用 Developer ID 簽章與 Apple 公證，第一次開啟應可通過 Gatekeeper。

功能

共用體驗

• 一鍵連線：首頁大圓鈕，連線與中斷狀態清楚
• 三種模式：規則、全域、直連
• 匯入：節點分享連結、base64 訂閱、Clash / Clash.Meta YAML 訂閱、sing-box JSON、剪貼簿、URL scheme（shadowspace://）與剪貼簿 QR 掃描
• 節點管理：手動新增、編輯、複製分享連結、QR Code 匯出
• 代理群組：手動選擇與自動測速（urltest）群組
• 節點鏈 / Relay：先經中轉節點再落地（detour）
• 分流規則：網域後綴 / 關鍵字 / 完整網域、IP CIDR、GeoIP、Geosite、程序名稱，策略可選代理、直連、拒絕
• Rule Providers：可訂閱的遠端規則集（.srs）
• 訂閱管理：剩餘流量、到期日、一鍵更新、定時自動更新、可調拉取 User-Agent
• 即時流量圖：上傳 / 下載速率折線圖與本次用量統計
• Kill switch 防洩漏：引擎意外停止時保留系統代理擋住流量外洩
• 自動連線 On-demand：偵測到網路就自動連上
• 設定備份 / 匯出與原始 sing-box 設定檢視
• 自動更新檢查（GitHub Releases）
• 多語系：繁體中文與英文介面（隨系統語言）
• 選單列常駐：快速連線、切換模式、切換節點、查看流量
• 本機資料：設定與節點存在 ~/Library/Application Support/ShadowSpace/

原生引擎

• 使用純 Apple 框架實作的 ShadowCore，不依賴外部代理核心
• 支援 Shadowsocks、Trojan、VLESS、SOCKS5
• 支援 TCP、TLS、WebSocket / WSS
• TLS 分片（抗封鎖）：以 NWProtocolFramer 把 TLS ClientHello 切段送出，干擾 DPI 的 SNI 偵測
• 不支援 Reality、VMess、Hysteria2、TUIC、WireGuard、TUN、GeoIP / Geosite 與 DoH / DoT 分流

更多原生核心細節見 Sources/ShadowCore/README.md。

sing-box 完整引擎

• 支援 Shadowsocks、VMess、VLESS（含 Reality）、Trojan、Hysteria2、TUIC、AnyTLS、SOCKS5、WireGuard
• 支援 TUN / 增強模式，可接管終端機、Docker 等不吃系統代理的流量
• 可自動設定系統代理，也可手動指向 127.0.0.1:7890
• 支援 GeoIP / Geosite、程序名稱規則、Rule Providers（可訂閱規則集）、一鍵廣告阻擋
• 支援遠端 / 直連 DNS 分流，包含 DoH 與 DoT
• Kill switch：引擎意外停止時保留系統代理，避免流量直連外洩
• 第一次連線可自動下載官方 sing-box 核心；發佈版建議先內嵌核心

系統需求

• macOS 14 Sonoma 以上
• 編譯需要 Xcode 或 Command Line Tools

快速開始

make setup
make run

make setup 會下載 sing-box 核心、編譯並打包 .app。如果只想跑開發版：

make dev

第一次使用：

1. 複製你的節點分享連結或訂閱網址。
2. 開啟 ShadowSpace，點「從剪貼簿匯入」。
3. 回首頁選節點與模式，按下連線按鈕。

可在「設定」切換代理引擎：

• 原生：預設引擎，純 Swift / Apple framework，適合 SS / Trojan / VLESS / SOCKS5。
• sing-box（完整）：完整協議與 TUN 能力，適合需要 Reality、Hysteria2、TUIC、WireGuard 或 GeoIP / Geosite 的使用者。

常見問題

原生引擎和 sing-box 引擎差在哪？
原生引擎用純 Apple 框架實作、不依賴外部核心，支援 SS / Trojan / VLESS / SOCKS5；sing-box 引擎功能完整，包含 TUN、系統代理設定與更多協議（Reality、Hysteria2、TUIC、WireGuard、GeoIP / Geosite 等）。

第一次連線很慢？
使用 sing-box（完整） 時，首次連線可能會下載核心引擎與分流規則檔；之後就會快很多。發佈版建議用 make engine 先內嵌核心。

設定系統代理失敗？
修改網路設定需要管理員帳號。也可以關掉「連線時自動設定系統代理」，手動把 HTTP / SOCKS 代理指到 127.0.0.1:7890。

和 Shadowrocket 一樣有 VPN / TUN 模式嗎？
sing-box（完整） 引擎支援 TUN / 增強模式，可接管終端機、Docker 等不吃系統代理的流量。

訂閱匯入失敗？
支援 base64 節點清單、Clash / Clash.Meta YAML 與 sing-box JSON，會依內容自動判型。若仍失敗，可到「設定 → 訂閱」調整拉取 User-Agent 再試（機場常依 UA 回傳不同格式）。

專案結構

Sources/
├── ShadowCore/                       # 純 Apple framework 原生代理核心
├── ShadowSpace/                      # App 進入點
├── ShadowSpaceKit/                   # SwiftUI UI、AppState、設定與引擎橋接
└── shadow-demo/                      # ShadowCore smoke test executable

Tests/
├── ShadowCoreTests/
└── ShadowSpaceKitTests/

scripts/
├── fetch-singbox.sh
├── sign.sh
├── make-dmg.sh
└── notarize.sh

開發

swift test
make dev
make app
make engine

常用命令：

• swift test：單元測試
• make dev：直接執行開發版
• make app：打包 build/ShadowSpace.app
• make engine：下載並內嵌 sing-box

發佈

直發版使用 Developer ID 簽章 + Apple 公證 + DMG。完整步驟見 PACKAGING.md。

make engine
make release SIGN_IDENTITY="Developer ID Application: 你的名字 (TEAMID)"

完成後會產出 build/ShadowSpace-<版本>.dmg。不帶 SIGN_IDENTITY 時會使用 ad-hoc 簽章，僅適合本機測試，不能拿來對外發佈。

路線圖

• 原生 ShadowCore 引擎
• sing-box 完整引擎
• TUN / 增強模式
• 規則編輯器與一鍵廣告阻擋
• 連線檢視器
• 節點編輯、分享連結與 QR Code 匯出
• DNS 自訂與訂閱自動更新
• 代理群組、節點鏈 / Relay
• Rule Providers（可訂閱規則集）
• Clash / Clash.Meta YAML 訂閱
• 即時流量圖、Kill switch、自動連線 On-demand
• 設定備份 / 匯出、URL scheme、剪貼簿 QR 掃描匯入
• TLS 分片（原生引擎）、AnyTLS（sing-box）
• 多語系 UI（繁中 / 英文）
• 自動更新檢查（GitHub Releases）
• Sparkle 靜默自動安裝（需簽章環境 / appcast）
• 全域快捷鍵

授權

本專案以 GPL-3.0 釋出。

sing-box 引擎使用 sing-box（GPLv3）作為獨立、未修改的子程序；二進位檔來自官方 GitHub Releases，發佈版可內嵌於 .app。分流規則集來自 sing-geosite 與 sing-geoip。

原生引擎以 ShadowCore（純 Apple 框架）實作，不包含 sing-box 或外部核心下載。