From a6f63163cc25d4f897f5adaf623929a1373e9fae Mon Sep 17 00:00:00 2001 From: JNHFlow21 Date: Thu, 23 Jul 2026 03:19:40 -0400 Subject: [PATCH] docs: make Homebrew the primary install path --- .github/workflows/release.yml | 8 ++-- README.md | 69 ++++++++++++++++++----------------- README.zh-CN.md | 66 ++++++++++++++++----------------- docs/roadmap.md | 5 +-- tests/test_docs.py | 12 +++++- 5 files changed, 85 insertions(+), 75 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 63f740c..8eeabb4 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -52,13 +52,13 @@ jobs: ## Install \`\`\`bash - brew tap JNHFlow21/tap && brew trust --tap JNHFlow21/tap && HOMEBREW_CASK_OPTS=--no-quarantine brew install --cask JNHFlow21/tap/agent-switch + brew tap JNHFlow21/tap && brew trust --tap JNHFlow21/tap && brew install --cask JNHFlow21/tap/agent-switch \`\`\` This build is ad-hoc signed and not notarized because the project does - not yet have an Apple Developer ID. The install command deliberately - disables Gatekeeper quarantine for this cask installation. Review the - public source and checksums before installing. + not yet have an Apple Developer ID. The project-owned Cask removes + Gatekeeper quarantine after installation. Review the public source and + checksums before installing. EOF gh release create "$GITHUB_REF_NAME" \ dist/Agent-Switch-"$version"-macos-universal.zip \ diff --git a/README.md b/README.md index b8a3335..535ee0a 100644 --- a/README.md +++ b/README.md @@ -18,53 +18,46 @@ Agent Switch replaces those copies with one local registry, one private credential store, and deterministic per-agent projections. > [!IMPORTANT] -> Agent Switch is **alpha software**. The current installer builds from source -> and requires Xcode. The intended public distribution is a Developer ID-signed, -> notarized GitHub Release installed through Homebrew Cask. That release channel -> is not available yet, so this README does not advertise a fake `brew` command. +> Agent Switch is **alpha software**. The public app is ad-hoc signed and is not +> Apple-notarized. The project-owned Homebrew Cask therefore removes Gatekeeper +> quarantine after installation. Review the [public source](https://github.com/JNHFlow21/agent-switch) +> and [release checksums](https://github.com/JNHFlow21/agent-switch/releases/tag/v0.2.0) +> before installing. ## Quick start ### Prerequisites - macOS 14 or newer -- Git -- Python 3.11 or newer -- [`pipx`](https://pipx.pypa.io/) -- Full Xcode with `xcodebuild` - -Install missing command-line prerequisites with: - -```bash -brew install python pipx -``` +- Homebrew 6.0 or newer ### Install -Run one verified source-install command: +Paste one verified command: ```bash -git clone https://github.com/JNHFlow21/agent-switch.git && cd agent-switch && ./scripts/install.sh +brew tap JNHFlow21/tap && brew trust --tap JNHFlow21/tap && brew install --cask JNHFlow21/tap/agent-switch ``` -The installer: +Homebrew: -1. verifies macOS, Python, pipx, and Xcode; -2. installs the Python CLI in an isolated pipx environment; -3. builds and installs the native app at `~/Applications/Agent Switch.app`; -4. creates a neutral, empty Agent Switch config if none exists; -5. opens the app without adopting MCPs or rewriting native agent configs. +1. registers and explicitly trusts the project-owned Tap; +2. installs the `agent-switch` CLI through `agent-switch-cli`; +3. installs the universal native app at `/Applications/Agent Switch.app`; +4. removes Gatekeeper quarantine because this alpha is not notarized; +5. leaves MCP adoption and native agent configuration unchanged. Expected first result: ```text agent-switch --version -> agent-switch 0.2.0 -Native app -> opens from ~/Applications/Agent Switch.app +Native app -> /Applications/Agent Switch.app ``` -Then preview your existing user-level command/stdio MCPs: +Open Agent Switch from Applications, or run: ```bash +open -a "Agent Switch" agent-switch mcp import --dry-run --json agent-switch doctor ``` @@ -73,20 +66,20 @@ Review the detected MCP IDs, target apps, and required secret **names** before running `agent-switch mcp import --adopt` or `agent-switch reconcile`.
-Why not npm, NPX, or a public Homebrew command? +Why Homebrew instead of npm or NPX? Agent Switch is a native macOS application with a Python CLI; Node.js is not part of its runtime. npm/NPX would add an unrelated dependency and still need to build or download the macOS app. -The correct end-user channel is: +The current alpha distribution is: ```text -signed + notarized release artifact -> GitHub Releases -> Homebrew Cask +ad-hoc signed release artifact -> GitHub Releases -> project-owned Homebrew Cask ``` -Until that artifact exists, the source installer above is the shortest honest -path. See the [roadmap](docs/roadmap.md). +Developer ID signing and notarization remain the stable-release target. See the +[roadmap](docs/roadmap.md).
@@ -210,8 +203,8 @@ It does **not** yet provide: - migration for native HTTP/SSE transports or OAuth sessions; - project-scoped MCP discovery; - automatic support for unknown agents; -- a signed and notarized downloadable app; -- a published Homebrew Cask or Python package; +- a Developer ID-signed and notarized downloadable app; +- a published PyPI package; - a password-manager or hardware-backed credential vault. These are limitations, not hidden features. Planned work lives in the @@ -247,10 +240,11 @@ safe import behavior. ## Update -From the cloned repository: +Homebrew installations: ```bash -git pull --ff-only && ./scripts/install.sh +brew update +brew upgrade --cask JNHFlow21/tap/agent-switch ``` Agent Switch does not silently update itself, third-party CLIs, or Skill @@ -268,6 +262,15 @@ sources. ## Development +The source installer remains available for contributors who have Python 3.11+, +`pipx`, and full Xcode: + +```bash +git clone https://github.com/JNHFlow21/agent-switch.git && cd agent-switch && ./scripts/install.sh +``` + +For an editable CLI environment: + ```bash git clone https://github.com/JNHFlow21/agent-switch.git cd agent-switch diff --git a/README.zh-CN.md b/README.zh-CN.md index f622f51..162d231 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -17,53 +17,45 @@ Agent Switch 用一个本地 MCP 注册表、一个私密凭据存储和可重 配置替代这些副本。 > [!IMPORTANT] -> Agent Switch 目前仍是 **Alpha 软件**。当前安装器会在本机从源码构建，因此需要 -> Xcode。正式面向用户的发行方式应当是经过 Developer ID 签名和 Apple 公证的 -> GitHub Release，并通过 Homebrew Cask 安装。这个发行通道尚未完成，所以这里不会 -> 放一个实际上不能使用的 `brew` 命令。 +> Agent Switch 目前仍是 **Alpha 软件**。公开 App 使用 ad-hoc 签名，尚未经过 +> Apple 公证，因此项目自己的 Homebrew Cask 会在安装完成后移除 Gatekeeper +> quarantine。安装前请先检查[公开源码](https://github.com/JNHFlow21/agent-switch) +> 和[发行校验和](https://github.com/JNHFlow21/agent-switch/releases/tag/v0.2.0)。 ## 快速开始 ### 前置条件 - macOS 14 或更高版本 -- Git -- Python 3.11 或更高版本 -- [`pipx`](https://pipx.pypa.io/) -- 包含 `xcodebuild` 的完整 Xcode - -缺少命令行依赖时，可以运行： - -```bash -brew install python pipx -``` +- Homebrew 6.0 或更高版本 ### 安装 -运行下面这一条经过验证的源码安装命令： +复制执行下面这一条经过验证的命令： ```bash -git clone https://github.com/JNHFlow21/agent-switch.git && cd agent-switch && ./scripts/install.sh +brew tap JNHFlow21/tap && brew trust --tap JNHFlow21/tap && brew install --cask JNHFlow21/tap/agent-switch ``` -安装器会： +Homebrew 会： -1. 检查 macOS、Python、pipx 和 Xcode； -2. 在独立的 pipx 环境中安装 Python CLI； -3. 构建原生应用并安装到 `~/Applications/Agent Switch.app`； -4. 仅在配置不存在时创建一个中立、空白的 Agent Switch 配置； -5. 打开应用，但不会自动接管 MCP，也不会改写原生 Agent 配置。 +1. 注册并显式信任项目自己的 Tap； +2. 通过 `agent-switch-cli` 安装 `agent-switch` CLI； +3. 把通用架构原生 App 安装到 `/Applications/Agent Switch.app`； +4. 因为当前 Alpha 尚未公证，所以移除 Gatekeeper quarantine； +5. 不会自动接管 MCP，也不会改写原生 Agent 配置。 首次安装成功后应当看到： ```text agent-switch --version -> agent-switch 0.2.0 -原生应用 -> 从 ~/Applications/Agent Switch.app 打开 +原生应用 -> /Applications/Agent Switch.app ``` -然后先预览已有的用户级 command/stdio MCP： +从“应用程序”打开 Agent Switch，或者运行： ```bash +open -a "Agent Switch" agent-switch mcp import --dry-run --json agent-switch doctor ``` @@ -72,19 +64,18 @@ agent-switch doctor 之前，请先检查检测到的 MCP ID、目标应用和所需密钥的**名称**。
-为什么不使用 npm、NPX 或直接写一个 Homebrew 命令？ +为什么使用 Homebrew，而不是 npm 或 NPX？ Agent Switch 是原生 macOS 应用加 Python CLI，Node.js 并不是它的运行时。 npm/NPX 只会引入无关依赖，最终仍然需要构建或下载 macOS 应用。 -正确的用户发行链路应当是： +当前 Alpha 的发行链路是： ```text -签名并公证的发行产物 -> GitHub Releases -> Homebrew Cask +ad-hoc 签名的发行产物 -> GitHub Releases -> 项目自己的 Homebrew Cask ``` -在这个产物真正存在之前，上面的源码安装器是最短且诚实的路径。详情见 -[路线图](docs/roadmap.md)。 +Developer ID 签名和 Apple 公证仍然是稳定版目标。详情见[路线图](docs/roadmap.md)。
@@ -200,8 +191,8 @@ Agent Switch 是本地优先工具，但它**不是密码保险库**。 - 原生 HTTP/SSE Transport 或 OAuth Session 迁移； - 项目级 MCP 发现； - 对未知 Agent 的自动支持； -- 已签名并公证的可下载应用； -- 已发布的 Homebrew Cask 或 Python 包； +- 经过 Developer ID 签名并公证的可下载应用； +- 已发布的 PyPI 包； - 密码管理器或硬件保护的凭据保险库。 这些是明确限制，不是隐藏功能。计划中的工作记录在[路线图](docs/roadmap.md)中。 @@ -235,10 +226,11 @@ agent-switch reconcile ## 更新 -在已经克隆的仓库中运行： +通过 Homebrew 安装的版本： ```bash -git pull --ff-only && ./scripts/install.sh +brew update +brew upgrade --cask JNHFlow21/tap/agent-switch ``` Agent Switch 不会静默更新自己、第三方 CLI 或 Skill 源。 @@ -255,6 +247,14 @@ Agent Switch 不会静默更新自己、第三方 CLI 或 Skill 源。 ## 开发 +需要 Python 3.11+、`pipx` 和完整 Xcode 的贡献者仍然可以使用源码安装器： + +```bash +git clone https://github.com/JNHFlow21/agent-switch.git && cd agent-switch && ./scripts/install.sh +``` + +创建可编辑的 CLI 开发环境： + ```bash git clone https://github.com/JNHFlow21/agent-switch.git cd agent-switch diff --git a/docs/roadmap.md b/docs/roadmap.md index f583829..20f4c7d 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -23,9 +23,8 @@ distribution. explicit ownership choice before adoption. 3. Add adapters through a documented contract and fixture suite rather than guessing unknown agent configuration formats. -4. Ship a Developer ID-signed and notarized macOS release that packages the app - and CLI together, publish it through GitHub Releases, and make Homebrew Cask - the one-line end-user install path. +4. Replace the current ad-hoc signed Homebrew alpha with a Developer ID-signed + and notarized release, then remove the Cask's Gatekeeper-quarantine bypass. 5. Add complete English and Chinese localization plus a first-run wizard that previews targets, MCP IDs, and secret names before any write. 6. Add a first-class backup browser and guided restore flow. diff --git a/tests/test_docs.py b/tests/test_docs.py index 59193d8..1f9b54d 100644 --- a/tests/test_docs.py +++ b/tests/test_docs.py @@ -21,11 +21,19 @@ def test_docs_reference_current_commands_and_boundaries(self) -> None: self.assertIn("README.zh-CN.md", "\n".join(readme.splitlines()[:12])) self.assertIn("README.md", "\n".join(readme_zh.splitlines()[:12])) install_command = ( - "git clone https://github.com/JNHFlow21/agent-switch.git && " - "cd agent-switch && ./scripts/install.sh" + "brew tap JNHFlow21/tap && brew trust --tap JNHFlow21/tap && " + "brew install --cask JNHFlow21/tap/agent-switch" ) self.assertIn(install_command, readme) self.assertIn(install_command, readme_zh) + source_command = ( + "git clone https://github.com/JNHFlow21/agent-switch.git && " + "cd agent-switch && ./scripts/install.sh" + ) + self.assertIn(source_command, readme) + self.assertIn(source_command, readme_zh) + self.assertIn("removes Gatekeeper quarantine", readme) + self.assertIn("移除 Gatekeeper quarantine", readme_zh) self.assertIn("agent-*", compat) self.assertIn("CC Switch", compat) self.assertIn("agent-switch reconcile", recovery)