跃界 / HopWorld
macOS 原生可视化 Xray/V2Ray 代理客户端（SwiftUI）。
协议、传输、REALITY 与导入格式的支持范围见 支持列表。内核分工、维护入口和扩展流程见 已支持协议与维护指南。
HopWorld 自有源码采用 MIT License。外部代理内核及规则数据遵循各自上游许可证，MIT 授权不覆盖这些组件。分发包含第三方组件的安装包时，应保留对应版本的许可证、版权声明并满足其源码提供等要求。
左下角用量卡片可显示本机 Codex / Cursor / Claude 用量（Claude 读取本机 Claude Code 登录，首次手动刷新时需允许访问「Claude Code-credentials」钥匙串）；其中 Codex 重置提醒 可通过 iMessage 在额度重置时通知你（默认关闭，见专节）。Cursor 用量通过只读打开本机 Cursor 登录数据库取得访问令牌；加密凭据需在启动后手动刷新一次并授权「Cursor Safe Storage」。发布问题或日志时，请勿附带登录数据库、令牌、订阅地址或节点凭证。
根据 macOS_Xray_可视化代理客户端_开发文档_V1.0.md 实现首版核心能力：订阅导入、日期型 URL、节点分类、测速、按国家一键连接、系统代理模式。
2.0 增加 软路由：另开一份核心，给同一局域网的手机和平板用。其它设备不必再装自己的代理 App，本机正在用的连接也不会被换掉。安装包：Apple Silicon、Intel，说明见 v2.0.0。
产品主页
落地页（启用 GitHub Pages 后）：https://zaohub.github.io/HopWorld/
仓库 Settings → Pages → Source 选 main / /docs 即可发布。About 的 Website 可填同一地址。
界面预览
环境
系统 VPN（Network Extension）仅在自行签名的构建中可用，需付费 Apple Developer 账号，见下文「启用系统 VPN」。公开发布的安装包不显示该选项。
从源码构建
在仓库根目录执行：
xcodegen generate
open HopWorld.xcodeproj
在 Xcode 中常规本地运行即可使用系统代理。源码仓库不包含代理内核与规则数据；首次连接、测速或打开「关于 → 管理更新」时，应用会在线下载并安装到本机（见下文）。若希望把内核打进工程资源（例如离线构建），可先运行 bash Scripts/fetch_xray.sh（工程可引用 geoip.dat / geosite.dat）。
命令行本地构建：
xcodebuild -project HopWorld.xcodeproj -scheme HopWorld -configuration Debug -derivedDataPath build build
分发安装包时须另外核对所含内核架构、第三方许可证、应用签名和公证状态。
启用系统 VPN（本机测试）
默认构建为 ad-hoc 签名，不含 Network Extension 权限，系统 VPN 不可用。本机测试系统 VPN 需要付费 Apple Developer Program 账号（免费 Apple ID 不支持 Network Extension）：
cp Configs/Signing.local.xcconfig.example Configs/Signing.local.xcconfig
# 编辑：填写 HOPWORLD_DEVELOPMENT_TEAM，并把 HOPWORLD_BUNDLE_PREFIX 换成你自己的反向域名
xcodegen generate
Signing.local.xcconfig 已被 git 忽略。Bundle ID 与 App Group（group.<前缀>.app）在 Apple 后台全局唯一，fork 时必须使用自己的前缀。在 Xcode 登录该账号后构建一次，自动签名会注册 App ID、App Group 与本机。
构建后建议把 App 放到 /Applications 再运行。在 路由 选择「规则代理」，会出现「接管方式」卡片，切换为「系统 VPN」后连接节点；首次连接时 macOS 会请求添加 VPN 配置。系统 VPN 不依赖应用是否遵循系统代理，并显示在「系统设置 → 网络」的 VPN 列表中。
这种 Development 签名的包只能在已登记的 Mac 上运行，因此公开发布的安装包仅支持系统代理等其他模式；需要系统 VPN 的用户请按上述步骤自行构建。
安装 Xray / 组件更新
日常使用不必手动跑脚本或 Homebrew。打开应用后：
- 进入 关于 → 组件更新 → 管理更新
- 在 Xray 卡片中检查并安装（可选手动选版本；稳定版可走自动更新）
- 下载失败时，在同一弹窗切换下载线路（GitHub 直连或镜像）后重试
首次连接节点或测速时，若本机尚无可用核心，也会自动下载默认稳定版并安装到 ~/Library/Application Support/HopWorld/（优先 current/xray 托管路径）。安装后下次连接或测试生效；已在跑的连接不受影响。
同一弹窗还可管理 sing-box 与 GeoFiles：
- sing-box 保留
1.14.2 基线，可更新至已适配的 1.14.4。两个版本均按架构固定官方 SHA-256；安装候选版本前检查全量/分应用 TUN 及 VLESS、TUIC、AnyTLS、Hysteria2、旧 Shadowsocks 桥接配置。更新版通过后才切换，后续未适配的上游版本只提示。
- GeoFiles 独立取自 Loyalsoldier/v2ray-rules-dat，从同一发布下载
geoip.dat / geosite.dat 并校验各自官方摘要，用本地 Xray 检查规则后成套切换。独立规则优先于 Xray 随附规则，后续更新 Xray 不覆盖独立规则。
- 启动时会触发自动检查。Xray：同一自然日若已检查过，自动流程会跳过联网刷新，但在开启自动更新时仍可安装已缓存的官方稳定版。sing-box / GeoFiles：关闭自动更新时同日跳过联网检查；开启自动更新时每次启动都会刷新。自动更新默认开启；Xray 仅自动安装官方稳定版，预发布版需手动选择。所有组件共用下载线路设置；候选校验失败时保留原版本。
可选：命令行预置（开发 / 离线）
仅在需要预先放入工程资源或本机路径时使用：
chmod +x Scripts/fetch_xray.sh
./Scripts/fetch_xray.sh
脚本按当前 Mac 架构拉取官方 release，写入 HopWorld/Resources/xray 与 ~/Library/Application Support/HopWorld/xray（与「管理更新」的 current/xray 布局不同）。也可安装 Homebrew 的 xray：存在托管版时优先托管；否则在本机可执行候选中选择版本较新者。
使用流程
- 打开 App → 订阅 → 添加订阅地址或导入分享链接
- 若识别为日期型 URL，确认使用自动日期模板
- 进入 测试 或等待更新后自动测速；需要时可在 应用连通 检查 ChatGPT、Claude 等能否打开
- 在 路由 选择接管方式：规则代理下的系统代理（默认）、全局 TUN，或规则代理下的「仅指定应用」TUN（自行签名构建还可选系统 VPN）；再在 概览 / 国家 / 菜单栏 连接节点
- （可选）在测试设置中开启节点元数据中文城市显示；首次会从 GeoNames 生成离线库到本机 Application Support，之后优先离线匹配
默认本地端口（系统代理入口，可在设置中修改）：
- SOCKS：
127.0.0.1:10808
- HTTP：
127.0.0.1:10809
软路由
路由页的软路由再开一份 Xray，只给同一局域网的其它设备用。它不替换本机主连接，也不改系统代理、TUN 和当前节点。
- 局域网地址固定为 HTTP
17890、SOCKS5 17891。这和上面的本机系统代理端口不是同一对。
- 手机和平板不必再装自己的代理 App。把系统代理指到这台 Mac 的局域网地址即可，不需要密码，也不需要 Shadowrocket 一类客户端。
- 可以只测勾选的订阅组；禁用的组也能用于软路由。测出时延后可以自动优选。
- 转发过程中可以按实测延时换线：超过设定秒数就按排名切到下一个；前若干个仍不达标时，会更新勾选的订阅并重新测试。也可以定时测试、定时更新订阅。这些定时不改主应用自己的定时。
- 指定国家和排除国家按已测到的出口，不看节点名称。
- 目前只使用 IPv4 局域网地址。首次开启时，系统可能会询问是否允许入站连接。用完请断开。
使用教程
Mac 和手机、平板要在同一个局域网，通常是同一个 Wi-Fi。
- 打开 路由，点时间下方的 软路由。
- 展开 策略与订阅，点 编辑。勾选要测的连通目标，再勾选订阅组。已经禁用的组也能勾选，只给软路由用。
- 想测完自动连上排第一的节点，勾上 自动优选。转发中要按延时换线，打开 延时换线，再设超过多少秒、在前几个节点里切换。定时测试按分钟，定时更新订阅按小时。点 完成。这些定时不改主应用自己的定时。
- 点 测试。只有测出时延的节点会出现在列表里。选一个，点 连接此节点。开了自动优选时，测试结束后会自己连上排第一的节点。
- 状态变成「正在转发」后，展开 局域网代理地址。有多条地址时，选和手机同一网段的那条。HTTP 端口是
17890，SOCKS5 是 17891。可以点 复制。
- 在其它设备上把系统代理设为手动：服务器填这台 Mac 的局域网 IP，端口填
17890，认证关掉。不需要用户名和密码，也不需要再装代理 App。
- iPhone：设置 → 无线局域网 → 当前网络右侧 ⓘ → 配置代理 → 手动
- Android：长按当前 Wi-Fi → 修改网络 → 高级 → 代理选手动
- 系统代理用 HTTP。SOCKS5
17891 只给能单独设置 SOCKS 的应用。
- 用完后，把手机代理改回关闭，回到软路由面板点 断开。
首次开启时，系统可能会询问是否允许入站连接。目前只使用 IPv4。17890 被占用时会直接失败，不会改到别的端口。本机主连接、系统代理、TUN 和当前节点都不会改。
Codex 重置提醒（iMessage）
跃界可在 Codex 周额度重置、可用重置次数增加，或 最近一笔可用重置即将到期 时，通过本机「信息」发送 iMessage。功能默认关闭；不经过任何远程服务器，收件人与监测基线只保存在本机。
如何开启
- 左下角 Codex 用量卡片 → 齿轮 → 通知
- 打开「启用 iMessage 通知」
- 添加收件人（iMessage 手机号建议带国家/地区码如
+86，或 Apple 账号邮箱），勾选要接收的人
- 点击 应用设置 保存（筛选只缩小列表，不改变勾选；编辑/删除也在应用后生效）
请先在本机「信息」登录 iMessage。首次发送时 macOS 会请求自动化权限；若拒绝，可到「系统设置 → 隐私与安全性 → 自动化」允许跃界控制「信息」。
This is the beginning of the README. Read the rest at the original. Read the full README ↗
