前言¶
在 DeepSeek Harness（DSH）里做运维排查或联调时，常见做法是：对话里先根据 Grafana、OpenSearch 等插件拿到线索，再需要到某台主机上看目录、进程、端口或执行有限修改。若只靠通用 Shell 工具，往往缺少与 DSH 工作台一体的 SSH、JumpServer 资产选择，以及「默认只读、人类显式开启写操作」的边界。下面介绍社区插件 dsh-zterm（包名 dsh-zterm，仓库 guhanfei-ai/dsh-zterm），它把 zterm 的机器连接与终端能力接到 DSH：DSH 负责 AI 与跨工具流程，本插件负责连接、终端、受限读工具、人类开启的读写操作和实际结果记录；外部系统的查询与归档仍由 DSH 其它插件完成。
这是什么¶
dsh-zterm 由维护者 guhanfei-ai 发布，插件 ID 为 zterm（见 cordis.patch.yml）。定位可以概括为：在 DSH Web 工作台右侧提供终端与主机／文件夹／JumpServer 资产列表（有 Better Sidebar 时用独立 Tab 与脑图切换，否则为可调宽的独立大面板），并向对话暴露 14 个 zterm_* 工具，使 AI 在绑定终端后按策略读机器、在人类授权后写操作，并用 zterm_results 把记录交给其它插件复核归档。
典型协作链路如下：
DSH 对话中指定主机，结合 Grafana / OpenSearch 等证据
→ 取得资产与证据
→ zTerm 连接、读取、操作和核验机器
→ DSH 使用其它插件复核并归档结果
核心功能¶
以下能力均来自插件 README 与 package.json 说明的当前交付范围。
连接与凭证¶
- SSH：支持密码、私钥内容、宿主私钥文件；在「设置 → zTerm」中保存命名凭证，多台主机按名称选用，私钥可直接选文件导入。
- 对话指定目标：先查远程主机，再查 JumpServer 授权；均无匹配时自动保存主机，使用选定的默认私钥凭证或宿主默认私钥文件。
- JumpServer：实例配置、按需节点树、分页资产、授权账号、fresh token 与 Koko SSH 网关。
终端与工作台¶
- 可选 DSH 宿主本地 PTY；多终端、尺寸同步、手工输入、终端搜索、断开和重连。
- 终端默认 12px；设置中可调 8–32px，即时应用并保存在当前浏览器。
AI 工具与权限¶
- 14 个
zterm_*工具；默认读模式，人类在已绑定终端工具栏勾选「允许AI写操作」后进入读写模式；未勾选时通用写命令被拒绝。 - 真正的退出码和完成边界；终端串行锁、取消、发送前授权复核、结果不明隔离、重复 callId 防重放。
- 集成 DSH 设置及凭据库、操作记录与导出、恢复上次目标列表。
执行与数据边界（使用前应知晓）¶
- AI 执行要求空闲 POSIX Shell；每次调用使用独立子 Shell，
cd／export不改变后续调用的环境。 - 终端在 DSH 宿主执行，本地终端对应宿主而非浏览器所在电脑。
- 授权只在内存中，刷新页面、换绑定目标、重连或插件重载均不恢复旧读写权限。
- 配置在 DSH 设置，秘密在 DSH 凭据库；指纹、调用标识、目标列表和操作记录在
$DSH_HOME/zterm/（未设置时为~/.dsh/zterm/）。记录和终端导出有上限，不能当作外部归档成功的回执。
许可证为 MIT，并保留 zterm 原始许可说明；Node.js 要求 >=22。
安装与启用¶
基线为 DSH 0.2.0-rc.2、Node.js 22 以上。Better Sidebar 为可选对等依赖（README 已核对 Web 0.24.1 的 Tab 契约）；@deepseek-ai/dsh-tools 亦为可选 peer。真实模型与真实测试机上的验收需自行完成。
README 给出的安装方式是从本地包或源码联调目录装入指定 profile（示例为 Web profile），不是凭仓库名拼接的通用 dsh plugin add github:... 命令：
把已生成的本地包安装到目标 profile，例如：
dsh plugin --profile web add "/path/to/dsh-zterm/out/dsh-zterm-0.1.10.tgz"
本地源码联调：
dsh plugin --profile web add "link:/path/to/dsh-zterm"
通过现有 DSH 界面或方式加载或重载插件后刷新页面。以上示例仅操作 Web profile，桌面 profile 不受影响。
包管理器须允许本插件的 postinstall 及所需原生依赖构建脚本。scripts/prepare-native.mjs 仅修复本依赖目录中 macOS node-pty 的 spawn-helper 执行位；SSH 不依赖本地 PTY，只有开启宿主本地终端才需要可用的 node-pty。若安装策略跳过了插件脚本，应在本插件目录中执行该脚本后再验收本地 PTY。
典型用法¶
按 README「开始使用」可复现的主流程如下。
- 在「设置 → zTerm」的【保存设置】下方管理凭证：名称、类型、内容；添加主机时选择已保存凭证名称，或设置默认 SSH 私钥凭证供 AI 自动新增主机时使用。
- 在对话中指定主机名或 IP。AI 使用
zterm_connect自动查找、保存并连接；也可点「zTerm」，从右侧选择已保存目标。 - 点击目标建立连接；通过可信渠道核实首次 SSH 指纹。连接完成后点「绑定 AI」，或由 AI 调用
zterm_bind。 - 让 AI 用目录、文件、系统、进程或端口等读工具检查机器（默认读模式下通用命令被拒绝）。
- 需要修改时，人类在已绑定终端勾选「允许AI写操作」；AI 可连续执行策略允许的命令，默认每次授权最多 100 条。
- 通过读工具、监控或日志复核效果后，使用
zterm_results把记录交给其它插件归档。
补充行为：手工输入后 AI 暂停并切回读模式；结束 vim／less 等交互程序、确认空闲 Shell 后点「确认空闲 Shell」。切换可见标签不会切换 AI 绑定目标。更完整的流程、设置与 FAQ 见仓库内 中文使用指南。
适用场景与注意¶
适合谁：已在 DSH 中用多插件做证据链（监控、日志、工单等），并需要在同一工作台里 SSH／JumpServer 到真实机器做只读核查，且在人类显式授权后再做有限写操作与结果导出的开发者或运维人员。
权限与安全：插件以当前 DSH 进程及其宿主环境权限运行；安装前应阅读源码与 MIT 许可证及 THIRD_PARTY_NOTICES.md。不要把任意远端输出视为已完全脱敏；人工终端会显示机器实际输出。
生态说明：DSH 奉行「一切皆插件」；SkillHub 目录页 为社区收录站点，与 DeepSeek／幻方无官方从属关系。
结尾¶
dsh-zterm 把 zTerm 的真实机器终端能力嵌入 DSH 对话与工作台：命名凭证与 JumpServer、默认只读与人类开启的写操作、14 个 zterm_* 工具与结果记录，便于与 Grafana、OpenSearch 等插件组成「取证 → 上机核验 → 归档」的闭环。
