One Person Lab Windows x64 安装与配置教程

当前公开下载入口始终是 One Person Lab App 的 Latest Stable Release：

https://github.com/gaofeng21cn/one-person-lab-app/releases/latest

Release 页面中的版本号和安装包文件名会随发布变化。教程不复制某个版本的 tag、文件名、 大小或 SHA-256；这些值应在安装时从同一 Latest Release 的平台 manifest 与 updater receipt 读取。

PDF 版本：下载本教程

先理解证据边界

Latest Release 上的 Windows x64 EXE、blockmap、latest.yml、平台 manifest 和 updater receipt，只能证明 release carrier 上存在这些精确 bytes 及其 digest。

它不能证明 WSL2 runtime acceptance、installed behavior 或产品支持完成，也不能从 release asset、文档生成或 focused tests 推导出生产环境、长期升级、代码签名或 release-wide ready。安装后应以实际 App readback、可见错误和独立的 installed/runtime 验收为准。

安装器的 Authenticode 状态以 Latest Release 中 opl-windows-updater-assets.json 的 code_signing 字段为准。Windows SmartScreen 仍可能显示警告；不要关闭 Microsoft Defender、修改全局 SmartScreen 策略，也不要把未签名文件描述为已签名。

1. 准备 Windows 11 x64

建议准备：

  • Windows 11 x64；
  • 当前用户可以安装桌面应用；
  • 至少 2 GB 可用磁盘空间；
  • 可以访问 GitHub Releases；
  • 如 App 实际进入 WSL 2 配置流程，Windows 的虚拟化与 WSL 组件可用。

关闭正在运行的旧 One Person Lab 窗口。不要删除 %APPDATA%、项目目录、Docker volume 或 WSL 发行版来“准备干净环境”；这些位置可能包含用户数据。

2. 从 Latest 下载并校验 Windows 资产

打开：

https://github.com/gaofeng21cn/one-person-lab-app/releases/latest

在 Assets 区域选择名称符合 One-Person-Lab-*-win-x64.exe 的 EXE。不要选择 .blockmap、latest.yml、JSON 或 Source code。若页面中没有唯一的 Windows x64 EXE， 不要从历史 tag 猜测地址；这表示当前 Latest 尚不能提供该平台资产。

也可以在下载目录打开普通 PowerShell，运行下面的命令，让平台 manifest 决定当前文件名 和 SHA-256，并通过 Latest URL 下载和校验：

$repo = 'gaofeng21cn/one-person-lab-app'
$latest = "https://github.com/$repo/releases/latest"
$platformManifest = "$latest/download/opl-desktop-platforms-manifest.json"
$platforms = Invoke-RestMethod $platformManifest
$matches = @($platforms.assets | Where-Object {
  $_.name -like 'One-Person-Lab-*-win-x64.exe'
})
if ($matches.Count -ne 1) {
  throw "Latest Release 必须包含一个 Windows x64 EXE，实际为 $($matches.Count) 个。"
}

$asset = $matches[0]
$installer = Join-Path (Get-Location) $asset.name
Invoke-WebRequest -UseBasicParsing "$latest/download/$($asset.name)" -OutFile $installer

$expected = $asset.digest -replace '^sha256:', ''
$actual = (Get-FileHash $installer -Algorithm SHA256).Hash.ToLowerInvariant()
if ($actual -ne $expected) {
  Remove-Item $installer -Force
  throw 'SHA-256 不一致，已删除下载文件。'
}

Write-Host "已校验: $($asset.name)"

需要查看签名政策和当前签名状态时，读取同一 Latest Release 的 updater receipt：

$updaterReceipt = "$latest/download/opl-windows-updater-assets.json"
$receipt = Invoke-RestMethod $updaterReceipt
$receipt.code_signing | Format-List

不要从旧截图、旧 issue、第三方网盘或历史 tag 猜测下载地址。若文件名、大小或 SHA-256 不一致：

  1. 不要运行该 EXE。
  2. 删除这一个错误下载文件。
  3. 从上面的 Latest Release 页面重新下载。
  4. 重新读取平台 manifest 并再次运行 Get-FileHash。

不要通过关闭 Defender、忽略 digest 或改名来绕过不一致。

3. 安装

  1. 双击刚才校验通过的 One-Person-Lab-...-win-x64.exe。
  2. 如果 Windows SmartScreen 出现，先确认文件名和刚才校验的 SHA-256。
  3. 只有在来源与 digest 都一致时，才根据系统界面决定是否继续。
  4. 完成安装后，从开始菜单启动 One Person Lab。

本指南记录当前公开资产，不承诺每台机器都已通过 exact installed acceptance。若 安装器失败，记录 Windows 版本、文件名、SHA-256、时间点和完整可见错误，不要重复 快速启动多个安装进程。

4. 首次启动与 Gateway 账户

首次启动后，按 App 当前界面完成设置。若界面要求 Gateway 账户：

  1. 在 App 的受控输入界面填写邮箱和密码。
  2. 点击“登录并继续”。
  3. 确认 App 显示当前账户。
  4. 按界面提示完成“设为模型访问方式”或等价的模型访问确认。
  5. 打开模型设置，确认模型目录可读。

Gateway 密码、token 和 API Key 不应进入 PowerShell、命令行参数、日志、截图或 问题报告。

当前版本只把 gateway.medopl.com 作为 OPL Gateway 的可信服务主机：账户登录、账户信息和用量查看使用 https://gateway.medopl.com/api/v1，模型访问使用 https://gateway.medopl.com/v1。新配置会由 App 自动写入 provider ID oplgateway 和上述模型地址，无需手工填写 Base URL。

已有 OPL Gateway Codex 配置会按 Gateway 地址原位复用，不会隐式迁移旧配置，也不会改写原 provider ID、名称或 Base URL，以保留既有会话和配置关联。

5. WSL 2 与 OPL-Linux

App contract 要求 Windows 上的 agent 和 Framework 执行边界使用专用 OPL-Linux，不允许 native Windows executor fallback。但当前 Stable Release asset 的存在本身不证明该执行边界已经在你的安装上通过验收。

如果 App 实际显示 WSL 2 配置、修复或重启流程：

  • 只按 App 当前界面操作；
  • 不要修改其他 WSL 发行版或默认发行版；
  • 不要执行 wsl.exe --unregister OPL-Linux 作为普通排障；
  • 不要手工修改 /opt/opl、/home/opl/.codex 或 /home/opl/.opl；
  • 需要只读检查时，可在普通 PowerShell 运行：
wsl.exe --version
wsl.exe --status
wsl.exe --list --verbose

如果 App 没有显示 WSL 流程，也不要根据本指南自行 bootstrap 产品 runtime。记录 实际界面和 readback，由 App/Shell owner 的合法入口判断。

6. 做一次真实模型访问检查

在单独的测试目录创建一个短任务，例如：

只回复 OPL_WINDOWS_MODEL_ACCESS_PASS，不要添加其他内容。

只有真实回复、会话完成和重新打开后的状态 readback 才能说明这次模型访问成功。 只打开窗口、只看到首页、下载成功或本地 health 响应都不能替代模型访问结果。

7. 检查更新

Latest Release 中的 Windows updater metadata latest.yml 和 receipt opl-windows-updater-assets.json 证明当前 Release 上存在 updater 资产， 但不自动证明长期升级或所有 predecessor 路径已通过。

使用 App 内“检查更新”时：

  1. 记录当前显示版本。
  2. 让 App 完成一次检查。
  3. 若更新可用，保存工作后按界面执行。
  4. 更新后重新打开 App，回读版本、Gateway 状态和一次真实模型请求。

不要手工替换 latest.yml、blockmap 或安装目录中的二进制文件。

8. 可选：Docker WebUI

Container WebUI 是独立运行形态：

https://gaofeng21cn.github.io/one-person-lab-app/latest/docker-webui-install/docker-webui-install.html

Windows Desktop App 不要求 Docker Desktop。只有在选择 Container WebUI 时，才按 独立教程安装 Docker Desktop，并访问：

http://localhost:3000/

不要为修复桌面 App 执行 Docker Factory Reset 或全局 Docker prune。

9. 日志与问题报告

遇到问题时记录：

  • Windows 版本和 OS build；
  • App“关于”页显示的版本，以及当时的 Latest Release URL；
  • 安装包文件名与 SHA-256；
  • 安装、首次启动、WSL、登录或模型访问阶段；
  • 可见错误原文；
  • 是否从旧版本升级；
  • App 显示的日志和诊断入口。

提交问题：

https://github.com/gaofeng21cn/one-person-lab-app/issues/new

不要上传整个用户数据目录。先删除邮箱、项目内容、token、API Key 和其他秘密。

10. 卸载与用户数据

  1. 正常退出 One Person Lab。
  2. 打开“设置 -> 应用 -> 已安装的应用”。
  3. 找到 One Person Lab。
  4. 点击“卸载”并完成向导。

卸载程序文件不等于删除用户数据、项目、Gateway 会话、OPL-Linux 或 Docker volume。需要清理测试数据时，先从 App 的数据、存储和诊断页面读取实际路径，再逐项 决定保留、导出或删除。

常见问题

双击后没有窗口

等待 20 秒并查看任务管理器。如果进程立即退出，记录时间和 App 日志入口。不要连续 启动多个实例，也不要先删用户数据。

SmartScreen 为什么提示未知发布者

先读取 Latest Release updater receipt 的 code_signing.status，再核对文件名和 SHA-256；不要关闭 Defender 或修改全局安全策略。签名状态只能以该 Release receipt 和 Windows readback 为准。

是否已经证明 Windows 产品支持完成

没有。当前证据证明 Stable Release 上存在精确 Windows x64 资产、updater metadata 和公开 digest；它不能证明 WSL2 runtime acceptance、installed behavior 或产品支持完成。

可以手工修复 OPL-Linux 吗

不建议。保留现场，使用 App 当前修复/诊断入口，并提供最小 readback。不要注销 OPL-Linux，因为该操作会不可恢复地删除发行版内数据。