persistproc

一个多代理开发工作流的共享进程层

---

完整文档：steveasleep.com/persistproc。

persistproc 是什么？

Persistproc 是一个 MCP 服务器和命令行工具，它允许代理和人类查看并控制长时间运行的进程，如 Web 服务器。其目标是减少在使用 AI 编码时需要复制粘贴的操作次数，使您更容易使用多个代理，并且与工具无关。

没有配置文件。进程完全在运行时进行管理。这不是 supervisord 的替代品。

示例用例：基本 Web 开发

假设您正在开发一个待办事项应用，该应用有一个通常通过 npm run dev 启动的开发服务器。此服务器会监视您的代码更改、类型检查、代码检查，并热重载页面。当出现错误时，它会在终端中打印错误信息。

如果您正在使用像 Cursor 或 Claude Code 这样的 LLM 代理，如果看到错误，您可能会从终端复制/粘贴到代理并询问如何修复。然后代理可能会做出一些更改，也许您会遇到另一个错误，所以您再次复制/粘贴，代理再做一次更改……等等。

如果代理可以直接看到这些更改，您就无需做任何事情！通过 persistproc，这是可能的。代替说 npm run dev，您可以说 persistproc npm run dev，这样代理可以立即读取其输出甚至重新启动它。否则，您仍然可以在原始终端中看到其输出，并使用 Ctrl+C 杀死它，就像您通常做的那样。

graph TB
    User[用户] -->|"persistproc npm run dev"| PP[persistproc 服务器]
    PP <-->|"管理和日志"| NPM["npm run dev<br/>(Web 服务器)"]
    PP -.->|"流输出"| User
    
    Agent[Cursor] -.->|"output()<br/>restart()"| PP
    
    style PP fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    style NPM fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style User fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    style Agent fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px

[!NOTE] 为什么不直接使用 Cursor 并让代理打开终端？

1. 不是每个人都喜欢在 Cursor/VSCode 中使用终端。工程师有许多不同的工作流程。
2. 只有 Cursor 的代理可以看到这个进程，而 Claude Code、Gemini CLI 等则不行。

示例用例：复杂 Web 开发

假设您需要运行四个进程才能在本地让 Web 应用正常工作。可能是 API、前端服务器、SCSS 构建器和 Postgres。每个服务都会发出自己的日志。

如果您在本地测试时遇到错误，您可以去阅读所有四个日志文件以找出发生了什么。

但如果您使用 persistproc 启动了这些进程，那么代理可以一次性读取所有内容，并可能更快地给出诊断。

graph TB
    User[用户] -->|"启动进程"| PP[persistproc 服务器]
    
    subgraph processes["管理进程"]
        API[API 服务器]
        FE[前端服务器]
        SCSS[SCSS 构建器]
        DB[Postgres]
    end
    
    PP <-->|"管理和日志"| processes
    
    Agent1[Claude Code] -.->|"读取日志<br/>诊断问题"| PP
    Agent2[Cursor] -.->|"读取日志<br/>诊断问题"| PP
    
    style PP fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    style API fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style FE fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style SCSS fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style DB fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style User fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    style Agent1 fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    style Agent2 fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    style processes fill:#f5f5f5,stroke:#999,stroke-width:1px,stroke-dasharray: 5 5

[!NOTE] 如果我的进程是由另一个系统启动的怎么办？

那么您最好的选择是将日志文件写入一个可预测的位置，并告诉代理它们在哪里， 而不是尝试使用 persistproc。或者，您可以关注 GitHub 上的这个问题。

目前，persistproc 最有用的情况是您希望代理能够 管理 进程，而不仅仅是查看它们的输出。

可用工具

persistproc 在 http://127.0.0.1:8947 暴露了一个标准的 Model Context Protocol (MCP) 服务器。您可以使用任何兼容 MCP 的客户端来编程地与其交互。

服务器暴露以下工具：

工具	描述
ctrl	统一进程控制：启动、停止或重启进程。
list	列出所有管理的进程及其状态。可选地按 PID、命令或工作目录过滤，并提供日志路径。
output	从进程中检索捕获的输出。

此列表有意保持简短，因为 LLM 在面对过多工具时表现不佳，以至于某些 IDE（如 Cursor）对您能拥有的工具数量有限制。

快速开始

1. 安装 persistproc

pip install persistproc

2. 启动服务器并配置您的代理

在一个专用终端中运行此命令并保持运行。

persistproc serve

persistproc serve 输出的第一件事是各种代理的配置说明，因此如果您还没有这样做，请遵循这些说明。

3. 启动一个进程

在另一个终端中，cd 到您的项目目录并通过 persistproc 运行您的命令。

# 示例：启动 Node.js 开发服务器
cd /path/to/your/project
persistproc npm run dev

命令被发送到服务器，其输出被流式传输到您的终端。您可以安全地关闭此终端，进程将继续运行。

[!TIP] 或者只需让您的代理“使用 persistproc 运行您的开发服务器”，它可能会通过查看您的 package.json 文件找到正确的命令并使用 persistproc 运行它。

这样一来，您的代理现在就可以使用可用工具来管理您的开发环境。

示例代理交互

一旦您的代理连接上，您可以要求它管理您的进程。假设您已经通过 persistproc npm run dev 启动了一个 Web 服务器（PID 12345），现在您可以与其互动。

• 您："列出正在运行的进程。"

  • 代理：调用 list() 并显示正在运行的 npm run dev 进程。

• 您："Web 服务器似乎卡住了。你能重启它吗？"

  • 代理：识别正确的进程并调用 ctrl(action="restart", pid=12345)。

• 您："给我看看来自 Web 服务器的任何错误。"

  • 代理：调用 output(pid=12345, stream="stderr") 以检索最新的错误日志。

开发

在完全配置的虚拟环境中运行 persistproc 使用 ./pp。在虚拟环境中运行其他命令，如 pytest 使用 uv run。

许可证

本项目采用 MIT 许可证。