# CFBrowser Windows/macOS 原生后端实施报告 日期:2026-11-05;交付版本:v0.1.1。源码基线:用户上传的 `cfbrowser-202611051438.zip`,SHA-256 为 `15617ecf0557296e451344643527c86b3faa7b6b0d93069bf10318791e1c7525`。 ## 交付结果 已增加真实 Windows WebView2 与 macOS WKWebView 适配器,独立库/worker 保持 `CGO_ENABLED=0`,使用现有八个 Agent 工具与私有管道协议。Windows/macOS 原生实现处于 experimental:本次已验证构建与平台测试编译,但没有这两个系统的实际运行结果。不能把本交付表述为已完成 Windows/macOS 实机验收。 同时更新完整中文设计、中英文设计/使用/ClusterFlow 集成/验证文档,新增双语原生后端说明、一键实机脚本、macOS bundle 辅助脚本与 Windows/macOS CI 入口。代码注释使用英文。 本次只修改独立 cfbrowser 项目,未修改 ClusterFlow 主应用。接入时复用现有注册适配器并替换 driver、分发对应 worker;不加载到 Wails 自身前端 WebView。 ## 主要实现 | 部分 | 实际变化 | | --- | --- | | Windows 原生 | COM STA、隐藏 HWND、消息循环、Evergreen Runtime Environment/Controller、导航事件、专属临时 profile、关闭清理 | | Windows 隔离求值 | WebView2 原生 COM CDP 通道,主 frame → named isolated world → Runtime.evaluate;不开放调试端口 | | Windows ABI | 锁定 loader/combridge v1.0.22,本地窄 vtable 包装;amd64/arm64 RECT 分开处理,显式 COM 引用生命周期与指针保活 | | macOS 原生 | 进程主线程固定、Cocoa/WebKit 动态调用、隐藏 NSWindow/WKWebView、nonpersistent data store、导航代理与事件循环 | | macOS 隔离求值 | WKContentWorld 加 no-op user script 保持世界;原生 completion block 回传有界 JSON,整数 token 关联 Go 回调 | | 共享 worker | 有界队列、配置与 viewport 校验、16 页面与 32 原生求值配额、取消、EOF/pump 故障、关闭时结束待完成求值及晚到回调保护 | | Native 客户端 | 支持三平台、准确引擎名、Windows 隐藏 console、拒绝 configure=false、启动失败测试 | | 测试入口 | CFBROWSER_TEST_ENGINE=native/cdp/both;原生脚本不会误跑 CDP 后就宣称 Native 通过 | | 分发 | 新增 macOS bundle/Info.plist 辅助打包;vendor 更新,离线构建可用 | 实现文件主要位于 `internal/nativehost/`、`cmd/cfbrowser-worker/{windows,darwin}.go` 和 `driver/native/`。Linux 保留现有 WebKitGTK 实现。 ## 本次验证证据 | 项目 | 结果 | | --- | --- | | Go 1.25.0、CGO=0 完整离线 vendor 单元测试 | 通过 | | 完整 race 测试、Linux go vet | 通过 | | Windows amd64/macOS arm64 原生相关包静态 go vet | 通过 | | linux/windows/darwin × amd64/arm64 构建 | 6 项通过,仅编译 | | Windows/macOS × amd64/arm64 × nativehost/native-client/integration 测试编译 | 12 项通过,仅编译 | | 真实 CDP 集成 | 5 组流程通过,含新增隔离世界测试 | | CDP CLI demo 与管道 demo | 通过 | | Python 合并覆盖率与 bundle 元数据 | 2 项通过 | | 原始基线增量补丁应用与应用后测试 | 见随附 `native-update-patch-apply.txt` | 公共 nativehost 层 Go 单元语句覆盖率为 **100.0%**;Native RPC 客户端为 **84.1%**。当前 Linux 选中的全模块单元覆盖率 **68.3%**,合并当前 CDP 集成与 CLI 运行后 **76.3%**。Windows/macOS 平台源文件被 Linux build tag 排除,不能用上述百分比推断它们已被运行覆盖。此前 82.42% 包含另一源码版本的 GTK 运行,只保存为历史证据。 原始日志移到 `test-results/baseline-v0.1.0/`;本次证据为 `test-results/native-update-*` 和当前 manifest。更详细的测试边界与复现命令见 `docs/VALIDATION.zh-CN.md`。 ## 应用补丁 在解压的原始 `cfbrowser-202611051438.zip` 中,进入包含 go.mod 的 cfbrowser 根目录,保留你自己的改动后执行: ```sh git apply --check /path/to/CFBrowser-Native-Windows-macOS-20261105.patch git apply /path/to/CFBrowser-Native-Windows-macOS-20261105.patch ``` 补丁包含新增 vendor 内容与二进制 patch 记录,使用 Git 原样应用;不要通过会改写换行的文本管道传递。若基线已有其他修改,先检查冲突,不使用强制覆盖或自动反复重放。附带源码 ZIP 已包含全部变更,解压后直接使用,不再应用同一补丁。 ## Windows 实机验收 先安装对应架构的 Evergreen WebView2 Runtime,在 PowerShell 的项目根目录执行: ```powershell .\scripts\test-native.ps1 ``` 或先手动运行最小 demo: ```powershell $env:CGO_ENABLED = "0" go build -buildvcs=false -mod=vendor -o bin/cfbrowser.exe ./cmd/cfbrowser go build -buildvcs=false -mod=vendor -o bin/cfbrowser-worker.exe ./cmd/cfbrowser-worker .\bin\cfbrowser.exe --engine native --worker "$PWD\bin\cfbrowser-worker.exe" --diagnostics demo ``` 成功应包含 `"status":"passed"` 和提取表格。无需传入完整 Edge 路径。demo 使用 Native,截图不支持,因此没有 screenshot 字段是预期行为。`doctor` 的 runtimeVerified=false 也属于设计行为;静态能力报告不能代替 demo。 ## macOS 实机验收 在 macOS 11+ 已登录 GUI 会话中: ```sh sh scripts/test-native.sh ``` 正式打包按 `docs/NATIVE.zh-CN.md` 创建 bundle,直接启动内部可执行文件并接入 stdio;签名、公证和真实安装包需另验。Python 仅供可选打包辅助,库/worker 运行无需 Python、Node 或 Swift。 ## 剩余边界 当前环境为 Linux,Windows/macOS 专有 ABI 测试、WebView 导航、cookie 隔离、隐藏窗口行为与退出清理尚无实机执行证据。Linux WebKitGTK 运行库在本次环境不可用,所以旧 Native 后端未重跑;CDP 与公共层已实际回归。CI 文件已提供,但未远程触发或获取结果。 Native 截图/下载/上传、可信键鼠输入、AX、跨域 frame、代理、持久 profile、用户接管 UI 不在本次实现范围。隐藏窗口仍依赖图形会话。网络策略仍只校验显式顶层导航。尚无 Job Object/进程组强杀或完整宿主异常退出恢复;签名安装包与 Wails UI 生命周期也未在本次验证。 ## Git commit 建议 ```text feat(browser): add cgo-free WebView2 and WKWebView workers - add native UI dispatch and isolated evaluation adapters - handle cancellation, callback lifetimes and pending evaluation cleanup - add ABI tests, native-only integration scripts and bilingual docs ```