内容
<p align="center">
<strong> </strong> · <a href="README.zh-CN.md">简体中文</a>
</p>
<p align="center">
<img src="docs/assets/agent-switch-icon.png" width="112" alt="Agent Switch 应用图标">
</p>
<h1 align="center">Agent Switch</h1>
<p align="center">
<strong>一次性定义每个MCP。一次性存储每个凭证。将其投影到每个支持的本地AI代理中。</strong>
</p>
<p align="center">
<a href="https://github.com/JNHFlow21/agent-switch/actions/workflows/ci.yml"><img src="https://github.com/JNHFlow21/agent-switch/actions/workflows/ci.yml/badge.svg" alt="CI 状态"></a>
<a href="https://www.apple.com/macos/"><img src="https://img.shields.io/badge/macOS-14%2B-111111?logo=apple" alt="macOS 14 或更高版本"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-111111.svg" alt="MIT 许可证"></a>
</p>
<p align="center">
<img src="docs/assets/agent-switch-dashboard.jpg" width="820" alt="Agent Switch 控制台，显示健康状态、配置漂移、MCP 路由和凭证可用性">
</p>
<p align="center">
<sub>实际的 macOS 控制台，显示隔离示例配置，公开健康状态、漂移、路由和凭证可用性 — 绝不公开凭证值。</sub>
</p>
Codex、Claude Code、Claude Desktop 和 Hermes 每个都保留自己的MCP配置。复制相同的服务器和凭证到每个客户端会造成漂移，并将机密分散到各个文件中。
Agent Switch 用一个本地注册表、一个私有凭证存储和确定性的每个代理投影取代了这些副本。
> [!IMPORTANT]
> Agent Switch 是 **alpha 软件**。公共应用是临时签名的，没有经过 Apple notarization。项目拥有的 Homebrew Cask 因此在安装后会删除 Gatekeeper quarantine。请在安装前查看 [公共源代码](https://github.com/JNHFlow21/agent-switch) 和 [发布校验和](https://github.com/JNHFlow21/agent-switch/releases/tag/v0.2.0)。
## 快速入门
### 先决条件
- macOS 14 或更高版本
- Homebrew 6.0 或更高版本
### 安装
粘贴一个已验证的命令：
```bash
brew tap JNHFlow21/tap && brew trust --tap JNHFlow21/tap && brew install --cask JNHFlow21/tap/agent-switch
```
Homebrew：
1. 注册并明确信任项目拥有的 Tap；
2. 通过 `agent-switch-cli` 安装 `agent-switch` CLI；
3. 在 `/Applications/Agent Switch.app` 安装通用原生应用；
4. 删除 Gatekeeper quarantine，因为此 alpha 版本未经 notarization；
5. 留下 MCP 采用和原生代理配置不变。
预期第一个结果：
```text
agent-switch --version -> agent-switch 0.2.0
原生应用 -> /Applications/Agent Switch.app
```
从 Applications 打开 Agent Switch，或运行：
```bash
open -a "Agent Switch"
agent-switch mcp import --dry-run --json
agent-switch doctor
```
在运行 `agent-switch mcp import --adopt` 或 `agent-switch reconcile` 之前，请查看检测到的 MCP ID、目标应用和所需的机密 **名称**。
<details>
<summary>为什么使用 Homebrew 而不是 npm 或 NPX？</summary>
Agent Switch 是一个原生 macOS 应用，带有 Python CLI；Node.js 不是其运行时。npm/NPX 将添加一个无关的依赖项，并且仍然需要构建或下载 macOS 应用。
当前 alpha 分发版是：
```text
临时签名发布产物 -> GitHub Releases -> 项目拥有的 Homebrew Cask
```
开发者 ID 签名和 notarization 仍然是稳定发布的目标。请参阅 [路线图](docs/roadmap.md)。
</details>
## 对您的影响
| 之前使用 Agent Switch | 使用 Agent Switch |
| --- | --- |
| 相同的 MCP 在每个代理中单独配置 | 注册一次并选择其目标代理 |
| API 密钥复制到原生客户端配置中 | 值保留在一个私有本地存储中 |
| 更改的 MCP 在客户端之间静默漂移 | `doctor` 报告漂移；`reconcile` 修复它 |
| 每个 MCP 可以继承整个 shell 环境 | 每个包装器仅注入其声明的机密名称 |
| 现有配置迁移是一个全有或全无的编辑 | 预览后，然后使用备份明确采用 |
新安装开始时具有空注册表。Agent Switch 不会安装维护者的首选 MCP 或请求无关的凭证。
## 核心工作流程
```bash
# 1. 预览支持的用户级 stdio MCP，而不更改文件
agent-switch mcp import --dry-run --json
# 2. 备份原生配置并明确采用预览的 MCP
agent-switch mcp import --adopt
# 3. 在不将值放入 argv 或聊天中的情况下本地写入凭证
secret-producing-command | agent-switch secret set --stdin SEARCH_API_KEY
# 4. 预览健康状态和漂移，然后应用中心状态
agent-switch doctor
agent-switch reconcile
# 5. 需要一个干净的管理状态
agent-switch doctor --strict
```
永远不要在记录的命令中用字面机密替换 `secret-producing-command`。macOS 应用是输入值的最简单的交互方式。
## Agent Switch 管理的内容
| 区域 | 当前行为 |
| --- | --- |
| **MCP 服务器** | 导入、添加、编辑、目标、启用、禁用、删除和协调用户级命令/_stdio MCP |
| **凭证** | 存储值一次，并为每个 MCP 授予其声明的机密名称 |
| **代理策略** | 为 Codex、Claude Code 和 Hermes 同步有界指令块 |
| **健康状态** | 检测无效配置、缺少机密名称、未固定的 `npx` 包、阻止的目标和管理漂移 |
| **恢复** | 在迁移或替换之前写入原子并备份原生文件 |
| **CLI 清单** | 显示已安装的 AI 工具、版本、包管理器和可执行路径 |
| **技能** | 清单可选的 Skill Hub 源，而不将下载视为激活 |
| **CC Switch** | 保留提供者切换并仅镜像 Agent Switch 所拥有的 MCP 行 |
## 工作原理
```mermaid
flowchart LR
UI["macOS 应用或 CLI"] --> C["中心配置"]
C --> D["Doctor"]
D --> R["Reconcile"]
S["私有机密存储"] --> W["每个 MCP 包装器"]
R --> X["无机密的代理配置"]
W --> M["MCP 进程"]
X --> A["Codex"]
X --> B["Claude Code / Desktop"]
X --> H["Hermes"]
```
| 本地真相来源 | 默认路径 |
| --- | --- |
| MCP 定义和授予 | `~/.config/agent-switch/config.json` |
| 机密值 | `~/.config/agent-switch/secrets.env` |
| 生成的 MCP 包装器 | `~/.config/agent-switch/mcp/bin/` |
| 原生配置备份 | `~/.config/agent-switch/backups/` |
Agent Switch 仅拥有 `agent-*` MCP 条目和标记的指令块。无关的提供者和 MCP 设置将被保留。
## 支持的集成
| 集成 | MCP 同步 | 共享策略 | 清单 |
| --- | :---: | :---: | :---: |
| Codex | ✓ | ✓ | ✓ |
| Claude Code | ✓ | ✓ | ✓ |
| Claude Desktop | ✓ | — | — |
| Hermes | ✓ | ✓ | ✓ |
| CC Switch | 拥有行镜像 | 提供者设置保留 | 模式检查 |
| Skill Hub | 技能清单/更新 | 显式项目/全局配置文件 | ✓ |
新的代理需要一个测试过的适配器。Agent Switch 不会猜测未知的配置格式。
## 凭证和隐私边界
Agent Switch 是本地优先的，但它 **不是密码保险箱**。
- 机密值保留在本地模式-`0600` 文件中，而不是在 Git、应用首选项、生成的代理配置或包装器源代码中。
- 机密写入使用标准输入或继承的文件描述符，而不是位置参数。
- 机密读取拒绝标准输出、标准错误、终端和别名描述符。
- 包装器将存储视为数据，删除继承的敏感变量，并仅注入授予该 MCP 的名称。
- 诊断、导入预览和审计报告机密 **名称**，而非值。
- 包装器在缺少所需的机密名称时关闭。
- 没有实现上传服务或云帐户。MCP 仍然可以在代理调用它时与其自己的提供者联系。
在处理敏感凭证之前，请阅读 [机密和包装器](docs/secrets-and-wrappers.md) 和 [安全策略](SECURITY.md)。安全报告应遵循 `SECURITY.md` 中的私人报告路线，而不是公共问题。
## 当前 alpha 范围
0.2 版本管理用户级命令/stdio MCP 定义和 macOS 上的静态机密值。
它 **尚未** 提供：
- 原生 HTTP/SSE 传输或 OAuth 会话的迁移；
- 项目范围的 MCP 发现；
- 对未知代理的自动支持；
- 开发者 ID 签名和 notarized 可下载应用；
- 已发布的 PyPI 包；
- 密码管理器或硬件支持的机密保险箱。
这些是限制，而不是隐藏功能。计划工作位于 [路线图](docs/roadmap.md) 中。
## 命令参考
```bash
agent-switch agents # 检测到的代理和策略注册
agent-switch clis # 已安装的 AI CLI 清单
agent-switch mcp list # 中心 MCP 注册表
agent-switch secret list # 仅机密名称
agent-switch skills # 可选的 Skill Hub 清单
agent-switch doctor --json # 机器可读的健康报告
agent-switch reconcile --dry-run # 计划的管理更改
```
添加一个中心管理的 MCP：
```bash
agent-switch mcp add filesystem \
--command npx \
--arg=-y \
--arg=@modelcontextprotocol/server-filesystem@1.0.0 \
--app codex \
--app claude
agent-switch reconcile
```
有关生命周期命令和安全导入行为，请参阅 [统一 MCP 注册表](docs/mcp-registry.md)。
## 更新
Homebrew 安装：
```bash
brew update
brew upgrade --cask JNHFlow21/tap/agent-switch
```
Agent Switch 不会静默更新自己、第三方 CLI 或 Skill 源。
## 文档
- [统一 MCP 注册表](docs/mcp-registry.md)
- [机密和包装器](docs/secrets-and-wrappers.md)
- [CC Switch 兼容性](docs/ccswitch-compat.md)
- [恢复和回滚](docs/recovery.md)
- [路线图](docs/roadmap.md)
- [贡献](CONTRIBUTING.md)
- [安全策略](SECURITY.md)
## 开发
源代码安装程序仍然可用于具有 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
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
python -m unittest discover -s tests
python -m unittest discover -s tests/integration
```
原生应用位于 [`macos-app/AgentSwitch`](macos-app/AgentSwitch) 并针对 macOS 14+。有关完整的测试和隐私门，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
[MIT](LICENSE) 2026 JNHFlow21
