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

FilesExpand file tree

README.md

Latest commit

History