环境体检医生 ZJYSZT/dsh-env-doctor

dsh-env-doctor

Windows / DSH 环境医生 —— 说一句「体检一下」，拿到「哪里坏了 + 为什么 + 该敲什么」。

状态：v0.1.0 已发布到 npm。 设计文档仍在（检查目录、安全模型、报告格式），随包一起发。

中文 · English

1. 它解决什么

Windows 上跑 DSH（或任何 Node 工具链），坏掉的方式往往很隐蔽：命令明明装了却解析到 .ps1、git push 卡在凭据、bash 起不来但不是 Git 坏了、沙箱把写入拒了却给不出原因。这些问题的共同点是——报错信息不指向真正的原因。

dsh-env-doctor 做一件事：把该查的都查一遍，按「真的坏了 / 能用但要注意 / 说不准」三档给结论，每条都带原始证据和可以直接粘贴的命令。

它不是万能修复器，设计上刻意保守：

- 体检零副作用：除了两个自写自删的探针文件，不建文件、不改配置、不动注册表。
- 只有 4 条能自动修（B.2 / C.4 / D.1 / E.3），且都要你先明确点头；其余只给命令。
- 说不准就说不准：探测不到时给 undiagnosed 并说明原因，绝不猜成 ok。

2. 安装

dsh plugin --profile desktop add dsh-env-doctor

装完完全退出 DSH Desktop 再打开一次（模块代码要重启才加载；只热更新配置不够）。dsh web 用户用 --profile web 并重启 dsh web。

装不上时优先试：add dsh-env-doctor@latest --registry https://registry.npmjs.org。刚发布的版本可能被 pnpm 的 minimumReleaseAge 供应链接管期静默跳过，或镜像还没同步。

3. 使用

在对话里说「体检一下」，或直接点名工具：

dsh_env_doctor(mode="check")

三种模式：

| 模式 | 做什么 | 写东西吗 |
| check | 跑全部 17 项，写报告文件 | 只写报告（默认在你工作区的 .dsh-doctor/） |
| explain | 不跑命令，按当前沙箱模式解释某一项为什么这样判 | 不写 |
| fix | 执行一条已确认的修复（见第 5 节） | 会改你点头的那一处 |

报告写到 <工作区>/.dsh-doctor/report-<时间戳>.md（旁边一份同内容 JSON 供历史对比），给模型看的只有十来行摘要。

4. 它检查什么（17 项）

| 组 | 查什么 | 项 |
| A 沙箱与文件权限 | 沙箱模式、工作区可写性、边界是否生效、ACL 是否被改坏 | A.1–A.3 |
| B Git Bash | 能不能启动（沙箱内启动失败是已知限制，判 undiagnosed 而不是故障）、是否在 PATH | B.1–B.2 |
| C 网络 / TLS / 凭据 | npm registry 可达性、TLS 栈、代理三处一致性、git 凭据助手是否指向不存在的程序 | C.1–C.4 |
| D 执行策略 | PowerShell 是否拦住 npm.ps1 / pnpm.ps1 | D.1 |
| E 工具链 | DSH 与 Node 版本、必备命令、同名多份安装、pnpm 大版本、python | E.1–E.5 |
| F 权限与安装通道 | 管理员/winget/choco/scoop、磁盘空间与长路径 | F.1–F.2 |

完整的判据、探测命令、危险等级在 检查目录；那份表是实现和历史的唯一契约，id 发布后不再改。

5. 它会改什么、绝不改什么

能自动修的 4 条（都要你先确认，命令逐字打印，旧值记进报告以便撤销）：

| id | 改什么 |
| B.2 | 把 bash 所在目录追加进用户级 PATH |
| C.4 | 删掉指向不存在程序的 git 凭据 helper，再 gh auth setup-git |
| D.1 | 把 CurrentUser 执行策略设为 RemoteSigned |
| E.3 | 调整用户级 PATH 顺序，让 .cmd 优先于 .ps1 |

永不碰：ACL（交棒内置技能 diagnose-windows-sandbox-acl）、注册表安全项、MSI/需要 UAC 的安装、系统级 PATH、任何带密码或令牌的文件。这些一律只给命令。

安全模型的完整论证（为什么"体检不写"能靠代码保证、两道确认门在哪、怎么测）见 docs/safety/model.md。

6. 报告长什么样

给模型的摘要（十来行，不是报告全文）：

体检完成：17 项检查 —— 通过 13、注意 2、失败 1、说不准 1。总体：失败
1. [高危] C.4 git 凭据助手指向的程序是否存在
→ git config --global --unset-all credential.https://github.com.helper
2. [中] D.1 执行策略是否拦 .ps1 脚本
→ Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
3. [低] E.3 同名命令多份安装 / 解析到意料之外
→ 把 %APPDATA%\npm 与 pnpm 的 .cmd shim 所在目录在用户级 PATH 中前置到 WindowsApps 之前说不准：B.1（原因见报告）全文：C:\...\.dsh-doctor\report-20261014-171203.md

这段就是 sample-summary.md 的原文（那个示例里 B.2 已经修完并复检通过，所以它不在「要动手」里，而是出现在报告的「已执行的修复」）。
完整报告是 Markdown：顶部一张元信息表 + 一句话结论，然后每个问题一节（现象 / 证据 / 下一步），最后是 17 项总表和「说不准的」。样例见 docs/prototypes/report/sample-report.md（构造的示例，用来演示四种 verdict 的形状，不是某台机器的真体检记录）。

7. 常见问题

- B.1 说 bash 起不来，可我明明能用 Git Bash？ 在 DSH 沙箱里启动 MSYS2 会报 couldn't create signal pipe, Win32 error 5，这是沙箱限制，不是你的 Git 坏了——所以判 undiagnosed 并给你一条在新终端里跑的命令。
- A.3 为什么总是「说不准」？ ACL 的真损坏只有两类（授权树里缺有效的 WRITE_DAC/WRITE_OWNER，或出现显式 AppContainer 包 ACE）；其余一律不猜。这项交棒给内置技能处理，本插件不改 ACL。
- 报告的 id 会变吗？ 不会。C.4 这类 id 是历史对比的键，只许往后追加新项。

8. 卸载

dsh plugin --profile desktop remove dsh-env-doctor

自动修过的东西不会自动还原——按报告里每条的「撤销」命令回退即可。

9. 开发

git clone https://github.com/ZJYSZT/dsh-env-doctor
cd dsh-env-doctor
npm test # 假 shell 的单元测试 + 四组安全测试（见 docs/safety/model.md §4）
npm run test:e2e # 在本机真跑 17 项（会真的读注册表 / 查 PATH，不写除报告外的任何东西）
npm run verify:samples # 重新生成报告样例并验证 schema / 样例 / 渲染器三者不漂移
dsh plugin --profile desktop add . # 本地装进 profile

发布流程（版本策略、registry 前置条件、发布清单）见 RELEASE.md。

10. 许可

Apache-2.0，版权声明见 NOTICE。

dsh-env-doctor 是 DSH 的 Windows 环境医生。说一句「跑个体检」，每项检查都给你一个结论——坏了 / 值得留意 / 说不准——每条都附原始证据和一条能直接粘贴的命令。

设计原则：体检绝不改动你的机器（只写一个报告文件）；只有四项能自动修（B.2、C.4、D.1、E.3），而且必须你明确确认；凡是观测不到的，一律报 undiagnosed，绝不猜成 ok。

状态： 设计已完成，实现进行中；v0.1.0 尚未发布。

安装（发布后）：

dsh plugin --profile desktop add dsh-env-doctor
then fully quit and reopen DSH Desktop

使用：

dsh_env_doctor(mode="check") # run all 17 checks, write the report
dsh_env_doctor(mode="explain", input="A.3") # explain one check without running it
dsh_env_doctor(mode="fix", fix={id:"C.4", confirm:true}) # one confirmed fix

报告写到 <workspace>/.dsh-doctor/report-<timestamp>.md，另存一份 JSON 供历史对比。17 项检查覆盖沙箱 / ACL、Git Bash、网络 / TLS / 凭据、PowerShell 执行策略、工具链、安装渠道。绝不碰：ACL、注册表安全键、任何需要 UAC 的东西、系统 PATH、凭据文件。

完整设计——检查目录、安全模型、报告 schema——见 docs/。基于 Apache-2.0 许可。