首页系统代理提示与修复

状态：2026-10-01 已确认设计，已在提交 4a0a72c 实现（Issue #73）。领域决策见 ADR-0022，术语见根目录 CONTEXT.md。

目标与现状边界

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

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

操作规则

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

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

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

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

接口差异

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

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

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

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

状态与操作

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

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

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

助手批准与失败组合

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

批准完成后的行为：

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

布局与文案

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

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

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

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

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

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

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

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

验收场景

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

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

9.5 KiB Raw Blame History Unescape Escape