前言¶

DeepSeek Harness (DSH) 采用插件化架构，旨在通过系统提示注入来规范智能体的行为。在现有的 DSH 插件生态中，多数针对 WSL（Windows Subsystem for Linux）的插件假设环境是从 WSL 向外桥接的。如果你在原生 Windows（无 WSL）环境下运行 DSH，现有的插件无法覆盖 PowerShell 的原生特性。

在原生 Windows 上直接使用 PowerShell 时，智能体常在命令链、编码处理和文件系统交互上犯错。dsh-windows-native 插件通过注入一份系统提示，将这些常见的“脚注陷阱”提前告知智能体，避免其在执行过程中反复试错。

插件介绍¶

dsh-windows-native 是一个专门针对原生 Windows (non-WSL) 环境的 DSH 插件。它不提供外部工具或二进制文件，而是一段系统提示注入，用于指导智能体在处理 PowerShell 语法、控制台编码以及 Windows 文件系统特性时的正确做法。

该插件由 lucifergzsz414 维护，采用 MIT 许可证。它基于作者在原生 Windows 环境中踩过的实际坑点整理而成，目前处于早期阶段。

核心功能¶

插件通过系统提示告知智能体以下 Windows 环境下的关键细节：

1. 命令链与执行逻辑¶

PowerShell 5.1 等原生版本不原生支持 && 或 || 命令链。
* 使用 ; 替代：如果需要顺序执行，请使用分号 ;。
* 替代写法：也可以使用 A; if ($?) { B } 的形式。
* SSH 调用陷阱：在 PowerShell 中转发包含嵌套引号的 SSH 命令（如 ssh host "sudo python3 -c \"...\"") 可能会静默挂起。建议将命令写入本地文件，然后通过 scp 传输执行。

2. 编码与文本处理¶

Windows 控制台通常不是 UTF-8，且 Python 的 subprocess 会使用系统区域设置（中文 Windows 默认为 GBK）解码子进程输出。
* 控制台输出：不要依赖控制台显示的中文文本，即使数据本身是正确的，显示可能已乱码。
* 避免内联多行非 ASCII 文本：不要通过 -c "..." 或内联 heredoc 传递多行非 ASCII 文本，应先写入文件再运行。
* Python subprocess：显式指定 encoding="utf-8", errors="replace"，否则子进程可能因解码错误而崩溃。
* 文件写入：Set-Content 和 Add-Content 默认使用系统 ANSI 编码（中文 Windows 为 GBK），写入中文文本时需添加 -Encoding utf8 参数，否则磁盘文件会损坏。

3. 文件系统与系统保留名称¶

• 符号链接与 Junction：创建 junction 或 symlink 需要管理员权限或开启开发者模式。若权限不足，操作会静默失败，请检查实际是否存在。
• 保留名称：NUL、CON、PRN、AUX、COM1-9、LPT1-9 在 Windows 的任何目录下都是保留名称。不要尝试使用 > nul 重定向输出，这可能会创建一个名为 nul 的文件。请使用 $null 或 Out-Null。
• Office 文件锁定：如果文件被 Word、Excel 或 WPS 打开，尝试写入会抛出普通的 PermissionError，这不是数据损坏，无需重试。

4. 工具特定问题¶

• Docker 卷挂载：在 docker run 中使用 -v "C:\path\file.yaml:/container/path:ro" 时，路径中的冒号 : 可能导致挂载被错误拆分，导致挂载失败但容器仍显示健康。建议使用 docker exec 进入容器检查文件。
• Node.js 二进制文件：在此插件构建的目录中构建的 .node npm 绑定是 Windows 二进制文件。如果将其部署到 Linux 服务器，程序会在运行时报错，尽管 npm install 可能成功。
• 进程终止与端口释放：杀死外层任务运行器（如 job wrapper）并不会释放端口，如果底层的 node/python 进程仍在运行，端口仍被占用。必须找到真实的 PID 进行终止。
• 计划任务无窗口：即使使用 -WindowStyle Hidden，计划任务有时仍会闪烁控制台窗口。要实现完全无窗口运行，应使用 pythonw.exe 配合 CREATE_NO_WINDOW 标志。

安装与启用¶

通过 DSH 的插件管理器安装该插件：

dsh plugin add dsh-windows-native

安装后，需要在配置文件中指定注入条件。默认情况下，插件会仅在检测到 windows 时生效，但你可以调整配置：

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

适用场景与注意¶

• 适用场景：直接在原生 Windows (PowerShell) 上运行 DeepSeek Harness，且环境为非 WSL。
• 注意：该插件本质上是一段系统提示注入，会直接修改智能体的行为模式。在安装前，建议查看其源码以确保符合你的安全策略。
• 状态说明：插件目前处于早期阶段，列表长度基于作者的个人踩坑经验，可能并非涵盖所有 Windows 脚注。如果遇到插件未覆盖的问题，请直接提交包含实际失败信息的 PR。

结尾¶

dsh-windows-native 为在原生 Windows 上构建智能体提供了基础的防御机制。它将复杂的系统特性转化为清晰的指令，帮助智能体规避编码和文件系统层面的常见错误。更多细节和源码，请查阅插件目录或 GitHub 仓库。