内容
# 代理舰队
[](LICENSE)
[](https://github.com/metahub-tech/agent-fleet/releases/tag/v0.8.4-alpha)
**英文** · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Español](README.es.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Português (BR)](README.pt-BR.md) · [Русский](README.ru.md)
<p align="center">
<img src="docs/assets/agent-fleet-demo.gif" alt="agent-fleet demo — an LLM agent driving a real iPad over MCP" width="320">
<br><sub><em>一个LLM代理驱动一个真实的iPad通过MCP — 没有人类的参与。</em></sub>
</p>
> **给你的LLM代理一个属于自己的物理设备舰队。**
> 将真实的Windows / macOS / Android / iOS硬件连接到你的LLM代理上，通过MCP让它像人类一样操作它们。一个命令即可安装：
>
> ```bash
> uvx --from "git+https://github.com/metahub-tech/agent-fleet@v0.8.4-alpha#subdirectory=cli" agent-fleet setup
> ```
## 什么是它
将**真实设备** — Windows PC、Mac、Android手机、iPhone — 带入你的LLM代理的工具链中，让它像本地命令一样驱动它们：截图、点击按钮、运行测试、读取日志、调试GUI。
这是**基于代理的软件测试和跨平台验证**的基础设施 — 更广泛地说，是给代理赋予对物理世界的真实感知和控制能力。
```
┌─────────────────┐ ┌──────────────┐
│ 代理（任意操作系统） │ ──── Tailscale 网状网络 ─────> │ Windows PC │ win-device :8766 ✅
│ Claude Code / │ ├──────────────┤
│ Cursor / Cline │ │ macOS box │ mac-device :8767 ✅
│ / OpenClaw / │ ├──────────────┤
│ Antigravity / │ │ Android phone│ android-device :8768 ✅
│ Hermes / ... │ ├──────────────┤
└─────────────────┘ │ iPhone/iPad │ ios-device :8769 ✅
└──────────────┘
↑ ↑
uvx agent-fleet setup 生成6个代理框架的配置文件
一条命令：安装客户端 + 服务器 / 配置Tailscale / 指导权限 / 自检 / 生成代码片段
```
## 状态
| 组件 | 版本 | 状态 |
|---|---|---|
| Windows 10/11 桥接 | `0.2.0` | ✅ 已发布（win-device，74种工具 — 43种核心+发现，+27种代理浏览器，+1种人类浏览器，+3种视觉（浏览器功能需要Chrome/node）；可流式HTTP） |
| macOS 12+ 桥接 | `0.3.0` | ✅ 已发布（mac-device，launchd，73种工具 — 42种核心+发现，+27种代理浏览器，+1种人类浏览器，+3种视觉（浏览器功能需要Chrome/node）；GUI权限流程） |
| Android 桥接 | `0.7.0-alpha` | ✅ 已发布（android-device，**31种工具**，多设备 + USB + 无线 + 混合ADB） |
| agent-fleet CLI 向导 | `0.5.0-alpha` | ✅ 已发布（`uvx agent-fleet setup` 一键安装；6个框架的配置文件） |
| 角色重命名 → `<os>-device` + macOS 权限入门 | `0.6.0-alpha` | ✅ 已发布 |
| v0.6.x 补丁（UI检查、烟雾测试、错误修复、安装程序强化……） | `0.6.1–0.6.15` | ✅ 已发布 — 见 [CHANGELOG.md](CHANGELOG.md) |
| iOS / iPadOS 桥接 | `0.8.0-alpha` | ✅ 已发布（ios-device，30种工具，WebDriverAgent + pymobiledevice3，iPad验证） |
| iOS WDA 守护进程（启动生存 + 保持活动） | `0.8.2-alpha` | ✅ 已发布（go-ios runwda + tunneld launchd；免费/付费签名模式） |
| 跨设备协调 | `0.10.0` | 🔭 未来 |
| 公开稳定发布 | `1.0.0` | 🔭 未来（在社区反馈alpha版本后） |
参见 [`docs/roadmap.md`](docs/roadmap.md)。
## 快速开始
**新手 / 一键流程** — 在被控制的设备上（PC 或带有手机的PC）：
```bash
# macOS / Linux — 不是 `curl ... | bash`！ 向导是交互式的，bash
# 从curl读取脚本使用stdin，questionary的提示
# 会因EOFError而失败。 `bash -c "$(...)"` 形式将脚本放入argv并
# 留下stdin = 终端。
bash -c "$(curl -fsSL https://raw.githubusercontent.com/metahub-tech/agent-fleet/main/install.sh)"
# Windows — `irm | iex` 在PowerShell上是安全的，因为iex在当前会话中运行脚本
# 而Read-Host从控制台主机读取，而不是stdin。
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/metahub-tech/agent-fleet/main/install.ps1 | iex"
```
或者，如果你已经有uv（在v0.8.4-alpha阶段，它从git中拉取，而不是PyPI）：
```bash
uvx --from "git+https://github.com/metahub-tech/agent-fleet@v0.8.4-alpha#subdirectory=cli" agent-fleet setup
```
> macOS 12 用户必须先运行 `brew install coreutils` （uv的包装器使用`realpath`，而macOS 12默认情况下没有它；参见 [#2](https://github.com/metahub-tech/agent-fleet/issues/2))。
向导会引导你完成：选择角色 → 安装MCP服务器 → 配置Tailscale → 交互式指导GUI权限 / ADB授权 → 运行健康检查 → 为6个代理框架生成配置文件。
**高级用户**仍然可以直接调用底层脚本 — `docs/install-pattern.md`仍然有效（高级手册）。
| 你是 | 阅读 |
|---|---|
| **新手** （让向导驱动） | 运行上面的命令并遵循提示 |
| **设备管理员脚本自己的部署** | [`docs/install-pattern.md`](docs/install-pattern.md) （低级脚本合约） |
| **代理操作员** | 将向导的代码片段粘贴到你的代理配置文件中；参见 [`docs/agent-host-setup.md`](docs/agent-host-setup.md) |
| **贡献者** （设计文档） | [`docs/internal/design/2026-05-11-agent-fleet-cli.md`](docs/internal/design/2026-05-11-agent-fleet-cli.md) |
## 架构
```mermaid
flowchart LR
A["🤖 LLM 代理<br/>Claude Code · Cursor · Cline · …<br/>统一MCP工具"]
A ==>|"① 连接到它自己的计算机<br/>MCP通过Tailscale（WireGuard，跨局域网）"| HUB
subgraph HUB["🖥️ 计算机 = 代理的手 · Windows / macOS"]
direction TB
SELF["驱动计算机本身<br/>win-device :8766 · mac-device :8767<br/>pywinauto · AppleScript · shell"]
JUMP["② 一个跳转主机到附加设备"]
end
JUMP -->|"USB · adb"| AND["📱 Android<br/>android-device :8768"]
JUMP -->|"USB · WebDriverAgent"| IOS["📱 iPhone / iPad<br/>ios-device :8769"]
JUMP -.->|"计划 · hdc"| HM["📱 HarmonyOS<br/>(计划)"]
JUMP -.->|"③ 任何人类可以通过计算机管理的设备"| MORE["⋯ 更多设备"]
classDef agent fill:#1f6feb,stroke:#0b3d91,color:#fff
classDef hub fill:#0e7490,stroke:#053b46,color:#fff
classDef dev fill:#16a34a,stroke:#064e23,color:#fff
classDef plan fill:#6b7280,stroke:#374151,color:#fff
class A agent
class SELF,JUMP hub
class AND,IOS dev
class HM,MORE plan
```
代理连接到一台**计算机**（Windows/macOS）— 它的“手” — 并使用它直接驱动计算机，并作为**跳转主机**到连接到它的设备：目前是Android和iOS，将来是HarmonyOS。原则上，任何人类可以通过计算机管理的设备，代理也可以。 （iOS主机必须是Mac。）
工具接口在平台之间保持语义一致（`take_screenshot` / `tap` / `launch_app` / …）；切换设备只需在`~/.claude.json`中更改URL。
参见 [`docs/architecture.md`](docs/architecture.md)。
## 仓库布局
```
agent-fleet/
├── docs/ # 共享文档
│ ├── install-pattern.md # 开发者基线：两个角色 / 两个安装路径 / 目录合约
│ ├── architecture.md # 共同桥接架构
│ ├── agent-host-setup.md # 代理端配置（~/.claude.json + 技能符号链接）
│ ├── roadmap.md # 平台路线图
│ └── platforms/<name>.md # 每个平台的手册（设备端）
├── platforms/ # 每个平台的自包含仓
│ ├── windows/
│ │ ├── platform.toml # 清单：id / port / host_os / 启用功能
│ │ ├── README.md # 一览
│ │ ├── server/ # MCP服务器源 + 依赖
│ │ ├── scripts/ # 安装 / 启动 / 故障排除脚本
│ │ ├── skills/using-win/ # 技能文档供代理使用
│ │ └── examples/ # claude-settings.json代码片段
│ ├── macos/ # 相同子结构
│ ├── android/ # 相同子结构
│ └── ios/ # 相同子结构
├── scripts/ # 仓库级脚本
│ └── install-agent-side.py # 一个命令安装MCP + 技能到~/.claude.json
├── examples/ # 跨平台示例
│ └── multi-platform-claude-settings.json
└── CHANGELOG.md
```
添加平台 → 在`platforms/<name>/`下添加相同的子结构。参见 [`docs/install-pattern.md` § 添加新平台](docs/install-pattern.md)。
## 许可证
[Apache 2.0](LICENSE)
## 贡献
欢迎贡献！ **agent-fleet 在Apache 2.0许可证下公开发布，并接受社区贡献。**
参见 [`CONTRIBUTING.md`](CONTRIBUTING.md) 了解贡献流程和编码约定，以及 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) 了解行为准则。通过GitHub安全选项卡 → “报告漏洞”私下报告安全漏洞。
