dsh-winrm 0.3.1 → 0.4.0

package/README.en.md

@@ -0,0 +1,130 @@
+# dsh-winrm — remote Windows administration for DSH (WinRM / PowerShell Remoting)
+
+[中文](README.md) | English
+
+A DSH plugin modeled on [dsh-ssh](https://github.com/zhu1090093659/dsh-web-ui/tree/main/packages/dsh-ssh): it administers Windows servers over the native **WinRM / PowerShell Remoting** protocol, so **the target machine needs no OpenSSH**.
+
+> **Provenance**: this project is a fork of [andyfan1094/dsh-winrm](https://github.com/andyfan1094/dsh-winrm) (Apache-2.0) that replaces the backend's Python + pywinrm implementation with a native Node.js client ([winrm-client](https://github.com/shide1989/winrm-client)), so **Python is no longer required locally**. The GUI, the agent tools and the feature scope follow the upstream design.
+
+## Features
+
+| Surface | What it does |
+| --- | --- |
+| "Windows" sidebar entry | A main panel with five tabs: **Hosts** / **Console** / **Services** / **Processes** / **Transfer** |
+| Agent tools | `winrm_list` `winrm_exec` `winrm_service` `winrm_process` `winrm_read` `winrm_write` `winrm_edit` `winrm_upload` `winrm_download` `winrm_cluster` |
+| PowerShell console | A WebSocket command session (each command runs through the native Node WinRM client and streams its output back) |
+| Service management | List / start / stop / restart / change start type (automatic, manual, disabled) |
+| Process management | List (CPU, memory, path) / kill by PID |
+| Remote text files | Read (paged by line, encoding aware, numbered envelope) / write (whole-file overwrite, optional UTF-8 / UTF-8 BOM / UTF-16LE) / edit (exact string replacement that keeps the original encoding; a non-unique match is refused by default) |
+| Transcript cards | `winrm_read` / `winrm_write` / `winrm_edit` render as a **file content card and diff cards** in the transcript (reusing the harness's own `ReadBlock` / `DiffBlock` primitives) instead of the raw model-facing envelope |
+| File transfer | Streamed over WinRM (upload through one shell and one stream, download through parallel byte ranges, **no SMB dependency**, any path works); uploads create parent directories |
+| Cluster | Run one command across many hosts concurrently (filtered by aliases / environment / tags) |
+
+## Authentication and transport
+
+- Uses a native Node.js WinRM client ([winrm-client](https://github.com/shide1989/winrm-client)) and picks the authentication automatically per transport: Basic first over HTTPS, NTLM first over HTTP, each falling back to the other (HTTP Basic is for trusted intranets only — use HTTPS on the public internet)
+- Local accounts are written as `Administrator`; domain accounts as `DOMAIN\user` or `user@domain`
+- No Python locally — WinRM runs on a pure Node dependency (winrm-client) installed with the plugin
+- Transport: HTTP (5985) or HTTPS (5986); HTTPS offers an "accept self-signed certificate" checkbox
+- Chinese output is never mangled: every command goes through a **UTF-8 base64 envelope** (`Out-String -Stream` wrapping plus three labelled envelope lines), which sidesteps the WinRM transport code page
+- PowerShell's CLIXML host records are stripped from `stderr` automatically; real process-level stderr (for example `[Console]::Error`) is preserved verbatim
+- **Scripts travel over WinRS stdin, not the command line**: WinRS hands the command line to `cmd.exe`, which caps it at roughly 8191 characters, while `-EncodedCommand` inflates a script by 2.67x — long scripts used to fail outright with `The command line is too long.`. The command line is now a **constant** and the script is chunked to stdin behind a UTF-8 byte-length prefix; a 200 KB script is verified working
+
+## Preparing the target machine (one time)
+
+On the Windows machine you want to manage, run this **as administrator**:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\enable-winrm.ps1
+```
+
+The script enables the WinRM service and the 5985 listener, allows Basic/Negotiate authentication, permits unencrypted HTTP (intranet), raises the WinRS memory limit to 512 MB, opens the firewall and prints the machine's IP address.
+
+> ⚠️ **Security**: HTTP + Basic is cleartext and belongs on trusted intranets only. On the public internet, configure HTTPS with a self-signed certificate and tick "accept self-signed certificate" in the plugin. Passwords are stored in cleartext in `~/.dsh/dsh-winrm.json` locally (mode 0600, readable only by the current user) and are never echoed back by the plugin UI.
+
+## Screenshot
+
+![dsh-winrm: the Hosts tab after opening the "Windows" sidebar entry](docs/screenshots/winrm-panel.png)
+
+## Install
+
+> Requires DeepSeek Harness **0.1.7-alpha.2 or newer** (including `0.1.7-rc.1`, `0.2.0-rc.*` and `0.2.x`). The plugin declares `peerDependencies` as `^0.1.7-alpha.2 || ^0.2.0-rc.1`, which DSH checks at startup: every 0.1.7 and 0.2.x version loads, and `0.3.0` onward is refused (use `dsh plugin allow-version` to admit a specific version if you accept the risk).
+
+Download the latest `dsh-winrm-*.tgz` from [Releases](https://github.com/MoRanYue/dsh-winrm/releases) and add it to your profile:
+
+```powershell
+dsh plugin --profile web add D:\downloads\dsh-winrm-0.3.1.tgz
+```
+
+You can also install straight from npm:
+
+```powershell
+dsh plugin --profile web add dsh-winrm
+```
+
+For local development, link the checkout instead:
+
+```bash
+dsh plugin --profile web add link:D:\projects\dsh-winrm
+```
+
+**Restart dsh web** after installing (quit and start `dsh web` again) so the plugin takes effect. A "Windows" entry appears in the sidebar, and `winrm_list` and friends become available in the conversation.
+
+### Building from source
+
+```bash
+cd D:\projects\dsh-winrm
+pnpm install
+npm run build     # tsc declarations + tsdown host/client bundles + postbuild wrapping
+```
+
+## Usage examples (agent tools)
+
+```
+winrm_list                                        # list configured hosts
+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_read   alias=web1 remotePath=C:\logs\app.log offset=1 limit=200
+winrm_write  alias=web1 remotePath=C:\temp\run.ps1 content="$env:TEMP" encoding=utf8bom
+winrm_edit   alias=web1 remotePath=C:\temp\app.config oldString="port=8080" newString="port=9090"
+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
+```
+
+## Architecture
+
+```
+src/
+  index.ts            Cordis plugin entry (webServer/tools/systemPrompt mounts + settings panel + announcement)
+  engine.ts           WinRmEngine facade: exec / services / processes / readFile / writeFile / editFile / ls / upload / download / console / cluster / test
+  store.ts            ~/.dsh/dsh-winrm.json host store (atomic write, 0600)
+  protocol.ts         Host <-> browser wire types
+  diff.ts             Bounded hunk derivation for the transcript cards (no diff package)
+  powershell.ts       PS fragment builders + stdin envelope (outer/child wrapping / services / processes / directory / streamed send-receive scripts)
+  routes.ts           /api/dsh-winrm route family + console WebSocket (loopback fence)
+  tools.ts            The 10 winrm_* agent tools
+  engine/client.ts    winrm-client transport: in-process authentication (NTLM/Basic), UTF-8 envelope, streamed upload/download + chunked fallback
+  engine/wsman.ts     Hand-written WSMan Send/Receive envelopes (raw bytes over stdin, no double base64; 512000 envelope cap)
+  engine/console.ts   Streaming PowerShell console session
+  client/             Browser half: sidebar entry + main panel (5 tabs)
+  client/tool/        Transcript cards: three tool.call.toolview frames rendered with DSH's own ReadBlock / DiffBlock
+scripts/
+  enable-winrm.ps1    One-shot WinRM enablement on the target machine
+  postbuild.mjs       __ModuleLoader__ wrapping for the client artifact
+```
+
+Transport relies on the native Node.js [winrm-client](https://github.com/shide1989/winrm-client) (NTLM/Basic, in-process authentication); the password is used only inside the host process and never appears on any child process command line.
+
+## Known limitations
+
+- The console is a command session: it does not preserve PowerShell variables or the current directory, and every command runs independently
+- Uploads go over **one stdin stream**: a single shell, a single command, one `Send` per 256 KB, with per-chunk gzip for compressible content (a 1.7 MB JSON fixture travels as 91 KB on the wire). The old 48 KB chunked path is kept as a fallback, used only when the streaming channel is unavailable
+- Downloads go over **parallel byte ranges**: up to four workers by default, each with its own shell reading an absolute byte range of the same file, compressed on the remote side and written locally at the matching offset (measured: 2 MiB in about 10-12 s, 16 MiB in about 21-23 s, 16 MiB of compressible content in about 6 s; the old 48 KB chunked path needed 129 s for 2 MiB and remains as a fallback). A single server `Receive` returns at most 128 KB regardless of the envelope size, so downloads are round-trip bound rather than bandwidth bound
+- `channel=auto` (the default) probes port 445 first: `net use` has no short timeout of its own and takes about 60 s to fail when SMB is unavailable, and that wait used to happen before every upload. It is now decided within 3 s and the transfer goes straight over WinRM
+- A failed download leaves no residue: bytes already written are discarded and the target file is removed. If the failure happens before any byte arrives (missing path, target is a directory, host unreachable), an existing local file is left untouched — the target file is only created on the first write
+- A single command times out after 60 s by default; pass `timeoutMs` to change it
+- The target machine must already have WinRM enabled (see above); cleartext HTTP Basic must not be used on the public internet
+- Closing and reopening the panel returns to the Hosts tab: the panel occupies the `main` slot, so it unmounts when you switch back to the conversation and the active tab is not preserved across toggles

package/README.md

@@ -1,6 +1,6 @@
 # dsh-winrm — Windows 远程管理插件（WinRM / PowerShell Remoting）
 
-[中文文档](README.zh.md) | English
+中文 | [English](README.en.md)
 
 仿照 [dsh-ssh](https://github.com/zhu1090093659/dsh-web-ui/tree/main/packages/dsh-ssh) 开发的 DSH 插件：用 Windows 原生的 **WinRM / PowerShell Remoting** 协议远程管理 Windows 服务器，**目标机不需要装 OpenSSH**。
 
@@ -11,10 +11,12 @@
 | 面 | 说明 |
 | --- | --- |
 | GUI 侧边栏「Windows」入口 | 居中面板：**主机** / **控制台** / **服务** / **进程** / **传输** 五个页签 |
-| Agent 工具 | `winrm_list` `winrm_exec` `winrm_service` `winrm_process` `winrm_upload` `winrm_download` `winrm_cluster` |
+| Agent 工具 | `winrm_list` `winrm_exec` `winrm_service` `winrm_process` `winrm_read` `winrm_write` `winrm_edit` `winrm_upload` `winrm_download` `winrm_cluster` |
 | PowerShell 控制台 | WebSocket 命令会话（每条命令通过原生 Node WinRM 客户端执行，输出实时返回） |
 | 服务管理 | 列出 / 启动 / 停止 / 重启 / 改启动类型（自动/手动/禁用） |
 | 进程管理 | 列出（CPU/内存/路径）/ 按 PID 结束 |
+| 远程文本文件 | 读（按行分页、编码感知、行号信封）/ 写（整文件覆盖，可选 UTF-8 / UTF-8 BOM / UTF-16LE）/ 编辑（精确串替换，保持原编码，非唯一匹配默认拒绝） |
+| 转录卡片 | `winrm_read` / `winrm_write` / `winrm_edit` 在会话里渲染为**文件内容卡片与 diff 卡片**（直接复用 harness 自带的 `ReadBlock` / `DiffBlock` 原语），不再是模型可见的原始信封文本 |
 | 文件传输 | WinRM 流式传输（上传单 shell 单流 / 下载并行区间，**不依赖 SMB**，任意路径可传）；上传自动建目录 |
 | 集群 | 一条命令并发跑多台主机（按 aliases / environment / tags 过滤） |
 
@@ -40,6 +42,10 @@ powershell -ExecutionPolicy Bypass -File .\scripts\enable-winrm.ps1
 
 > ⚠️ **安全**：HTTP + Basic 是明文，仅限受信内网；公网请配置 HTTPS + 自签名证书，并在插件里勾选「接受自签名证书」。密码明文存于本机 `~/.dsh/dsh-winrm.json`（0600 权限，仅当前用户可读），插件界面永不回显。
 
+## 截图
+
+![dsh-winrm：侧边栏「Windows」入口打开后的主机页签](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` 逐版本放行）。
@@ -47,7 +53,7 @@ powershell -ExecutionPolicy Bypass -File .\scripts\enable-winrm.ps1
 从 [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
+dsh plugin --profile web add D:\downloads\dsh-winrm-0.3.1.tgz
 ```
 
 也可以直接从 npm 安装：
@@ -80,6 +86,9 @@ 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_read   alias=web1 remotePath=C:\logs\app.log offset=1 limit=200
+winrm_write  alias=web1 remotePath=C:\temp\run.ps1 content="$env:TEMP" encoding=utf8bom
+winrm_edit   alias=web1 remotePath=C:\temp\app.config oldString="port=8080" newString="port=9090"
 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
@@ -90,16 +99,18 @@ 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
+  engine.ts           WinRmEngine 门面：exec / services / processes / readFile / writeFile / editFile / ls / upload / download / console / cluster / test
   store.ts            ~/.dsh/dsh-winrm.json 主机存储（原子写，0600）
   protocol.ts         宿主↔浏览器 wire 类型
+  diff.ts             转录卡片用的有界 hunk 推导（不依赖 diff 包）
   powershell.ts       PS 片段构造器 + stdin 信封（outer/child 包装 / 服务 / 进程 / 目录 / 流式收发脚本）
   routes.ts           /api/dsh-winrm 路由族 + 控制台 WebSocket（loopback 围栏）
-  tools.ts            7 个 winrm_* agent 工具
+  tools.ts            10 个 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 页签）
+  client/tool/        转录卡片：tool.call.toolview 三个帧 + DSH 原生 ReadBlock / DiffBlock 渲染
 scripts/
   enable-winrm.ps1    目标机一键启用 WinRM
   postbuild.mjs       客户端产物 __ModuleLoader__ 包装