前言¶

在 DeepSeek Harness（DSH）里，Agent 常用的一次性命令工具是「提交 → 等进程完全结束 → 再拿结果」。中间不能向进程喂输入、不能中断前台命令，超时也看不到进展。分钟级任务可以用后台跑命令的方式，但若命令会一直活着、或需要中途输入、SIGINT 后还要在同一 shell 里继续，一次性命令就不够用。

下面介绍社区插件 dsh-background-terminal（维护者 AkezI-T，分类：工作流）。它在 DSH 里为 Agent 提供跨工具调用、跨模型回合仍可续用的交互式 shell，用一组 terminal_* 工具补齐读写、中断与增量读输出等能力。

这是什么¶

dsh-background-terminal 的定位是：一次调用开一个交互式 shell，首条命令写入 stdin；之后可反复读增量输出、写输入、用 SIGINT 中断前台命令后继续用同一个 shell，任务结束再关闭会话。

判据可以简化为：这条命令会不会「活着」跨越你的下一步。

• 秒级、要退出码 → 用官方 bash / pwsh
• 分钟级、只要最后结果 → run_in_background
• 会一直活着，或要中途喂输入 / 中断后继续用 → terminal_*

默认后端直连 node-pty，该会话的读 / 写 / 网络不受 ACL 沙箱约束；每个工具结果里的 enforcement 会如实上报实际隔离等级。

核心功能¶

插件通过五个工具挂起和管理会话：

与一次性命令相比，插件明确补了三类能力：向已启动进程写输入、中断前台命令后继续同一 shell、多次续读且不重复（游标）。还支持有界等待（waitMs）和命令结束时唤醒（notifyOnExit）。

超时不是失败：terminal_exec 在 waitMs 窗口内若命令未结束，会返回 status: 'running' 并把控制权还给你；会话与命令仍在跑，需要时用 terminal_state、terminal_read 跟进。

读全输出的判据（三者同时成立）：outputFinal: true、lossy: false、unreadBytes: 0。

随包技能 background-terminal（skills/background-terminal/SKILL.md）会在插件注册后供 Agent 加载，字段含义与常见坑的说明以该技能为准。

安装与启用¶

在 DSH 里添加插件，输入仓库地址（也接受本地目录）：

https://github.com/AkezI-T/dsh-background-terminal

依赖解析、挂载、工具与技能注册由 DSH 完成，不需要手工改 profile 或预设。重启 Host 后生效。

运行环境要求（见 package.json）：Node >=22.19。许可证：MIT。

典型用法¶

1. 发现终端¶

省略 shellPath 时，插件按 shellDialect 与平台解析，命中第一个 shell 即用。Linux / bash 候选顺序为 /bin/bash → /usr/bin/bash → /usr/local/bin/bash → PATH。一个都不存在时插件挂载失败（SHELL_NOT_FOUND）。

找不到 shell 时，先用系统命令查绝对路径，再在新建会话时传入：

Get-Command pwsh | Select-Object -ExpandProperty Source    # 或：which bash

terminal_exec({ command: '<命令>', shellPath: '<绝对路径>' })

shellPath 仅在新建会话时有效，须为绝对路径且与 shellDialect（bash / pwsh）匹配。Windows 在 ACL 沙箱下请用 pwsh，不要用 Git Bash（danger-full-access 除外）。

2. 挂起使用¶

terminal_exec 的常见参数：

带 sessionId 的 terminal_exec 在同一 shell 里跑下一条命令，cwd、环境、REPL 状态保留。上一条命令的帧未闭合时（典型：SIGINT 之后），须显式 reset: true 续签，代价是放弃该命令的退出码。

3. 退出结束¶

命令结束不会自动销毁会话；占用的容量需手动释放。任务完成后建议：

terminal_state({})                            // 列全
terminal_signal({ sessionId, close: true })   // 逐条关
terminal_state({})                            // 复核

关闭前先把未读输出读出来。

配置摘要¶

完整项见仓库 lib/config.mjs。

适用场景与注意¶

适合：需要 REPL、交互式安装向导、长时间编译且要看中间输出、或 SIGINT 后仍在同一 shell 继续操作的 Agent 工作流。

务必知晓：

1. 默认 ptyBackend: 'node-pty' 不经 ctx.sandbox.confine，工作区外读写、联网不受 ACL 限制；需要沙箱隔离时仍应使用官方 bash / pwsh / 文件工具。
2. 插件以当前 DSH Host 进程权限运行；安装前应自行查看源码与 MIT 许可证，确认可接受隔离等级与依赖（如 node-pty 1.2.0-beta.15）。
3. 不要用 terminal_write 代替「换一条命令」——它是裸输入，不建命令帧、没有退出码。
4. SIGINT 之后看 commandStateTrustworthy；为 false 时不要信 commandRunning，在同一 shell 继续干活用 reset: true。
5. macOS 自带 bash 为 3.2；Windows PowerShell 5.1 没有 && / ||，用 ; 串联。

DSH 生态是「一切皆插件」；社区目录 SkillHub 插件页 为独立站点，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-background-terminal 把 DSH Agent 从「只能等命令跑完」扩展到「活着的 shell」：跨回合读写、中断、增量读输出，并在用完时显式关闭会话。需要细节时对照仓库 README 与随包技能即可。

• 目录页：https://www.skillhub.cn/plugins/AkezI-T/dsh-background-terminal
• GitHub：https://github.com/AkezI-T/dsh-background-terminal