Qiu Yuzhou
a7465154d2
收起状态按钮只显示当前选中 IP；接口名称（接口：…）与地址类型 （地址类型：…）以说明行展示在按钮下方，与菜单项的 title/subtitle 结构对应。模型移除不再被呈现层使用的 label 组合字段。
4.2 KiB
首页代理环境变量命令地址选择
日期：2026-10-01。 状态：已实现（issue #72）；交互设计与测试边界来自 grill-with-docs 会话，spec 已发布为 Issue #72。
功能范围
首页“复制代理环境变量设置命令”卡片在非“仅本机”监听方式下，在 zsh / bash 和 fish 两个复制按钮上方显示一个单选下拉框。仅本机模式隐藏下拉框并使用 IPv4 回环地址。
所选地址同时用于两种 shell 命令的 HTTP、HTTPS 和 SOCKS 端点。端口取已保存的监听设置，现有 shell 语法、变量集合和 no_proxy 内容保持不变。IPv6 在 URL 中使用方括号。选择只改变生成的命令，不改变监听配置或系统代理。
候选地址
仅包含 loopback，以及本机当前启用的 Wi-Fi、Ethernet 接口的单播 IP。VPN、其他虚拟接口和其他接口类型排除；不能仅依据 BSD 接口前缀或通用 Ethernet 链路类型来接受虚拟接口。无法确认是允许类型的非回环接口不纳入列表。
不提供手动输入，不提供通配绑定地址，IPv6 链路本地地址排除；IPv6 地址经 SIOCGIFAFLAG_IN6 查询内核标志，IN6_IFF_TEMPORARY（RFC 4941 隐私临时地址，会轮换）不进候选。IPv4 链路本地地址属于允许接口的单播地址时可以列出。候选列表不表示网络连通性已验证。
| 已保存的监听方式 | 地址族 | 默认地址 |
|---|---|---|
| 仅本机 | IPv4 回环；隐藏下拉框 | 127.0.0.1 |
| 所有 IPv4 接口 | IPv4 | 127.0.0.1 |
| 所有 IPv4 与 IPv6 接口 | IPv4、IPv6，包含两个回环地址 | 127.0.0.1 |
| 仅所有 IPv6 接口 | IPv6 | ::1 |
下拉菜单项主行显示 {IP}，副标题行显示「注记 - 接口名称」（无注记时仅接口名称；菜单项经 adaptive-controls 机制把两个 Text 桥接为 NSMenuItem 的原生 title/subtitle，注记与 ifconfig 同源，如 autoconf secured、dynamic）。收起状态只显示当前选中项的 {IP}，其下以说明行展示「接口：{接口名称}」与「地址类型：{注记}」（有注记时），便于识别地址稳定性。接口名称优先取 SCNetworkInterfaceGetLocalizedDisplayName(interface)；名称缺失或无法映射到 SystemConfiguration 接口时，回退到 BSD 接口名，但不会因此放宽接口类型过滤。回环项回退名称为 lo0。
回环项置顶，双栈时 127.0.0.1 在 ::1 前。其余按接口名称排序，同一接口先 IPv4 后 IPv6，再按地址稳定排序。同一接口的重复 IP 合并；不同接口即使 IP 相同也保留接口身份。
选择生命周期与刷新
选择在本次应用运行期间保留，包括离开首页后返回；不跨应用重启持久化。进入首页、网络变化以及复制前刷新候选地址。监听方式变化时立即重新过滤候选。
所选地址消失，或监听方式不再支持该地址时，回退到对应监听方式的默认回环地址。复制前刷新发现地址失效时，本次复制使用回退后的地址，界面与命令一致。
地址枚举失败时仅保留兼容的回环项，继续允许复制。代理未运行时也允许复制；生成命令不承诺端点当前可连接。
实现与验证边界
地址枚举、接口名称及类型识别通过可注入的事实来源提供，UI 不自行访问底层控制器拼接命令。应用会话状态持有选中地址的接口身份和地址值，不使用界面显示名称作为身份。
需要验证四种监听方式的候选过滤和默认地址、Wi-Fi/Ethernet/loopback 类型过滤、VPN/虚拟接口排除、名称回退、IPv6 URL、两种 shell 的共享选中地址、离开首页后保留、应用重启后重置、网络变化和复制前失效回退，以及枚举失败时的回环退化行为。用户明确不做视觉验收；系统接口映射通过非视觉验证核实。
现有决策调整
此设计扩展 ADR-0015 中“命令始终面向本机回环”的旧约定。实现时同步更新该 ADR 的命令地址段落以及 CONTEXT.md 中对应定义和约束；健康检查和系统代理目标仍由监听方式确定，不受命令地址选择影响。此项是可逆的首页交互调整，不新增 ADR。