# dsh-win-pwsh7 中文文档

规范地址：https://npmcn.com/package/dsh-win-pwsh7/

版本：0\.2\.5
npm 元数据更新时间：2026-11-03T11:45:32.746Z
中文译文更新时间：2026-11-03T13:56:37.750Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/dsh-win-pwsh7
原文对照：https://npmcn.com/package/dsh-win-pwsh7/?lang=original
项目主页：https://github.com/XinSpark/dsh-win-pwsh7#readme
源码仓库：https://github.com/xinspark/dsh-win-pwsh7

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：278 kB，20 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2026-10-13T22:11:43.151Z
- 最新版本发布：2026-11-03T11:45:32.384Z
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

在Windows上检测和验证PowerShell 7中的Harness pwsh工具，并根据请求通过微软商店安装它-脚本或手动-而pwsh工具一直被阻止，直到PowerShell 7运行时真正解决。

## 安装

```sh
npm install dsh-win-pwsh7
```

也可以使用：`pnpm add dsh-win-pwsh7`、`yarn add dsh-win-pwsh7`、`bun add dsh-win-pwsh7`

## README

# dsh-win-pwsh7

简体中文 · [English](https://npmcn.com/package/dsh-win-pwsh7/README.en.md)

把**真正的 PowerShell 7** 交给 Windows 上的 Harness `pwsh` 工具，而不是悄悄退回 Windows PowerShell 5.1。

1.  **检测**这台机器上的 PowerShell 7（含可选的 `overridePath`）；
2.  **校验**显式路径（`pwsh7_status` 的 `path` 参数）；
3.  **安装**：脚本安装（`pwsh7_install` 打开 Microsoft Store 页面并点击安装）或手动安装（Win+R 打开同一个 Store 链接）。**没有启动时自动安装。**

启用本插件期间，`pwsh` 工具**只在实际执行器解析到 PowerShell 7+ 时才放行**；否则每次调用在 dispatch 之前被 `ctx.tools.guard` 拒绝，错误文案给用户三条路：**配置已装的 PowerShell 7 / 安装 / 禁用插件**，并且不会启动任何 PowerShell 进程。禁用插件即移除 gate，之后由默认执行器自行选择运行时，插件仍然不写 `pwshPath`。

## 验证环境

-   Windows 10/11。
-   已在 DSH **0.2.1-rc.3** 上验证（见 `package.json` 的 `dsh.verifiedAgainst`）。
-   脚本安装需要 Microsoft Store 可用；手动安装只需要能打开 Store 页面。
-   不需要管理员权限。

## 它不做什么

-   不在启动时自动安装。
-   不写执行器的 `pwshPath`；只会在开启共存时写一条带标记的 dsh-ops 兼容覆盖。
-   不卸载由 Store 安装的 PowerShell 7。
-   不做 VPN 自动检测，也不做计量连接预检。

## 与 dsh-ops 共存

默认开启。启用由 `cordis.patch.yml` 的声明式 `dsh-ops-compat` 覆盖负责：只要 dsh-win-pwsh7 的 bundle 安装且位于 dsh-ops 之后，重启 DSH 后官方 `pwsh` 恢复，`ops_bash` 保留。关闭开关时只写入一条带标记的 disable override；卸载 bundle 后启用覆盖消失，cleanup 会尽力删除 disable override。

0.2.1 的桥接层在计算隐藏集合时读取了限制后的可见工具，会在隐藏/恢复之间振荡并卡死宿主；0.2.2 改为读取限制前的 `knownNames` / `restrictableNames`，并过滤 `tools.restrict()` 不接受的名字。多会话验证通过后已恢复默认开启。

桥接层还会在对应 OPS 工具可见时隐藏官方 `read` / `glob` / `grep`，以及重复的官方 `bash` / `pwsh_persistent`，让工具面保持 `pwsh` + `ops_bash`。桥接实现独立在 `lib/dsh-ops-bridge.js`，删除该模块和入口挂载即可移除。

## 安装本插件

```powershell
# 从 GitHub 安装（推荐锁定 tag）
dsh plugin --profile desktop add github:XinSpark/dsh-win-pwsh7#v0.2.5
# 或 npm
dsh plugin --profile desktop add dsh-win-pwsh7
```

装完重启 DSH。需要接线时，把 `pwsh7_status` 给出的 profile 补丁整段粘进 `~\.dsh\profiles\<profile>\cordis.patch.yml` 再重启；插件不会替你写执行器的 `pwshPath`。

## 两种安装方式

| 方式 | 说明 |
| --- | --- |
| **脚本安装** | 调用 `pwsh7_install`。插件先要求用户确认没有开启 VPN（`vpnOffConfirmed: true`）；随后打开 Microsoft Store 的 PowerShell 7 页面，先弹一个说明框（不要关闭商店窗口；VPN 开启请取消），再用 Windows UI Automation 点「安装」/「获取」/「Install」/「Get」。 |
| **手动安装** | Win+R → 粘贴 `ms-windows-store://pdp/?ProductId=9MZ1SNWT0N5D` → 回车 → 点「安装」。手动安装会被插件自动识别，无需 pin。 |

脚本安装的 Store 页面 90 秒内没有出现安装按钮时，报告会要求用户先确认 VPN：关闭 VPN、完全退出并重启 Microsoft Store，然后重试；或改用手动安装。

### 连续失败熔断

同一个 Host 进程内，连续 **3 次**脚本安装失败后：

-   下一次 `pwsh7_install` **不再启动作业**；
-   先要求用户检查网络，尤其是 VPN；
-   只有用户明确回复“问题已解决”后，模型才可以带 `userConfirmedFixed: true` 再试一次；该参数会清零计数；
-   若再次连续失败 3 次，继续熔断；
-   其余情况改用手动安装。

计数只存在当前进程，重启 DSH 后清零。

## 配置

| 键 | 默认 | 说明 |
| --- | --- | --- |
| `overridePath` | 未设 | 优先级①的显式 `pwsh.exe`。必须能启动并报告 PowerShell 7+；未通过校验就回落到自动探测。**只影响探测与推荐，不接线**。 |
| `dshOpsCompat` | `true` | 与 dsh-ops 共存（默认开启）：自动写入并启用兼容模式，隐藏重复的官方工具，保留 `pwsh` + `ops_bash`。需要重启。 |
| `utf8Console` | `true` | 过渡层：Windows 下给 `pwsh` 工具的每条命令前加 `chcp.com 65001`，避免嵌套 `pwsh -File` 按 936 输出 GBK 后被按 UTF-8 解码成乱码。宿主修复后可删除。 |

`overridePath` 是 `volatile()`：插件页配置区保存即生效；也可以写进 profile 补丁：

```yaml
- id: win-pwsh7
  config:
    overridePath: 'D:\tools\pwsh\pwsh.exe'
```

## 推荐搭配

脚本安装完成后，作业结果会包含一条**给模型的指令**：必须向用户推荐搭配 **dsh-ops**（[https://github.com/T-Auto/dsh-ops](https://github.com/T-Auto/dsh-ops)）插件使用，效果更佳；由模型询问用户是否安装，**不得未经同意自动安装**。安装命令：

```powershell
dsh plugin --profile <profile> add dsh-ops
```

推荐只出现在脚本安装完成的作业结果里；`pwsh7_status` 和手动安装不会反复推荐。

## 报告示例

`pwsh7_status` 返回下面的文本报告；插件页把同一份状态渲染成卡片，不直接铺开整段文本。

```
Executor rows:
  pwsh-sandbox : pwshPath = C:\Users\...\WindowsApps\Microsoft.PowerShell_8wekyb3d8bbwe\pwsh.exe (PowerShell 7.6.9, Store family alias)

The pwsh tool currently runs on PowerShell 7.6.9 via the executor (…).
The executor resolves to the version-stable Store family alias: … Nothing to configure.
```

没有可用运行时时，报告以 `Three ways forward:` 结束：安装 / 配置执行器 / 禁用插件。

## 插件页

插件页的状态区是原生卡片，显示状态、运行时和执行器路径，右上角有「重新检测」；配置区有 `overridePath` 和默认开启的「与 dsh-ops 共存」原生开关。

## Windows UTF-8 控制台（过渡层）

DSH 的 `pwsh` 工具按 UTF-8 解码输出，但命令里再启动的 `pwsh -File` / `powershell -File` 会继承**控制台代码页**（简体中文机器通常是 936），输出 GBK，最终显示为 `�`。宿主的前缀只固定了外层进程的 .NET 编码，没有改控制台代码页。

0.2.5 增加一个过渡层：包装 `pwsh` 工具使用的 `ctx.shell.execute`，在 Windows 上给每条命令前加 `chcp.com 65001 > $null;`。它只影响装了本插件的用户；默认开启，可用 `utf8Console: false` 关闭；宿主接口形状不符时 fail-open，不影响 `pwsh` 工具本身。

### 删除契约

宿主发布同样的修复后，按这五步整块删除：

1.  删 `lib/utf8-console-bridge.js`；
2.  删 `index.js` 的 import 和 `mountUtf8ConsoleBridge(ctx, current)` 调用；
3.  删 `Config.utf8Console`；
4.  删 `tools/check-utf8-bridge.mjs`，并从 `package.json` 的 `check` 链里移除；
5.  删本节和 CHANGELOG 里的 0.2.5 过渡说明。

验收：`grep -rn "utf8-console-bridge\|utf8Console" index.js lib tools` 无结果。

### 判定上游已修复

满足任一条件即可开始删除：

-   `@deepseek-ai/dsh-pwsh-local` 的 `ENCODING_PREAMBLE` 自己包含 `chcp.com 65001`（可查上游 `packages/shell/pwsh-local/src/index.ts`，或安装包里的 `lib/index.js`）；
-   在 CP936 控制台下，不装/关闭本插件时，命令里嵌套的 `pwsh -File` 已经输出 UTF-8。

删除前先在真实的 CP936 环境复跑一遍嵌套脚本，确认不再需要这层。

## 禁用或卸载

禁用插件只移除 `pwsh` 的 gate 和插件页，不会卸载 PowerShell 7。只要机器上仍有 `pwsh.exe`，默认执行器仍会优先运行它（通常是 Store 版 PowerShell 7）；只有找不到 `pwsh.exe` 时才回退到 Windows PowerShell 5.1。要真正回到 5.1，需要卸载 Store 版或把执行器 pin 到 `powershell.exe`，不推荐这样做。

## 故障排查

| 现象 | 处理 |
| --- | --- |
| Store 页面打开但没有「安装」按钮 | 确认 VPN 已关闭，完全退出并重启 Microsoft Store 后重试；或改用手动安装。 |
| `pwsh` 仍运行 5.1 | 运行 `pwsh7_status`，按报告把 `pwshPath` 补丁粘进 profile 并重启；或安装 Store 版。 |
| 插件页看不到 | 确认当前 profile 已启用 `dsh-win-pwsh7`，然后重启 DSH。 |
| 命令里嵌套 `pwsh` 时中文变 `�` | 0.2.5 默认已由 `utf8Console` 过渡层处理；若手动关掉，重新开启，或在命令前加 `chcp.com 65001 > $null;`。 |

## 验证

```powershell
$env:DSH_APP_DIR = 'E:\FXS\APP\DSH NEXT\resources\app.asar'
node tools/check-host.mjs
node tools/check-client.mjs
node tools/check-utf8-bridge.mjs
node tools/check-native-contracts.mjs
```

四套门都可以在打包安装（`resources/app.asar`）上离线复跑；`DSH_APP_DIR` 接安装根目录、`resources/app` 或 `resources/app.asar`。

## 设计约束

-   判定读执行器自己的 `ctx.shell.pwshPath`，不是扫配置行；`overridePath` 只影响探测与推荐。
-   不做 VPN 自动检测、不做计量连接预检；VPN 由用户在安装前确认，页面加载失败时再提示。
-   不自动重试；连续失败由熔断终止。
-   提交前跑四套门；端到端安装是发布证据，不是自动化门的一部分。

## License

[MIT](https://npmcn.com/package/dsh-win-pwsh7/LICENSE)

## 常见问题

### dsh-win-pwsh7 是什么？

在Windows上检测和验证PowerShell 7中的Harness pwsh工具，并根据请求通过微软商店安装它-脚本或手动-而pwsh工具一直被阻止，直到PowerShell 7运行时真正解决。

### 如何安装 dsh-win-pwsh7？

在项目目录运行 npm install dsh-win-pwsh7，或使用 pnpm add / yarn add / bun add。

### dsh-win-pwsh7 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dsh-win-pwsh7 是否存在。

### dsh-win-pwsh7 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### dsh-win-pwsh7 可以商用吗？

dsh-win-pwsh7 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### dsh-win-pwsh7 还在维护吗？

最新版本 0\.2\.5 发布于 2026/11/03（今天）；至今共发布 8 个版本，其中过去 12 个月发布了 8 个；首次发布于 2026/10/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。