# Windows EXE 打包说明

桌面端支持打包成单个 EXE 文件。首次打包需要联网安装构建依赖，后续可复用项目中的 `.build-venv` 和 `.uv-cache`。

## 一键打包

最简单的方法是直接双击项目目录中的：

```text
一键打包EXE.bat
```

打包成功后会自动打开 `dist` 文件夹。若打包失败，命令窗口会保持打开并显示原因。

也可以在项目目录打开 PowerShell，运行：

```powershell
powershell -ExecutionPolicy Bypass -File build_windows_exe.ps1
```

生成文件位于：

```text
dist/ZhenAI-WeCom-Assistant-v1.0.0.exe
```

EXE 可以直接复制到其他 Windows 电脑运行，不需要另外安装 Python。程序运行数据保存在：

```text
%LOCALAPPDATA%\ZhenYangTangRPA
```

其中包含云端配置缓存、客服名称本地偏好、聊天记录和登记数据。升级 EXE 不会清空这些资料。

## 目标电脑要求

- 支持 Windows 10 / Windows 11 64 位系统。
- 不需要安装 Python。
- 不需要安装 Microsoft WebView2 Runtime；EXE 已内置 Qt WebEngine 浏览器内核、浏览器子进程、中文语言包和资源文件。
- 需要能够访问云端配置域名和客服网页域名。
- 第一次打开单文件 EXE 会释放内置浏览器组件，因此启动时间可能比后续稍长。

默认界面使用内置 Qt WebEngine。只有开发调试时主动添加 `--classic-ui` 参数，才会改用依赖系统 Microsoft Edge 的经典界面，正常客户使用无需该参数。

每次执行一键打包时，脚本都会强制检查以下内容：

- 内置 `QtWebEngineProcess.exe` 浏览器子进程
- Qt WebEngine 核心资源和字符数据
- `zh-CN` 中文语言包
- VC++ 运行库
- 打包后 EXE 能否离线创建浏览器内核并成功加载测试页面

任意一项缺失或浏览器自检失败，打包脚本都会返回失败，BAT 窗口会保留错误信息，不会把该 EXE 当成成功版本交付。

## 发布新版本

1. 修改 `app_version.py` 中的 `APP_VERSION`，例如改为 `1.0.1`。
2. 重新运行 `build_windows_exe.ps1`。
3. 把生成的 EXE 上传到可下载地址。
4. 在云端管理后台“桌面端版本升级”中填写相同版本号和下载地址。
5. 确认下载地址可用后，再决定是否开启强制升级。

建议发布前在另一台 Windows 电脑上打开 EXE，确认软件能启动、能加载客服页面并能收到云端配置。

## 生成可安装版本

直接双击：

```text
一键生成安装包.bat
```

它会先重新生成并验证桌面 EXE，再制作中文 Windows 安装包。第一次制作安装包时，会从 NuGet 软件包源下载固定版本的开源 NSIS 构建工具，并校验文件哈希，后续可直接复用。

安装包生成在：

```text
dist\installer\甄AI客服-安装包-v1.0.0.exe
```

安装后的效果：

- 软件名称为“甄AI客服”
- 自动创建桌面快捷方式
- 自动创建开始菜单快捷方式
- 快捷方式名称和安装后的程序名称均为“甄AI客服”
- 安装到当前用户目录，无需管理员权限
- 可以在 Windows“已安装的应用”中正常卸载
- 覆盖安装新版时保留 `%LOCALAPPDATA%\ZhenYangTangRPA` 中的配置和聊天资料

说明：桌面和开始菜单中显示的是“甄AI客服”。安装目录里的主程序会保留打包时的英文文件名，这是 Qt WebEngine 浏览器内核正常启动所必需的，请不要手动重命名安装目录中的 EXE。