JohnXu22786/pty-runner

README excerpt

backstage 后台终端作业管理插件 ，为 DeepSeek Harness（dsh）提供持久的后台进程（PTY）管理能力。 AI agent 在跑开发服务器、watch 任务、长时构建等进程时，普通的一次性 shell 调用无法胜任：进程会随调用结束被回收，agent 也拿不到交互输入与后续输出。本插件把这类进程放进 独立的后台终端会话 （job），agent 可以随时： - 启动进程并让它独立运行（PTY，支持交互程序） - 向进程写入输入（普通文本或 \x03 这类控制序列） - 分页读取进程输出（环形缓冲、正则过滤、断点续读） - 按状态/分组查看所有作业 - 优雅或强制终止进程，并在插件卸载时统一清理 功能一览 能力 说明 后台运行 进程在独立伪终端中运行，不随工具调用结束而退出 多作业并发 同时管理任意数量的作业，每个作业独立缓冲与状态 交互输入 写入普通文本与转义控制序列（Ctrl+C、方向键、ESC 等） 环形输出缓冲 每作业保留最近 N 行（默认 5000），自动剥离终端转义序列 分页读取 按全局行号断点续读，支持正则过滤（类似 grep）与忽略大小写 退出检测 区分正常结束（exit 0）、崩溃（非零退出码/信号）与主动终止 端口提示 启动前检查目标端口占用；自动从输出中识别服务地址（如 http://localhost:5173 ） 分组管理 作业打组标签，可一键停止整组 超时保护 可选 timeoutMs ，超时自动终止作业 退出通知 可选：作业结束时向会话注入一条通知（无需轮询） 跨平台 Windows（ConPTY）/ macOS / Linux；无原生模块时自动降级为管道后端 安装 要求：Node.js ≥ 20，npm 或 pnpm。 方式一：作为 bundle 装入 profile（推荐） 在任意目录（例如本插件目录的上层）安装 dsh CLI 后： dsh plugin add 会完成三件事：把本包链接进 profile 的依赖、把 dsh-backstage 追加到 dsh.profile.bundles 、并应用本包 cordis.patch.yml 中声明的插件行。之后 dsh plugin --profile demo remove dsh-backstage 可完整卸载。 方式二：作为 overlay 加载（本地开发） 本包自带的 cordis.patch.yml 声明插件行，也可以直接用 --patch 挂载到任意 profile： Windows 注意 ：patch 里的 name 若指向本地文件，必须写成 file:/// URL 形式， 否则加载器会报 ERR UNSUPPORTED ESM URL SCHEME 。示例： 以 bundle 方式安装（方式一）时 name 解析为包名，无此限制。 启动…

Category