Background Process Manager

后台进程管理器

一个专门的MCP（模型上下文协议）服务器，用于管理开发流程，支持零停机重启、自动崩溃恢复以及智能的开发/发布模式切换。

特点/功能

• 零停机重启先构建，然后切换到新二进制文件
• 自动崩溃恢复可配置的退避策略，适用于开发和发布模式
• 开发/发布模式切换在一段时间无操作后自动切换到发布模式
• Direnv 集成自动检测并使用 .envrc 用于环境变量
• 日志管理具有搜索功能的内存中环形缓冲区
• MCP协议与Claude及其他MCP客户端无缝集成

用例

这个工具专为爱好项目和原型设计，即使在您不主动开发时也能保持运行。与传统进程管理器不同，它在开发过程中优先考虑快速迭代（使用 cargo run）同时在空闲时仍能切换到优化后的发布版本进行构建。

安装

cargo build --release

该二进制文件将位于 target/release/background-process-manager。

配置

创建一个 .mcp-run 在你的项目目录中找到文件：

# Port for the MCP server to listen on
mcp_port = 3001

# Time in hours before switching to release mode (optional, default: 3)
dev_timeout_hours = 3

# Wait time in seconds after a crash in dev mode (optional, default: 120)
dev_crash_wait_seconds = 120

# Initial backoff in seconds for crash recovery in release mode (optional, default: 1)
release_crash_backoff_initial_seconds = 1

# Maximum backoff in seconds for crash recovery in release mode (optional, default: 300)
release_crash_backoff_max_seconds = 300

# Define processes to manage
[process.main]
type = "rust"
args = ["--port", "8080"]

# Optional: NPM sidecar process
# [process.frontend]
# type = "npm"
# command = ["npm", "run", "dev"]

使用

运行管理器

background-process-manager /path/to/project

或者使用 systemd：

[Unit]
Description=Background Process Manager for MyProject
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/project
ExecStart=/path/to/background-process-manager /path/to/project
Restart=always

[Install]
WantedBy=multi-user.target

MCP 工具

服务器提供了四个MCP工具：

1. search_logs

使用可选的正则表达式模式和过滤条件搜索进程日志。

{
  "process": "main",
  "pattern": "error.*timeout",  // optional regex
  "context_lines": 2,             // optional: lines around matches
  "head": 50,                     // optional: first N lines
  "tail": 100,                    // optional: last N lines
  "index": -1                     // optional: -1 = most recent, -2 = previous, etc.
}

2. search_build_log

搜索构建日志（参数与 search_logs）。

3. restart

重启一个进程。首先进行构建（针对Rust项目），然后重启。自动切换回开发模式。

{
  "process": "main"
}

4. get_status

获取所有进程的状态，包括模式、运行时间、状态以及最近发生的事件。

{}

它是如何运作的

进程生命周期

1. 初始启动开始于 发布模式 （设计用于系统启动场景），构建时使用 cargo build --release 并启动该过程
2. 崩溃恢复:

- 开发者模式：重启前等待2分钟（可配置），以便您有时间进行调查 - 发布模式：使用次指数级退避（1秒、1.5秒、2.25秒，...，最长可达5分钟）

1. 自动释放开关在3小时（可配置）内未调用任何工具后，若当前处于开发模式，则以发布模式重新构建
2. 手动重启当你调用 restart 工具，切换到开发模式以加快迭代速度

零停机重启

当你打电话时 restart：

1. 手动重启标志已设置，以防止崩溃监视器干扰
2. 构建在后台开始（旧进程继续运行）
3. 构建完成后，停止旧进程（发送SIGTERM信号，5秒宽限期，然后发送SIGKILL信号）
4. 新流程立即开始
5. 手动重启标志已清除

这意味着编译时间不会增加停机时间——只有切换进程的短暂瞬间。手动重启标志确保崩溃监控器不会干扰，并且重启不会被计为崩溃。

Direnv 支持

如果一个 .envrc 文件存在于您的项目目录中，所有命令（构建、运行）都被封装在 direnv exec。

记录日志

所有受管理的进程和构建过程的输出均为：

• 捕获到内存中的环形缓冲区（可通过MCP工具进行搜索）
• 传递到标准输出/标准错误流（stdout/stderr）中，使用 [process_name] 或者 [build] 前缀

这意味着，当作为 systemd 服务运行时，日志会出现在 journalctl 中，同时仍然可以通过 MCP 接口进行搜索。

连接到Claude代码

将MCP服务器添加到您的Claude代码配置中（~/.config/claude-code/config.json)：

{
  "mcpServers": {
    "ganbot": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

一旦连接成功，您就可以直接在Claude Code中使用MCP工具：

• search_logs - 搜索进程日志以查找错误或模式
• search_build_log - 检查构建输出以查找编译问题
• restart - 在代码更改后重建并重新启动您的进程
• get_status - 检查当前模式、运行时间以及最近事件

示例：与ganbot一起使用

# Create configuration
cat > ~/dev/ganbot/.mcp-run << 'EOF'
mcp_port = 3001
dev_timeout_hours = 3

[process.main]
type = "rust"
args = []
EOF

# Start the manager
background-process-manager ~/dev/ganbot

# Now connect from Claude Code using the configuration above

TUI（终端用户界面）

提供了一个内置的TUI（文本用户界面），用于手动与MCP服务器进行交互：

# Run the TUI (connects to default localhost:3001)
bpm-tui

# Or specify a custom MCP server URL
bpm-tui http://localhost:3001/mcp

TUI功能

TUI提供了一个包含四个面板的综合仪表盘：

• 服务器状态 （左上角）：连接状态、模式、进程数、状态消息
• 处理详情 （右上角）：选定的进程信息、运行时间、事件、崩溃次数
• 流程；过程 （左下角）：所有管理进程的列表，带有状态指示器
• 输出 （右下角）：所选进程的实时日志

TUI 快捷键

• ▲▼ 或者 j/k - 浏览进程列表
• Enter - 刷新选定进程的日志
• r - 重启所选进程（先重建，然后重启）
• c - 清晰的输出面板
• q 或者 Esc - 退出

TUI状态指示器

• 🟢 绿色 ▶ - 进程正在运行
• 🟡 黄色 ■ - 进程已停止/处于空闲状态
• 🔴 红 ✗ - 进程已崩溃

TUI（文本用户界面）每秒自动刷新状态，并为所有操作提供实时反馈。

建筑

┌─────────────────────────────────────┐
│  MCP Client (Claude Code)           │
└─────────────┬───────────────────────┘
              │ JSON-RPC over HTTP/SSE
┌─────────────▼───────────────────────┐
│  MCP HTTP Server (port 3001)        │
│  Endpoint: /mcp                     │
│                                     │
│  Tools:                             │
│  - search_logs                      │
│  - search_build_log                 │
│  - restart                          │
│  - get_status                       │
└─────────────┬───────────────────────┘
              │
    ┌─────────┴─────────┐
    │                   │
┌───▼────────┐  ┌───────▼──────┐
│ Builder    │  │ Mode Manager │
│ - cargo    │  │ - Dev/Release│
│ - direnv   │  │ - Timeouts   │
└───┬────────┘  └──────────────┘
    │
┌───▼──────────────────────────┐
│ Process Manager              │
│ - Spawn/Stop                 │
│ - Log capture                │
│ - Crash detection            │
│ - Manual restart flag        │
└───┬──────────────────────────┘
    │
┌───▼──────────────────────────┐
│ Your Application (ganbot)    │
└──────────────────────────────┘

局限性

• 仅在Linux上测试过（使用Unix信号）
• 仅内存日志（管理器重启时丢失）
• 不支持进程依赖
• 基本健康检查（进程运行 = 健康）

未来的改进/增强

• 自定义构建命令
• 过程依赖排序
• 健康检查端点
• 持久化日志存储
• Windows支持
• 进程资源限制

许可证

麻省理工许可证（或您喜欢的任何许可证）