proxy-station/scripts/ffsb/README.md

历史本机 FFSB / Surge 协调层

已退役（2026-10-19）：当前使用正式 Proxy Station 订阅内的手动 🦁 FFSB 选项。LaunchAgent 已停用，不要按下文重新安装；最新配置和设备前提见 手动订阅方案。以下仅保留为历史实现与回滚参考。

此工具只针对已验收的 macOS 本机。生产维护独立 🦀 Claude 组；本机增加自动入口 Claude。25 项范围来自 ffsb-service networks list，快照为 rules/ffsb-domains.json，不能把精确的 claude.ai 扩成通配域。实际报告见 docs/FFSB-SURGE-IMPLEMENTATION-2026-10-19.md。

• overlay.py：从完整生产配置生成本机候选。FFSB 就绪时，25 项 DNS 指向 100.70.255.254，业务策略绑定 utun100；其余 Claude 规则仍使用 🦀 Claude。FFSB 未就绪时移除这些 DNS 覆盖，自动入口只包含 🦀 Claude。
• reconcile.py：读取 FFSB 管理/信令状态并探测 DNS；经官方 surge-cli --check 后原子替换本机生成文件，仅在该文件为活动配置时 reload/flush dns。失败保留最近有效源；重载失败会在下一轮重试。不会关闭/开启 FFSB 或 Surge。
• 生产源 URL 取自原有 Proxy Station.conf，只允许 HTTPS。每小时重新获取、原生验证并保存到私有缓存；--refresh 可立即刷新。原托管文件不被写入。生成配置是普通本机配置，更新由协调任务负责，不能把普通配置的 UI 更新按钮当成此任务的刷新入口。
• 用户级 LaunchAgent 每 10 秒运行一次；两端需要就绪后再使用，切换不承诺瞬时完成或迁移已建立的连接。

已安装文件位于 ~/Library/Application Support/ProxyStationFFSB/，LaunchAgent 为 ~/Library/LaunchAgents/com.proxystation.ffsb-overlay.plist；生成配置为 ~/Library/Application Support/Surge/Profiles/Proxy Station Claude.conf。配置缓存与备份含节点凭据，保持私有目录和文件权限，不提交 Git。

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s scripts/ffsb -v
PYTHONDONTWRITEBYTECODE=1 /usr/bin/python3 "$HOME/Library/Application Support/ProxyStationFFSB/reconcile.py" --refresh
launchctl print "gui/$(id -u)/com.proxystation.ffsb-overlay"

更新这些源码不会自动更新本机已安装副本；重新安装前先测试并保存副本。接口名、FFSB DNS、域名范围或服务输出格式改变时须重新验收。

手动 --refresh 成功且配置没有变化时，输出 Refresh succeeded; configuration unchanged; mode=FFSB; no reload（回退时 mode 为 Surge）。后台定时检查无变化时保持静默。拉取或原生校验失败但已有有效缓存时，stderr 明确提示沿用缓存，手动无变化提示为 Refresh failed；此时仍可正常完成缓存协调，退出码不能单独代表远端刷新成功。日志不输出订阅 URL。

回滚本机覆盖层

先停用协调任务，再切回原来的 Proxy Station，保留文件以便调查：

launchctl bootout "gui/$(id -u)/com.proxystation.ffsb-overlay"
/Applications/Surge.app/Contents/Applications/surge-cli profile switch 'Proxy Station'
/Applications/Surge.app/Contents/Applications/surge-cli managed-profile update

这仅撤销本机覆盖，生产仍保留独立 🦀 Claude 组。生产规则回滚应通过管理 API 使用本次快照定向恢复，不覆盖其他人后续变更。FFSB 自身设置未修改。

已知边界

系统分域 DNS 和已有 host routes 仍由 FFSB 负责。FFSB 关闭后的回退已实测；FFSB 处于“接口存在但内部故障”时，系统客户端仍可能受其残留 DNS/路由影响，不能将“关闭回退”扩大解释成所有隧道故障都自动修复。

Surge 原生 fallback 有探测及缓存周期，本地状态协调也有周期。短时过渡可能失败，既有连接不迁移。硬编码 IP、独立远端代理/加密 DNS 等不可识别目标无法保证按域名分类。真实应用认证、长流、睡眠/网络切换及完整启动顺序的覆盖状态以验收报告为准。