feat(plugins): ship prebuilt macOS installers

.gitattributes

@@ -0,0 +1,3 @@
+
+# Keep executable macOS installers usable after Windows checkouts.
+*.command text eol=lf

.github/workflows/opengui-codex-ci.yml

@@ -43,7 +43,10 @@ jobs:
         run: pnpm check
       - name: Produce the allowlisted upload and archive
         working-directory: ${{ runner.temp }}/opengui
-        run: pnpm package
+        run: |
+          pnpm package
+          bash -n scripts/install-macos.command
+          node scripts/test-installer.mjs
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
         with:
           name: opengui-codex-${{ matrix.os }}

.github/workflows/opengui-codex-release.yml

@@ -65,8 +65,9 @@ jobs:
           version="${GITHUB_REF_NAME#opengui-codex-v}"
           archive="opengui-codex-$version.tar.gz"
           upload="opengui-codex-$version.zip"
-          test "$(find release-assets -maxdepth 1 -type f | wc -l | tr -d ' ')" = 4
-          (cd release-assets && sha256sum -c "$archive.sha256" && sha256sum -c "$upload.sha256")
+          installer="opengui-codex-$version-install.command"
+          test "$(find release-assets -maxdepth 1 -type f | wc -l | tr -d ' ')" = 6
+          (cd release-assets && sha256sum -c "$archive.sha256" && sha256sum -c "$upload.sha256" && sha256sum -c "$installer.sha256")
           tar -xOf "release-assets/$archive" opengui/docs/release-notes.md > "$RUNNER_TEMP/notes.md"
           if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
             test "$(gh release view "$GITHUB_REF_NAME" --json isDraft --jq .isDraft)" = true
@@ -76,6 +77,8 @@ jobs:
           fi
           gh release upload "$GITHUB_REF_NAME" \
             "release-assets/$archive" "release-assets/$archive.sha256" \
-            "release-assets/$upload" "release-assets/$upload.sha256" --clobber
-          # Keep the release draft until real-device acceptance is recorded.
+            "release-assets/$upload" "release-assets/$upload.sha256" \
+            "release-assets/$installer" "release-assets/$installer.sha256" --clobber
+          # Stable publication requires real-device acceptance.
+          # The maintainer may explicitly publish this draft as a testing prerelease.
           # Directory submission, approval, and publication are separate manual gates.

.github/workflows/workbuddy-plugin-ci.yml

@@ -48,6 +48,8 @@ jobs:
           cache-dependency-path: workbuddy-plugin/package-lock.json
       - run: npm ci
       - run: npm run pack:release
+      - run: node scripts/test-publish.mjs
+      - run: node scripts/test-release-installer.mjs
       - run: npm run test:native
       - uses: actions/upload-artifact@v4
         with:

.github/workflows/workbuddy-plugin-release.yml

@@ -1,6 +1,12 @@
 name: WorkBuddy Plugin Release
 
 on:
+  workflow_dispatch:
+    inputs:
+      prerelease:
+        description: Publish for public testing (stable requires real-device acceptance)
+        type: boolean
+        default: true
   push:
     tags:
       - 'opengui-workbuddy-v*'
@@ -16,6 +22,8 @@ jobs:
   release:
     runs-on: macos-latest
     timeout-minutes: 20
+    env:
+      OPENGUI_PRERELEASE: ${{ github.event_name == 'push' || inputs.prerelease }}
     defaults:
       run:
         working-directory: workbuddy-plugin
@@ -33,7 +41,8 @@ jobs:
       - run: npm ci
       - run: npm run pack:release
       - run: npm run smoke:packed
-      - name: Require real WorkBuddy acceptance
+      - name: Require real WorkBuddy acceptance for stable publication
+        if: env.OPENGUI_PRERELEASE != 'true'
         run: node scripts/validate.mjs --release
       - name: Publish immutable WorkBuddy assets
         env:

docs/plans/simple-plugin-install.md

@@ -0,0 +1,25 @@
+# Codex / WorkBuddy 简化安装方案
+
+目标：macOS 用户下载对应宿主的安装脚本并运行一次，自动取得固定版本预构建包、校验 SHA-256、准备私有 Node、安装并给出首次使用指引。普通安装不需要源码、Git、pnpm、编译器或测试工具。
+
+每个插件维护自己的安装脚本和发布资产；不共享运行时、配置、版本或设备服务。沿用 DSH 已验证的机制：版本化包、HTTPS 下载、校验、独立目录、配置备份。保留现有发布验收，不把候选产物声称为正式发布。
+
+流程：GitHub Release -> 对应宿主安装脚本 -> 私有版本目录 -> 宿主原生插件安装 / WorkBuddy 配置合并。
+
+- Codex：使用独立 opengui-standalone 来源，保持仓库旧 marketplace 不变；拒绝同时安装其他来源的同名插件。通过 codex plugin 命令注册、安装和核验，保留配置备份。沿用已固定的 Node 22.23.2 和独立缓存。
+- WorkBuddy：先检查宿主退出，再使用私有 Node/npm 安装校验过的 tgz（禁用安装脚本），从包内运行既有配置安装器，统一处理 MCP、Skill 和 Hooks。保留新旧包目录和回退日志。
+- 发布：为两种插件新增带版本的安装脚本及校验文件；CI 同时验证脚本、归档和安装行为。正式发布仍要求原有人工验收证据。
+- 开发验收：支持显式本地 archive + SHA-256 文件，不需要先发布；测试使用临时 HOME / CODEX_HOME，不操作真实手机和生产宿主配置。
+
+新增公开入口仅为两种宿主各一个安装脚本，参数 --archive 用于本地候选验证，--help 展示说明。下载版本来自脚本所属版本，避免解析全仓 Latest 错装 DSH。没有发布资产就退出，不自动回落源码编译。新版本下载对应脚本，旧版本脚本用于回退。
+
+验证：成功安装、坏校验、无发布、同名插件冲突、配置保留、重复安装、带空格目录、安装失败和回退；运行双方完整 check/package 和 WorkBuddy packed smoke。最脆弱前提是宿主原生安装接口和 macOS 下载执行权限；以实际临时配置安装核实前者，桌面首次运行和手机验收单独记录。需要公共 GitHub、nodejs.org、npm 网络，无新增账户/API key。不增加常驻服务。
+
+涉及超过八个文件；源码和发布流程作为一个可审阅变更交付。回滚通过恢复对应宿主配置备份并重新安装旧版本实现，不删除用户数据、不修改 DSH、不自动强停手机任务。
+
+## 实现验证命令
+
+- `plugins/opengui`: `pnpm check`、`pnpm package`、`node scripts/test-installer.mjs`。
+- `workbuddy-plugin`: `npm run pack:release`、`npm run smoke:packed`、使用官方 Node 发行包执行 `node scripts/test-release-installer.mjs`（该测试需要发行包内的 npm）。
+- 安装 Skill：Skill Creator 的 `quick_validate.py skills/opengui-plugin-install`。
+- macOS 人工安装验收：使用临时 HOME / CODEX_HOME 和真实 Codex CLI 验证首装、重复安装；WorkBuddy 使用空 HOME 和不含 Node 的 PATH 验证私有运行时下载及三个配置入口。宿主桌面和真实手机验收仍沿用原发布清单。

plugins/opengui/README.md

@@ -1,12 +1,42 @@
 # OpenGUI for Codex
 
 Standalone screenshot-guided Android control for **local Codex on macOS arm64/x64**.
-This is a candidate package, not a published or directory-approved release.
+This is a testing candidate, not a stable or directory-approved release.
 
 It includes a control Skill, local CLI/daemon, macOS ADB executable, and a read-only
 device wall. It does not depend on, modify, install, update, or reload DSH.
 See [source provenance](SOURCE.md) and [privacy](docs/privacy.md).
 
+## Install on macOS
+
+Once a release is published, download `opengui-codex-<version>-install.command`
+and its `.sha256` from that same [Codex release](https://github.com/Core-Mate/OpenGUI/releases).
+Verify the checksum in the download directory, then run `bash <downloaded-installer>`.
+The installer downloads the matching prebuilt package, checks it, prepares private Node,
+and registers the standalone plugin using the native `codex plugin` commands.
+No Git, pnpm, source build, or Xcode is required; Codex CLI with plugin support is required.
+Start a **new chat**, choose OpenGUI, and ask to list connected phones without operating them.
+
+For agent-assisted installation, use the repository's
+[installation Skill](../../skills/opengui-plugin-install/SKILL.md) and say
+“Install OpenGUI for Codex”. The Skill resolves only complete releases for this host.
+Public testing downloads are marked prerelease; stable publication requires the release gates below.
+
+The installer uses the independent `opengui-standalone` marketplace and leaves the
+repository's legacy marketplace unchanged. Finish OpenGUI tasks before upgrading.
+A same-name plugin from another source is reported instead of silently replaced.
+Packages and recovery inventories are retained under `~/.codex/opengui-codex/packages`
+(or the selected `CODEX_HOME`). On failure, inspect the printed recovery directory;
+source rollback is attempted through Codex commands, without resetting other settings.
+
+Maintainers can test an unpublished archive without installing build tools on the test Mac:
+
+```sh
+bash scripts/install-macos.command --archive /absolute/path/opengui-codex-0.1.0.tar.gz
+```
+
+The adjacent `.sha256` file is required. Build and package once on the maintainer machine.
+
 ## Development and verification
 
 Run commands from this directory:
@@ -28,8 +58,8 @@ On macOS, `node scripts/smoke-archive.mjs <plugin.tar.gz> <node-darwin.tar.gz>`
 verifies a packaged launcher using the checksum-pinned Node 22.23.2 archive in a
 temporary private cache. It does not connect to ADB or install into a Codex profile.
 
-For local Codex installation, stage this package into a separate disposable
-marketplace using Plugin Creator. Do not install both the legacy and standalone
+For development-only manual staging, use a separate disposable marketplace with Plugin Creator.
+The release installer above creates its own standalone source automatically. Do not install both the legacy and standalone
 `opengui` plugins into the same test task. Installing into your normal Codex
 profile or submitting to the public directory requires a separate user decision.
 
@@ -99,3 +129,6 @@ Mac setup, actual Android tasks on one and two devices, both architectures, fina
 downloaded archive checksums, public policy URLs, and publisher identity. GitHub
 artifact creation is not OpenAI approval. Do not announce publication until the
 approved version has actually been published.
+
+Public testing releases are explicitly marked prerelease on GitHub. Publishing a testing
+prerelease does not complete desktop/device acceptance or authorize stable/directory publication.

plugins/opengui/README.zh-CN.md

@@ -9,9 +9,35 @@
 - 发送、发布、购买、删除需要对话确认和原生单次确认。
 - 取消/关闭清理会话截图；空闲会话 30 分钟过期，空闲守护进程 5 分钟退出。
 
+## 普通用户安装
+
+正式发布后，从对应 [Codex Release](https://github.com/Core-Mate/OpenGUI/releases) 下载
+`opengui-codex-版本-install.command` 及其 `.sha256`，在下载目录校验后运行：
+
+```sh
+shasum -a 256 -c opengui-codex-0.1.0-install.command.sha256
+bash opengui-codex-0.1.0-install.command
+```
+
+安装器自动下载并校验预构建包、准备私有 Node、注册独立插件来源。需要带插件管理功能的
+Codex CLI，不需要 Git、pnpm、Xcode 或源码构建。完成后新开对话，选择 OpenGUI，先说
+“列出已连接手机，不操作手机”。USB 授权仍需在手机上批准。
+
+也可让 Agent 使用仓库的 [安装 Skill](../../skills/opengui-plugin-install/SKILL.md)，
+说“帮我安装 OpenGUI Codex 插件”。它会自动查找匹配的正式版本并校验安装文件。
+当前尚未正式发布；没有完整 Release 时会明确停止，不会偷偷转为源码构建。
+
+升级前结束旧任务。同名插件冲突会提示，不会自动移除。旧包和配置备份保存在
+`~/.codex/opengui-codex/packages`，使用 `CODEX_HOME` 时跟随该目录。回退可运行旧版本安装器。
+
+维护者测试候选包：`bash scripts/install-macos.command --archive /绝对路径/opengui-codex-0.1.0.tar.gz`，
+同目录需有归档的 `.sha256` 文件。
+
+## 开发者构建
+
 开发时在本目录运行 `pnpm install --frozen-lockfile --ignore-scripts`、
 `pnpm check` 和 `pnpm package`。打包产物位于 `.artifacts/`。
-原仓库 marketplace 保持原样，测试安装必须使用独立临时来源。
+原仓库 marketplace 保持原样，安装器自动使用独立来源，不要求用户自行搭建 marketplace。
 
 会话操作使用宿主提供的 `CODEX_THREAD_ID` 绑定当前任务，缺少该身份时拒绝执行。
 会话列表仅返回当前任务的会话；设备墙令牌也按会话隔离。此机制防止任务间误操作，

plugins/opengui/docs/release-notes.md

@@ -1,15 +1,11 @@
 # OpenGUI for Codex 0.1.0
 
-Initial standalone candidate, independent of the production DSH plugin.
-
-- Local macOS Android control and a read-only multi-device wall.
-- Frozen device selection, one-action screenshot freshness, and operation limits.
-- Observe-only sessions, session discovery, cancellation, idle expiry, and private
-  screenshot cleanup.
-- Verified first-use Node runtime setup and pinned scrcpy Unicode input.
-- Native confirmation for classified send/publish/purchase/delete actions.
-- Separate package, dependencies, build, tests, and release version line.
-
-Automated verification, real-device acceptance, GitHub release, directory review,
-and public publication are distinct gates. This document does not claim that any
-of the latter gates have completed.
+Public testing prerelease for local Codex on macOS arm64/x64.
+
+- Install the prebuilt plugin with a host-specific installer that downloads and verifies private Node, with no source build or Xcode.
+- Control authorized Android devices from screenshots, or view a read-only device wall.
+- Keep existing plugin settings and previous packages, with explicit conflict checks and source recovery during upgrades.
+
+Download `opengui-codex-0.1.0-install.command` and its `.sha256`, verify the checksum, then run the installer with `bash`. Codex CLI with plugin support is required. Start a new Codex chat after installation and first request read-only device discovery.
+
+This prerelease is for testing. Automated tests and isolated installer checks have passed locally; desktop, real-phone and two-device acceptance remain incomplete. It is not a stable or directory-approved release.