codex-ringside 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.3.0 (2026-11-03)
+
+- Replace the native sidebar usage icon with Ringside meters in place, preserving its usage menu, management actions and keyboard controls. Restore the native icon when the add-on is removed.
+- Show plan, credit balance (including zero/unlimited), reset times and reset cards in the hover details. Clear all account-specific values on expiry, disconnection and account changes.
+- Preserve the original background-settings action on ring click, Enter and Space, including interception of the native pointerdown menu. Keep the native usage menu under a separate hover-details action and ArrowDown; right-click and Shift+F10 still open background settings.
+- Add Chromium interaction coverage for native replacement, remounting, cleanup, menu actions, background settings and stale/credit-only states.
+
+## 0.2.0 (2026-10-31)
+
+- Automatically check stable GitHub releases every six hours, verify and install newer standalone bundles, and retry failures after one hour. Preserve settings, back up and roll back failed updates without closing the desktop client.
+- Add `update`, `update --check`, `update --enable`, `update --disable` and update diagnostics in `status`; serialize updates with installation/uninstallation and cancel stale downloads.
+- Add a one-command macOS 13+ installer that verifies release checksums and selects native Apple Silicon or Intel bundles, including when Terminal runs under Rosetta.
+- Ship private Node 22.23.4 and precompiled Swift helpers so users do not need Node, Homebrew or Xcode Command Line Tools. LaunchAgents and the installed CLI use the private Node.
+- Preserve settings, migration backups and transactional rollback across standalone upgrades; uninstall removes the private runtime too.
+- Build/check standalone bundles on both macOS architectures in CI, publish both archives and the installer with checksums, and update English/Chinese installation and release documentation.
+
 ## 0.1.1
 
 - Add copyable English and Chinese AI installation prompts to the README, covering prerequisites, installation, existing settings and status verification.

package/README.md

@@ -4,7 +4,9 @@ English · [简体中文](README.zh-CN.md)
 
 Usage rings and customizable backgrounds for the Codex desktop sidebar on macOS.
 
-See your remaining allowance at a glance, hover for reset times, and click a ring to configure a wallpaper, image or glass background. Image controls include cropping, positioning, zoom, blur and color adjustments.
+Rings replace the native sidebar usage icon in place. Hover for your plan, remaining allowance, credit balance, reset times and reset cards; click to open the original background settings and configure a wallpaper, image or glass background. Image controls include cropping, positioning, zoom, blur and color adjustments. The hover details' usage-menu button preserves the native menu and its management actions.
+
+Credit balances are grouped and rounded to whole credits, including zero; unlimited balances are labeled explicitly, and missing balances are omitted. Credit-only accounts show a balance summary instead of a percentage ring. Account changes, connection failures and data older than 150 seconds clear old account values. On older clients without a compatible usage button, a separate ring opens background settings on click. Removing the add-on restores the native icon.
 
 **Unofficial community add-on. Not affiliated with or endorsed by OpenAI.** Parts are adapted from [Codex Usage Card](https://github.com/Lorie7813/codex-usage-card); see [NOTICE](NOTICE).
 
@@ -12,78 +14,97 @@ See your remaining allowance at a glance, hover for reset times, and click a rin
 
 ## Install
 
-Requirements: macOS, Node.js 22+, Xcode Command Line Tools (`xcode-select --install`), and a signed-in compatible desktop client. The development host is `/Applications/ChatGPT.app`, version `26.1027.30824`, on Apple Silicon. Other host versions depend on compatible internal interfaces and are not individually verified. The CLI and settings panel currently use Chinese labels.
+One-command installation requires **macOS 13+** (Apple Silicon or Intel) and a signed-in compatible desktop client. **You do not need Node.js, npm, Homebrew or Xcode Command Line Tools.** The release includes a private Node runtime and a precompiled helper. The development host is `/Applications/ChatGPT.app`, version `26.1027.30824`; other host versions depend on compatible internal interfaces. CLI and panel labels currently use Chinese.
 
-### Option 1: Ask an AI assistant
+### Option 1: One-command install (recommended)
 
-Copy the prompt below into an AI assistant that can run commands on your Mac. The assistant can check prerequisites, install Ringside and verify the result. Complete any macOS authorization or host sign-in prompts yourself when needed.
+Paste into Terminal:
 
-```text
-Please install Codex Ringside on my Mac: https://github.com/tccpc/codex-ringside
+```bash
+curl -fsSL https://github.com/tccpc/codex-ringside/releases/latest/download/install.sh | /bin/bash
+```
+
+Available starting with release **0.2.0**. The script selects your native architecture (including Apple Silicon terminals running under Rosetta), downloads a release bundle over HTTPS, checks its SHA-256, and installs under your user account. It does not use or change your system Node, shell configuration or Homebrew installation; no `sudo` is required. The background task also uses the private runtime. Installation leaves an already-open desktop session running.
 
-Read the repository's README first and briefly explain what will be installed, including the local debug port.
-Check macOS, Node.js 22+, Xcode Command Line Tools and a compatible signed-in desktop client.
-If this is not macOS, explain that it is unsupported and stop.
-Help resolve missing prerequisites, and tell me when a system dialog needs my input.
+If rings do not appear, save your work, quit the desktop app with ⌘Q, and reopen its original icon. The add-on may reopen a freshly launched client once, subject to the safeguards below.
 
-Install from the official npm registry:
-npx --yes --registry=https://registry.npmjs.org/ codex-ringside@latest install
+Observe mode disables that startup handoff:
 
-Preserve existing Ringside or Codex Plus settings.
-If the compatible desktop app is outside the default location, use CODEX_RINGSIDE_APP to specify the detected path.
+```bash
+curl -fsSL https://github.com/tccpc/codex-ringside/releases/latest/download/install.sh | /bin/bash -s -- --observe
+```
 
-After installation, run:
-npx --yes --registry=https://registry.npmjs.org/ codex-ringside@latest status
+To inspect the installer before running it, download `install.sh` from [Releases](https://github.com/tccpc/codex-ringside/releases), read it, then run `/bin/bash install.sh`. Use `--version 0.2.0` to select an exact release. To set a custom host path, export it before running the one-command installer:
 
-Report whether the background agent is running and the usage ring is placed, then give me the uninstall command.
-If the ring is not visible yet, explain the status and tell me to save my work and reopen the client manually.
-Do not close or force-quit the client I am using.
+```bash
+export CODEX_RINGSIDE_APP="/Applications/ChatGPT.app"
 ```
 
-### Option 2: Install from the terminal
+After installation, status and uninstall work without npm:
 
 ```bash
-npx codex-ringside@latest install
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" status
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" uninstall
 ```
 
-If rings do not appear, save your work, quit the desktop app with ⌘Q, and reopen its original icon. The add-on may reopen a freshly launched client once, subject to the safeguards below.
+### Option 2: Ask an AI assistant
 
-Observe mode installs the agent without allowing it to restart the desktop client:
+Copy this prompt into an assistant that can run commands on your Mac:
+
+```text
+Please install Codex Ringside on my Mac: https://github.com/tccpc/codex-ringside
+Read the README and explain what will be installed, including the local debug port.
+Check macOS 13+ and a compatible signed-in desktop client. If unsupported, stop.
+Use the README's one-command installer. It bundles Node and the helper; do not install Homebrew, Node or Xcode tools for this task.
+Preserve existing settings. If the app is outside the default location, export CODEX_RINGSIDE_APP with its detected path.
+After installation, run "$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" status.
+Report whether the agent is running and the ring is placed, and give the uninstall command.
+If needed, ask me to save my work and reopen the client manually. Do not close or force-quit it.
+```
+
+### Option 3: npm / source installation
+
+For developers who already have **Node.js 22+ and Xcode Command Line Tools**:
 
 ```bash
-npx codex-ringside@latest install --observe
+npx codex-ringside@latest install
 ```
 
-You can also use `npm install -g codex-ringside`, then `codex-ringside install`. Downloading the npm package alone never installs or starts the agent: there are no install lifecycle hooks. No `sudo` is needed with npx.
+This path compiles the Swift helper locally. It requires a working system Node; if `npx` crashes with a missing Homebrew dynamic library, use Option 1. Downloading the npm package alone never installs or starts the agent: there are no install lifecycle hooks. npm users can continue using `npx codex-ringside@latest <command>` for status, background settings and uninstall.
 
 | Location | Contents |
 | --- | --- |
-| `~/Library/Application Support/CodexRingside` | Runtime, locally compiled bridge, settings and state |
+| `~/Library/Application Support/CodexRingside` | Program, private Node and its license (one-command install), helper, settings and state |
 | `~/Library/LaunchAgents/com.codexringside.agent.plist` | Background agent |
 | `~/Library/Logs/CodexRingside` | Agent logs |
 | `~/Library/Application Support/CodexRingside Backups` | Local installation/migration backups |
 
-The installed runtime is independent of the checkout. For a custom application path:
+Host resolution order: `CODEX_RINGSIDE_APP`, legacy `CODEX_PLUS_APP`, saved path, then `/Applications/ChatGPT.app`.
 
-```bash
-CODEX_RINGSIDE_APP="/Applications/ChatGPT.app" npx codex-ringside@latest install
-```
+## Upgrade and migrate from Codex Plus
 
-Resolution order: `CODEX_RINGSIDE_APP`, legacy `CODEX_PLUS_APP`, saved path, then `/Applications/ChatGPT.app`.
+**Automatic updates are enabled by default.** About one minute after the agent starts, it checks the latest stable GitHub Release, then checks every six hours. Check times survive restarts. A newer release is downloaded for the running architecture, verified against its SHA-256 manifest, checked for the expected version/runtime, and installed with its private Node. Drafts, prereleases and downgrades are skipped. Failed checks or installations retry after one hour.
 
-## Upgrade and migrate from Codex Plus
+An independent update job restarts only the Ringside agent, leaving the desktop session open. The app path, observe mode, background, images and update preference are preserved. Files are backed up before replacement; if the new watcher fails to become ready, the installer restores previous files, runtime and service state. Uninstalling, reinstalling or disabling updates during a download cancels that automatic installation. A lock prevents overlapping installation, update replacement and uninstall operations.
 
-Run `npx codex-ringside@latest install` again. Existing Ringside settings take precedence. First migration preserves the old application path, observe mode, background settings and images, then retires `com.codexplus.agent`.
+```bash
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" update
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" update --check
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" update --disable
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" update --enable
+```
+
+These commands update immediately, check only, disable or enable automatic updates. `status` includes an `update` object with the installed/latest versions, preference, check times and last error; timestamps are Unix milliseconds. Update logs are in `~/Library/Logs/CodexRingside/update.log` and `update.err.log`. A version-pinned install still follows future stable releases; disable automatic updates to keep a pinned version or source changes.
 
-The helper is compiled in a staging directory before services are stopped. Files are backed up before replacement; if the new watcher fails to become ready, the installer restores previous files and service state. A lock prevents overlapping install/uninstall operations. Installation itself does not restart an existing desktop session.
+Older versions need one manual reinstall to receive this feature. Existing Ringside settings take precedence over Codex Plus settings; first migration preserves the old settings and retires `com.codexplus.agent`.
 
 Backups remain in `CodexRingside Backups/install-*`. `receipt.json` records original paths and service states; `0` contains the previous Ringside installation and `1` the previous Codex Plus installation. Backups can contain private paths and images. Keep them local and remove them manually when satisfied with the upgrade. Uninstall preserves backups.
 
-Reinstalling preserves observe mode; `install --observe` explicitly disables startup handoff. To re-enable it, unload the agent, set `allowClientRestart` to `true` in the installed `settings.json`, then run `install` again.
+Reinstalling preserves observe mode; `--observe` explicitly disables startup handoff. To re-enable it, unload the agent, set `allowClientRestart` to `true` in the installed `settings.json`, then reinstall. npm/source users can use `npx codex-ringside@latest update`; a successful update switches the managed installation to the standalone bundle with private Node, without changing the source checkout. `npx codex-ringside@latest install` continues to require development tools.
 
 ## Background controls
 
-Click a ring to open settings. Panel changes apply immediately; CLI changes apply within five seconds.
+Click a ring, or press Enter or Space while focused, to open background settings. The hover details' background settings button, right-click and Shift+F10 also work. Open the native usage menu through the separate button in the hover details or ArrowDown while the ring is focused; this entry is hidden on clients without a compatible native usage button. Panel changes apply immediately; CLI changes apply within five seconds.
 
 | Source | Behavior |
 | --- | --- |
@@ -97,10 +118,10 @@ Transparency and blur control the effect. Images support cover, contain, stretch
 The appearance switch uses the host's own system/light/dark setting and synchronizes with its settings page. It is hidden when compatible internal functions cannot be found.
 
 ```bash
-npx codex-ringside@latest background image ~/Pictures/photo.jpg --transparency 50 --blur 8
-npx codex-ringside@latest background --layout contain --zoom 120 --y 20
-npx codex-ringside@latest background --crop 10,0,80,60
-npx codex-ringside@latest background default
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" background image ~/Pictures/photo.jpg --transparency 50 --blur 8
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" background --layout contain --zoom 120 --y 20
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" background --crop 10,0,80,60
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" background default
 ```
 
 Options without a source keep the current source. `background` without arguments prints the saved configuration. Crop values are left, top, width and height in percentages; `--crop none` clears the crop. `--help` lists flags and `--version` prints the version; both work without an installed host.
@@ -113,15 +134,29 @@ Options without a source keep the current source. `background` without arguments
 - Background cleanup uses host DOM heuristics. Terminals, code blocks, canvases and embedded web content are left alone; an unfamiliar page may retain opaque areas.
 - Host updates can break rate-limit reading, placement or theme integration. Disable the background or uninstall if problems arise.
 
+### Recommended wallpaper sites
+
+Find a background image on these sites:
+
+| Site | Highlights |
+| --- | --- |
+| [Wallhaven](https://wallhaven.cc/) | A broad wallpaper collection with keyword, resolution and aspect-ratio filters |
+| [WallpaperHub](https://www.wallpaperhub.app/) | Windows, Surface and Fluent Design wallpapers in sizes for different devices |
+| [Peapix](https://peapix.com/) | Bing daily wallpapers and Windows Spotlight images, including landscapes, architecture and nature photography |
+| [Unsplash](https://unsplash.com/wallpapers) | HD photography wallpapers covering nature, travel, animals and more |
+| [Pexels](https://www.pexels.com/search/desktop%20wallpaper/) | A photography library with desktop, 4K and dark wallpaper categories |
+
+Download an image to your Mac, click a sidebar ring, then choose the `image` source and select the file. You can also set it as your macOS desktop wallpaper and choose the `wallpaper` source to align the background with your desktop.
+
 ## Status and troubleshooting
 
 ```bash
-npx codex-ringside@latest status
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" status
 ```
 
-Look for `agent: "running"`, `cdp.windows[].card.placed`, and `cdp.windows[].background.applied`. `nativeGlass: false` means the host disables native glass. `startup.event` explains skipped handoffs. Status may contain private paths and window URLs; redact it before sharing.
+Look for `agent: "running"`, `cdp.windows[].card.placed`, and `cdp.windows[].background.applied`. `card.replacesNative` confirms replacement of the native usage icon; `card.credits` and `card.plan` show current allowance details. `nativeGlass: false` means the host disables native glass. `startup.event` explains skipped handoffs. Status may contain private paths and window URLs; redact it before sharing.
 
-If no ring appears, verify the signed-in host, application path, Node version, Command Line Tools and whether port 39222 is occupied. Installing while the host is open does not trigger a restart. Save your work and reopen its original icon when convenient. Check `~/Library/Logs/CodexRingside` for errors.
+If no ring appears, verify the signed-in host, application path and whether port 39222 is occupied. Node and Command Line Tools checks apply only to npm/source installations. A missing release asset means that version does not contain a standalone bundle; use 0.2.0 or later. A checksum or download failure stops before changing the installed app; retry when the network is available. Installing while the host is open does not trigger a restart. Save your work and reopen its original icon when convenient. Check `~/Library/Logs/CodexRingside` for errors.
 
 Missing or expired allowance data is shown as unavailable. Account switches reset the app-server connection. The number of rings follows the valid allowance windows returned for your account.
 
@@ -134,10 +169,10 @@ An app already running when the agent starts is never handed off. Only normal sy
 ## Uninstall
 
 ```bash
-npx codex-ringside@latest uninstall
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" uninstall
 ```
 
-This removes current and legacy agents, moves runtime/settings/logs to the Trash and removes injected UI. Backups remain. The desktop application bundle is unchanged. The debug port remains active until that desktop process exits; the next ordinary launch has no Ringside debug flag.
+This removes current and legacy agents and the update job, moves the private Node runtime and program/settings/logs to the Trash and removes injected UI. Backups remain. The desktop application bundle is unchanged. The debug port remains active until that desktop process exits; the next ordinary launch has no Ringside debug flag.
 
 ## Security and privacy
 
@@ -145,7 +180,7 @@ Ringside starts the host's bundled `codex app-server`, reads `account/rateLimits
 
 **The debug endpoint has no authentication.** Local software can execute JavaScript in the desktop renderer through it. Never expose, forward or proxy port 39222. Use this add-on only where you trust the other local software.
 
-Ringside does not read project files, chat content or the conversation database, and has no telemetry. It checks only the modification time of `auth.json`. The host CLI makes its own network requests. Wallpaper and chosen image processing is local; images/configuration are not uploaded. See [SECURITY.md](SECURITY.md).
+Ringside does not read project files, chat content or the conversation database, and has no telemetry. It checks only the modification time of `auth.json`. The host CLI makes its own network requests. Automatic updates request the public GitHub release API and assets without account tokens or local settings, paths or images; `update --disable` stops automatic requests. Wallpaper and chosen image processing is local; images/configuration are not uploaded. See [SECURITY.md](SECURITY.md).
 
 ## Development
 
@@ -156,7 +191,7 @@ npm ci --ignore-scripts
 npm run verify
 ```
 
-Verification runs syntax checks, unit tests and tests the actual packed CLI and Swift source. There are no runtime npm dependencies. CI covers Node.js 22/24/26 and compiles on Apple Silicon and Intel macOS. Full host compatibility requires a real signed-in client.
+Development requires Node.js 22+ and Xcode Command Line Tools. Verification runs syntax checks, unit tests and tests the actual packed CLI and Swift source. `npm run build:standalone` builds a native release bundle; `npm run check:standalone` tests its real runtime, helper, installation and rollback with simulated services and unusable system development tools. There are no runtime npm dependencies. CI covers Node.js 22/24/26 and compiles on Apple Silicon and Intel macOS. Full host compatibility requires a real signed-in client.
 
 For the browser-only fixture, run `python3 -m http.server 4173 --bind 127.0.0.1` from the checkout and open `http://127.0.0.1:4173/test/fixtures/card.html`. It uses simulated data and gradient images.
 

package/README.zh-CN.md

@@ -4,94 +4,116 @@
 
 ![背景设置](https://raw.githubusercontent.com/tccpc/codex-ringside/main/docs/images/background-settings.png)
 
-在 Codex 桌面端的侧栏显示剩余额度圆环，悬停可看重置时间；点击圆环可以自定义 Codex 的背景：图片、壁纸或毛玻璃，透明度和模糊自由调节，图片还能裁剪、缩放和调整布局。仅支持 macOS。
+用剩余额度圆环替换 Codex 桌面端侧栏的官方用量图标，悬停可看套餐、余额和重置时间，点击圆环打开原有背景设置。可以自定义图片、壁纸或毛玻璃，透明度和模糊自由调节，图片还能裁剪、缩放和调整布局。悬停详情中的“用量菜单”保留官方“管理用量”等操作。仅支持 macOS。
 
 这是非官方插件，与 OpenAI 无关。原理参考 [Codex Usage Card](https://github.com/Lorie7813/codex-usage-card)，署名见 [NOTICE](NOTICE)。
 
 ## 工作原理
 
 - **额度**：启动 Codex 内置的 `codex app-server`，通过 stdio 调用 `account/rateLimits/read`，每 60 秒刷新一次。
-- **显示**：通过本机调试端口 `127.0.0.1:39222` 把卡片注入到 `nav[data-app-navigation-rail]`。
+- **显示**：通过本机调试端口 `127.0.0.1:39222` 在侧栏官方用量按钮内替换图标，保留原生菜单、键盘操作和“管理用量”等账号功能。找不到兼容的官方按钮时，回退为独立圆环；卸载会恢复原图标。
 - **背景**：同样通过调试端口，把 Codex 外壳层的背景清空，在页面最底层放一张图片。窗口属性由主进程控制，插件改不了，所以“透明”透出的是 Codex 自带的系统毛玻璃，壁纸来源显示的是对齐到屏幕位置的桌面壁纸。
 - **启动**：Codex 的 `app.asar` 受完整性校验保护，不能修改，只能让它带调试端口启动。后台任务发现你从原图标打开 Codex 时，会在安全条件都满足的情况下有序退出，再带端口重开一次。
 
 账号有几个额度窗口就显示几个圆环。圆环是分段刻度样式，环内显示剩余百分比和窗口名称（“5小时”或“周”）。额度充足时为青绿渐变，50% 及以下转为黄橙，低于 10% 转为橙红。
 
-## 安装
+悬停详情显示套餐、各窗口的剩余百分比及重置时间、可用重置卡，以及接口提供的额度余额。余额按整数分组显示，例如 `12,346`；零余额显示 `0`，无限额度显示“不限额”，未返回余额时不猜测数值。只有余额、没有百分比窗口时，侧栏显示余额摘要。连接失败、数据超过 150 秒未更新或账号切换时，会清除旧数值并提示重试。重置、购买和管理操作继续由官方菜单处理。
 
-需要 macOS、Node.js 22+ 和 Xcode Command Line Tools（`xcode-select --install`），以及已登录的兼容桌面客户端。开发与真机验证使用 `/Applications/ChatGPT.app`，版本 `26.1027.30824`。其他客户端版本依赖相同内部结构，未逐一验证。
+## 安装
 
-### 方式一：让 AI 帮你安装
+一键安装需要 **macOS 13 或更高版本**（Apple Silicon 或 Intel），以及已登录的兼容桌面客户端。**无需自行安装 Node.js、npm、Homebrew 或 Xcode Command Line Tools。** 安装包自带专用 Node 和预编译 helper。开发验证使用 `/Applications/ChatGPT.app`，版本 `26.1027.30824`；其他客户端版本依赖相同内部结构，未逐一验证。命令行和设置面板目前使用中文。
 
-把下面整段提示词复制给能在你的 Mac 上运行终端命令的 AI 助手，让它完成环境检查、安装和结果验证。遇到 macOS 授权弹窗或客户端登录时，由你本人完成操作。
+### 方式一：一键安装（推荐）
 
-```text
-请帮我在这台 Mac 上安装 Codex Ringside，项目地址：https://github.com/tccpc/codex-ringside
+在终端粘贴这一条命令：
 
-先阅读仓库的 README，简要说明安装内容和本机调试端口的用途。
-检查 macOS、Node.js 22+、Xcode Command Line Tools，以及已登录的兼容桌面客户端。
-如果不是 macOS，请说明不支持并停止安装。
-缺少依赖时协助补齐，需要我处理系统弹窗时再提示我。
+```bash
+curl -fsSL https://github.com/tccpc/codex-ringside/releases/latest/download/install.sh | /bin/bash
+```
 
-从官方 npm 源安装：
-npx --yes --registry=https://registry.npmjs.org/ codex-ringside@latest install
+从 **0.2.0** 版本开始提供。脚本自动识别芯片架构（包括 Rosetta 下的终端），通过 HTTPS 下载对应安装包，校验 SHA-256 后安装到当前用户目录。安装和后台运行均使用插件自带的 Node，不依赖或更改系统 Node、Homebrew、终端配置，也不需要 `sudo`。安装过程不会关闭正在使用的客户端。
 
-保留已有的 Ringside 或 Codex Plus 设置；
-如果兼容桌面应用不在默认位置，用 CODEX_RINGSIDE_APP 指定检测到的应用路径。
+如果圆环还没出现，保存工作，用 ⌘Q 退出客户端，再点原图标打开。后台可能在符合下文条件时将刚启动的客户端重开一次。
 
-安装后运行：
-npx --yes --registry=https://registry.npmjs.org/ codex-ringside@latest status
+只观察、不自动重开客户端：
 
-告诉我后台是否正常运行、侧栏圆环是否已显示，并给出卸载命令。
-圆环尚未显示时，解释当前状态，提醒我保存工作后手动重开客户端；
-不要主动关闭或强制结束我正在使用的客户端。
+```bash
+curl -fsSL https://github.com/tccpc/codex-ringside/releases/latest/download/install.sh | /bin/bash -s -- --observe
 ```
 
-### 方式二：终端安装
+想先审阅脚本，可以从 [Releases](https://github.com/tccpc/codex-ringside/releases) 下载 `install.sh`，阅读后执行 `/bin/bash install.sh`。加上 `--version 0.2.0` 可指定发行版本。应用不在默认位置时，先设置路径，再执行一键安装命令：
 
-以下命令显式安装后台任务；仅下载 npm 包不会安装或启动后台。命令行和设置面板目前使用中文。
+```bash
+export CODEX_RINGSIDE_APP="/Applications/ChatGPT.app"
+```
+
+安装后查看状态和卸载也不需要 npm：
 
 ```bash
-npx codex-ringside@latest install
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" status
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" uninstall
+```
+
+### 方式二：让 AI 帮你安装
+
+把下面整段提示词复制给能在你的 Mac 上运行命令的 AI 助手：
+
+```text
+请帮我在这台 Mac 上安装 Codex Ringside：https://github.com/tccpc/codex-ringside
+先阅读 README，说明安装内容和本机调试端口的用途。
+检查 macOS 13+ 和已登录的兼容客户端，不支持时停止。
+使用 README 的一键安装入口；安装包自带 Node 和 helper，不要为此安装 Homebrew、Node 或 Xcode 命令行工具。
+保留已有设置；应用不在默认位置时，先 export CODEX_RINGSIDE_APP 为检测到的路径。
+安装后运行："$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" status
+告诉我后台是否正常、圆环是否显示，并给出卸载命令。
+需要重开客户端时提醒我保存工作后手动操作，不要主动关闭或强制结束客户端。
 ```
 
-然后保存工作，用 ⌘Q 退出 Codex，再点原图标打开。
+### 方式三：npm / 源码安装
 
-只想看后台会做什么、不重启 Codex：
+适用于已有 **Node.js 22+ 和 Xcode Command Line Tools** 的开发者：
 
 ```bash
-npx codex-ringside@latest install --observe
+npx codex-ringside@latest install
 ```
 
-安装内容：
+此方式在本机编译 Swift helper，需要本机 Node 能正常运行。如果 `npx` 因 Homebrew 动态库缺失崩溃，直接使用方式一。仅下载 npm 包不会安装或启动后台；没有安装生命周期脚本。npm 用户仍可使用 `npx codex-ringside@latest <命令>` 查看状态、设置背景和卸载。
 
 | 位置 | 内容 |
 |---|---|
-| `~/Library/Application Support/CodexRingside` | 程序、`bridge`、设置和状态 |
+| `~/Library/Application Support/CodexRingside` | 程序、专用 Node 及许可证（一键安装）、helper、设置和状态 |
 | `~/Library/LaunchAgents/com.codexringside.agent.plist` | 后台任务 |
 | `~/Library/Logs/CodexRingside` | 日志 |
+| `~/Library/Application Support/CodexRingside Backups` | 安装和迁移备份 |
 
-运行时不依赖这个仓库，改代码后要重新 `install`。
+应用路径按 `CODEX_RINGSIDE_APP`、旧变量 `CODEX_PLUS_APP`、保存的应用路径、默认 `/Applications/ChatGPT.app` 的顺序选择。
 
 ## 升级和从 Codex Plus 迁移
 
-升级时重新运行 `npx codex-ringside@latest install`。已有新版设置优先；首次迁移保留旧版应用路径、观察模式、背景设置和图片，并停用 `com.codexplus.agent`。先暂存编译、备份，再切换后台；新后台未就绪时恢复原文件和运行状态。
-
-备份保留在 `~/Library/Application Support/CodexRingside Backups/install-*`。`receipt.json` 记录原路径及后台运行状态，`0` 是原 Ringside 安装，`1` 是原 Codex Plus 安装。卸载不会删除备份，确认新版正常后可手动清理。
+从本版起，**自动更新默认开启**。后台启动约一分钟后检查 GitHub 的最新正式发行版，之后每 6 小时检查一次；检查时间会保存，重启后台不会重复下载。发现更高版本后，自动下载对应架构的完整安装包，校验 SHA-256、版本及运行时，再升级程序和专用 Node。跳过草稿和预发行版，不会降级。网络或安装失败会记录原因，一小时后重试。
 
-迁移和重装保留观察模式；`install --observe` 可明确关闭自动接管。要重新开启，退出后台后将安装目录 `settings.json` 的 `allowClientRestart` 改为 `true`，再运行 `install`。备份包含本地路径及图片，不要上传。
+更新由独立任务执行，只重启插件后台，不关闭正在使用的客户端。现有应用路径、观察模式、背景、图片和自动更新开关都会保留；新后台未就绪时恢复原文件、运行时和运行状态。下载期间卸载、重新安装或关闭自动更新，会取消这次自动安装。
 
-非默认应用路径：
+也可以立即更新、只检查或控制自动更新：
 
 ```bash
-CODEX_RINGSIDE_APP="/Applications/ChatGPT.app" npx codex-ringside@latest install
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" update
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" update --check
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" update --disable
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" update --enable
 ```
 
-新环境变量优先于旧变量 `CODEX_PLUS_APP`，然后使用保存的应用路径，最后使用默认 `/Applications/ChatGPT.app`。
+`status` 的 `update` 字段显示当前/最新版本、自动更新开关、检查时间、下次检查时间和失败原因；时间字段为 Unix 毫秒时间戳。更新日志在 `~/Library/Logs/CodexRingside/update.log` 和 `update.err.log`。指定版本安装后仍会跟随正式版；需要固定版本或保留源码改动时，运行 `update --disable`。
+
+旧版用户先重新执行一次一键安装命令，获得自动更新功能。已有新版设置优先；首次从 Codex Plus 迁移会保留旧版设置，并停用 `com.codexplus.agent`。安装、更新切换和卸载共用互斥锁，不会互相覆盖。
+
+备份保留在 `~/Library/Application Support/CodexRingside Backups/install-*`。`receipt.json` 记录原路径及后台运行状态，`0` 是原 Ringside 安装，`1` 是原 Codex Plus 安装。卸载不会删除备份，确认新版正常后可手动清理。
+
+迁移和重装保留观察模式；`--observe` 可明确关闭自动接管。要重新开启，退出后台后将安装目录 `settings.json` 的 `allowClientRestart` 改为 `true`，再重新安装。备份包含本地路径及图片，不要上传。npm / 源码用户可用 `npx codex-ringside@latest update` 执行相同更新；更新成功后，已安装副本转为包含专用 Node 的独立安装，不修改源码工作区。继续用 `npx codex-ringside@latest install` 则仍需开发工具。
 
 ## 自定义背景
 
-点击侧栏的圆环打开设置面板。先选来源，再用效果调外观，所有调节都立即生效。
+直接点击侧栏圆环打开原有背景设置面板，聚焦后按 Enter 或空格也可以打开。悬停面板中的“背景设置”、右键和 Shift+F10 仍可使用。官方用量菜单通过悬停面板中的“用量菜单”打开，也可以聚焦圆环后按向下键；没有兼容的官方按钮时，这个菜单入口隐藏。先选来源，再用效果调外观，所有调节都立即生效。
 
 面板顶部还能切换 Codex 的**外观模式**：跟随系统、浅色、深色。它和设置页的“模式”是同一个设置，改动会保存，并在两边同步。这里用的是 Codex 内部的设置函数，找不到时控件自动隐藏。
 
@@ -118,22 +140,22 @@ CODEX_RINGSIDE_APP="/Applications/ChatGPT.app" npx codex-ringside@latest install
 也可以用命令行设置，5 秒内生效：
 
 ```bash
-npx codex-ringside@latest background image ~/Pictures/photo.jpg --transparency 50 --blur 8
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" background image ~/Pictures/photo.jpg --transparency 50 --blur 8
 ```
 
 ```bash
-npx codex-ringside@latest background --layout contain --zoom 120 --y 20
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" background --layout contain --zoom 120 --y 20
 ```
 
 ```bash
-npx codex-ringside@latest background --crop 10,0,80,60
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" background --crop 10,0,80,60
 ```
 
 ```bash
-npx codex-ringside@latest background default
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" background default
 ```
 
-只写选项时保留当前来源，不带参数时打印当前设置。`--crop` 的四个数是左、上、宽、高的百分比，`--crop none` 取消裁剪。完整选项见不带参数运行 `npx codex-ringside@latest` 的用法提示。
+只写选项时保留当前来源，不带参数时打印当前设置。`--crop` 的四个数是左、上、宽、高的百分比，`--crop none` 取消裁剪。完整选项见不带参数运行安装目录内的 `bin/codex-ringside` 的用法提示。
 
 使用限制：
 
@@ -143,21 +165,37 @@ npx codex-ringside@latest background default
 - **切换有延迟**：切换桌面空间后，壁纸最多 60 秒才更新；拖动窗口时壁纸有轻微跟随延迟。
 - **页面自动适配**：内容区里方角、无边框、占满区域的不透明层会被当作页面背景清除，设置页这类圆角卡片变成半透明磨砂，文字依然清楚。终端、代码块和内嵌网页不处理。设计不同的页面可能漏掉，这时自带背景的地方保持原样。
 
+### 壁纸网站推荐
+
+可以从这些网站挑选背景图片：
+
+| 网站 | 推荐内容 |
+|---|---|
+| [Wallhaven](https://wallhaven.cc/) | 综合壁纸图库，可按关键词、分辨率和宽高比筛选 |
+| [WallpaperHub](https://www.wallpaperhub.app/) | Windows、Surface 和 Fluent Design 风格壁纸，提供多种设备尺寸 |
+| [Peapix](https://peapix.com/) | Bing 每日壁纸与 Windows Spotlight 图片，适合寻找风景、建筑和自然摄影 |
+| [Unsplash](https://unsplash.com/wallpapers) | 摄影类高清壁纸，涵盖自然、旅行、动物等主题 |
+| [Pexels](https://www.pexels.com/search/desktop%20wallpaper/) | 摄影图库，提供桌面、4K 和深色壁纸等分类 |
+
+下载图片到本机后，点击侧栏圆环，在背景设置面板中选择 `image` 图片来源并选取文件。也可以先将图片设为 macOS 桌面壁纸，再选择 `wallpaper` 壁纸来源，让背景与桌面对齐。
+
 ## 查看状态
 
+下载失败或 SHA-256 校验失败时，安装器会在更改现有安装前停止，可在网络恢复后重试。发行版缺少安装包时，请选择 0.2.0 或更高版本。通过一键入口安装后，无需检查系统 Node 或编译工具。
+
 ```bash
-npx codex-ringside@latest status
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" status
 ```
 
-重点看 `cdp.windows[].card.placed`。背景看 `background`（保存的设置）和 `cdp.windows[].background`：`applied` 表示已生效，`nativeGlass` 为 `false` 表示 Codex 此刻关闭了毛玻璃。输出可能包含本机路径，分享前请先脱敏。
+重点看 `cdp.windows[].card.placed`，`replacesNative` 为 `true` 表示已替换官方用量图标；`credits` 和 `plan` 显示当前余额和套餐。背景看 `background`（保存的设置）和 `cdp.windows[].background`：`applied` 表示已生效，`nativeGlass` 为 `false` 表示 Codex 此刻关闭了毛玻璃。输出可能包含本机路径，分享前请先脱敏。
 
 ## 卸载
 
 ```bash
-npx codex-ringside@latest uninstall
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" uninstall
 ```
 
-新旧后台任务会被移除，程序、设置和日志进废纸篓，安装备份保留。当前窗口的注入界面会移除；调试端口会保持到客户端退出，下次正常启动后关闭。桌面应用文件未改动。
+新旧后台任务和自动更新任务会被移除，专用 Node 随程序一起卸载，程序、设置和日志进废纸篓，安装备份保留。当前窗口的注入界面会移除；调试端口会保持到客户端退出，下次正常启动后关闭。桌面应用文件未改动。
 
 ## 什么时候会重启 Codex
 
@@ -180,15 +218,19 @@ npx codex-ringside@latest uninstall
 
 ## 隐私
 
-只读取额度数据，不读项目文件、对话内容和 Codex 数据库，也没有任何上报。`auth.json` 只看修改时间，用来发现账号切换，不读内容。app-server 自身的网络请求由 Codex CLI 发出。背景功能只读取系统壁纸和你选的图片，转换后存在本机的 `CodexRingside/background` 目录，不会上传。
+只读取额度数据，不读项目文件、对话内容和 Codex 数据库，也没有遥测或数据上传。`auth.json` 只看修改时间，用来发现账号切换，不读内容。app-server 自身的网络请求由 Codex CLI 发出。自动更新会请求 GitHub 的公开发行接口并下载发行包，不使用账号令牌，不发送本机设置、路径或图片；可以用 `update --disable` 关闭自动请求。背景功能只读取系统壁纸和你选的图片，转换后存在本机的 `CodexRingside/background` 目录，不会上传。
 
 ## 开发
 
+开发和源码构建仍需要 Node.js 22+ 与 Xcode Command Line Tools。一键安装的普通用户不需要这些工具。
+
 ```bash
 npm ci --ignore-scripts
 npm run verify
 ```
 
+`npm run build:standalone` 构建本机架构的完整安装包，`npm run check:standalone` 使用包内真实 Node 和 helper，在系统开发工具不可用的隔离环境下验证安装、重装和回滚。CI 分别在 Apple Silicon 与 Intel 上运行此检查。
+
 卡片样式可以用 `test/fixtures/card.html` 调试，不需要真实的 Codex。
 
 完整开发和发布流程见 [贡献指南](CONTRIBUTING.md)、[发布指南](docs/RELEASING.md)；漏洞请通过 [私密安全报告](https://github.com/tccpc/codex-ringside/security/advisories/new) 提交。

package/bin/codex-ringside.cjs

@@ -7,6 +7,7 @@ const { BackgroundStore, parseBackgroundArgs } = require('../src/background.cjs'
 const { CDP_PORT, CdpSession, isMainWindow, listTargets } = require('../src/cdp.cjs');
 const launchd = require('../src/launchd.cjs');
 const installer = require('../src/install.cjs');
+const updater = require('../src/update.cjs');
 const { version } = require('../package.json');
 
 const { installDir } = launchd.paths;
@@ -28,6 +29,7 @@ async function install({ observe }) {
     ? '如果圆环还没出现：保存工作后用 ⌘Q 退出 Codex，再点原图标打开。'
     : '当前为观察模式：不会重启 Codex。');
   console.log(`原安装备份：${result.backup}`);
+  console.log(result.settings.autoUpdate ? '自动更新已开启，每 6 小时检查正式发行版。' : '自动更新已关闭。');
 }
 
 // Reachable only if Codex is running with the port; without it there is no card to remove.
@@ -86,6 +88,7 @@ async function status() {
   console.log(JSON.stringify({
     agent: job ? job.match(/state = (\S+)/)?.[1] ?? 'loaded' : 'not installed',
     settings: readJson(settingsFile),
+    update: fs.existsSync(settingsFile) ? updater.updateStatus(installDir) : null,
     background: new BackgroundStore({ root: installDir }).config,
     startup: state && { event: state.event, updatedAt: new Date(state.updatedAt).toISOString() },
     listenAddresses: listeners(),
@@ -105,6 +108,23 @@ async function background(args) {
   console.log(`背景来源：${config.source}，5 秒内生效。`);
 }
 
+async function update(args) {
+  if (args.length > 1 || args.some(arg => !['--check', '--enable', '--disable'].includes(arg))) {
+    throw Error('用法：codex-ringside update [--check | --enable | --disable]');
+  }
+  if (args[0] === '--enable' || args[0] === '--disable') {
+    const enabled = args[0] === '--enable';
+    await updater.setAutoUpdate(enabled);
+    console.log(enabled ? '自动更新已开启，后台将在一分钟内检查。' : '自动更新已关闭。');
+    return;
+  }
+  console.log('正在检查 GitHub 正式发行版…');
+  const result = await updater.runUpdate({ checkOnly: args[0] === '--check' });
+  if (result.status === 'updated') console.log(`已更新到 ${result.installedVersion}，后台已重启。`);
+  else if (result.status === 'available') console.log(`发现新版本 ${result.latestVersion}。`);
+  else console.log('当前没有更新的正式版本。');
+}
+
 async function main() {
   const [command, ...args] = process.argv.slice(2);
   if (command === '--version' || command === '-v') { console.log(version); return; }
@@ -116,8 +136,10 @@ async function main() {
   else if (command === 'uninstall') await uninstall();
   else if (command === 'status') await status();
   else if (command === 'background') await background(args);
+  else if (command === 'update') await update(args);
   else {
-    console.log('用法：codex-ringside <install [--observe] | uninstall | status | background [来源] [选项]>');
+    console.log('用法：codex-ringside <install [--observe] | uninstall | status | update [选项] | background [来源] [选项]>');
+    console.log('更新选项：--check 仅检查 | --enable 开启自动更新 | --disable 关闭自动更新；无选项立即更新');
     console.log('背景来源：default | image <图片路径> | wallpaper | glass');
     console.log('背景效果：--transparency <0-100> --blur <0-60>');
     console.log('图片调整：--layout <cover|contain|stretch|center|tile> --zoom <10-400> --x <0-100> --y <0-100>');

package/native/bridge.swift

@@ -155,6 +155,10 @@ func wallpaper() -> [String: Any] {
 }
 
 let args = CommandLine.arguments
+if args.count == 2 && args[1] == "version" {
+    emit(["protocol": 1])
+    exit(0)
+}
 guard args.count >= 3 else { fail("usage: bridge <command> <app> [...]") }
 let command = args[1]
 let appPath = canonical(args[2])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-ringside",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Usage rings and customizable backgrounds for the Codex desktop app. Unofficial macOS add-on.",
   "license": "MIT",
   "type": "commonjs",
@@ -15,12 +15,15 @@
   ],
   "scripts": {
     "test": "node --test test/*.test.cjs",
+    "test:card": "node --test test/card.browser.cjs",
     "install-agent": "node bin/codex-ringside.cjs install",
     "uninstall-agent": "node bin/codex-ringside.cjs uninstall",
     "status": "node bin/codex-ringside.cjs status",
     "check": "node scripts/check.cjs",
     "check:package": "node scripts/check-package.cjs",
-    "verify": "npm run check && npm test && npm run check:package"
+    "verify": "npm run check && npm test && npm run check:package",
+    "build:standalone": "node scripts/build-standalone.cjs",
+    "check:standalone": "node scripts/check-standalone.cjs"
   },
   "repository": {
     "type": "git",
@@ -51,5 +54,8 @@
     "LICENSE",
     "NOTICE",
     "CHANGELOG.md"
-  ]
+  ],
+  "devDependencies": {
+    "playwright": "1.64.1"
+  }
 }