proc-cli

proc CLI —— 进程管理工具

proc 是一款用于管理 macOS、Linux 和 Windows 上进程与端口的语义化 CLI。你可以按端口（:3000）、PID、名称、文件或目录指定目标，并且每条命令都可以返回单个 JSON 文档。

开始之前

• 检查是否已安装：proc --version。本文档介绍的是 proc 1.14.3（proc inspect 和 uptime_secs 需要 1.14 或更高版本）。
• 如果尚未安装，先征求用户同意再安装。可选方式：brew install yazeed/proc/proc（macOS）、cargo install proc-cli、npm install -g proc-cli、scoop bucket add proc https://github.com/yazeed/scoop-bucket-proc && scoop install proc（Windows）或 nix profile install github:yazeed/proc。

关键规则

1. 每条命令都必须传入 --json，以获取结构化输出
2. 执行破坏性命令时必须传入 --yes，跳过交互式提示
3. 执行破坏性操作前使用 --dry-run，预览将执行的操作
4. 检查退出码：0=成功，1=一般错误（包括部分失败和 wait 超时），2=未找到，3=权限被拒，4=输入无效。"success": false 始终伴随非零退出码
5. 使用 --json 时的错误会在标准输出中生成 {"action":"<cmd>", "success":false, "error":"...", "exit_code":N}，包括无效标志或参数
6. 每个 JSON 响应都是单个文档（watch 流除外），包含 action（命令名称，别名已解析）和 success 字段
7. 只操作由你启动或由用户指定的进程。 优先使用端口和 PID 作为目标；使用 --in <dir> 或 --by <name> 限定名称目标的范围
8. 退出码 3 表示需要更高权限。 使用 sudo 重试前先征求用户同意

用 proc 替代

替代方式	使用
lsof -i :3000、netstat -tlnp、ss -tlnp	proc on :3000 --json、proc ports --json
lsof -ti :3000 | xargs kill -9	proc free :3000 --yes --json（终止进程后验证端口已释放）
ps aux | grep node、pgrep -f node	proc by node --json，或使用多个模式：proc list 'node,vite' --json
pkill -f pattern	先运行 proc kill pattern --in . --dry-run --json，然后添加 --yes 再运行
kill PID、kill -9 PID	proc stop PID --yes --json、proc kill PID --yes --json
kill -STOP / kill -CONT	proc freeze / proc thaw
while kill -0 $PID; do sleep 1; done	proc wait PID --timeout 60 --json
lsof /path/to/file	proc for /path/to/file --json
pstree、ps -o ppid=	proc tree PID --json、proc why PID --json
top、ps aux --sort=-%cpu	proc list --sort cpu --limit 10 --json

目标语法

大多数命令接受相同的目标格式：

• :3000 —— 正在端口 3000 上监听的进程
• 1234 —— PID 为 1234 的进程
• node —— 名称与“node”匹配的进程（按名称和命令行进行子串匹配）
• :3000,:8080,node —— 以逗号分隔的多个目标，按 PID 去重

例外：proc free 仅接受端口，proc for 接受文件路径，proc in 接受目录。

你可能会看到用户输入的别名：:（on）、f（for）、b（by）、l/ps（list）、i/inspect（info）、p（ports）、k（kill）、s（stop）、t（tree）、w/top（watch）、x（stuck）、u（unstick）、o（orphans）。JSON action 始终使用完整名称。

命令

发现（只读，无需 --yes）

proc on :3000 --json              # what process is on port 3000?
proc on 1234 --json               # what ports does PID 1234 use?
proc on node --json               # what ports are node processes using?
proc for ./server.py --json       # what's running (or holding open) this file?
proc by node --json               # find processes by name
proc by node --in . --json        # ...started from the current directory
proc in . --json                  # all processes whose cwd is under this directory
proc in ~/project --by node --json
proc list --json                  # all processes
proc list --min-cpu 10 --json     # processes using >10% CPU
proc list --status stopped --json # frozen/stopped processes
proc list --path /usr/local/bin --json  # filter by executable path
proc info :3000,1234 --json       # inspect one or more targets: full details
proc ports --json                 # all listening ports
proc ports --exposed --json       # only ports bound to 0.0.0.0 / ::
proc ports --local --json         # only ports bound to 127.0.0.1 / ::1
proc ports --range 3000-3999 --json
proc why :3000 --json             # trace ancestry — why is this port busy?
proc tree node --json             # descendants of node processes
proc tree 1234 --ancestors --json # path from the top ancestor down to PID 1234
proc orphans --in . --json        # processes whose parent died (reparented to PID 1)
proc stuck --json                 # processes >50% CPU running longer than --timeout (default 300s)

检查进程时，使用 proc info（别名：inspect、i；JSON action 始终为 "info"）。对于每个目标，它会报告名称、PID、命令行、可执行文件路径、工作目录、用户、父 PID、状态、CPU、内存、启动时间和运行时长。list、by 和 in 一次返回多个进程的相同字段。

生命周期（破坏性操作——始终使用 --yes --json）

proc kill :3000 --yes --json               # force kill (SIGKILL)
proc kill node --in . --graceful --yes --json  # SIGTERM instead of SIGKILL
proc stop node --yes --json                # SIGTERM, then SIGKILL after --timeout (default 10s)
proc stop nginx --signal HUP --yes --json  # send a different initial signal
proc freeze node --yes --json              # pause (SIGSTOP)
proc thaw node --yes --json                # resume (SIGCONT)
proc free :3000 --yes --json               # kill + verify port is free (--wait, default 10s)
proc free :3000,:8080 --yes --json         # free multiple ports
proc unstick 1234 --yes --json             # SIGCONT then SIGINT; no kill
proc unstick 1234 --force --yes --json     # ...then SIGTERM, SIGKILL if still stuck
proc orphans --in . --kill --yes --json    # kill orphans whose cwd is under this directory

监控

proc wait node --timeout 60 --json       # block until all node processes exit (max 60s)
proc wait :3000 -n 1 -q --timeout 30 --json  # poll every 1s, quiet
timeout 10 proc watch node --json        # NDJSON stream, one object per refresh (-n seconds)

操作指南

端口被占用（EADDRINUSE，“地址已在使用中”）

proc on :3000 --json        # who holds it? check name, cwd and command
proc why :3000 --json       # what started it (ancestry)
proc free :3000 --yes --json  # only if it's yours or the user agreed

如果占用端口的是用户自己的应用、另一个项目或其他 Agent 的服务，请先征求用户同意再释放端口，或在其他端口启动你的服务。

在后台运行服务或任务，然后进行清理

• 启动时记下端口或 PID。根据目标停止进程：proc stop :4789 --yes --json 或 proc kill 12345 --yes --json。
• 不要使用从你输入的命令中复制的名称模式来停止进程。实际命令行通常不同（bunx serve 会以 node …/serve 的形式运行），因此该模式可能会悄无声息地匹配不到任何进程。
• kill 和 stop 只会向指定目标进程发送信号，不会发送给其子进程。终止 npm run dev 可能会留下 node 或 ts-node 子进程。检查 proc tree PID --json，并将子进程也作为目标；或者按端口停止。
• 确认进程已退出：如果没有进程正在监听，proc on :4789 --json 会以状态码 2 退出。

完成任务前，检查是否有残留进程

proc ports --in <project-dir> --json      # servers you left listening
proc orphans --in <project-dir> --json    # processes whose parent already exited
proc list 'headless,ms-playwright,puppeteer' --json   # headless browsers

--in 会匹配进程的工作目录，因此要传入进程运行时所在的目录（即你执行 cd 进入的目录），该目录可能不是你自己的当前工作目录。停止残留进程前，先检查 proc why PID --json。如果该进程的祖先进程链指向另一个 Agent 会话、编辑器或用户的终端，就不要终止它：应报告该进程。

机器运行缓慢

proc list --sort cpu --limit 10 --json
proc list --min-mem 1000 --sort mem --json   # over 1 GB
proc stuck --json                             # sustained high CPU

报告你发现的情况，并列出每个进程的 cwd、uptime_secs 和 parent_pid，由用户决定要停止哪些进程。

正确重启服务

proc stop :3000 --yes --json   # SIGTERM, SIGKILL after 10s
proc on :3000 --json           # exit 2 = nothing listening; safe to start again

proc free :3000 --yes --json 一步完成所有操作：发送 SIGTERM，最多 5 秒后发送 SIGKILL，然后检查端口是否已释放。对于预计会自行退出的进程，请使用 proc wait：如果没有匹配的进程，它会立即以状态码 2 退出。

安全

• 名称目标会匹配 proc 能看到的、名称或命令行中包含该模式的所有进程：其他项目、编辑器、用户的终端，以及其他 Agent 的 MCP 服务和浏览器。始终先对名称目标使用 --dry-run，并使用 --in 限定范围。
• proc 按名称匹配时，永远不会匹配自身进程或其父进程链上的进程（最多向上追溯 10 层），因此在 Agent 内部运行 proc by claude 时，不会包含该 Agent。PID 和端口目标不受此保护。
• 不要一开始就使用 kill（SIGKILL）。优先使用 stop，给进程留出清理时间。

过滤器

并非每个命令都支持所有过滤器 — 请查看 proc <cmd> --help。

过滤器	命令
--in [dir]（-i，默认为 .）	除 why、free、in 外的所有命令
--by <name>（-b）	除 why、free、by 和 list 外的所有命令（这两个命令将名称作为参数）
--min-cpu <pct>、--min-mem <MB>	list、by、in、for、tree、watch
--status <s>（running、sleeping、stopped、zombie）	list、by、in、for、tree
--min-uptime <secs>	list、by、in、for、tree
--parent <pid>	list、by、in
--path <path>（-p，可执行文件路径）	list
--sort <key>（cpu、mem、pid、name）	list、by、in、for、watch
--sort <key>（port、pid、name）	ports
--limit <n>（-n；watch 使用 -l）	list、by、in、for、ports、watch
--depth <n>（-d，默认为 10）、--compact（-C，仅显示 PID）	tree

输出架构

如需完整的 JSON 输出架构和字段定义，请参阅 reference.md。进程最常用的字段包括：pid、name、command、cwd、parent_pid、user、status、cpu_percent、memory_mb、start_time、uptime_secs。

Agent／管道使用须知

• 单次查询：on、for、by、in、list、info、ports、why、tree、orphans、stuck — 立即返回
• 阻塞操作：proc wait — 始终传入 --timeout
• 流式输出：proc watch --json — 无限输出 NDJSON；使用 timeout N 或 | head -n N 限定输出范围。不带 --json 且没有 TTY 时，它会打印一次快照。要获取单次快照，优先使用 proc list
• 破坏性操作：kill、stop、freeze、thaw、free、unstick，以及带 --kill 的 orphans／stuck — 始终传入 --yes --json
• 向用户展示结果：运行时不带 --json，以便输出易读的表格（在宽度为 100 列或以上的终端中会显示 UPTIME 列）

注意事项

• 端口目标必须以 : 开头 — proc on 3000 会查找 PID 3000，而不是端口 3000。
• proc free 只接受端口目标（:3000）。名称或 PID 目标请使用 proc kill。
• 名称匹配基于子字符串：proc by node 会匹配 "node"、"nodejs"、"nodemon"。使用 --in 缩小范围，或使用 PID。
• proc by 接受一个模式；proc list 接受多个以逗号分隔的模式：proc list 'git commit,pre-commit' --json。模式是普通的不区分大小写的子字符串，会与名称和完整命令行进行匹配，并非正则表达式。
• JSON 中的运行时长字段是 uptime_secs（单位为秒）。start_time 是 Unix 时间戳，不是持续时长。
• 进程可能会继续在已删除的目录中运行（例如已移除的 worktree），而这类进程往往正是你要找的残留进程。从 proc 1.14.1 开始，proc in <dir> 会列出这些进程，cwd 显示纯路径。在 1.14.0 及更早版本中，proc in <dir> 遇到已删除目录会以退出码 4 退出，因此请改用 proc list --in <dir> 或 proc orphans --in <dir>（在 macOS 上；在 Linux 上，这些版本无法找到它们，因为内核会将其 cwd 报告为 <dir> (deleted)）。
• --dry-run --json 会输出 "dry_run": true，以及将受影响的 processes；不会更改任何内容。
• proc orphans --kill 和 proc stuck --kill 的报告格式与 proc kill 相同（succeeded/failed），其中 action 为 "orphans"/"stuck"。
• 如果 kill/stop/freeze/thaw/orphans --kill/stuck --kill 中有任何进程操作失败，退出码为 1，且 failed 会列出失败原因；succeeded 中的进程仍已执行相应操作。
• proc wait 超时后会输出结果，其中包含 timed_out: true，并以退出码 1 退出。
• --signal 仅适用于 proc stop。有效信号：HUP、INT、QUIT、ABRT、KILL、TERM、STOP、CONT、USR1、USR2（可带或不带 SIG，大小写不限）。
• --graceful 仅适用于 proc kill。
• 未知标志会以退出码 4 退出；使用 --json 时，错误会作为 JSON 对象输出到 stdout，否则会以纯文本输出到 stderr。
• freeze 和 thaw 仅适用于 Unix — 在 Windows 上会以退出码 1 失败。
• proc stuck 是一种启发式检测（持续高 CPU），不是挂起检测器。
• 孤儿进程（父 PID 为 1）不一定是被遗弃的：守护进程和 tmux/nohup 作业本来就会成为孤儿进程。将其视为残留进程前，请检查 cwd、command 和运行时长。