# Windows 桌面端（全局代理）

Windows 版与 macOS 桌面同路线：Flutter 应用 + `sing-box.exe` 子进程 + **wintun** TUN
接管整机流量（全局代理）。提权方式：应用 manifest 设了 `requireAdministrator`，
启动时 UAC 提权，`sing-box.exe` 子进程继承管理员权以创建 TUN 适配器。

> 状态：代码就绪，**未在真 Windows 机器上构建/验证过**（开发在 macOS）。以下为
> 在 Windows 上首次构建运行的步骤。

## 前置

- Windows 10/11，已装 Flutter（含 Windows 桌面支持）、Visual Studio（C++ 桌面负载）。
- 拉取内核二进制（在仓库根，Git Bash / WSL 下跑；脚本会下载 sing-box.exe + wintun.dll
  并校验 SHA256）：

  ```bash
  app/kernel/fetch-desktop-bin.sh windows amd64
  # 产物：app/kernel/dist/desktop/windows-amd64/{sing-box.exe, wintun.dll}
  ```

## 开发运行（flutter run）

从仓库内直接跑时，`kernel_process.dart` 的 `_resolveBinaryPath` 会从可执行目录向上
查找 `app/kernel/dist/desktop/windows-amd64/sing-box.exe`，无需手动放置：

```powershell
# 必须用「管理员」终端（TUN 需要管理员权）
cd client
flutter run -d windows --dart-define=PANGOLIN_API_URL=http://<后端IP>:8080
```

也可用环境变量显式指定二进制：
`set PANGOLIN_SINGBOX_BIN=C:\path\to\sing-box.exe`（同目录须有 `wintun.dll`）。

## 打包（release）

`flutter build windows` 后，CMake 的 install 步骤会自动把
`app/kernel/dist/desktop/windows-*/{sing-box.exe, wintun.dll}` 拷到 app `.exe` 同级目录
（见 `windows/CMakeLists.txt` 的 “Pangolin sing-box kernel” 段）。**wintun.dll 必须与
sing-box.exe 同目录**，否则 sing-box 无法创建 TUN。

## 端到端验证（连通出网）

1. 管理员终端 `flutter run -d windows`（或运行打包后的 `.exe`，会弹 UAC）。
2. 登录 → 选节点 → connect。
3. 验证全局代理生效：

   ```powershell
   curl https://api.ipify.org   # 出口 IP 应为节点公网 IP
   ```

## 已知限制 / BACKLOG

- 提权用 `requireAdministrator`（每次启动弹一次 UAC）。正式版可换**特权 helper 服务**
  避免每次 UAC，类比 macOS 的 SMJobBless。见 `runner/runner.exe.manifest`。
- 未做 Inno Setup 安装包 / 代码签名 / CI Windows job（后续切片）。
- 停止用 `Process.kill`（Dart 在 Windows 映射为 TerminateProcess）；wintun 适配器随
  进程退出自动移除。