@goodandready/dsh-remote-workspace 0.3.7 → 0.3.9

package/README.md

@@ -99,6 +99,11 @@ graph LR
   - **Password Authentication**: Direct secure password authentication.
 - **Diagnostic Health Probing**: Built-in `testConnection` executes latency measurements (ping in milliseconds) and detects remote OS architecture (`uname -srm`).
 - **Resilience**: Heartbeat keep-alive packets prevent timeout disconnects from aggressive firewalls.
+- **Proxy and jump hosts**: `proxyCommand` runs an OpenSSH-style command. Tokens are `%h`, `%p`, `%r`, `%n`, and `%%`. `jumpHosts` is an ordered list of profile ids. A comma-separated `jumpHostId` is the fallback. The first bastion comes from the pool. Each later bastion has its own connection, released when the target session ends.
+- **Agent and one-time codes**: `agentPath` selects an agent socket. An empty value uses `SSH_AUTH_SOCK`, or Pageant on Windows when that is the configured path. A keyboard-interactive server shows its prompt on the card. The prompt expires after 60 seconds.
+- **Idle pool**: a pooled connection with no tunnel and no running command closes after 30 minutes. The next command opens it again.
+- **Reconnect before output**: if the connection drops before the command prints anything, the command runs again, up to three times. A command timeout, output that already started, or `idempotent: false` is not repeated.
+- **Separate terminal session**: the terminal does not share the pooled connection. Closing the terminal closes only that SSH session.
 
 ### 2. `RemoteFsService` — Resilient SFTP Operations
 - **Atomic File Writing**: Writes content to an ephemeral temporary file (`.tmp.<timestamp>.<hash>`) and renames it atomically upon complete upload, preventing partial or corrupted files.
@@ -122,13 +127,22 @@ Four orthogonal, high-leverage tools exposed directly to LLM agents:
 - `remote_fs`: Read, write, inspect, list, create directories, or delete files on the remote filesystem.
 - `remote_sync`: Synchronize files between the local mirror and remote server with conflict awareness and dry-run mode.
 - `remote_tunnel`: Start, stop, or list SSH port-forwarding tunnels.
+- `remote_hosts`: Return a compact markdown table of configured hosts. Secrets, private keys, and proxy commands are omitted. `query` is required; an empty query lists every host.
+- `remote_cluster`: Run one command on every host that matches an environment, every requested tag, and an optional alias list. `maxWorkers` defaults to 8.
 
 ### 6. `client.js` — Native DSH Settings Card UI
 - Designed strictly to DSH UX guidelines and styled after `dsh-clinebot`.
 - **Segmented Auth Switcher**: Clean tabbed toggle between Private Key and Password authentication.
 - **Remote Directory Browser Modal**: Interactive remote file browser with breadcrumb navigation and one-click path selection.
-- **Connection Diagnostic Badge**: Real-time ping testing with visual latency indicators and remote OS display.
-- **Action Triggers**: Quick buttons for directional synchronization and tunnel monitoring.
+- **Connection Diagnostic Badge**: Real-time ping testing with visual latency indicators and remote OS display. The header badge follows `/dsh-remote-workspace/state`: it shows a loading, empty, ready, or unavailable connection instead of a permanent Ready label.
+- **Action Triggers**: Quick buttons for directional synchronization and tunnel monitoring. A failed save, delete, activation, directory browse, or tunnel stop shows the server error in an alert on the card. Test Connection posts the profile fields, including `host`.
+- **Plugin list label**: English `Remote Workspace` or Chinese `远程开发工作区`, taken from the dictionaries already loaded with the card.
+- **Updater version**: the row shows the installed version returned by the status request. Before that response it shows "Version unknown".
+- **Host groups**: profiles can carry `environment`, `tags`, `location`, and `description`. The card can list them flat, by environment, or by tag, and test one group together.
+- **Files**: the Files tab uploads and downloads a remote file. Progress follows the bytes already moved, and Cancel stops the transfer. Files larger than 512MB are refused.
+- **Terminal font**: `terminalFontFamily` is a CSS font family for the terminal. Leave it empty for the default monospace stack.
+- **Hidden tab**: status polling pauses while the browser tab is hidden and refreshes when the tab returns.
+- **Sidebar workspace**: a Remote button in the left navigation opens the center column with Hosts, Terminal, Files, Containers, Tunnels, and Cluster. Switching back to chat hides that column and keeps the open terminal.
 
 ---
 
@@ -187,6 +201,15 @@ dsh-remote-workspace:
 | `profile.password` | `string` | `""` | Password for password-based authentication. |
 | `profile.remoteWorkspace` | `string` | `""` | Base directory of the project on the remote machine. |
 | `profile.localMirrorPath` | `string` | `""` | Local directory for mirror synchronization. |
+| `profile.agentPath` | `string` | `""` | SSH agent socket. Empty uses `SSH_AUTH_SOCK`. | 
+| `profile.proxyCommand` | `string` | `""` | OpenSSH ProxyCommand. Tokens: `%h` `%p` `%r` `%n`. | 
+| `profile.jumpHosts` | `string[]` | `[]` | Bastion profile ids, first hop first. | 
+| `profile.jumpHostId` | `string` | `""` | Comma-separated bastion ids when `jumpHosts` is empty. | 
+| `profile.environment` | `string` | `""` | Group and cluster filter, compared case-insensitively. | 
+| `profile.tags` | `string[]` | `[]` | Labels. A cluster filter requires every tag. | 
+| `profile.location` | `string` | `""` | Free-form place label. | 
+| `profile.description` | `string` | `""` | Free-form note. | 
+| `terminalFontFamily` | `string` | `""` | Terminal CSS font family. Empty keeps the default monospace stack. |
 
 ---
 
@@ -225,6 +248,23 @@ Manages SSH local port forwarding tunnels.
   - `tunnelId` (`string`, optional): Identifier of the tunnel to terminate (for `"stop"`).
 - **Returns**: `{ tunnelId, localPort, remotePort }` or `{ tunnels: [...] }` or `{ success: boolean }`.
 
+### `remote_hosts`
+Lists configured hosts for the model without secrets.
+- **Parameters**:
+  - `query` (`string`, required): Case-insensitive match against name, host, or id. An empty string lists every host.
+- **Returns**: A markdown table. Password, private key, key path, passphrase, agent socket, and proxy command are omitted.
+
+### `remote_cluster`
+Runs one shell command on a filtered set of hosts.
+- **Parameters**:
+  - `command` (`string`, required): Shell command.
+  - `environment` (`string`, optional): Exact environment name.
+  - `tags` (`string`, optional): Comma-separated tags. Every tag must match.
+  - `aliases` (`string`, optional): Comma-separated profile ids or names.
+  - `maxWorkers` (`number`, optional): Parallel connections. Default 8.
+- **Returns**: One row per host with success, exit code, duration, stdout, stderr, and error.
+- **Limit**: A host that fails to connect is reported on its own row. Other hosts still run.
+
 ---
 
 ## 🌐 HTTP API Routes Reference
@@ -240,6 +280,13 @@ All endpoints are hosted under `/dsh-remote-workspace`:
 | `POST` | `/dsh-remote-workspace/test` | Test SSH connectivity and latency. | Profile JSON object |
 | `POST` | `/dsh-remote-workspace/browse` | List directory contents for remote browser modal. | `{ profile: object, path: string }` |
 | `POST` | `/dsh-remote-workspace/sync` | Trigger manual pull or push synchronization. | `{ direction: "pull" \| "push", dryRun?: boolean, force?: boolean }` |
+| `POST` | `/dsh-remote-workspace/profiles/import-ssh-config` | Import `~/.ssh/config`, or the posted config text. | `{ content?: string }` |
+| `POST` | `/dsh-remote-workspace/profiles/test-group` | Test the stored profiles whose ids are posted. | `{ ids: string[] }` |
+| `POST` | `/dsh-remote-workspace/cluster` | Run one command on the filtered stored profiles. | `{ command, environment?, tags?, aliases?, maxWorkers? }` |
+| `GET` | `/dsh-remote-workspace/file/download` | Stream a remote file. Query: `profileId`, `filePath`. | — |
+| `POST` | `/dsh-remote-workspace/file/upload` | Upload a raw file body. Query: `profileId`, `filePath`. | file bytes |
+| `POST` | `/dsh-remote-workspace/terminal/font` | Save the terminal font family. | `{ fontFamily: string }` |
+| `POST` | `/dsh-remote-workspace/auth/keyboard` | Submit a keyboard-interactive code. | `{ id, answers }` |
 
 ---
 

package/README.ru.md

@@ -99,6 +99,11 @@ graph LR
   - **Пароль (Password)**: Прямая безопасная аутентификация по логину и паролю.
 - **Диагностический зонд**: Метод `testConnection` измеряет пинг в миллисекундах и определяет платформу удалённого хоста (`uname -srm`).
 - **Защита от таймаутов**: Пакеты keep-alive предотвращают разрыв соединения корпоративными фаерволами.
+- **Прокси и прыжки**: `proxyCommand` запускает команду в стиле OpenSSH. Токены: `%h`, `%p`, `%r`, `%n` и `%%`. `jumpHosts` — упорядоченный список идентификаторов профилей. Если массив пуст, используется `jumpHostId` через запятую. Первый бастион берётся из пула, следующие открывают отдельные соединения и закрываются вместе с целевой сессией.
+- **Агент и одноразовый код**: `agentPath` задаёт сокет агента. Пустое значение использует `SSH_AUTH_SOCK`, а на Windows можно указать `pageant`. Запрос keyboard-interactive появляется на карточке и истекает через 60 секунд.
+- **Простой пула**: соединение без туннеля и без выполняемой команды закрывается через 30 минут. Следующая команда открывает его снова.
+- **Повтор до вывода**: если соединение оборвалось до первого вывода, команда повторяется до трёх раз. Таймаут команды, уже начатый вывод и `idempotent: false` не повторяются.
+- **Отдельный терминал**: терминал не делит соединение пула. Закрытие терминала закрывает только его SSH-сессию.
 
 ### 2. `RemoteFsService` — Отказоустойчивый SFTP
 - **Атомарная запись файлов**: Загрузка производится во временный файл (`.tmp.<timestamp>.<hash>`) с последующим атомарным переименованием. Разрыв соединения не повреждает целевой файл.
@@ -122,13 +127,22 @@ graph LR
 - `remote_fs`: Операции чтения, записи, stat, листинга, создания директорий и удаления.
 - `remote_sync`: Синхронизация между локальным зеркалом и сервером с отчётом о конфликтах и режимом dry-run.
 - `remote_tunnel`: Управление SSH-туннелями (запуск, остановка, список).
+- `remote_hosts`: Краткая markdown-таблица хостов без паролей, ключей и команд прокси. `query` обязателен; пустая строка показывает все хосты.
+- `remote_cluster`: Одна команда на хостах, которые совпали по окружению, всем указанным меткам и необязательным псевдонимам. `maxWorkers` по умолчанию 8.
 
 ### 6. `client.js` — Нативный UI карточки настроек
 - Полноценная интеграция в слот `settings.plugin.item` с ключом `dsh-remote-workspace`.
 - **Сегментированный переключатель авторизации**: Удобное переключение между SSH-ключом и паролем.
 - **Интерактивный браузер удалённых папок**: Модальное окно с навигацией по каталогам и выбором рабочей директории в один клик.
-- **Индикатор статуса и задержки**: Проверка связи с отображением пинга и ОС удалённого узла.
-- **Кнопки действий**: Быстрый запуск синхронизации и контроль туннелей прямо из настроек.
+- **Индикатор статуса и задержки**: Проверка связи с отображением пинга и ОС удалённого узла. Бейдж шапки читает `/dsh-remote-workspace/state` и показывает проверку, отсутствие активного хоста, готовность или недоступность статуса.
+- **Кнопки действий**: Быстрый запуск синхронизации и контроль туннелей прямо из настроек. Ошибка сохранения, удаления, выбора активного профиля, обзора каталога или остановки туннеля показывается в предупреждении на карточке. Проверка соединения отправляет поля профиля, включая `host`.
+- **Подпись в списке плагинов**: английская `Remote Workspace` или китайская `远程开发工作区` из словарей карточки.
+- **Версия в блоке обновления**: строка показывает установленную версию из ответа статуса. Пока ответ не пришёл, показывается нейтральная подпись неизвестной версии.
+- **Группы хостов**: у профиля есть `environment`, `tags`, `location` и `description`. Карточка показывает плоский список, группы по окружению или по метке и может проверить группу целиком.
+- **Файлы**: вкладка Files загружает и скачивает удалённый файл, показывает прогресс по байтам и даёт отменить передачу. Файл больше 512 МБ отклоняется.
+- **Шрифт терминала**: `terminalFontFamily` — семейство шрифтов CSS. Пустое значение оставляет стандартный моноширинный набор.
+- **Скрытая вкладка**: опрос состояния останавливается, пока вкладка браузера скрыта, и сразу обновляется, когда вкладка снова видна.
+- **Боковая панель**: кнопка Remote слева открывает в центральной колонке хосты, терминал, файлы, контейнеры, туннели и кластер. Возврат в чат только скрывает колонку, буфер терминала сохраняется.
 
 ---
 
@@ -187,6 +201,15 @@ dsh-remote-workspace:
 | `profile.password` | `string` | `""` | Пароль для входа по логину и паролю. |
 | `profile.remoteWorkspace` | `string` | `""` | Путь к каталогу проекта на удалённом сервере. |
 | `profile.localMirrorPath` | `string` | `""` | Путь к локальному зеркалу проекта. |
+| `profile.agentPath` | `string` | `""` | Сокет SSH-агента. Пустое значение использует `SSH_AUTH_SOCK`. |
+| `profile.proxyCommand` | `string` | `""` | OpenSSH ProxyCommand. Токены: `%h` `%p` `%r` `%n`. |
+| `profile.jumpHosts` | `string[]` | `[]` | Идентификаторы бастионов, первый — вход. |
+| `profile.jumpHostId` | `string` | `""` | Бастионы через запятую, если `jumpHosts` пуст. |
+| `profile.environment` | `string` | `""` | Окружение для группы и фильтра кластера. |
+| `profile.tags` | `string[]` | `[]` | Метки. Фильтр кластера требует совпадения каждой. |
+| `profile.location` | `string` | `""` | Подпись места. |
+| `profile.description` | `string` | `""` | Заметка. |
+| `terminalFontFamily` | `string` | `""` | Семейство шрифта терминала. Пусто — стандартный моноширинный набор. |
 
 ---
 
@@ -225,6 +248,23 @@ dsh-remote-workspace:
   - `tunnelId` (`string`, для stop): Идентификатор туннеля для закрытия.
 - **Возвращает**: `{ tunnelId, localPort, remotePort }` или список туннелей `{ tunnels: [...] }`.
 
+### `remote_hosts`
+Список хостов для модели без секретов.
+- **Параметры**:
+  - `query` (`string`, обязательно): Поиск по имени, хосту или идентификатору. Пустая строка показывает все.
+- **Возвращает**: Markdown-таблицу. Пароль, ключ, путь к ключу, passphrase, сокет агента и proxy command не включаются.
+
+### `remote_cluster`
+Одна команда на отфильтрованном наборе хостов.
+- **Параметры**:
+  - `command` (`string`, обязательно): Команда оболочки.
+  - `environment` (`string`): Точное имя окружения.
+  - `tags` (`string`): Метки через запятую. Нужны все.
+  - `aliases` (`string`): Идентификаторы или имена через запятую.
+  - `maxWorkers` (`number`): Параллельность, по умолчанию 8.
+- **Возвращает**: Строку на каждый хост: успех, код выхода, длительность, stdout, stderr и ошибка.
+- **Ограничение**: Сбой соединения одного хоста не останавливает остальные.
+
 ---
 
 ## 🌐 Справочник HTTP API
@@ -240,6 +280,13 @@ dsh-remote-workspace:
 | `POST` | `/dsh-remote-workspace/test` | Проверка связи и замер пинга. | JSON профиля |
 | `POST` | `/dsh-remote-workspace/browse` | Получение списка файлов для браузера папок. | `{ profile: object, path: string }` |
 | `POST` | `/dsh-remote-workspace/sync` | Запуск синхронизации. | `{ direction: "pull" \| "push", dryRun?: boolean, force?: boolean }` |
+| `POST` | `/dsh-remote-workspace/profiles/import-ssh-config` | Импорт `~/.ssh/config` или переданного текста. | `{ content?: string }` |
+| `POST` | `/dsh-remote-workspace/profiles/test-group` | Проверка сохранённых профилей по списку id. | `{ ids: string[] }` |
+| `POST` | `/dsh-remote-workspace/cluster` | Команда на отфильтрованных сохранённых профилях. | `{ command, environment?, tags?, aliases?, maxWorkers? }` |
+| `GET` | `/dsh-remote-workspace/file/download` | Поток удалённого файла. Query: `profileId`, `filePath`. | — |
+| `POST` | `/dsh-remote-workspace/file/upload` | Загрузка тела файла. Query: `profileId`, `filePath`. | байты файла |
+| `POST` | `/dsh-remote-workspace/terminal/font` | Сохранение шрифта терминала. | `{ fontFamily: string }` |
+| `POST` | `/dsh-remote-workspace/auth/keyboard` | Ответ keyboard-interactive. | `{ id, answers }` |
 
 ---
 

package/README.zh.md

@@ -99,6 +99,11 @@ graph LR
   - **密码认证**：原生支持常规账号密码安全登录。
 - **链路诊断探测**：内置 `testConnection` 方法，精确测定毫秒级网络延迟，并自动探测远程主机内核与架构（`uname -srm`）。
 - **心跳保活机制**：主动发送 Keep-Alive 探测包，有效防止各类网络防火墙超时断开空闲连接。
+- **代理命令与跳板**：`proxyCommand` 运行 OpenSSH 风格命令，令牌为 `%h`、`%p`、`%r`、`%n` 和 `%%`。`jumpHosts` 是按顺序排列的配置编号；`jumpHostId` 可以用逗号分隔作为后备。第一跳来自连接池，后续跳板使用独立连接，并在目标会话结束时关闭。
+- **代理与一次性验证码**：`agentPath` 指定 SSH 代理套接字。留空则使用 `SSH_AUTH_SOCK`；在 Windows 上可填写 `pageant`。需要键盘交互时，验证码显示在设置卡片上，60 秒后失效。
+- **空闲连接**：没有隧道、也没有正在执行的命令时，池中的连接在 30 分钟后关闭。下一次命令会重新连接。
+- **输出前重连**：如果连接在命令产生任何输出之前断开，同一命令最多再试 3 次。命令超时、已经开始的输出，以及 `idempotent: false` 不会重试。
+- **独立终端**：终端不共用连接池。关闭终端只关闭这一条 SSH 会话。
 
 ### 2. `RemoteFsService` — 原子高可用 SFTP 文件系统
 - **原子安全写入**：文件首先上传至独立的临时文件（`.tmp.<timestamp>.<hash>`)，上传完成校验后通过原子重命名完成替换，彻底避免因网络异常产生残缺文件。
@@ -122,13 +127,22 @@ graph LR
 - `remote_fs`：执行远程文件的读、写、状态查询、目录列表、创建与删除。
 - `remote_sync`：在本地镜像与远程目录间发起具备冲突感知的同步操作。
 - `remote_tunnel`：开启、关闭或枚举 SSH 端口转发隧道。
+- `remote_hosts`：返回不含密码、私钥和代理命令的主机 Markdown 表。`query` 必填，空字符串列出全部主机。
+- `remote_cluster`：在符合环境、标签和别名的主机上运行同一条命令。`maxWorkers` 默认 8。
 
 ### 6. `client.js` — 原生 DSH 设置面板
 - 深度适配 `settings.plugin.item` 插槽（Key: `dsh-remote-workspace`）。
 - **分段式认证切换器**：优雅切换私钥认证与密码认证。
 - **远程目录浏览器弹窗**：可视化浏览远程服务器目录树，支持面包屑导航与一键选取。
-- **实时连接状态徽章**：可视化展示连通性、网络延迟以及远程操作系统信息。
-- **快捷动作触发**：一键发起定向文件同步并监控隧道运行状态。
+- **实时连接状态徽章**：可视化展示连通性、网络延迟以及远程操作系统信息。页眉徽章读取 `/dsh-remote-workspace/state`，分别表示正在检查、没有活动主机、主机已就绪或状态不可用，不再固定显示“就绪”。
+- **快捷动作触发**：一键发起定向文件同步并监控隧道运行状态。保存、删除、设为活动、浏览目录或关闭隧道失败时，卡片上的警告会显示服务器返回的错误。连接测试提交的是配置本身，其中包含 `host`。
+- **插件列表名称**：英文为 `Remote Workspace`，中文为 `远程开发工作区`，取自随卡片加载的词典。
+- **更新版本**：该行显示状态接口返回的已安装版本。结果返回前显示“版本未知”。
+- **主机分组**：配置可以填写 `environment`、`tags`、`location` 和 `description`。卡片可按平铺、环境或标签显示，并一次测试整组。
+- **文件传输**：文件页可以上传和下载远程文件，按已传输字节显示进度，并可取消。超过 512MB 的文件会被拒绝。
+- **终端字体**：`terminalFontFamily` 是终端的 CSS 字体族。留空则使用默认等宽字体。
+- **隐藏页面**：浏览器标签隐藏时暂停状态轮询，回到页面后立即刷新。
+- **侧栏工作区**：左侧导航的“远程”按钮在中央区域打开主机、终端、文件、容器、隧道和集群。返回聊天只是隐藏该区域，终端内容保留。
 
 ---
 
@@ -187,6 +201,15 @@ dsh-remote-workspace:
 | `profile.password` | `string` | `""` | 密码认证模式下的登录密码。 |
 | `profile.remoteWorkspace` | `string` | `""` | 远程服务器上的项目工作区根目录。 |
 | `profile.localMirrorPath` | `string` | `""` | 对应远程项目的本地镜像工作目录。 |
+| `profile.agentPath` | `string` | `""` | SSH 代理套接字。留空使用 `SSH_AUTH_SOCK`。 |
+| `profile.proxyCommand` | `string` | `""` | OpenSSH ProxyCommand。令牌：`%h` `%p` `%r` `%n`。 |
+| `profile.jumpHosts` | `string[]` | `[]` | 跳板配置编号，第一台为入口。 |
+| `profile.jumpHostId` | `string` | `""` | `jumpHosts` 为空时的逗号分隔跳板编号。 |
+| `profile.environment` | `string` | `""` | 分组和集群过滤，忽略大小写。 |
+| `profile.tags` | `string[]` | `[]` | 标签。集群过滤要求每个标签都匹配。 |
+| `profile.location` | `string` | `""` | 位置说明。 |
+| `profile.description` | `string` | `""` | 备注。 |
+| `terminalFontFamily` | `string` | `""` | 终端 CSS 字体族。留空使用默认等宽字体。 |
 
 ---
 
@@ -225,6 +248,23 @@ dsh-remote-workspace:
   - `tunnelId` (`string`，停止时必填)：需要关闭的隧道 ID。
 - **返回数据**：`{ tunnelId, localPort, remotePort }` 或隧道清单 `{ tunnels: [...] }`。
 
+### `remote_hosts`
+向模型返回不含秘密的主机表。
+- **输入参数**：
+  - `query` (`string`，必填)：按名称、主机或编号匹配。空字符串列出全部。
+- **返回数据**：Markdown 表。密码、私钥、密钥路径、口令、代理套接字和代理命令不会出现。
+
+### `remote_cluster`
+在筛选后的主机上运行同一条命令。
+- **输入参数**：
+  - `command` (`string`，必填)：Shell 命令。
+  - `environment` (`string`，可选)：精确的环境名。
+  - `tags` (`string`，可选)：逗号分隔的标签，必须全部匹配。
+  - `aliases` (`string`，可选)：逗号分隔的配置编号或名称。
+  - `maxWorkers` (`number`，可选)：并行数，默认 8。
+- **返回数据**：每台主机一行，包含成功与否、退出码、耗时、标准输出、标准错误和错误。
+- **限制**：一台主机连接失败只影响自己的结果行。
+
 ---
 
 ## 🌐 HTTP API 接口列表
@@ -240,6 +280,13 @@ dsh-remote-workspace:
 | `POST` | `/dsh-remote-workspace/test` | 测试 SSH 连通性、延迟与系统信息。 | 主机配置 JSON |
 | `POST` | `/dsh-remote-workspace/browse` | 获取指定远程路径下的子目录列表（供选择器使用）。 | `{ profile: object, path: string }` |
 | `POST` | `/dsh-remote-workspace/sync` | 发起手动目录镜像同步。 | `{ direction: "pull" \| "push", dryRun?: boolean, force?: boolean }` |
+| `POST` | `/dsh-remote-workspace/profiles/import-ssh-config` | 导入 `~/.ssh/config` 或提交的配置文本。 | `{ content?: string }` |
+| `POST` | `/dsh-remote-workspace/profiles/test-group` | 测试提交的已保存配置编号。 | `{ ids: string[] }` |
+| `POST` | `/dsh-remote-workspace/cluster` | 在筛选后的已保存主机上运行命令。 | `{ command, environment?, tags?, aliases?, maxWorkers? }` |
+| `GET` | `/dsh-remote-workspace/file/download` | 流式下载远程文件。查询参数：`profileId`、`filePath`。 | — |
+| `POST` | `/dsh-remote-workspace/file/upload` | 上传原始文件。查询参数：`profileId`、`filePath`。 | 文件字节 |
+| `POST` | `/dsh-remote-workspace/terminal/font` | 保存终端字体。 | `{ fontFamily: string }` |
+| `POST` | `/dsh-remote-workspace/auth/keyboard` | 提交键盘交互验证码。 | `{ id, answers }` |
 
 ---
 

package/lib/agent-endpoint.js

@@ -0,0 +1,16 @@
+/**
+ * ssh2 agent endpoint for a profile. Pageant is the Windows name ssh2 understands.
+ * A private key is never read for this auth type.
+ * @param {any} profile
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {string} [platform]
+ */
+export function resolveAgentEndpoint(profile, env = process.env, platform = process.platform) {
+  if (profile?.authType !== 'agent') return undefined;
+  const raw = String(profile.agentPath || '').trim();
+  if (raw.toLowerCase() === 'pageant') return 'pageant';
+  if (raw) return raw;
+  if (env && env.SSH_AUTH_SOCK) return env.SSH_AUTH_SOCK;
+  if (platform === 'win32') return 'pageant';
+  return undefined;
+}