One Person Lab App 首次安装图文教程

macOS 下载、安装与首次设置

适用对象：医生、PI、课题负责人及合作团队成员；不要求计算机基础。

本文按“安装 App、完成首次检查、登录或确认模型访问、进入工作台”的顺序说明 One Person Lab App 的首次使用。

下载最新版本：https://github.com/gaofeng21cn/one-person-lab-app/releases/latest

已安装 Homebrew 的 Mac 用户优先使用 Homebrew Cask 安装 Standard；直接 DMG 适合无 Homebrew 用户，Full DMG 只用于需要离线预置的新机器。不要把可变分支中的 安装脚本直接通过管道交给 shell 执行。

准备清单

  • 一台 Apple Silicon（arm64）Mac；当前 macOS App 不支持 Intel Mac。
  • 稳定网络，用于下载安装包和完成首次检查。
  • 一个本机工作目录，用于保存项目材料和生成结果。
  • 可选：可用的 OPL Gateway 账户，或兼容方式所需的 API Key。本机已有可用 Codex 配置时可以直接重新检测。

1. 安装 One Person Lab

推荐打开 macOS“终端”，粘贴并运行下面的 Homebrew Standard 安装命令：

brew install --cask gaofeng21cn/one-person-lab/one-person-lab

这条命令适用于 Standard 首次安装和稳定版升级。Homebrew Cask 会把 App 安装到 “应用程序”，但不会自动打开 App，也不应被当作清理 quarantine 的入口。安装完成后运行：

open -a "One Person Lab"

App 启动后可直接跳到第 3 步。

不方便使用终端时，打开上面的最新 Release 页面，在 Assets 区域下载 One-Person-Lab-<版本>-mac-arm64.dmg。教程只保留 Latest 入口，不展示会随发版过期的 版本截图或精确 tag URL。

  • 当前只提供 Apple Silicon（arm64）安装包。
  • 不要下载 ZIP、blockmap、YML、JSON 或 Source code。
  • Release 页面版本号会持续变化，以标记为 Latest 的稳定版为准。
  • Standard 选择 One-Person-Lab-<版本>-mac-arm64.dmg。
  • 只有需要离线 Base 和 Package seeds 时才选择同 tag One-Person-Lab-Full-<版本>-mac-arm64.dmg。Full 不是更新频道，后续仍走 Standard 更新路径。

从已审阅的 source checkout 开发或恢复时可以运行仓库内的 ./install.sh。普通安装 不要从可变 main 分支下载后直接执行；需要终端入口时，从 Latest Release 下载唯一 公开 installer opl-install.sh。它会先解析并绑定当前精确 Release：

curl -fLO https://github.com/gaofeng21cn/one-person-lab-app/releases/latest/download/opl-install.sh
chmod 0755 opl-install.sh
./opl-install.sh --stable-macos-install --standard --yes

该 installer 会在挂载 DMG 或替换 App 前校验所选 Release 的 component manifest、installer 与 DMG 的摘要。

2. 手工安装 DMG（可选）

仅在第 1 步选择 Standard 或 Full DMG 时执行本步。打开 DMG，将 One Person Lab 拖到 Applications。复制完成后关闭 DMG 窗口，再从“应用程序”启动 App。

将 One Person Lab 拖入 Applications

首次打开如出现 macOS 安全提示，按系统提示确认。不要长期在 DMG 挂载窗口中直接运行 App；如果系统持续阻止打开，可改用第 1 步的 Latest opl-install.sh，由它完成摘要校验、复制、quarantine 清理和启动。

3. 完成首次检查

首次启动后，OPL 会先检查工作目录、本机助手和模型访问，并显示当前进度。

等待 OPL 完成首次检查

检查期间可以先点击右上角“进入 OPL”，但这不会自动完成尚未配置的项目。出现“需要处理”时，按页面给出的下一步操作即可；技术细节默认折叠，不要求普通用户理解底层工具名称。

4. 登录或确认模型访问

模型访问显示“缺失”时，根据实际情况处理：

  1. 账户登录（默认）：填写 OPL Gateway 的“邮箱”和“密码”，点击“登录并继续”。密码只用于本次登录，不会保存在 App 中。
  2. 重新检测已有配置：本机 Codex/OpenAI 已登录或已有可用配置时，点击“重新检测已有配置”。这是独立检测操作，不是第三种登录方式。
  3. API Key（兼容方式）：只有需要手工密钥接入时才切换到“API Key”，按团队提供的方式填写。
  4. 暂时进入工作台：当前没有可用账户或密钥时，可先点击右上角“进入 OPL”；需要模型的功能仍会提示完成访问设置。

默认使用账户登录，也可切换 API Key 或重新检测已有配置

请勿把密码或完整 API Key 发送到群聊、公开文档或代码仓库，也不要在截图中展示。

5. 开始第一项工作

进入主界面后，可以直接描述目标，也可以选择科研、基金、演示或写书等专业入口。本教程以科研入口为例。

在主界面描述目标或选择专业工作入口

第一条任务建议同时说明目标和材料位置，例如：

我有一批已经脱敏的肺结节随访数据，材料在当前项目的 raw_data 文件夹。请先判断最值得推进的研究问题，并说明还缺哪些证据。

涉及患者或敏感研究数据时，应先完成脱敏，并遵守所在机构的数据管理和伦理要求。

6. 后续调整与更新

  • 管理 Gateway 账户和访问状态：打开“设置 -> 账户与访问”。
  • 选择模型：打开“设置 -> 模型”。
  • 调整工作目录：打开“设置 -> 工作区”。
  • 检查 App 更新：打开“设置 -> 关于”，再点击“检查更新”。
  • 再次打开 App 时，已经完成的首启设置会保留，不需要重复配置。

常见问题

  • Intel Mac 可以安装吗？ 当前不支持。请使用 Apple Silicon（arm64）Mac。
  • 已经在用 Codex，还需要登录 OPL Gateway 吗？ 不需要。点击“重新检测已有配置”即可确认现有模型访问。
  • 暂时没有 Gateway 账户或 API Key 怎么办？ 可以先“进入 OPL”，后续从“设置 -> 账户与访问”完成配置。
  • 下载页面里文件很多，应该选哪个？ 普通安装选择 One-Person-Lab-<版本>-mac-arm64.dmg；只有离线首装才选择同 tag Full DMG。不要下载 ZIP、blockmap、YML、JSON 或 Source code。
  • 打不开 App 怎么办？ 确认 App 已复制到 /Applications 并按 macOS 安全提示允许打开；仍无法启动时，使用同 tag opl-install.sh 安装。
  • 账户登录失败怎么办？ 确认邮箱和密码正确、网络可用；反馈问题时提供操作系统、发生步骤和不含密码或 API Key 的报错截图。
  • 需要自己选择具体模型版本吗？ 通常不需要；需要调整时打开“设置 -> 模型”。