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 分支补全
2026-06-13 14:58:38 +08:00
parent 30e73b31c2
commit c84b6ea7da
16 changed files with 1677 additions and 11 deletions
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDisplayName</key>
+	<string>穿山甲 Tunnel</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>PacketTunnel</string>
+	<key>CFBundlePackageType</key>
+	<string>XPC!</string>
+	<key>CFBundleShortVersionString</key>
+	<string>$(FLUTTER_BUILD_NAME)</string>
+	<key>CFBundleVersion</key>
+	<string>$(FLUTTER_BUILD_NUMBER)</string>
+	<key>NSExtension</key>
+	<dict>
+		<key>NSExtensionPointIdentifier</key>
+		<string>com.apple.networkextension.packet-tunnel</string>
+		<key>NSExtensionPrincipalClass</key>
+		<string>$(PRODUCT_MODULE_NAME).PacketTunnelProvider</string>
+	</dict>
+</dict>
+</plist>
@@ -0,0 +1,78 @@
+// PacketTunnelProvider.swift — Packet Tunnel Extension 骨架
+//
+// Target: PacketTunnel (NEPacketTunnelProvider extension)
+// Bundle: com.pangolin.pangolinVpn.PacketTunnel
+//
+// 生命周期占位日志；实际 TUN 隧道建立与 libbox 接线由 11F 完成。
+//
+// 与主 App 通信：
+//   主 App → extension: NETunnelProviderSession.sendProviderMessage(_:responseHandler:)
+//   extension → 主 App: 通过 NEProvider.cancelTunnelWithError 或 NETunnelProviderSession 回调
+//
+// TODO(11F): 在 startTunnel 中初始化 sing-box/libbox TUN 模式内核。
+
+import NetworkExtension
+import os.log
+
+class PacketTunnelProvider: NEPacketTunnelProvider {
+
+    private let log = OSLog(
+        subsystem: "com.pangolin.pangolinVpn.PacketTunnel",
+        category: "VPN"
+    )
+
+    // ── NEPacketTunnelProvider 生命周期 ──────────────────────────
+
+    override func startTunnel(
+        options: [String: NSObject]?,
+        completionHandler: @escaping (Error?) -> Void
+    ) {
+        os_log(
+            "PacketTunnelProvider: startTunnel — options keys: %{public}@",
+            log: log, type: .info,
+            (options?.keys.joined(separator: ", ") ?? "(none)")
+        )
+        // TODO(11F): 解析 options["config"] → 写入临时配置文件
+        //            → 调用 libbox/sing-box TUN 启动 API
+        //            → 配置 packetFlow / setTunnelNetworkSettings
+        completionHandler(nil)
+    }
+
+    override func stopTunnel(
+        with reason: NEProviderStopReason,
+        completionHandler: @escaping () -> Void
+    ) {
+        os_log(
+            "PacketTunnelProvider: stopTunnel — reason=%d",
+            log: log, type: .info,
+            reason.rawValue
+        )
+        // TODO(11F): 停止 sing-box 内核 → 关闭 TUN fd
+        completionHandler()
+    }
+
+    override func handleAppMessage(
+        _ messageData: Data,
+        completionHandler: ((Data?) -> Void)?
+    ) {
+        os_log(
+            "PacketTunnelProvider: handleAppMessage — %d bytes",
+            log: log, type: .debug,
+            messageData.count
+        )
+        // TODO(11F): 解码 messageData（JSON 或 protobuf）→ 路由到内核命令
+        //            如 selectOutbound / getStats 等
+        completionHandler?(nil)
+    }
+
+    override func sleep(completionHandler: @escaping () -> Void) {
+        os_log("PacketTunnelProvider: sleep", log: log, type: .debug)
+        // TODO(11F): 挂起内核流量处理
+        completionHandler()
+    }
+
+    override func wake() {
+        os_log("PacketTunnelProvider: wake", log: log, type: .debug)
+        // TODO(11F): 恢复内核流量处理
+    }
+}
@@ -13,8 +13,26 @@
 		97C146FC1CF9000F007C117D /* Main.storyboard in Resources */ = {isa = PBXBuildFile; fileRef = 97C146FA1CF9000F007C117D /* Main.storyboard */; };
 		97C146FE1CF9000F007C117D /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 97C146FD1CF9000F007C117D /* Assets.xcassets */; };
 		97C147011CF9000F007C117D /* LaunchScreen.storyboard in Resources */ = {isa = PBXBuildFile; fileRef = 97C146FF1CF9000F007C117D /* LaunchScreen.storyboard */; };
+		/* VpnManager.swift in Runner Sources */
+		CAFE000000000001000000AB /* VpnManager.swift in Sources */ = {isa = PBXBuildFile; fileRef = CAFE000000000001000000AA /* VpnManager.swift */; };
+		/* PacketTunnelProvider.swift in PacketTunnel Sources */
+		CAFE000000000002000000AB /* PacketTunnelProvider.swift in Sources */ = {isa = PBXBuildFile; fileRef = CAFE000000000002000000AA /* PacketTunnelProvider.swift */; };
+		/* PacketTunnel Info.plist in PacketTunnel Resources */
+		CAFE000000000003000000AB /* Info.plist in Resources */ = {isa = PBXBuildFile; fileRef = CAFE000000000003000000AA /* Info.plist */; };
+		/* PacketTunnel.appex embedded in Runner */
+		CAFE000000000004000000AB /* PacketTunnel.appex in Embed App Extensions */ = {isa = PBXBuildFile; fileRef = CAFE000000000004000000AA /* PacketTunnel.appex */; settings = {ATTRIBUTES = (RemoveHeadersOnCopy, ); }; };
 /* End PBXBuildFile section */

+/* Begin PBXContainerItemProxy section */
+		CAFE000000000070000000AA /* PBXContainerItemProxy */ = {
+			isa = PBXContainerItemProxy;
+			containerPortal = 97C146E61CF9000F007C117D /* Project object */;
+			proxyType = 1;
+			remoteGlobalIDString = CAFE000000000030000000AA /* PacketTunnel */;
+			remoteInfo = PacketTunnel;
+		};
+/* End PBXContainerItemProxy section */
+
 /* Begin PBXCopyFilesBuildPhase section */
 		9705A1C41CF9048500538489 /* Embed Frameworks */ = {
 			isa = PBXCopyFilesBuildPhase;
@@ -26,6 +44,17 @@
 			name = "Embed Frameworks";
 			runOnlyForDeploymentPostprocessing = 0;
 		};
+		CAFE000000000060000000AA /* Embed App Extensions */ = {
+			isa = PBXCopyFilesBuildPhase;
+			buildActionMask = 2147483647;
+			dstPath = "";
+			dstSubfolderSpec = 13;
+			files = (
+				CAFE000000000004000000AB /* PacketTunnel.appex in Embed App Extensions */,
+			);
+			name = "Embed App Extensions";
+			runOnlyForDeploymentPostprocessing = 0;
+		};
 /* End PBXCopyFilesBuildPhase section */

 /* Begin PBXFileReference section */
@@ -41,6 +70,14 @@
 		97C146FD1CF9000F007C117D /* Assets.xcassets */ = {isa = PBXFileReference; lastKnownFileType = folder.assetcatalog; path = Assets.xcassets; sourceTree = "<group>"; };
 		97C146FF1CF9000F007C117D /* LaunchScreen.storyboard */ = {isa = PBXFileReference; lastKnownFileType = file.storyboard; name = LaunchScreen.storyboard; path = Base.lproj/LaunchScreen.storyboard; sourceTree = "<group>"; };
 		1771E259F7494EBC8BB1F97A /* GeneratedPluginRegistrant.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = GeneratedPluginRegistrant.h; sourceTree = "<group>"; };
+		/* VpnManager.swift (Runner) */
+		CAFE000000000001000000AA /* VpnManager.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = VpnManager.swift; sourceTree = "<group>"; };
+		/* PacketTunnelProvider.swift (PacketTunnel extension) */
+		CAFE000000000002000000AA /* PacketTunnelProvider.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = PacketTunnelProvider.swift; sourceTree = "<group>"; };
+		/* PacketTunnel/Info.plist */
+		CAFE000000000003000000AA /* Info.plist */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.plist.xml; path = Info.plist; sourceTree = "<group>"; };
+		/* PacketTunnel.appex product */
+		CAFE000000000004000000AA /* PacketTunnel.appex */ = {isa = PBXFileReference; explicitFileType = "wrapper.app-extension"; includeInIndex = 0; path = PacketTunnel.appex; sourceTree = BUILT_PRODUCTS_DIR; };
 /* End PBXFileReference section */

 /* Begin PBXFrameworksBuildPhase section */
@@ -51,6 +88,13 @@
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
+		CAFE000000000010000000AC /* Frameworks */ = {
+			isa = PBXFrameworksBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
 /* End PBXFrameworksBuildPhase section */

 /* Begin PBXGroup section */
@@ -70,6 +114,7 @@
 			children = (
 				9740EEB11CF90186004384FC /* Flutter */,
 				97C146F01CF9000F007C117D /* Runner */,
+				CAFE000000000020000000AA /* PacketTunnel */,
 				97C146EF1CF9000F007C117D /* Products */,
 			);
 			sourceTree = "<group>";
@@ -78,6 +123,7 @@
 			isa = PBXGroup;
 			children = (
 				97C146EE1CF9000F007C117D /* Runner.app */,
+				CAFE000000000004000000AA /* PacketTunnel.appex */,
 			);
 			name = Products;
 			sourceTree = "<group>";
@@ -90,12 +136,22 @@
 				97C146FF1CF9000F007C117D /* LaunchScreen.storyboard */,
 				97C146F11CF9000F007C117D /* Info.plist */,
 				74858FAE1ED2DC5600515810 /* AppDelegate.swift */,
+				CAFE000000000001000000AA /* VpnManager.swift */,
 				1498D2311E8E86230040F4C2 /* GeneratedPluginRegistrant.m */,
 				1771E259F7494EBC8BB1F97A /* GeneratedPluginRegistrant.h */,
 			);
 			path = Runner;
 			sourceTree = "<group>";
 		};
+		CAFE000000000020000000AA /* PacketTunnel */ = {
+			isa = PBXGroup;
+			children = (
+				CAFE000000000002000000AA /* PacketTunnelProvider.swift */,
+				CAFE000000000003000000AA /* Info.plist */,
+			);
+			path = PacketTunnel;
+			sourceTree = "<group>";
+		};
 /* End PBXGroup section */

 /* Begin PBXNativeTarget section */
@@ -109,16 +165,35 @@
 				97C146EC1CF9000F007C117D /* Resources */,
 				9705A1C41CF9048500538489 /* Embed Frameworks */,
 				3B06F39B1EFE8EE800ECD283 /* Thin Binary */,
+				CAFE000000000060000000AA /* Embed App Extensions */,
 			);
 			buildRules = (
 			);
 			dependencies = (
+				CAFE000000000070000000AB /* PBXTargetDependency */,
 			);
 			name = Runner;
 			productName = Runner;
 			productReference = 97C146EE1CF9000F007C117D /* Runner.app */;
 			productType = "com.apple.product-type.application";
 		};
+		CAFE000000000030000000AA /* PacketTunnel */ = {
+			isa = PBXNativeTarget;
+			buildConfigurationList = CAFE000000000050000000AA /* Build configuration list for PBXNativeTarget "PacketTunnel" */;
+			buildPhases = (
+				CAFE000000000010000000AA /* Sources */,
+				CAFE000000000010000000AC /* Frameworks */,
+				CAFE000000000010000000AB /* Resources */,
+			);
+			buildRules = (
+			);
+			dependencies = (
+			);
+			name = PacketTunnel;
+			productName = PacketTunnel;
+			productReference = CAFE000000000004000000AA /* PacketTunnel.appex */;
+			productType = "com.apple.product-type.app-extension";
+		};
 /* End PBXNativeTarget section */

 /* Begin PBXProject section */
@@ -132,6 +207,9 @@
 						CreatedOnToolsVersion = 7.3.1;
 						LastSwiftMigration = 0900;
 					};
+					CAFE000000000030000000AA = {
+						CreatedOnToolsVersion = 1510;
+					};
 				};
 			};
 			buildConfigurationList = 97C146E91CF9000F007C117D /* Build configuration list for PBXProject "Runner" */;
@@ -148,6 +226,7 @@
 			projectRoot = "";
 			targets = (
 				97C146ED1CF9000F007C117D /* Runner */,
+				CAFE000000000030000000AA /* PacketTunnel */,
 			);
 		};
 /* End PBXProject section */
@@ -164,6 +243,14 @@
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
+		CAFE000000000010000000AB /* Resources */ = {
+			isa = PBXResourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+				CAFE000000000003000000AB /* Info.plist in Resources */,
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
 /* End PBXResourcesBuildPhase section */

 /* Begin PBXShellScriptBuildPhase section */
@@ -206,12 +293,29 @@
 			buildActionMask = 2147483647;
 			files = (
 				74858FAF1ED2DC5600515810 /* AppDelegate.swift in Sources */,
+				CAFE000000000001000000AB /* VpnManager.swift in Sources */,
 				1498D2321E8E86230040F4C2 /* GeneratedPluginRegistrant.m in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
+		CAFE000000000010000000AA /* Sources */ = {
+			isa = PBXSourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+				CAFE000000000002000000AB /* PacketTunnelProvider.swift in Sources */,
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
 /* End PBXSourcesBuildPhase section */

+/* Begin PBXTargetDependency section */
+		CAFE000000000070000000AB /* PBXTargetDependency */ = {
+			isa = PBXTargetDependency;
+			target = CAFE000000000030000000AA /* PacketTunnel */;
+			targetProxy = CAFE000000000070000000AA /* PBXContainerItemProxy */;
+		};
+/* End PBXTargetDependency section */
+
 /* Begin XCBuildConfiguration section */
 		249021D3217E4FDB00AE95B9 /* Profile */ = {
 			isa = XCBuildConfiguration;
@@ -435,6 +539,75 @@
 			};
 			name = Release;
 		};
+		/* PacketTunnel build configurations */
+		CAFE000000000040000000AA /* Debug */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				CLANG_ENABLE_MODULES = YES;
+				CODE_SIGN_IDENTITY = "iPhone Developer";
+				CURRENT_PROJECT_VERSION = "$(FLUTTER_BUILD_NUMBER)";
+				INFOPLIST_FILE = PacketTunnel/Info.plist;
+				IPHONEOS_DEPLOYMENT_TARGET = 12.0;
+				LD_RUNPATH_SEARCH_PATHS = (
+					"$(inherited)",
+					"@executable_path/Frameworks",
+					"@executable_path/../../Frameworks",
+				);
+				PRODUCT_BUNDLE_IDENTIFIER = "com.pangolin.pangolinVpn.PacketTunnel";
+				PRODUCT_NAME = PacketTunnel;
+				SDKROOT = iphoneos;
+				SKIP_INSTALL = YES;
+				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
+				SWIFT_VERSION = 5.0;
+				TARGETED_DEVICE_FAMILY = "1,2";
+			};
+			name = Debug;
+		};
+		CAFE000000000040000000AB /* Release */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				CLANG_ENABLE_MODULES = YES;
+				CODE_SIGN_IDENTITY = "iPhone Developer";
+				CURRENT_PROJECT_VERSION = "$(FLUTTER_BUILD_NUMBER)";
+				INFOPLIST_FILE = PacketTunnel/Info.plist;
+				IPHONEOS_DEPLOYMENT_TARGET = 12.0;
+				LD_RUNPATH_SEARCH_PATHS = (
+					"$(inherited)",
+					"@executable_path/Frameworks",
+					"@executable_path/../../Frameworks",
+				);
+				PRODUCT_BUNDLE_IDENTIFIER = "com.pangolin.pangolinVpn.PacketTunnel";
+				PRODUCT_NAME = PacketTunnel;
+				SDKROOT = iphoneos;
+				SKIP_INSTALL = YES;
+				SWIFT_OPTIMIZATION_LEVEL = "-Owholemodule";
+				SWIFT_VERSION = 5.0;
+				TARGETED_DEVICE_FAMILY = "1,2";
+			};
+			name = Release;
+		};
+		CAFE000000000040000000AC /* Profile */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				CLANG_ENABLE_MODULES = YES;
+				CODE_SIGN_IDENTITY = "iPhone Developer";
+				CURRENT_PROJECT_VERSION = "$(FLUTTER_BUILD_NUMBER)";
+				INFOPLIST_FILE = PacketTunnel/Info.plist;
+				IPHONEOS_DEPLOYMENT_TARGET = 12.0;
+				LD_RUNPATH_SEARCH_PATHS = (
+					"$(inherited)",
+					"@executable_path/Frameworks",
+					"@executable_path/../../Frameworks",
+				);
+				PRODUCT_BUNDLE_IDENTIFIER = "com.pangolin.pangolinVpn.PacketTunnel";
+				PRODUCT_NAME = PacketTunnel;
+				SDKROOT = iphoneos;
+				SKIP_INSTALL = YES;
+				SWIFT_VERSION = 5.0;
+				TARGETED_DEVICE_FAMILY = "1,2";
+			};
+			name = Profile;
+		};
 /* End XCBuildConfiguration section */

 /* Begin XCConfigurationList section */
@@ -458,6 +631,16 @@
 			defaultConfigurationIsVisible = 0;
 			defaultConfigurationName = Release;
 		};
+		CAFE000000000050000000AA /* Build configuration list for PBXNativeTarget "PacketTunnel" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				CAFE000000000040000000AA /* Debug */,
+				CAFE000000000040000000AB /* Release */,
+				CAFE000000000040000000AC /* Profile */,
+			);
+			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Release;
+		};
 /* End XCConfigurationList section */
 	};
 	rootObject = 97C146E61CF9000F007C117D /* Project object */;
@@ -1,13 +1,98 @@
+// AppDelegate.swift — Flutter ↔ 原生通道注册
+//
+// 通道契约（见 lib/bridge/vpn_bridge.dart 头部注释）：
+//   MethodChannel  : pangolin/vpn
+//   EventChannel   : pangolin/vpn/status  → VpnStatusStreamHandler
+//   EventChannel   : pangolin/vpn/stats   → VpnStatsStreamHandler
+//
+// VpnManager.shared 持有 NETunnelProviderManager 与 NEVPNStatus 订阅。
+
 import UIKit
 import Flutter
+import NetworkExtension

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
-  override func application(
-    _ application: UIApplication,
-    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
-  ) -> Bool {
-    GeneratedPluginRegistrant.register(with: self)
-    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
-  }
+
+    override func application(
+        _ application: UIApplication,
+        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
+    ) -> Bool {
+        GeneratedPluginRegistrant.register(with: self)
+
+        guard let controller = window?.rootViewController as? FlutterViewController else {
+            return super.application(application, didFinishLaunchingWithOptions: launchOptions)
+        }
+        let messenger = controller.binaryMessenger
+
+        // ── MethodChannel ────────────────────────────────────────
+        let vpnChannel = FlutterMethodChannel(name: "pangolin/vpn", binaryMessenger: messenger)
+        vpnChannel.setMethodCallHandler { [weak self] call, result in
+            self?.handleVpnMethod(call: call, result: result)
+        }
+
+        // ── EventChannel: status ─────────────────────────────────
+        FlutterEventChannel(name: "pangolin/vpn/status", binaryMessenger: messenger)
+            .setStreamHandler(VpnStatusStreamHandler.shared)
+
+        // ── EventChannel: stats ──────────────────────────────────
+        FlutterEventChannel(name: "pangolin/vpn/stats", binaryMessenger: messenger)
+            .setStreamHandler(VpnStatsStreamHandler.shared)
+
+        // 预加载 VPN 偏好设置（首次为空，静默失败）
+        VpnManager.shared.loadFromPreferences { error in
+            if let error = error {
+                NSLog("VpnManager: loadFromPreferences error: %@", error.localizedDescription)
+            }
+        }
+
+        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
+    }
+
+    // ── MethodChannel handler ─────────────────────────────────────
+
+    private func handleVpnMethod(call: FlutterMethodCall, result: @escaping FlutterResult) {
+        switch call.method {
+
+        case "start":
+            let configJson = call.arguments as? String ?? "{}"
+            VpnManager.shared.start(configJson: configJson) { error in
+                if let error = error {
+                    result(FlutterError(
+                        code: "START_FAILED",
+                        message: error.localizedDescription,
+                        details: nil
+                    ))
+                } else {
+                    result(nil)
+                }
+            }
+
+        case "stop":
+            VpnManager.shared.stop()
+            result(nil)
+
+        case "getStatus":
+            result(VpnManager.shared.statusString)
+
+        case "selectOutbound":
+            let tag = call.arguments as? String ?? "auto"
+            NSLog("VPN: selectOutbound tag=%@", tag)
+            // TODO(11F): sendProviderMessage → PacketTunnelProvider outbound selector
+            result(nil)
+
+        case "getActiveOutbound":
+            // TODO(11F): query from PacketTunnelProvider via sendProviderMessage
+            result("auto")
+
+        case "setKillSwitch":
+            let on = call.arguments as? Bool ?? false
+            NSLog("VPN: setKillSwitch on=%d", on ? 1 : 0)
+            // TODO(11F): 通过 include/excludeRoutes 实现 Kill Switch
+            result(nil)
+
+        default:
+            result(FlutterMethodNotImplemented)
+        }
+    }
 }
@@ -47,5 +47,8 @@
 	<true/>
 	<key>UIApplicationSupportsIndirectInputEvents</key>
 	<true/>
+	<!-- VPN 使用说明（App Store 审核必填） -->
+	<key>NSVPNUsageDescription</key>
+	<string>穿山甲使用 VPN 为您的网络连接提供加密保护。</string>
 </dict>
 </plist>
@@ -0,0 +1,187 @@
+// VpnManager.swift — 主 App 侧 NETunnelProviderManager 封装
+//
+// 职责：
+//   1. loadAllFromPreferences / saveToPreferences — 首次安装时建立 VPN 配置条目
+//   2. start / stop — 通过 NETunnelProviderSession 驱动 PacketTunnel extension
+//   3. sendProviderMessage — 透传 IPC 消息到 PacketTunnelProvider.handleAppMessage
+//
+// AppDelegate 持有本类单例，在 MethodChannel handler 中调用其方法。
+//
+// TODO(11F): 实现 start/stop 前的证书/权限检查；订阅 NEVPNStatus 通知并
+//            通过 VpnStatusStreamHandler.shared.eventSink 推送到 Dart 侧。
+
+import Foundation
+import NetworkExtension
+
+// ── 流处理器（Flutter EventChannel stream handlers）───────────────
+
+/// status 流：推送 "off" / "connecting" / "on" / "error" 字符串
+class VpnStatusStreamHandler: NSObject, FlutterStreamHandler {
+    static let shared = VpnStatusStreamHandler()
+    private(set) var eventSink: FlutterEventSink?
+
+    func onListen(withArguments arguments: Any?, eventSink events: @escaping FlutterEventSink) -> FlutterError? {
+        eventSink = events
+        return nil
+    }
+
+    func onCancel(withArguments arguments: Any?) -> FlutterError? {
+        eventSink = nil
+        return nil
+    }
+
+    func push(_ status: String) {
+        DispatchQueue.main.async { self.eventSink?(status) }
+    }
+}
+
+/// stats 流：推送 [String: Any] 字典，字段同 vpn_bridge.dart VpnStatsEvent schema
+class VpnStatsStreamHandler: NSObject, FlutterStreamHandler {
+    static let shared = VpnStatsStreamHandler()
+    private(set) var eventSink: FlutterEventSink?
+
+    func onListen(withArguments arguments: Any?, eventSink events: @escaping FlutterEventSink) -> FlutterError? {
+        eventSink = events
+        return nil
+    }
+
+    func onCancel(withArguments arguments: Any?) -> FlutterError? {
+        eventSink = nil
+        return nil
+    }
+
+    func push(_ stats: [String: Any]) {
+        DispatchQueue.main.async { self.eventSink?(stats) }
+    }
+}
+
+// ── VPN 管理器 ────────────────────────────────────────────────────
+
+class VpnManager: NSObject {
+
+    static let shared = VpnManager()
+
+    private var tunnelManager: NETunnelProviderManager?
+
+    // Bundle ID 与 PacketTunnel target PRODUCT_BUNDLE_IDENTIFIER 保持同步
+    private let extensionBundleId = "com.pangolin.pangolinVpn.PacketTunnel"
+
+    private var statusObserver: NSObjectProtocol?
+
+    private override init() {
+        super.init()
+        subscribeToVpnStatus()
+    }
+
+    // ── 偏好设置加载与保存 ─────────────────────────────────────
+
+    /// 从系统偏好加载已存在的 VPN 配置（首次为空列表）。
+    /// 必须在调用 start() 前完成。
+    func loadFromPreferences(completion: @escaping (Error?) -> Void) {
+        NETunnelProviderManager.loadAllFromPreferences { [weak self] managers, error in
+            guard let self = self else { return }
+            if let error = error {
+                completion(error)
+                return
+            }
+            self.tunnelManager = managers?.first(where: {
+                ($0.protocolConfiguration as? NETunnelProviderProtocol)?
+                    .providerBundleIdentifier == self.extensionBundleId
+            }) ?? NETunnelProviderManager()
+            completion(nil)
+        }
+    }
+
+    /// 创建或更新 VPN 配置条目（首次安装时调用一次）。
+    func saveConfiguration(serverAddress: String = "pangolin", completion: @escaping (Error?) -> Void) {
+        let manager = tunnelManager ?? NETunnelProviderManager()
+        let proto = NETunnelProviderProtocol()
+        proto.providerBundleIdentifier = extensionBundleId
+        proto.serverAddress = serverAddress
+        manager.protocolConfiguration = proto
+        manager.localizedDescription = "穿山甲 Pangolin VPN"
+        manager.isEnabled = true
+        manager.saveToPreferences { [weak self] error in
+            if error == nil { self?.tunnelManager = manager }
+            completion(error)
+        }
+    }
+
+    // ── 隧道控制 ──────────────────────────────────────────────
+
+    /// 启动 VPN 隧道（通过 NETunnelProviderSession）。
+    /// [configJson]: sing-box 配置 JSON，作为 options 传入 PacketTunnelProvider.startTunnel。
+    func start(configJson: String, completion: @escaping (Error?) -> Void) {
+        guard let manager = tunnelManager else {
+            completion(makeError("VpnManager: tunnelManager not loaded. Call loadFromPreferences first."))
+            return
+        }
+        do {
+            let options: [String: NSObject] = ["config": configJson as NSString]
+            try manager.connection.startVPNTunnel(options: options)
+            completion(nil)
+        } catch {
+            completion(error)
+        }
+    }
+
+    /// 停止 VPN 隧道。
+    func stop() {
+        tunnelManager?.connection.stopVPNTunnel()
+    }
+
+    /// 当前连接状态字符串（供 getStatus MethodChannel 方法使用）。
+    var statusString: String {
+        switch tunnelManager?.connection.status ?? .invalid {
+        case .invalid, .disconnected:  return "off"
+        case .connecting:              return "connecting"
+        case .connected:               return "on"
+        case .disconnecting:           return "connecting"
+        case .reasserting:             return "connecting"
+        @unknown default:              return "error"
+        }
+    }
+
+    // ── IPC 消息通道 ──────────────────────────────────────────
+
+    /// 向 PacketTunnelProvider.handleAppMessage 发送消息。
+    func sendProviderMessage(_ data: Data, responseHandler: ((Data?, Error?) -> Void)?) {
+        guard let session = tunnelManager?.connection as? NETunnelProviderSession else {
+            responseHandler?(nil, makeError("VpnManager: no active NETunnelProviderSession"))
+            return
+        }
+        do {
+            try session.sendProviderMessage(data) { responseData in
+                responseHandler?(responseData, nil)
+            }
+        } catch {
+            responseHandler?(nil, error)
+        }
+    }
+
+    // ── NEVPNStatus 订阅 ──────────────────────────────────────
+
+    private func subscribeToVpnStatus() {
+        statusObserver = NotificationCenter.default.addObserver(
+            forName: NSNotification.Name.NEVPNStatusDidChange,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            guard let self = self else { return }
+            let s = self.statusString
+            VpnStatusStreamHandler.shared.push(s)
+        }
+    }
+
+    deinit {
+        if let obs = statusObserver {
+            NotificationCenter.default.removeObserver(obs)
+        }
+    }
+
+    // ── 工具 ─────────────────────────────────────────────────
+
+    private func makeError(_ message: String) -> NSError {
+        NSError(domain: "VpnManager", code: -1, userInfo: [NSLocalizedDescriptionKey: message])
+    }
+}