dsh-zterm 0.0.0-stage → 0.1.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zTerm contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# zTerm
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把 [zterm](https://github.com/guhanfei-ai/zterm) 的真实机器终端能力移植到 DeepSeek Harness（DSH）。DSH 负责 AI、对话与跨工具流程，zTerm 提供机器连接、终端、受限读工具、人类开启的读写操作和实际结果记录。安装包名为 `dsh-zterm`。
+
+```text
+DSH 对话中指定主机，结合 Grafana / OpenSearch 等证据
+    → 取得资产与证据
+    → zTerm 连接、读取、操作和核验机器
+    → DSH 使用其它插件复核并归档结果
+```
+
+右侧工作台中，终端在左，主机／文件夹／JumpServer 资产列表在右。有 Better Sidebar 时使用独立 Tab，与脑图切换；没有时使用可调宽的独立大面板。
+
+## 当前交付
+
+- SSH 密码、私钥内容、宿主私钥文件；设置中保存命名凭证，多台主机按名称选用，私钥可直接选文件导入。
+- 对话指定目标：先查远程主机，再查 JumpServer 授权；均无匹配时自动保存主机，使用选定的默认私钥凭证或宿主默认私钥文件。
+- JumpServer 实例、按需节点树、分页资产、授权账号、fresh token 与 Koko SSH 网关。
+- 可选 DSH 宿主本地 PTY；多终端、尺寸同步、手工输入、终端搜索、断开和重连。
+- 终端默认 12px；设置中可调 8–32px，即时应用并保存在当前浏览器。
+- 14 个 `zterm_*` 工具；默认读模式，人类在已绑定终端工具栏开启读写。
+- 真正的退出码和完成边界；终端串行锁、取消、发送前授权复核、结果不明隔离、重复 callId 防重放。
+- DSH 设置及凭据库、操作记录与导出、恢复上次目标列表。
+
+本插件负责连接、操作与真实结果；外部系统的查询与归档由 DSH 的其它工具完成。
+
+## 安装
+
+基线为 DSH `0.2.0-rc.2`、Node.js 22 以上。Better Sidebar 可选，已核对 Web `0.24.1` 的 Tab 契约。真实模型与真实测试机上的验收请自行完成；离线检查和界面夹具不能替代该验收。
+
+可以把已生成的本地包安装到目标 profile，例如 Web profile：
+
+```sh
+dsh plugin --profile web add "/path/to/dsh-zterm/out/dsh-zterm-0.1.10.tgz"
+```
+
+本地源码联调可使用：
+
+```sh
+dsh plugin --profile web add "link:/path/to/dsh-zterm"
+```
+
+`cordis.patch.yml` 使用插件 ID `zterm` 和包名 `dsh-zterm`。通过现有 DSH 界面／方式加载或重载插件，然后刷新页面。以上示例仅操作 Web profile，桌面 profile 不受影响。
+
+包管理器须允许本插件的 `postinstall` 和需要的原生依赖构建脚本。`scripts/prepare-native.mjs` 仅修复本依赖目录中 macOS `node-pty` 的 `spawn-helper` 执行位；不会改系统文件。SSH 不需要本地 PTY 原生模块；开启宿主本地终端才需要可用的 `node-pty`。如果安装策略跳过了本插件脚本，应在本插件目录中执行该脚本后再验收本地 PTY。
+
+日常检查与构建不执行 Git 写操作，也不启动或重启服务。维护者的发布入口见下方「发布」。
+
+## 开始使用
+
+1. 在「设置 → zTerm」的【保存设置】下方管理凭证：填写名称、类型和内容，私钥可选择文件导入。添加主机时选择已保存凭证的名称；同一凭证可以供多台主机使用。也可设置默认 SSH 私钥凭证，让 AI 自动新增主机时直接选用。
+2. 直接在对话中指定要访问的主机名或 IP。AI 使用 `zterm_connect` 自动查找、保存并连接；也可以点击「zTerm」，从右侧选择已保存的目标。
+3. 点击目标建立连接；通过可信渠道核实首次 SSH 指纹。连接完成后点「绑定 AI」，或由 AI 调用 `zterm_bind`。
+4. 让 AI 用目录、文件、系统、进程或端口读工具检查机器。默认读模式下通用命令被拒绝。
+5. 需要修改时，人类在当前已绑定终端手工勾选「允许AI写操作」开启读写模式；未勾选时保持读模式。AI 可连续执行策略允许的命令，默认每次授权最多 100 条。
+6. 通过读工具、监控或日志复核实际效果，再使用 `zterm_results` 把记录交给其它插件归档。
+
+手工输入后，AI 暂停并切回读模式。结束 vim／less 等交互程序、确认回到空闲 Shell 后，再点「确认空闲 Shell」。切换可见标签不会切换 AI 绑定目标。
+
+完整流程、设置和常见问题见 [中文使用指南](USERGUIDE.zh-CN.md)。
+
+## 检查与构建
+
+在项目目录中执行：
+
+```sh
+npm ci --cache ".cache/npm"
+npm run verify
+npm run check:package
+node "scripts/check-host.mjs" "<DSH 安装目录>/node_modules/@deepseek-ai/dsh"
+npm pack --ignore-scripts --pack-destination "out"
+```
+
+`verify` 包含 TypeScript、Vitest、宿主与客户端构建。测试只使用虚构数据、独立临时目录以及测试拥有的回环 HTTP／SSH／PTY，不连接真实机器。SDK 检查使用已安装包创建临时 Cordis 上下文，不启动真实 DSH。
+
+## 发布
+
+[deploy.sh](deploy.sh) 沿用 dsh-grafana 的维护者手动发布流程：
+
+```sh
+./deploy.sh release   # 输入版本号，验证后提交、打标签并推送
+./deploy.sh build     # 安装开发依赖、准备原生依赖、验证和编译，打包到 dist/
+./deploy.sh publish   # 校验当前版本安装包，发布到 npm 与 GitHub Release
+./deploy.sh all       # 依次执行上述三步
+```
+
+发布链路默认限 main 分支，凭证和确认提示与来源项目一致。构建保留已有版本产物；分发只使用当前包名与版本对应的归档，并核对包内版本、宿主及客户端 bundle。脚本可从任意目录调用，不安装到 DSH profile，也不重启 Web 或桌面服务。
+
+`release` 和 `all` 包含 Git 写操作，`publish` 会上传安装包，由维护者本人执行；AI 在本项目的 Git 写禁令仍然有效。
+
+## 执行和数据边界
+
+AI 执行要求空闲 POSIX Shell。每次调用使用独立子 Shell，`cd`／`export` 不改变后续调用的环境。结果不明的操作不会自动重试；核实远端后重建连接。
+
+终端在 DSH 宿主执行，本地终端对应宿主而非浏览器电脑。授权只在内存中，刷新页面、换绑定目标、重连或插件重载均不恢复旧读写权限。
+
+配置存放在 DSH 设置，秘密存放在 DSH 凭据库；插件的指纹、调用标识、目标列表和操作记录在 `$DSH_HOME/zterm/`，未设置时为 `~/.dsh/zterm/`。记录和终端导出有明确上限，不能作为外部归档成功的回执。不要把任意远端输出都视为已完全去除秘密的内容；人工终端本身会显示机器实际输出。
+
+MIT，保留 [zterm 原始许可](LICENSE)；来源及依赖许可见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,241 @@
+# 来源与第三方许可
+
+本项目将 [zterm](https://github.com/guhanfei-ai/zterm) 0.4.1 的终端核心移植到 DSH。移植基线为源项目提交 `602f5a215d28c24e9e86356779d105ce2221e964`（仅作来源标识，本工程没有执行 Git 写操作）。
+
+`src/core/` 的 SSH、PTY、JumpServer、终端完成协议、输出缓冲、内置读工具、命令限制、输入协调、主机信任与错误翻译均源自 zterm；DSH 的宿主适配、工具接口、存储和 React 工作台在本项目实现。有效回归测试保留了来源说明，并替换了源项目的 Pi/Electron 适配。
+
+zterm 的原始 MIT 许可保存在随包分发的 `LICENSE`。本项目没有分发源项目的 Electron 应用、模型运行时、用户配置、凭据或 Git 元数据。
+
+## 依赖说明
+
+xterm.js、Fit 和 Search 随客户端打包。ssh2、node-pty、Schemastery 和 TypeBox 作为 npm 依赖安装；各依赖及其传递依赖的原始许可证随各自包分发。React 由 DSH 宿主共享，本项目的生产客户端不打包第二份 React。
+
+以下保留本项目直接依赖的原始许可文本。
+
+## @xterm/xterm
+
+```text
+Copyright (c) 2017-2019, The xterm.js authors (https://github.com/xtermjs/xterm.js)
+Copyright (c) 2014-2016, SourceLair Private Company (https://www.sourcelair.com)
+Copyright (c) 2012-2013, Christopher Jeffrey (https://github.com/chjj/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
+
+## @xterm/addon-fit
+
+```text
+Copyright (c) 2019, The xterm.js authors (https://github.com/xtermjs/xterm.js)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
+
+## @xterm/addon-search
+
+```text
+Copyright (c) 2017, The xterm.js authors (https://github.com/xtermjs/xterm.js)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
+
+## ssh2
+
+```text
+Copyright Brian White. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+```
+
+## node-pty
+
+```text
+Copyright (c) 2012-2015, Christopher Jeffrey (https://github.com/chjj/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+
+
+The MIT License (MIT)
+
+Copyright (c) 2016, Daniel Imms (http://www.growingwiththeweb.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+
+MIT License
+
+Copyright (c) 2018 - present Microsoft Corporation
+
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## @deepseek-ai/schemastery
+
+```text
+MIT License
+
+Copyright (c) 2021-present Shigma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## @sinclair/typebox
+
+```text
+TypeBox
+
+Json Schema Type Builder with Static Type Resolution for TypeScript 
+
+The MIT License (MIT)
+
+Copyright (c) 2017-2025 Haydn Paterson (sinclair) <haydn.developer@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```

package/USERGUIDE.zh-CN.md

@@ -0,0 +1,126 @@
+# 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` 是否可执行。不要改系统配置来掩盖插件安装问题。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: zterm
+      name: dsh-zterm