dsh-ui-web/packages/dsh-ssh

一句话定位

为 DSH Web GUI 加入一套完整的远程 SSH 运维能力：在 Web 端集中管理多台远程主机（增删改查、搜索、连接测试、一键导入 ~/.ssh/config），在 host 进程内复用持久 ssh2 连接池执行命令、跑 Web 终端、SFTP 传文件、开本地端口转发隧道，并在多台主机上并发跑同一条命令；同时为 Agent 提供 6 个工具，调用同一份主机配置。

核心能力

• 主机增删改查、搜索、连接测试；支持密钥 / 密码认证、passphrase 密钥、多级 ProxyJump 跳板机（每跳必须是本插件已配置别名）
• 一键导入 ~/.ssh/config：解析 Host / HostName / User / Port / IdentityFile / ProxyJump 等字段，已有别名自动跳过（通配模式 / 缺 HostName 跳过）
• 持久 ssh2 连接池：每台主机复用一条长连接（不每次重连），空闲 30 分钟自动断开，断线自动重连（最多 3 次）
• 命令执行：单主机 exec 带超时（默认 60s）、stdout / stderr 分离、单次输出上限 2MB 截断保护
• Web 终端（xterm.js + WebSocket PTY，背压自动暂停 / 恢复）、SFTP 文件传输（浏览器选文件 → NDJSON 进度流）、本地端口转发隧道（仅 127.0.0.1 监听，访问远程数据库 / 内网服务）、集群并发执行（默认并发 8，可按别名 / 环境 / 标签过滤）
• Agent 工具 ssh_list / ssh_exec / ssh_upload / ssh_download / ssh_tunnel / ssh_cluster，GUI 与 Agent 共享同一份主机配置

技术实现

• 语言: TypeScript（host 半区 src/index.ts）+ TypeScript + React 18 + CSS Modules（browser 半区 src/client/）
• 关键依赖: ssh2 ^1.17.0（持久 ssh2 连接池 + SFTP）、@xterm/xterm ^6.0.0 + @xterm/addon-fit ^0.11.0（浏览器终端）、ws ^8.18.0（WebSocket PTY）
• 架构模式: 双半区 cordis bundle。src/index.ts 是 host 半区（SshEngine 连接池 + /api/dsh-ssh/* 路由 + 6 个 Agent 工具 + 系统提示词宣告），src/client/index.ts 是 browser 半区（侧边栏入口 + 主机管理 / 终端 / 传输 / 隧道 / 集群面板 + locale 注册）。bundle 声明在 packages/dsh-ssh/cordis.patch.yml:10-12（插入 id ssh），浏览器端通过 dsh.client.inject 注入 3 个官方 @deepseek-ai/dsh-client-*（client-runtime / client-connection / client-ui-settings）+ platform: web。连接池默认参数：空闲 30 分钟、握手 15s 超时、keepalive 15s 间隔、输出 2MB 上限、exec 默认超时 60s、集群并发 8、SFTP 并发 8（src/engine.ts:33-41）
• 入口文件: packages/dsh-ssh/src/index.ts（host apply）、packages/dsh-ssh/src/client/index.ts（browser apply）；bundle 声明 packages/dsh-ssh/cordis.patch.yml:1-12，浏览器依赖 packages/dsh-ssh/package.json:31-39

适用场景

• 日常需要同时管理多台 SSH 服务器（开发 / 测试 / 生产混合）的开发者：希望在 DSH Web GUI 中集中浏览主机、执行命令、传文件、开隧道访问远程数据库 / 内网服务，省去切换多个工具；
• 想让 Agent 直接执行远程运维任务的开发者：在 GUI 中预先配置好主机（手动填或导入 ~/.ssh/config），Agent 就能通过 ssh_list / ssh_exec / ssh_upload / ssh_download / ssh_tunnel / ssh_cluster 调用同一套主机配置；
• 已有 ~/.ssh/config 的用户：通过「导入 ssh_config」一键把现成的 SSH 别名同步到插件，无需重复输入 host / port / user / identityFile。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:CAPTAIN1275/dsh-ui-web/packages/dsh-ssh

配置项

本插件在 dsh 设置面板的「SSH」区域提供 2 个开关：

引擎内部还有几处不暴露给 GUI 的硬编码常量（src/engine.ts:33-41）：空闲超时 30 分钟、握手超时 15 秒、keepalive 间隔 15 秒、keepalive 重试上限 3、输出上限 2MB、exec 默认超时 60 秒、集群默认并发 8、SFTP 并发 8；上传单次请求体上限 4 GiB、WebSocket 终端背压 1MB / 512KB（src/routes.ts:23-39）。调整需改源码后重新构建。

常见问题

Q: 安装之后侧边栏没出现 SSH 入口怎么办？

A: 重启 dsh web。bundle 激活是 host 启动时一次性做的，刷新浏览器不足以触发；重启后侧边栏出现「SSH」入口，Agent 提示词也会自动带上插件说明（受 announceToAgent 开关控制）。

Q: 密码是怎么保存的？安全吗？

A: 以明文存于 ~/.dsh/dsh-ssh.json，文件权限 0600、目录权限 0700，原子写入（tmp + rename）。这与 ssh-skill 把密码写进 ~/.ssh/config 注释的信任模型一致——既然 ~/.ssh/config 也常以注释形式存密码，本插件不做额外加密。文件路径与权限在 src/store.ts:18-20、src/store.ts:328-336。

Q: 局域网里别人能访问我的 SSH 控制台吗？

A: 不能。所有 /api/dsh-ssh/* 路由仅信任本机回环连接（socket 地址必须命中 IPv4 127/8 / ::1 / IPv4-mapped ::ffff:127/8，并校验同源 Host header、sec-fetch-site / Origin），LAN 邻居直接 403。WebSocket 终端升级也走同一个 loopback 围栏；本地端口转发隧道只监听 127.0.0.1，不会暴露到外部网络。详见 src/routes.ts:42-62、src/engine.ts:709。

Q: Agent 能在我没配置的主机上执行命令吗？

A: 不能。Agent 只能操作 GUI 中已配置或从 ~/.ssh/config 导入的主机别名。ssh_exec / ssh_upload 等工具调用若别名未配置会直接报错，不会臆造主机。这一约定同时写在系统提示词「限制」段（src/index.ts:58）与 README 中。

Q: 远程输出会脱敏吗？比如 env 命令？

A: 不会。exec / cluster 的 stdout / stderr 原样返回（不做 secret 替换），env 这类命令可能把远端环境变量里的密钥带回对话记录。这是 ssh-skill 同样的语义——传输 / 执行消耗真实远程资源、Agent 使用前需用户确认。

Q: 下载能整目录吗？上传呢？

A: 下载仅支持单文件（在「传输」面板的远程浏览器里挑文件，再走 /api/dsh-ssh/download）；上传支持本地目录递归（walk 后逐文件传），整目录下载未实现。限制在 src/engine.ts:519-533、README.md:74。

Q: 跳板机能用 ~/.ssh/config 里的别名吗？

A: 不能。ProxyJump 链上的每一跳必须是本插件已配置的主机别名（不能跨插件引用 ~/.ssh/config 别名）；导入时若某跳不在本插件主机表中，会在创建时报错跳过。限制见 README.md:76、src/store.ts:240-260。

Q: 自动重连会不会重放我的命令？

A: 会。exec 断线时会自动重连（最多 3 次），命令会在新连接上重新发送；非幂等命令（如 rm、追加写文件）会有副作用，请优先用幂等命令或确认后再执行。详见 src/engine.ts:212-231、README.md:75。

上手难度

入门 — 一行命令安装、重启 dsh web 即可见 SSH 入口；主机可在 GUI 里手动填或一键导入 ~/.ssh/config，无需写配置文件或命令行。但因涉及远程主机、密钥、跳板机，建议先试一两条 exec / 隧道再批量使用。

已知问题与限制

• 上传的远程目标路径必须为绝对路径，相对路径会被拒绝（src/engine.ts:486-490、README.md:73）
• 下载仅支持单文件；上传支持本地目录递归（walk 后逐文件传），下载整目录未实现（README.md:74、src/engine.ts:519-533）
• exec 断线自动重连（最多 3 次）会重发同一命令，非幂等命令需自行注意副作用（src/engine.ts:212-231、README.md:75）
• ProxyJump 链上的每一跳必须是本插件已配置的主机别名，不能跨插件引用 ~/.ssh/config 别名（README.md:76）
• 断点续传（resume）暂未实现；单次上传请求体上限 4 GiB（src/routes.ts:23-26）
• Agent 工具的传输路径是宿主机器本地路径（与 ssh-skill 同一语义）——ssh_upload / ssh_download 以宿主进程权限直接读写本机任意路径，不经 bash 沙箱，请注意该权限面（README.md:30-31、src/index.ts:58）
• 主机配置 ~/.dsh/dsh-ssh.json 以明文保存密码与 passphrase，文件 0600、目录 0700，不做加密（src/store.ts:328-336、README.md:25-26）
• exec / cluster 远程输出原样返回（不脱敏），env 等命令可能带回远端环境密钥（src/index.ts:58、README.md:32-33）
• 本地端口转发隧道只监听 127.0.0.1，外部网络无法访问；这是围栏设计而非可配置项（src/engine.ts:709、src/routes.ts:42-62）
• 主机别名仅允许字母、数字、点 .、连字符 -、下划线 _（首字符不能是分隔符）；不符合的正则会在创建 / 导入时报错跳过（src/store.ts:62-68、src/store.ts:296-303）
• 配置文件损坏时会被重命名为 .corrupt-<timestamp> 备份、随后启动为空表，不会被静默覆盖（src/store.ts:317-325）

English README

基于 zhu1090093659/dsh-web-ui（Apache-2.0）开发的 DeepSeek Harness（DSH）Web UI 插件套件。全套 22 个包已发布到 npm（@captain1275/*）。

DSH Web UI 全家桶为 DeepSeek Harness 的 Web 界面提供一系列插件与皮肤：极光毛玻璃皮肤、任务看板、 SSH 运维、右侧文件/变更面板、Git 图谱、移动端远程控制、DeepSeek 娘看板娘（养成系）、实时令牌统计， 以及皮肤中心。所有插件既可独立安装，也可通过聚合包一次装齐。

极光 Aurora 皮肤效果（沉浸光感 / 深色 / 浅色）

特性

极光（Aurora）皮肤（支持动态背景）

• 毛玻璃输入框：高斯模糊（backdrop-filter 30px）+ 半透明玻璃底 + 细边框 + 内高光
• 自定义背景：URL / 本地图片 / 动图（GIF/WebP）/ 视频（mp4/webm） / 透明度 / 模糊调节， 深浅两套极光渐变；视频背景支持静音开关、本地文件持久化（存 ~/.dsh/skin-aurora-media/，刷新不丢）
• 仿Claude Code推理等级滑块：点击模型菜单的「推理等级」弹出 Effort 滑块面板——无极拖动、松手吸附、 WebGL 火焰跟随、OFF/MAX 刻度、Low/Medium/High/Ultracode 状态

• 用户消息气泡毛玻璃：与输入框统一的玻璃质感

DeepSeek 看板娘（养成系）

• 图片资源（社区同人资源，codex-pet-DeepSeek-girl）
• 养成系统：亲密度 4 级成长（幼鲸 / 伙伴 / 挚友 / 深海羁绊）、升级庆祝气泡、进度条、 Token 零食经济、使用时长成长（每 30 分钟 +1）
• 待机随机气泡：空闲时随机说话（live2d 风格文案）
• 摸头 / 喂食 / 改名 / 拖动，召唤按钮（live2d 同款贴边滑出）

Skill 人格设定

• 设置「人格设定」：开关启用/禁用常驻人格，编辑技能名、描述与人格正文
• 一键生效：保存后写入用户级技能 ~/.dsh/skills/catgirl-rp/SKILL.md，DSH 技能系统实时加载， 所有新对话自动以该人格回应（含语气、动作表达、互动规则）
• 内置猫娘人格：默认提供「小咪」猫娘人格（常驻生效、好感度系统、模式切换指令），可自由改写
• 可临时退出：对话中说「退出角色扮演模式」即切回普通助手，说「进入角色扮演模式」恢复

用量看板

• 彩色统计卡：累计 token、调用次数、缓存命中、估算费用（按 DeepSeek 官方定价）
• 近 14 天趋势：每日 token 消耗柱状图
• 模型分布：各 provider/model 用量环形图 + 图例
• 会话排行：Top 20 会话（标题 / 模型 / 调用数 / token / 费用）
• 自动记录：对话时自动采集 token 用量（会话快照替换语义，不双计），存 ~/.dsh/usage.json
• 侧边栏入口：彩色柱状按钮打开全屏看板

功能插件

皮肤中心

10 套皮肤（ths / xp / blue-fantasy / dragon-heir / minecraft / miku / trading / whale-song / aurora / skin-center），支持皮肤启用互斥管理与一键切换。

其余皮肤（ths / xp / blue-fantasy / dragon-heir / minecraft / miku / trading / whale-song） 为上游 dsh-web-ui 自带皮肤。

安装

方式一：npm（推荐，已发布）

# 在 DSH profile 目录（~/.dsh/profiles/web）安装聚合包
npm install @captain1275/dsh-web-ui-all@0.2.8

然后在 profile 的 package.json 里把 @captain1275/dsh-web-ui-all 加入 dsh.profile.bundles：

{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "@captain1275/dsh-client-ui-skin-aurora",
        "@captain1275/dsh-full-stats",
        "@captain1275/dsh-web-ui-all"
      ]
    }
  }
}

重启 DSH 即生效。

方式二：从源码（开发）

git clone <your-repo-url> dsh-web-ui
cd dsh-web-ui
pnpm install
pnpm -r build

# 把本地包链接进 profile（junction）
node scripts/link-profile.mjs

开发

• 构建：pnpm -r build（或 pnpm --filter <package> build）
• 新增皮肤：参考 packages/skins/aurora（skin.json + src/client + cordis.patch.yml）， 然后用 node scripts/skin-center-bundles 重新生成注册表
• 聚合包 patch：编辑 packages/dsh-web-ui-all/aggregate.yml 后 node scripts/aggregate.mjs
• 皮肤资产同步：node packages/dsh-skins/build.mjs

目录结构

packages/
├─ dsh-task-board / dsh-ssh / dsh-aionui-panel / dsh-git-graph
├─ dsh-pet / dsh-live-stats / dsh-full-stats
├─ dsh-web-ui-settings / dsh-web-ui-all / dsh-skins
└─ skins/            # 皮肤源码（aurora、miku、ths 等）
scripts/             # 构建 / 注册表 / 链接工具
shared/              # 共享构建预设（tsdown.client.ts）

版权与许可

• 主体代码：zhu1090093659/dsh-web-ui，Apache-2.0
• 增强优化：@captain1275
• DeepSeek 娘精灵图：xpy12367/codex-pet-DeepSeek-girl， 社区同人资源，版权归原作者
• 人形图标：Font Awesome 6.7.2，CC BY 4.0
• 样式参考：live2d-widget（GPL-3.0，仅参考视觉风格，未搬用代码）
• 商标：DeepSeek 及其相关标识均为 DeepSeek 官方资产；本插件为社区开发者独立维护的非官方同人项目， 不代表 DeepSeek 官方立场。