OpenProgram 安装、打包、发布与升级设计

本文是 OpenProgram 安装与分发的规范来源。它分别定义用户类型与平台支持，覆盖 macOS 桌面包、macOS/Linux 命令行与服务器安装、浏览器访问、Python 运行时归属、Program 扩展环境、版本、升级和卸载。实施任务单独记录，不与概念设计混合。

1. 已确定的设计约束

1. Python 是 OpenProgram 后端、CLI、Runtime 和 Program 执行的核心运行时，不允许以删除 Python 的方式简化安装。
2. macOS 桌面版通过明确标注 Unsigned 的 DMG/ZIP 分发；Linux 只发布完整 CLI/server runtime，完整桌面包通过公共入口验收前不发布任何 Linux 桌面产物。
3. 所有非开发者安装使用同一份按平台与架构构建的完整 product runtime。Desktop 只是增加 Electron 外壳，CLI/server 只是增加命令行 launcher；二者不能安装不同的 Web、Provider、Channel、Browser、OCR 或第一方 Program 功能集合。
4. 完整 product runtime 包含固定 CPython、OpenProgram、预编译 Web、默认 Browser/Chromium、Channels、Search、GUI/Research/Wiki 第一方 Programs、默认 OCR、GUI detector 权重及其运行依赖。首次使用这些默认能力不再触发组件安装。
5. 普通用户不需要预装 Python、Node.js 或 Git。安装器可以下载与当前平台对应的完整 runtime archive，但安装完成后不能因缺少可选依赖而形成降级版本。
6. 桌面包与 CLI runtime 在运行期保持只读；配置、会话、缓存和用户新增的第三方 Program 写入 ~/.openprogram。
7. 开发安装在完整产品能力之上增加 editable source、调试工具、本地 Web/Ink 构建、测试工具，以及 OCR、Browser 等后端替换能力；开发模式不能用于补齐普通安装缺失的产品功能。
8. stable 表示已发布、已验证的版本，不表示 origin/main。main 只属于开发安装。
9. 正式安装不使用 editable checkout，不在用户机器上构建 Web 或 Ink，不依赖仓库目录，也不通过 PyPI 解析产品依赖。
10. PyInstaller、Briefcase 和 py2app 只作为参考实现，不替换现有 Electron 桌面应用。
11. 普通用户的 CLI/server 默认入口是 curl -fsSL https://openprogram.io/install | sh。站点脚本只解析最新稳定 release、校验版本格式并下载该不可变 tag 下的 installer；runtime checksum、capability manifest 和 cold-start 验证仍由版本化 installer 完成。
12. Windows 原生安装不进入当前 release，但不是被拒绝的方向。现有 runtime、manifest、installer 和 Desktop 分层必须避免引入阻止后续 Windows 实现的假设；是否支持及采用何种产物由后续独立决策确定。

2. 当前实现与已验证缺口

3. 官方规范与工具比较

本设计以 Electron 和 electron-builder 组装 macOS 桌面外壳，以 uv 和标准 wheel 组装内部 product runtime，并以 GitHub Release 分发 macOS/Linux 按平台与架构固定的完整 runtime archive。Apple、Linux 桌面打包与 PyPA 规范继续用于说明被明确拒绝或限制的分发选择。

4. 用户类型与平台支持

三类用户描述安装目的，平台矩阵描述产品承诺。两者分别维护，不能以用户类型代替平台覆盖。

4.1 平台支持矩阵

浏览器访问不把客户端操作系统提升为原生支持平台。服务端必须运行在受支持的 macOS 或 Linux 安装中；只有经过浏览器和响应式验收的组合才能标为正式支持。

5. 一个版本与一组发布产物

pyproject.toml 中的项目版本是规范版本来源。Electron metadata 由于构建工具要求保留副本，release gate 验证它、runtime manifest、release manifest 和 tag 完全一致。tag 必须指向被构建的 commit。

每次 release 至少生成：

• macOS arm64/x64 与 Linux x86_64/arm64 的完整 runtime archives；
• macOS arm64/x64 unsigned DMG 与 ZIP；
• 开发者使用的 wheel/sdist，但不作为普通用户安装入口；
• 包含版本、capability IDs、第一方 Program commits、模型标识、文件大小和 SHA-256 的 release manifest。

首个正式版本分别构建 arm64 和 x64，不生成 universal2。Python native wheels、Browser、OCR、模型和 Electron helper 都具有平台或架构差异；每个平台分别生成 runtime，但同一 capability manifest 的所有条目必须为 present 和 verified，否则整个平台不发布。

6. macOS 桌面包

6.1 逻辑内容

OpenProgram.dmg → OpenProgram.app/Contents/

macOS 桌面资源目录
        ├── MacOS/
        │   └── OpenProgram                 # Electron launcher
        ├── Frameworks/
        │   ├── Electron Framework.framework
        │   └── Electron helpers
        └── Resources/
            ├── app.asar                    # Electron main/preload
            └── runtime/
                ├── python/                  # 固定 portable CPython + 完整产品依赖
                ├── bin/uv                   # 固定 uv
                ├── wheel/                   # 构建时 wheel 证据
                ├── browser/                 # 默认 Chromium
                ├── models/                  # 默认 OCR 与 detector 数据
                └── runtime-manifest.json

macOS 和 Linux 的 portable CPython 都来自固定 uv 版本所索引的 python-build-standalone 产物。runtime manifest 记录 OpenProgram、Python、uv、capability manifest、第一方 Program commits、Browser 与模型标识；release manifest 记录最终 artifact hash。不允许从打包机系统 Python 复制任意运行时。

6.2 启动

1. Electron 读取 app 内的 runtime manifest，并验证完整 capability manifest 与所需文件。
2. Electron 使用 app 内的 Python worker launcher，调用明确的绝对路径，不查询 PATH。
3. Python 使用 -I -B 启动，忽略系统 PYTHONPATH、用户 site-packages 和系统 Python 配置，并禁止向 app 写入 bytecode。
4. launcher 设置 runtime 内默认 Browser、OCR 与 detector 资产路径，导入随 runtime 固定的第一方 Programs。
5. worker 监听本机端口并通过 /healthz 返回运行状态与 capability manifest hash。
6. Electron 获取认证 URL 后加载 Web UI；启动失败时显示错误类别、日志位置和修复动作。

6.3 不允许发生的行为

• 不调用 PATH 中的 openprogram、python、node 或 git。
• 不修改 /Applications/OpenProgram.app。
• 不在首次使用时下载 Python、Web、默认 Browser、默认 OCR、detector 权重或第一方 Programs。
• 不从仓库目录读取 web/out、Program checkout 或开发配置。
• 不在用户机器上执行 npm build、pip dependency resolution 或 git clone。

7. 完整产品 Runtime 与开发扩展

~/.openprogram/
├── programs/
│   ├── src/<program-id>/
│   ├── manifests/<program-id>.json
│   └── environments/
│       └── <runtime-id>/
│           ├── releases/<generation>/
│           └── current -> releases/<generation>
├── config/
├── sessions/
├── logs/
└── cache/

runtime-id 至少包含 CPython minor version、CPU architecture、dependency lock、第一方 Program commits 和模型标识。Desktop 与 CLI 在相同平台架构上的 runtime ID 和 capability manifest hash 必须一致。

第三方 Program 的 install、upgrade 和 remove 执行同一事务：

1. 解析 Program 来源和声明，写入临时目录；
2. 使用 app 内的 uv 和 CPython 创建 staging environment；
3. 从全部已启用 Program manifest 解析并安装依赖，记录精确版本和 artifact hash；
4. 执行 import probe、Program 注册检查和 worker cold-start probe；
5. 全部通过后原子切换 current；失败时删除 staging environment，继续使用原环境。

8. 安装、升级和卸载

8.1 桌面安装

1. macOS 用户下载对应架构且文件名含 unsigned 的 DMG，验证 SHA-256，复制 App 后通过“隐私与安全性 → 仍要打开”完成首次授权。
2. Desktop artifact 内嵌已经通过完整 capability probe 的平台 runtime archive；首次启动只创建配置和状态目录。
3. worker 从桌面包内置 CPython 启动。
4. Linux 不提供桌面安装；用户安装完整 CLI/server runtime 后使用 Web UI 或 TUI。

8.2 CLI / Server 安装

1. 默认命令 curl -fsSL https://openprogram.io/install | sh 从项目域名取得短 bootstrap；bootstrap 在未指定 OPENPROGRAM_VERSION 时通过 GitHub 的 latest release redirect 解析稳定版本。
2. bootstrap 只接受三段数字版本，随后下载对应不可变 tag 下的 scripts/install-release.sh。需要可复现安装时可在 sh 进程上显式设置 OPENPROGRAM_VERSION=X.Y.Z。
3. 版本化 installer 从同一 GitHub Release 下载与 OS/architecture 精确匹配的 runtime archive 和 checksum，不访问 PyPI。
4. 校验后解压到 ~/.openprogram/runtime/cli/releases/X.Y.Z；macOS Desktop 使用同一 archive 作为构建输入，Linux 直接以该完整 archive 作为正式产品入口。
5. 安装器使用 runtime 的绝对路径执行版本、capability、first-party Program、Browser/OCR asset 和 worker cold-start probes。
6. 全部成功后原子切换 current，并在 ~/.local/bin/openprogram 创建 launcher；失败时继续使用旧版本。

8.3 开发安装

开发文档使用仓库 checkout、uv sync、Web/Ink build 和测试工具。开发环境必须能执行与 release 相同的 capability probe，并允许以显式配置替换 OCR/Browser 后端、编辑第一方 Program 源码和启用诊断；这些 overlay 不改变产品 manifest。

8.4 升级

• macOS 桌面：手动下载新 DMG；当前 unsigned 产物不启用 electron-updater。
• CLI / Server：下载新的完整 runtime archive，在新 version directory 验证后切换 current；失败时保留旧版本。
• 开发：保留 source checkout 的 fetch、build、完整 capability probe 和 restart 流程，目标 ref 必须显式。
• 命令：openprogram upgrade 是统一公开命令；旧 update 先作为兼容别名，再按弃用策略移除。

GUI、Research、Wiki 第一方 Programs 与产品 runtime 原子升级；任一第一方 Program 或默认资产验证失败时，整个新 runtime 不得激活。第三方 Program 使用独立 environment 迁移；迁移失败只停用对应第三方 Program，不改变已验证的产品 capability manifest。

8.5 卸载

• 删除 OpenProgram.app 只卸载桌面应用，默认保留 ~/.openprogram。
• CLI uninstall 删除启动入口和 OpenProgram 管理的 CLI runtime，默认保留状态。
• 只有显式 purge 操作删除配置、会话、Program 和缓存；执行前必须显示精确目录并要求确认。

9. 安全、完整性和失败处理

发布不需要 Apple 或 PyPI 凭据；GitHub Actions 使用仓库提供的短期 token 创建 Release。第一方 Program commits、模型来源和 runtime archive hash 进入 release manifest。本文不增加系统 Keychain、keyring 或 Credential Manager 集成。

10. 公共入口验收标准

10.1 平台 product runtime

1. 在原生 runner 从固定 OpenProgram commit、dependency lock、第一方 Program commits 和模型来源构建。
2. openprogram --version、worker cold-start、/healthz、/chat 和 hashed Web asset 成功。
3. GUI、Research、Wiki Functions 全部注册；Channels、Search、默认 Playwright Chromium、EasyOCR 与 detector weight 的 import/asset probe 成功。
4. 生成 capability manifest 和 runtime archive SHA-256；缺少任一项即失败。

10.2 macOS DMG

1. 分别在未安装 OpenProgram、Python、Node.js 和 Git 的干净 arm64 与 x64 环境验证。
2. 文件名、Release 说明和安装页明确标注 unsigned，并验证“隐私与安全性 → 仍要打开”流程。
3. 断网后完成首次启动、worker、Web、第一方 Program 注册、默认 Browser/OCR/model probe。
4. Electron 启动的 Python 路径与 capability manifest hash 必须来自内嵌 runtime archive。

10.3 Linux 桌面发布门禁

1. Linux 桌面产物必须封装与 CLI/server 相同的完整 runtime，不能删减任何 capability、Program、OCR、模型或 Browser 资产。
2. 必须在无系统 OpenProgram、Python、Node.js 和 Git 的干净 x86_64 Linux 环境从公开入口启动，并在断网环境完成完整 probes。
3. 当前 AppImage 在完整 runtime 的 electron-builder block-map 阶段失败，因此没有产物通过本门禁；release 配置不得构建或发布 AppImage。
4. 只有新的完整桌面产物通过本节全部条件后，才能恢复 Linux 桌面支持声明。

10.4 第三方 Program 与开发 overlay

1. 第一方 GUI/Research/Wiki 不允许显示为未安装，也不由首次启动 wizard 补装。
2. 第三方 Program 只修改 ~/.openprogram/programs 和独立 environment，不能覆盖产品 runtime。
3. 开发者替换 OCR/Browser backend 或启用调试后，基础 capability manifest 仍能通过。

10.5 CLI / Server

1. curl -fsSL https://openprogram.io/install | sh 可以在干净 macOS/Linux 用户环境解析最新稳定 release 并下载固定 runtime archive，不访问 PyPI、不克隆仓库。
2. 短 bootstrap 的自动版本解析和显式 OPENPROGRAM_VERSION 固定版本路径均需通过无网络的入口测试；解析结果必须限定为三段数字版本，下载地址必须使用对应不可变 tag。
3. 安装后的 runtime archive hash 和 capability manifest hash 与 release manifest 一致；macOS Desktop 使用相同构建输入。
4. 安装器使用 runtime 绝对路径执行完整 probes；升级失败时旧版本仍能启动。

10.6 release

1. tag、runtime archive、Electron package、manifest 和 health endpoint 报告相同版本。
2. GitHub Release 包含 macOS runtime archives 与 unsigned DMG/ZIP、Linux runtime archives、checksums 和 capability manifest；不包含未通过门禁的 Linux 桌面包。
3. 普通用户文档不出现 pip install openprogram、缺省 optional Program 或组件补装步骤。
4. 已发布 tag 不允许移动；修复使用更高 patch version。

实施记录：任务拆分、RED/GREEN、审查和 gate 记录位于 Installation and distribution implementation plan。该记录不改变本文的概念边界。

11. 实现状态

12. 明确不在范围内

• macOS App Store、Developer ID 签名与 notarization；
• 系统 Keychain、keyring、Credential Manager 或同类 credential-store 集成；
• 把 OpenProgram 改写成不需要 Python 的应用；
• 以 PyInstaller、Briefcase、py2app 或 Tauri 替换现有 Electron；
• 第一阶段实现 per-Program 进程隔离；
• 自动安装任意第三方 Program；
• 把可替换 OCR、stealth/agent-browser backend 或调试工具作为普通用户产品依赖。

相关设计：Single-port worker and frontend；Self-update。安装与分发的冲突内容以本文为准，并在相关设计中引用本文。