# dsh-win32

## 修好 Windows 上的 DSH，不需要 WSL

**官方 PowerShell。Workspace Write。一条命令。**

```powershell
npx dsh-win32 setup
```

当前版 DeepSeek Harness 已经自带持久 PowerShell 和 Windows ACL 沙箱。dsh-win32 会检查这套官方能力，定位已知的 Windows 故障，只执行能够验证安全的修复，并创建桌面快捷方式。

当前路径不会安装 Git、PowerShell、busybox、WSL，也不会把另一个 DSH bundle 写进 profile。

当前版 DSH 请使用上面的独立 CLI。不要为这条路径运行 `dsh plugin --profile web add dsh-win32`：那会安装旧版 bundle，不是当前 Windows 配置方式。

[English](../README.md) · [Windows 实证与旧版细节](./windows-details.md)

**DSH 已经坏了，想禁用/卸载旧插件？** 请看[禁用、卸载与恢复（disable / uninstall / remove）](./uninstall.zh.md)。从 0.17.14 起，`npx dsh-win32@0.17.14 disable --profile web` 可离线预览；关闭 DSH 后添加 `--apply`，先备份 manifest，再解除旧 bundle 启用，不需要 DSH 能启动。

让 coding agent 帮忙时，可以复制[安装与验收指令](https://github.com/sjh9714/dsh-win32/blob/master/docs/agent-setup.md#中文)。第一次排错请看[Windows PowerShell 故障：先诊断，再验证](https://github.com/sjh9714/dsh-win32/blob/master/docs/windows-first-run.zh.md)。

<p>
<a href="https://www.npmjs.com/package/dsh-win32"><img src="https://img.shields.io/npm/v/dsh-win32?style=flat-square&label=npm&color=cb3837" alt="npm"></a>
<a href="https://github.com/sjh9714/dsh-win32/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/sjh9714/dsh-win32/ci.yml?style=flat-square&label=CI" alt="CI"></a>
<a href="https://github.com/sjh9714/dsh-win32/stargazers"><img src="https://img.shields.io/github/stars/sjh9714/dsh-win32?style=flat-square" alt="stars"></a>
<img src="https://img.shields.io/badge/platform-win32-0078D4?style=flat-square" alt="win32">
</p>

## 当前安装流程

**可复现的安装演示，不是真实录屏。**

![当前 DSH 上的 dsh-win32 安装流程](../assets/demo.gif)

这条命令会完成下面的工作。

- 检查官方持久 PowerShell 和 Workspace Write package
- 检查 PowerShell 7 与已知损坏的 koffi runtime
- 为 Web profile 创建 `DeepSeek Harness` 桌面快捷方式
- 不修改官方 profile 和 Minimal 预设
- 输出第一次会话所需的准确步骤

安装后打开 DSH，添加工作区，选择官方 **Minimal**，权限保持 **Workspace Write**。

从 **0.17.12** 开始，可显式选择 setup 后执行一次已安装组件验收：

```powershell
npx dsh-win32 setup --verify
```

按需添加 `--profile NAME --no-shortcut`。普通 `setup` 不变，`--legacy --verify` 被拒绝。Setup 与组件验收分开报告；验收失败或环境不受支持时命令以非零退出。它不会安装 DSH，也不证明完整 Desktop/Minimal 会话通过。不需要 setup 或需要 JSON 时，使用 `npx dsh-win32 verify --json`。

## 体检与安全修复

```powershell
npx dsh-win32 doctor
npx dsh-win32 doctor --json
npx dsh-win32 fix
```

`doctor` 检查官方 Windows stack 和本机已知故障。JSON 输出遵循 `dsh-doctor/v1`。

`fix` 只处理已知损坏或真实加载失败的 koffi 版本，修复后会再次执行加载验证。

## 升级前先检查

```powershell
npx dsh-win32 preflight
npx dsh-win32 preflight --target 0.2.2-alpha.2 --profile web
npx dsh-win32 preflight --json
```

`preflight` 只回答一个问题：这个 profile 能否升级到目标 DSH 版本。它只读，也可以在 macOS 和 Linux 上运行。`--target` 接受 `@deepseek-ai/dsh` 的精确版本或 dist-tag，默认 `latest`。

- **插件**：读取 profile 中的第三方插件（包括已停用的），并对目标版本套用 host 自身的规则。有 `engines.dsh` 时只看它，否则检查 DSH peer，预发布版本也参与判断。CI 会把结果与已安装的 `dsh-app-boot` 对比。`dsh plugin allow-version` 的豁免只有写明目标精确版本时才算数。
- **Node**：使用目标版本的 `engines.node`。部分版本没有声明，此时回退到 `^22.19.0 || >=24` 并注明。
- **Windows**：检查 PowerShell 7 是否存在，以及 `pwsh` 能否通过 PATH 解析。
- **版本规则**：升级跨过已知行为变更（已保存的模型 ID、API Key 来源、SSH 协议）时给出警告。这些只是提醒，不会读取你的设置来确认是否受影响。如果目标版本比这些规则最后审阅的版本更新，它会单独给出警告，因为其变更尚未被检查。

退出码与 `doctor` 相同：0 全部通过，1 有警告，2 有失败。无法读取目标或 profile 也算失败，因此没有完成的检查不会显示为安全。遇到不兼容的插件时，它会查询该插件的最新版本；如果兼容就建议更新，否则建议保留当前 DSH。通过不代表升级一定成功：它只覆盖已声明的要求和已知变更，不会安装或启动目标版本。升级后请运行 `verify`。

## Windows 正常后，再搬现有配置

[dsh-movein](https://github.com/sjh9714/dsh-movein) 可以预演搬入 Claude Code、Codex 或 OpenCode 配置。它是可选的另一项操作；dsh-win32 不会自动安装它。

在需要搬入的项目目录中先运行 `npx dsh-movein`，查看目标、冲突和不支持项，确认后才使用 `--apply`。搬入配置不代表 hook 强制生效，也不代表完整 Minimal 会话已经验收。

## 旧版 DSH

DSH rc.6 及更早版本没有当前官方 PowerShell stack。原来的 Git Bash 和 busybox 预设仍保留，但必须显式选择。

package 中的 `@deepseek-ai/dsh-subprocess-local` peer 范围 `>=0.1.0-rc.5 <0.1.0-rc.7` 是刻意保留的旧版 bundle 边界，不是独立 `setup`、`doctor` 或 `verify` 命令的 host 版本范围；这些命令不会把 bundle 接入当前版 DSH。`dsh plugin add` 成功不等于兼容，缺少 host-peer 警告的问题见[上游 #6680](https://github.com/deepseek-ai/deepseek-harness/discussions/6680)。

如果新宿主提示 `skipping profile bundle "dsh-win32"` 或 subprocess peer 不兼容，不要把放宽版本范围或 `allow-version` 豁免当成修复。DSH `0.1.7-rc.1` 要求的进程检查器 snapshot 契约与旧 bundle 不同；能加载或 `--dump-config` 成功不等于旧 bundle 兼容。请按[兼容性警告迁移指南](https://github.com/sjh9714/dsh-win32/blob/master/docs/windows-first-run.zh.md#compatibility-warning)处理。当前 DSH 已自带 Windows 进程检查器。

如果当前 profile 已把 dsh-win32 列为插件，请用真实 profile 名运行 `npx dsh-win32 doctor --profile NAME`。Doctor 会提示旧版 bundle 和移除命令，但不会自动移除。先检查并备份受影响的 profile，再决定是否移除。

```powershell
npx dsh-win32 setup --legacy
npx dsh-win32 setup --legacy --sandboxed
npx dsh-win32 doctor --legacy
```

旧版 Git Bash 预设需要 `danger-full-access`。旧版 busybox 预设可以留在 Workspace Write。两个路径都不会自动安装 Git。

## 限制

- 当前路径检查 npm 上发布的 DSH package metadata，不能证明另一个缓存中的 launcher 正在运行同一版本
- `verify` 只验收官方 PowerShell、terminal、subprocess、Workspace Write policy 与 ACL sandbox 组件链，不会启动完整 Minimal host，也不会验证插件安装或 hook 强制执行
- `verify` 会自行创建 Workspace Write policy 和受 Windows ACL 约束的 PowerShell 子进程。如果调用它的 agent 已经位于另一层 Workspace Write 或 Windows ACL 沙箱内，请只为这一条 verify 命令批准一次非沙箱/full-access 执行；嵌套的受限 token/ConPTY 可能在 PowerShell 启动前停住。内层验收边界不会被绕过，工作区外写入仍必须被拒绝。
- Windows 上的本地 `dsh plugin add` 路径可能因空格被拆分；本地包请暂存到不含空格的绝对路径，并回读实际安装的 package（[上游 #2485](https://github.com/deepseek-ai/deepseek-harness/discussions/2485)）
- hook 日志不能单独证明拦截生效；Windows PowerShell 可能丢失 interpreter hook 的阻塞退出码，而 `{"continue": false}` 也可能只记录 stop 却继续运行。修改 hook 或升级 DSH 后，请用无害的必拒绝 canary 确认目标动作真的被拦住（[上游 #2485](https://github.com/deepseek-ai/deepseek-harness/discussions/2485)、[#1514](https://github.com/deepseek-ai/deepseek-harness/discussions/1514)）
- 推荐 PowerShell 7，但 dsh-win32 不会自动安装
- 旧版 busybox 会话使用 ash，不是 Bash
- 编辑旧编码文件后会保存为 UTF-8
- 上游 Windows 路径问题修好前，把 `C:\tmp` 视为旧版写入围栏之外

## License

MIT.