原生数据面 macOS 冒烟通过（P0 闸）+ 修 stasel WebRTC macOS 切片缺头

- P0 闸达成：新增 macOS 独立单测 target CommilitiaDropMacTests（把 LibWebRtcEngine.swift 直接编入测试 bundle，无宿主 app、同模块无需 @testable），跑与 iOS 同一份环回端到端测试——两个引擎同进程交叉连，20MB 伪随机源逐字节比对。macOS 上线协议（offer/answer/ICE + 分片 / 背压 / ack / finalize）在 libwebrtc 闭环，证实原生数据面在 Mac 可用（≈3s 通过）。是 Mac 复用 iOS 引擎的技术前提
- 修 stasel/WebRTC 149.0.0 原生 macOS 切片缺头：macos-x86_64_arm64 随包只带 umbrella WebRTC.h、缺全部 80+ 子头（ios / maccatalyst / simulator 三切片各 93 头齐全），umbrella #import 的子头找不到致 import WebRTC 在原生 macOS 编不过；切片二进制本身有效（arm64+x86_64 dylib）。scripts/patch-macos-webrtc-headers.sh 从同包 ios-arm64 切片补齐（子头为平台守卫 ObjC 声明、跨切片同构；排除 3 个 UIKit 绑定视图头 + 从 umbrella 去掉本包缺失的 RTCMTLNSVideoView.h）。幂等，须 SPM resolve 之后、build 之前跑
- LibWebRtcEngineTests.swift 导入条件化：仅 #if os(iOS) 时 @testable import CommilitiaDrop（macOS 侧引擎编在同模块、无需 import），iOS 与 macOS 共用同一份测试文件验证同构闭环
- Justfile：mac-prep（xcodegen + -resolvePackageDependencies + 补头脚本）→ mac-build / mac-test 均依赖之；build / test 加 -disableAutomaticPackageResolution 防 build 期再解析冲掉补丁
- 验证：just mac-test 从残缺态复现全绿——resolve + 补头（1→90）+ 编译 + 环回测试通过

Justfile

@@ -98,12 +98,24 @@ ios-sim-build:
     cd ios/CDrop && xcodegen generate
     cd ios/CDrop && xcodebuild -project CommilitiaDrop.xcodeproj -scheme CommilitiaDrop -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' -derivedDataPath build/DD build
 
-# macOS 原生客户端本地编译验证（ad-hoc 签名，无需 Apple 账号）：xcodegen + xcodebuild -sdk macosx。
-# 当前为脚手架（MacApp/ 导航骨架 + 菜单栏占位）；引擎 / 复用视图 / 桌面功能随后续阶段并入。
-# 产物 build/DD-mac/Build/Products/Debug/CommilitiaDropMac.app（用于本地打开自测）。
-mac-build:
+# 内部：生成工程 + 解析 SPM 依赖 + 补齐 macOS WebRTC 头。stasel/WebRTC 149 的原生 macOS 切片随包
+# 只带 umbrella、缺全部子头（`import WebRTC` 编不过；二进制有效），须从 ios 切片补齐，见
+# scripts/patch-macos-webrtc-headers.sh。mac-build / mac-test 共用；须 resolve 之后 build 之前跑。
+mac-prep:
     cd ios/CDrop && xcodegen generate
-    cd ios/CDrop && xcodebuild -project CommilitiaDrop.xcodeproj -scheme CommilitiaDropMac -sdk macosx -destination 'platform=macOS' -derivedDataPath build/DD-mac build
+    cd ios/CDrop && xcodebuild -project CommilitiaDrop.xcodeproj -scheme CommilitiaDropMac -sdk macosx -derivedDataPath build/DD-mac -resolvePackageDependencies
+    bash ios/CDrop/scripts/patch-macos-webrtc-headers.sh ios/CDrop/build/DD-mac
+
+# macOS 原生客户端本地编译（ad-hoc 签名，无需 Apple 账号）。当前为脚手架（MacApp/ 导航骨架 +
+# 菜单栏占位）；引擎 / 复用视图 / 桌面功能随后续阶段并入。产物 build/DD-mac/Build/Products/Debug/
+# CommilitiaDropMac.app（本地打开自测）。
+mac-build: mac-prep
+    cd ios/CDrop && xcodebuild -project CommilitiaDrop.xcodeproj -scheme CommilitiaDropMac -sdk macosx -destination 'platform=macOS' -derivedDataPath build/DD-mac -disableAutomaticPackageResolution build
+
+# 原生数据面 macOS 冒烟（P0 闸）：跑 CommilitiaDropMacTests 环回端到端测试——两个 LibWebRtcEngine
+# 同进程交叉连，20MB 逐字节验证 libwebrtc macOS 切片上线协议闭环。证实原生数据面在 Mac 可用。
+mac-test: mac-prep
+    cd ios/CDrop && xcodebuild test -project CommilitiaDrop.xcodeproj -scheme CommilitiaDropMac -sdk macosx -destination 'platform=macOS' -derivedDataPath build/DD-mac -disableAutomaticPackageResolution
 
 # 真机构建 + 装机（自动 provisioning，经 ASC API Key）。前置：付费 ADP；App ID 的 App Groups /
 # Push 能力（门户建好或自动建）；根目录 gitignore 的 .env 配齐：CDROP_TEAM_ID / CDROP_ASC_KEY_PATH

ios/CDrop/Tests/LibWebRtcEngineTests.swift

@@ -1,5 +1,10 @@
 import XCTest
+// iOS：测试宿主为主 app，经 @testable import 取引擎内部类型（LibWebRtcEngine 编在 app 里）。
+// macOS：CommilitiaDropMacTests 把 LibWebRtcEngine.swift 直接编入测试 bundle（同模块，无需 import）。
+// 二者共用本文件，验证同一套线协议在 libwebrtc 的 iOS 与 macOS 切片上同构闭环。故仅 iOS 需此导入。
+#if os(iOS)
 @testable import CommilitiaDrop
+#endif
 
 // LibWebRtcEngine 环回端到端测试：两个引擎在同进程内交叉连，跑完整线协议
 // （offer/answer/ICE + meta/分片/done + ack + 收尾），验证收到的文件字节与源逐字节相等。

ios/CDrop/project.yml

@@ -199,6 +199,24 @@ targets:
         # App Group entitlement（Support/macOS/AppMac.entitlements）在 macOS 属受限能力，即便
         # ad-hoc 签名也须 provisioning profile；脚手架阶段（本地免账号编译 / 自测）暂不挂，待桌面
         # 剪贴板 / 小组件共享落地 + Developer ID 签名（Phase 6）再引用该文件。见 AppMac.entitlements。
+  # 原生数据面 macOS 冒烟（P0 闸）：把 LibWebRtcEngine.swift 直接编入独立测试 bundle（无宿主 app，
+  # 同模块无需 @testable import），跑与 iOS 同一份环回端到端测试——两个引擎同进程交叉连，验证
+  # libwebrtc 的 macOS 切片上线协议（offer/answer/ICE + 分片 / 背压 / ack / finalize）逐字节闭环。
+  # 证实原生数据面在 Mac 可用，是 Mac 复用 iOS 引擎的技术前提。
+  CommilitiaDropMacTests:
+    type: bundle.unit-test
+    platform: macOS
+    deploymentTarget: "26.0"
+    sources:
+      - path: Tests
+      - path: Sources/Engine/LibWebRtcEngine.swift
+    dependencies:
+      - package: WebRTC
+    settings:
+      base:
+        PRODUCT_BUNDLE_IDENTIFIER: net.commilitia.Commilitia-Drop.mac.tests
+        ARCHS: arm64
+        GENERATE_INFOPLIST_FILE: "YES"
 schemes:
   CommilitiaDrop:
     build:
@@ -214,6 +232,10 @@ schemes:
     build:
       targets:
         CommilitiaDropMac: all
+    test:
+      targets:
+        - CommilitiaDropMacTests
+      gatherCoverageData: false
     run:
       config: Debug
     archive:

ios/CDrop/scripts/patch-macos-webrtc-headers.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# 补齐 stasel/WebRTC 原生 macOS 切片缺失的头文件。
+#
+# 背景：stasel/WebRTC 149.0.0 的 macos-x86_64_arm64 切片随包只带 umbrella WebRTC.h，缺全部 80+ 子头
+# （ios-arm64 / maccatalyst / simulator 三切片各 93 头齐全）——umbrella `#import <WebRTC/…>` 的子头
+# 找不到，`import WebRTC` 在原生 macOS target 无法编译。切片二进制本身有效（arm64+x86_64 dylib，
+# 环回 DataChannel 20MB 逐字节端到端实测通过）。
+#
+# 修法：从同包 ios-arm64 切片补齐 macOS 切片的头——这些子头是平台守卫（#if TARGET_OS_IPHONE / #else）
+# 的 ObjC 声明，跨切片同构，可直接复用。排除 3 个 UIKit 绑定视图头（RTCCameraPreviewView /
+# RTCEAGLVideoView / RTCMTLVideoView，macOS umbrella 本就不引用它们），并从 macOS umbrella 去掉本包
+# 缺失且无处可取的 RTCMTLNSVideoView.h（Metal NSView 视图，数据面不用）。
+#
+# 幂等：已补齐（macOS 头数 > 1）则跳过。SPM 每次 re-resolve 会重置切片为原始（残缺）状态，故须在
+# resolve 之后、build 之前跑（Justfile 的 mac-prep 已 chain）。
+set -euo pipefail
+
+DD="${1:?用法: patch-macos-webrtc-headers.sh <derivedDataPath>}"
+
+XCF="$(find "$DD/SourcePackages/artifacts" -type d -name 'WebRTC.xcframework' 2>/dev/null | head -1)"
+[ -n "$XCF" ] || { echo "未找到 WebRTC.xcframework（先跑 xcodebuild -resolvePackageDependencies）"; exit 1; }
+
+IOSH="$XCF/ios-arm64/WebRTC.framework/Headers"
+MACH="$XCF/macos-x86_64_arm64/WebRTC.framework/Versions/A/Headers"
+[ -d "$IOSH" ] || { echo "未找到 ios-arm64 切片头：$IOSH"; exit 1; }
+[ -d "$MACH" ] || { echo "未找到 macos 切片头：$MACH"; exit 1; }
+
+if [ "$(ls -1 "$MACH" | wc -l | tr -d ' ')" -gt 1 ]; then
+    echo "macOS WebRTC 头已补齐（$(ls -1 "$MACH" | wc -l | tr -d ' ') 个），跳过。"
+    exit 0
+fi
+
+for h in "$IOSH"/*.h; do
+    b="$(basename "$h")"
+    case "$b" in
+        WebRTC.h | RTCCameraPreviewView.h | RTCEAGLVideoView.h | RTCMTLVideoView.h) continue ;;
+    esac
+    cp "$h" "$MACH/$b"
+done
+
+grep -v 'RTCMTLNSVideoView.h' "$MACH/WebRTC.h" > "$MACH/WebRTC.h.tmp" && mv "$MACH/WebRTC.h.tmp" "$MACH/WebRTC.h"
+
+echo "已补齐 macOS WebRTC 头：$(ls -1 "$MACH" | wc -l | tr -d ' ') 个。"