@linxin666/dsh-ssh 0.3.19 → 0.3.21

package/lib/types/client/body-mutations.d.ts

@@ -0,0 +1,45 @@
+/**
+ * One `document.body` MutationObserver per page, shared by every family
+ * plugin bundle.
+ *
+ * Family plugins that inject at the DOM level must notice when the shell
+ * re-renders around their injected node: the sidebar entry rows
+ * (sidebar-entry-core), the center-column panel containers
+ * (panel-mount-core), and the aggregate shell's column shims. Each consumer
+ * used to install its OWN `MutationObserver` on `document.body` with
+ * `{ childList: true, subtree: true }`, so a page carrying N family plugins
+ * paid N native observers and N callback invocations for EVERY mutation batch
+ * the app produced — chat token streaming alone produces many per second, and
+ * the count grows with the number of installed plugins.
+ *
+ * This module keeps exactly ONE body observer per page. The registry lives on
+ * `globalThis` under a `Symbol.for` key, so the per-package generated copies
+ * of this file (scripts/sync-shared.mjs) and separately bundled plugins all
+ * reach the same hub at runtime instead of one hub per module instance.
+ * Record subscribers receive the mutations accumulated since the last flush.
+ * Consumers that only re-check their DOM use subscribeBodyInvalidations:
+ * when all subscribers use that path, the hub retains no mutation records
+ * (or detached subtrees) while a background page's animation frames pause.
+ * Both paths run at most once per frame. The last subscriber disconnects the
+ * observer, cancels the pending frame and releases its records.
+ *
+ * Failure policy: without a DOM or `MutationObserver` the subscription is a
+ * no-op disposer (the same silence the per-consumer observers had), and when
+ * `requestAnimationFrame` is unavailable the flush runs synchronously so a
+ * subscriber is never silently dropped. A throwing subscriber cannot stop the
+ * others.
+ */
+/**
+ * Subscribe to a coalesced DOM re-check without retaining mutation records.
+ * The marked wrapper also works with an older hub, which delivers records
+ * that it simply ignores until a page reload picks up the updated hub.
+ */
+export declare function subscribeBodyInvalidations(subscriber: () => void): () => void;
+/**
+ * Subscribe to body-level childList mutations.
+ * @param subscriber - called at most once per animation frame with the records
+ *   collected since the previous flush; must be safe to run repeatedly.
+ * @returns the disposer removing this subscriber (and the observer when it was
+ *   the last one).
+ */
+export declare function subscribeBodyMutations(subscriber: (records: MutationRecord[]) => void): () => void;

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

@@ -36,6 +36,12 @@ export declare const zh: {
     readonly 'hosts.delete': "删除";
     readonly 'hosts.deleteConfirm': "确定删除主机「{alias}」？将同时停止其隧道。";
     readonly 'hosts.imported': "解析 {parsed} 个配置块，新增 {added} 台主机，跳过 {skipped} 个。";
+    readonly 'hosts.proxyBadge': "代理";
+    readonly 'import.reason.wildcard': "通配符 pattern，需手动配置";
+    readonly 'import.reason.existing': "别名已存在";
+    readonly 'import.reason.match': "Match 条件块，不支持";
+    readonly 'import.reason.invalid': "字段不合法，无法导入";
+    readonly 'import.more': "其余 {count} 个未显示";
     readonly 'hosts.testing': "连接测试中…";
     readonly 'hosts.testOk': "连接成功（{latency} ms）";
     readonly 'hosts.testFail': "连接失败：{error}";
@@ -62,7 +68,9 @@ export declare const zh: {
     readonly 'form.passwordHint': "明文保存在 $DSH_HOME/dsh-ssh.json（本机私有文件）";
     readonly 'form.passwordRequired': "密码认证需要填写密码。";
     readonly 'form.proxyJump': "跳板机别名";
-    readonly 'form.proxyJumpHint': "逗号分隔的本地主机别名，按顺序连接";
+    readonly 'form.proxyJumpHint': "逗号分隔的本地主机别名，或 [user@]host[:port] 地址，按顺序连接";
+    readonly 'form.proxyCommand': "ProxyCommand";
+    readonly 'form.proxyCommandHint': "OpenSSH ProxyCommand：%h 主机、%p 端口、%r 用户、%n 别名；留空或填 none 表示不使用。与跳板机别名互斥。";
     readonly 'form.description': "备注";
     readonly 'form.environment': "环境";
     readonly 'form.environmentHint': "如 development / production";

package/lib/types/client/panel/TunnelsTab.d.ts

@@ -1,6 +1,6 @@
 import type { SshApi } from '../api.ts';
 import type { TunnelInfo } from '../../protocol.ts';
-/** Live-tunnel polling interval while the tab is mounted (ms). */
+/** Live-tunnel polling interval while the tab and page are visible (ms). */
 export declare const TUNNEL_POLL_MS = 5000;
 /**
  * Return `next` only when the tunnel list changed in a user-visible way
@@ -12,6 +12,8 @@ export declare function diffTunnels(prev: TunnelInfo[] | null, next: TunnelInfo[
 /** Tunnels tab props. */
 export interface TunnelsTabProps {
     api: SshApi;
+    /** Pause automatic reads while the owning panel is closed, preserving form state. */
+    active?: boolean;
 }
 /** The tunnels tab. */
-export declare function TunnelsTab({ api }: TunnelsTabProps): import("react").JSX.Element;
+export declare function TunnelsTab({ api, active }: TunnelsTabProps): import("react").JSX.Element;

package/lib/types/client/panel-mount-core.d.ts

@@ -21,7 +21,7 @@
 import { type Root } from 'react-dom/client';
 /** Options for mountCenterPanel; dsh-ssh mount.tsx and dsh-task-board board-mount.tsx are the canonical consumers. */
 export interface CenterPanelMountOptions {
-    /** Render the panel React tree into a root (initial mount, remount, locale refresh). */
+    /** Render the panel tree (first open, remount while open, locale refresh). */
     render: (root: Root) => void;
     /** dataset key of the injected container's view attribute, e.g. `dshSshView` for `data-dsh-ssh-view`. */
     viewDatasetKey: string;

package/lib/types/client/sidebar-entry-core.d.ts

@@ -1,18 +1,3 @@
-/**
- * Shared sidebar entry injection core.
- *
- * dsh's sidebar shell exposes no slot an external plugin can register into,
- * so the entry row is injected between the shell's New Session button and the
- * workspace browser. The injection self-heals: a MutationObserver watches the
- * sidebar root and re-inserts the row whenever a React re-render displaces it
- * (re-insertion happens in the same frame, before paint, so no flicker).
- *
- * The row is plain DOM (no React tree) so it can never disturb the shell's
- * reconciliation; the view it toggles is a separate root owned by the caller.
- *
- * Packages receive this file as a generated copy via scripts/sync-shared.mjs;
- * edit the shared source and re-run the sync instead of editing a copy.
- */
 /** Per-package configuration for one sidebar entry row. */
 export interface SidebarEntryOptions {
     /** Full attribute name identifying the injected row (idempotency key), e.g. 'data-dsh-ssh-entry'. */

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

@@ -62,10 +62,30 @@ export declare function appendOutput(target: {
     text: string;
     truncated: boolean;
 }, chunk: Buffer, maxBytes: number): void;
+/**
+ * Parse an OpenSSH jump hop written as an address: `[user@]host[:port]`
+ * (an IPv6 literal must be bracketed). Returns undefined when the value is not
+ * an address at all.
+ */
+export declare function parseJumpSpec(spec: string): {
+    host: string;
+    port?: number;
+    user?: string;
+} | undefined;
+/**
+ * Resolve one ProxyJump spec: an alias configured in this plugin wins, and any
+ * other value is read as an OpenSSH address whose credentials come from the
+ * target entry (an ad-hoc hop has no stored auth of its own).
+ */
+export declare function resolveHop(engine: PoolEngine, entry: SshHostEntry, spec: string): SshHostEntry;
 /**
  * Build one full jump chain for an entry: hop clients connected through in
  * order, each forwarding a stream to the next destination, ending with the
  * target client. Shared by the pool and standalone shell sessions.
+ *
+ * A ProxyCommand is the transport that reaches its own host, so the entry's
+ * own command seeds the chain when there is no jump chain, and the first hop's
+ * command is used when the hop carries one.
  */
 export declare function connectChain(engine: PoolEngine, entry: SshHostEntry, onKeyboardInteractive?: KeyboardInteractiveHandler): Promise<{
     client: Client;

package/lib/types/engine/proxy-command.d.ts

@@ -0,0 +1,36 @@
+/**
+ * OpenSSH-compatible ProxyCommand transport: run the command with the user's
+ * shell and expose its stdio as a Duplex that ssh2 accepts as `sock`.
+ *
+ * The command comes verbatim from the user's own 0600 store file and runs with
+ * the DSH host process's privileges — the same trust the `ssh(1)` client gives
+ * the identical line in `~/.ssh/config`.
+ */
+import { type ChildProcess } from 'node:child_process';
+import { Duplex } from 'node:stream';
+/** Token source for one host: the values %h / %p / %r / %n expand to. */
+export interface ProxyTarget {
+    host: string;
+    port: number;
+    user: string;
+    /** The name the user addresses this host by (OpenSSH's %n). */
+    alias: string;
+}
+/** Expand the OpenSSH ProxyCommand tokens; unknown %X sequences stay verbatim. */
+export declare function expandProxyTokens(command: string, target: ProxyTarget): string;
+/** One running proxy command: its transport plus the process behind it. */
+export interface ProxyCommandProcess {
+    /** The duplex transport handed to ssh2 as `sock`. */
+    stream: Duplex;
+    /** The spawned shell; killing the stream kills it (and its process group). */
+    child: ChildProcess;
+}
+/**
+ * Start one ProxyCommand and bridge its stdio into a Duplex.
+ *
+ * Failure modes are reported through the stream: a spawn error, or an exit
+ * before the SSH handshake finished, destroys it with the exit status and the
+ * tail of the command's stderr instead of letting ssh2 wait for its own
+ * `readyTimeout`.
+ */
+export declare function startProxyCommand(rawCommand: string, target: ProxyTarget): ProxyCommandProcess;

package/lib/types/index.d.ts

@@ -39,7 +39,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 \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 \u6309 aliases/environment/tags \u81F3\u5C11\u4E00\u79CD\u975E\u7A7A selector \u7B5B\u9009\u540E\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";
+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 \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 \u6309 aliases/environment/tags \u81F3\u5C11\u4E00\u79CD\u975E\u7A7A selector \u7B5B\u9009\u540E\u96C6\u7FA4\u5E76\u53D1\u6267\u884C\uFF1B\u652F\u6301\u5BC6\u94A5/\u5BC6\u7801/ssh-agent \u8BA4\u8BC1\u3001passphrase \u5BC6\u94A5\u3001ProxyJump \u8DF3\u677F\u673A\uFF08\u522B\u540D\u6216 [user@]host[:port] \u5730\u5740\uFF09\u4E0E OpenSSH \u8BED\u4E49\u7684 ProxyCommand\uFF08\u8DF3\u8FC7\u5821\u5792\u673A\u5BA2\u6237\u7AEF\u573A\u666F\uFF0C\u53EA\u80FD\u7531\u7528\u6237\u5728 GUI \u914D\u7F6E\uFF0Cagent \u4E0D\u53EF\u5199\uFF09\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

@@ -33,6 +33,13 @@ export interface SshHostEntry {
     };
     /** Jump chain: local aliases connected through in order (ProxyJump). */
     proxyJump: string[];
+    /**
+     * OpenSSH-compatible ProxyCommand: a shell command whose stdio becomes the
+     * connection transport. Tokens %h (host) / %p (port) / %r (user) / %n (alias)
+     * expand before exec and %% is a literal percent; an empty value or 'none'
+     * means "no proxy command". Mutually exclusive with a non-empty proxyJump.
+     */
+    proxyCommand?: string;
     /** Free-form note. */
     description?: string;
     /** Deployment environment label (development / production / ...). */
@@ -54,6 +61,8 @@ export interface SshHostSummary {
     /** Whether the key path exists on the host machine (key auth only). */
     keyReady: boolean;
     proxyJump: string[];
+    /** Configured ProxyCommand, echoed to the browser so the form can edit it. */
+    proxyCommand?: string;
     description?: string;
     environment?: string;
     tags: string[];
@@ -132,18 +141,31 @@ export interface HostPayload {
      */
     auth?: SshHostEntry['auth'];
     proxyJump?: string[];
+    /**
+     * ProxyCommand to store. An empty string or 'none' clears a stored value;
+     * omitting the key leaves it untouched (PATCH semantics).
+     */
+    proxyCommand?: string;
     description?: string;
     environment?: string;
     tags?: string[];
     location?: string;
 }
+/** Why one ssh_config Host block was not imported. */
+export type ImportSkipReason = 'wildcard' | 'existing' | 'match' | 'invalid';
+/** One skipped ssh_config block and the reason it could not be imported. */
+export interface ImportSkipBlock {
+    /** Host pattern (or '`Match …`' label) that was skipped. */
+    name: string;
+    reason: ImportSkipReason;
+}
 /** Import outcome from ~/.ssh/config. */
 export interface ImportResult {
     parsed: number;
     added: number;
     skipped: number;
-    /** Aliases that failed to map (wildcard patterns, missing HostName, ...). */
-    skippedNames: string[];
+    /** Every skipped block with its reason, in scan order and deduplicated by name. */
+    skippedBlocks: ImportSkipBlock[];
 }
 /** JSON error body used by every route. */
 export interface ApiErrorBody {

package/lib/types/ssh-config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Minimal `~/.ssh/config` reader for the one-shot host import: Host blocks with
+ * `Include` expansion and explicit skip reasons. Values stay raw strings; the
+ * store maps them onto a HostPayload.
+ *
+ * Deliberate simplifications (documented in the package README):
+ *   - `Match` blocks are skipped — their options are conditional and must never
+ *     merge into the Host block above them.
+ *   - A multi-pattern `Host a b` line only exposes its first pattern.
+ *   - Include pathnames accept `~`, globs, and several whitespace-separated
+ *     pathnames, but not environment variables, `%` tokens, or quoting.
+ *   - Relative Include pathnames resolve against the directory of the config
+ *     file the import started from (OpenSSH: `~/.ssh` for a user config).
+ *   - A file that already contributed lines is never read twice, which doubles
+ *     as the Include cycle guard.
+ */
+import type { ImportSkipBlock } from './protocol.ts';
+/** One parsed Host block. */
+export interface SshBlock {
+    /** Raw Host line value (may hold several whitespace-separated patterns). */
+    pattern: string;
+    /** Lowercased option key/value pairs; the last occurrence of a key wins. */
+    props: Record<string, string>;
+}
+/** One config file read, with every Include expanded in place. */
+export interface SshConfigRead {
+    blocks: SshBlock[];
+    skipped: ImportSkipBlock[];
+}
+/**
+ * Parse one ssh_config file (Include expanded) into Host blocks plus the
+ * `Match` blocks that were deliberately skipped.
+ */
+export declare function readSshConfigBlocks(configPath: string): SshConfigRead;

package/lib/types/store.d.ts

@@ -42,12 +42,15 @@ export declare class HostStore {
     delete(alias: string): void;
     /**
      * Import hosts from `~/.ssh/config`: Host blocks with a single non-wildcard
-     * pattern and a HostName become entries (key auth via IdentityFile, jump
-     * hosts via ProxyJump). Existing aliases are skipped.
+     * pattern become entries (a missing HostName falls back to the pattern
+     * itself; key auth via IdentityFile; jump hosts via ProxyJump; ProxyCommand
+     * kept verbatim). `Include` files are expanded, and `Match` blocks,
+     * wildcard patterns, and aliases that already exist are skipped with a
+     * reason instead of silently disappearing.
      * @returns import statistics.
      */
     importFromSshConfig(): ImportResult;
-    private skippedNames;
+    private skippedBlocks;
     /**
      * Last parsed store keyed by file identity. list/find ride every acquire
      * and GUI refresh; re-reading and re-parsing the whole file each call is
@@ -59,5 +62,10 @@ export declare class HostStore {
 }
 /** Normalize an agent endpoint for storage: trim, expand `~`, and resolve the SSH_AUTH_SOCK token. */
 export declare function normalizeAgentPath(agentPath: string | undefined): string | undefined;
+/**
+ * Normalize a ProxyCommand for storage: trim, and treat an empty value or
+ * OpenSSH's `none` keyword as "no proxy command" (an explicit clear).
+ */
+export declare function normalizeProxyCommand(raw: string | undefined): string | undefined;
 /** Expand a leading `~` in a filesystem path. */
 export declare function expandHome(path: string): string;

package/lib/types/tools.d.ts

@@ -4,6 +4,30 @@
  * is immediately operable by any agent, and vice versa.
  */
 import type { SshEngine } from './engine.ts';
+import type { SshAuthKind, SshHostSummary } from './protocol.ts';
+/**
+ * One host row for the agent surface. The ProxyCommand STRING is deliberately
+ * projected to a boolean: the command may embed credentials for a bastion
+ * client, and the model only needs to know that the host goes through one.
+ */
+export interface AgentHostRow {
+    alias: string;
+    host: string;
+    port: number;
+    user: string;
+    auth: SshAuthKind;
+    keyReady: boolean;
+    proxyJump: string[];
+    proxyCommandConfigured: boolean;
+    description?: string;
+    environment?: string;
+    tags: string[];
+    location?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Project one summary onto the agent-facing row shape. */
+export declare function toAgentHostRow(host: SshHostSummary): AgentHostRow;
 /** The host-list tool. */
 export declare function sshListTool(engine: SshEngine): import("@deepseek-ai/dsh-tools").ToolDefinition;
 /** The command-execution tool. */

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.3.19",
+  "version": "0.3.21",
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
@@ -26,7 +26,7 @@
   },
   "dsh": {
     "engines": {
-      "dsh": ">=0.1.2-rc.1"
+      "dsh": ">=0.1.5-rc.1"
     },
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -52,18 +52,18 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-client-connection": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-scope": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-settings": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-timeout": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-connection": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-scope": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.5-rc.1",
     "@types/node": "^22.20.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "^18.3.5",

package/src/client/body-mutations.ts

@@ -0,0 +1,133 @@
+// Generated by scripts/sync-shared.mjs from shared/client/body-mutations.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * One `document.body` MutationObserver per page, shared by every family
+ * plugin bundle.
+ *
+ * Family plugins that inject at the DOM level must notice when the shell
+ * re-renders around their injected node: the sidebar entry rows
+ * (sidebar-entry-core), the center-column panel containers
+ * (panel-mount-core), and the aggregate shell's column shims. Each consumer
+ * used to install its OWN `MutationObserver` on `document.body` with
+ * `{ childList: true, subtree: true }`, so a page carrying N family plugins
+ * paid N native observers and N callback invocations for EVERY mutation batch
+ * the app produced — chat token streaming alone produces many per second, and
+ * the count grows with the number of installed plugins.
+ *
+ * This module keeps exactly ONE body observer per page. The registry lives on
+ * `globalThis` under a `Symbol.for` key, so the per-package generated copies
+ * of this file (scripts/sync-shared.mjs) and separately bundled plugins all
+ * reach the same hub at runtime instead of one hub per module instance.
+ * Record subscribers receive the mutations accumulated since the last flush.
+ * Consumers that only re-check their DOM use subscribeBodyInvalidations:
+ * when all subscribers use that path, the hub retains no mutation records
+ * (or detached subtrees) while a background page's animation frames pause.
+ * Both paths run at most once per frame. The last subscriber disconnects the
+ * observer, cancels the pending frame and releases its records.
+ *
+ * Failure policy: without a DOM or `MutationObserver` the subscription is a
+ * no-op disposer (the same silence the per-consumer observers had), and when
+ * `requestAnimationFrame` is unavailable the flush runs synchronously so a
+ * subscriber is never silently dropped. A throwing subscriber cannot stop the
+ * others.
+ */
+
+/** The page-wide hub: one observer plus its subscribers and pending records. */
+interface BodyMutationHub {
+  observer: MutationObserver
+  subscribers: Set<(records: MutationRecord[]) => void>
+  pending: MutationRecord[]
+  scheduled: boolean
+  frame?: number
+}
+
+/** Cross-bundle registry key; `Symbol.for` so every module copy agrees. */
+const HUB_KEY = Symbol.for('dsh-web.body-mutation-hub')
+const INVALIDATION_ONLY = Symbol.for('dsh-web.body-mutation-invalidation')
+type Subscriber = ((records: MutationRecord[]) => void) & { [INVALIDATION_ONLY]?: true }
+
+function needsRecords(subscribers: Set<(records: MutationRecord[]) => void>): boolean {
+  for (const listener of subscribers) {
+    if (!(listener as Subscriber)[INVALIDATION_ONLY]) return true
+  }
+  return false
+}
+
+/**
+ * Subscribe to a coalesced DOM re-check without retaining mutation records.
+ * The marked wrapper also works with an older hub, which delivers records
+ * that it simply ignores until a page reload picks up the updated hub.
+ */
+export function subscribeBodyInvalidations(subscriber: () => void): () => void {
+  const listener: Subscriber = () => { subscriber() }
+  listener[INVALIDATION_ONLY] = true
+  return subscribeBodyMutations(listener)
+}
+
+/**
+ * Subscribe to body-level childList mutations.
+ * @param subscriber - called at most once per animation frame with the records
+ *   collected since the previous flush; must be safe to run repeatedly.
+ * @returns the disposer removing this subscriber (and the observer when it was
+ *   the last one).
+ */
+export function subscribeBodyMutations(subscriber: (records: MutationRecord[]) => void): () => void {
+  if (typeof globalThis === 'undefined' || typeof document === 'undefined') return () => {}
+  if (typeof MutationObserver !== 'function') return () => {}
+  const registry = globalThis as unknown as Record<symbol, unknown>
+  let hub = registry[HUB_KEY] as BodyMutationHub | undefined
+  if (hub === undefined) {
+    const subscribers = new Set<(records: MutationRecord[]) => void>()
+    const created: BodyMutationHub = {
+      observer: undefined as unknown as MutationObserver,
+      subscribers,
+      pending: [],
+      scheduled: false,
+    }
+    const flush = (): void => {
+      created.frame = undefined
+      created.scheduled = false
+      const batch = created.pending
+      created.pending = []
+      for (const listener of [...subscribers]) {
+        if (!subscribers.has(listener)) continue
+        try {
+          listener(batch)
+        } catch {
+          // One subscriber must never break the others; the next flush retries it.
+        }
+      }
+    }
+    const schedule = (): void => {
+      if (created.scheduled) return
+      created.scheduled = true
+      if (typeof requestAnimationFrame === 'function') created.frame = requestAnimationFrame(flush)
+      else flush()
+    }
+    created.observer = new MutationObserver((records) => {
+      if (needsRecords(subscribers)) {
+        for (const record of records) created.pending.push(record)
+      }
+      schedule()
+    })
+    created.observer.observe(document.body ?? document.documentElement, { childList: true, subtree: true })
+    registry[HUB_KEY] = created
+    hub = created
+  }
+  const active = hub
+  active.subscribers.add(subscriber)
+  let subscribed = true
+  return () => {
+    if (!subscribed) return
+    subscribed = false
+    active.subscribers.delete(subscriber)
+    if (!needsRecords(active.subscribers)) active.pending = []
+    if (active.subscribers.size === 0 && registry[HUB_KEY] === active) {
+      active.observer.disconnect()
+      if (active.frame !== undefined && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(active.frame)
+      active.frame = undefined
+      active.pending = []
+      active.scheduled = false
+      delete registry[HUB_KEY]
+    }
+  }
+}

package/src/client/locales.ts

@@ -38,6 +38,12 @@ export const zh = {
   'hosts.delete': '删除',
   'hosts.deleteConfirm': '确定删除主机「{alias}」？将同时停止其隧道。',
   'hosts.imported': '解析 {parsed} 个配置块，新增 {added} 台主机，跳过 {skipped} 个。',
+  'hosts.proxyBadge': '代理',
+  'import.reason.wildcard': '通配符 pattern，需手动配置',
+  'import.reason.existing': '别名已存在',
+  'import.reason.match': 'Match 条件块，不支持',
+  'import.reason.invalid': '字段不合法，无法导入',
+  'import.more': '其余 {count} 个未显示',
   'hosts.testing': '连接测试中…',
   'hosts.testOk': '连接成功（{latency} ms）',
   'hosts.testFail': '连接失败：{error}',
@@ -65,7 +71,9 @@ export const zh = {
   'form.passwordHint': '明文保存在 $DSH_HOME/dsh-ssh.json（本机私有文件）',
   'form.passwordRequired': '密码认证需要填写密码。',
   'form.proxyJump': '跳板机别名',
-  'form.proxyJumpHint': '逗号分隔的本地主机别名，按顺序连接',
+  'form.proxyJumpHint': '逗号分隔的本地主机别名，或 [user@]host[:port] 地址，按顺序连接',
+  'form.proxyCommand': 'ProxyCommand',
+  'form.proxyCommandHint': 'OpenSSH ProxyCommand：%h 主机、%p 端口、%r 用户、%n 别名；留空或填 none 表示不使用。与跳板机别名互斥。',
   'form.description': '备注',
   'form.environment': '环境',
   'form.environmentHint': '如 development / production',
@@ -192,6 +200,12 @@ export const en: Record<keyof typeof zh, string> = {
   'hosts.delete': 'Delete',
   'hosts.deleteConfirm': 'Delete host "{alias}"? Its tunnels will be stopped.',
   'hosts.imported': 'Parsed {parsed} blocks, added {added} hosts, skipped {skipped}.',
+  'hosts.proxyBadge': 'proxy',
+  'import.reason.wildcard': 'wildcard pattern — configure it by hand',
+  'import.reason.existing': 'alias already configured',
+  'import.reason.match': 'Match block — not supported',
+  'import.reason.invalid': 'invalid fields — not imported',
+  'import.more': '{count} more not shown',
   'hosts.testing': 'Testing connection…',
   'hosts.testOk': 'Connected ({latency} ms)',
   'hosts.testFail': 'Connection failed: {error}',
@@ -218,7 +232,9 @@ export const en: Record<keyof typeof zh, string> = {
   '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',
+  'form.proxyJumpHint': 'Comma-separated local aliases or [user@]host[:port] addresses, chained in order',
+  'form.proxyCommand': 'ProxyCommand',
+  'form.proxyCommandHint': 'OpenSSH ProxyCommand: %h host, %p port, %r user, %n alias; empty or none disables it. Mutually exclusive with the jump chain.',
   'form.description': 'Description',
   'form.environment': 'Environment',
   'form.environmentHint': 'e.g. development / production',

package/src/client/panel/HostFormDialog.tsx

@@ -31,6 +31,7 @@ interface FormState {
   password: string
   agentPath: string
   proxyJump: string
+  proxyCommand: string
   description: string
   environment: string
   tags: string
@@ -55,6 +56,7 @@ function blankOf(editing: SshHostSummary | null | undefined): FormState {
     password: '',
     agentPath: '',
     proxyJump: (editing?.proxyJump ?? []).join(', '),
+    proxyCommand: editing?.proxyCommand ?? '',
     description: editing?.description ?? '',
     environment: editing?.environment ?? '',
     tags: (editing?.tags ?? []).join(', '),
@@ -121,6 +123,9 @@ export function HostFormDialog({ api, editing, onClose, onSaved }: HostFormDialo
       user,
       auth,
       proxyJump: splitList(form.proxyJump),
+      // Always sent (never omitted): an empty value is the explicit clear,
+      // because the API cannot express "remove this field" any other way.
+      proxyCommand: form.proxyCommand.trim(),
       description: form.description.trim() === '' ? undefined : form.description.trim(),
       environment: form.environment.trim() === '' ? undefined : form.environment.trim(),
       tags: splitList(form.tags),
@@ -212,6 +217,16 @@ export function HostFormDialog({ api, editing, onClose, onSaved }: HostFormDialo
           <input className={css.input} value={form.proxyJump} onChange={event => { set('proxyJump', event.target.value) }} />
           <span className={css.hint}>{tt('form.proxyJumpHint')}</span>
         </label>
+        <label className={css.field}>
+          <span className={css.fieldLabel}>{tt('form.proxyCommand')}</span>
+          <input
+            className={css.input}
+            value={form.proxyCommand}
+            placeholder="corp-vpn proxy %h %p %r"
+            onChange={event => { set('proxyCommand', event.target.value) }}
+          />
+          <span className={css.hint}>{tt('form.proxyCommandHint')}</span>
+        </label>
         <div className={css.formRow}>
           <label className={css.field}>
             <span className={css.fieldLabel}>{tt('form.environment')}</span>