# ShadowsocksX-NG

本领域涵盖 macOS Shadowsocks 客户端的服务器配置、订阅、代理规则与代理控制，以及用户管理这些内容的工作区。术语用于统一产品讨论与代码中的概念，英文名称保留为检索对应。

## 领域术语

### 配置与订阅

**服务器库（Server library）**：
用户持久保存的完整配置目录、订阅关联、收藏与所需凭据的集合。它不同于为后台代理服务生成的运行配置，也不同于单个配置组的导出快照。

**配置目录（Configuration catalog）**：
服务器配置与配置组组成的有序树的根，根本身不作为用户可见的配置组。

**服务器配置（Server configuration）**：
一个 Shadowsocks 服务器的连接资料，包含用户可见名称、来源归属和持久身份，是配置目录中的叶节点。

**配置组（Configuration group）**：
具有名称和子节点顺序的容器，可包含服务器配置和嵌套配置组；每个节点最多属于一个父节点，组之间不形成环。

**收藏（Favorite）**：
用户对一个服务器配置或配置组的独立标记，不改变节点的来源或目录位置，也不包含对其后代的标记。

**收藏列表（Favorites list）**：
用户排列的收藏节点序列，每个节点最多出现一次，配置组与服务器配置均作为单独一项，不展开后代。

**节点时间戳（Node timestamps）**：
配置目录中每个节点（服务器配置或配置组）的创建时间与修改时间事实。创建时间是节点进入目录的时刻；修改时间是节点自身资料、或分组的直接子节点集合与顺序最后一次变化的时刻，移动节点本身不算修改。历史文档未记录的时间是未知事实，不做回填。

**配置组导出（Configuration group export）**：
用户请求生成的可分享文件快照，包含一个配置组及其全部后代的连接资料和所需凭据。它可以包含不具备激活条件的服务器配置。

**配置组分享（Configuration group share）**：
通过 SIP-008 JSON 文件或逐行 `ss://` URI 列表（文本文件或剪贴板）传递一个配置组及其全部后代服务器的连接资料和所需凭据，供其他客户端使用。URI 列表不保留分组结构。

**服务器分享（Server share）**：
通过二维码（屏幕显示、复制图片或保存图片文件）或剪贴板传递单个服务器配置的 `ss://` URI，供其他设备使用。
_避免用词_：导出（导出指配置组或诊断报告等文件快照）。

**服务器导入（Server import）**：
把剪贴板文本或文件中的服务器配置引入配置目录、形成独立手动子树的操作。来源资料中的标识只用于装配其内部结构，导入产生的每个节点都获得全新的本地持久身份；同一资料重复导入产生相互独立的服务器配置，不与既有节点合并或去重。

**节点复制（Node duplication）**：
在原节点之后的同级位置创建独立手动副本。组复制包含整棵子树，保留层级、顺序、连接字段、所需凭据和空组；所有节点获得全新身份，副本与原节点的凭据修改互不影响。支持手动服务器、手动组和根层订阅组，不支持订阅服务器或嵌套订阅子组。订阅副本不携带订阅来源资料；顶层副本名称加本地化后缀并在同级重名时追加序号；名称末尾已有“副本”或“Copy”（含编号）时沿用该后缀，以同级未占用的编号命名，避免重复追加后缀。目录和凭据作为一次逻辑变更提交，失败不发布部分子树或凭据变更。复制不切换活动目标；在活动组内新增的副本按普通目录变更进入运行时收敛。

**导入来源（Import source）**：
一次服务器导入中可独立处理的一份资料，例如剪贴板文本或单个文件。每个来源独立解码、独立提交，是成功、部分成功与失败报告的粒度单位；一个来源失败不影响其他来源。

**服务器表单草稿（Server form draft）**：
用户创建或编辑一个服务器配置时，尚未保存的连接字段集合。

**插件参数草稿（Plugin parameter draft）**：
服务器表单中尚未保存的有序插件参数集合，每项包含参数名及可选值。无等号的标志与等号后的空值是不同的参数形式。

**手动组（Manual group）**：
用户拥有的配置组，其后代也由用户拥有。

**订阅（Subscription）**：
具有持久身份的远程配置来源，对应一个固定的订阅组；订阅 URL 是可修改的访问地址，而非来源身份。

**订阅资料（Subscription information）**：
供应商随订阅提供的已用流量、剩余流量、服务到期时间与流量重置时间等事实。它不包含服务器连接资料、凭据或完整订阅响应。

**订阅组（Subscription group）**：
一个订阅拥有的配置子树，内容和结构以远程资料为准，用户不能在本地覆盖其成员、名称或连接字段。

**可删除节点（Deletable node）**：
用户拥有且可从配置目录删除的服务器配置或手动组。移除订阅属于订阅管理，与删除节点是不同的操作。
_避免用词_：可移除节点（Removable node）。

**活动目标（Active target）**：
用户选定并保存的代理目标，可以是服务器配置或配置组；选择配置组时，目标仍是该组，而非实际被选用的后代服务器。

**激活候选（Activation candidate）**：
没有已知本地阻断问题、可用于生成代理配置的服务器配置。它不保证远程可达，也不表示插件参数已经验证有效。

**服务器连通性测试（Server connectivity test）**：
用户手动请求，经指定服务器配置向测试 URL 发起应用 TCP 请求并检查响应的操作。测试经过该配置的实际传输路径，包括使用 UDP 传输的插件隧道；它不验证应用 UDP 中继。

**测试 URL（Connectivity test URL）**：
服务器连通性测试请求访问的目标地址，是用户可修改的非敏感偏好信息，在展示、日志与诊断中无需脱敏。

**代理响应延迟（Proxy response latency）**：
完成目标地址选择与预热后，经指定服务器配置访问测试 URL 的 HTTP 响应头耗时，以成功样本的中位数表示。它与测试目标及测试条件有关，不表示服务器 IP 的纯网络往返时间或下载速度。

**配置组最快响应延迟（Fastest group response latency）**：
配置组全部后代服务器的成功测试结果中，符合展示条件的最小代理响应延迟。它不表示活动配置组实际选用的服务器或负载均衡后的响应耗时。

**托管插件（Managed plugin）**：
由产品随应用发布的 SIP003 插件，其发布版本与来源事实属于随应用提供的程序，不代表用户自备的同名程序。

**插件记录（Plugin record）**：
一份可由多个名称引用的本机插件资料，包含可执行程序的选择、共享的本地启动参数与插件传输模式；用户记录具有独立于名称的持久身份。

**插件传输模式（Plugin transport mode）**：
一条插件记录承载的传输协议范围：`tcp_only` 表示插件仅承载 TCP，`tcp_and_udp` 表示插件承载 TCP 与 UDP。它不表示插件已经具备 SIP003u 支持，也不同于本地 SOCKS5 端点的 UDP 中继能力。

**插件别名（Plugin alias）**：
引用同一插件记录的名称之一。同一记录的名称共享程序、本地启动参数与插件传输模式，服务器资料保留自己使用的名称。

**本地插件启动参数（Local plugin arguments）**：
当前 macOS 用户为一条插件记录设置的有序命令行参数，由所有引用该记录的服务器共享。它与服务器连接资料中的插件选项不同，不随服务器资料分享。

**用户插件映射（User plugin mapping）**：
当前 macOS 用户维护的插件名称与本机插件记录之间的对应关系。同名映射覆盖托管插件的默认选择，但不改写服务器配置中的插件引用。

**有效插件目录（Effective plugin catalog）**：
由当前应用提供的托管插件与用户插件映射共同确定的插件名称、实际来源与可用性事实集合。失效的用户映射仍保留其覆盖关系，不自动退回同名托管插件。

**旧版配置（Legacy configuration）**：
冻结的旧版客户端保存的服务器列表与偏好设置。

**旧版导入（Legacy import）**：
经用户确认，将旧版服务器资料转换为新客户端独立手动组的操作。它只迁移服务器资料，保留旧版来源和新客户端现有偏好设置。

### 代理规则

**代理模式（Proxy mode）**：
用户选择的流量路由方式，包括规则模式、全局模式和直连模式。全局模式下公共目标默认经 Shadowsocks 转发，固定本地目标仍直连。

**规则模式（Rule mode）**：
由内置规则和自定义规则决定各目标代理或直连的路由模式；未匹配目标的处理方式由规则默认动作决定。

**规则默认动作（Rule default action）**：
规则模式下，没有规则匹配目标时采用的代理或直连动作。
_避免用词_：回退（Fallback，含义不明确）。

**内置规则快照（Built-in rule snapshot）**：
随应用发布的固定规则集，包含来源、归属与转换报告等资料。它只保留转换后可决定路由的规则，不保留被吸收或遮蔽而省略的上游条目。

**自定义规则（Custom rule）**：
用户拥有的代理或直连规则，以精确域名、域名后缀或 IPv4/IPv6 地址范围作为匹配条件，并具有持久身份。列表顺序不代表路由优先级。
_避免用词_：用户规则（User rule）。

**规则身份（Rule identity）**：
规范化匹配条件与路由动作的组合，用于识别不同来源中的等价规则。它与可编辑自定义条目的持久身份不同，单个 IP 地址与其完整前缀长度的 CIDR 等价。

**规则来源归属（Rule source membership）**：
一个规则身份所属的全部来源；等价条目合并展示时仍保留各来源归属。

**规则停用（Rule disablement）**：
用户保存的、跨全部来源排除某个规则身份的选择；来源条目仍保留，覆盖同一目标的更宽规则也不因此被停用。固定本地绕过策略不能停用。

**规则吸收（Rule absorption）**：
同动作规则之间的覆盖关系，其中较宽规则使较窄规则在路由判定中冗余。它与反动作遮蔽不同，也不删除已保存的自定义规则。

**规则遮蔽（Rule shadowing）**：
动作相反的规则之间的覆盖关系，可以是全部或部分覆盖，也可以涉及固定本地绕过策略。它与同动作吸收不同，也不表示规则已在运行中生效。

**快照转换报告（Snapshot conversion report）**：
生成内置规则快照时记录的转换、吸收、跳过与拒绝数量。它描述快照生成时的结果，而非当前规则集合的覆盖关系或运行状态。

**离线规则测试（Offline rule test）**：
针对域名、IP 地址或 URL 主机，仅依据规则给出“代理／直连／未匹配规则”的解释。它独立于代理模式、运行状态和规则默认动作，不解析 DNS，也不测试连通性。

### 代理控制与网络

**代理模式选择器（Proxy mode selector）**：
用户选择规则、全局或直连模式的统一入口，与代理服务开关、系统代理开关和自定义规则管理分别对应不同意图。

**代理服务开关（Agent switch）**：
用户保存的后台代理服务开启或关闭意图，与服务当前是否健康不同。
_避免用词_：代理开关（Proxy switch，与系统代理开关混淆）。

**系统代理开关（System proxy switch）**：
用户保存的、通过 macOS 系统代理设置使用本地代理入口的意图，与设置当前是否已应用或暂停不同。
_避免用词_：代理开关（Proxy switch，与代理服务开关混淆）。

**系统代理配置（System proxy configuration）**：
macOS 网络服务上的设备级代理设置，由不同应用与用户账户共享。
_避免用词_：全局代理配置（Global proxy configuration，与全局代理模式混淆）。

**网络服务（Network service）**：
macOS 中具有独立代理设置的命名网络配置项，包括当前未连接的项。它与物理接口及终端命令地址候选不同。

**期望系统代理配置（Desired system proxy configuration）**：
新客户端已保存设置所要求的代理值，与各网络服务上实际存在的值不同。

**受管系统代理配置（Typed system proxy configuration）**：
新客户端负责管理的 SOCKS、HTTP、HTTPS、PAC、自动发现、简单主机名排除和例外值的完整集合。
_避免用词_：完整代理字典（Complete proxy dictionary，可能包含产品管理范围外的值）。

**系统代理配置差异（System proxy configuration difference）**：
网络服务上的受管代理值与期望系统代理配置之间当前存在的语义差异。它不表示历史变更，也不能证明由哪个应用造成。

**系统代理修复（System proxy repair）**：
用户明确请求将存在差异的网络服务对齐到期望系统代理配置的操作。
_避免用词_：恢复（Restore，可能暗示恢复其他应用的旧值）。

**系统代理暂停（System proxy suspension）**：
后台代理服务或当前模式的出口不可用时，系统代理设置已清除、但系统代理意图仍开启的临时状态。清除失败属于清理失败，不属于成功暂停。

**附加系统代理例外（Additional system-proxy exception）**：
用户添加的主机名、域名、IP 地址或 CIDR，用于让 macOS 将对应流量排除在系统代理之外。它不改变固定本地绕过策略或代理规则。
_避免用词_：绕过列表（Bypass list，混淆用户附加项与产品固定策略）。

**固定本地绕过策略（Fixed local bypass policy）**：
产品规定始终直连的本地 IP 范围与主机名，适用于系统代理和本地代理入口。用户可查看该策略，但不能通过附加系统代理例外修改它。

**HTTP 代理入口（HTTP proxy inbound）**：
后台代理服务提供的本地 HTTP/HTTPS 请求入口，与代理模式和旧版 Privoxy 适配器不同。
_避免用词_：HTTP 代理模式（HTTP proxy mode）。

**SOCKS5 UDP 中继（SOCKS5 UDP relay）**：
SOCKS5 入口接受 UDP ASSOCIATE 流量并通过代理服务中继的能力。它不表示系统全部 UDP 流量都会被代理。
_避免用词_：系统级 UDP 代理、自动 UDP 代理。

**旧版 Privoxy 适配器（Legacy Privoxy adapter）**：
冻结旧版中，将 HTTP(S) 请求桥接到本地 SOCKS5 的组件，仅属于旧版实现。

**本地监听（Local listening）**：
仅供本机使用的 SOCKS 与 HTTP 代理入口，始终随后台代理客户端提供服务。

**局域网监听（LAN listening）**：
供网络设备访问的附加 SOCKS 与 HTTP 代理入口，与本地监听共存并使用不同端口；它可以独立关闭。

**局域网身份验证（LAN authentication）**：
局域网 SOCKS 与 HTTP 入口共用的用户名和密码验证，不表示 UDP 中继具备同等保护。身份验证启用时，保存要求用户名形状有效且密码引用存在；新写入 keychain 的密码还需符合形状。身份验证关闭时凭据是保留值，不拦其他局域网设置的保存。

**监听模式（Listener mode）**：
局域网监听启用时采用的地址族选项，包括所有 IPv4 接口、所有 IPv4 与 IPv6 接口、所有 IPv6 接口；与是否启用局域网监听独立。
_避免用词_：监听范围（Listen scope）。

**HTTP 代理环境命令（HTTP proxy environment command）**：
仅设置本机 HTTP/HTTPS 代理环境变量的终端命令，目标为本地监听入口。

**终端代理环境命令（Terminal proxy environment commands）**：
按目标 shell 语法设置 HTTP 与 SOCKS 代理环境变量及本地主机例外的命令。它只影响遵循这些环境变量的子进程。

**终端命令地址（Terminal command address）**：
复制的终端代理环境命令中，HTTP 与 SOCKS 入口共同使用的 IP 地址。它是当前应用会话内的选择，与监听设置和系统代理设置独立。

**代理运行服务（Proxy runtime）**：
为当前用户提供代理入口与外部隧道服务的后台服务，其生命周期独立于图形界面。

**运行配置文件（Runtime configuration file）**：
供外部隧道服务使用、由活动目标派生的连接配置，包含端点、凭据、加密、插件、监听与规则信息。它与用户管理的服务器配置和订阅文档不同。

**运行状态收敛（Runtime convergence）**：
将已部署的代理服务对齐到期望运行配置的过程，与保存用户配置意图是不同的概念。

### 设置与工作区

**登录项（Login item）**：
图形界面应用在用户登录项中的系统注册，是独立的偏好设置。

**独立保存设置项（Independently saved setting item）**：
用户作为一个整体明确保存的设置或一组关联值，其保存边界不包含其他未保存设置。
_避免用词_：即时编辑（Immediate edit，可能暗示每次按键都应用）。

**系统级快捷键（System-level shortcut）**：
用户可配置的键盘操作，即使应用未获得焦点也能触发应用动作。
_避免用词_：全局热键（Global hotkey）、全局快捷键（Global shortcut）。

**窗口内默认动作快捷键（Window-local default action shortcut）**：
绑定到当前聚焦窗口或表单的键盘操作，例如确认对话框；它与系统级快捷键不同。

**工作区页面（Workspace destination）**：
单一工作区中的顶层位置，例如首页、服务器、代理规则或设置。它只表示导航位置，不包含节点选择或功能草稿。

**工作区路由（Workspace route）**：
从工作区或其他应用入口切换工作区页面的导航选择与意图，与用户配置和功能局部状态不同。

**工作区窗口（Workspace window）**：
承载工作区的唯一主窗口；关闭后可从状态菜单重新打开。

**诊断窗口（Diagnostics window）**：
由菜单栏“诊断…”入口显式打开的唯一独立窗口，承载状态摘要、日志查看与复制、脱敏报告导出。关闭后停止诊断轮询，不影响代理运行和日志记录；日志来源选择在本次应用运行内保留。

**自适应应用形态（Adaptive app form）**：
随工作区、独立规则报告窗口和诊断窗口的开启状态变化的应用呈现方式：有窗口时显示 Dock 图标并参与应用切换，最后一个窗口关闭后仅保留菜单栏状态菜单。
_避免用词_：菜单栏形态（Menu bar form，应用形态并非恒定）。

**静默启动（Silent launch）**：
启动时不显示工作区窗口、从菜单栏形态开始的用户偏好。它只影响窗口呈现，与代理服务恢复和登录项分别对应不同设置。

### 凭据与诊断

**敏感信息（Sensitive information）**：
服务器密码、完整插件选项，以及用户提供的非空远程 URL，包括订阅 URL，但不包括测试 URL。

**凭据暴露边界（Credential exposure boundary）**：
产品降低意外泄露及向其他用户账户暴露凭据的保护范围。该范围不包含同一用户进程被攻破、root 访问或快照与备份，也不承诺安全擦除。

**凭据引用（Credential reference）**：
设置与其独立保存的持久凭据之间的非秘密关联，例如局域网身份验证设置与认证密码的关联，与凭据值本身不同。服务器密码、完整插件参数和订阅 URL 属于服务器库中的相应记录，不以凭据引用表达。

**诊断报告（Diagnostic report）**：
用户请求生成的脱敏文档，包含允许披露的运行状态、端点元数据、配置汇总及安全事件资料。它排除敏感信息、服务器地址、备注和原始日志。

**诊断日志视图（Diagnostic log view）**：
用户明确查看或复制界面事件与后台服务原始日志的入口，所展示的原始日志不属于诊断报告。

**诊断事实（Diagnostic facts）**：
可供诊断报告使用的配置目录与代理服务汇总事实，已经脱敏，且不暴露配置条目或敏感信息。