@linxin666/dsh-ssh 0.2.7 → 0.2.9

package/lib/index.js

@@ -2,7 +2,7 @@ import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-sett
 import { closeSync, createReadStream, createWriteStream, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { Client } from "ssh2";
 import { homedir, tmpdir } from "node:os";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { createServer } from "node:net";
 import { unlink } from "node:fs/promises";
 import { randomBytes } from "node:crypto";
@@ -412,7 +412,7 @@ var require_lib$1 = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	});
 }));
 //#endregion
-//#region src/store.ts
+//#region src/dsh-home.ts
 var import_lib = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	var __defProp = Object.defineProperty;
 	var __name = (target, value) => __defProp(target, "name", {
@@ -1025,7 +1025,39 @@ var import_lib = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((export
 	module.exports = Schema;
 })))(), 1);
 /**
-* Host config store: one JSON file (`~/.dsh/dsh-ssh.json`) holding every
+* DSH_HOME resolution shared by the plugin family's Host halves: the
+* environment override wins, the platform home fallback follows. Mirrors
+* what dsh-pet and dsh-liangshen each used to implement locally.
+*/
+/** Expand a leading ~ (or ~user) in a path, platform-style. */
+function expandHome$1(path, home = homedir()) {
+	if (path === "~") return home;
+	if (path.startsWith("~/") || path.startsWith("~\\")) return join(home, path.slice(2));
+	return path;
+}
+/**
+* Resolve the DSH home directory.
+* @param env - process environment to read DSH_HOME from.
+* @param home - platform home directory fallback (test seam).
+* @returns the absolute DSH home path.
+*/
+function resolveDshHome(env = process.env, home = homedir()) {
+	const raw = env.DSH_HOME;
+	if (raw !== void 0 && raw.trim() !== "") {
+		const expanded = expandHome$1(raw.trim(), home);
+		return isAbsolute(expanded) ? expanded : join(process.cwd(), expanded);
+	}
+	return join(home, ".dsh");
+}
+/** Resolve the DSH home directory from the live environment. */
+function dshHome() {
+	return resolveDshHome();
+}
+//#endregion
+//#region src/store.ts
+/**
+* Host config store: one JSON file (`$DSH_HOME/dsh-ssh.json`, defaulting
+* to `~/.dsh`) holding every
 * SSH host entry, written atomically (tmp + rename). Also parses the user's
 * standard `~/.ssh/config` for one-shot import. Secrets (passwords,
 * passphrases) live in this user-owned file in plaintext — same trust model
@@ -1033,9 +1065,9 @@ var import_lib = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((export
 */
 /** File format version. */
 const FORMAT_VERSION = 1;
-/** Store file location: <home>/.dsh/dsh-ssh.json. */
+/** Store file location: $DSH_HOME/dsh-ssh.json (defaults to ~/.dsh). */
 function storePath() {
-	return join(homedir(), ".dsh", "dsh-ssh.json");
+	return join(dshHome(), "dsh-ssh.json");
 }
 /** The user's standard OpenSSH config path. */
 function sshConfigPath() {
@@ -2950,7 +2982,7 @@ function sshListTool(engine) {
 function sshExecTool(engine) {
 	return defineTool({
 		name: "ssh_exec",
-		description: "Execute a command on a configured SSH host by alias. Prefer combining independent read-only queries into one command. Triggers: run command on server, deploy, check server/status, service control, view logs, any remote operation.",
+		description: "Execute a shell command on a REMOTE SSH host by alias; the command runs on the remote host, never on this machine. For commands on this machine, use the local bash tool. Prefer combining independent read-only queries into one command. Triggers: run command on server, deploy, check server/status, service control, view logs, any remote operation.",
 		parameters: {
 			alias: {
 				type: "string",
@@ -3022,7 +3054,7 @@ function sshExecTool(engine) {
 function sshUploadTool(engine) {
 	return defineTool({
 		name: "ssh_upload",
-		description: "Upload a local file to a configured SSH host. The local path is on THIS machine (the dsh host). Triggers: upload file to server, deploy artifact, copy config to server.",
+		description: "Transfer a file FROM this machine (the dsh host) TO a remote SSH host. Use this only when the file must be copied to the remote host. Files that stay on this machine are handled with the local file tools (read / write / edit), not ssh_upload. Triggers: upload file to server, deploy artifact, copy config to server.",
 		parameters: {
 			alias: {
 				type: "string",
@@ -3032,12 +3064,12 @@ function sshUploadTool(engine) {
 			localPath: {
 				type: "string",
 				required: true,
-				description: "Absolute local file path on this machine."
+				description: "Absolute path of the source file on THIS machine (the dsh host) — not a path on the remote host."
 			},
 			remotePath: {
 				type: "string",
 				required: true,
-				description: "Destination path on the remote host (parent dirs are created)."
+				description: "Absolute destination path on the remote SSH host (parent dirs are created)."
 			}
 		},
 		output: {
@@ -3077,7 +3109,7 @@ function sshUploadTool(engine) {
 function sshDownloadTool(engine) {
 	return defineTool({
 		name: "ssh_download",
-		description: "Download a remote FILE from a configured SSH host to a local path on this machine. Directory download is not supported — download files individually. Triggers: download file from server, fetch remote log/artifact.",
+		description: "Copy a remote FILE from a configured SSH host to this machine (the dsh host). Use this only when the source is on the remote host; files already on this machine are read with the local file tools (read / write / edit), not ssh_download. Directory download is not supported — download files individually. Triggers: download file from server, fetch remote log/artifact.",
 		parameters: {
 			alias: {
 				type: "string",
@@ -3087,12 +3119,12 @@ function sshDownloadTool(engine) {
 			remotePath: {
 				type: "string",
 				required: true,
-				description: "Remote file path."
+				description: "Absolute path of the source file on the remote SSH host."
 			},
 			localPath: {
 				type: "string",
 				required: true,
-				description: "Absolute destination path on this machine."
+				description: "Absolute destination path on THIS machine (the dsh host)."
 			}
 		},
 		output: {
@@ -3457,7 +3489,7 @@ const DEFAULT_ANNOUNCE = false;
 /** Order of the announcement section within the tool-guidance band. */
 const SECTION_ORDER = 150;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-const SSH_GUIDANCE = "本机已安装 dsh-ssh 插件（DSH 远程 SSH 运维）：侧边栏「SSH」入口；在 dsh-web-ui 插件全家桶仓库（packages/dsh-ssh）统一维护。能力：主机配置存 ~/.dsh/dsh-ssh.json（可从 ~/.ssh/config 导入）；持久连接池复用长连接（空闲 30 分钟自动断开）；ssh_list 列出主机、ssh_exec 执行远程命令、ssh_upload/ssh_download 传输文件、ssh_tunnel 本地端口转发（访问远程数据库/内网服务）、ssh_cluster 集群并发执行；支持密钥/密码/ssh-agent 认证、passphrase 密钥与 ProxyJump 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。";
+const SSH_GUIDANCE = "本机已安装 dsh-ssh 插件（DSH 远程 SSH 运维）：侧边栏「SSH」入口；在 dsh-web-ui 插件全家桶仓库（packages/dsh-ssh）统一维护。能力：主机配置存 $DSH_HOME/dsh-ssh.json（默认 ~/.dsh）（可从 ~/.ssh/config 导入）；持久连接池复用长连接（空闲 30 分钟自动断开）；ssh_list 列出主机、ssh_exec 执行远程命令、ssh_upload/ssh_download 传输文件、ssh_tunnel 本地端口转发（访问远程数据库/内网服务）、ssh_cluster 集群并发执行；支持密钥/密码/ssh-agent 认证、passphrase 密钥与 ProxyJump 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。路径区分：本机（dsh host）上的文件与命令一律用本地工具（read / write / edit / bash），ssh_* 工具只针对远程主机上的路径。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。";
 /**
 * Mount the SSH engine, routes, tools, and announcement.
 * @param ctx - host plugin context carrying webServer/tools/systemPrompt.

package/lib/types/client/locales.d.ts

@@ -59,7 +59,7 @@ export declare const zh: {
     readonly 'form.keyPathHint': "如 ~/.ssh/id_ed25519";
     readonly 'form.passphrase': "密钥口令";
     readonly 'form.password': "密码";
-    readonly 'form.passwordHint': "明文保存在 ~/.dsh/dsh-ssh.json（本机私有文件）";
+    readonly 'form.passwordHint': "明文保存在 $DSH_HOME/dsh-ssh.json（本机私有文件）";
     readonly 'form.passwordRequired': "密码认证需要填写密码。";
     readonly 'form.proxyJump': "跳板机别名";
     readonly 'form.proxyJumpHint': "逗号分隔的本地主机别名，按顺序连接";

package/lib/types/dsh-home.d.ts

@@ -0,0 +1,16 @@
+/**
+ * DSH_HOME resolution shared by the plugin family's Host halves: the
+ * environment override wins, the platform home fallback follows. Mirrors
+ * what dsh-pet and dsh-liangshen each used to implement locally.
+ */
+/** Expand a leading ~ (or ~user) in a path, platform-style. */
+export declare function expandHome(path: string, home?: string): string;
+/**
+ * Resolve the DSH home directory.
+ * @param env - process environment to read DSH_HOME from.
+ * @param home - platform home directory fallback (test seam).
+ * @returns the absolute DSH home path.
+ */
+export declare function resolveDshHome(env?: NodeJS.ProcessEnv, home?: string): string;
+/** Resolve the DSH home directory from the live environment. */
+export declare function dshHome(): string;

package/lib/types/index.d.ts

@@ -38,7 +38,7 @@ export interface Config {
 }
 export declare const Config: z<Config>;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-export declare const SSH_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-ssh \u63D2\u4EF6\uFF08DSH \u8FDC\u7A0B SSH \u8FD0\u7EF4\uFF09\uFF1A\u4FA7\u8FB9\u680F\u300CSSH\u300D\u5165\u53E3\uFF1B\u5728 dsh-web-ui \u63D2\u4EF6\u5168\u5BB6\u6876\u4ED3\u5E93\uFF08packages/dsh-ssh\uFF09\u7EDF\u4E00\u7EF4\u62A4\u3002\u80FD\u529B\uFF1A\u4E3B\u673A\u914D\u7F6E\u5B58 ~/.dsh/dsh-ssh.json\uFF08\u53EF\u4ECE ~/.ssh/config \u5BFC\u5165\uFF09\uFF1B\u6301\u4E45\u8FDE\u63A5\u6C60\u590D\u7528\u957F\u8FDE\u63A5\uFF08\u7A7A\u95F2 30 \u5206\u949F\u81EA\u52A8\u65AD\u5F00\uFF09\uFF1Bssh_list \u5217\u51FA\u4E3B\u673A\u3001ssh_exec \u6267\u884C\u8FDC\u7A0B\u547D\u4EE4\u3001ssh_upload/ssh_download \u4F20\u8F93\u6587\u4EF6\u3001ssh_tunnel \u672C\u5730\u7AEF\u53E3\u8F6C\u53D1\uFF08\u8BBF\u95EE\u8FDC\u7A0B\u6570\u636E\u5E93/\u5185\u7F51\u670D\u52A1\uFF09\u3001ssh_cluster \u96C6\u7FA4\u5E76\u53D1\u6267\u884C\uFF1B\u652F\u6301\u5BC6\u94A5/\u5BC6\u7801/ssh-agent \u8BA4\u8BC1\u3001passphrase \u5BC6\u94A5\u4E0E ProxyJump \u8DF3\u677F\u673A\uFF1BWeb \u7EC8\u7AEF\u8D70 WebSocket\u3002\u9650\u5236\uFF1A\u4E3B\u673A\u64CD\u4F5C\u7531\u7528\u6237\u5728 GUI \u4E2D\u914D\u7F6E\u540E agent \u65B9\u53EF\u4F7F\u7528\uFF1B\u5BC6\u7801\u4EE5\u660E\u6587\u5B58\u5728\u7528\u6237\u4E3B\u76EE\u5F55\u79C1\u6709\u6587\u4EF6\uFF08\u6743\u9650 0600\uFF09\uFF1B\u547D\u4EE4\u8F93\u51FA\u539F\u6837\u8FD4\u56DE\u3001\u53EF\u80FD\u542B\u654F\u611F\u4FE1\u606F\uFF1B\u65AD\u7EBF\u91CD\u8FDE\u53EF\u80FD\u91CD\u653E\u975E\u5E42\u7B49\u547D\u4EE4\uFF1B\u4F20\u8F93/\u6267\u884C\u6D88\u8017\u771F\u5B9E\u8FDC\u7A0B\u8D44\u6E90\uFF0C\u5148\u786E\u8BA4\u518D\u64CD\u4F5C\u3002\u7528\u6237\u63D0\u5230\u300CSSH / \u8FDC\u7A0B\u670D\u52A1\u5668 / \u670D\u52A1\u5668\u64CD\u4F5C / \u8DF3\u677F\u673A / \u96A7\u9053 / \u90E8\u7F72 / \u4E0A\u4F20\u4E0B\u8F7D\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
+export declare const SSH_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-ssh \u63D2\u4EF6\uFF08DSH \u8FDC\u7A0B SSH \u8FD0\u7EF4\uFF09\uFF1A\u4FA7\u8FB9\u680F\u300CSSH\u300D\u5165\u53E3\uFF1B\u5728 dsh-web-ui \u63D2\u4EF6\u5168\u5BB6\u6876\u4ED3\u5E93\uFF08packages/dsh-ssh\uFF09\u7EDF\u4E00\u7EF4\u62A4\u3002\u80FD\u529B\uFF1A\u4E3B\u673A\u914D\u7F6E\u5B58 $DSH_HOME/dsh-ssh.json\uFF08\u9ED8\u8BA4 ~/.dsh\uFF09\uFF08\u53EF\u4ECE ~/.ssh/config \u5BFC\u5165\uFF09\uFF1B\u6301\u4E45\u8FDE\u63A5\u6C60\u590D\u7528\u957F\u8FDE\u63A5\uFF08\u7A7A\u95F2 30 \u5206\u949F\u81EA\u52A8\u65AD\u5F00\uFF09\uFF1Bssh_list \u5217\u51FA\u4E3B\u673A\u3001ssh_exec \u6267\u884C\u8FDC\u7A0B\u547D\u4EE4\u3001ssh_upload/ssh_download \u4F20\u8F93\u6587\u4EF6\u3001ssh_tunnel \u672C\u5730\u7AEF\u53E3\u8F6C\u53D1\uFF08\u8BBF\u95EE\u8FDC\u7A0B\u6570\u636E\u5E93/\u5185\u7F51\u670D\u52A1\uFF09\u3001ssh_cluster \u96C6\u7FA4\u5E76\u53D1\u6267\u884C\uFF1B\u652F\u6301\u5BC6\u94A5/\u5BC6\u7801/ssh-agent \u8BA4\u8BC1\u3001passphrase \u5BC6\u94A5\u4E0E ProxyJump \u8DF3\u677F\u673A\uFF1BWeb \u7EC8\u7AEF\u8D70 WebSocket\u3002\u9650\u5236\uFF1A\u4E3B\u673A\u64CD\u4F5C\u7531\u7528\u6237\u5728 GUI \u4E2D\u914D\u7F6E\u540E agent \u65B9\u53EF\u4F7F\u7528\uFF1B\u5BC6\u7801\u4EE5\u660E\u6587\u5B58\u5728\u7528\u6237\u4E3B\u76EE\u5F55\u79C1\u6709\u6587\u4EF6\uFF08\u6743\u9650 0600\uFF09\uFF1B\u547D\u4EE4\u8F93\u51FA\u539F\u6837\u8FD4\u56DE\u3001\u53EF\u80FD\u542B\u654F\u611F\u4FE1\u606F\uFF1B\u65AD\u7EBF\u91CD\u8FDE\u53EF\u80FD\u91CD\u653E\u975E\u5E42\u7B49\u547D\u4EE4\uFF1B\u4F20\u8F93/\u6267\u884C\u6D88\u8017\u771F\u5B9E\u8FDC\u7A0B\u8D44\u6E90\uFF0C\u5148\u786E\u8BA4\u518D\u64CD\u4F5C\u3002\u8DEF\u5F84\u533A\u5206\uFF1A\u672C\u673A\uFF08dsh host\uFF09\u4E0A\u7684\u6587\u4EF6\u4E0E\u547D\u4EE4\u4E00\u5F8B\u7528\u672C\u5730\u5DE5\u5177\uFF08read / write / edit / bash\uFF09\uFF0Cssh_* \u5DE5\u5177\u53EA\u9488\u5BF9\u8FDC\u7A0B\u4E3B\u673A\u4E0A\u7684\u8DEF\u5F84\u3002\u7528\u6237\u63D0\u5230\u300CSSH / \u8FDC\u7A0B\u670D\u52A1\u5668 / \u670D\u52A1\u5668\u64CD\u4F5C / \u8DF3\u677F\u673A / \u96A7\u9053 / \u90E8\u7F72 / \u4E0A\u4F20\u4E0B\u8F7D\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
 /**
  * Mount the SSH engine, routes, tools, and announcement.
  * @param ctx - host plugin context carrying webServer/tools/systemPrompt.

package/lib/types/protocol.d.ts

@@ -5,7 +5,7 @@
  */
 /** Authentication flavors a host entry may carry. */
 export type SshAuthKind = 'key' | 'password' | 'agent';
-/** One stored host entry (the ~/.dsh/dsh-ssh.json store shape). */
+/** One stored host entry (the $DSH_HOME/dsh-ssh.json store shape). */
 export interface SshHostEntry {
     /** Stable, user-chosen identifier used by every operation. */
     alias: string;

package/lib/types/store.d.ts

@@ -1,12 +1,13 @@
 /**
- * Host config store: one JSON file (`~/.dsh/dsh-ssh.json`) holding every
+ * Host config store: one JSON file (`$DSH_HOME/dsh-ssh.json`, defaulting
+ * to `~/.dsh`) holding every
  * SSH host entry, written atomically (tmp + rename). Also parses the user's
  * standard `~/.ssh/config` for one-shot import. Secrets (passwords,
  * passphrases) live in this user-owned file in plaintext — same trust model
  * as ssh-skill's annotated ssh-config comments; document it, never log it.
  */
 import type { HostPayload, ImportResult, SshHostEntry, SshHostSummary } from './protocol.ts';
-/** Store file location: <home>/.dsh/dsh-ssh.json. */
+/** Store file location: $DSH_HOME/dsh-ssh.json (defaults to ~/.dsh). */
 export declare function storePath(): string;
 /** The user's standard OpenSSH config path. */
 export declare function sshConfigPath(): string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linxin666/dsh-ssh",
   "description": "Remote SSH operations for the dsh web GUI: host config store (~/.dsh/dsh-ssh.json, import from ~/.ssh/config), a persistent ssh2 connection pool with jump-host support, exec / PTY web terminal / SFTP transfer / local port-forward tunnels / cluster execution, plus agent tools (ssh_list, ssh_exec, ssh_upload, ssh_download, ssh_tunnel, ssh_cluster). Hot-pluggable — mounted via ~/.dsh/cordis.patch.yml + a profile node_modules symlink, no dsh source changes.",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
@@ -25,6 +25,9 @@
     "./package.json": "./package.json"
   },
   "dsh": {
+    "engines": {
+      "dsh": ">=0.1.1-rc.1"
+    },
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
@@ -49,18 +52,18 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-client-connection": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-scope": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-settings": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-timeout": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-client-connection": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-scope": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
     "@types/node": "^22.20.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "^18.3.5",

package/src/client/locales.ts

@@ -62,7 +62,7 @@ export const zh = {
   'form.keyPathHint': '如 ~/.ssh/id_ed25519',
   'form.passphrase': '密钥口令',
   'form.password': '密码',
-  'form.passwordHint': '明文保存在 ~/.dsh/dsh-ssh.json（本机私有文件）',
+  'form.passwordHint': '明文保存在 $DSH_HOME/dsh-ssh.json（本机私有文件）',
   'form.passwordRequired': '密码认证需要填写密码。',
   'form.proxyJump': '跳板机别名',
   'form.proxyJumpHint': '逗号分隔的本地主机别名，按顺序连接',
@@ -209,7 +209,7 @@ export const en: Record<keyof typeof zh, string> = {
   'form.keyPathHint': 'e.g. ~/.ssh/id_ed25519',
   'form.passphrase': 'Key passphrase',
   'form.password': 'Password',
-  'form.passwordHint': 'Stored in plaintext in ~/.dsh/dsh-ssh.json (private local file)',
+  'form.passwordHint': 'Stored in plaintext in $DSH_HOME/dsh-ssh.json (private local file)',
   'form.passwordRequired': 'Password auth requires a password.',
   'form.proxyJump': 'Jump host aliases',
   'form.proxyJumpHint': 'Comma-separated local aliases, chained in order',

package/src/client/panel/HostsTab.tsx

@@ -105,15 +105,21 @@ export function HostsTab({ api, onConnect }: HostsTabProps) {
     return () => { clearTimeout(timer) }
   }, [search, load])
 
+  // Every async setState path guards with mountedRef, not just load(): a
+  // promise settling after unmount would setState against the torn-down
+  // environment (window is not defined, main-CI flake).
   const runTest = async (alias: string): Promise<void> => {
+    if (!mountedRef.current) return
     setTestingAlias(alias)
     try {
       const result = await api.testHost(alias)
+      if (!mountedRef.current) return
       setTestResults(prev => ({ ...prev, [alias]: result }))
     } catch (cause) {
+      if (!mountedRef.current) return
       setTestResults(prev => ({ ...prev, [alias]: { ok: false, error: errorMessage(cause) } }))
     } finally {
-      setTestingAlias(null)
+      if (mountedRef.current) setTestingAlias(null)
     }
   }
 
@@ -121,32 +127,38 @@ export function HostsTab({ api, onConnect }: HostsTabProps) {
     if (!window.confirm(tt('hosts.deleteConfirm', { alias }))) return
     try {
       await api.deleteHost(alias)
+      if (!mountedRef.current) return
       void load()
     } catch (cause) {
+      if (!mountedRef.current) return
       setError(errorMessage(cause))
     }
   }
 
   // Group-header batch action (#379): test every host in the group.
   const testGroup = async (group: HostGroup): Promise<void> => {
+    if (!mountedRef.current) return
     setTestingGroup(group.key)
     try {
       await Promise.all(group.hosts.map(host => runTest(host.alias)))
     } finally {
-      setTestingGroup(null)
+      if (mountedRef.current) setTestingGroup(null)
     }
   }
 
   const importConfig = async (): Promise<void> => {
+    if (!mountedRef.current) return
     setImporting(true)
     try {
       const result = await api.importSshConfig()
+      if (!mountedRef.current) return
       setNotice(tt('hosts.imported', { parsed: result.parsed, added: result.added, skipped: result.skipped }))
       void load()
     } catch (cause) {
+      if (!mountedRef.current) return
       setError(errorMessage(cause))
     } finally {
-      setImporting(false)
+      if (mountedRef.current) setImporting(false)
     }
   }
 

package/src/client/panel/SshPanel.tsx

@@ -55,7 +55,7 @@ export function SshPanel({ controller, api, terminalFont }: SshPanelProps) {
   }
 
   return (
-    <div className={css.panel}>
+    <div className={css.panel} data-dsh-plugin="ssh">
       <div className={css.panelHeader}>
         <button
           type="button"
@@ -70,7 +70,7 @@ export function SshPanel({ controller, api, terminalFont }: SshPanelProps) {
       </div>
       <div className={css.tabBar} role="tablist" data-dsh-part="tab-bar">
         {TABS.map(tab => (
-          <button key={tab.id} type="button" role="tab" aria-selected={activeTab === tab.id} data-active={activeTab === tab.id ? '' : undefined} className={css.tab} onClick={() => { setActiveTab(tab.id) }}>
+          <button key={tab.id} type="button" role="tab" aria-selected={activeTab === tab.id} data-active={activeTab === tab.id ? '' : undefined} data-dsh-part="tab" className={css.tab} onClick={() => { setActiveTab(tab.id) }}>
             {tab.label()}
           </button>
         ))}

package/src/client/panel/panel.module.css

@@ -49,12 +49,13 @@ html[data-dsh-ssh-active]:not([data-dsh-taskboard-active]) [class*='centerCol']
 /* --- sidebar entry row ------------------------------------------------------- */
 
 .entry {
+  box-sizing: border-box;
   display: flex;
   align-items: center;
-  gap: 8px;
+  gap: 10px;
   width: 100%;
-  height: 32px;
-  padding: 0 12px;
+  min-height: 36px;
+  padding: 0 10px;
   background: transparent;
   border: none;
   border-radius: 8px;
@@ -79,9 +80,17 @@ html[data-dsh-ssh-active]:not([data-dsh-taskboard-active]) [class*='centerCol']
   display: inline-flex;
   align-items: center;
   justify-content: center;
+  width: 24px;
+  height: 24px;
   flex: none;
 }
 
+.entryIcon svg {
+  display: block;
+  width: 18px;
+  height: 18px;
+}
+
 .entryLabel {
   overflow: hidden;
   text-overflow: ellipsis;
@@ -91,7 +100,9 @@ html[data-dsh-ssh-active]:not([data-dsh-taskboard-active]) [class*='centerCol']
 [data-dsh-frame][data-sidebar-collapsed] .entry {
   justify-content: center;
   padding: 0;
-  width: 100%;
+  width: 40px;
+  min-height: 40px;
+  margin-inline: auto;
 }
 
 [data-dsh-frame][data-sidebar-collapsed] .entryLabel {

package/src/client/sidebar-entry.ts

@@ -16,8 +16,8 @@ import { mountSidebarEntry as mountSharedSidebarEntry } from './sidebar-entry-co
 /** Stable data attribute identifying the injected entry row. */
 export const ENTRY_SELECTOR = '[data-dsh-ssh-entry]'
 
-/** Inline icon (matches the shell's 16px nav-icon look): a terminal prompt glyph. */
-const ICON = '<svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.3" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="2.5" width="12" height="11" rx="1.5"/><path d="M4.5 5.5l2.5 2.5-2.5 2.5"/><path d="M8.5 10.5h3"/></svg>'
+/** Inline terminal glyph sized to the shell's current sidebar navigation icons. */
+const ICON = '<svg viewBox="0 0 16 16" width="18" height="18" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="1.75" y="2.25" width="12.5" height="11.5" rx="1.75"/><path d="M4.25 5.25l2.75 2.75-2.75 2.75"/><path d="M8.5 10.75h3.25"/></svg>'
 
 /**
  * Mount the sidebar entry, waiting for the shell to render and self-healing

package/src/dsh-home.ts

@@ -0,0 +1,36 @@
+// Generated by scripts/sync-shared.mjs from shared/host/dsh-home.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * DSH_HOME resolution shared by the plugin family's Host halves: the
+ * environment override wins, the platform home fallback follows. Mirrors
+ * what dsh-pet and dsh-liangshen each used to implement locally.
+ */
+
+import { homedir } from 'node:os'
+import { isAbsolute, join } from 'node:path'
+
+/** Expand a leading ~ (or ~user) in a path, platform-style. */
+export function expandHome(path: string, home: string = homedir()): string {
+  if (path === '~') return home
+  if (path.startsWith('~/') || path.startsWith('~\\')) return join(home, path.slice(2))
+  return path
+}
+
+/**
+ * Resolve the DSH home directory.
+ * @param env - process environment to read DSH_HOME from.
+ * @param home - platform home directory fallback (test seam).
+ * @returns the absolute DSH home path.
+ */
+export function resolveDshHome(env: NodeJS.ProcessEnv = process.env, home: string = homedir()): string {
+  const raw = env.DSH_HOME
+  if (raw !== undefined && raw.trim() !== '') {
+    const expanded = expandHome(raw.trim(), home)
+    return isAbsolute(expanded) ? expanded : join(process.cwd(), expanded)
+  }
+  return join(home, '.dsh')
+}
+
+/** Resolve the DSH home directory from the live environment. */
+export function dshHome(): string {
+  return resolveDshHome()
+}

package/src/index.ts

@@ -64,7 +64,7 @@ const DEFAULT_ANNOUNCE = false
 const SECTION_ORDER = 150
 
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-export const SSH_GUIDANCE = '本机已安装 dsh-ssh 插件（DSH 远程 SSH 运维）：侧边栏「SSH」入口；在 dsh-web-ui 插件全家桶仓库（packages/dsh-ssh）统一维护。能力：主机配置存 ~/.dsh/dsh-ssh.json（可从 ~/.ssh/config 导入）；持久连接池复用长连接（空闲 30 分钟自动断开）；ssh_list 列出主机、ssh_exec 执行远程命令、ssh_upload/ssh_download 传输文件、ssh_tunnel 本地端口转发（访问远程数据库/内网服务）、ssh_cluster 集群并发执行；支持密钥/密码/ssh-agent 认证、passphrase 密钥与 ProxyJump 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。'
+export const SSH_GUIDANCE = '本机已安装 dsh-ssh 插件（DSH 远程 SSH 运维）：侧边栏「SSH」入口；在 dsh-web-ui 插件全家桶仓库（packages/dsh-ssh）统一维护。能力：主机配置存 $DSH_HOME/dsh-ssh.json（默认 ~/.dsh）（可从 ~/.ssh/config 导入）；持久连接池复用长连接（空闲 30 分钟自动断开）；ssh_list 列出主机、ssh_exec 执行远程命令、ssh_upload/ssh_download 传输文件、ssh_tunnel 本地端口转发（访问远程数据库/内网服务）、ssh_cluster 集群并发执行；支持密钥/密码/ssh-agent 认证、passphrase 密钥与 ProxyJump 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。路径区分：本机（dsh host）上的文件与命令一律用本地工具（read / write / edit / bash），ssh_* 工具只针对远程主机上的路径。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。'
 
 /**
  * Mount the SSH engine, routes, tools, and announcement.

package/src/protocol.ts

@@ -7,7 +7,7 @@
 /** Authentication flavors a host entry may carry. */
 export type SshAuthKind = 'key' | 'password' | 'agent'
 
-/** One stored host entry (the ~/.dsh/dsh-ssh.json store shape). */
+/** One stored host entry (the $DSH_HOME/dsh-ssh.json store shape). */
 export interface SshHostEntry {
   /** Stable, user-chosen identifier used by every operation. */
   alias: string

package/src/store.ts

@@ -1,5 +1,6 @@
 /**
- * Host config store: one JSON file (`~/.dsh/dsh-ssh.json`) holding every
+ * Host config store: one JSON file (`$DSH_HOME/dsh-ssh.json`, defaulting
+ * to `~/.dsh`) holding every
  * SSH host entry, written atomically (tmp + rename). Also parses the user's
  * standard `~/.ssh/config` for one-shot import. Secrets (passwords,
  * passphrases) live in this user-owned file in plaintext — same trust model
@@ -9,14 +10,15 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
+import { dshHome } from './dsh-home.ts'
 import type { HostPayload, ImportResult, SshHostEntry, SshHostSummary } from './protocol.ts'
 
 /** File format version. */
 const FORMAT_VERSION = 1
 
-/** Store file location: <home>/.dsh/dsh-ssh.json. */
+/** Store file location: $DSH_HOME/dsh-ssh.json (defaults to ~/.dsh). */
 export function storePath(): string {
-  return join(homedir(), '.dsh', 'dsh-ssh.json')
+  return join(dshHome(), 'dsh-ssh.json')
 }
 
 /** The user's standard OpenSSH config path. */

package/src/tools.ts

@@ -109,7 +109,7 @@ export function sshListTool(engine: SshEngine) {
 export function sshExecTool(engine: SshEngine) {
   return defineTool({
     name: 'ssh_exec',
-    description: 'Execute a command on a configured SSH host by alias. Prefer combining independent read-only queries into one command. ' +
+    description: 'Execute a shell command on a REMOTE SSH host by alias; the command runs on the remote host, never on this machine. For commands on this machine, use the local bash tool. Prefer combining independent read-only queries into one command. ' +
       'Triggers: run command on server, deploy, check server/status, service control, view logs, any remote operation.',
     parameters: {
       alias: { type: 'string', required: true, description: 'Host alias from ssh_list.' },
@@ -154,12 +154,12 @@ export function sshExecTool(engine: SshEngine) {
 export function sshUploadTool(engine: SshEngine) {
   return defineTool({
     name: 'ssh_upload',
-    description: 'Upload a local file to a configured SSH host. The local path is on THIS machine (the dsh host). ' +
+    description: 'Transfer a file FROM this machine (the dsh host) TO a remote SSH host. Use this only when the file must be copied to the remote host. Files that stay on this machine are handled with the local file tools (read / write / edit), not ssh_upload. ' +
       'Triggers: upload file to server, deploy artifact, copy config to server.',
     parameters: {
       alias: { type: 'string', required: true, description: 'Host alias from ssh_list.' },
-      localPath: { type: 'string', required: true, description: 'Absolute local file path on this machine.' },
-      remotePath: { type: 'string', required: true, description: 'Destination path on the remote host (parent dirs are created).' },
+      localPath: { type: 'string', required: true, description: 'Absolute path of the source file on THIS machine (the dsh host) — not a path on the remote host.' },
+      remotePath: { type: 'string', required: true, description: 'Absolute destination path on the remote SSH host (parent dirs are created).' },
     },
     output: {
       schema: {
@@ -191,12 +191,12 @@ export function sshUploadTool(engine: SshEngine) {
 export function sshDownloadTool(engine: SshEngine) {
   return defineTool({
     name: 'ssh_download',
-    description: 'Download a remote FILE from a configured SSH host to a local path on this machine. Directory download is not supported — download files individually. ' +
+    description: 'Copy a remote FILE from a configured SSH host to this machine (the dsh host). Use this only when the source is on the remote host; files already on this machine are read with the local file tools (read / write / edit), not ssh_download. Directory download is not supported — download files individually. ' +
       'Triggers: download file from server, fetch remote log/artifact.',
     parameters: {
       alias: { type: 'string', required: true, description: 'Host alias from ssh_list.' },
-      remotePath: { type: 'string', required: true, description: 'Remote file path.' },
-      localPath: { type: 'string', required: true, description: 'Absolute destination path on this machine.' },
+      remotePath: { type: 'string', required: true, description: 'Absolute path of the source file on the remote SSH host.' },
+      localPath: { type: 'string', required: true, description: 'Absolute destination path on THIS machine (the dsh host).' },
     },
     output: {
       schema: {