前言¶

用 dsh web 做開發時，經常需要在瀏覽器裏順手執行幾條命令。常見做法有兩種：切到獨立的終端窗口，或者用 overlay 式終端把會話內容蓋住。前者要來回切換上下文，後者會遮擋正在進行的對話。

下面介紹的 dsh-web-shell 採用第三種思路：把終端停靠在窗口右側，主對話欄自動讓位，終端和會話內容同時可見，摺疊面板也不會中斷會話。

這是什麼¶

dsh-web-shell 是 DeepSeek Harness 的右側停靠 Web Shell 插件，由 JesmonX 維護，基於 MIT 許可證發佈，npm 上的當前版本爲 0.1.1。瀏覽器端使用 xterm.js 渲染終端，通過 /api/shell WebSocket 與宿主側 PTY 橋接，支持 bash 和 zsh 切換。

DSH 的理念是「一切皆插件」，這類 UI 擴展正是通過插件機制接入宿主的。

核心功能¶

按 README 的描述，插件提供以下能力：

1、右側停靠。打開後主對話欄自動讓位，不再遮擋會話內容。完整效果需要較新的 dsh-client-ui-layout，舊版宿主會自動降級，見下文兼容性一節。

2、可調寬度。拖動 shell 左邊緣即可調整，範圍 360–960px。

3、按 profile 記憶佈局。當前 profile 的 settings domain 保存 dock 寬度和摺疊狀態，刷新後恢復。具體來說，插件註冊 web-shell settings namespace，字段爲 dockWidth 和 folded；寬度只在拖拽結束時寫入，摺疊和關閉都會記錄爲 folded。設置不使用瀏覽器 localStorage，因此同一 profile 重新加載不會丟失佈局偏好。

4、摺疊與關閉分離。摺疊隱藏面板但保持 WebSocket / PTY 會話存活，再次展開恢復同一個 shell；關閉則斷開連接並終止 PTY，再次打開會創建新 shell。

5、bash / zsh 切換。切換時關閉舊 PTY 並啓動新 shell。

6、安全預檢 companion。插件同時發佈 dsh-web-shell/invariant，導出 checkWebShellTrust()，對 /api/shell 升級路由做啓動前安全圍欄預檢。

安裝與啓用¶

要求 DeepSeek Harness >= 0.1.0-rc.5（npm 上 @deepseek-ai/dsh 的 latest 爲 0.1.0-rc.6）。

先從 npm 安裝（推薦）：

dsh plugin --profile web add dsh-web-shell

安裝後啓動：

dsh web

點擊窗口右側的 ❯_ 按鈕即可打開 shell。

也可以從 GitHub 安裝：

dsh plugin --profile web add github:JesmonX/dsh-web-shell

倉庫已提交構建好的 lib/，git 安裝直接可用，不需要構建授權。如果插件管理器不支持 GitHub 簡寫，可先 clone 再本地安裝：

git clone https://github.com/JesmonX/dsh-web-shell.git
dsh plugin --profile web add ./dsh-web-shell

典型用法¶

日常操作集中在面板按鈕和邊緣拖拽上：

• 打開 / 展開：右側 ❯_ 按鈕，打開 shell 或從摺疊中恢復；
• 摺疊：面板標題欄 › 按鈕，隱藏面板但保持會話存活；
• 關閉：面板標題欄 × 按鈕，終止會話；
• 切換 shell：標題欄 bash / zsh，啓動新的 PTY；
• 調整寬度：面板左邊緣拖拽，範圍 360–960px。

宿主側默認配置通過 cordis.patch.yml 注入：

- id: web-shell
  name: 'dsh-web-shell'
  inject: [webServer, subprocess, webRuntime]
  config:
    shells: [bash, zsh]
    defaultShell: bash
    rows: 40
    cols: 120
    graceMs: 5000
    fontFamily: '"Maple Mono NF CN", "Sarasa Mono SC", "Cascadia Code", "JetBrains Mono", "Noto Sans Mono CJK SC", "Microsoft YaHei UI", monospace'

各字段含義如下，均可在後續 patch 層覆蓋：

• shells：可選 shell 列表，目前支持 bash 和 zsh；
• defaultShell：瀏覽器未選擇時使用的默認 shell；
• cwd：新終端起始目錄，默認 process.cwd()；
• rows / cols：初始終端行列數；
• graceMs：PTY 清理寬限時間；
• fontFamily：瀏覽器端 xterm.js 的 CSS 字體棧，使用瀏覽器所在系統的字體。

兼容性¶

插件的 shell.overlay 槽位由 dsh-client-ui-layout 聲明。完整的「主對話欄讓位」效果依賴該包提供 ctx.layout.setShellWidth / closeShell 等右側停靠 API。

如果宿主 UI 版本較舊（有 shell.overlay 但沒有右側停靠 API），插件會自動降級爲純 overlay 模式：shell 仍可打開、摺疊、關閉和拖拽，但主對話欄不會讓位。

安全與注意事項¶

先說權限：shell 以與 dsh 進程相同的操作系統權限運行。裝進環境之前，應檢查插件源碼和許可證，確認可接受再使用。插件採用 MIT 許可證，源碼在 GitHub 上公開。

再看網絡防護。/api/shell 升級路由使用與 /api 網關相同的 loopback / trusted-host / origin 防護；非 loopback 部署必須通過 trustedHosts 顯式聲明。

如果想在啓動前發現配置缺口，可以接入 dsh-web-shell/invariant companion。它導出 checkWebShellTrust()，在 dsh 的 invariant/doctor 診斷組合中對解析後的 webServer / webRuntime 配置執行同一套 /api/shell 圍欄預檢：Host 必須存在，loopback 必須可用，非 loopback Host 必須在 trustedHosts 中，Origin 必須同源，Sec-Fetch-Site: cross-site 必須拒絕；綁定 0.0.0.0 時還必須配置至少一個合法 trusted host。這樣問題在啓動前暴露，而不是等 WebSocket 升級後才發現。

結尾¶

經過上面的步驟，你就得到了一個不遮擋會話、摺疊不斷線、佈局可按 profile 記憶的瀏覽器終端。對經常在瀏覽器裏操作 DSH 的開發者來說，這是一個值得裝上試試的插件。

插件目錄頁：https://www.skillhub.cn/plugins/JesmonX/dsh-web-shell

GitHub 倉庫：https://github.com/JesmonX/dsh-web-shell

需要說明的是，skillhub.cn 是社區維護的獨立插件目錄，與 DeepSeek、幻方沒有官方從屬關係。