内容
# macOS ZLaunch 管理器
一个原生的 macOS 图形用户界面（GUI）和命令行界面（CLI），用于管理 launchd 服务。取代了直接使用 `launchctl` 命令和 plist 文件的需要。
## 功能
macOS 使用 `launchd` 来管理所有后台服务，但没有内置的 GUI 来管理它（不像 Windows 服务或 Linux systemctl）。ZLaunch 管理器填补了这个空白，提供了：
- **图形用户界面应用程序** — 三列 SwiftUI 界面，用于浏览、控制和配置服务
- **命令行工具（`zlm`）** — 快速终端界面，用于执行相同的操作
- **MCP 服务器** — 模型上下文协议服务器，允许 AI 助手（Kiro，Claude Desktop）管理 launchd 服务
## 安装
### 命令行工具 — 一行命令（推荐）
```bash
curl -fsSL https://raw.githubusercontent.com/zavora-ai/macos-zlaunch-manager/main/scripts/install.sh | bash
```
### 命令行工具 — Homebrew
```bash
brew tap zavora-ai/tap
brew install zlm
```
### 命令行工具 — 下载二进制文件
```bash
# 从 GitHub Releases （不需要 Swift/Xcode）
curl -L https://github.com/zavora-ai/macos-zlaunch-manager/releases/latest/download/zlm-v1.2.0-macos-universal.tar.gz | tar xz
sudo mv zlm /usr/local/bin/
```
### 命令行工具 — 从源代码构建
```bash
git clone https://github.com/zavora-ai/macos-zlaunch-manager.git
cd macos-zlaunch-manager/cli
swift build -c release
cp .build/release/zlm /usr/local/bin/zlm
```
### 图形用户界面应用程序 — DMG
```bash
# 本地构建
./scripts/create-dmg.sh
# 输出：build/ZLaunchManager-YYYY.MM.DD.dmg
# 打开 DMG → 拖到应用程序
```
或从 [GitHub Releases](https://github.com/zavora-ai/macos-zlaunch-manager/releases) 下载。
### MCP 服务器
```bash
# 构建和安装
cd mcp-server
swift build -c release
cp .build/release/zlm-mcp-server /usr/local/bin/
# 添加到 Kiro （~/.kiro/settings/mcp.json）
```
```json
{
"mcpServers": {
"launchd": {
"command": "/usr/local/bin/zlm-mcp-server",
"args": [],
"autoApprove": ["launchd_list", "launchd_status", "launchd_logs", "launchd_info", "launchd_plist_read"]
}
}
}
```
对于 Claude Desktop，添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`。
## 命令行工具用法
`zlm` 命令提供完整的终端服务管理：
```bash
# 列出服务
zlm # 所有服务（默认）
zlm list -d user # 仅用户代理
zlm list -d global-daemons # 仅全局守护进程
zlm list --running # 仅正在运行的服务
zlm list --loaded # 仅已加载的服务
zlm list -f docker # 按名称子字符串筛选
# 服务信息
zlm status <label> # 详细状态
zlm info <label> # 原始 launchctl print 输出
zlm logs <label> # 查看 stdout/stderr 日志
zlm logs -f <label> # 跟随日志（tail -f）
zlm logs -l 200 <label> # 最后 200 行
# 控制服务
zlm start <label> # 启动（如果需要，自动加载）
zlm stop <label> # 停止（SIGTERM）
zlm stop -f <label> # 强制杀死（SIGKILL）
zlm restart <label> # 停止 + 启动
# 加载/卸载
zlm load <label> # 引导到 launchd
zlm unload <label> # 从 launchd 卸载
# 启用/禁用
zlm enable <label> # 自动加载开机/登录
zlm disable <label> # 防止自动加载
# 创建/删除
zlm create com.company.myservice \
-p /usr/local/bin/myapp \
--run-at-load --keep-alive \
--stdout /tmp/myservice.log \
--stderr /tmp/myservice.err
zlm delete <label> # 卸载 + 删除 plist
zlm delete -y <label> # 跳过确认
# 编辑
zlm edit <label> # 在 $EDITOR 中打开 plist
# 图形用户界面
zlm gui # 打开图形用户界面应用程序（如果未找到，则安装）
zlm gui --reinstall # 强制从 GitHub 重新安装图形用户界面
```
### 域
| 标志 | 域 | 路径 |
|------|--------|------|
| `-d user` | 用户代理 | `~/Library/LaunchAgents` |
| `-d global-agents` | 全局代理 | `/Library/LaunchAgents` |
| `-d global-daemons` | 全局守护进程 | `/Library/LaunchDaemons` |
| `-d system-agents` | 系统代理 | `/System/Library/LaunchAgents` |
| `-d system-daemons` | 系统守护进程 | `/System/Library/LaunchDaemons` |
| `-d all` | 所有（默认） | 以上所有 |
### 状态指示器
```
● running — 服务有活动进程
◐ loaded — 已向 launchd 注册但未运行
○ stopped — 未加载到 launchd
```
## MCP 服务器
MCP 服务器将 launchd 管理公开为 AI 助手的工具。它实现了模型上下文协议（JSON-RPC 2.0 via stdio）。
### 可用工具
| 工具 | 描述 |
|------|-------------|
| `launchd_list` | 列出服务，带有域/状态/标签筛选 |
| `launchd_status` | 详细服务信息（PID，退出代码，配置） |
| `launchd_start` | 启动服务（如果需要，自动加载） |
| `launchd_stop` | 停止服务（SIGTERM 或 SIGKILL） |
| `launchd_restart` | 重启服务 |
| `launchd_load` | 引导服务到 launchd |
| `launchd_unload` | 从 launchd 卸载服务 |
| `launchd_enable` | 启用自动加载开机/登录 |
| `launchd_disable` | 禁用自动加载 |
| `launchd_logs` | 读取 stdout/stderr 日志文件 |
| `launchd_info` | 原始 `launchctl print` 输出 |
| `launchd_create` | 创建新的服务 plist |
| `launchd_delete` | 卸载并删除服务 |
| `launchd_plist_read` | 读取原始 XML plist 内容 |
| `launchd_plist_write` | 写入/更新 plist 内容并进行验证 |
| `launchd_force_reload` | 清除陈旧状态并重新加载（卸载 + 启用 + 引导） |
| `launchd_print_disabled` | 查询 launchd 的内部禁用覆盖数据库 |
| `launchd_override_status` | 检测 plist 和 launchd 覆盖状态之间的冲突 |
| `launchd_open_gui` | 打开 ZLaunch 管理器图形用户界面应用程序 |
### 配置
**Kiro** (`~/.kiro/settings/mcp.json`）：
```json
{
"mcpServers": {
"launchd": {
"command": "/usr/local/bin/zlm-mcp-server",
"args": [],
"autoApprove": ["launchd_list", "launchd_status", "launchd_logs", "launchd_info", "launchd_plist_read"]
}
}
}
```
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"launchd": {
"command": "/usr/local/bin/zlm-mcp-server"
}
}
}
```
### 示例提示
配置完成后，您可以询问您的 AI 助手：
- "列出所有正在运行的 launchd 服务"
- "我的 adk-gateway 服务的状态是什么？"
- "停止 com.zavora.adk-gateway"
- "显示 yabai 的日志"
- "创建一个新的服务，每小时运行一次我的备份脚本"
- "禁用 Google 更新程序在登录时运行"
- "强制重新加载 adk-gateway 服务 — 它卡住了"
- "检查是否有任何服务具有冲突的禁用状态"
- "打开 ZLaunch 管理器图形用户界面"
## 图形用户界面功能
- **三列布局** — 侧边栏域 → 服务列表 → 详细信息视图
- **所有 5 个 launchd 域**，带有服务计数和正在运行的徽章
- **服务生命周期** — 启动，停止，重启，加载/卸载，启用/禁用
- **plist 编辑器** — 编辑 XML，带有验证和保存
- **日志查看器** — stdout/stderr + 系统日志，带有筛选和自动刷新
- **创建服务** — 模板向导（简单代理，周期性任务，守护进程，Web 服务器）
- **删除服务** — 卸载然后删除 plist，带有确认
- **搜索和筛选** — 按标签或可执行文件，筛选状态
- **上下文菜单** — 右键单击快速操作
- **暗黑模式** — 完全支持
- **通用二进制文件** — 在 Intel 和 Apple Silicon 上原生运行
## 项目结构
```
macos-zlaunch-manager/
├── ZLaunchManager/ # 图形用户界面应用程序（SwiftUI）
│ ├── ZLaunchManager.xcodeproj
│ └── ZLaunchManager/
│ ├── ZLaunchManagerApp.swift
│ ├── ContentView.swift
│ ├── Models/
│ │ ├── LaunchdService.swift
│ │ └── ServiceDomain.swift
│ ├── Services/
│ │ ├── ServiceManager.swift
│ │ └── PrivilegedHelper.swift
│ └── Views/
│ ├── SidebarView.swift
│ ├── ServiceListView.swift
│ ├── ServiceDetailView.swift
│ ├── PlistEditorView.swift
│ ├── CreateServiceView.swift
│ ├── LogViewerView.swift
│ ├── SettingsView.swift
│ ├── SearchBar.swift
│ └── ServiceStatusBadge.swift
├── cli/ # 命令行工具（Swift 包）
│ ├── Package.swift
│ └── Sources/
│ ├── LM.swift
│ ├── Commands.swift
│ └── Helpers.swift
├── mcp-server/ # MCP 服务器（Swift 包）
│ ├── Package.swift
│ └── Sources/
│ ├── main.swift
│ ├── MCPServer.swift
│ └── ServiceManager.swift
├── scripts/
│ ├── create-dmg.sh
│ ├── install.sh
│ ├── generate-dmg-background.py
│ └── dmg-background.png
├── docs/
│ ├── ARCHITECTURE.md
│ ├── USAGE.md
│ ├── DEVELOPMENT.md
│ └── CHANGELOG.md
├── .github/workflows/release.yml
├── README.md
├── LICENSE
└── .gitignore
```
## 工作原理
图形用户界面和命令行工具在底层都使用 `launchctl` 子命令：
| 操作 | 命令 |
|--------|---------|
| 列出已加载 | `launchctl list` |
| 启动 | `launchctl kickstart -kp <target>` |
| 停止 | `launchctl kill SIGTERM <target>` |
| 加载 | `launchctl bootstrap <domain> <plist>` |
| 卸载 | `launchctl bootout <target>` |
| 启用 | `launchctl enable <target>` |
| 禁用 | `launchctl disable <target>` |
| 信息 | `launchctl print <target>` |
服务目标使用格式 `gui/<uid>/<label>` 用于用户/代理域，`system/<label>` 用于守护进程。
对于需要 root 的系统级操作，图形用户界面使用 AppleScript `with administrator privileges`，命令行工具使用 `osascript` 提示管理员凭证。
## 要求
- macOS 14.0（Sonoma）或更高版本
- Xcode 15.0+（用于从源代码构建）
- Swift 5.9+（用于命令行工具）
## 分发
### 未签名（个人使用）
```bash
./scripts/create-dmg.sh
# 接收者绕过 Gatekeeper：xattr -cr /Applications/ZLaunchManager.app
```
### 签名 + notarized（公共分发）
需要 Apple 开发者计划（99 美元/年）：
```bash
export DEVELOPER_ID="Zavora Technologies Ltd (TEAMID)"
export APPLE_ID="james.karanja@zavora.ai"
export APPLE_TEAM_ID="YOUR_TEAM_ID"
./scripts/create-dmg.sh
```
## 安全说明
- **无应用沙盒**（需要 launchd 访问权限）
- 系统拥有的服务（`/System/Library/`）是只读的
- 破坏性操作需要确认
- 特权操作通过标准 macOS 身份验证对话框提示
- 通用二进制文件（arm64 + x86_64）
## 相关项目
- **[LaunchManager](https://github.com/Sean10000/LaunchManager)** by Shi-Cheng Ma ([launchmanager.dev](https://www.launchmanager.dev/)) — 一个独立开发的 macOS launchd 管理器，其项目和公开设计文档早于此仓库。ZLaunch Manager 从独立开发，但因为 launchd 限制了解决方案空间，两个项目有相似的功能集和 macOS UI 模式。我们将我们的项目从“LaunchManager”重命名为“ZLaunch Manager”，以避免混淆，因为他们的项目先于我们的项目。如果您正在比较选项，请查看他们的项目。
其他值得了解的 launchd 工具：
- [LaunchControl](https://www.soma-zone.com/LaunchControl/) — 成熟的商业 launchd 图形用户界面
- [glowinthedark/pylaunchd](https://github.com/glowinthedark/pylaunchd) — Python launchd 图形用户界面
## 贡献
1. 分叉仓库
2. 创建一个功能分支（`git checkout -b feature/my-feature`）
3. 提交您的更改
4. 推送并打开拉取请求
## 许可证
Apache License 2.0 — 见 [LICENSE](LICENSE)
## 作者
**James Karanja Maina**
邮箱：james.karanja@zavora.ai
公司： [Zavora Technologies Ltd](https://zavora.ai)
---
Copyright 2024-2026 Zavora Technologies Ltd
