Introduction

DeepSeek Harness (DSH) adopts a plugin-based architecture and aims to standardize agent behavior through system prompt injection. In the existing DSH plugin ecosystem, most plugins for WSL (Windows Subsystem for Linux) assume that the environment is bridged outward from WSL. If you run DSH on native Windows (without WSL), existing plugins cannot cover PowerShell’s native behaviors.

When using PowerShell directly on native Windows, agents often make mistakes in command chaining, encoding handling, and file system interactions. The dsh-windows-native plugin injects a system prompt that informs the agent about common gotchas in advance, reducing repeated trial and error during execution.

Plugin Overview

dsh-windows-native is a DSH plugin specifically for native Windows (non-WSL) environments. It does not provide external tools or binary files; instead, it is a system prompt injection that guides the agent on correct practices when handling PowerShell syntax, console encoding, and Windows file system behaviors.

The plugin is maintained by lucifergzsz414 and is licensed under the MIT License. It is based on real-world pitfalls the author encountered in native Windows environments and is currently in an early stage.

Core Features

The plugin informs the agent of the following key details in Windows environments through a system prompt:

1. Command Chaining and Execution Logic

Native versions such as PowerShell 5.1 do not natively support && or || command chaining.
* Use ; instead: If you need to execute commands sequentially, use a semicolon ;.
* Alternative syntax: You can also use the form A; if ($?) { B }.
* SSH invocation pitfalls: Forwarding SSH commands with nested quotes in PowerShell (such as ssh host "sudo python3 -c \"...\"") may hang silently. It is recommended to write the command to a local file and then transfer it via scp for execution.

2. Encoding and Text Processing

Windows consoles are often not UTF-8, and Python’s subprocess decodes child process output using the system locale (Chinese Windows defaults to GBK).
* Console output: Do not rely on Chinese text displayed in the console; even if the underlying data is correct, the display may be garbled.
* Avoid inline multiline non-ASCII text: Do not pass multiline non-ASCII text via -c "..." or inline heredocs. Write it to a file first, then run it.
* Python subprocess: Explicitly specify encoding="utf-8", errors="replace"; otherwise the child process may crash due to decoding errors.
* File writing: Set-Content and Add-Content use the system ANSI encoding by default (GBK on Chinese Windows). When writing Chinese text, add the -Encoding utf8 parameter; otherwise the file on disk may be corrupted.

3. File System and System-Reserved Names

  • Symbolic links and junctions: Creating a junction or symlink requires administrator privileges or Developer Mode. If permissions are insufficient, the operation may fail silently; verify whether it actually exists.
  • Reserved names: NUL, CON, PRN, AUX, COM1-9, and LPT1-9 are reserved names in any Windows directory. Do not attempt to redirect output using > nul, as this may create a file named nul. Use $null or Out-Null instead.
  • Office file locks: If a file is opened by Word, Excel, or WPS, attempting to write to it will raise an ordinary PermissionError. This is not data corruption and should not be retried.

4. Tool-Specific Issues

  • Docker volume mounts: When using -v "C:\path\file.yaml:/container/path:ro" with docker run, the colon : in the path may cause the mount specification to be split incorrectly. The mount may fail while the container still appears healthy. It is recommended to enter the container with docker exec and inspect the file.
  • Node.js binaries: .node npm bindings built in the plugin’s build directory are Windows binaries. If deployed to a Linux server, the program will fail at runtime, even if npm install succeeds.
  • Process termination and port release: Killing an outer task runner (such as a job wrapper) does not release the port. If the underlying node/python process is still running, the port remains occupied. You must find and terminate the actual PID.
  • Windowless scheduled tasks: Even when using -WindowStyle Hidden, scheduled tasks may still flash a console window. To run completely without a window, use pythonw.exe together with the CREATE_NO_WINDOW flag.

Installation and Activation

Install the plugin using DSH’s plugin manager:

dsh plugin add dsh-windows-native

After installation, the injection condition must be specified in the configuration file. By default, the plugin takes effect only when windows is detected, but you can adjust the configuration:

when: windows   # 仅在原生 Win32 环境注入，或改为 "always" 全局注入
order: 15       # 确保在其他系统提示注入之后执行
extraNotes: ""  # 可在此处追加自定义备注

Use Cases and Notes

  • Use cases: Running DeepSeek Harness directly on native Windows (PowerShell) in a non-WSL environment.
  • Note: The plugin is essentially a system prompt injection and directly modifies the agent’s behavior pattern. Before installation, review its source code to ensure it complies with your security policy.
  • Status note: The plugin is currently in an early stage. The list’s coverage is based on the author’s personal experience with pitfalls and may not cover all Windows gotchas. If you encounter an issue not covered by the plugin, submit a PR directly with actual failure information.

Conclusion

dsh-windows-native provides a basic defensive mechanism for building agents on native Windows. It translates complex system behaviors into clear instructions, helping the agent avoid common encoding and file system errors. For more details and source code, consult the plugin directory or GitHub repository.