Skip to content

release-quick-start.md

Latest commit

 

History

History
153 lines (116 loc) · 5.54 KB

release-quick-start.md

File metadata and controls

153 lines (116 loc) · 5.54 KB
Raw

OpenUsage Bar 安装指南 / Install guide

OpenUsage Bar 0.7.1 支持 Apple Silicon Mac 和 macOS 15 或更高版本。

图形化安装（推荐）

  1. 从 v0.7.1 发布页 下载 OpenUsage-Bar-v0.7.1-macos-arm64.dmg。
  2. 双击 DMG，将 OpenUsage Bar 拖入 Applications。
  3. 在访达“应用程序”中打开。App 会自动注册登录项和内置采集器。
  4. 若 macOS 显示“OpenUsage Bar 已损坏”，确认下载来源和 SHA-256 后执行 xattr -dr com.apple.quarantine "/Applications/OpenUsage Bar.app"，再从 “应用程序”打开。不要全局关闭 Gatekeeper。
  5. 若出现后台访问提示，在 系统设置 > 通用 > 登录项允许 OpenUsage Bar。

OpenUsage Bar 是菜单栏工具，不会出现在 Dock 或 Command-Tab。采集器每五分钟刷新。

Install (English)

Download the v0.7.1 DMG, open it, drag OpenUsage Bar to Applications, then open it from Finder. The app registers its login item and bundled collector on first launch. If macOS says the app is damaged, verify the download and run xattr -dr com.apple.quarantine "/Applications/OpenUsage Bar.app" for this app only. Do not disable Gatekeeper system-wide. Allow it under General > Login Items if macOS requests background approval.

可选完整性校验 / Optional checksum

将 DMG 和 .dmg.sha256 放在同一目录后执行：

shasum -a 256 -c OpenUsage-Bar-v0.7.1-macos-arm64.dmg.sha256

高级修复与自动化 / Advanced repair

普通用户不需要执行脚本。ZIP 中仍附带事务式安装、回滚和卸载工具：

shasum -a 256 -c OpenUsage-Bar-v0.7.1-macos-arm64.zip.sha256
unzip OpenUsage-Bar-v0.7.1-macos-arm64.zip
cd OpenUsage-Bar-v0.7.1-macos-arm64
scripts/install_app.sh

安装器优先使用 /Applications，不可写时降级到 ~/Applications。自定义目录：

OPENUSAGE_INSTALL_DIR="$HOME/My Apps" scripts/install_app.sh

GitHub 构建使用 ad-hoc 签名，未进行 Developer ID 公证。不要运行全局关闭 Gatekeeper 的命令。

Every release must use an immutable vX.Y.Z tag whose version and build agree with all three app bundles, the Python helper, and the matching CHANGELOG entry. CI pins third-party Actions to verified full commit SHAs. Developer ID signing and notarization are optional distribution conveniences, not source-release requirements.

Build from source

Install Xcode and Python 3.11 or later, then run:

scripts/bootstrap.sh
scripts/build_app.sh
scripts/install_app.sh

Roll back

Before every upgrade, the installer writes a complete signed-app backup under ~/.local/state/openusage-bar/backups/app. Only the two newest complete, hash-verified backups are retained. To restore the newest one:

scripts/rollback_app.sh

Rollback verifies the backup's bundle identity, version, signature, and full content hash before the atomic swap. It preserves the ledger, provider configuration, and Keychain entries. If the three Local API v1 contract routes do not recover within 20 seconds, the rollback itself is reversed.

Uninstall

scripts/uninstall_app.sh

This preserves the local ledger, configuration, and Keychain items. To remove the local ledger and configuration as well:

scripts/uninstall_app.sh --purge-data

Keychain entries are deliberately not deleted automatically. Remove them in Keychain Access only after confirming that no other local installation uses the same service entries.

Opt-in canary diagnostics

OpenUsage Bar sends no telemetry. A canary tester may explicitly create a redacted aggregate for a GitHub canary report:

Before running any extracted script, verify the downloaded ZIP directly with GitHub CLI. Then the packaged candidate verifier checks the manifest, SBOM, checksums, every release asset and all attestations:

gh attestation verify OpenUsage-Bar-v0.7.1-macos-arm64.zip \
  --repo tttboy123/openusage-bar \
  --signer-workflow tttboy123/openusage-bar/.github/workflows/release.yml \
  --source-ref refs/tags/v0.7.1 \
  --deny-self-hosted-runners
shasum -a 256 -c OpenUsage-Bar-v0.7.1-macos-arm64.zip.sha256
unzip OpenUsage-Bar-v0.7.1-macos-arm64.zip
cd OpenUsage-Bar-v0.7.1-macos-arm64
scripts/verify_canary_candidate.py --assets-dir .. --version 0.7.1

After installing the verified candidate, a tester may explicitly create a redacted aggregate:

scripts/export_diagnostics.py --output /tmp/openusage-diagnostics.json
scripts/privacy_scan.py /tmp/openusage-diagnostics.json

This keeps the byte-compatible aggregate diagnostics v1 as the default. For a bounded, source-aware daily reconciliation, explicitly request v2:

scripts/export_diagnostics.py \
  --schema-version 2 \
  --from 2026-07-17 \
  --to 2026-07-18 \
  --timezone Asia/Singapore \
  --output /tmp/openusage-diagnostics-v2.json
scripts/privacy_scan.py /tmp/openusage-diagnostics-v2.json

Review either file before attaching it. V2 preserves source totals, marks non-comparable or incomplete rows, separates complete tokenTotals from partial observedTokenTotals, replaces account references with per-export pseudonyms, and only reports duplicate candidates backed by duplicate effective rows. accountTotalComparison also makes local Codex session and OpenUsage collector coverage explicitly non-comparable with an account-wide dashboard; undeclared source scope stays unknown. It cannot observe source-selection history. The full 30-day process and the 1.0 release gate are documented in canary.md.