前言¶
用 DeepSeek Harness（DSH）做智能體開發，大部分時間泡在 web GUI 裏，但一到要執行 shell 命令——起服務、看日誌、臨時進 vim 改配置——就得切出去另開一個終端窗口，回來還要自己對一遍目錄和會話狀態。
dsh-web-terminal 解決的就是這個問題：它在 web GUI 側邊欄加一個 Terminal 入口，打開一個多標籤終端面板，每個標籤都是宿主進程上的真實 PTY shell。DSH 的理念是一切皆插件，這個插件不改 dsh 源碼，裝進 web profile 即可。下面按功能、安裝、配置、驗證的順序介紹。
這是什麼¶
dsh-web-terminal 是 iamsee123 維護的 DeepSeek Harness web GUI 本地終端插件，當前版本 0.1.1，MIT 許可證（README 的 License 章節與 package.json 均標明）。一句話定位：側邊欄多標籤 xterm.js 面板，每個標籤通過 node-pty 在宿主進程運行真實 PTY shell，並經 WebSocket 路由流式傳輸。
依賴棧很直接：node-pty ^1.1.0 負責 PTY，@xterm/xterm ^6.0.0 負責前端渲染，@xterm/addon-fit ^0.11.0 負責尺寸適配，ws ^8.18.0 負責傳輸，react ^18.2.0 作爲 peer dependency。
核心功能¶
按 README 的說明，能力集中在六點：
1、真實僞終端 shell：交互程序（vim、top、htop）、Ctrl-C、resize 均可用；
2、多標籤終端面板，提供新建 / 關閉 / 斷開 / 重連 / 清屏控制；
3、面板打開、窗口 resize、容器變化時自動適配（auto-fit）；
4、shell 與工作目錄可配置（settings panel 或 patch yaml）；
5、所有路由帶 loopback-only 信任柵欄（同源 + 127.0.0.1/localhost 校驗）；
6、熱插拔：不改 dsh 源碼，通過 web profile bundle list 掛載，與 dsh-ssh 相同的 dual-face 插件模式。
雙半邊架構¶
插件分 host、client 兩半：
| 半邊 | 入口 | 職責 |
|---|---|---|
| host（node） | lib/index.js（源碼 src/index.ts） |
node-pty shell 會話、/api/dsh-terminal/info 路由、/api/dsh-terminal/terminal WebSocket 升級、system-prompt 公告、settings 命名空間（shell/cwd） |
| client（瀏覽器） | lib/client.js（源碼 src/client/index.ts） |
側邊欄 Terminal 入口（DOM 注入、自愈）、多標籤終端面板（React + xterm.js） |
線協議¶
兩端通信走 src/protocol.ts 定義的線協議：
client → host: {type:"input",data}、{type:"resize",cols,rows}
host → client: {type:"ready",shell}、{type:"output",data}、{type:"exit",code,error?}
client 發送鍵盤輸入和尺寸變化，host 返回就緒、終端輸出和退出事件。
安裝與啓用¶
先確認 Node 版本：package.json 的 engines 要求 ^22.19.0 || >=24.0.0。官方提供兩種安裝方式。
Option A：bundle list（推薦）¶
先做構建腳本放行，再添加依賴並掛載到 bundle list。在 ~/.dsh/profiles/web 下操作：
# 1) 一次性：在 ~/.dsh/profiles/web/pnpm-workspace.yaml 允許構建腳本
# allowBuilds:
# esbuild: true
# node-pty: true
# 2) 添加依賴（路徑換成你的 checkout 位置）
cd ~/.dsh/profiles/web
pnpm add dsh-web-terminal@link:/path/to/dsh-web-terminal
# 3) 在 package.json 的 dsh.profile.bundles 裏追加 "dsh-web-terminal"
# （bundle 自帶的 cordis.patch.yml 會插入 id=terminal 的插件行）
# 4) 重啓 dsh web
第一步不能省：node-pty 和 esbuild 的構建腳本需要先在 pnpm-workspace.yaml 裏放行，否則裝不上。
Option B：手動 patch 行¶
如果包已安裝到 profile，也可以在 ~/.dsh/profiles/web/cordis.patch.yml 手動添加 patch 行：
- insert:
- id: terminal
name: 'dsh-web-terminal'
配置¶
shell 與工作目錄都可在 settings panel 或 patch yaml 裏配置：
- id: terminal
config:
enabled: true
announceToAgent: true
shell: /bin/zsh # 默認取 $SHELL
cwd: /path/to/work # 默認爲宿主進程 cwd（即 workspace root）
四項分別控制開關、是否向 system-prompt 公告、要啓動的 shell、以及工作目錄。不配置時 shell 取 $SHELL，工作目錄落在宿主進程 cwd（workspace root）。
驗證¶
重啓 dsh web 後，先用 curl 確認 host 路由已就位：
curl http://127.0.0.1:3080/api/dsh-terminal/info
# {"shell":"/bin/zsh","platform":"darwin",...}
能返回 shell 和平臺信息，說明 host 半邊掛載成功。然後刷新瀏覽器 GUI：側邊欄出現 Terminal 入口，新建標籤，輸入命令即可。
開發與已知問題¶
想從源碼構建或參與開發，官方給出的命令如下：
pnpm install # pnpm-workspace.yaml 必須放行 esbuild / node-pty 構建腳本
pnpm run typecheck # tsc --noEmit
pnpm run build # esbuild 產出 lib/index.js（host）+ lib/client.js（ModuleLoader 包裝）
pnpm test # client bundle 語法 + jsdom ModuleLoader 模擬
node scripts/smoke.mjs # host WebSocket 鏈路冒煙測試
node scripts/browser-diag.mjs # Playwright：打開真實 GUI，點 Terminal，敲一條命令
構建腳本會把 node_modules/@xterm/xterm/css/xterm.css 內嵌進 src/client/xterm-css.ts（生成文件），因爲 ModuleLoader 環境沒有 CSS loader。
README 列了三個已知坑：
1、@xterm/* 必須打包進 bundle。client 側只有平臺種子模塊（react 全家）和 shell 自帶模塊（@deepseek-ai/*）可以保持 external，xterm 若保持 external 會報 require("@xterm/xterm") missed the module table。
2、面板高度鏈。[data-dsh-terminal-view] 是絕對定位容器，其直接子元素 .dshTermView 必須設 height: 100%，否則內層 .dshTermPanel { height: 100% } 會解析到 auto 高度的父級，整條 flex 鏈塌陷，終端被壓成 2px 條。
3、spawn-helper 可執行位。預編譯的 prebuilds/<platform>/spawn-helper 可能丟失可執行位，報 posix_spawnp failed；執行 pnpm run fix:spawn-helper 修復（postinstall 會在 pnpm install 時自動執行）。另外注意：node-pty 的 spawn 在 dsh 文件沙箱內會被阻止，冒煙測試需針對真實 dsh 進程運行。
適用場景與注意¶
適合的場景：你已經在用 DSH web GUI，希望在同一個界面裏完成命令執行——調試智能體時看日誌、跑腳本、臨時進 vim 或 top，不必來回切窗口。
權限方面務必明確：這個終端以當前 dsh 進程（即宿主用戶）的權限執行命令，等同於直接 shell 訪問。所有路由雖有 loopback-only 信任柵欄（同源 + 127.0.0.1/localhost 校驗），也應只在本地環境使用。安裝任何第三方插件前，建議先檢查源碼與許可證；本插件許可證爲 MIT。
結尾¶
回顧一下：dsh-web-terminal 把真實 PTY shell 塞進 DSH web GUI，不改源碼、熱插拔，交互程序、Ctrl-C、resize 都能用。如果你日常泡在 dsh web GUI 裏，可以裝一份試試。
- 目錄頁：https://www.skillhub.cn/plugins/iamsee123/dsh-web-terminal （社區維護的目錄站點，與 DeepSeek / 幻方無官方從屬關係）
- GitHub：https://github.com/iamsee123/dsh-web-terminal
