dsh-winrm 0.3.1 → 0.4.1

package/src/tools.ts

@@ -6,7 +6,8 @@
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
-import type { WinRmEngine } from './engine.ts'
+import { boundedHunkDiffs, type RemoteFileDiff } from './diff.ts'
+import { READ_DEFAULT_LIMIT, READ_MAX_LIMIT, type WinRmEngine } from './engine.ts'
 import type { ClusterResult, ExecResult, WinHostSummary } from './protocol.ts'
 
 /** One text content block (the only render shape these tools emit). */
@@ -272,7 +273,7 @@ export function winrmUploadTool(engine: WinRmEngine) {
       alias: { type: 'string', required: true, description: 'Host alias from winrm_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, e.g. C:\\temp\\file.txt (parent dirs are created).' },
-      channel: { type: 'string', enum: ['auto', 'smb', 'winrm'], description: 'Transfer channel: smb (admin share), winrm (streamed over the WinRS stdin channel), or auto (default, SMB first with WinRM fallback).' },
+      channel: { type: 'string', enum: ['auto', 'smb', 'winrm'], description: 'Transfer channel: auto (default) uses the SMB admin share when TCP 445 answers and otherwise WinRM; smb fails outright when 445 is closed; winrm always streams over the WinRS stdin channel.' },
     },
     output: {
       schema: {
@@ -305,13 +306,13 @@ export function winrmUploadTool(engine: WinRmEngine) {
 export function winrmDownloadTool(engine: WinRmEngine) {
   return defineTool({
     name: 'winrm_download',
-    description: 'Download a remote FILE from a configured Windows host to a local path on this machine. The bytes come over the SMB admin share when it is reachable, otherwise they are streamed over WinRM as parallel byte ranges (the 48 KiB base64 chunk path is kept only as a fallback). Directory download is not supported — download files individually. ' +
+    description: 'Download a remote FILE from a configured Windows host to a local path on this machine. The bytes come over the SMB admin share when it is reachable, otherwise they are streamed over WinRM as parallel byte ranges (the 48 KiB base64 chunk path is kept only as a fallback). Large files are fine: the WinRM path runs for as long as bytes keep arriving and only fails once a range stalls. Directory download is not supported — download files individually. ' +
       'Triggers: download file from Windows server, fetch remote log/artifact.',
     parameters: {
       alias: { type: 'string', required: true, description: 'Host alias from winrm_list.' },
       remotePath: { type: 'string', required: true, description: 'Remote file path, e.g. C:\\temp\\file.txt.' },
       localPath: { type: 'string', required: true, description: 'Absolute destination path on this machine.' },
-      channel: { type: 'string', enum: ['auto', 'smb', 'winrm'], description: 'Transfer channel: smb (admin share), winrm (streamed over parallel WinRS ranges), or auto (default, SMB first with WinRM fallback).' },
+      channel: { type: 'string', enum: ['auto', 'smb', 'winrm'], description: 'Transfer channel: auto (default) uses the SMB admin share when TCP 445 answers and otherwise WinRM; smb fails outright when 445 is closed; winrm always streams over parallel WinRS byte ranges.' },
     },
     output: {
       schema: {
@@ -386,3 +387,301 @@ export function winrmClusterTool(engine: WinRmEngine) {
     },
   })
 }
+
+/** Render a read window in the numbered envelope the local read tool uses. */
+function renderWindow(window: {
+  path?: string
+  offset?: number
+  lines?: Array<{ number: number; text: string }>
+  totalLines?: number
+  encoding?: string
+  truncatedByBytes?: boolean
+}): string {
+  const lines = window.lines ?? []
+  const offset = window.offset ?? 1
+  const total = window.totalLines ?? 0
+  const last = offset + lines.length - 1
+  const body = lines.map(line => `${line.number}: ${line.text}`).join('\n')
+  // Only a non-UTF-8 file needs saying: that is when a later write would
+  // otherwise replace the encoding without the caller noticing.
+  const encoding = window.encoding !== undefined && window.encoding !== 'utf8'
+    ? `, encoding ${window.encoding}`
+    : ''
+  let footer: string
+  if (lines.length === 0) {
+    footer = total === 0
+      ? `(End of file - total 0 lines${encoding})`
+      : `(No lines at offset ${offset}; the file has ${total} lines${encoding}.)`
+  } else if (window.truncatedByBytes === true) {
+    footer = `(Showing lines ${offset}-${last} of ${total}${encoding}. The window stopped at the byte budget — continue with offset=${last + 1}.)`
+  } else if (last < total) {
+    footer = `(Showing lines ${offset}-${last} of ${total}${encoding}. Continue with offset=${last + 1}.)`
+  } else {
+    footer = `(End of file - total ${total} lines${encoding})`
+  }
+  const content = body === '' ? footer : `${body}\n\n${footer}`
+  return [`<path>${window.path ?? ''}</path>`, '<type>file</type>', '<content>', content, '</content>'].join('\n')
+}
+
+/** The remote read tool: a line-numbered window of a text file on the target. */
+export function winrmReadTool(engine: WinRmEngine) {
+  return defineTool({
+    name: 'winrm_read',
+    description: 'Read a text file ON A REMOTE Windows host and return its content line-numbered. The path is on the Windows host, not this machine — use `read` for local files. Decodes UTF-8 (with or without BOM) and UTF-16 with a BOM, and refuses binary files instead of returning mojibake. Page through large files with offset and limit. ' +
+      'Triggers: read file on Windows server, inspect remote config/log/script.',
+    parameters: {
+      alias: { type: 'string', required: true, description: 'Host alias from winrm_list.' },
+      remotePath: { type: 'string', required: true, description: 'Path on the remote host, e.g. C:\\temp\\app.log.' },
+      offset: { type: 'integer', description: '1-based first line to return. Defaults to 1.' },
+      limit: { type: 'integer', description: `Maximum lines to return (default ${READ_DEFAULT_LIMIT}, max ${READ_MAX_LIMIT}).` },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          path: { type: 'string' },
+          offset: { type: 'integer' },
+          lines: {
+            type: 'array',
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                number: { type: 'integer', required: true },
+                text: { type: 'string', required: true },
+              },
+            },
+          },
+          totalLines: { type: 'integer' },
+          encoding: { type: 'string' },
+          truncatedByBytes: { type: 'boolean' },
+          truncatedLines: { type: 'integer' },
+          error: { type: 'string' },
+        },
+      },
+      render: (_args, value: { ok: boolean; path?: string; offset?: number; lines?: Array<{ number: number; text: string }>; totalLines?: number; encoding?: string; truncatedByBytes?: boolean; error?: string }) => text(value.ok
+        ? renderWindow(value)
+        : `read failed: ${value.error ?? 'unknown error'}`),
+      // The GUI draws a read card from this; the model-facing text above stays
+      // the fallback for a client without the card.
+      presentationMeta: (args, value: { ok: boolean; path?: string; offset?: number; lines?: Array<{ number: number; text: string }>; totalLines?: number; encoding?: string; truncatedByBytes?: boolean; truncatedLines?: number; error?: string }) => (value.ok
+        ? {
+            card: 'winrm-read',
+            path: value.path ?? args.remotePath,
+            offset: value.offset ?? 1,
+            lines: value.lines ?? [],
+            totalLines: value.totalLines ?? 0,
+            encoding: value.encoding ?? 'utf8',
+            truncatedByBytes: value.truncatedByBytes === true,
+            truncatedLines: value.truncatedLines ?? 0,
+            // Every arm carries the same keys: the metadata is typed against a
+            // JSON index signature, where an arm-specific optional key would
+            // widen to `undefined` and stop satisfying it.
+            error: '',
+          }
+        : {
+            card: 'winrm-read',
+            path: args.remotePath,
+            offset: 0,
+            lines: [],
+            totalLines: 0,
+            encoding: '',
+            truncatedByBytes: false,
+            truncatedLines: 0,
+            error: value.error ?? 'unknown error',
+          }),
+    },
+    async execute(args) {
+      const offset = Math.max(1, Math.trunc(args.offset ?? 1))
+      const limit = Math.min(READ_MAX_LIMIT, Math.max(1, Math.trunc(args.limit ?? READ_DEFAULT_LIMIT)))
+      try {
+        const window = await engine.readFile(args.alias, args.remotePath, offset, limit)
+        return { ok: true, ...window }
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) }
+      }
+    },
+  })
+}
+
+/** The remote write tool: replace a whole text file on the target. */
+export function winrmWriteTool(engine: WinRmEngine) {
+  return defineTool({
+    name: 'winrm_write',
+    description: 'Write a text file ON A REMOTE Windows host, creating parent directories and overwriting any existing file. The path is on the Windows host, not this machine — use `write` for local files, and prefer winrm_edit when only part of an existing file changes. Line endings are sent verbatim, so include \\r\\n for a Windows-native file. The encoding is whatever `encoding` asks for — rewriting an existing utf16le or utf8bom file without setting it converts the file to plain UTF-8; `winrm_read` names a non-UTF-8 file in its footer when you need to match one. ' +
+      'Triggers: write file on Windows server, create remote script/config, overwrite remote file.',
+    parameters: {
+      alias: { type: 'string', required: true, description: 'Host alias from winrm_list.' },
+      remotePath: { type: 'string', required: true, description: 'Destination path on the remote host, e.g. C:\\temp\\script.ps1 (parent dirs are created).' },
+      content: { type: 'string', required: true, description: 'Full file content.' },
+      encoding: { type: 'string', enum: ['utf8', 'utf8bom', 'utf16le'], description: 'Byte-order mark to emit: utf8 (default, no BOM), utf8bom, or utf16le (PowerShell 5.1 reads a BOM-less script as ANSI, so non-ASCII script text needs a BOM). Does not preserve the existing file\'s encoding — pass it explicitly when overwriting a UTF-16 or BOM-carrying file.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          path: { type: 'string' },
+          operation: { type: 'string', enum: ['create', 'update'] },
+          bytes: { type: 'integer' },
+          encoding: { type: 'string', enum: ['utf8', 'utf8bom', 'utf16le'] },
+          diffs: {
+            type: 'array',
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                path: { type: 'string', required: true },
+                oldText: { type: 'string', required: true },
+                newText: { type: 'string', required: true },
+              },
+            },
+          },
+          beyondBasis: { type: 'boolean' },
+          error: { type: 'string' },
+        },
+      },
+      render: (_args, value: { ok: boolean; path?: string; operation?: string; bytes?: number; error?: string }) => text(value.ok
+        ? [`<path>${value.path ?? ''}</path>`, '<type>file</type>', '<content>', `${value.operation === 'update' ? 'Updated' : 'Created'} file (${value.bytes ?? 0} bytes)`, '</content>'].join('\n')
+        : `write failed: ${value.error ?? 'unknown error'}`),
+      presentationMeta: (args, value: { ok: boolean; path?: string; operation?: 'create' | 'update'; bytes?: number; encoding?: string; diffs?: RemoteFileDiff[]; beyondBasis?: boolean; error?: string }) => (value.ok
+        ? {
+            card: 'winrm-write',
+            path: value.path ?? args.remotePath,
+            operation: value.operation ?? 'update',
+            bytes: value.bytes ?? 0,
+            encoding: value.encoding ?? 'utf8',
+            diffs: value.diffs ?? [],
+            beyondBasis: value.beyondBasis === true,
+            error: '',
+          }
+        : {
+            card: 'winrm-write',
+            path: args.remotePath,
+            operation: 'update' as const,
+            bytes: 0,
+            encoding: '',
+            diffs: [],
+            beyondBasis: false,
+            error: value.error ?? 'unknown error',
+          }),
+    },
+    async execute(args) {
+      try {
+        const outcome = await engine.writeFile(args.alias, args.remotePath, args.content, args.encoding ?? 'utf8')
+        // A create compares against nothing, so its whole content is one
+        // insertion hunk; an update whose prior text was past the basis cap
+        // reports the path without hunks rather than a misleading full rewrite.
+        const diffs = outcome.before !== null
+          ? boundedHunkDiffs(outcome.path, outcome.before, outcome.after)
+          : outcome.operation === 'create'
+            ? boundedHunkDiffs(outcome.path, '', outcome.after)
+            : []
+        return {
+          ok: true,
+          path: outcome.path,
+          operation: outcome.operation,
+          bytes: outcome.bytes,
+          encoding: outcome.encoding,
+          diffs,
+          beyondBasis: outcome.operation === 'update' && outcome.before === null,
+        }
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) }
+      }
+    },
+  })
+}
+
+/** The remote edit tool: replace an exact string inside a file on the target. */
+export function winrmEditTool(engine: WinRmEngine) {
+  return defineTool({
+    name: 'winrm_edit',
+    description: 'Replace an exact string in a text file ON A REMOTE Windows host, preserving the file encoding. The path is on the Windows host, not this machine — use `edit` for local files. `oldString` must match the file byte for byte, including indentation and line endings, and must be unique unless `replaceAll` is set; read the file with winrm_read first. ' +
+      'Triggers: edit file on Windows server, patch remote config, change remote script.',
+    parameters: {
+      alias: { type: 'string', required: true, description: 'Host alias from winrm_list.' },
+      remotePath: { type: 'string', required: true, description: 'Path on the remote host, e.g. C:\\temp\\app.config.' },
+      oldString: { type: 'string', required: true, description: 'Exact text to replace. Must not be empty.' },
+      newString: { type: 'string', required: true, description: 'Replacement text. Must differ from oldString.' },
+      replaceAll: { type: 'boolean', description: 'Replace every occurrence instead of requiring exactly one. Defaults to false.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          path: { type: 'string' },
+          encoding: { type: 'string' },
+          replacements: { type: 'integer' },
+          size: { type: 'integer' },
+          diffs: {
+            type: 'array',
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                path: { type: 'string', required: true },
+                oldText: { type: 'string', required: true },
+                newText: { type: 'string', required: true },
+              },
+            },
+          },
+          beyondBasis: { type: 'boolean' },
+          error: { type: 'string' },
+        },
+      },
+      render: (_args, value: { ok: boolean; path?: string; replacements?: number; size?: number; error?: string }) => text(value.ok
+        ? ((value.replacements ?? 0) > 1
+          ? `The file ${value.path ?? ''} has been updated. All ${value.replacements ?? 0} occurrences were successfully replaced.`
+          : `The file ${value.path ?? ''} has been updated successfully.`)
+        : `edit failed: ${value.error ?? 'unknown error'}`),
+      presentationMeta: (args, value: { ok: boolean; path?: string; replacements?: number; size?: number; encoding?: string; diffs?: RemoteFileDiff[]; beyondBasis?: boolean; error?: string }) => (value.ok
+        ? {
+            card: 'winrm-edit',
+            path: value.path ?? args.remotePath,
+            replacements: value.replacements ?? 0,
+            size: value.size ?? 0,
+            encoding: value.encoding ?? 'utf8',
+            diffs: value.diffs ?? [],
+            beyondBasis: value.beyondBasis === true,
+            error: '',
+          }
+        : {
+            card: 'winrm-edit',
+            path: args.remotePath,
+            replacements: 0,
+            size: 0,
+            encoding: '',
+            diffs: [],
+            beyondBasis: false,
+            error: value.error ?? 'unknown error',
+          }),
+    },
+    async execute(args) {
+      try {
+        const outcome = await engine.editFile(args.alias, args.remotePath, args.oldString, args.newString, args.replaceAll ?? false)
+        // The edit fragment returns both texts only when the file was inside the
+        // basis cap; otherwise the card reports the path and the count alone.
+        const diffs = outcome.before !== null && outcome.after !== null
+          ? boundedHunkDiffs(outcome.path, outcome.before, outcome.after)
+          : []
+        return {
+          ok: true,
+          path: outcome.path,
+          encoding: outcome.encoding,
+          replacements: outcome.replacements,
+          size: outcome.size,
+          diffs,
+          beyondBasis: outcome.before === null,
+        }
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) }
+      }
+    },
+  })
+}

package/README.zh.md

@@ -1,126 +0,0 @@
-# dsh-winrm — Windows 远程管理插件（WinRM / PowerShell Remoting）
-
-仿照 [dsh-ssh](https://github.com/zhu1090093659/dsh-web-ui/tree/main/packages/dsh-ssh) 开发的 DSH 插件：用 Windows 原生的 **WinRM / PowerShell Remoting** 协议远程管理 Windows 服务器，**目标机不需要装 OpenSSH**。
-
-> **来源**：本项目是 [andyfan1094/dsh-winrm](https://github.com/andyfan1094/dsh-winrm)（Apache-2.0）的分支，把后端的 WinRM 实现从 Python + pywinrm 换成原生 Node.js 客户端（[winrm-client](https://github.com/shide1989/winrm-client)），因此**本机不再需要 Python**。GUI、Agent 工具与功能范围沿用上游设计。
-
-## 功能
-
-| 面 | 说明 |
-| --- | --- |
-| GUI 侧边栏「Windows」入口 | 居中面板：**主机** / **控制台** / **服务** / **进程** / **传输** 五个页签 |
-| Agent 工具 | `winrm_list` `winrm_exec` `winrm_service` `winrm_process` `winrm_upload` `winrm_download` `winrm_cluster` |
-| PowerShell 控制台 | WebSocket 命令会话（每条命令通过原生 Node WinRM 客户端执行，输出实时返回） |
-| 服务管理 | 列出 / 启动 / 停止 / 重启 / 改启动类型（自动/手动/禁用） |
-| 进程管理 | 列出（CPU/内存/路径）/ 按 PID 结束 |
-| 文件传输 | WinRM 流式传输（上传单 shell 单流 / 下载并行区间，**不依赖 SMB**，任意路径可传）；上传自动建目录 |
-| 集群 | 一条命令并发跑多台主机（按 aliases / environment / tags 过滤） |
-
-## 认证与传输
-
-- 使用原生 Node.js WinRM 客户端（[winrm-client](https://github.com/shide1989/winrm-client)），按传输自动选择认证：HTTPS 优先 Basic、HTTP 优先 NTLM，两者均自动回退（HTTP Basic 仅限受信内网，公网必须使用 HTTPS）
-- 本地账户可写 `Administrator`；域账户可写 `DOMAIN\\user` 或 `user@domain`
-- 本机无需 Python —— WinRM 走纯 Node 依赖（winrm-client），随插件一起安装
-- 传输：HTTP(5985) 或 HTTPS(5986)；HTTPS 可勾选「接受自签名证书」
-- 中文输出不乱码：所有命令走 **UTF-8 base64 信封**（`Out-String -Stream` 包装 + 三条带标签的信封行），绕过 WinRM 传输的代码页问题
-- 命令结果的 `stderr` 已自动剥离 PowerShell 的 CLIXML 宿主机记录；真实的进程级 stderr（如 `[Console]::Error`）原样保留
-- **脚本走 WinRS stdin，不走命令行**：WinRS 把命令行交给 `cmd.exe`，上限约 8191 字符，而 `-EncodedCommand` 会把脚本膨胀 2.67 倍 —— 命令行长脚本此前会直接报 `The command line is too long.`。现在命令行是**常量**，脚本按 UTF-8 字节数分块送到 stdin，实测 200 KB 脚本正常
-
-## 目标机准备（一次性）
-
-在要管理的 Windows 机器上，**以管理员身份**运行：
-
-```powershell
-powershell -ExecutionPolicy Bypass -File .\scripts\enable-winrm.ps1
-```
-
-脚本自动：启用 WinRM 服务与 5985 监听 → 开放 Basic/Negotiate 认证 → 允许 HTTP 明文（内网）→ WinRS 内存上限 512MB → 放行防火墙 → 打印本机 IP。
-
-> ⚠️ **安全**：HTTP + Basic 是明文，仅限受信内网；公网请配置 HTTPS + 自签名证书，并在插件里勾选「接受自签名证书」。密码明文存于本机 `~/.dsh/dsh-winrm.json`（0600 权限，仅当前用户可读），插件界面永不回显。
-
-## 截图
-
-![dsh-winrm 截图](docs/screenshots/winrm-panel.png)
-
-
-## 安装
-
-> 需要 DeepSeek Harness **0.1.7-alpha.2 及以后**（含 `0.1.7-rc.1`、`0.2.0-rc.*`、`0.2.x`）。插件的 `peerDependencies` 声明为 `^0.1.7-alpha.2 || ^0.2.0-rc.1`，DSH 启动时会据此校验：0.1.7 与 0.2.x 各版本可加载，`0.3.0` 起会被拒绝（确需冒险可用 `dsh plugin allow-version` 逐版本放行）。
-
-从 [Releases](https://github.com/MoRanYue/dsh-winrm/releases) 下载最新的 `dsh-winrm-*.tgz`，加入 profile：
-
-```powershell
-dsh plugin --profile web add D:\downloads\dsh-winrm-0.3.0.tgz
-```
-
-也可以直接从 npm 安装：
-
-```powershell
-dsh plugin --profile web add dsh-winrm
-```
-
-本地开发可用 profile 链接安装：
-
-```bash
-dsh plugin --profile web add link:D:\项目\dsh-winrm
-```
-
-安装后 **重启 dsh web**（退出再启动 `dsh web`）使插件生效。侧边栏出现「Windows」入口；对话中可直接用 `winrm_list` 等工具。
-
-### 从源码构建
-
-```bash
-cd D:\项目\dsh-winrm
-pnpm install
-npm run build     # tsc 声明 + tsdown 宿主/客户端打包 + postbuild 包装
-```
-
-## 使用示例（agent 工具）
-
-```
-winrm_list                                        # 列出已配置主机
-winrm_exec  alias=web1 command="Get-Service | Select -First 5 | Format-Table"
-winrm_service alias=web1 name=W3SVC action=restart
-winrm_process alias=web1 action=list
-winrm_process alias=web1 id=1234 action=kill
-winrm_upload alias=web1 localPath=D:\a.zip remotePath=C:\temp\a.zip
-winrm_download alias=web1 remotePath=C:\logs\app.log localPath=D:\app.log
-winrm_cluster command="Get-Date" tags=prod
-```
-
-## 架构
-
-```
-src/
-  index.ts            Cordis 插件入口（webServer/tools/systemPrompt 挂载 + 设置面板 + 公告）
-  engine.ts           WinRmEngine 门面：exec / services / processes / ls / upload / download / console / cluster / test
-  store.ts            ~/.dsh/dsh-winrm.json 主机存储（原子写，0600）
-  protocol.ts         宿主↔浏览器 wire 类型
-  powershell.ts       PS 片段构造器 + stdin 信封（outer/child 包装 / 服务 / 进程 / 目录 / 流式收发脚本）
-  routes.ts           /api/dsh-winrm 路由族 + 控制台 WebSocket（loopback 围栏）
-  tools.ts            7 个 winrm_* agent 工具
-  engine/client.ts    winrm-client 传输层：进程内认证（NTLM/Basic）、UTF-8 信封、流式上传/下载 + 分块回退
-  engine/wsman.ts     手写 WSMan Send/Receive 信封（原始字节走 stdin，不做二次 base64；512000 信封上限）
-  engine/console.ts   流式 PowerShell 控制台会话
-  client/             浏览器半：侧边栏入口 + 居中面板（5 页签）
-scripts/
-  enable-winrm.ps1    目标机一键启用 WinRM
-  postbuild.mjs       客户端产物 __ModuleLoader__ 包装
-```
-
-传输依赖原生 Node.js 的 [winrm-client](https://github.com/shide1989/winrm-client)（NTLM/Basic，进程内认证）；密码只在宿主进程内使用，不出现在任何子进程命令行参数中。
-
-## 已知限制
-
-- 控制台是命令会话，不保持 PowerShell 变量和当前目录状态；每条命令独立执行
-- 上传走**单条 stdin 流**：一个 shell、一个命令，每 256KB 一个 `Send`，可压缩内容自动按块 gzip（实测 1.7MB JSON 线上仅 91KB）。旧的 48KB 分块路径保留为回退，仅在流式通道不可用时启用
-- 下载走**并行区间流**：默认最多 4 个 worker，各自一个 shell 读同一文件的绝对字节区间，远端 gzip 后回传，本地按 offset 落位（实测 2MiB 约 10-12 秒，16MiB 约 21-23 秒，可压缩的 16MiB 约 6 秒；旧的 48KB 分块路径 2MiB 需 129 秒，保留为回退）。服务端单次 `Receive` 最多回 128KB，与信封大小无关，所以下载是往返次数受限而非带宽受限
-- `channel=auto`（默认）先探测目标机 445 端口：`net use` 自身没有短超时，SMB 不可用时要等约 60 秒才失败，此前这段等待发生在每次上传之前。现在 3 秒内判定并直接走 WinRM
-- 下载失败不留残file：已写入的数据会被丢弃、目标文件被删除；若失败发生在任何字节到达之前（路径不存在、目标是目录、主机不可达），已存在的本地文件保持原样不动（目标文件在首次写入时才创建）
-- 单命令默认 60s 超时，可传 `timeoutMs`
-- 目标机需已启用 WinRM（见上）；HTTP 明文 Basic 不应用于公网
-- 面板关闭再打开会回到「主机」页签：面板是 `main` 插槽的占用者，切回对话时卸载，页签状态不跨开关保留
-
----
-
-English documentation: see [README.md](README.md).