v0.17.0 — 偏好设置 UI/UX 第一批：OKlch 深色视觉 + 配置可信性修复

新增

偏好设置 UI/UX 第一批

• 深色 OKLch 视觉规范迁移：单一深色主题取代浅色优先/系统跟随双主题；token 与组件度量对齐 docs/design/ 设计规范（15px 正文、38px 按钮/输入、52px 面板头、状态色 success/warn/danger），设计规范与交互原型入库为单一真相源
• 侧栏：⌘K 搜索过滤导航（标题/副题/领域关键词、无结果提示、Escape 清空）；导航项未保存圆点；头部 saved-hint；状态栏恒显 ⌘S/⌘K 提示
• 窄窗口（≤1080px）：服务器/供应商主列表转横向选择条，标题与子标签固定、详情区滚动；880×600 可完成核心操作
• 端口映射与 NFS：改带字段标签的分组表单，五位端口与长路径不再挤压；转发条目轻分隔列表，按详情宽度自适应同行/双行，测试反馈独立整行

配置可信性修复

• 快速接入：默认勾选项实际参与执行；模型/协议选择跨重绘保留，确认与执行使用同一份计划；零客户端选择不再误报成功
• 供应商：替换 API Key 草稿跨页/跨重绘保留；「拉取模型 / 测试连接」提交当前表单草稿——后端按稳定 ID 恢复掩码凭证、复用保存校验、不落盘（不带 draft 的调用仍测试已保存配置）
• OpenVPN：用户名/DNS 修改进入未保存状态，profile_set 等运行态装饰不再产生脏数据
• 确认弹窗补齐取消文案翻译、对话框名称与 Shift+Tab 双向焦点循环

全量变更: v0.16.1...v0.17.0

v0.16.1 — VPN IPv6 泄漏修复 + 移除「经代理启动」

修复

VPN 连接后 Codex 等 AI 客户端断连（IPv6 泄漏）

• 真因：纯 IPv4 隧道下，物理网络的原生 IPv6 绕过隧道直接出网，OpenAI 系域名在泄漏路径上被 SNI 重置。此前的 reject 路由堵口会被 macOS configd 在会话中途撤掉（真机实测 8 分钟后消失）。
• 修复：up 脚本对默认路由网络服务执行 networksetup -setv6LinkLocal（服务级配置，扛 RA 刷新/睡眠唤醒），reject 路由降级为兜底；断开时精确还原原 IPv6 模式。

移除「经代理启动」功能

• 该功能注入的 https_proxy=127.0.0.1:8888 环境变量无法从已启动进程回收；SSH→VPN 切换后（8888 随接入层互斥关闭），旧终端与经其拉起的守护进程持续连接被拒（真机案例：codex app-server 守护）。
• 整体移除功能与 capture/chromium_proxy.py 模块；系统代理开关（networksetup 事务式）不受影响。

全量变更: v0.16.0...v0.16.1

v0.16.0 — 竞态修复批 + 架构加固 R7-R9

修复

P0（v0.15.0 带病）

• _on_tick 空闲态 NameError——空闲挂机即触发（47b73ea）

竞态与状态一致性

• 接入切换（SSH↔VPN）、转发重连、配置保存三处竞态修复（PR#121）
• 服务器重连按最新保存的角色分派，不再用陈旧角色拉起
• VPN 安装资产新鲜度：stamp sidecar 重装判据单一归宿（改了脚本/DNS 逻辑不再用旧资产到天荒地老）

设置窗

• VPN 三个端点生产环境 503 修复（profile/credentials/连接操作全恢复）
• 空行校验不再连坐正常行；token 铸造不再被空 host 行恒败（R9 同窗交互债）

校验与 i18n

• 校验止血：host/port 两规则 Python 补齐 + 设置窗镜像同步
• 原生窗（webview 提示/日志窗）中文残留全部进 locale catalog——i18n 迁移清零

内部加固（架构评审 R7-R9 收官）

• VpnCoordinator 接入域收编：app 不再 getattr 捅 VpnClient 内部；VPN 稳定 id 寻址
• servers[] 形状访问器全线下沉 shared/server_shape，读侧清零
• local_token 写径收进事务边界；行校验按事务触面自动跳
• 防漂移守卫扩域：root+suanpan → 全部 11 域（模块描述删行即红）
• 构建链修复：图标再生成纯 Pillow（numpy 哑弹）、build staleness 检查、add-data 自 manifest 单源生成（修掉 18 个运行时模块漏收）

升级说明

• 配置无迁移（schema 不变）
• VPN root 侧脚本在下次连接时按 stamp 自动重装（可能弹一次管理员授权）

Full Changelog: v0.15.0...v0.16.0

v0.15.0 — OpenVPN 客户端 + 菜单五段定稿「行即开关」+ 服务层自治

新功能

OpenVPN 客户端（全功能）

• 服务器卡 OpenVPN 服务：.ovpn 导入（桥接式文件选择）、一键连接/断开、10s 确认切换
• root openvpn + management interface 受控执行：sudoers argv 全量钉死（零通配）、profile 净化（脚本/管理类指令剥除）、崩溃孤儿收养、root 目录无空格布局
• VPN established 后服务层会话自动重建（路由翻转自愈）

菜单栏五段定稿「行即开关」

• 状态（仅活跃期有行）→ 接入（SSH/VPN 行即开关）→ 功能（系统代理/端口映射/远程挂载）→ AI ▸ → 应用
• 主图标四色：灰=无连接 / 蓝=SSH 已连接 / 绿=VPN 已连接 / 黄=连接中
• 20 行收至 14-16 行；组标题健康挂活跃计数、异常挂 ⚠

接入层互斥 / 服务层自治（ADR-011 修订）

• 接入层全局唯一：任一台服务器的 -D 代理或 OpenVPN 二选一
• 服务层按服务器自治：每台服务器 0..n 端口映射 + 0..n NFS 挂载独立运行，连 VPN 不再陪葬（A 服务器做 VPN、B 服务器做转发/挂载的拓扑两条线互不干扰）
• 代理服务器自己的转发改独立会话（-L 便车退役）——点它不再重启整个代理

修复

• VPN DNS 应用竞态免疫（迟到 down 还原新连接 DNS 的竞态结构性不可复现）+ IPv6 绕行 reject 路由 + dns.log 全程诊断日志
• 脚本版本化重装（改了注入逻辑不再「磁盘 conf 用到天荒地老」）
• notarize 守卫消息的 bash 3.2 非 ASCII 解析炸点（潜伏 bug，tag 缺失分支首次被走到）

升级说明

• VPN 相关的 root 侧脚本（/Library/MagicStack/openvpn）在首次连接 VPN 时自动检测版本并重装（会弹一次管理员授权）
• 配置无迁移（schema 不变）

Full Changelog: v0.14.0...v0.15.0

v0.14.0 — 产品国际化（中英双语）+ NFS 挂载回归修复

功能

• 产品国际化（ADR-012 M0–M2，#114 #116）：菜单栏与设置窗全量中英双语，一处切换即时生效
  • 语言偏好：自动（跟随系统）/ 中文 / English——菜单「选项 ▸ 语言」或 设置窗「系统选项 ▸ 语言」均可切换，两处同拍生效；未保存表单不丢
  • 自研语义键 catalog 双语单一真相（非 gettext），五道守卫测试钉住翻译纪律（键位奇偶/占位符、en 全译、取词、汉字字面量、HTML 渲染层残留）
  • 设置窗 ~490 键全量键化（含校验消息）；浏览器直开与登录页同按语言渲染
• R5 遗留清偿（#113）：抓包状态漂移报警、余额页来源 Agent 维度等三刀切、网关缝卫生

修复

• NFS 挂载 v2 schema 回归（#115，v0.13.0 引入的真机事故）：服务器中心重构后 NFS 会话仍按 v1 形状注入转发表落空 → 连接会话与 NFS 会话双 spawn 抢绑同口 → 重试死循环、NFS 本地端口无监听。v0.13.0 + NFS 挂载的用户请升级
• 设置窗侧边栏溢出：默认窗口尺寸下「复制 AI 助手指令」被窗口下缘裁掉——侧边栏垂直压缩 + 矮窗口导航内部滚动
• 全页面双语审查五项（#116）：快速接入页代码字面量渲染、页头副标题/pending 按钮/登录页文案双语缺口、服务器页导语错位、侧边栏副标题折行

验证

• pytest 2177 通过 + node 147 通过（五道 i18n 守卫在内）
• 真机装机回归：NFS 三挂载自动恢复、1080/8030/12049/9527 全端口就绪
• 公证：app + dmg 双 Accepted + Stapled 一次过

v0.13.0 — 更名 Magic Stack · 服务器中心配置模型

功能

• 🔄 产品更名 Magic AI Router → Magic Stack——「Router」只命名了三层闭环（接入/路由/审计）的一层，Stack 如实命名整套本地 AI 网络栈。配置路径/Keychain/密钥零迁移，老用户无感升级
• 🖥 服务器中心配置模型（ADR-011，Server → Service → Instance）：配置从 tunnels[] 换轴为 servers[]——一台远程服务器一页配完（连接 + 全部服务），v1 配置自动迁移（稳定 id 保留，服务器名/密钥/挂载/Keychain 密码零损失）
• 📑 设置窗「服务器」单视图：侧边栏收敛为 服务器 + 网络设置；服务配置横向 tab 展开（连接 / 端口映射 / NFS / OpenVPN 占位），tab 常驻渲染——切 tab 不丢未保存编辑
• 🔍 服务卡一键检测：每台服务器可探「这台机器上有什么可以用」——SSH 可达性+延迟 / NFS 发行版+2049 监听+导出表 / OpenVPN 装没装（/api/server-check，新服务类型 = 注册表加一张卡）
• ✨ 设置窗 SVG 图标体系：16 枚 Lucide 单笔触线性图标（侧边栏/服务 tab/能力徽标/区块头/空态），明暗自适应

修复

• 端口映射与远程挂载的空态引导可点击直达设置页；状态栏菜单故障可见性（⚠ 异常计数）；Docker 形态合法 reload 误判竞态（watchdog 对账策略两形态共享）

验证

• 全量测试 2146 passed + node 147（pytest 全绿；跨语言校验镜像报警在位）
• Apple 公证：app + dmg 双双 Accepted + Stapled，Gatekeeper 评估通过
• 真机验收：v1→v2 配置自动迁移实测（两台服务器/挂载/密码零损失）；SSH/NFS/网关全链路恢复验证

v0.12.0 — 端口转发逐条启停 + 网关自愈

端口映射升级为逐条启停、网关僵尸态自动检出重建。另收一批真机修复与两轮架构评审内功（2070 测试全绿）。

端口转发逐条启停

• forwards 行新增 enabled（缺省 true，旧配置零迁移）——停用行不进会话 -L 集合、不占本地端口；未运行的会话绝不因翻转被拉起
• 菜单「端口映射 ▸」重排：端口摘要移出隧道行标题，每条转发独立成行 8030 → 3080 · 已映射/已停用/待会话，点击即启停（圆点随会话着色）
• 设置窗转发表开关列，保存流生效

网关自愈（watchdog）

• audit() 健康审计（running 旗标 vs 端口真相）+ tick 对账：连续 3 次失配 ≈15s 检出僵尸态并 worker 重建；用户显式停止与崩溃态绝不拉起；失败退避 30s
• Docker 形态同谓词进程内 watchdog（补 compose 无 healthcheck 的缺口）

修复

• 远程挂载清单「N 挂载中」徽标恒为 0（nfs_states 对象形状漏计）；mounts:[null] 直接 400 拒绝
• 设置窗端口预检两处漏检（NFS 本地端口、显式 0 端口——此前第一道闸放行、只在提交 422 现形）；新增跨语言校验漂移报警器钉住 JS↔Python 镜像契约
• :9528 孤儿监听：开窗异常路径零持有者常驻——持有者收进唯一写口，变更即收敛
• 用量统计 agent 维度补齐（anthropic 流式与转换车道错误路径此前漏记）

架构内功（两轮评审，PR #97）

守卫单一归宿 / 运行态装饰单点声明 / 供应商注册表卡 / config_server 路由表 dispatch / 网关四车道共用骨架——行为保持型重构，净删约 470 行镜像代码；code-review 双轴（Standards/Spec）通过。

验证

pytest 2070 绿 + node 141 绿；DMG Developer ID 签名 + Apple 公证 + staple 通过（Gatekeeper: Notarized Developer ID）。

v0.11.0 — ADR-010 协议矩阵：一个 Key 配好全部 Agent

一个 Key 配好全部 Agent：网关升级三协议入站（新增 Codex/Responses），快速接入向导一键配置 Claude Code / Codex / OpenCode / ZCode。另收三项真机案例修复。

三协议入站 + 多 Agent 注册表（ADR-010）

• 三协议入站：Anthropic Messages / OpenAI Chat / Responses（Codex）——同协议直通优先、失配才经转换器（Anthropic⇄OpenAI 请求/响应/SSE 全量翻译，含流式），供应商只需配一份
• 快速接入向导：选厂商填 Key → 端点三级探测（存在性/认证/模型清单）→ 勾选 Agent 一键配置；Agent 里写入的是本地网关凭证，厂商 Key 永不落 Agent 配置
• Agent 矩阵：Claude Code / Codex（tomlkit 增量编辑）/ OpenCode / ZCode；菜单新增「配置 Agent…」深链直达向导
• 供应商注册表升级端点矩阵：每厂商 anthropic/openai/responses 端点卡 + 认证头 + 套餐变体

Claude Code 同步：规则=持久真相

「保存并同步」从此同时写入网关 tier 路由规则（/.suanpan.yaml）和 Claude Code env（/.claude/settings.json）——此前同一意图存在两份真相且只有一份可编辑，"幽灵规则"持续把别名流量路由到已裁剪模型（真机案例：2966 次请求命中 glm-5.2）。现在确认弹窗会展示规则 diff 与「未在清单」软警告，一次保存两面同时对齐。

配置面端口收敛（ADR-009）

配置 API（:9528）默认不再常驻监听：设置窗开着 / 复制 AI 助手指令后 / 显式开关（系 统 ▸「配置 API 服务」）三持有者任一在场才监听——冷启动零配置面端口。Docker 形态不受影响。

修复

• 保存可致网关永久下线：uvicorn 优雅停机无限等待在连连接 → 僵尸线程卡死运行态 → :9527 再也不监听（真机案例：Claude Code Connection refused 重试 10 次）。停机改为 2s 有界宽限，reload 自愈
• 「关于」页从一行式旧文案重写为五域全景

验证

pytest 2004 绿 + node 130 绿；真机四轮验证：协议矩阵 SIT（探测/配置/请求全链路）、规则对账单 preview（claude-opus/haiku glm-5.2→glm-5.3）、保存触发 reload 网关存活、冷启动 lsof :9528 为空。DMG Developer ID 签名 + Apple 公证 + staple 通过。

v0.10.1 — 挂载失败可见性 + 浏览器设置页复制指令修复

两个真机案例驱动的可见性/可操作性修复：挂载失败不再「没反应」，浏览器打开设置页的「复制 AI 助手指令」从哑巴按钮恢复为可用。

挂载失败可见性链路 + 一键修复导出

2026-09-18 真机案例：加挂载项未先「一键安装」→ 远端无导出 → mount_nfs 报错如天书，且设置窗是不刷新的快照——错误永远不出现，用户视角是「挂载没反应」。四级修复：

• 失败分类：mount_nfs 错误码 → 中文指引 + fixable 标记（ENOENT → 「远程路径不存在或未导出——请先执行一键安装」）
• 状态投影：MountState 新增 fixable 字段（NamedTuple 默认值，位置兼容），失败写入/成功清空
• 装饰升级：/api/state 的 nfs_states 携带 {status, error, fixable}——error 不再在传输层丢弃
• 设置窗闭环：状态徽标 + 错误行内红字；fixable=exports 时一键「修复导出并重挂」（自动执行远程安装 → 1 秒自动重挂）；NFS 视图 5s 定向轮询只合并装饰字段、绝不碰未保存的表单（node 测试钉死不变量）

浏览器设置页「复制 AI 助手指令」修复

浏览器直开设置页（http://127.0.0.1:9528，输 token 登录）是官方支持入口，但侧栏「复制 AI 助手指令」按钮在此场景是静默空操作——此前 token 拼装移到原生侧时，只有 WKWebView 路径拿到了实现。修复：

• 新增认证 GET /api/agent-instructions——文本与菜单栏/原生设置窗复制路径逐字节一致（agent_instructions() 单一归宿），token 经 HttpOnly 会话 cookie 携带、不进 JS
• JS 双通道：原生设置窗走 bridge 不变；浏览器 fetch 后 Clipboard API 写剪贴板 + toast 反馈（Safari 用户手势不跨 await 存活时退 execCommand 兜底）

文档

• agent.md API 表新增 /api/agent-instructions；CLAUDE.md / 双语 README 同步浏览器入口说明
• 新增 AGENTS.md（指向 CLAUDE.md 的符号链接，单一真相源）

验证

pytest 1901 绿 + node 127 绿；临时实例 HTTP 冒烟（无 token 401 / 带 token 200 / 单一归宿一致性）通过；真机安装 v0.10.1 构建后三个 NFS 挂载自动恢复、新路由 401 门生效。DMG Developer ID 签名 + Apple 公证 + staple 通过。

v0.10.0 — NFSv4 远程挂载（SSH 隧道）+ 退出清理修复

远程服务器的目录经 SSH 隧道以 NFSv4 挂载到本机，像本地磁盘一样直读直写。决策落档 ADR-007；四轮架构评审同日收官（ADR-008）。

NFS 远程挂载（ADR-007）

• 仅 NFSv4：单端口 2049、一条 SSH -L 隧道承载该服务器全部挂载；macOS 自带客户端，本地零内核扩展（对比 SSHFS 的 macFUSE）
• 服务器一键安装：设置窗「远程挂载」页填路径 →「一键安装 / 更新导出」——发行版探测（apt/dnf/yum）+ 装包 + 写应用专属 exports（仅导出给 127.0.0.1，不对公网暴露）+ 2049 验证，幂等可重复执行
• 本地挂载：默认 /Volumes/<挂载名>（可自定义）；首次挂载弹一次管理员授权（sudoers 规则仅限 mount_nfs/umount 两个命令），之后免密
• 断线自愈：hard 挂载 + 隧道断开立即强制卸载（Finder 不卡死）→ 网络恢复自动重挂；应用退出先卸载后断隧道
• 属主统一映射（all_squash）：服务器/Mac 用户 UID 不一致时文件属主统一到 SSH 用户，一键安装自动处理目录属主
• 密钥登录的服务器：sudo 密码输入一次存 Keychain，或直接支持 NOPASSWD
• 菜单栏新增「远程挂载 ▸」分区（挂/卸/打开目录/状态徽标）；状态行挂载计数

退出清理修复

• AppleEvent 退出（osascript / 注销 / 重启 / 升级替换）曾跳过全部清理——NFS 会话的 ssh 泄漏成孤儿进程占住本地端口，下个实例挂载死循环（真机实测定位）；清理链收进幂等 _shutdown 并挂 NSApplicationWillTerminate，两条退出路径同一咽喉
• 启动时自动清扫上个实例崩溃残留的陈旧挂载

设置窗

• 「远程挂载」页与「隧道」页同款 master-detail 布局（共享服务器选中）；偏好设置窗口加宽至 1200×880

架构评审四轮收官（ADR-008）

SSH 会话三件套收敛为 SshSession（镜像 3→1）、prepare 校验分域（303→80 行）、运行态投影 RuntimeProjection 单一 seam、ForwardState/MountState NamedTuple 化、六件次级清偿（含一处行为修复）——剩余候选的「暂不做 + 触发条件」清单落档 ADR-008。

验证

pytest 1893 绿 + node 124 绿；双服务器真机 E2E（一键安装 / 挂载 / 读写核对 / 断线恢复 / 干净卸载 / 现场还原）；DMG Developer ID 签名 + Apple 公证 + staple 通过。