前言¶
在 DSH 里做远程运维时，常见做法是另开系统终端或独立 SSH 客户端：窗口和 IDE 分离，AI 侧也很难直接利用你已经连上的会话。若希望主机列表、交互式终端、文件传输和本地/远程隧道都收在 DSH 界面里，并且「记住密码」交给操作系统凭据库而不是插件自造加密，社区插件 UniTerminal（npm 包 @winking-r/dsh-uniterminal，维护者 WinKing-R）就是面向这一组合需求的客户端类插件。下面介绍它的定位、能力与安装方式；事实以 GitHub 仓库 README 为准。
这是什么¶
UniTerminal 挂在 DSH 右侧栏：一个侧边栏标签里可以并存多条会话（顶部会话栏切换；同一主机连两次会显示 #2）。每条会话并列提供 终端（xterm + shell）、文件（SFTP）和 隧道（-L / -R / -D）三视图。
插件自述：密码交给操作系统密码箱保管（Windows 凭据管理器、macOS 钥匙串、Linux Secret Service），自身不实现任何加密；仅当本机没有可用系统密码箱时才回落明文文件，并在界面上说明。当前 README 标注版本 0.2.19，许可证 MIT；运行环境要求 DSH >=0.2.1-rc.2、Node >=20。
社区目录页：skillhub.cn/plugins/WinKing-R/dsh-uniterminal。DSH 生态是「一切皆插件」；该目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
主机与会话¶
- 主机：添加 / 编辑 / 删除（二次确认）、分组；可从
~/.ssh/config只读导入（不回写）；连接前可「测试」连通性；孤儿会话可接管或关闭（接管无需重新输入密码）。 - 状态：行内状态芯片显示延迟；成功结果 5 分钟后变暗、30 分钟后回到「未测试」；失败保留到下次测试；支持「测试全部」（≤3 并发）与巡检抽屉（依赖远端 Linux 的
/proc、df等，缺字段则少显示、不阻断连接）。 - 认证：密码、私钥（路径或粘贴）可同时启用；勾选「记住密码」并保存配置即写入凭据库，不必先连一次；支持跳板链
ProxyJump（各跳暂用同一套凭据）。
终端、文件与隧道¶
- 终端：xterm.js，自适应尺寸，断线重连；面板重挂载或页面刷新后，会话与输出通过
sessionStorage存档尽量不丢。 - 文件：SFTP 浏览、多选上传（进度与取消）、下载、新建目录、删除。
- 隧道：本地转发、远程转发、SOCKS5；监听 127.0.0.1；随会话关闭自动回收（README 说明
-R停止时远端端口可能不会立刻释放，需等会话关闭）。
AI 可调用工具¶
注册 uniterminal_list_sessions（发现会话）与 uniterminal_exec（在已有会话里执行命令并取 stdout / 退出码）。默认 mode=exec（独立通道，不占用用户正在看的终端）；mode=shell 会把命令打进用户终端并留在屏幕上。AI 不能自行建连或提交凭据，只能操作你已打开的会话。不需要时可在插件设置把 agentExec 设为 off。
右栏承载方式¶
插件双注册并运行时探测：若安装了 DSH-better-sidebar 则优先注册到 betterSidebar；否则回落官方 @deepseek-ai/dsh-client-ui-sidebar-right 的 sidebarRightTabs。没有 better-sidebar 也能用。
安装与启用¶
前提：DSH >=0.2.1-rc.2、Node >=20。
一条命令（推荐）¶
DSH CLI 会完成装包并在 profile 中登记：
dsh plugin --profile desktop add @winking-r/dsh-uniterminal@latest
--profile 换成你 ~/.dsh/profiles/ 下实际目录名（常见 desktop 或 web）。装完重启 DSH，右栏应出现 UniTerminal 标签。
README 注明：安装过程若退出码为 1 且打印 Ignored build scripts: cpu-features, ssh2，可能是预期现象——包可能已装好，但自动登记被打断；需确认 dsh.profile.bundles 含 @winking-r/dsh-uniterminal，否则按仓库「故障排查」手动追加。改动宿主代码后须重启 DSH（硬刷新页面不够）。
手动等价步骤¶
cd ~/.dsh/profiles/desktop
pnpm add @winking-r/dsh-uniterminal
在对应 package.json 的 dsh.profile.bundles 数组追加：
"@winking-r/dsh-uniterminal"
重启 DSH；若右栏未自动出现，用右栏 + 手动添加 UniTerminal 标签。
装完自检（README 建议）¶
| 检查 | 做法 | 期望 |
|---|---|---|
| 宿主服务 | 请求 http://127.0.0.1:<DSH 端口>/api/uniterminal/health |
{"ok":true} |
| AI 工具 | 查 ~/.dsh/uniterminal/diag.log 的 agent-tools.registered |
含 uniterminal_list_sessions、uniterminal_exec |
| 凭据存储 | ~/.dsh/uniterminal/security.json 的 storage |
有密码箱时为 keychain 且 degraded 为 false |
卸载：先从 dsh.profile.bundles 移除包名，再在 profile 目录 pnpm remove @winking-r/dsh-uniterminal，重启 DSH。主机档案与凭据默认留在 ~/.dsh/uniterminal/。
典型用法¶
- 在 UniTerminal 标签中维护主机（或从
~/.ssh/config导入），必要时行内「测试」再「连接」。 - 连接后在同一会话切换 终端 / 文件 / 隧道；同一标签可开多条会话，用顶部栏切换。
- 需要 AI 在远端执行只读或脚本类命令时，保持会话已连接，由 DSH 内 AI 调用
uniterminal_exec（默认 exec 模式不污染你的交互终端）。
插件设置（节选，见 README 配置表）：
| 键 | 默认 | 说明 |
|---|---|---|
knownHostsPolicy |
reject |
未知指纹：reject 需显式信任 / trust 自动信任并落盘 |
connectTimeoutMs |
20000 |
连接超时（毫秒） |
agentExec |
on |
关闭则不再注册 exec 工具且相关 API 403 |
term |
xterm-256color |
TERM 类型 |
用户数据目录 ~/.dsh/uniterminal/：profiles.json 存主机与分组（不含密码）；记住的口令在有密码箱时进系统库；无密码箱时可能出现高敏感性的 credentials.json。安全细节见仓库 docs/SECURITY.md。
适用场景与注意¶
适合：已在用 DSH 做开发与智能体协作、希望 SSH / SFTP / 端口转发与右栏 UI 一体、并愿意把「记住密码」交给 OS 凭据库的用户。
务必知晓：
- 插件以当前 DSH 进程权限运行；安装与启用前请自行查看源码与 MIT 许可证，评估主机与凭据风险。
- 不提供终端锁屏；离开座位时已连接会话无额外保护，需自行锁屏或断开。
- 无系统密码箱或多用户共用机器时，不要依赖「记住密码」的明文回落方案。
- README 列出的限制还包括：跳板链各跳同一凭据、shell 模式拒绝部分交互式/全屏程序、SFTP 覆盖式上传在个别服务器上的极短窗口等——上线前建议通读 README「已知限制」一节。
结尾¶
UniTerminal 把 SSH 终端、SFTP 与本地/远程/SOCKS 隧道收进 DSH 右栏，并可选地向 AI 暴露已有会话上的 exec 能力；凭据策略明确依赖操作系统密码箱而非插件内加密。进一步了解与 issue 反馈：
