前言¶

在 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