dsh-web-shell DeepSeek Harness 的右侧停靠 Web Shell 插件。浏览器端使用 xterm.js，通过 /api/shell WebSocket 与宿主侧 PTY 桥接，支持 bash / zsh 切换。 ## 功能 - 右侧停靠：打开后主对话栏自动让位，不再遮挡会话内容（需要较新的 dsh-client-ui-layout）。 - 可调宽度：拖动 shell 左边缘即可调整宽度（360–960px）。 - 按 profile 记忆布局：当前 profile 的 settings domain 会保存 dock 宽度和折叠状态，刷新后恢复。 - 折叠 / 关闭分离： - 折叠：隐藏面板但保持 WebSocket / PTY 会话存活，再次展开恢复同一个 shell。 - 关闭：断开连接并终止 PTY，再次打开会创建新 shell。 - bash / zsh 切换：切换时关闭旧 PTY 并启动新 shell。 ## 安装 要求 DeepSeek Harness >= 0.1.0-rc.5（npm 上 @deepseek-ai/dsh 的 latest 为 0.1.0-rc.6）。 ### 从 npm（推荐） sh dsh plugin --profile web add dsh-web-shell 安装后启动： sh dsh web 点击窗口右侧的 ❯_ 按钮打开 shell。 ### 从 GitHub sh dsh plugin --profile web add github:JesmonX/dsh-web-shell 仓库已提交构建好的 lib/，git 安装直接可用，不需要构建授权（allowBuilds）。 如果插件管理器不支持 GitHub 简写，可先 clone 再本地安装： sh 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 注入宿主侧默认配置： yaml - 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 字体栈（使用浏览器所在系统的字体）。默认值优先使用本机已安装的 Maple Mono NF CN，并回退到常见等宽中文字体。 ### 布局设置 插件注册 web-shell settings namespace，字段为 dockWidth 和 folded。宽度只在拖拽结束时写入，范围仍由 UI 合同限制在 360–960px；折叠和关闭都会记录为 folded。设置属于 dsh 当前 profile 的 settings domain，不使用浏览器 localStorage，因此同一 profile 的重新加载不会丢失布局偏好。 ## 兼容性说明 - 插件的 shell.overlay 槽位由 dsh-client-ui-layout 声明。建议使用包含该槽位的 DeepSeek Harness 版本（>=0.1.0-rc.5）。 - 完整"主对话栏让位"效果需要 dsh-client-ui-layout 提供 ctx.layout.setShellWidth / closeShell 等右侧停靠 API。 - 如果宿主 UI 版本较旧（有 shell.overlay 但没有右侧停靠 API），插件会自动降级为纯 overlay 模式：shell 仍可打开、折叠、关闭和拖拽，但主对话栏不会让位。 ## 从源码构建 本仓库自带完整构建链，无需依赖 deepseek-harness monorepo： sh npm install npm run build - npm run build 依次执行：tsc -b tsconfig.host.json（宿主侧）→ tsc -b tsconfig.client.json（浏览器侧）→ tsdown --env.DSH_BUILD_FACE client（打包 lib/index.js 与 lib/client.js）。 - 构建管线复刻自 monorepo 的 packages/client/tsdown.client.ts 预设（模块表 externals、CSS Module 内联、xterm.css 内联），产物与 monorepo 构建逐字节兼容（仅 CSS 类名哈希与注释路径不同）。 - 构建工具已锁定精确版本（tsdown 0.22.2 / lightningcss 1.32.0 / typescript 6.0.3），保证产物可复现。 - lib/ 已提交进 git 并随 npm 发布：修改 src/ 后请重新 npm run build 并把 lib/ 一起提交，确保 git / npm 安装到的产物与源码一致。 - 仅类型检查：npm run typecheck；开发热更新：npm run watch。 ## 安全 Shell 以与 dsh 进程相同的操作系统权限运行。升级路由使用与 /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 升级后才发现。 ## License MIT