@linxin666/dsh-ssh 0.2.4 → 0.2.6

package/lib/index.js

@@ -1050,9 +1050,10 @@ function validateHostPayload(payload) {
 	const auth = p.auth;
 	if (auth !== void 0) {
 		if (typeof auth !== "object" || auth === null) return "auth must be an object";
-		if (auth.kind !== "key" && auth.kind !== "password") return "auth.kind must be key or password";
+		if (auth.kind !== "key" && auth.kind !== "password" && auth.kind !== "agent") return "auth.kind must be key, password or agent";
 		if (auth.kind === "key" && (typeof auth.keyPath !== "string" || auth.keyPath.trim() === "")) return "auth.keyPath is required for key auth";
 		if (auth.kind === "password" && auth.password !== void 0 && typeof auth.password !== "string") return "auth.password must be a string when provided";
+		if (auth.kind === "agent" && auth.agentPath !== void 0 && typeof auth.agentPath !== "string") return "auth.agentPath must be a string when provided";
 	}
 	if (p.port !== void 0 && (typeof p.port !== "number" || !Number.isInteger(p.port) || p.port < 1 || p.port > 65535)) return "port must be an integer in 1..65535";
 	if (p.proxyJump !== void 0 && (!Array.isArray(p.proxyJump) || p.proxyJump.some((x) => typeof x !== "string" || x === ""))) return "proxyJump must be an array of alias strings";
@@ -1092,6 +1093,7 @@ var HostStore = class {
 	summarize(entry) {
 		let keyReady = true;
 		if (entry.auth.kind === "key" && entry.auth.keyPath) keyReady = existsSync(expandHome(entry.auth.keyPath));
+		else if (entry.auth.kind === "agent") keyReady = false;
 		return {
 			alias: entry.alias,
 			host: entry.host,
@@ -1129,7 +1131,8 @@ var HostStore = class {
 				kind: payload.auth.kind,
 				keyPath: payload.auth.kind === "key" ? expandHome(payload.auth.keyPath?.trim() ?? "") : void 0,
 				passphrase: payload.auth.kind === "key" ? payload.auth.passphrase ?? void 0 : void 0,
-				password: payload.auth.kind === "password" ? payload.auth.password : void 0
+				password: payload.auth.kind === "password" ? payload.auth.password : void 0,
+				agentPath: payload.auth.kind === "agent" ? normalizeAgentPath(payload.auth.agentPath) : void 0
 			},
 			proxyJump: [...payload.proxyJump ?? []],
 			description: payload.description?.trim() || void 0,
@@ -1158,15 +1161,17 @@ var HostStore = class {
 		if (patch.user !== void 0) entry.user = patch.user.trim();
 		if (patch.auth !== void 0) {
 			const auth = patch.auth;
-			if (auth.kind !== "key" && auth.kind !== "password") throw new Error("auth.kind must be key or password");
+			if (auth.kind !== "key" && auth.kind !== "password" && auth.kind !== "agent") throw new Error("auth.kind must be key, password or agent");
 			if (auth.kind === "key" && (typeof auth.keyPath !== "string" || auth.keyPath.trim() === "")) throw new Error("auth.keyPath is required for key auth");
 			if (auth.kind === "password" && auth.password !== void 0 && typeof auth.password !== "string") throw new Error("auth.password must be a string when provided");
+			if (auth.kind === "agent" && auth.agentPath !== void 0 && typeof auth.agentPath !== "string") throw new Error("auth.agentPath must be a string when provided");
 			const keyChanged = auth.kind === "key" && auth.keyPath !== void 0 && expandHome(auth.keyPath.trim()) !== entry.auth.keyPath;
 			entry.auth = {
 				kind: auth.kind,
 				keyPath: auth.kind === "key" ? expandHome(auth.keyPath?.trim() ?? "") : void 0,
 				passphrase: auth.kind === "key" ? auth.passphrase !== void 0 ? auth.passphrase : keyChanged ? void 0 : entry.auth.passphrase : void 0,
-				password: auth.kind === "password" ? auth.password : void 0
+				password: auth.kind === "password" ? auth.password : void 0,
+				agentPath: auth.kind === "agent" ? auth.agentPath !== void 0 ? normalizeAgentPath(auth.agentPath) : entry.auth.agentPath : void 0
 			};
 		}
 		if (patch.proxyJump !== void 0) entry.proxyJump = [...patch.proxyJump];
@@ -1247,9 +1252,10 @@ var HostStore = class {
 				port: block.props.port !== void 0 ? Number.parseInt(block.props.port, 10) : 22,
 				user: block.props.user ?? process.env.USER ?? "root",
 				auth: {
-					kind: block.props.identityfile !== void 0 ? "key" : "password",
+					kind: block.props.identityfile !== void 0 ? "key" : block.props.identityagent !== void 0 && block.props.identityagent.toLowerCase() !== "none" ? "agent" : "password",
 					keyPath: block.props.identityfile,
-					password: block.props.password
+					password: block.props.password,
+					agentPath: block.props.identityagent !== void 0 && block.props.identityagent.toLowerCase() !== "none" ? normalizeAgentPath(block.props.identityagent) : void 0
 				},
 				proxyJump: block.props.proxyjump !== void 0 ? block.props.proxyjump.split(",").map((hop) => hop.trim()).filter((hop) => hop !== "") : [],
 				description: block.props.description,
@@ -1325,6 +1331,16 @@ var HostStore = class {
 		this.cache = void 0;
 	}
 };
+/** Normalize an agent endpoint for storage: trim, expand `~`, and resolve the SSH_AUTH_SOCK token. */
+function normalizeAgentPath(agentPath) {
+	const trimmed = agentPath?.trim();
+	if (trimmed === void 0 || trimmed === "") return void 0;
+	if (trimmed === "SSH_AUTH_SOCK" || trimmed === "$SSH_AUTH_SOCK") {
+		const sock = process.env.SSH_AUTH_SOCK;
+		return sock !== void 0 && sock !== "" ? sock : void 0;
+	}
+	return expandHome(trimmed);
+}
 /** Expand a leading `~` in a filesystem path. */
 function expandHome(path) {
 	if (path === "~") return homedir();
@@ -1359,7 +1375,11 @@ function buildConnectConfig(entry, sock, opts) {
 	};
 	if (sock !== void 0) config.sock = sock;
 	if (entry.auth.kind === "password") config.password = entry.auth.password;
-	else {
+	else if (entry.auth.kind === "agent") {
+		const agentPath = resolveAgentPath(entry.auth.agentPath);
+		if (agentPath === void 0) throw new Error("ssh-agent is not available: set SSH_AUTH_SOCK or configure an agent path (use 'pageant' for PuTTY Pageant on Windows)");
+		config.agent = agentPath;
+	} else {
 		const keyPath = entry.auth.keyPath === void 0 ? void 0 : expandHome(entry.auth.keyPath);
 		if (keyPath === void 0 || !existsSync(keyPath)) throw new Error("private key not found: " + (entry.auth.keyPath ?? "(unset)"));
 		config.privateKey = readFileSync(keyPath, "utf8");
@@ -1367,6 +1387,14 @@ function buildConnectConfig(entry, sock, opts) {
 	}
 	return config;
 }
+/** Resolve the ssh2 agent path for 'agent' auth. */
+function resolveAgentPath(agentPath) {
+	const explicit = normalizeAgentPath(agentPath);
+	if (explicit !== void 0) return explicit;
+	const sock = process.env.SSH_AUTH_SOCK;
+	if (sock !== void 0 && sock !== "") return sock;
+	if (process.platform === "win32") return "pageant";
+}
 /** Connect one ssh2 client (resolve on ready, reject on error/close). */
 function connectClient(config) {
 	return new Promise((resolve, reject) => {
@@ -2875,7 +2903,11 @@ function sshListTool(engine) {
 							},
 							auth: {
 								type: "string",
-								enum: ["key", "password"],
+								enum: [
+									"key",
+									"password",
+									"agent"
+								],
 								required: true
 							},
 							keyReady: {
@@ -3425,7 +3457,7 @@ const DEFAULT_ANNOUNCE = true;
 /** 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 集群并发执行；支持密钥/密码认证、passphrase 密钥与 ProxyJump 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。";
+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 / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。";
 /**
 * Mount the SSH engine, routes, tools, and announcement.
 * @param ctx - host plugin context carrying webServer/tools/systemPrompt.

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

@@ -51,12 +51,16 @@ export declare const zh: {
     readonly 'form.auth': "认证方式";
     readonly 'form.auth.key': "密钥";
     readonly 'form.auth.password': "密码";
-    readonly 'form.authKeepHint': "编辑时密钥/密码留空将保留原认证方式与已存凭据；如需更换认证方式请填写新凭据。";
+    readonly 'form.auth.agent': "SSH Agent";
+    readonly 'form.agentPath': "Agent 路径";
+    readonly 'form.agentPathHint': "留空自动检测（SSH_AUTH_SOCK / Windows Pageant）；也可填 socket 路径或 pageant";
+    readonly 'form.authKeepHint': "编辑时密钥/密码/Agent 留空将保留原认证方式与已存凭据；如需更换认证方式请填写新凭据。";
     readonly 'form.keyPath': "私钥路径";
     readonly 'form.keyPathHint': "如 ~/.ssh/id_ed25519";
     readonly 'form.passphrase': "密钥口令";
     readonly 'form.password': "密码";
     readonly 'form.passwordHint': "明文保存在 ~/.dsh/dsh-ssh.json（本机私有文件）";
+    readonly 'form.passwordRequired': "密码认证需要填写密码。";
     readonly 'form.proxyJump': "跳板机别名";
     readonly 'form.proxyJumpHint': "逗号分隔的本地主机别名，按顺序连接";
     readonly 'form.description': "备注";

package/lib/types/engine/connection-pool.d.ts

@@ -48,6 +48,8 @@ export interface PoolEngine {
 }
 /** Build the ssh2 connect config for one entry (key read from disk). */
 export declare function buildConnectConfig(entry: SshHostEntry, sock: ConnectConfig['sock'] | undefined, opts: Required<EngineOptions>): ConnectConfig;
+/** Resolve the ssh2 agent path for 'agent' auth. */
+export declare function resolveAgentPath(agentPath?: string): string | undefined;
 /** Connect one ssh2 client (resolve on ready, reject on error/close). */
 export declare function connectClient(config: ConnectConfig): Promise<Client>;
 /** Cap captured output at the configured byte budget (marks truncation). */

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\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/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";
 /**
  * Mount the SSH engine, routes, tools, and announcement.
  * @param ctx - host plugin context carrying webServer/tools/systemPrompt.

package/lib/types/protocol.d.ts

@@ -4,7 +4,7 @@
  * each, no runtime identity to share.
  */
 /** Authentication flavors a host entry may carry. */
-export type SshAuthKind = 'key' | 'password';
+export type SshAuthKind = 'key' | 'password' | 'agent';
 /** One stored host entry (the ~/.dsh/dsh-ssh.json store shape). */
 export interface SshHostEntry {
     /** Stable, user-chosen identifier used by every operation. */
@@ -24,6 +24,12 @@ export interface SshHostEntry {
         passphrase?: string;
         /** Password for 'password' auth. */
         password?: string;
+        /**
+         * ssh-agent endpoint for 'agent' auth. A socket path, the special value
+         * 'pageant' (PuTTY Pageant on Windows), or undefined for auto-detect
+         * (SSH_AUTH_SOCK, then Pageant on Windows).
+         */
+        agentPath?: string;
     };
     /** Jump chain: local aliases connected through in order (ProxyJump). */
     proxyJump: string[];

package/lib/types/store.d.ts

@@ -56,5 +56,7 @@ export declare class HostStore {
     private load;
     private save;
 }
+/** Normalize an agent endpoint for storage: trim, expand `~`, and resolve the SSH_AUTH_SOCK token. */
+export declare function normalizeAgentPath(agentPath: string | undefined): string | undefined;
 /** Expand a leading `~` in a filesystem path. */
 export declare function expandHome(path: string): 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.4",
+  "version": "0.2.6",
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"

package/src/client/api.ts

@@ -34,6 +34,17 @@ export class SshApiError extends Error {
   }
 }
 
+/** Extract the `.error` message from a JSON error body; undefined when absent. */
+function extractError(text: string): string | undefined {
+  if (text === '') return undefined
+  try {
+    const parsed = JSON.parse(text) as { error?: unknown } | null
+    return typeof parsed?.error === 'string' ? parsed.error : undefined
+  } catch {
+    return undefined
+  }
+}
+
 /** Parse a JSON response or throw an SshApiError. */
 async function readJson<T>(response: Response): Promise<T> {
   let body: unknown
@@ -219,7 +230,9 @@ export class SshApi {
       body: file,
     })
     if (!response.ok || response.body === null) {
-      throw new SshApiError(`upload failed: HTTP ${response.status}`)
+      const text = await response.text().catch(() => '')
+      const error = extractError(text)
+      throw new SshApiError(error ?? `upload failed: HTTP ${response.status}`)
     }
     const reader = response.body.getReader()
     const decoder = new TextDecoder()
@@ -268,7 +281,8 @@ export class SshApi {
     const response = await fetch(SSH_API.download + query({ alias, remotePath }))
     if (!response.ok || response.body === null) {
       const text = await response.text().catch(() => '')
-      throw new SshApiError(text !== '' && text.startsWith('{') ? text : `download failed: HTTP ${response.status}`)
+      const error = extractError(text)
+      throw new SshApiError(error ?? `download failed: HTTP ${response.status}`)
     }
     const total = Number(response.headers.get('content-length') ?? '0')
     const disposition = response.headers.get('content-disposition') ?? ''

package/src/client/locales.ts

@@ -54,12 +54,16 @@ export const zh = {
   'form.auth': '认证方式',
   'form.auth.key': '密钥',
   'form.auth.password': '密码',
-  'form.authKeepHint': '编辑时密钥/密码留空将保留原认证方式与已存凭据；如需更换认证方式请填写新凭据。',
+  'form.auth.agent': 'SSH Agent',
+  'form.agentPath': 'Agent 路径',
+  'form.agentPathHint': '留空自动检测（SSH_AUTH_SOCK / Windows Pageant）；也可填 socket 路径或 pageant',
+  'form.authKeepHint': '编辑时密钥/密码/Agent 留空将保留原认证方式与已存凭据；如需更换认证方式请填写新凭据。',
   'form.keyPath': '私钥路径',
   'form.keyPathHint': '如 ~/.ssh/id_ed25519',
   'form.passphrase': '密钥口令',
   'form.password': '密码',
   'form.passwordHint': '明文保存在 ~/.dsh/dsh-ssh.json（本机私有文件）',
+  'form.passwordRequired': '密码认证需要填写密码。',
   'form.proxyJump': '跳板机别名',
   'form.proxyJumpHint': '逗号分隔的本地主机别名，按顺序连接',
   'form.description': '备注',
@@ -197,12 +201,16 @@ export const en: Record<keyof typeof zh, string> = {
   'form.auth': 'Authentication',
   'form.auth.key': 'Key',
   'form.auth.password': 'Password',
-  'form.authKeepHint': 'While editing, empty secret fields keep the stored authentication and credentials; enter new secrets to switch methods.',
+  'form.auth.agent': 'SSH Agent',
+  'form.agentPath': 'Agent path',
+  'form.agentPathHint': 'Leave empty to auto-detect (SSH_AUTH_SOCK / Pageant on Windows), or set a socket path or "pageant"',
+  'form.authKeepHint': 'While editing, empty secret fields keep the stored authentication and credentials; enter new values to switch methods.',
   'form.keyPath': 'Private key path',
   '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.passwordRequired': 'Password auth requires a password.',
   'form.proxyJump': 'Jump host aliases',
   'form.proxyJumpHint': 'Comma-separated local aliases, chained in order',
   'form.description': 'Description',

package/src/client/panel/HostFormDialog.tsx

@@ -29,6 +29,7 @@ interface FormState {
   keyPath: string
   passphrase: string
   password: string
+  agentPath: string
   proxyJump: string
   description: string
   environment: string
@@ -52,6 +53,7 @@ function blankOf(editing: SshHostSummary | null | undefined): FormState {
     keyPath: '',
     passphrase: '',
     password: '',
+    agentPath: '',
     proxyJump: (editing?.proxyJump ?? []).join(', '),
     description: editing?.description ?? '',
     environment: editing?.environment ?? '',
@@ -92,17 +94,27 @@ export function HostFormDialog({ api, editing, onClose, onSaved }: HostFormDialo
       setError(tt('form.portInvalid'))
       return
     }
+    // A password-auth host needs a password on create; when editing, a blank
+    // secret field preserves the stored credential instead.
+    if (editing == null && form.authKind === 'password' && form.password === '') {
+      setError(tt('form.passwordRequired'))
+      return
+    }
     // Secrets are never echoed back by the API: when editing and the secret
     // fields are left empty, the auth block is omitted so the stored
     // authentication is preserved.
     const secretEmpty = form.authKind === 'password'
       ? form.password === ''
-      : form.keyPath.trim() === ''
+      : form.authKind === 'key'
+        ? form.keyPath.trim() === ''
+        : form.agentPath.trim() === ''
     const auth: HostPayload['auth'] = editing != null && secretEmpty
       ? undefined
       : form.authKind === 'password'
         ? { kind: 'password', password: form.password }
-        : { kind: 'key', keyPath: form.keyPath.trim(), passphrase: form.passphrase === '' ? undefined : form.passphrase }
+        : form.authKind === 'key'
+          ? { kind: 'key', keyPath: form.keyPath.trim(), passphrase: form.passphrase === '' ? undefined : form.passphrase }
+          : { kind: 'agent', agentPath: form.agentPath.trim() === '' ? undefined : form.agentPath.trim() }
     const payload: HostPayload = {
       host,
       port,
@@ -163,6 +175,10 @@ export function HostFormDialog({ api, editing, onClose, onSaved }: HostFormDialo
               <input type="radio" name="dsh-ssh-auth" checked={form.authKind === 'password'} onChange={() => { set('authKind', 'password') }} />
               {tt('form.auth.password')}
             </label>
+            <label className={css.radioLabel}>
+              <input type="radio" name="dsh-ssh-auth" checked={form.authKind === 'agent'} onChange={() => { set('authKind', 'agent') }} />
+              {tt('form.auth.agent')}
+            </label>
           </div>
           {editing != null && <span className={css.hint}>{tt('form.authKeepHint')}</span>}
         </div>
@@ -178,6 +194,12 @@ export function HostFormDialog({ api, editing, onClose, onSaved }: HostFormDialo
               <input className={css.input} type="password" value={form.passphrase} onChange={event => { set('passphrase', event.target.value) }} />
             </label>
           </div>
+        ) : form.authKind === 'agent' ? (
+          <label className={css.field}>
+            <span className={css.fieldLabel}>{tt('form.agentPath')}</span>
+            <input className={css.input} value={form.agentPath} onChange={event => { set('agentPath', event.target.value) }} />
+            <span className={css.hint}>{tt('form.agentPathHint')}</span>
+          </label>
         ) : (
           <label className={css.field}>
             <span className={css.fieldLabel}>{tt('form.password')}</span>

package/src/client/panel/HostsTab.tsx

@@ -157,7 +157,7 @@ export function HostsTab({ api, onConnect }: HostsTabProps) {
         <td className={css.mono}>{host.alias}</td>
         <td className={css.mono}>{host.host}:{host.port}</td>
         <td>{host.user}</td>
-        <td><span className={css.badge} data-kind={host.auth}>{host.auth === 'key' ? tt('form.auth.key') : tt('form.auth.password')}</span></td>
+        <td><span className={css.badge} data-kind={host.auth}>{host.auth === 'key' ? tt('form.auth.key') : host.auth === 'password' ? tt('form.auth.password') : tt('form.auth.agent')}</span></td>
         <td className={css.cellMuted}>{host.environment ?? ''}</td>
         <td className={css.cellMuted}>{host.tags.join(', ')}</td>
         <td className={css.cellMuted}>{host.description ?? ''}</td>

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

@@ -414,6 +414,11 @@ html[data-dsh-ssh-active]:not([data-dsh-taskboard-active]) [class*='centerCol']
   border-color: var(--dsw-alias-state-warn-primary);
 }
 
+.badge[data-kind='agent'] {
+  color: var(--dsw-alias-state-success-primary);
+  border-color: var(--dsw-alias-state-success-primary);
+}
+
 .badge[data-status='ok'] {
   color: var(--dsw-alias-state-success-primary);
   border-color: var(--dsw-alias-state-success-primary);

package/src/engine/connection-pool.ts

@@ -6,7 +6,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { Client, type ConnectConfig } from 'ssh2'
 import type { ExecResult, SshHostEntry } from '../protocol.ts'
-import { expandHome, type HostStore } from '../store.ts'
+import { expandHome, normalizeAgentPath, type HostStore } from '../store.ts'
 
 /** Default engine knobs. */
 export interface EngineOptions {
@@ -74,6 +74,12 @@ export function buildConnectConfig(entry: SshHostEntry, sock: ConnectConfig['soc
   if (sock !== undefined) config.sock = sock
   if (entry.auth.kind === 'password') {
     config.password = entry.auth.password
+  } else if (entry.auth.kind === 'agent') {
+    const agentPath = resolveAgentPath(entry.auth.agentPath)
+    if (agentPath === undefined) {
+      throw new Error('ssh-agent is not available: set SSH_AUTH_SOCK or configure an agent path (use \'pageant\' for PuTTY Pageant on Windows)')
+    }
+    config.agent = agentPath
   } else {
     const keyPath = entry.auth.keyPath === undefined ? undefined : expandHome(entry.auth.keyPath)
     if (keyPath === undefined || !existsSync(keyPath)) {
@@ -87,6 +93,16 @@ export function buildConnectConfig(entry: SshHostEntry, sock: ConnectConfig['soc
   return config
 }
 
+/** Resolve the ssh2 agent path for 'agent' auth. */
+export function resolveAgentPath(agentPath?: string): string | undefined {
+  const explicit = normalizeAgentPath(agentPath)
+  if (explicit !== undefined) return explicit
+  const sock = process.env.SSH_AUTH_SOCK
+  if (sock !== undefined && sock !== '') return sock
+  if (process.platform === 'win32') return 'pageant'
+  return undefined
+}
+
 /** Connect one ssh2 client (resolve on ready, reject on error/close). */
 export function connectClient(config: ConnectConfig): Promise<Client> {
   return new Promise((resolve, reject) => {

package/src/index.ts

@@ -64,7 +64,7 @@ const DEFAULT_ANNOUNCE = true
 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 集群并发执行；支持密钥/密码认证、passphrase 密钥与 ProxyJump 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。'
+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 / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。'
 
 /**
  * Mount the SSH engine, routes, tools, and announcement.

package/src/protocol.ts

@@ -5,7 +5,7 @@
  */
 
 /** Authentication flavors a host entry may carry. */
-export type SshAuthKind = 'key' | 'password'
+export type SshAuthKind = 'key' | 'password' | 'agent'
 
 /** One stored host entry (the ~/.dsh/dsh-ssh.json store shape). */
 export interface SshHostEntry {
@@ -26,6 +26,12 @@ export interface SshHostEntry {
     passphrase?: string
     /** Password for 'password' auth. */
     password?: string
+    /**
+     * ssh-agent endpoint for 'agent' auth. A socket path, the special value
+     * 'pageant' (PuTTY Pageant on Windows), or undefined for auto-detect
+     * (SSH_AUTH_SOCK, then Pageant on Windows).
+     */
+    agentPath?: string
   }
   /** Jump chain: local aliases connected through in order (ProxyJump). */
   proxyJump: string[]

package/src/store.ts

@@ -38,13 +38,16 @@ export function validateHostPayload(payload: unknown): string | undefined {
   const auth = p.auth as Record<string, unknown> | undefined
   if (auth !== undefined) {
     if (typeof auth !== 'object' || auth === null) return 'auth must be an object'
-    if (auth.kind !== 'key' && auth.kind !== 'password') return 'auth.kind must be key or password'
+    if (auth.kind !== 'key' && auth.kind !== 'password' && auth.kind !== 'agent') return 'auth.kind must be key, password or agent'
     if (auth.kind === 'key' && (typeof auth.keyPath !== 'string' || auth.keyPath.trim() === '')) {
       return 'auth.keyPath is required for key auth'
     }
     if (auth.kind === 'password' && auth.password !== undefined && typeof auth.password !== 'string') {
       return 'auth.password must be a string when provided'
     }
+    if (auth.kind === 'agent' && auth.agentPath !== undefined && typeof auth.agentPath !== 'string') {
+      return 'auth.agentPath must be a string when provided'
+    }
   }
   if (p.port !== undefined && (typeof p.port !== 'number' || !Number.isInteger(p.port) || p.port < 1 || p.port > 65535)) {
     return 'port must be an integer in 1..65535'
@@ -101,6 +104,8 @@ export class HostStore {
     let keyReady = true
     if (entry.auth.kind === 'key' && entry.auth.keyPath) {
       keyReady = existsSync(expandHome(entry.auth.keyPath))
+    } else if (entry.auth.kind === 'agent') {
+      keyReady = false
     }
     return {
       alias: entry.alias,
@@ -143,6 +148,7 @@ export class HostStore {
         keyPath: payload.auth.kind === 'key' ? expandHome(payload.auth.keyPath?.trim() ?? '') : undefined,
         passphrase: payload.auth.kind === 'key' ? payload.auth.passphrase ?? undefined : undefined,
         password: payload.auth.kind === 'password' ? payload.auth.password : undefined,
+        agentPath: payload.auth.kind === 'agent' ? normalizeAgentPath(payload.auth.agentPath) : undefined,
       },
       proxyJump: [...(payload.proxyJump ?? [])],
       description: payload.description?.trim() || undefined,
@@ -184,13 +190,16 @@ export class HostStore {
     if (patch.user !== undefined) entry.user = patch.user.trim()
     if (patch.auth !== undefined) {
       const auth = patch.auth
-      if (auth.kind !== 'key' && auth.kind !== 'password') throw new Error('auth.kind must be key or password')
+      if (auth.kind !== 'key' && auth.kind !== 'password' && auth.kind !== 'agent') throw new Error('auth.kind must be key, password or agent')
       if (auth.kind === 'key' && (typeof auth.keyPath !== 'string' || auth.keyPath.trim() === '')) {
         throw new Error('auth.keyPath is required for key auth')
       }
       if (auth.kind === 'password' && auth.password !== undefined && typeof auth.password !== 'string') {
         throw new Error('auth.password must be a string when provided')
       }
+      if (auth.kind === 'agent' && auth.agentPath !== undefined && typeof auth.agentPath !== 'string') {
+        throw new Error('auth.agentPath must be a string when provided')
+      }
       // A changed key path with no passphrase means the new key has none;
       // only keep the old passphrase when the key path is unchanged.
       const keyChanged = auth.kind === 'key'
@@ -203,6 +212,9 @@ export class HostStore {
           ? (auth.passphrase !== undefined ? auth.passphrase : (keyChanged ? undefined : entry.auth.passphrase))
           : undefined,
         password: auth.kind === 'password' ? auth.password : undefined,
+        agentPath: auth.kind === 'agent'
+          ? (auth.agentPath !== undefined ? normalizeAgentPath(auth.agentPath) : entry.auth.agentPath)
+          : undefined,
       }
     }
     if (patch.proxyJump !== undefined) entry.proxyJump = [...patch.proxyJump]
@@ -281,9 +293,16 @@ export class HostStore {
         port: block.props.port !== undefined ? Number.parseInt(block.props.port, 10) : 22,
         user: block.props.user ?? process.env.USER ?? 'root',
         auth: {
-          kind: block.props.identityfile !== undefined ? 'key' : 'password',
+          kind: block.props.identityfile !== undefined
+            ? 'key'
+            : block.props.identityagent !== undefined && block.props.identityagent.toLowerCase() !== 'none'
+              ? 'agent'
+              : 'password',
           keyPath: block.props.identityfile,
           password: block.props.password,
+          agentPath: block.props.identityagent !== undefined && block.props.identityagent.toLowerCase() !== 'none'
+            ? normalizeAgentPath(block.props.identityagent)
+            : undefined,
         },
         proxyJump: block.props.proxyjump !== undefined
           ? block.props.proxyjump.split(',').map(hop => hop.trim()).filter(hop => hop !== '')
@@ -355,6 +374,17 @@ export class HostStore {
   }
 }
 
+/** Normalize an agent endpoint for storage: trim, expand `~`, and resolve the SSH_AUTH_SOCK token. */
+export function normalizeAgentPath(agentPath: string | undefined): string | undefined {
+  const trimmed = agentPath?.trim()
+  if (trimmed === undefined || trimmed === '') return undefined
+  if (trimmed === 'SSH_AUTH_SOCK' || trimmed === '$SSH_AUTH_SOCK') {
+    const sock = process.env.SSH_AUTH_SOCK
+    return sock !== undefined && sock !== '' ? sock : undefined
+  }
+  return expandHome(trimmed)
+}
+
 /** Expand a leading `~` in a filesystem path. */
 export function expandHome(path: string): string {
   if (path === '~') return homedir()

package/src/tools.ts

@@ -83,7 +83,7 @@ export function sshListTool(engine: SshEngine) {
                 host: { type: 'string', required: true },
                 port: { type: 'integer', required: true },
                 user: { type: 'string', required: true },
-                auth: { type: 'string', enum: ['key', 'password'], required: true },
+                auth: { type: 'string', enum: ['key', 'password', 'agent'], required: true },
                 keyReady: { type: 'boolean', required: true },
                 proxyJump: { type: 'array', items: { type: 'string' }, required: true },
                 description: { type: 'string' },