opencode-background-process

OpenCode 插件：在后台启动、监控、交互、终止长驻进程（dev server / 构建 / 监控脚本），不阻塞当前会话。纯 Node 实现，无 Bun 依赖，Windows / macOS / Linux 通用。

An OpenCode plugin for managing background processes: launch, monitor, read output, send input, and kill long-running tasks without blocking the session. Pure Node, no Bun dependency.

功能 / Features

工具 Tool	作用 Description
background_process_launch	后台启动命令（dev server / 构建 / 监控脚本），立即返回不阻塞
background_process_list	列出本会话启动的全部进程及状态
background_process_read	读取进程输出（stdout+stderr 合并，环形缓冲，默认 500 行）
background_process_write	向进程 stdin 写入输入（可交互）
background_process_kill	终止进程（含子进程树）
background_process_cleanup	清理已退出进程 / 一键终止全部

与其他插件对比 / Why this plugin

项目	运行时	状态	区别
@howaboua/opencode-background-process	Bun-only	维护中	名字相近，但依赖 Bun，Node 桌面版无法使用
zenobi-us/opencode-background	Bun-only	已归档	停更，无 Windows 专项支持
shekohex/opencode-pty	Bun-only	维护中	功能更全（PTY / Web UI），但需 Bun，非 Windows 优先

本插件是唯一 纯 Node 实现：

• Windows / macOS / Linux 通用，桌面版 Node 运行时直接可用
• Windows 中文输出自动解码（UTF-8 / GBK 探测，跨 chunk 边界正确处理）
• 进程随 OpenCode 退出自动清理（taskkill /T 杀进程树，无孤儿）

安装 / Installation

方式一：npm 声明（推荐，显示包名）

在 opencode.json 的 plugin 数组加入：

{
  "plugin": ["opencode-background-process"]
}

opencode 启动时自动安装并加载。

方式二：本地文件

复制 index.js 到全局插件目录：

# Windows
copy index.js %USERPROFILE%\.config\opencode\plugins\index.js
# macOS / Linux
cp index.js ~/.config/opencode/plugins/index.js

重启 opencode 生效。

使用示例 / Usage

在后台启动 python -m http.server 8000
列出所有后台进程
读取进程 npm-1 的最后 100 行输出
向进程 npm-1 发送 q 退出
终止进程 npm-1

特性 / Notes

• 进程随 OpenCode 退出而自动终止（process.on("exit") + 进程树终止），不留孤儿进程
• Windows 中文输出自动解码：UTF-8 / GBK 自动探测，跨 chunk 边界正确处理
• Windows 进程树终止：taskkill /T /F 递归终止，不会漏掉子进程
• 输出环形缓冲：默认保留最近 500 行，可自定义（10–10000）
• 自动 ID：npm-1、python-2 等（命令基名 + 序号），也可自定义
• 无 PTY：REPL / TUI 类交互程序不适用（纯管道）

限制 / Limitations

• 后台进程随 OpenCode 退出而终止，无法脱离宿主存活
• 无 PTY 支持，交互式终端程序（vim、REPL 等）无法使用
• 进程状态仅保存在内存中，重启 opencode 后历史记录丢失

License

MIT