ShadowsocksX-NG/docs/design/system-proxy-runtime-control.md

# 首页系统代理提示与修复

**状态**：2026-10-01 已确认设计，已在提交 `4a0a72c` 实现（Issue #73）。领域决策见 [ADR-0022](../adr/0022-observe-system-proxy-differences-and-repair.md)，术语见根目录 [CONTEXT.md](../../CONTEXT.md)。

## 目标与现状边界

首页 RuntimeControlCard 的系统代理开关表达用户意图，旁边的状态与下方提示表达实际配置；外部修改不自动修复。提示提供用户解决当前问题所需的操作，不把失败结果与助手批准入口互相排斥。

实现前，代码会在网络位置、服务和路径变化后自动应用，忽略单独的代理配置事件；健康失效时保留现有系统代理配置，卡片没有接口差异提示或修复按钮。提交 `4a0a72c` 已实现本文规则；717 项 hostless 单测通过，并通过替身渲染检查了卡片的长名称换行、批准入口与修复进度。以上不证明真实主机系统代理写入、权限批准或观察通知已通过验收。

## 操作规则

| 事件 | 目标行为 |
| --- | --- |
| 用户开启系统代理 | 后台入口与当前模式出口可用后，应用到当前网络位置的全部服务；等待就绪属于该次开启操作的延续 |
| 用户关闭系统代理 | 清除所有网络位置、所有服务的完整代理配置，不恢复历史值 |
| 用户关闭后台代理 | 系统代理意图若开启，则一并关闭，先清除再停止监听；系统代理意图已关闭时不清除 |
| 外部修改代理配置 | 只检查、提示；不自动修复 |
| 网络位置、服务或路径变化 | 只检查当前位置；不因这些事件自动应用 |
| 保存本 App 的端口、系统代理例外等相关设置 | 系统代理开启且后台可用时自动应用；允许覆盖外部修改。未保存的编辑不触发应用 |
| 后台失效或当前模式无可用出口 | 系统代理意图开启时，自动清除全部系统代理配置；保留两个开关的开启意图 |
| 后台恢复健康且当前模式出口可用 | 系统代理意图仍开启时自动应用；允许覆盖暂停期间的外部修改 |
| GUI 启动且系统代理意图开启 | 后台健康时只检查；后台不可用时自动清除，后续恢复健康再自动应用 |
| GUI 启动且系统代理意图关闭 | 不应用、不清除 |

普通断网本身不算后台失效。规则／全局模式要求可用活动目标；直连模式不要求活动服务器。已暂停或失败不会自动关闭开关。用户在暂停期间关闭系统代理后，后台恢复也不再应用。

监控只在 GUI **进程运行期间**进行；关闭工作区窗口、保留菜单栏进程仍属于运行期间。退出 GUI 后不提供即时差异检测、提示或健康变化引发的系统代理操作；后台代理运行不因此停止。

失败的应用、修复或清除不在后台反复重试。新的用户操作或健康恢复事件是新的触发；被动网络事件不是重试入口。

## 接口差异

“网络接口”文案指当前网络位置中的 macOS 网络服务，包括未连接的服务，并不采用终端命令地址选择器的 Wi-Fi／Ethernet 白名单。使用系统设置里可识别、可重命名的服务名称；名单完整换行，不用省略号隐藏接口。

仅比较本 App 管理的代理字段：SOCKS、HTTP、HTTPS 的启用状态、地址和端口，以及 PAC、自动发现、简单主机名排除与例外等值。等价写入和不管理字段的变化不产生提示，也不判断修改者是谁。

提示反映当前差异，不累积历史事件。外部恢复一致后移除对应名称，全部一致后撤下提示。新网络位置或新增服务尚未应用当前配置时，使用“尚未应用”文案，避免误称为外部修改；两类情况同时存在时分段列出，共用一个修复按钮。

修复前重新读取当前位置与配置，只处理当时仍有差异的服务，跳过已经一致的服务，保留本 App 不管理的字段。修复完成后再次读取；写入成功本身不足以撤下提示或显示“已应用”。

## 状态与操作

| 当前状态 | 开关旁文字 | 开关下方内容 | 操作 |
| --- | --- | --- | --- |
| 关闭，且无操作失败 | 未应用 | 现有开启说明 | 无 |
| 首次开启，等待入口就绪 | 待应用 | 等待本地入口与当前模式出口就绪 | 无 |
| 当前配置一致 | 已应用 | 系统代理已指向本地入口 | 无 |
| 外部修改，仍存在差异 | 配置已改变 | 已改变的接口名单 | 修复 |
| 新位置／新增服务尚未应用 | 待应用 | 尚未应用的接口名单 | 修复 |
| 正在应用／修复 | 应用中／修复中 | 保留相关接口名单 | 进度指示，禁止重复操作 |
| 应用／修复失败 | 应用失败／修复失败 | 保留差异名单及失败原因 | 修复 |
| 后台不可用，清除成功 | 已暂停 | 已清除，恢复后自动应用 | 无 |
| 清除失败 | 清除失败 | 失败原因；后台不可用时点明后台状态 | 重试清除 |
| 配置读取失败 | 无法检查 | 读取失败原因；不得继续声称已应用 | 重新检查（只读） |
| 助手待批准，尚无失败结果 | 待批准 | 批准说明与路径 | 在登录项中批准… |

失败结果可以在开关关闭后保留，特别是关闭操作清除失败时，不能用“未应用”掩盖残留设置。尚有差异而无操作错误时继续显示差异名单；读取失败时不能用缓存名单冒充已确认的当前事实。

当前最需要处理的结果决定主要状态：清除失败优先于后台暂停，后台不可用时隐藏配置修复入口。后台恢复后重新检查实际配置。不额外弹通知，也不提供关闭差异提示的按钮。

## 助手批准与失败组合

操作结果说明发生了什么，阻塞原因提供解决入口。助手等待批准时，无论主要状态是清除失败、应用失败还是修复失败，都始终保留批准说明及按钮。隐藏当前无法执行的修复／重试按钮；若错误原因只是未批准，不重复展示同一错误。

批准完成后的行为：

- 已经失败的操作：移除批准说明，恢复“修复”或“重试清除”，不自动重试；结果保留至成功解决。
- 首次开启且尚未执行的请求：继续原先用户发起的应用，仍受当前意图、健康与出口条件约束。
- 新发生的后台健康恢复：按自动应用例外执行。

## 布局与文案

保留系统代理开关与右侧状态，在其下展示警告图标、提示、完整接口名单和操作。警告采用橙色，同时以图标与文字表达状态；按钮采用小尺寸原生按钮，放在名单下一行，不采用醒目的主操作样式。点击修复直接执行，不弹确认；修复中保留名单，按钮显示“修复中…”及进度并禁止重复点击。

```text
设置系统代理       [开启]   配置已改变

⚠ 以下网络接口的代理配置已被改变：
  Wi-Fi、USB Ethernet
  [修复]
```

```text
设置系统代理       [开启]   修复失败

⚠ 以下网络接口的代理配置仍有差异：
  Wi-Fi

系统代理助手等待批准。
请在系统设置 → 登录项与扩展中允许。
[在登录项中批准…]
```

| 场景 | 中文文案 |
| --- | --- |
| 外部修改 | 以下网络接口的代理配置已被改变：{名称列表} |
| 尚未应用 | 以下网络接口尚未应用当前系统代理配置：{名称列表} |
| 修复失败后仍有差异 | 以下网络接口的代理配置仍有差异：{名称列表} |
| 后台不可用，清除成功 | 后台代理不可用，已清除系统代理配置。恢复后将自动应用。 |
| 后台不可用，清除失败 | 后台代理不可用，系统代理配置未能清除。 |
| 修复失败原因 | 无法修复系统代理配置：{原因} |
| 无法读取 | 无法读取网络接口的代理配置：{原因} |
| 助手待批准 | 系统代理助手等待批准。请在系统设置 → 登录项与扩展中允许。 |
| 操作 | 修复／修复中…／重试清除／重新检查／在登录项中批准… |

英文候选已在设计访谈中展示；此文档先记录确认后的中文设计，不修改本地化目录。

## 验收场景

以下保留设计验收场景；已执行的验证范围见上方状态说明，不将替身测试或卡片渲染等同于真实主机验收：

1. 外部修改一个或多个服务，仅出现一次实时差异提示，不产生自动写入；恢复一致后对应名称消失。
2. 不管理字段变化或等价写入不产生提示；本 App 自身应用产生的变化不留下误报。
3. 切换网络位置或新增服务只显示“尚未应用”；未连接服务仍参与检查与修复。
4. 修复前某服务已恢复一致或当前位置已变化，操作基于重新读取的当前差异；成功后重新读取确认。
5. 保存相关设置自动应用；失败保留结果，修复由用户重试，不由被动事件触发。
6. 后台失效时清除全部位置且保留意图；清除失败不显示成功暂停；恢复后自动应用可覆盖外部值。
7. 暂停期间关闭系统代理，恢复健康不再应用；关闭后台代理保留现有级联关闭行为。
8. 健康启动仅检查；不健康且意图开启的启动清除；意图关闭的启动不写系统设置。
9. 任意操作失败与助手待批准共存时，批准入口可见；批准后已失败操作不自动重试，未执行的首次开启可继续。
10. 读取失败显示“无法检查”，重新检查不写配置；读取恢复后再呈现真实状态。
11. 关闭工作区窗口仍监控，退出 GUI 不监控；再次启动按启动规则检查。