# zTerm 中文使用指南

## 工作台

DSH 会话标题栏的「zTerm」打开右侧大框。左侧保留 DSH 对话，框内左侧是终端，右侧是主机与资产列表。拖动内部分隔线调整列表宽度，也可以收起列表。独立面板可以拖外侧边缘调宽；Better Sidebar 模式使用宿主的面板和 Tab。

终端标签只控制正在看的机器。底部「AI 绑定」显示 AI 真正操作的目标；绑定、读写授权和可见标签分别管理，避免切标签时误换机器。

终端默认字号为 12px。在 DSH「设置 → zTerm → 终端外观」中可调为 8–32px，立即应用到已打开的终端并同步行列数，无需重新连接。字号保存在当前浏览器，刷新后保留；其它浏览器使用自己的设置。

## 在对话中连接机器

告诉 AI 要访问哪台机器，例如「连接 root@192.0.2.21，查看服务状态」。AI 将明确目标交给 `zterm_connect`，宿主按以下顺序处理：

1. 精确查找已保存远程主机，复用其账号及认证配置。
2. 查找已配置 JumpServer 的授权资产及可连接账号。
3. 都没有匹配时，自动把目标保存到远程主机列表，使用设置里选择的默认 SSH 私钥凭证；没有选定凭证时使用宿主默认私钥文件。

不要求先手工添加主机。对话明确给出的账号和端口优先；新主机未指定账号时，采用设置中的默认账号，留空则使用 DSH 宿主当前用户。多候选会返回可选择的标识；查询失败或分页未完成不会被当成没有授权。

默认 SSH 凭证按名称从已保存的私钥内容或私钥文件凭证中选择。未选定时，可在「指定已有的宿主私钥文件」中填写路径；留空依次查找宿主的 `~/.ssh/id_ed25519`、`id_rsa`、`id_ecdsa`，选择第一个存在的文件。没有文件时主机仍已保存，补充认证后即可重连。不会生成密钥或把私钥内容发给 AI。首次 SSH 指纹确认和默认读模式仍然生效。

## 管理凭证

在「设置 → zTerm」中，【保存设置】按钮下方是「管理凭证」。列表只显示凭证名称和类型；新增时填写名称、类型、内容，然后点击【保存凭证】。

- 密码：输入密码，主机可以按凭证名称复用。
- 私钥内容：粘贴私钥，也可以点击「选择私钥文件」直接导入文件，不需要记路径。文件上传到运行 DSH 的机器，私钥内容存入 DSH 凭据库；加密私钥需填写口令。
- 私钥文件：填写运行 DSH 的机器上的绝对路径或 `~/` 路径，一次保存后按名称复用。DSH 在远端运行时，这里使用远端文件路径；浏览器的本地文件可通过「私钥内容」导入。

编辑可以修改名称、类型或内容；密码和私钥内容不会回显，留空保留原值，切换类型时须填写新的内容。口令可明确清除。更新后的凭证在下次连接或重连时生效，已有连接继续运行。保存凭证会刷新列表，并保留其它尚未保存的设置。

## 配置 SSH

点击右侧「＋ 主机」，填写名称、地址、端口、账号与文件夹，选择认证方式：

- 选择已保存凭证：按名称选择「管理凭证」中已保存的凭证，无需再次填写内容或路径；多台主机可选择同一凭证。
- 密码：也可以在当前主机的密码输入框单独填写。
- 私钥内容：粘贴私钥内容；如有口令则填写口令。编辑时留空保留原值，可明确移除此主机的口令引用。
- 私钥文件：填写 DSH 宿主上的绝对路径或 `~/` 路径，例如 `/srv/dsh/.ssh/id_ed25519`。DSH 部署在远端时，填写远端路径；浏览器电脑不需要这份文件。留空使用设置中的默认私钥文件；加密文件的口令填写在当前主机表单。

密码、私钥内容与口令写入 DSH 凭据库；私钥文件的内容仅在连接时由宿主读取，配置只保存路径。编辑名称或地址而把秘密留空时，保留原引用；切换认证方式须提供适合新方式的凭据。过期配置保存会被拒绝，应刷新列表再编辑。

右侧主机行的「⋯」可编辑，「×」可移除配置；移除配置不改变已经建立的连接。文件夹支持嵌套、新建、改名和调整父节点；移除文件夹前先移出主机和子文件夹。SSH 配置导出不包含秘密。

点击主机建立连接。首次连接显示 SSH 算法和 SHA256 指纹，需要通过管理员或其它可信渠道核实后选择「仅信任此次连接」或「信任并保存」。已保存指纹变化时连接会被拒绝；核实变更后可清除旧记录，再重新连接并确认。无法核实时取消连接。

## 配置 JumpServer

切换到「JumpServer」，点击「＋ 实例」。填写服务地址，选择 Access Key、Token 或账号密码。Access Key 的 ID 与 Secret 都进入 DSH 凭据库。

选择实例后，节点树按需获取。点节点名称筛选其资产，点箭头加载子节点；搜索和翻页只读取当前需要的资产。点资产后选择有连接权限的账号。连接和重连都会重新申请 fresh token，并经过 SSH 网关指纹确认。

节点路径 `key` 用于查子节点，`nodeId` 用于查节点资产；账号和资产使用稳定 ID。网关账号、密码和 fresh token 仅在宿主连接层处理，不作为模型工具参数。

## AI 默认读模式

连接就绪后，点「绑定 AI」。AI 也可以先用工具查找和连接目标，再调用 `zterm_bind` 明确绑定。`connecting` 仅表示开始建连，必须用 `zterm_sessions` 确认 `ready`。

读模式提供六类真实查询：

| 工具 | 用途 |
| --- | --- |
| `zterm_read_directory` | 列出指定目录，最多 200 项 |
| `zterm_read_file` | 有界文本读取、行范围和续读位置 |
| `zterm_search_text` | 字面关键词搜索，不递归、不展开脚本 |
| `zterm_read_system` | 系统、运行时间、内存和磁盘概况 |
| `zterm_list_processes` | 有界进程列表、PID 或名称筛选 |
| `zterm_list_sockets` | 使用目标现有的 ss／lsof 查询端口与连接 |

读工具由宿主生成固定查询，不接受任意 Shell 命令。它们仍使用登录账号的权限；这不是操作系统级只读沙箱。文件路径不展开 `~`、变量或通配符，拒绝设备、管道和常见凭据文件，能力缺失或读取范围越界会返回失败。

`zterm_read_context` 是有限终端历史和最近已验证结果，不能冒充实时机器信息。

## 人类开启读写

只有已绑定且就绪的终端可以开启读写。工具栏的「允许AI写操作」未勾选时为读模式；人类手工勾选后切换为读写模式，AI 可使用 `zterm_execute` 连续完成已经授权的操作，插件不新增普通命令逐条确认。

默认一次授权最多 100 条通用命令，可在设置中调为 1–1000。重新绑定同一目标不会续期或重置预算；关闭再由人类重新开启才形成新授权。命令仍须通过 zterm 原有策略。未知脚本、嵌套解释器和策略拒绝的命令不会因为开启读写而放行。DSH 其它策略的 ask／deny 仍独立生效。

例如在明确允许的测试目录写入内容，然后用文件读工具核验：

```json
{"command":"printf 'dsh-zterm smoke' > /tmp/dsh-zterm-smoke.txt"}
```

每次命令在独立 POSIX 子 Shell 执行。需要指定目录时，在同一条命令中使用 `cd /path && ...`；前一次 `cd`／`export` 不会影响下一次。命令退出成功不等于业务问题已解决，仍需要监控、日志或其它业务证据。

切回读模式、切换绑定目标、重连、页面刷新或宿主重载会撤销旧写权限。执行前、异步探测后和业务发送边界都会检查授权。已经发送的操作可能已经产生副作用，不能把撤销权限解释成回滚。

## 手工操作与停止

空闲时可以直接使用终端，复制、粘贴、搜索与常用终端快捷键沿用 xterm。手工输入撤销该目标的读写，并暂停 AI 的后续操作；退出交互程序、确认没有半行命令后，点击「确认空闲 Shell」。该确认不会自动恢复读写。

AI 正在占用终端时，不把手工输入混入它的协议。点击「停止」发出取消并切回读模式；停止不证明远端进程已经结束。如果业务已下发但没有可信完成回执，显示「结果不明」，保留手工终端供核实，禁止继续自动下发。核实远端状态后重新连接，再绑定并保持只读开始。

本地 Windows cmd／PowerShell 可以作为人工终端，AI 完成协议会拒绝这类目标。当前交付的原生 PTY 验证在 macOS arm64／Node 24 完成，其它平台需各自安装与运行验收。

## 记录、导出和恢复

点击「记录」查看实际目标、状态、退出码、完成语义、错误和有限输出；可导出 JSON。底部「导出终端」仅导出有界终端缓冲。AI 使用 `zterm_results` 取最近最多 200 条记录，交给其它归档工具。

| 状态 | 含义 |
| --- | --- |
| `executing` | 已进入执行流程，尚未核实结束 |
| `completed` | 收到可信完成边界，退出码为 0；业务仍需另行核验 |
| `failed` | 退出码非 0 或查询解码／业务读取失败 |
| `unknown` | 业务可能已经下发，未核实完成；不自动重试 |
| `not_sent` | 业务没有下发 |
| `blocked` | 执行守卫或参数／存储条件拒绝 |

重载后未完成的持久记录恢复为 `unknown`。已经处理过的工具 callId 在宿主重载后仍不重放。新的 DSH 会话有独立目标和调用标识。

工作台可以在空列表时「恢复上次终端列表」。这会重新建立连接，仍需可用配置／凭据和必要的指纹确认；不会重放命令或恢复写权限。部分配置失效时保留原始目标列表，修复后可再恢复。

记录文件逐条追加；内存展示与查询最多 200 条，重载历史只读文件末尾 2 MiB，单条输出最多 64,000 字符。记录查询的文本总预算为 64,000 字符，工作台轮询为 16,000 字符，近期正文优先，超限条目会标记截断。终端缓冲最多 5000 行，展示还受字符上限限制。长期完整审计与归档应交给其它团队能力，收到成功回执后才算完成。

## 设置和升级

DSH 设置里的「zTerm」可管理命名凭证、选择默认 SSH 私钥凭证，调整本地终端、默认登录账号、宿主默认私钥文件、面板默认宽度、终端数量、写命令预算和超时。本地终端默认关闭，自动目标查找不需要额外开启地址开关。

使用本地终端时，勾选「允许打开运行 DSH 的机器上的终端」并保存设置，然后打开 zTerm，点击面板右上方的「打开本机终端」。每次点击都会新建独立终端并切换到对应标签，可重复打开多个，数量受「每会话终端上限」控制。未启用时按钮置灰并提示去设置开启。「本机」指运行 DSH 的机器。

升级前由维护者备份 DSH 设置、凭据库和 `$DSH_HOME/zterm/`，安装新的本地包并通过现有方式重载插件。现有连接会释放；模式保持默认读。回退时装回原包并核对数据格式，不自动回滚机器上的实际操作。

遇到「凭据未配置」检查宿主凭据库；「配置已变化」刷新列表；「Shell 未就绪」先退出交互程序；「结果不明」先核实机器；本地 PTY 的 `posix_spawnp failed` 检查安装脚本和依赖自己的 `spawn-helper` 是否可执行。不要改系统配置来掩盖插件安装问题。