内容
# 构建控制塔
一个 **跨多个并发代理序列化构建** 的 MCP 服务器，以防止它们使您的机器过载。当多个代理同时尝试构建一个大型项目时，所有操作都会变慢。构建控制塔使它们依次进行：一次运行一个构建，其余的等待队列。
它适用于命令行 `xcodebuild`/`swift build` 和在 Xcode 中启动的构建 — 服务器监视系统 CPU 以注意到它未授予的构建（例如，在 Xcode 中手动 ⌘B），并在它们运行时保持队列。
它作为 **单个长寿命的 HTTP 守护进程** 在 localhost 上运行。机器上的每个代理都连接到该守护进程，因此它们都共享一个构建队列。（每个代理都有自己的 MCP 会话；共享状态是队列，而不是会话。）
请参阅 [`tech-spec.md`](tech-spec.md) 以获取完整的设计。
## 要求
- macOS 14 或更高版本
- Swift 6.2 / Xcode 26 或更高版本（用于构建）
## 安装
```sh
git clone <your-remote> build-control-tower
cd build-control-tower
./build.sh --install ~/.local/bin # 运行测试，构建发布版本，安装二进制文件
```
## 运行守护进程
代理连接需要运行守护进程。它监听 `http://127.0.0.1:7373/mcp`（设置 `BCT_PORT` 以更改端口）。
**登录时自动启动（推荐）**。将其安装为 launchd 代理 — 这将二进制文件安装到 `~/.local/bin`，现在启动它，并在每次登录（以及崩溃时）重新启动它：
```sh
./build.sh --install-agent
```
**手动运行：**
```sh
~/.local/bin/BuildControlTower
```
### 管理 launchd 代理
由于代理使用 `KeepAlive`，普通的 `kill <pid>` **不会停止它** — launchd 会立即重新启动它。使用 `bootout`:
```sh
# 现在停止它（保持停止直到重新安装）：
launchctl bootout gui/$(id -u)/com.build-control-tower.daemon
# 启动 / 重新启动它：
launchctl kickstart -k gui/$(id -u)/com.build-control-tower.daemon
# 状态和日志：
launchctl print gui/$(id -u)/com.build-control-tower.daemon
tail -f ~/Library/Logs/build-control-tower.log
# 完全删除它（停止 + 删除 LaunchAgent）：
./build.sh --uninstall-agent
```
## 与代理注册
将 **每个** 共享机器的代理指向同一个守护进程 URL：
```sh
claude mcp add --transport http build-control-tower http://127.0.0.1:7373/mcp
```
… 或将其添加到任何 MCP 客户端配置中：
```json
{
"mcpServers": {
"build-control-tower": {
"type": "http",
"url": "http://127.0.0.1:7373/mcp"
}
}
}
```
## 代理如何使用它
1. **`request_build`** — 加入队列。返回票证 ID 和是否允许您现在构建（`GRANTED`）或 `QUEUED`。
2. **`build_status`** — 如果排队，请使用票证轮询（每 30–60 秒）直到它报告 `GRANTED`，然后运行您的构建。
3. **`finish_build`** — 始终在构建完成时调用（或放弃排队请求）。它立即将时间片交给下一个代理。
4. **`queue_status`** — 检查谁正在构建和谁正在等待。
如果授予的代理崩溃并且从未调用 `finish_build`，后台轮询会在放弃的时间片被闲置（无构建 CPU）一段时间后回收，以防止队列死锁。
## 配置
通过环境变量在启动时可调（均为可选）：
| 变量 | 默认值 | 含义 |
| ------------------- | ------- | -------------------------------------------------------------- |
| `BCT_PORT` | `7373` | 守护进程监听的 localhost TCP 端口。 |
| `BCT_POLL_SECONDS` | `120` |后台安全网轮询间隔。 |
| `BCT_GRACE_SECONDS` | `360` | 空闲时间，在此期间，无声授予被回收（保持 > 轮询）。 |
| `BCT_CPU_THRESHOLD` | `40` | 综合编译器 `%CPU`，超过此值时，构建被视为活动。 |
## 开发
```sh
swift build # 调试构建
swift test # 运行测试套件
swift test --filter onlyOneGrantAtATime # 运行单个测试
```
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
