merge: maestro/tsk_iP5-_Ztq5THx [桥接 API 面 Channel 契约 + 三端原生骨架] [tsk_rcNKc3GQHBUd]

合并冲突补救：原分支从 merge base 7871512 分叉，仅修改 client/ 目录，
与 main 新增的 server/(apierr/idgen/CONVENTIONS.md) 完全不重叠，
无真实文件冲突，手动应用 feature branch 的全部 client/ 改动。

client 侧新增：
- lib/bridge/vpn_bridge.dart      — Dart↔原生通道契约（冻结）
- lib/bridge/vpn_bridge_mock.dart — 假内核，UI 联调用
- lib/bridge/kernel_process.dart  — 桌面子进程管理接口
- ios/PacketTunnel/{Info.plist,PacketTunnelProvider.swift} — NEPacketTunnel 骨架
- ios/Runner/VpnManager.swift     — NETunnelProviderManager 封装
- android/.../PangolinVpnService.kt — VpnService 骨架
- android/.../VpnEventBus.kt      — Application 级状态总线
- test/bridge/vpn_bridge_mock_test.dart — 桥接层单元测试

client 侧修改：
- android/.../MainActivity.kt    — 注册三通道（MethodChannel + 2×EventChannel）
- android/.../AndroidManifest.xml — 声明 FOREGROUND_SERVICE + PangolinVpnService
- ios/Runner/AppDelegate.swift   — 注册通道 + VpnManager 初始化
- ios/Runner/Info.plist          — 新增 NSVPNUsageDescription
- ios/Runner.xcodeproj/project.pbxproj — 添加 PacketTunnel extension target
- lib/widgets/connect_button.dart — VpnStatus 迁移到 bridge/vpn_bridge.dart
- lib/widgets/home_shell.dart    — error 状态 UI 分支补全

client/lib/bridge/kernel_process.dart

@@ -0,0 +1,112 @@
+// kernel_process.dart — 桌面端内核子进程管理接口
+//
+// 桌面平台（macOS / Windows / Linux）直接将 sing-box 二进制作为
+// 子进程运行，通过其 Clash 兼容 REST API 进行控制。
+//
+// 本文件仅定义接口契约；具体实现由任务 11D（桌面 PoC）完成。
+//
+// 进程生命周期：
+//   spawn(configPath) → 子进程启动，REST API 开始监听
+//   kill()            → 优雅停止（SIGTERM），超时后 SIGKILL
+//
+// Clash API 通信由 [ClashApiClient] 封装，基地址固定为
+// http://127.0.0.1:9090（可覆盖）。
+
+import 'dart:async';
+
+// ── Clash API 客户端 ─────────────────────────────────────────────
+
+/// sing-box Clash 兼容 REST API 客户端。
+/// 实现由 11D（桌面 PoC）填充；本骨架仅定义调用约定。
+class ClashApiClient {
+  ClashApiClient({this.baseUrl = 'http://127.0.0.1:9090'});
+
+  final String baseUrl;
+
+  /// GET /traffic — 流量统计
+  Future<Map<String, dynamic>> getTraffic() {
+    throw UnimplementedError('ClashApiClient.getTraffic — 11D 实现');
+  }
+
+  /// GET /proxies — 节点列表
+  Future<Map<String, dynamic>> getProxies() {
+    throw UnimplementedError('ClashApiClient.getProxies — 11D 实现');
+  }
+
+  /// PUT /proxies/{group} — 切换出口
+  Future<void> selectProxy(String group, String proxy) {
+    throw UnimplementedError('ClashApiClient.selectProxy — 11D 实现');
+  }
+
+  /// GET /connections — 实时连接
+  Future<Map<String, dynamic>> getConnections() {
+    throw UnimplementedError('ClashApiClient.getConnections — 11D 实现');
+  }
+
+  /// DELETE /connections — 关闭所有连接
+  Future<void> closeAllConnections() {
+    throw UnimplementedError('ClashApiClient.closeAllConnections — 11D 实现');
+  }
+}
+
+// ── 进程管理接口 ─────────────────────────────────────────────────
+
+/// 桌面端内核子进程管理接口。
+///
+/// 使用方式：
+/// ```dart
+/// final kernel = DesktopKernelProcess();
+/// await kernel.spawn('/path/to/config.json');
+/// final traffic = await kernel.clashApiClient.getTraffic();
+/// await kernel.kill();
+/// ```
+abstract class KernelProcess {
+  /// 启动内核子进程。
+  ///
+  /// [configPath] 为 sing-box JSON 配置文件的绝对路径。
+  /// 返回的 [Future] 在进程就绪（REST API 可用）后 complete。
+  Future<void> spawn(String configPath);
+
+  /// 停止内核子进程。
+  ///
+  /// 先发 SIGTERM，[gracePeriod] 内未退出则 SIGKILL。
+  Future<void> kill({
+    Duration gracePeriod = const Duration(seconds: 3),
+  });
+
+  /// 进程是否正在运行。
+  bool get isRunning;
+
+  /// Clash 兼容 REST API 客户端（进程运行时可用）。
+  ClashApiClient get clashApiClient;
+
+  /// 进程标准输出/标准错误日志流（用于调试面板）。
+  Stream<String> get logStream;
+}
+
+// ── 占位实现（防 analyze 报错）────────────────────────────────────
+
+/// 占位实现，抛出 [UnimplementedError]。
+/// 11D 替换为真实子进程实现时删除本类。
+class DesktopKernelProcess implements KernelProcess {
+  @override
+  Future<void> spawn(String configPath) {
+    throw UnimplementedError('DesktopKernelProcess.spawn — 11D 实现');
+  }
+
+  @override
+  Future<void> kill({Duration gracePeriod = const Duration(seconds: 3)}) {
+    throw UnimplementedError('DesktopKernelProcess.kill — 11D 实现');
+  }
+
+  @override
+  bool get isRunning => false;
+
+  @override
+  ClashApiClient get clashApiClient =>
+      throw UnimplementedError('DesktopKernelProcess.clashApiClient — 11D 实现');
+
+  @override
+  Stream<String> get logStream =>
+      throw UnimplementedError('DesktopKernelProcess.logStream — 11D 实现');
+}

client/lib/bridge/vpn_bridge.dart

@@ -0,0 +1,243 @@
+// vpn_bridge.dart — Dart↔原生桥接 API 契约（冻结字段）
+//
+// ═══════════════════════════════════════════════════════════════
+// 通道名称（Channel names）
+// ═══════════════════════════════════════════════════════════════
+//   MethodChannel : pangolin/vpn
+//   EventChannel  : pangolin/vpn/status
+//   EventChannel  : pangolin/vpn/stats
+//
+// ═══════════════════════════════════════════════════════════════
+// MethodChannel 方法签名（Method signatures）—— 不得私改
+// ═══════════════════════════════════════════════════════════════
+//   start(String configJson)         → void
+//   stop()                           → void
+//   getStatus()                      → String ("off"|"connecting"|"on"|"error")
+//   selectOutbound(String tag)       → void
+//   getActiveOutbound()              → String tag
+//   setKillSwitch(bool on)           → void
+//
+// ═══════════════════════════════════════════════════════════════
+// EventChannel 事件 schema —— 不得私改
+// ═══════════════════════════════════════════════════════════════
+//   pangolin/vpn/status → String
+//     值：  "off" | "connecting" | "on" | "error"
+//     来源：内核回调（严禁 UI 乐观显示；start 返回 ≠ on）
+//
+//   pangolin/vpn/stats → Map<String, dynamic>
+//     {
+//       "uploadBytes"    : int,        // 本次隧道累计上传字节
+//       "downloadBytes"  : int,        // 本次隧道累计下载字节
+//       "uploadSpeed"    : double,     // bytes/s 瞬时上行速率
+//       "downloadSpeed"  : double,     // bytes/s 瞬时下行速率
+//       "urltestResults" : [           // urltest 延迟结果列表
+//         { "tag": String, "delayMs": int },
+//         ...
+//       ]
+//     }
+//     周期：约 1 秒一帧（内核驱动，非固定间隔）
+//
+// 最后修订：任务 tsk_iP5-_Ztq5THx（桥接 API 面定稿）
+// ═══════════════════════════════════════════════════════════════
+
+import 'dart:async';
+import 'package:flutter/services.dart';
+
+// ── 状态枚举 ────────────────────────────────────────────────────
+// 与 design/flutter/widgets/connect_button.dart VpnStatus 对齐。
+// error 为桥接层扩展态，仅由内核回调产生，UI 层按需处理。
+enum VpnStatus {
+  off,
+  connecting,
+  on,
+  error;
+
+  /// 从原生侧字符串解析
+  static VpnStatus fromString(String s) => switch (s) {
+        'off' => VpnStatus.off,
+        'connecting' => VpnStatus.connecting,
+        'on' => VpnStatus.on,
+        'error' => VpnStatus.error,
+        _ => VpnStatus.error,
+      };
+
+  /// 序列化为原生侧字符串
+  String toNativeString() => switch (this) {
+        VpnStatus.off => 'off',
+        VpnStatus.connecting => 'connecting',
+        VpnStatus.on => 'on',
+        VpnStatus.error => 'error',
+      };
+}
+
+// ── stats 数据模型 ───────────────────────────────────────────────
+
+class UrltestResult {
+  const UrltestResult({required this.tag, required this.delayMs});
+
+  final String tag;
+  final int delayMs;
+
+  factory UrltestResult.fromMap(Map<String, dynamic> m) => UrltestResult(
+        tag: m['tag'] as String? ?? '',
+        delayMs: (m['delayMs'] as num?)?.toInt() ?? -1,
+      );
+
+  Map<String, dynamic> toMap() => {'tag': tag, 'delayMs': delayMs};
+
+  @override
+  String toString() => 'UrltestResult(tag=$tag, delayMs=$delayMs)';
+}
+
+class VpnStatsEvent {
+  const VpnStatsEvent({
+    required this.uploadBytes,
+    required this.downloadBytes,
+    required this.uploadSpeed,
+    required this.downloadSpeed,
+    required this.urltestResults,
+  });
+
+  final int uploadBytes;
+  final int downloadBytes;
+  final double uploadSpeed;
+  final double downloadSpeed;
+  final List<UrltestResult> urltestResults;
+
+  factory VpnStatsEvent.fromMap(Map<String, dynamic> m) => VpnStatsEvent(
+        uploadBytes: (m['uploadBytes'] as num?)?.toInt() ?? 0,
+        downloadBytes: (m['downloadBytes'] as num?)?.toInt() ?? 0,
+        uploadSpeed: (m['uploadSpeed'] as num?)?.toDouble() ?? 0.0,
+        downloadSpeed: (m['downloadSpeed'] as num?)?.toDouble() ?? 0.0,
+        urltestResults: ((m['urltestResults'] as List?)
+                ?.where((e) => e is Map)
+                .map((e) => UrltestResult.fromMap(
+                      Map<String, dynamic>.from(e as Map),
+                    ))
+                .toList()) ??
+            const [],
+      );
+
+  /// 从平台通道原始 Map（Map<Object?, Object?>）解析，自动转换键类型。
+  static VpnStatsEvent fromNativeMap(Map<Object?, Object?> raw) =>
+      VpnStatsEvent.fromMap(raw.cast<String, dynamic>());
+
+  Map<String, dynamic> toMap() => {
+        'uploadBytes': uploadBytes,
+        'downloadBytes': downloadBytes,
+        'uploadSpeed': uploadSpeed,
+        'downloadSpeed': downloadSpeed,
+        'urltestResults': urltestResults.map((r) => r.toMap()).toList(),
+      };
+
+  @override
+  String toString() =>
+      'VpnStatsEvent(up=${uploadBytes}B, down=${downloadBytes}B, '
+      'upSpeed=${uploadSpeed.toStringAsFixed(0)}B/s, '
+      'downSpeed=${downloadSpeed.toStringAsFixed(0)}B/s, '
+      'urltest=${urltestResults.length}nodes)';
+}
+
+// ── 抽象接口 ─────────────────────────────────────────────────────
+
+/// Dart 侧 VPN 桥接接口。
+/// 实现方：[VpnNativeBridge]（真实原生通道）与 [VpnBridgeMock]（UI 联调）。
+abstract class VpnBridge {
+  // ── MethodChannel 方法 ──
+
+  /// 启动 VPN。[configJson] 为 sing-box 兼容 JSON 配置字符串。
+  /// 返回不代表连接已建立，实际状态由 [statusStream] 驱动。
+  Future<void> start(String configJson);
+
+  /// 停止 VPN。
+  Future<void> stop();
+
+  /// 查询当前状态（一次性拉取，实时监听用 [statusStream]）。
+  Future<VpnStatus> getStatus();
+
+  /// 切换出口节点。[tag] 为 sing-box outbound tag。
+  Future<void> selectOutbound(String tag);
+
+  /// 获取当前激活出口节点 tag。
+  Future<String> getActiveOutbound();
+
+  /// 设置 Kill Switch 开关。
+  Future<void> setKillSwitch({required bool on});
+
+  // ── EventChannel 流 ──
+
+  /// 实时 VPN 状态流（来自内核回调）。
+  Stream<VpnStatus> get statusStream;
+
+  /// 约每秒推一帧统计数据流（来自内核计时器）。
+  Stream<VpnStatsEvent> get statsStream;
+
+  /// 释放资源。
+  void dispose();
+}
+
+// ── 原生实现 ─────────────────────────────────────────────────────
+
+/// 生产实现：使用 Flutter MethodChannel / EventChannel 与原生侧通信。
+class VpnNativeBridge implements VpnBridge {
+  VpnNativeBridge()
+      : _method = const MethodChannel('pangolin/vpn'),
+        _statusRaw = const EventChannel('pangolin/vpn/status'),
+        _statsRaw = const EventChannel('pangolin/vpn/stats');
+
+  // 允许测试注入
+  VpnNativeBridge.withChannels({
+    required MethodChannel method,
+    required EventChannel status,
+    required EventChannel stats,
+  })  : _method = method,
+        _statusRaw = status,
+        _statsRaw = stats;
+
+  final MethodChannel _method;
+  final EventChannel _statusRaw;
+  final EventChannel _statsRaw;
+
+  @override
+  Future<void> start(String configJson) =>
+      _method.invokeMethod<void>('start', configJson);
+
+  @override
+  Future<void> stop() => _method.invokeMethod<void>('stop');
+
+  @override
+  Future<VpnStatus> getStatus() async {
+    final s = await _method.invokeMethod<String>('getStatus') ?? 'off';
+    return VpnStatus.fromString(s);
+  }
+
+  @override
+  Future<void> selectOutbound(String tag) =>
+      _method.invokeMethod<void>('selectOutbound', tag);
+
+  @override
+  Future<String> getActiveOutbound() async =>
+      await _method.invokeMethod<String>('getActiveOutbound') ?? 'auto';
+
+  @override
+  Future<void> setKillSwitch({required bool on}) =>
+      _method.invokeMethod<void>('setKillSwitch', on);
+
+  @override
+  Stream<VpnStatus> get statusStream => _statusRaw
+      .receiveBroadcastStream()
+      .map((e) => VpnStatus.fromString(e?.toString() ?? 'error'));
+
+  @override
+  Stream<VpnStatsEvent> get statsStream => _statsRaw
+      .receiveBroadcastStream()
+      .where((e) => e is Map)
+      .map((e) => VpnStatsEvent.fromNativeMap(
+            Map<Object?, Object?>.from(e as Map),
+          ));
+
+  @override
+  void dispose() {
+    // EventChannel 由 Flutter 引擎管理，无需手动关闭
+  }
+}

client/lib/bridge/vpn_bridge_mock.dart

@@ -0,0 +1,137 @@
+// vpn_bridge_mock.dart — 假内核实现，供 UI 层先行联调
+//
+// 行为：
+//   start()  → 立即 emit connecting，[connectDelay] 后 emit on，启动统计计时器
+//   stop()   → 立即 emit off，停止统计计时器
+//   stats    → on 状态下按 [statsInterval] 周期推假数据帧
+//
+// 用法示例（UI 联调）：
+//   final bridge = VpnBridgeMock();
+//
+// 用法示例（测试）：
+//   final bridge = VpnBridgeMock(
+//     connectDelay:  Duration(milliseconds: 50),
+//     statsInterval: Duration(milliseconds: 50),
+//   );
+
+import 'dart:async';
+import 'dart:math';
+import 'vpn_bridge.dart';
+
+class VpnBridgeMock implements VpnBridge {
+  VpnBridgeMock({
+    this.connectDelay = const Duration(milliseconds: 1500),
+    this.statsInterval = const Duration(seconds: 1),
+  });
+
+  final Duration connectDelay;
+  final Duration statsInterval;
+
+  // 内部状态
+  VpnStatus _status = VpnStatus.off;
+  String _activeOutbound = 'auto';
+  bool _killSwitch = false;
+
+  final _statusCtrl = StreamController<VpnStatus>.broadcast();
+  final _statsCtrl = StreamController<VpnStatsEvent>.broadcast();
+
+  Timer? _connectTimer;
+  Timer? _statsTimer;
+
+  int _tickCount = 0;
+  final _rng = Random();
+
+  // ── helpers ───────────────────────────────────────────────────
+
+  void _emitStatus(VpnStatus s) {
+    _status = s;
+    if (!_statusCtrl.isClosed) _statusCtrl.add(s);
+  }
+
+  void _startStats() {
+    _tickCount = 0;
+    _statsTimer?.cancel();
+    _statsTimer = Timer.periodic(statsInterval, (_) {
+      _tickCount++;
+      if (!_statsCtrl.isClosed) _statsCtrl.add(_fakeTick(_tickCount));
+    });
+  }
+
+  VpnStatsEvent _fakeTick(int t) {
+    // 模拟稳定带宽 + 微抖动
+    final upSpeed = 10240.0 + _rng.nextDouble() * 2048;
+    final downSpeed = 51200.0 + _rng.nextDouble() * 8192;
+    return VpnStatsEvent(
+      uploadBytes: (upSpeed * t * statsInterval.inMilliseconds / 1000).round(),
+      downloadBytes: (downSpeed * t * statsInterval.inMilliseconds / 1000).round(),
+      uploadSpeed: upSpeed,
+      downloadSpeed: downSpeed,
+      urltestResults: const [
+        UrltestResult(tag: 'hk-01', delayMs: 18),
+        UrltestResult(tag: 'jp-01', delayMs: 32),
+        UrltestResult(tag: 'sg-01', delayMs: 54),
+      ],
+    );
+  }
+
+  // ── VpnBridge methods ─────────────────────────────────────────
+
+  @override
+  Future<void> start(String configJson) async {
+    _connectTimer?.cancel();
+    _statsTimer?.cancel();
+    _emitStatus(VpnStatus.connecting);
+    _connectTimer = Timer(connectDelay, () {
+      _emitStatus(VpnStatus.on);
+      _startStats();
+    });
+  }
+
+  @override
+  Future<void> stop() async {
+    _connectTimer?.cancel();
+    _statsTimer?.cancel();
+    _connectTimer = null;
+    _statsTimer = null;
+    _emitStatus(VpnStatus.off);
+  }
+
+  @override
+  Future<VpnStatus> getStatus() async => _status;
+
+  @override
+  Future<void> selectOutbound(String tag) async {
+    _activeOutbound = tag;
+    // 切换出口时模拟短暂重连
+    if (_status == VpnStatus.on) {
+      _statsTimer?.cancel();
+      _emitStatus(VpnStatus.connecting);
+      _connectTimer = Timer(connectDelay ~/ 2, () {
+        _emitStatus(VpnStatus.on);
+        _startStats();
+      });
+    }
+  }
+
+  @override
+  Future<String> getActiveOutbound() async => _activeOutbound;
+
+  @override
+  Future<void> setKillSwitch({required bool on}) async {
+    _killSwitch = on;
+  }
+
+  @override
+  Stream<VpnStatus> get statusStream => _statusCtrl.stream;
+
+  @override
+  Stream<VpnStatsEvent> get statsStream => _statsCtrl.stream;
+
+  @override
+  void dispose() {
+    _connectTimer?.cancel();
+    _statsTimer?.cancel();
+    _statusCtrl.close();
+    _statsCtrl.close();
+  }
+}

client/lib/widgets/connect_button.dart

@@ -1,9 +1,12 @@
 // connect_button.dart — 核心连接键(三态:off / connecting / on)
+// VpnStatus 枚举定义在 lib/bridge/vpn_bridge.dart（含 error 扩展态）
 import 'package:flutter/material.dart';
+import '../bridge/vpn_bridge.dart' show VpnStatus;
 import '../pangolin_theme.dart';
 import 'pangolin_icons.dart';
 
-enum VpnStatus { off, connecting, on }
+// 重导出便于其他 widget 从 connect_button.dart 引入（向后兼容）
+export '../bridge/vpn_bridge.dart' show VpnStatus;
 
 class ConnectButton extends StatefulWidget {
   const ConnectButton({
@@ -47,12 +50,14 @@ class _ConnectButtonState extends State<ConnectButton> with SingleTickerProvider
       VpnStatus.off => c.bgSubtle,
       VpnStatus.connecting => c.accent,
       VpnStatus.on => c.success,
+      VpnStatus.error => c.danger,
     };
     final Color fg = s == VpnStatus.off ? c.accent : PangolinColors.white;
     final IconData icon = switch (s) {
       VpnStatus.off => PangolinIcons.power,
       VpnStatus.connecting => PangolinIcons.loader,
       VpnStatus.on => PangolinIcons.shieldCheck,
+      VpnStatus.error => PangolinIcons.power,
     };
 
     final List<BoxShadow> glow = s == VpnStatus.off

client/lib/widgets/home_shell.dart

@@ -117,6 +117,7 @@ class _ConnectPage extends StatelessWidget {
       VpnStatus.off => zh ? '未连接 · 轻点连接' : 'Tap to connect',
       VpnStatus.connecting => zh ? '连接中…' : 'Connecting…',
       VpnStatus.on => zh ? '已连接 · 网络已加密' : 'Connected · Encrypted',
+      VpnStatus.error => zh ? '连接错误' : 'Connection error',
     };
     return Column(children: [
       _TopBar(zh: zh, trailing: Text(status == VpnStatus.on ? (zh ? '● 在线' : '● Online') : (zh ? '○ 离线' : '○ Offline'),