plan(client/ios): iOS+iPad 支持实施计划(6 阶段/12 任务,TestFlight 里程碑)

A 补 libbox / B Xcode 接线 / C Provider 重写对齐 macOS / D 真机连通+内存双闸 / E iPad 横竖屏适配 / F TestFlight 分发。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-22 19:22:05 +08:00
parent 84912f4dea
commit e11c06225d
1 changed files with 618 additions and 0 deletions
@@ -0,0 +1,618 @@
+# iOS + iPad 支持 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 把 Pangolin Flutter 客户端的 iOS 隧道从「能编译的 M3 PoC 桩」推进到「iPhone/iPad 真机真正连通、扛得住 NE 内存红线、可推 TestFlight」，iPad 共用同一 iOS target 并完成布局+横屏适配。
+
+**Architecture:** iOS PacketTunnel 扩展按 macOS 已验证的 libbox 集成方式重写（`LibboxNewCommandServer` + `LibboxPlatformInterfaceProtocol` + 真 utun fd），删除 PoC 的 socketpair 手工桥接；主 App 侧 `VpnManager` 已基本可用，仅需对齐配置 key。iPad 复用已有 `form_factor.dart`（宽≥600 自动走 `TabletShell`）+ `tablet_shell.dart`，补横竖屏 orientation 与大屏校验。分发走 App Store Connect / TestFlight。
+
+**Tech Stack:** Swift / NetworkExtension / libbox(sing-box v1.13.13 via sagernet gomobile fork) / Flutter(Riverpod) / Xcode / App Store Connect。
+
+## Global Constraints
+
+每个任务的要求都隐含包含本节。值均逐字取自设计稿与代码。
+
+- **sing-box 版本**：`v1.13.13`（与节点对齐，`SINGBOX_VERSION` 默认值）。
+- **TeamID**：`BYL4KQHMTN`。
+- **Bundle ID**：主 App `com.pangolin.pangolinVpn`；扩展 `com.pangolin.pangolinVpn.PacketTunnel`。
+- **App Group（iOS 格式）**：`group.com.pangolin.pangolinVpn`（注意：非 macOS 的 `<TeamID>.` 前缀）。
+- **扩展链接铁律**：`Libbox.xcframework` **只 Link 不 Embed**（静态库）；PacketTunnel target 设 `OTHER_LDFLAGS = ""`（切断 CocoaPods 继承标志，否则会把 `flutter_secure_storage` 链进扩展）；`otool -L` 扩展二进制应**零外部 `@rpath` 依赖**。
+- **libbox 集成铁律**：`startTunnel` 在后台队列启 libbox（防三方死锁）；`startOrReloadService` **传非空** `LibboxOverrideOptions()`（传 nil → SIGSEGV）；`startDefaultInterfaceMonitor` **阻塞到首个 path 更新再返回**（否则 `no available network interface`）。
+- **配置来源**：sing-box 配置由服务端 `BuildClientConfig` 渲染、原样下发，客户端不拼；DNS 劫持首条规则随配置下发（服务端已处理，iOS 无需改）。
+- **红线词**：用户可见文案不得出现 VPN / 翻墙 / 科学上网 等词；用「加速」口径。
+- **内存红线**：iOS NE 进程 ~50MB（旧设备 ~15MB），jetsam 超限杀进程——头号风险。
+- **设计 token 单源**：颜色/间距走 token，禁硬编码 hex；`pangolin_tokens.gen.dart` 勿手改。
+- **平台**：iOS 12+，设备族 `"1,2"`（iPhone+iPad，已设）。
+- **Frameworks 不入 git**：`Libbox.xcframework` 本地构建，加 `.gitignore` 排除。
+
+---
+
+## File Structure
+
+| 文件 | 责任 | 动作 |
+|---|---|---|
+| `client/ios/Frameworks/Libbox.xcframework` | iOS+sim libbox 静态框架 | 构建产物放入（不入 git） |
+| `client/ios/.gitignore` | 排除框架产物 | 追加一行 |
+| `client/ios/Runner.xcodeproj/project.pbxproj` | 扩展链接 Libbox+系统框架、Team、OTHER_LDFLAGS | Xcode 改 |
+| `client/ios/PacketTunnel/PacketTunnelProvider.swift` | NE 扩展：libbox 集成（重写对齐 macOS） | 重写 |
+| `client/ios/Runner/VpnManager.swift` | 主 App 侧隧道控制 | 微调（配置 key 已是 `config`，核对即可） |
+| `client/ios/Runner/Info.plist` | iPad orientation | 改 |
+| `client/test/responsive/form_factor_test.dart` | 断点判定测试 | 新建 |
+| `client/lib/Runner/Info.plist`（导出合规） | `ITSAppUsesNonExemptEncryption` | 改 |
+
+参照（只读，不改）：`client/macos/PacketTunnel/PacketTunnelProvider.swift`（金标准）、`client/lib/core/responsive/form_factor.dart`、`client/lib/shell/tablet_shell.dart`。
+
+---
+
+## Phase A — libbox iOS 框架（解阻塞）
+
+### Task A1: 构建含 iOS 切片的 Libbox.xcframework 并放入 iOS 工程
+
+**Files:**
+- Create: `client/ios/Frameworks/Libbox.xcframework`（构建产物拷入）
+- Modify: `client/ios/.gitignore`（追加排除）
+
+**Interfaces:**
+- Produces: `client/ios/Frameworks/Libbox.xcframework`，含 `ios-arm64`(真机) 与 `ios-arm64_x86_64-simulator`(模拟器) slice，供 Task B1 链接。
+
+- [ ] **Step 1: 构建全 Apple xcframework**
+
+Run（需 macOS + Xcode CLT + Go；耗时数分钟到十几分钟）：
+```bash
+bash /Users/wangjia/code/pangolin/scripts/build-libbox.sh apple
+```
+Expected: 末尾打印 `✅ 产物: /tmp/pangolin-libbox/sing-box/Libbox.xcframework`
+
+- [ ] **Step 2: 验证含 iOS 切片**
+
+Run:
+```bash
+ls -1 /tmp/pangolin-libbox/sing-box/Libbox.xcframework/
+```
+Expected: 列出含 `ios-arm64`、`ios-arm64_x86_64-simulator`、`macos-arm64_x86_64`（可能还有 tvos）等目录。
+
+- [ ] **Step 3: 拷入 iOS 工程**
+
+Run:
+```bash
+rm -rf /Users/wangjia/code/pangolin/client/ios/Frameworks/Libbox.xcframework
+mkdir -p /Users/wangjia/code/pangolin/client/ios/Frameworks
+cp -R /tmp/pangolin-libbox/sing-box/Libbox.xcframework /Users/wangjia/code/pangolin/client/ios/Frameworks/
+```
+（保留 macOS 既有 `client/macos/Frameworks/Libbox.xcframework` 不动，避免扰动已验证的 macOS 构建。）
+
+- [ ] **Step 4: gitignore 排除框架**
+
+向 `client/ios/.gitignore` 追加一行（仿 macOS 的 `client/macos/.gitignore:10`）：
+```
+**/Frameworks/Libbox.xcframework/
+```
+
+- [ ] **Step 5: 验证已忽略**
+
+Run:
+```bash
+cd /Users/wangjia/code/pangolin && git status --porcelain client/ios/Frameworks/
+```
+Expected: 无输出（框架未被 git 跟踪）。
+
+- [ ] **Step 6: Commit**
+
+```bash
+cd /Users/wangjia/code/pangolin
+git add client/ios/.gitignore
+git commit -m "build(client/ios): 引入 iOS libbox 框架 + gitignore 排除产物"
+```
+
+---
+
+## Phase B — Xcode 接线与签名
+
+### Task B1: 把 Libbox + 系统框架链入 PacketTunnel 扩展（Link-only），设 Team 与 OTHER_LDFLAGS
+
+**Files:**
+- Modify: `client/ios/Runner.xcodeproj/project.pbxproj`（经 Xcode GUI 改，避免手改 pbxproj 出错）
+
+**Interfaces:**
+- Consumes: `client/ios/Frameworks/Libbox.xcframework`（Task A1）
+- Produces: 可编译的 PacketTunnel 扩展 target，零外部 `@rpath` 依赖。
+
+照 macOS 扩展 target 的链接清单（`macos/Runner.xcodeproj` 的 PacketTunnel Frameworks build phase：Libbox + NetworkExtension + libresolv + SystemConfiguration），iOS 把 AppKit 去掉。
+
+- [ ] **Step 1: 打开工程**
+
+Run:
+```bash
+open /Users/wangjia/code/pangolin/client/ios/Runner.xcworkspace
+```
+
+- [ ] **Step 2: 给 PacketTunnel target 链接框架（Link-only）**
+
+在 Xcode 选 `PacketTunnel` target → General → **Frameworks and Libraries**，添加并将 Embed 全设为 **Do Not Embed**：
+- `Frameworks/Libbox.xcframework`（Add Other… 选 Task A1 拷入的）
+- `NetworkExtension.framework`
+- `SystemConfiguration.framework`
+- `libresolv.tbd`
+
+- [ ] **Step 3: 设 Build Settings**
+
+`PacketTunnel` target → Build Settings：
+- `Other Linker Flags`（`OTHER_LDFLAGS`）→ 置为**空**（删除任何继承值；防 CocoaPods 标志把 `flutter_secure_storage` 链进扩展）。
+- `Framework Search Paths` 含 `$(PROJECT_DIR)/Frameworks`。
+- `Development Team`（`DEVELOPMENT_TEAM`）→ `BYL4KQHMTN`。
+
+`Runner`（主 App）target → Build Settings：`Development Team` → `BYL4KQHMTN`。
+
+- [ ] **Step 4: 确认 Signing & Capabilities**
+
+`Runner` 与 `PacketTunnel` 两 target 的 Signing & Capabilities 均含：
+- **App Groups** → `group.com.pangolin.pangolinVpn`
+- `PacketTunnel`：**Network Extensions** → Packet Tunnel Provider（entitlements 文件已声明，确认未报红）。
+
+- [ ] **Step 5: 编译验证**
+
+Run:
+```bash
+cd /Users/wangjia/code/pangolin/client && flutter build ios --debug --no-codesign
+```
+Expected: 构建成功（Swift 此时尚未引用 libbox，仅验证链接配置不破坏构建）。
+
+- [ ] **Step 6: 验证扩展零外部 @rpath 依赖**
+
+Run:
+```bash
+otool -L /Users/wangjia/code/pangolin/client/build/ios/iphoneos/Runner.app/PlugIns/PacketTunnel.appex/PacketTunnel
+```
+Expected: 仅 `/usr/lib/*` 与 `/System/Library/Frameworks/*`；**无** `@rpath/...`（尤其无 `flutter_secure_storage`、无 `@rpath/Libbox`——静态库不应出现）。
+
+- [ ] **Step 7: 验证 Team 已写入**
+
+Run:
+```bash
+grep -c "DEVELOPMENT_TEAM = BYL4KQHMTN" /Users/wangjia/code/pangolin/client/ios/Runner.xcodeproj/project.pbxproj
+```
+Expected: ≥ 2（主 App + 扩展）。
+
+- [ ] **Step 8: Commit**
+
+```bash
+cd /Users/wangjia/code/pangolin
+git add client/ios/Runner.xcodeproj/project.pbxproj
+git commit -m "build(client/ios): PacketTunnel 链接 libbox+系统框架(Link-only) + 设 Team/OTHER_LDFLAGS"
+```
+
+---
+
+## Phase C — iOS Provider 重写（对齐 macOS 验证过的 libbox API）
+
+### Task C1: 用 macOS CommandServer+PlatformInterface 方式重写 iOS PacketTunnelProvider
+
+**Files:**
+- Modify（整体重写）: `client/ios/PacketTunnel/PacketTunnelProvider.swift`
+- Reference（只读）: `client/macos/PacketTunnel/PacketTunnelProvider.swift`
+- Keep: `client/ios/PacketTunnel/MemoryMonitor.swift`（复用）
+
+**Interfaces:**
+- Consumes: `LibboxNewCommandServer(_:_:_:)`、`LibboxPlatformInterfaceProtocol`、`LibboxOverrideOptions`、`LibboxSetup`（真实框架 API，与 macOS 一致）；`VpnManager` 经 `options["config"]` 传配置、经 App Group key `lastConfigJson` 缓存。
+- Produces: `class PacketTunnelProvider`、`final class PangolinPlatformInterface`、`final class InterfaceIterator`、`func simpleError(_:)`。
+
+**背景**：现有 iOS 文件用的是**不存在于真实框架的旧 API**（`LibboxNewService` / `LibboxPlatformInterface` / `openTun(_:)->Int32` + socketpair 桥接），链入真实 Libbox 后编不过。本任务用 macOS 金标准结构整体替换，只改三处：App Group 前缀、log subsystem、配置 key；并保留 `MemoryMonitor` 接入与精简 IPC。
+
+- [ ] **Step 1: 以 macOS 文件为基底重写**
+
+把 `client/macos/PacketTunnel/PacketTunnelProvider.swift` 全文作为基底写入 `client/ios/PacketTunnel/PacketTunnelProvider.swift`，并施加以下**精确改动**：
+
+(a) 顶部常量：
+```swift
+// 改这两行（原 macOS 值 → iOS 值）
+private let log = Logger(subsystem: "com.pangolin.pangolinVpn.PacketTunnel", category: "provider")
+// iOS App Group 用 group. 前缀（非 macOS 的 <TeamID>. 前缀）。
+private let appGroup = "group.com.pangolin.pangolinVpn"
+```
+
+(b) 在 `final class PacketTunnelProvider` 顶部加内存监控成员：
+```swift
+final class PacketTunnelProvider: NEPacketTunnelProvider {
+    private var commandServer: LibboxCommandServer?
+    private var platform: PangolinPlatformInterface?
+    private let memoryMonitor = MemoryMonitor()   // ← 新增（iOS 内存红线打点）
+```
+
+(c) `startTunnel` 成功处（`completionHandler(nil)` 之前）启动监控——在 `self.commandServer = server` 之后加：
+```swift
+                self.commandServer = server
+                self.memoryMonitor.start()        // ← 新增
+                log.info("startTunnel: service started")
+                completionHandler(nil)
+```
+
+(d) `stopTunnel` 开头停监控并打峰值——在 `try? commandServer?.closeService()` 之前加：
+```swift
+        log.info("stopTunnel reason=\(reason.rawValue)")
+        memoryMonitor.stop()                                          // ← 新增
+        log.info("memory peak: \(self.memoryMonitor.summaryString(), privacy: .public)")  // ← 新增
+        try? commandServer?.closeService()
+```
+
+(e) `resolveConfig` 的 options key 改为 `config`（匹配 `VpnManager.start`）并补 App Group 缓存回退：
+```swift
+    private func resolveConfig(_ options: [String: NSObject]?) throws -> String {
+        if let inline = options?["config"] as? String, !inline.isEmpty {
+            return inline
+        }
+        // App Group UserDefaults 缓存（VpnManager 写入 key=lastConfigJson，崩溃恢复用）
+        if let shared = UserDefaults(suiteName: appGroup),
+           let cached = shared.string(forKey: "lastConfigJson"), !cached.isEmpty {
+            return cached
+        }
+        guard let base = FileManager.default
+            .containerURL(forSecurityApplicationGroupIdentifier: appGroup) else {
+            throw simpleError("no app group container")
+        }
+        let content = (try? String(contentsOf: base.appendingPathComponent("config.json"),
+                                   encoding: .utf8)) ?? ""
+        guard !content.isEmpty else { throw simpleError("empty sing-box config") }
+        return content
+    }
+```
+
+(f) `handleAppMessage` 替换为支持 `getStatus` / `getMemory` 的 IPC（对齐 `VpnManager.sendProviderMessage`；删 PoC 的 socketpair/selectOutbound 等无对应内核 API 的分支）：
+```swift
+    override func handleAppMessage(_ messageData: Data,
+                                   completionHandler: ((Data?) -> Void)?) {
+        guard let req = try? JSONSerialization.jsonObject(with: messageData) as? [String: Any],
+              let action = req["action"] as? String else { completionHandler?(nil); return }
+        var resp: [String: Any] = [:]
+        switch action {
+        case "getStatus":
+            resp["status"] = (commandServer != nil) ? "on" : "error"
+        case "getMemory":
+            resp["memory"] = memoryMonitor.summaryString()
+            resp["peakRssBytes"] = memoryMonitor.peakResidentBytes
+        default:
+            resp["error"] = "unknown action: \(action)"
+        }
+        completionHandler?((try? JSONSerialization.data(withJSONObject: resp)) ?? nil)
+    }
+```
+
+(g) `PangolinPlatformInterface`、`InterfaceIterator`、`simpleError` 三部分**原样照搬 macOS**（iOS 全部 API 可用：`tunFd()` 的 utun 扫描、`IP_BOUND_IF`/`IPV6_BOUND_IF`、`getifaddrs` 在 iOS 同样有效，与 sing-box-for-apple 一致）。`import` 段照搬 macOS（`Darwin/Foundation/Libbox/Network/NetworkExtension/os`，无 AppKit）。
+
+- [ ] **Step 2: 编译验证（链入真实 libbox）**
+
+Run:
+```bash
+cd /Users/wangjia/code/pangolin/client && flutter build ios --debug --no-codesign
+```
+Expected: 构建成功；不再出现 `LibboxNewService` / `LibboxPlatformInterface` 等旧符号未定义错误。
+
+- [ ] **Step 3: 静态核对铁律**
+
+Run:
+```bash
+grep -nE "DispatchQueue.global|LibboxOverrideOptions\(\)|firstUpdate.wait|options\?\[\"config\"\]" \
+  /Users/wangjia/code/pangolin/client/ios/PacketTunnel/PacketTunnelProvider.swift
+```
+Expected: 四项均命中（后台队列、非空 OverrideOptions、阻塞 interface monitor、config key）。
+
+- [ ] **Step 4: Commit**
+
+```bash
+cd /Users/wangjia/code/pangolin
+git add client/ios/PacketTunnel/PacketTunnelProvider.swift
+git commit -m "feat(client/ios): Provider 对齐 macOS libbox 集成(CommandServer+utun fd)+ 内存监控"
+```
+
+---
+
+## Phase D — 真机连通与内存验收
+
+### Task D1: iPhone 真机连通 + 内存基线
+
+**Files:** 无代码改动（验证任务；如需签名修复改 `project.pbxproj`）
+
+**Interfaces:**
+- Consumes: Task C1 的 Provider；`VpnManager`（已实现 load/save/start/stop）。
+
+- [ ] **Step 1: 真机安装运行**
+
+USB 接入开发者已登记的 iPhone（设备 UDID 已在 App ID 描述文件中）：
+```bash
+cd /Users/wangjia/code/pangolin/client && flutter run --release -d <iphone-device-id>
+```
+Expected: app 在真机启动。
+
+- [ ] **Step 2: 触发连接并看日志**
+
+app 内点连接。同时在 macOS 终端开 device console 过滤扩展日志：
+```bash
+log stream --predicate 'subsystem == "com.pangolin.pangolinVpn.PacketTunnel"' --info
+```
+Expected: 依次出现 `startTunnel` → `startTunnel: service started`；**无** `no available network interface`、无 SIGSEGV 崩溃。
+
+- [ ] **Step 3: 验证真出网**
+
+真机连接态下，Safari 打开一个境外站点（如 example.com 以外的被墙站点）。
+Expected: 能打开（DNS 解析不失败 + 数据走节点）。
+
+- [ ] **Step 4: 读内存峰值**
+
+连接保持 10 分钟后，app 内触发 `getMemory` IPC（或读 device console 的 `memory peak` 行）。
+Expected: `peakRssBytes` < 设备 jetsam 上限（新设备目标 < 50MB；旧设备 < 15MB）；进程未被系统杀。
+
+- [ ] **Step 5: 记录结论**
+
+把内存实测峰值与设备型号记到 `docs/ios-ipad-support-design.html` 的「头号风险」卡片下（追加一行实测数据）。若**超限** → 执行 Task D2；若达标 → 跳过 D2。
+
+- [ ] **Step 6: Commit（如有文档更新）**
+
+```bash
+cd /Users/wangjia/code/pangolin
+git add docs/ios-ipad-support-design.html
+git commit -m "docs(client/ios): 记录 iPhone 真机连通 + NE 内存实测峰值"
+```
+
+### Task D2:（条件触发）内存超限 → 本地 .srs 预取瘦身
+
+**仅当 Task D1 Step 4 内存超限时执行。** 头号风险缓解的第二道闸：避免启动期把远程 `geoip-cn.srs`/`geosite-cn.srs` 下载进 NE 进程内存。
+
+**Files:**
+- Modify: `server/internal/httpapi/clientconfig.go`（rule_set 由 `type:"remote"` 改为本地 `type:"local",path:...`，仅对 iOS 客户端或全平台）
+- Create: `client/ios/Runner/Resources/geoip-cn.srs`、`geosite-cn.srs`（随 app 打包）
+- Modify: `client/ios/Runner/AppDelegate.swift`（启动时把 bundle 内 .srs 拷到 App Group 容器）
+
+**Interfaces:**
+- Consumes: 控制面 `/v1/rules/*.srs`（构建期预取一次）。
+- Produces: App Group 容器内 `geoip-cn.srs`/`geosite-cn.srs` 本地文件；下发配置引用其本地路径。
+
+- [ ] **Step 1: 预取 .srs 打入 app bundle**
+
+Run（从节点拉一次，提交进仓库）：
+```bash
+curl -fsSL http://<节点公网>:8080/v1/rules/geoip-cn.srs   -o /Users/wangjia/code/pangolin/client/ios/Runner/Resources/geoip-cn.srs
+curl -fsSL http://<节点公网>:8080/v1/rules/geosite-cn.srs -o /Users/wangjia/code/pangolin/client/ios/Runner/Resources/geosite-cn.srs
+```
+Expected: 两个 `.srs` 文件落地，非空。在 Xcode 把 `Resources/` 加入 Runner target 的 Copy Bundle Resources。
+
+- [ ] **Step 2: 启动期拷到 App Group 容器**
+
+在 `AppDelegate.swift` 的 `application(_:didFinishLaunchingWithOptions:)` 内，加把 bundle 内 `.srs` 拷到 `group.com.pangolin.pangolinVpn` 容器的逻辑（若不存在再拷）：
+```swift
+let group = "group.com.pangolin.pangolinVpn"
+if let base = FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: group) {
+    for name in ["geoip-cn", "geosite-cn"] {
+        let dst = base.appendingPathComponent("\(name).srs")
+        if !FileManager.default.fileExists(atPath: dst.path),
+           let src = Bundle.main.url(forResource: name, withExtension: "srs") {
+            try? FileManager.default.copyItem(at: src, to: dst)
+        }
+    }
+}
+```
+
+- [ ] **Step 3: 服务端配置引用本地路径**
+
+在 `server/internal/httpapi/clientconfig.go` 的 `split_cn` 分支，把 `geoip-cn`/`geosite-cn` 两条 rule_set 由 `type:"remote"`（带 url/download_detour）改为 `type:"local"` + `path` 指向 App Group 容器内的 `.srs`（路径由客户端启动期已知，作为渲染参数传入或约定固定相对路径）。
+Expected: 下发配置中两条 rule_set 为 `"type":"local"`。
+
+- [ ] **Step 4: Go 测试**
+
+Run:
+```bash
+cd /Users/wangjia/code/pangolin/server && go test ./internal/httpapi/...
+```
+Expected: PASS（含 BuildClientConfig 渲染测试，确认 local 分支正确）。
+
+- [ ] **Step 5: 真机复测内存**
+
+重复 Task D1 Step 1–4。
+Expected: `peakRssBytes` 降到设备 jetsam 上限以下。
+
+- [ ] **Step 6: Commit**
+
+```bash
+cd /Users/wangjia/code/pangolin
+git add server/internal/httpapi/clientconfig.go client/ios/Runner/AppDelegate.swift
+git commit -m "perf(client/ios): 本地 .srs 预取替代远程下载，压低 NE 内存峰值"
+```
+
+---
+
+## Phase E — iPad UI 适配（布局 + 横屏）
+
+### Task E1: form_factor 断点判定测试（锁定 iPad → tablet）
+
+**Files:**
+- Create: `client/test/responsive/form_factor_test.dart`
+- Reference: `client/lib/core/responsive/form_factor.dart`
+
+**Interfaces:**
+- Consumes: `FormFactorContext.formFactor`（已有：非桌面平台宽≥600 → `.tablet`）。
+
+- [ ] **Step 1: 写失败测试**
+
+```dart
+// client/test/responsive/form_factor_test.dart
+import 'package:flutter/widgets.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pangolin_vpn/core/responsive/form_factor.dart';
+
+Future<FormFactor> _ffAt(WidgetTester tester, Size size) async {
+  late FormFactor ff;
+  tester.view.physicalSize = size;
+  tester.view.devicePixelRatio = 1.0;
+  addTearDown(tester.view.reset);
+  await tester.pumpWidget(MediaQuery(
+    data: MediaQueryData.fromView(tester.view),
+    child: Builder(builder: (c) { ff = c.formFactor; return const SizedBox(); }),
+  ));
+  return ff;
+}
+
+void main() {
+  testWidgets('iPad 竖屏(768) → tablet', (t) async {
+    expect(await _ffAt(t, const Size(768, 1024)), FormFactor.tablet);
+  });
+  testWidgets('iPad 横屏(1024) → tablet', (t) async {
+    expect(await _ffAt(t, const Size(1024, 768)), FormFactor.tablet);
+  });
+  testWidgets('iPhone(390) → mobile', (t) async {
+    expect(await _ffAt(t, const Size(390, 844)), FormFactor.mobile);
+  });
+}
+```
+
+- [ ] **Step 2: 跑测试看通过/失败**
+
+Run:
+```bash
+cd /Users/wangjia/code/pangolin/client && flutter test test/responsive/form_factor_test.dart
+```
+Expected: 3 测试全 PASS（现有 `form_factor.dart` 逻辑已满足；本测试锁定行为防回归）。若 iPhone case 因默认平台非 iOS 而判成 tablet，则说明测试环境 `defaultTargetPlatform` 默认 android（非桌面），390<600 仍 → mobile，应 PASS。
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd /Users/wangjia/code/pangolin
+git add client/test/responsive/form_factor_test.dart
+git commit -m "test(client): 锁定 form_factor 断点(iPad→tablet, iPhone→mobile)"
+```
+
+### Task E2: 开 iPad 横竖屏 orientation + 大屏校验
+
+**Files:**
+- Modify: `client/ios/Runner/Info.plist`
+- Reference: `client/lib/shell/tablet_shell.dart`、`design/ui_kits/tablet/`
+
+**Interfaces:**
+- Consumes: `TabletShell`（已实现侧栏+内容区双栏）。
+
+- [ ] **Step 1: 开 iPad 全向**
+
+在 `client/ios/Runner/Info.plist` 设 iPad 支持全部方向（`UISupportedInterfaceOrientations~ipad`）：
+```xml
+<key>UISupportedInterfaceOrientations~ipad</key>
+<array>
+    <string>UIInterfaceOrientationPortrait</string>
+    <string>UIInterfaceOrientationPortraitUpsideDown</string>
+    <string>UIInterfaceOrientationLandscapeLeft</string>
+    <string>UIInterfaceOrientationLandscapeRight</string>
+</array>
+```
+
+- [ ] **Step 2: 模拟器多尺寸目测**
+
+Run（iPad 模拟器跑起来）：
+```bash
+cd /Users/wangjia/code/pangolin/client && flutter run -d "iPad (10th generation)"
+```
+逐屏（connect / nodes / stats / account）竖屏与横屏各看一遍。
+Expected: 走 `TabletShell`（侧栏+双栏内容），无溢出（无黄黑条）、不空旷、不拉伸；对照 `design/ui_kits/tablet/tabapp.jsx` 原型布局一致。
+
+- [ ] **Step 3: analyze 通过**
+
+Run:
+```bash
+cd /Users/wangjia/code/pangolin/client && flutter analyze
+```
+Expected: No issues。
+
+- [ ] **Step 4: Commit**
+
+```bash
+cd /Users/wangjia/code/pangolin
+git add client/ios/Runner/Info.plist client/lib/shell/tablet_shell.dart
+git commit -m "feat(client/ios): 开 iPad 全向 orientation + 平板布局校验"
+```
+
+### Task E3: iPad 真机连通验收
+
+- [ ] **Step 1: iPad 真机跑连接**
+
+Run:
+```bash
+cd /Users/wangjia/code/pangolin/client && flutter run --release -d <ipad-device-id>
+```
+连接 → 验出网（同 Task D1 Step 2–3）；竖横屏切换布局正常。
+Expected: iPad 连通且布局达标；内存峰值同样 < 上限。
+
+---
+
+## Phase F — 分发到 TestFlight
+
+### Task F1:（用户操作）开发者后台注册 — App ID / NE 能力 / App Group / 描述文件
+
+**这是用户在 developer.apple.com / App Store Connect 手点的清单，Claude 无法代点。**
+
+- [ ] **Step 1: 注册 App ID（两个）**
+  - `com.pangolin.pangolinVpn`（主 App）— 勾 **App Groups**、**Network Extensions**。
+  - `com.pangolin.pangolinVpn.PacketTunnel`（扩展）— 勾 **App Groups**、**Network Extensions** → Packet Tunnel Provider。
+
+- [ ] **Step 2: 建 App Group**
+  - `group.com.pangolin.pangolinVpn`，关联上面两个 App ID。
+
+- [ ] **Step 3: 描述文件**
+  - 为两个 App ID 各建 App Store 分发描述文件（或用自动签名）；登记测试设备 UDID（开发阶段）。
+
+- [ ] **Step 4: App Store Connect 建 app 记录**
+  - 新建 app，Bundle ID 选 `com.pangolin.pangolinVpn`，填基本信息。
+
+### Task F2: 导出合规 + Archive + 上传 TestFlight
+
+**Files:**
+- Modify: `client/ios/Runner/Info.plist`（导出合规键）
+
+- [ ] **Step 1: 标注导出合规**
+
+在 `client/ios/Runner/Info.plist` 加（避免每次上传被问加密合规；如使用标准加密走豁免，按实际填）：
+```xml
+<key>ITSAppUsesNonExemptEncryption</key>
+<false/>
+```
+
+- [ ] **Step 2: 递增构建号**
+
+确认 `client/pubspec.yaml` 的 build number（`+N`）已递增（驱动 `FLUTTER_BUILD_NUMBER` → 扩展与主 App 的 `CFBundleVersion`）。
+
+- [ ] **Step 3: Archive**
+
+Run:
+```bash
+cd /Users/wangjia/code/pangolin/client && flutter build ipa --release
+```
+Expected: 产出 `build/ios/ipa/*.ipa`，签名成功。
+
+- [ ] **Step 4: 上传 TestFlight**
+
+Run（或用 Xcode Organizer / Transporter）：
+```bash
+xcrun altool --upload-app -f /Users/wangjia/code/pangolin/client/build/ios/ipa/*.ipa \
+  -t ios --apiKey <KEY_ID> --apiIssuer <ISSUER_ID>
+```
+Expected: 上传成功；App Store Connect → TestFlight 出现构建（处理后可加外部测试者）。
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd /Users/wangjia/code/pangolin
+git add client/ios/Runner/Info.plist client/pubspec.yaml
+git commit -m "release(client/ios): 导出合规标注 + 构建号递增,准备 TestFlight"
+```
+
+---
+
+## 验收标准（Definition of Done）
+
+1. ✅ `Libbox.xcframework` 含 iOS 切片；扩展 `otool -L` 零外部 `@rpath`（A1 Step2 / B1 Step6）。
+2. ✅ iPhone 真机：连接 → sing-box 起来 → 打开境外站点（D1 Step2–3）。
+3. ✅ iPad 真机：连通 + 竖/横屏布局对照原型无拉伸/空旷（E2、E3）。
+4. ✅ `MemoryMonitor` 真机峰值 < 设备 jetsam 上限，10 分钟不被杀（D1 Step4，必要时 D2）。
+5. ✅ 成功 Archive 并上传 TestFlight，外部测试者可装可连（F2）。
+
+---
+
+## Self-Review 记录
+
+- **Spec 覆盖**：设计稿 5 工作线 → Phase A(①libbox) / B+C(②Provider) / C(③App Group IPC，并入 VpnManager 既有实现) / E(④iPad) / F(⑤分发)；头号风险内存闸 → D1+D2 双闸。全覆盖。
+- **占位符**：D2 的 `<节点公网>`、F 的 `<KEY_ID>`/`<device-id>` 为运行期真实值占位（环境相关，不可硬编码），非逻辑占位；其余步骤均含可执行命令与期望输出。
+- **类型一致**：`PangolinPlatformInterface`/`InterfaceIterator`/`simpleError`/`commandServer`/`memoryMonitor` 命名跨任务一致；IPC key `getStatus`/`getMemory` 与 `VpnManager.sendProviderMessage` 一致；配置 key 统一为 `config`。