安装与分发实施计划#

本工程记录与权威 HTML 设计刻意分开，记录当前分发工作的限定实施范围、验证和审查证据。

正式发布的更新架构、实现状态、验证证据和发布可见验收统一维护在 docs/reference/design/distribution/automatic-updates.html，不在这份历史分发台账中重复。

移除通过 Python 包安装产品的入口#

• 产品合同：普通用户安装完整的 GitHub Release 产物；pip install openprogram、pipx install openprogram、uv tool install openprogram 和 PyPI 项目页都不是受支持的产品入口。
• 公开界面：站点首页、引导与故障排查页、示例和运行时依赖错误均指向正式安装器或完整重装，不要求用户修改 Python 包。
• 保留开发边界：发布运行时组装、源码开发、测试，以及明确由开发者管理的第三方扩展环境，仍可在内部构建或安装 wheel。
• 公开入口 RED：分发合同扫描公开文档和产品修复提示中的 Python 包安装说明，同时保留运行时构建器仍使用已验证 wheel 的断言。
• RED 证据：两个针对性用例均失败：公开界面仍宣传 Python 包安装，打包后的 openprogram browser install 仍调用 Python 安装器。
• GREEN 证据：两个针对性用例均通过。受影响的分发、Browser、Channels、Providers、OAuth、配置、PDF 和 embedding 测试共 1,330 项通过、5 项跳过、1 项预期失败；正式发布测试 21 项通过。文档构建 529 页，落地页检查通过，链接验证为零死链。
• 排除项：不重写为无 Python 产品，不删除 pyproject.toml，不改变插件或第三方 Program 格式，不修改远端 PyPI。
• 9e50cebc 的规格审查要求修改：六处第一方 PDF Agentic Function 错误仍建议 pip install pymupdf，而公开界面回归排除了整个 Agentic Functions 目录树。
• 修复：这些内建错误改为指引用户完整重装；回归扫描将第一方 Agentic Functions 与其他产品运行时代码一并纳入。明确由开发者管理的扩展安装器仍排除。
• d9047511 的规格复审通过。剩余 Python 包操作限于发布组装、源码开发、测试和开发者管理的扩展环境。
• d9047511 的质量审查要求修改：OpenClaw 源码集成准备了锁定的 uv 环境，但示例 skill 仍用无关的系统 Python；公开内建 PDF 能力依赖 pypdf，完整运行时却既未安装也未验证它。PDF 失败提示缺少必要修复操作，源码故障排查错误暗示 checkout 安装器会改变 shell 的活动 Python。此外，缺少 Node 或 apps/cli/dist 的受管运行时会在现有 Rich 终端回退之前退出，违反发布合同的终端 UI 要求。
• 修复：OpenClaw skill 改用克隆 checkout 的 uv run --project，回归覆盖中英文说明。pypdf 成为锁定的基础依赖；运行时验证器导入它，并用生成的 PDF 执行两条内建提取路径。缺少 PDF 依赖时提示完整重装；故障排查区分受管私有运行时与 uv run 或 .venv 源码开发。Ink 启动失败进入内置 Rich REPL；rich 成为直接锁定依赖，并增加运行时渲染探测和回退回归。
• 8c6b2f0c 的最终限定审查：规格和质量均通过。分发、正式发布、Browser 和结构化输出覆盖共 123 项通过；包含独立运行覆盖的发布审查 120 项通过；真实 PDF 样例 6 项通过。文档构建 529 页、落地页验证通过、零死链。更广泛的不带额外依赖测试在 793 项通过后因开发环境缺少 Playwright 停止；该失败用例在发布运行时的 --extra all --extra search 配置下通过。
• 状态：完成。

本地 App 版本一致性#

• 公开边界：scripts/refresh-local-app.sh 仅刷新 bundle、运行时 manifest、Python 分发元数据、Python 源码版本和 Desktop 源码版本全部一致的已安装 App。apps/desktop/scripts/install-app.sh 在获取锁前拒绝低于当前规范 App 的候选版本；在锁内复制并验证候选，再于停止 worker 或修改文件系统前比较不可变暂存版本与已安装 App。数字版本段使用十进制任意精度比较。现有规范路径若未通过 bundle、manifest 或嵌入元数据验证，必须保留并拒绝操作，不能当作不存在。同版本刷新将 Desktop updater 实现复制到重建的 App archive，核对 wheel 元数据，然后重新获取安装目标锁，在修改 worker 或 App 前再次核对源码、wheel 和已安装 App。
• RED：公开安装器接受用 0.6.1 候选覆盖已安装 0.6.2 App；发布版本入口不识别已安装 App 与源码匹配请求。
• GREEN：两个公开入口用例均通过。真实刷新命令在创建构建产物前拒绝用 0.6.6 checkout 刷新当时的 0.6.1 App；App 文件和健康 worker 保持不变。
• 受影响检查：正式发布与分发测试 74 项通过；发布版本、Ruff、shell 语法和 diff 检查通过。
• 排除项：无降级覆盖选项、预发布排序、新版本来源、用户状态迁移、Windows 包或远端发布修改。
• 状态：实现已提交；独立规格审查待完成。

本地规范 App 与 Apple 图标批次#

• 基线提交：9477273e。
• 公开入口：npm --prefix apps/desktop run dist 构建并验证一个完整的临时 OpenProgram.app，只替换 /Applications/OpenProgram.app。
• 图标合同：apps/desktop/build/AppIcon.icon 是 Apple 分层设计源，其四个 1024 x 1024 SVG 图层不预先裁剪系统轮廓，并保留已批准的细胞与三个扁平圆片。受支持的 macOS 15 构建机缺少完整 Xcode actool 流程，因此已审查的 apps/desktop/build/icon.icns 提交为 Electron 打包输入。检查同时验证两个资产、全部旧格式表示及安装后的系统轮廓；已删除的手绘外形 SVG 不得恢复。
• 事务合同：激活失败不得删除旧 App 唯一可恢复副本。真实 launchd 卸载失败在修改 App 前停止；已经卸载的过期 plist 可替换。Launch Services 注册后的失败恢复并重新注册旧规范 App，且不覆盖最初安装错误。组装后的 App 在安装前通过现有完整打包运行时冒烟检查。
• 并发合同：跨 worktree 打包共用一个稳定的用户级锁；安装在目标 Applications 目录使用覆盖完整事务的原子锁。竞争安装器在 App 或服务修改前失败，不能创建嵌套 bundle。
• 清理边界：打包清理随机 App 目录、暂存运行时、Python wheel 构建、生成的 Web 构建/输出、复制的 Web 前端和锁。不删除已安装 App 数据、源码、包依赖或用户状态。
• 生产文件：apps/desktop/build/AppIcon.icon、apps/desktop/build/icon.icns、apps/desktop/scripts/check-icon.sh、apps/desktop/scripts/package-and-install-app.sh、apps/desktop/scripts/install-app.sh 和 openprogram/worker/services/launchd.py。
• 验收：图标检查要求 1024 x 1024 源、透明角、824 x 824 不透明主体边界、与 macOS 内建 App 对齐的 256 px 栅格轮廓和实心区域、十种旧格式表示，以及 ICNS 往返验证。事务故障注入保留 previous.app；launchd 测试覆盖已加载、过期和卸载失败状态；损坏的组装运行时在安装前拒绝。运行时验证器还要求已安装 OpenProgram 包元数据等于 manifest 版本。审查后用一次真实 npm run dist 替换已安装 App，刷新 Launch Services，并检查 Finder/Launchpad 显示。
• 排除项：无 Developer ID 签名、公证、Windows 包、新图标依赖、第二份安装 App 或图像生成模型。
• 检查清单：针对性分发测试、Desktop 检查、图标生成与往返、打包运行时冒烟、文档构建/链接、Ruff、shell 语法、diff、独立规格审查及新的独立质量审查。
• 安装验收（2026-08-16）：一次完整 npm run dist 通过运行时和打包 App 冒烟后，原子替换 /Applications/OpenProgram.app。已安装 bundle 版本为 0.6.6、标识为 ai.openprogram.desktop；运行时 manifest、CLI 和 Python 分发元数据均为 0.6.6，ICNS SHA-256 与生成的源资产一致。默认 worker 使用 bundle 的 CPython 3.12.10，/healthz 为 ok。Launch Services 返回规范 0.6.6 App，Launchpad 数据库包含其应用项，Dock 可见图标大小和圆角轮廓与相邻 macOS App 一致。
• 清理验收：仅保留 /Applications/OpenProgram.app；安装后随机打包目录、暂存运行时、Python wheel 构建、Web .next/out 和复制的前端均不存在。
• 状态：已实现、独立审查、安装并通过可视验收。

v0.6.1 发布检查修复#

• 实现移至 openprogram/channels/implementations/ 后，删除四个无引用旧 Channel 模块；运行时 HTTP 清单仅扫描活动 Channel 代码。
• 将 Research writer 被丢弃的 context 参数改名为运行时支持的 project_context。
• 将 Browser Agent 明确记录为延后的内部工具循环，不改变其行为。
• 本地验收：原四个失败测试通过；受影响测试 461 项通过；完整非集成测试 5274 项通过、11 项跳过、1 项预期失败。Desktop、Web、发布脚本、运行时 HTTP、Ruff 和文档检查通过。
• 此修复早于原生 Windows 产物。当前 Windows 发布路径见 Windows 支持。

原生发布结果与 v0.6.2 修正#

• v0.6.1 在发布运行 31820999574 解析完整 macOS x86_64 运行时失败后保持不可变；该标签未发布 GitHub Release。
• 根因：semble 0.2.0 将 tree-sitter-language-pack 约束为低于 1.8，锁定的 1.6.2 没有 macOS x86_64 wheel。
• 修正：要求 semble>=0.5.3，其语法依赖改为 semble-grammars；锁定语法包提供 macOS x86_64/arm64 与 Linux x86_64/arm64 原生 wheel，并保留搜索能力。
• 回归检查：为 macOS x86_64 上 CPython 3.12 解析完整锁定产品依赖，并断言锁定语法产物覆盖该平台。发布重试使用更高补丁版本 v0.6.2。
• v0.6.2 在运行 31822787529 通过搜索依赖步骤、但发现 torch 2.13.0 不再提供 macOS x86_64 wheel 后保持不可变；该标签未发布 GitHub Release。
• v0.6.3 重试使用上游最后兼容 macOS x86_64 的 torch 2.2.2 和 torchvision 0.17.2，搭配 numpy 1.26.4 维持 NumPy ABI 兼容。四个发布目标必须解析同一 GUI 依赖组合；Linux 继续使用官方 CPU wheel 索引。
• v0.6.3 在运行 31823941178 发现未约束的 GUI harness 安装经当前 OpenCV 依赖把 NumPy 升回 2.x、破坏 Torch 2.2.2 NumPy ABI 后保持不可变；该标签未发布 GitHub Release。
• v0.6.4 重试固定 opencv-python 4.11.0.86，并对所有第一方 Program 安装应用同一约束文件，防止后续解析替换已验证的 NumPy、OpenCV、Torch 或 Torchvision。
• v0.6.4 在运行 31824996497 构建并安装四个完整运行时、但暴露 Intel macOS Desktop 架构名称不一致后保持不可变：发布 archive 使用 x86_64，electron-builder 接受 x64。该标签未发布 GitHub Release。
• v0.6.5 保留运行时产物名称，将 Intel Desktop 构建参数映射为 x64；发布 workflow 回归强制两个 macOS 架构的显式映射。
• v0.6.5 在运行 31827207974 构建两个 macOS Desktop 产物、但暴露冒烟脚本仅能解析紧凑 JSON 而 manifest 为格式化 JSON 后保持不可变。四个完整运行时和 CLI 安装器任务均通过；该标签未发布 GitHub Release。
• v0.6.6 重试采用运行时归档和 Desktop 准备已有的空白容错 manifest 解析器，提供可操作错误，并增加格式化 manifest 回归。

v0.6.6 正式发布验收#

• v0.6.6 指向 d08486953e19cf168fd8aba0704fe968b2a7f3a8；发布运行 31829278086 成功完成，未移动任何旧标签。
• 稳定 GitHub Release 在 https://github.com/fzkuji-neo/OpenProgram/releases/tag/v0.6.6 发布，非草稿、非预发布。包含四个完整运行时 archive 及校验和、未签名 macOS arm64/x64 DMG 与 ZIP 及校验和、开发者 wheel/sdist 和 release-manifest.json。
• macOS arm64/x86_64 与 Linux arm64/x86_64 原生验收通过。每个运行时在原生 runner 上组装归档；四个 CLI 安装器任务均验证校验和、解压、完整产品能力、worker 冷启动、原子激活和启动器版本。两个 macOS Desktop 任务在上传前验证相同嵌入运行时。
• main CI 31828655714 通过 Python 3.11/3.12/3.13、Web 和文档/示例任务；文档发布 31828655717 也通过。
• 发布后公开入口验收将 https://openprogram.io/install 经 GitHub latest 解析到 v0.6.6，把 macOS arm64 archive 安装到隔离状态和启动器目录，返回 openprogram 0.6.6，通过安装器完整运行时、/healthz 和 openprogram doctor 检查。

v0.7.0 浏览器发布验收#

• v0.7.0 解析到 c7f5916b2b3acb67b936081763945ee080f81b9a；在 main CI 31973024049 和文档发布 31973024046 成功后一次创建。
• 发布运行 31973458867 成功。四个原生产品运行时、四个 CLI 安装器、两个 macOS Desktop、Python 分发及最终发布任务均通过。
• 稳定 OpenProgram 0.7.0 Release 非草稿、非预发布。该验收点 GitHub latest 为 v0.7.0。17 个资产包含四个运行时及校验和、arm64/x64 未签名 DMG 与 ZIP 及校验和清单、开发者 wheel/sdist 和 release-manifest.json。
• 已发布 manifest 版本为 0.7.0；两个 macOS Desktop 架构和四个运行时的字节数及 SHA-256 与 GitHub 资产元数据一致。
• 发布验收使用 CI 包/运行时冒烟和只读发布元数据检查，未安装、替换、激活或重启用户当前 /Applications/OpenProgram.app，所以前台更新器 UI、长期调度与睡眠恢复明确仍未验证。
• 发布范围包括内建 Browser、profile 导入、书签/历史和 Agent 绑定 WebTab 控制。Chrome/Edge 扩展安装刻意排除，已在权威内建浏览器设计及产品 FAQ 说明。

当前 v0.9.8 发布验收#

• 候选整合持久函数代码选择和重启恢复、模块组织及可恢复文件操作。现有本地签名、权限、取消和未知效果边界仍为准。
• 源码、锁文件、Desktop 与安装器版本一致。发布验收要求组合 Python 回归清单、Desktop、文档及独立规格/质量审查。
• 发布要求原生运行时、Desktop 和 CLI 安装器任务成功，再验证 manifest 和资产。
• 公开 macOS 桌面包使用 Developer ID 签名及 Apple 公证。本地刷新和自更新使用本地开发证书，不保留生产签名。
• 运行时能力验证和校验和要求不变。Windows Desktop 发布要求已配置签名凭据。

简短公开安装命令批次#

• 基线提交：c1886a3fdf7ba196c42ec9a2c19dca7fe86c12e7。
• 公开命令：普通 macOS/Linux CLI 和服务端安装使用 curl -fsSL https://openprogram.io/install | sh。
• 边界：根脚本解析最新稳定 GitHub Release，校验三段数字版本，下载不可变标签下的安装器并传入版本。不组装第二套安装器，不削弱运行时校验和、能力 manifest 或 worker 冷启动验证。
• 可复现性：高级用户和 CI 可向 sh 进程传入 OPENPROGRAM_VERSION=X.Y.Z。标签中的 scripts/install-release.sh 保留为公开兼容 URL，并从相同不可变标签下载权威 scripts/release/install-release.sh。
• 发布：docs/_static_root/install.sh 在部署站点根目录重命名为 /install；/docs/install/ 保留为安装文档目录。
• 测试：用模拟 curl 执行公开根脚本，覆盖自动最新版本解析和显式固定，断言标签安装器转交，构建文档并检查组装后的根文件，运行现有分发发布测试。
• RED：两个公开入口测试最初失败，因为根引导脚本不存在且 Pages workflow 未发布 /install。
• GREEN：分发发布文件 25 项通过；文档 509 页；落地页通过；零死链；组装站点探测保留 /docs/install/ 并验证根 /install 脚本。
• 2026-08-15 发布前证据：GitHub latest 最初为 v0.6.0，既无资产，标签也无 scripts/install-release.sh。安装器正确失败而非安装缩水产品。上面的 v0.6.6 正式验收取代这一已观察发布状态。

统一完整产品批次#

• 基线提交：e6ec8694977080153a3c94e50a5080d2ff43b69b。
• 产品合同：每个受支持的非开发安装在对应平台/架构包含相同完整能力。Desktop 使用与 CLI/服务端相同的运行时 archive，只允许 Electron 外层不同。若完整打包入口未通过，不提供该 Desktop 产物，而不是削减能力。
• 必须能力：Web、providers、MCP、memory、channels、search、Playwright Chromium、GPA detector 模型及 GUI、Research、Wiki 第一方 Programs。Research 含 PDF 支持。产品运行时明确排除 PyTorch、torchvision、OpenCV、EasyOCR、sentence-transformers、triton 和 NVIDIA/CUDA 分发包。
• 开发安装增加可编辑源码、测试、诊断、本地前端构建和显式配置的 GUI 感知/OCR/浏览器 overlay。需要被排除感知依赖的路径不是产品 manifest 能力。产品运行时不隐式安装这些依赖；显式 overlay 所需模型资产由其自身配置负责。
• 普通用户从 GitHub Release 安装。PyPI wheel 仅为内部构建输入和开发者产物，不是产品安装路径。
• macOS 产物明确为未签名 DMG/ZIP；Apple Developer ID 签名和公证不是该发布要求。Linux 发布完整 x86_64/arm64 CLI/服务端运行时；完整 AppImage 未通过打包检查后不再发布 Linux Desktop。
• 本批最初没有 Windows 产物。现在相同运行时/Desktop 分离方式生成原生 Windows x64/arm64 运行时、安装器和 Desktop，见 Windows 支持。仍排除 OS 凭据存储集成。

当前批次文件#

• 产品合同：docs/reference/design/distribution/installation-packaging.html 及本记录。
• 运行时组装：已提交产品 manifest、构建/归档脚本、Desktop 运行时暂存及 CLI 发布安装器。
• 启动器：Electron 和 CLI 启动路径设置内置 Playwright Chromium 与 GPA detector 位置并验证能力 manifest。Session/Memory Git 历史使用宿主系统 Git；两个启动器均不捆绑 Git。
• 发布：.github/workflows/release.yml、Desktop 命名、运行时 archive、校验和和公开入口冒烟。
• 产品文档：安装、桌面、服务端、升级、Programs 和 README 入口描述一个完整产品，而非可选第一方组件。
• 测试：tests/unit/test_distribution_release.py 及针对性 Program/运行时与打包入口探测。

当前批次公开入口验收#

1. 每个平台 archive 含 manifest，为 web、providers、mcp、memory、channels、search、browser.playwright、model.gpa_detector、program.gui、program.research、program.wiki 提供 present 和 verified。GUI 用 --no-deps 安装；Research 带 PDF 支持。不安装 PyTorch、torchvision、OpenCV、EasyOCR、sentence-transformers、triton 或 NVIDIA/CUDA 分发包。
2. 受支持 Desktop 打包使用已构建 archive；CLI 安装器使用 GitHub Release 中字节相同的 archive。两者不独立解析产品依赖。
3. 普通安装不进行 PyPI 依赖解析、仓库克隆、npm 构建，或首次使用时下载 Playwright Chromium、GPA detector、第一方 Programs；也不隐式下载被排除的 GUI 感知依赖，相关路径需显式开发或 backend overlay。
4. 发布产物或切换 CLI current 前，公开入口探测验证 worker、Web 资产、第一方 Program 注册、channel/search 导入、Playwright Chromium 可执行文件和 detector 模型。
5. macOS 产物名称和文档注明 unsigned；发布 workflow 不要求 Apple/PyPI 凭据，也不执行签名、公证或 PyPI 发布。
6. 文档不把 pip install openprogram、可选 GUI/Research/Wiki 安装、组件选择提示或未验证 Linux Desktop 包作为普通产品安装方式。

当前批次检查清单#

python -m pytest tests/unit/test_distribution_release.py tests/unit/test_desktop_packaged_files.py tests/unit/test_webui_frontend.py
python -m scripts.docs_site.checklinks
python -m scripts.docs_site.build
python -m pytest tests/ --ignore=tests/integration
npm run check --prefix desktop
npm run check --prefix web
bash -n scripts/release/build-product-runtime.sh scripts/install-release.sh scripts/release/prepare-desktop-runtime.sh
git diff --check
git status --short

平台运行时和公开 Desktop 产物探测在原生发布 runner 上执行。平台产物宁可不提供，也不发布削减能力的 manifest。

当前批次证据#

先前打包批次（历史证据）#

• 基线：717d4e176307e08cc4ae4facd3c484511684746c。
• 公开行为：发布 wheel 无需 Node.js 即提供预构建 Web；打包 Electron 启动嵌入 CPython；macOS 构建 DMG/ZIP，Linux 构建 AppImage；发布 CI 验证版本和校验和。
• 产品文档只描述验收通过的行为。
• 此历史批次未实现 Windows 原生打包；它是延后产品决定，不是拒绝方向。
• 排除 OS 凭据存储集成。

先前批次文件#

• 生产：apps/server/openprogram_server/_webui/frontend.py、pyproject.toml、apps/desktop/main.js、apps/desktop/package.json、发布暂存脚本及 workflow。
• 测试：前端包资源、Desktop 打包运行时及发布配置检查。
• 文档：分发 HTML 设计、相关设计链接，以及安装/升级/桌面/服务端产品页。

先前批次公开入口验收#

1. 发布资产暂存后构建的 wheel 包含 openprogram_server/_webui/_frontend/index.html 和带哈希的 Next.js 资产；隔离安装不依赖仓库源码或 Node.js 即提供 /chat。
2. 打包 Electron 仅从 process.resourcesPath 解析 Python，执行 -I -B -m openprogram worker start，不回退 PATH，不向签名应用写字节码。
3. electron-builder 声明 macOS DMG/ZIP 和 Linux AppImage，将暂存运行时作为不可变资源。
4. 标签触发 workflow 在各平台原生 runner 构建，执行针对性验收，只在产物存在后发布校验和。

先前批次完整检查清单#

python -m pytest tests/component/webui/runtime/test_webui_frontend.py tests/unit/webui/test_desktop_packaged_files.py tests/component/config/test_distribution_release.py
python -m scripts.docs_site.checklinks
python -m scripts.docs_site.build
python -m pytest tests/ --ignore=tests/integration
npm run check --prefix desktop
npm run check --prefix web
git diff --check
git status --short

平台产物在发布 workflow 构建，因为 macOS 不能验证 Linux CPython/AppImage，Linux 不能签名或公证 macOS App。

先前 Linux 完成批次#

• 基线：540591e9f628498dee87a1c2ebb30ab4c5e757f6。
• 生产文件：apps/desktop/package.json、scripts/release/smoke-packaged-runtime.sh、scripts/install-release.sh、.github/workflows/release.yml、.github/workflows/linux-release-smoke.yml。
• 测试文件：tests/unit/test_distribution_release.py。
• Linux x86_64 验收：原生 runner 构建 AppImage，在 Xvfb 下执行公开入口，由 Electron 启动嵌入 worker，验证 /healthz、/chat、不可变 Program 行为及一致的 freedesktop 文件名/StartupWMClass 元数据。
• Linux CLI 验收：原生 x86_64/arm64 runner 用固定 uv 和受管 CPython 安装发布 wheel，切换 current 前冷启动 worker，并验证启动器版本。
• 发布前执行：手动 Linux 冒烟 workflow 无需 Apple/PyPI 凭据，仅上传验证后的 wheel/AppImage 为 CI 资产，不创建稳定发布。
• 此历史批次早于 Windows 实现，没有增加 Linux arm64 Desktop、发行版原生 deb/rpm 或 OS 凭据存储。当前 Windows 发布路径见 Windows 支持。

先前批次台账#

先前 Linux 完成证据#