环境排障工具 Caoran1314/dsh-envkit

dsh-envkit 🔧

DeepSeek Harness 环境工具插件：遇到「某类操作莫名失败」时，先探明环境，而不是靠猜。

三个工具都来自真实事故的沉淀（详见 为什么）。

工具

env_probe — 一次性探明环境

| 探什么 | 为什么 |
| 网络端点可达性（npm / GitHub API / raw / codeload / jsDelivr / PyPI） | 某个源不通时，换另一个（如 API 限流就改走 codeload tarball） |
| 代理环境变量 | 用户开了代理但工具没继承时，症状会伪装成「服务挂了」 |
| 临时目录 / 家目录 / 当前目录可写性 | 安装器或包管理器报 拒绝访问 时先确认到底哪里不可写 |
| 子进程管道 spawn 能力 | 受限沙箱下 Node spawn(stdio:'pipe') 会 EPERM，表现为「命令莫名跑不起来」 |
| 平台 / Node 版本 | 版本相关的坑很多 |

返回里还带 hints——按探测结果给出针对性建议，而不是丢一堆原始数据。

safe_json_edit — 无 BOM 安全改写 JSON

DSH 的头号杀手：profile 的 package.json 被写入 UTF-8 BOM，之后 dsh plugin 全命令报 SyntaxError: Unexpected token ''。

本工具：读取时容忍 BOM，写回时保证无 BOM、原子替换，默认留一份备份，并支持点路径操作：

{
"file": "C:\\Users\\you\\.dsh\\profiles\\desktop\\package.json",
"set": { "dsh.profile.bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-edict"] },
"del": ["dependencies.something-old"]
}

{"inspectOnly": true} 只检查（是否带 BOM、能否解析、缩进与换行风格），不改文件。

git_repair — .git 元数据丢失检测与重建

.git/objects 和 refs 还在、但 HEAD / config / index 被删时，git 会报 not a git repository。本工具识别这种状态（metadata-lost-objects-intact）并给出重建步骤：

git init → git branch -M main → git remote add origin <remote>
→ git fetch origin → git reset --mixed origin/main # 保留工作区改动

默认 dryRun: true，只列命令不执行；确认后传 dryRun: false。

安装

dsh plugin --profile desktop add dsh-envkit

装完重启 DSH：设置页会出现「环境工具」面板（可视化展示探测结果 + 一键检查本机各 profile 的 BOM 与 bundles 状态）。

无 UI 时也可用命令：env-probe、env-json-check <file>、env-git-check [dir]。

设置页面板

- 网络端点可达性（✓/✗ + 状态码 + 耗时）
- 运行环境（子进程管道、各目录可写性、代理变量）
- 提示（按探测结果生成）
- 「检查我的 profile」：只读列出每个 profile 的 hasBom、bundles/deps 数量、以及「已装但未启用」的插件

为什么有这三个工具

这份插件的每一条都对应本仓库作者真实踩过的坑：

| 事故 | 症状 | 对应工具 |
| profile 被写入 BOM | dsh plugin 全命令 SyntaxError | safe_json_edit |
| 沙箱剥离 TLS 凭据 / 限制命名管道 | schannel: SEC_E_NO_CREDENTIALS、spawn EPERM | env_probe |
| GitHub API 匿名限流 60/h | 安装/探测报「无法安装」，但插件本身没问题 | env_probe（提示改走 codeload） |
| .git 元数据被删 | not a git repository，但 objects/refs 都在 | git_repair |

安全边界

- env_probe 只做只读探测（GET 请求 + 临时文件写入后立即删除）
- safe_json_edit 会改文件，因此：默认备份、原子写、支持 inspectOnly
- git_repair 默认 dryRun，且只做 init/fetch/reset（不删任何东西）

开发

npm test # 契约测试 + 冒烟测试
npm run contract # 只跑契约测试（校验 dsh.bundle / dsh.client / exports 成对 / 路由存在）

契约测试与 dsh-plugin-authoring 技能里的范式一致。

License

MIT