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

正式版本：v0.9.8

本文是 OpenProgram 安装与分发的规范来源。它分别定义用户类型与平台支持，覆盖 macOS/Windows 桌面包、macOS/Linux/Windows 命令行与服务器安装、浏览器访问、Python 运行时归属、Program 扩展环境、版本、升级和卸载。正式版本的检查、下载、平台安装边界和当前实现证据由正式版本自动更新设计细化。

1. 已确定的设计约束

1. Python 是 OpenProgram 后端、CLI、Runtime 和 Program 执行的核心运行时，不允许以删除 Python 的方式简化安装。
2. macOS 桌面版通过明确标注 Unsigned 的 DMG/ZIP 分发；Windows 桌面版只通过 Authenticode 签名的 x64 NSIS installer 分发；Linux 只发布完整 CLI/server runtime。
3. 所有非开发者安装使用同一份按平台与架构构建的完整 product runtime。Desktop 只是增加 Electron 外壳，CLI/server 只是增加命令行 launcher；二者不能安装不同的 Web、Provider、Channel、Browser、模型资产或第一方 Program 功能集合。
4. 完整 product runtime 包含固定 CPython、OpenProgram、预编译 Web、Channels、Search、GUI/Research/Wiki 第一方 Programs、Playwright Chromium、GPA detector 权重，以及 Research 的 PDF 支持和其他 manifest 依赖。GUI Program 使用 --no-deps 安装；product runtime 明确排除 PyTorch、torchvision、OpenCV、EasyOCR、sentence-transformers、triton 和 NVIDIA/CUDA distributions。
5. 普通用户不需要预装 Python 或 Node.js。Session 与 Memory 的 Git history 需要 PATH 中可用的系统 Git，product runtime 不内嵌 Git。安装器可以下载与当前平台对应的完整 runtime archive，但不能把缺少 manifest capability 的产物标为完整安装。
6. 桌面包与 CLI runtime 在运行期保持只读；配置、会话、缓存和用户新增的第三方 Program 写入 ~/.openprogram。
7. 开发安装在完整产品能力之上增加 editable source、调试工具、本地 Web/Ink 构建、测试工具，以及 GUI perception、OCR、Browser 等显式配置的 backend overlay。依赖 PyTorch、OpenCV 或 EasyOCR 的 GUI perception 路径只在这类 overlay 中提供，不属于普通安装的 manifest capability。
8. stable 表示已发布、已验证的版本，不表示 origin/main。main 只属于开发安装。
9. 正式安装不使用 editable checkout，不在用户机器上构建 Web 或 Ink，不依赖仓库目录，也不通过 PyPI 解析产品依赖。
10. pip install openprogram、pipx install openprogram 和 uv tool install openprogram 都不是受支持的产品安装入口。公开索引、入门文档和运行时修复提示只能指向正式安装器或完整安装包；wheel 仅用于 release runtime 组装、源码开发和测试。
11. PyInstaller、Briefcase 和 py2app 只作为参考实现，不替换现有 Electron 桌面应用。
12. 普通用户的 CLI/server 默认入口是 curl -fsSL https://openprogram.io/install | sh。站点脚本只解析最新稳定 release、校验版本格式并下载该不可变 tag 下的 installer；runtime checksum、capability manifest 和 cold-start 验证仍由版本化 installer 完成。
13. macOS 本机安装态只有固定路径 /Applications/OpenProgram.app。本地桌面构建在未注册的临时目录生成并验证 App，随后替换该固定路径；临时 App 不启动、不保留，也不使用版本号或任务名作为 App 目录名。
14. Windows x86_64 CLI/server 使用完整 ZIP runtime 与 PowerShell installer。Windows Desktop 使用同一 runtime archive、按用户 NSIS installer、ConPTY 与强制签名 release gate；Windows 沙箱仍是独立层级。

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

3. 官方规范与工具比较

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

4. 用户类型与平台支持

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

4.1 平台支持矩阵

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

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

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

每次 release 至少生成：

• macOS arm64/x64、Linux x86_64/arm64 与 Windows x86_64 的完整 runtime archives；
• macOS arm64/x64 unsigned DMG/ZIP 与 Windows x64 signed EXE；
• 开发者使用的 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 与 Windows 桌面包

6.1 图标资产

• apps/desktop/build/AppIcon.icon 是 Apple 分层维护源，四个 SVG layer 使用 1024×1024 未遮罩画布；apps/desktop/build/icon.icns 是受版本控制、供 Electron 打包的兼容产物。
• legacy ICNS 保留经过系统 App 对照验收的可见范围、圆角轮廓、透明四角和受控阴影；分层 .icon 本身不得预绘系统外框。
• 薰衣草色细胞和其中三个扁平圆片保持居中并位于安全区域，不增加文字、问号或嵌入 raster。标志定义见 App 图标规范。
• 构建门禁验证分层源结构、品牌图形约束、ICNS representations、256 px 轮廓与实心面积、透明四角和 ICNS round trip；最终只通过安装后的 /Applications/OpenProgram.app 检查 Dock、Finder 和 Launchpad 显示。

6.2 逻辑内容

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 证据
                ├── assets/playwright/       # 固定 Playwright Chromium
                ├── assets/gpa/model.pt      # GPA detector 权重
                └── runtime-manifest.json

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

6.3 启动

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 内 Playwright Chromium 与 GPA detector 资产路径，导入随 runtime 固定的第一方 Programs。
5. worker 监听本机端口并通过 /healthz 返回运行状态与 capability manifest hash。
6. Electron 获取认证 URL 后加载 Web UI；启动失败时显示错误类别、日志位置和修复动作。

6.4 不允许发生的行为

• 不调用 PATH 中的 openprogram、python、node 或 git。
• 运行中的 App 和自动更新器不直接修改自身 bundle；只有本地安装事务或经验证的正式更新事务可以替换固定 /Applications/OpenProgram.app。
• 本地安装器取得固定路径安装锁后，先复制并验证候选 App，再以不可变的事务副本版本重新读取、比较当前 App；若候选版本更低，必须在停止 worker 或移动文件前拒绝。版本段按十进制任意精度整数比较。固定路径已经存在但无法验证时必须保留原内容并失败，不能跳过比较。
• 同版本开发刷新必须同步 Electron main/preload、正式 updater 实现及其运行依赖，不能生成引用当前源码但保留旧模块的 app.asar。刷新构建完成后必须校验 wheel metadata，并在与完整安装器共享的固定路径锁内重新核对源码、wheel 与当前 App，之后才能停止 worker 或写入 Python/asar。
• 不在首次使用时下载 Python、Web、默认 Browser、默认 OCR、detector 权重或第一方 Programs。
• 不从仓库目录读取 apps/web/out、Program checkout 或开发配置。
• 不在用户机器上执行 npm build、pip dependency resolution 或 git clone。

6.5 Windows 封装与签名

• Electron-builder 生成 x64、按用户安装、可选择目录的 NSIS installer，并以 asInvoker 运行。
• 封装输入是正式 Windows runtime ZIP；先通过 PowerShell release installer 完成 archive、manifest、capability 和 worker cold-start 验证，再移动到 Desktop resources。
• 应用 executable 与 installer 都必须通过 Authenticode。缺少证书或签名无效时 release job 失败，不能上传 unsigned Windows Desktop。
• 本地 unsigned build 只用于开发 package smoke，不是公开安装入口。
• Terminal 使用 Windows PowerShell/ConPTY；浏览器资料导入使用 Windows 正常安装与 Local AppData 位置；这些路径不修改用户 ACL。

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，将唯一的 OpenProgram.app 复制到 Applications 并替换旧版，再通过“隐私与安全性 → 仍要打开”完成首次授权。
2. Windows 用户只下载 release 附带的精确 win-x64.exe，同时验证 SHA-256 与 Authenticode，再运行按用户 NSIS 安装向导；没有带签名 EXE 的版本使用 CLI/server。
3. 本地 macOS 开发者执行 npm --prefix apps/desktop run dist 时，脚本在随机临时目录构建一个 unpacked App，校验 bundle identifier、版本、主 executable 和内嵌 runtime，然后停止正在运行的正式 App 及默认 worker。候选版本低于当前固定 App 时必须在任何 App、worker 或 Launch Services 修改前拒绝安装。
4. scripts/refresh-local-app.sh 只用于同版本 macOS 源码刷新：checkout 的 Python/desktop 版本、现有 bundle、runtime manifest 和内置 Python distribution metadata 必须完全一致。任一版本不同即在构建 wheel、停止 App 或写入 runtime 前失败；版本升级必须重新封装并安装完整 App。
5. macOS 封装使用与 worktree 无关的用户级锁；安装器另在目标 Applications 目录持有覆盖完整事务的原子锁。并发调用必须在修改 App 或服务前明确失败，锁清理只删除当前 PID 持有的锁。
6. 若默认 profile 已安装 launchd 服务，替换前先卸载 KeepAlive 服务，再停止实际持锁 worker；成功后用新 App 的内嵌 Python 和 -I -B 重新安装服务，并等待 /healthz 成功后再打开 App。服务的 ProgramArguments 不得继续指向 conda、源码 checkout 或已删除 App。
7. macOS 脚本先在 Applications 所在卷完成 staging；只有 staging 完整后才将旧 App 临时移入同一事务目录并激活新 App。激活失败时恢复旧 App、launchd 服务及替换前的 App/worker 运行状态；成功后删除旧 App、Python wheel 构建缓存、runtime staging、构建目录与事务目录。
8. macOS 激活后显式将固定 /Applications/OpenProgram.app 注册到 Launch Services；后续步骤失败并恢复旧 App 时，以 best-effort 重新注册恢复后的固定路径，同时保留原始失败状态。
9. 两个平台的 Desktop artifact 都内嵌已经通过完整 capability probe 的平台 runtime archive；首次启动只创建配置和状态目录，worker 从桌面包内置 CPython 启动。packaged mode 的认证 URL 同样只由内置 Python 生成，不依赖系统 CLI。
10. Linux 不提供桌面安装；用户安装完整 CLI/server runtime 后使用 Web UI 或 TUI。

8.1.1 同版本本地刷新完成条件

本地刷新只启动一次新内嵌 worker：已有 launchd 服务时，服务安装负责提交启动请求；否则由内嵌 CLI 启动一个后台 worker。默认端口 18100 的健康轮询限时一百二十秒，每次探测单独限制时长；轮询不会反复启动 worker。超时记录失败的健康端点与 worker 日志位置，并保留失败状态。完整 App 通过代码签名验证后，即使健康或 worker 身份验证失败，退出清理仍尝试重开同一 App。重开仅执行一次，保留最初的失败状态，并单独报告重开失败。签名验证前的失败不启动部分更新或未验证的 App。清理保留临时目录删除错误，并继续尝试其他清理；已有主错误时保留主错误，否则返回清理错误。清理失败不输出刷新成功。已有提交源码、版本、外部签名和锁限制继续适用。

8.2 CLI / Server 安装

1. macOS/Linux 使用 curl -fsSL https://openprogram.io/install | sh，Windows 使用 irm https://openprogram.io/install.ps1 | iex；短 bootstrap 在未指定 OPENPROGRAM_VERSION 时通过 GitHub latest release 解析稳定版本。
2. bootstrap 只接受三段数字版本，随后下载对应不可变 tag 下的平台兼容入口 scripts/install-release.sh 或 scripts/install-release.ps1，再取得同一 tag 下的正式实现。
3. 正式 installer 从同一 GitHub Release 下载与 OS/architecture 精确匹配的 runtime archive 和 checksum，不访问 PyPI。
4. 校验后解压到用户状态目录下的 runtime/cli/releases/X.Y.Z；macOS Desktop 使用同一 archive 作为构建输入，Linux 与 Windows 直接以完整 archive 作为正式产品入口。
5. 安装器使用 runtime 的绝对路径执行版本、capability、first-party Program、Browser/OCR asset 和 worker cold-start probes。
6. 全部成功后，macOS/Linux 原子切换 current symlink；Windows 原子替换 PowerShell launcher 并保留上一份 launcher。失败时继续使用旧版本。

8.3 开发安装

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

8.4 升级

• macOS 桌面：自动检查最新正式 Release；设置页按架构下载完整 DMG，验证字节数和 SHA-256 后打开，由用户确认替换 App。
• Windows 桌面：选择精确 signed EXE，验证字节数、SHA-256 与 Authenticode 后打开，由用户确认安装。
• CLI / 服务端：openprogram upgrade 下载新的完整 runtime archive，在新 version directory 验证后切换 current；失败时保留旧版本，运行中的 worker 由用户显式重启。
• 开发：同一命令在 source checkout 中保留 fetch、build、完整 capability probe 和 restart 流程，目标 ref 必须显式。
• 兼容命令：旧 update 是 upgrade 的兼容别名；worker 启动不自动应用产品更新。

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 凭据；Windows Desktop publication 需要代码签名证书 secret。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 冷启动、/healthz、/chat 和 hashed Web asset 成功。
3. GUI、Research、Wiki Functions 全部注册；Channels、Search、Playwright Chromium、GPA detector 与 Research PDF 支持的 import/asset probe 成功。
4. 验证已安装 distributions 不含 PyTorch、torchvision、OpenCV、EasyOCR、sentence-transformers、triton 或 NVIDIA/CUDA 项。
5. 生成 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 注册、Playwright Chromium、GPA detector 和 Research PDF probes；GUI perception overlay 不得由首次使用隐式安装。
4. Electron 启动的 Python 路径与 capability manifest hash 必须来自内嵌 runtime archive。

本地完整打包先由 electron-builder 对 Electron 组件执行 ad-hoc 签名，补全组件资源签名；随后使用固定本地证书签署 OpenProgram 主 App 与 runtime helper，并执行严格的递归签名校验。构建模式不得因为无需发布证书而跳过组件签名。完整 App 构建、严格签名验证、运行时检查、固定路径安装和默认 worker 刷新均已验证。

10.2.1 本地固定 App 替换

1. 连续执行两次本地桌面构建后，Applications 中只存在 OpenProgram.app，不存在带版本号、commit、任务名或 before 后缀的 App。
2. 两个 worktree 或安装器并发执行时，只有一个进程进入目标 App 事务；另一个在修改 App 或服务前失败，不产生嵌套 App，成功日志版本与最终安装版本一致。
3. 损坏的新 bundle、复制失败或激活失败不得删除可用旧 App；成功替换后不得保留旧 bundle 或构建 bundle。
4. 构建与 staging 路径中的 App 从不执行 open，最终启动命令只接受固定安装路径。
5. 安装版的 bundle identifier、版本、主 executable、ICNS 和内嵌 runtime 验证通过；bundle、runtime manifest、openprogram --version 与内置 Python distribution metadata 必须报告同一版本；Launch Services 只需注册固定安装路径。
6. 版本为 X 的 checkout 对版本 Y 的固定 App 执行源码刷新时，仅 X=Y 允许继续；X<Y 和 X>Y 均要求完整 App 构建。版本低于当前 App 的完整候选也必须在停止 App 和 worker 前被拒绝。

10.2.2 Windows 签名 EXE

1. 原生 Windows runner 使用与 CLI installer 相同的完整 runtime ZIP，并从 win-unpacked 验证 runtime manifest、内置 Python、worker health 与 Web chat。
2. OpenProgram.exe 和 NSIS installer 的 Authenticode 状态必须为 Valid；没有签名凭证时 release 直接失败。
3. Terminal 的 Windows PowerShell 与 Claude preset 通过 ConPTY 启动；Chrome、Edge、Brave 与 Chromium profile discovery 通过 Windows 路径测试。
4. Updater 只选择精确 x64 EXE，size/hash/签名任何一项失败都删除临时文件并禁止打开。

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 / 服务端

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

10.6 发布

发布说明先列出用户可见的变化，提供按平台和架构组织的下载表并直接链接已发布产物，将升级说明与开发者恢复细节分开。安装命令保留在可复制代码块中。仅修正文档的发布说明变更同步修改规范说明与公开发布正文，不移动标签或替换产物。

1. tag、runtime archive、Electron package、manifest 和 health endpoint 报告相同版本。
2. GitHub Release 包含 macOS runtime archives 与 unsigned DMG/ZIP、Linux runtime archives、Windows runtime ZIP 与 signed Desktop EXE、checksums 和 capability manifest；不包含未通过门禁的 Linux 桌面包或 unsigned Windows Desktop。
3. 公开 GitHub Release 的标题与正文统一使用英文；workflow 在发布前拒绝包含中日韩文字的 release notes。
4. 普通用户文档、站点索引和产品运行时错误不出现 pip install openprogram、PyPI 产品下载入口、缺省 optional Program 或组件补装步骤；缺失内置依赖时要求重新安装完整产品。
5. 已发布 tag 不允许移动；修复使用更高 patch version。

实施记录：任务拆分、RED/GREEN、审查和 gate 记录位于 安装与分发实施计划。该记录不改变本文的概念边界。

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 或调试工具作为普通用户产品依赖。

相关设计：单端口 worker 与前端；自更新。安装与分发的冲突内容以本文为准，并在相关设计中引用本文。