前言¶
在本地编码环境中，通过 bash 启动长生命周期的进程常会遇到“僵尸进程”问题：智能体忘记了进程的 PID，端口保持占用，下一次启动时遇到 EADDRINUSE 错误。这往往导致智能体误判为代码逻辑错误，而实际上只是端口冲突。
这是什么¶
dsh-agent-processes 是 DeepSeek Harness Web UI 的一个插件，由 janpauldahlke 维护，旨在为主机拥有的进程和端口提供完整生命周期管理。它为智能体提供了第一流的控制能力，包括启动/停止/列表/日志/等待就绪，并通过 UI 提供持久化的存储视图和交互面板。
核心功能¶
该插件提供以下核心能力：
- 进程控制：支持
process_start、process_stop、process_list、process_logs、process_wait_ready和process_ping。 - 端口回收：启动带端口的进程时，会自动回收已被跟踪的端口占用者；对于未被跟踪的持有者，插件会拒绝连接，而非直接杀死进程。
- UI 面板：
- Processes Rightbar：跟随聊天工作区，显示状态点、ID/端口、PID/运行时长、命令、工作目录、日志预览，并提供 Kill/Restart/Clear 按钮。
- Dock Chip：当右栏关闭且工作区有运行进程时，显示芯片提示（如
Processes · :3000），点击打开面板。
安装与启用¶
安装此插件需要 DeepSeek Harness 的 Web 配置文件（dsh web）以及 Node.js 环境版本 ≥ 20。
dsh plugin --profile web add dsh-agent-processes
安装后，重启 dsh web 或依赖热更新加载插件，并在浏览器端进行硬刷新以加载客户端代码。
典型用法¶
在智能体工作流中，使用插件提供的工具代替原始的 Shell 命令和 sleep，可以避免端口冲突和进程丢失。
- 启动进程：使用
process_start启动进程。如果该进程监听端口，必须在参数中包含port。 - 等待就绪：使用
process_wait_ready替代sleep。它会轮询直到端口可连接（或超时），确保进程已准备好接收流量。 - 检查状态：在假设端口空闲之前，使用
process_list检查当前跟踪的进程记录。 - 停止进程：使用
process_stop停止进程。
适用场景与注意¶
- 适用场景：本地开发服务器、文件监控服务、长期运行的 Node.js 服务等需要保持运行的进程。
- 安全限制：插件仅能终止它所跟踪的 PID；对于未被跟踪的外部进程占用端口，插件会拒绝连接（
refused），而不会强制杀死该进程。用户需手动清理这些外部进程或切换到其他端口。 - 已知限制：插件不包含日志轮转功能；日志为追加模式；崩溃检测依赖于存活探针，而非信号监听；不存在基于会话的隔离，存储库是针对 Web 配置文件的。
结语¶
dsh-agent-processes 解决了本地编码环境中进程生命周期管理的痛点，确保端口可用性和进程可控性。通过提供标准化的工具接口和直观的 UI，它让智能体在处理长任务时更加稳定。
