用途
Overmind 是一个基于 tmux 的进程管理器，本技能用于将 Overmind 配置为对智能体（agent）友好的开发服务器进程管理器。相比 Foreman，Overmind 的关键优势在于：守护进程模式、可单独重启某个进程，以及通过 overmind connect 进行交互式调试。
使用场景：搭建新项目的开发环境、向 Procfile 添加服务，或让智能体管理开发服务器进程。
依赖：需要 tmux（在 macOS 上通过 brew install overmind 会自动安装）。
主要能力
- 通过 Procfile.dev 定义多个开发服务，每行一个服务（格式为
name: command）。 - 提供
bin/devbash 包装脚本，支持 start、stop、restart、status、logs、help 等子命令。 - 通过
.overmind.env配置 socket 路径与推荐设置。 - 支持守护进程模式运行，便于智能体和开发者持续工作。
- 支持单独重启某个服务、查看进程状态与 URL、跟踪日志。
- 支持将参数直接透传给 Overmind。
使用方式
初始化清单
- 项目根目录放置
Procfile.dev，每行一个服务（name: command）。 - 创建
bin/devbash 包装脚本，包含子命令（start、stop、restart、status、logs、help）。 - 创建
.overmind.env，配置 socket 路径与推荐设置。 - 创建
tmp/.keep并由 git 跟踪；.gitignore中包含/tmp/*与!/tmp/.keep。
.overmind.env 推荐设置
OVERMIND_SOCKET=tmp/overmind.sock
OVERMIND_NO_PORT=1
OVERMIND_CAN_DIE=css
各设置说明：
OVERMIND_SOCKET=tmp/overmind.sock：保持项目根目录整洁，避免 macOS 104 字符 socket 路径限制。OVERMIND_NO_PORT=1：阻止 Overmind 注入 PORT=5000/5100/5200，避免覆盖 Procfile 中显式的端口变量。OVERMIND_CAN_DIE=css：Tailwind 监听进程崩溃时不会拖垮整个进程栈。
可选：OVERMIND_AUTO_RESTART=css 可在监听进程崩溃时自动重启。
关键设计决策
- 对引擎/库类项目默认使用守护进程——
bin/dev以守护方式运行，使智能体和开发者可以继续工作；调试时用-f参数切换到前台。对应用类项目，默认前台可能更好（崩溃可立即被发现）。 - 每条 overmind 命令都显式加上
-s "$SOCKET"——不要只依赖.overmind.env。socket 参数不受当前工作目录影响，这对会 cd 到子目录的脚本很重要。 - socket 放在
tmp/下——保持项目根目录整洁（Rails 惯例）。 - 处理陈旧 socket——
bin/dev在启动前清理陈旧 socket（防止“already running”错误）；bin/dev stop在overmind quit失败时回退为删除 socket。
bin/dev 命令
| 命令 | 作用 |
|---|---|
bin/dev |
以守护进程方式启动（默认） |
bin/dev -f |
前台启动 |
bin/dev stop |
停止运行中的实例 |
bin/dev restart web |
重启指定服务 |
bin/dev status |
显示进程状态与 URL |
bin/dev logs |
跟踪所有日志 |
bin/dev logs web |
跟踪指定服务的日志 |
bin/dev -- -l web,css |
将参数直接传给 overmind |
Procfile 模式
# 标准 Rails
web: bin/rails server -p ${PORT:-3000}
css: bin/rails tailwindcss:watch
# 使用显式端口变量（配合 OVERMIND_NO_PORT=1）
web: cd lookbook && bin/rails server -p ${LOOKBOOK_PORT:-4001}
docs: cd docs && bin/bridgetown start -P ${DOCS_PORT:-4000}
# 带 worker
worker: bundle exec sidekiq
智能体工作流
- 检查状态：
bin/dev status 2>/dev/null && echo "running" || echo "not running" - 以守护方式启动：
bin/dev（绝不用前台——会阻塞终端） - 修改
lib/后：bin/dev restart web（app/下的改动会自动加载） - 读取日志：
bin/dev logs web（单个进程）或bin/dev logs（全部） - 会话结束时保持运行——由用户自行执行
bin/dev stop停止。
常用 Overmind 参数
| 参数 | 用途 |
|---|---|
-D |
守护进程化 |
-f FILE |
指定 Procfile 路径 |
-s SOCKET |
指定 socket 路径 |
-r PROCESS |
崩溃时自动重启（-r all 表示全部） |
-l PROCESS |
只启动指定进程（-l web,css） |
-N |
禁用自动 PORT 分配（等同于 OVERMIND_NO_PORT=1） |
适用场景
- 搭建新项目的开发环境。
- 向 Procfile 添加服务。
- 让智能体以非阻塞方式管理开发服务器进程。
- 需要单独重启某个服务或查看各服务日志的开发流程。
限制与常见陷阱
- 陈旧 socket：崩溃/重启后，
overmind start会提示“already running”。修复：rm tmp/overmind.sock（或让bin/dev处理）。 - 端口遮蔽：未设置
OVERMIND_NO_PORT=1时，Overmind 会为每个进程注入 PORT=5000/5100/5200，覆盖显式端口变量。 - socket 路径长度：macOS 将 Unix socket 路径限制为 104 字符。使用相对路径
tmp/overmind.sock可避免此问题。切勿使用$TMPDIR。 - 嵌套 tmux：若已在 tmux 内，
overmind connect会嵌套会话。使用 Ctrl-b Ctrl-b d（双前缀）分离。