dsh-env-inspector

dsh-env-inspector

环境信息探针插件（v0.3.0）：一条命令拿到版本、PATH、环境变量，以及磁盘容量与端口占用。敏感值永不显示明文。

安装

npm install dsh-env-inspector

工具

inspect_env

参数	类型	说明
scope	string	all（默认）/ versions / path / env
env_filter	string	可选，按子串过滤变量名（大小写不敏感）
env_show_sensitive	boolean	默认 false；true 时列出敏感变量名（值仍掩码）

输出内容：

• versions：平台/架构、主机名、Node、npm、git 版本（命令不可用时如实标注，不阻塞）
• path：PATH 目录逐项列出（Windows 按 ;、Unix 按 : 分割）
• env：环境变量键值；敏感变量默认隐藏并提示数量

locate_command

参数	类型	说明
commands	string[]	必填，要定位的命令名列表（如 node、git）

Windows 用 where、Unix 用 which，一次可查多个命令；含路径分隔符的输入会被跳过，未找到的命令如实标注。

disk_usage

参数	类型	说明
paths	string[]	可选，指定目录或挂载点（如 E:\、/var）；省略则枚举本机全部盘符/挂载点

Windows 通过盘符枚举加 statfs 读取容量，Unix 走 df -Pk。输出总容量、已用、可用与使用率，使用率 ≥90% 的卷会追加提醒。纯读取，不写入任何文件。

port_usage

参数	类型	说明
port	integer	可选，查询单个端口（如 3000）；省略则列出全部监听端口
limit	integer	可选，列表模式最多展示条数，默认 50

取数命令按平台自动降级：Windows netstat -ano + tasklist，Linux ss → netstat -tulpn，macOS 兜底 lsof。输出协议、监听地址、PID 与进程名；查询指定端口未命中时明确回复"未发现监听进程"。

脱敏策略

变量名命中以下模式（不区分大小写）即视为敏感：key、token、secret、password/passwd/pwd、credential、auth、cookie、session、signature、cert。

• 默认：敏感变量整体隐藏，输出提示"另有 N 个敏感变量已隐藏"
• env_show_sensitive=true：显示变量名，值以掩码形式呈现（保留前 2 后 1 字符 + 长度标注，如 sk***f(len=18)），任何情况下不显示明文
• 设计原则：宁可多掩码（误报），绝不漏报

测试

npm test

覆盖敏感名识别与掩码格式、明文不泄露、过滤与 scope 校验，容量格式化与 df 解析，netstat/ss/lsof 三套端口输出解析、非法端口与非法 scope 报错等 64 项断言。

版本历史

0.3.0（2026-09-30）

• 新增 disk_usage 工具：盘符/挂载点容量总览，使用率 ≥90% 预警
• 新增 port_usage 工具：端口占用查询与监听进程定位（跨平台自动降级）
• 修复 Windows 下 npm 版本探测：Node 自带工具路径含空格时执行失败

0.2.0（2026-09-13）

• 新增 locate_command 工具：定位命令真实路径（which/where）
• inspect_env 新增内存与代理环境变量段（HTTP_PROXY 等值掩码）

Roadmap（v0.4 候选）

• 环境变量批量导出（脱敏后可存档）
• 磁盘/端口快照留存，与上次结果对比

源码与发布地址

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-env-inspector
• npm：https://www.npmjs.com/package/dsh-env-inspector

典型场景

1. 排查"命令找不到"

用户：为什么 npm 命令在脚本里报 ENOENT

locate_command 定位可执行文件的真实路径与类型，inspect_env 查看 PATH 是否包含目标目录。

2. 跨平台脚本兼容性检查

用户：这个脚本在 Windows 上能跑吗

查看 shell、平台、关键环境变量差异，提前发现 .cmd/shell: true 之类的平台差异。

3. 环境变量核对

用户：代理/编码相关的环境变量现在是什么值

inspect_env 按名称过滤列出环境变量（自动屏蔽疑似敏感值）。

4. CI 与本地环境对比

用户：CI 里为什么行为不一样

在两边分别跑 inspect_env，对比 Node 版本、平台、PATH 与代理变量。

5. 端口被占用排查

用户：3000 端口起不来，谁占着

port_usage 传 port=3000 直接给出 PID 与进程名；若怀疑是磁盘写满导致启动失败，用 disk_usage 确认目标盘剩余空间。

安全边界

• 敏感值屏蔽：名称含 TOKEN/KEY/SECRET/PASSWORD/CREDENTIAL 等的环境变量只显示是否存在与长度，不输出原值。
• 只读：不设置、不修改任何环境变量，不写入文件。
• 不发起网络请求：仅读取本机进程环境与 PATH 解析结果。
• 路径信息：输出包含本机绝对路径，分享输出前请自行确认是否含敏感目录名。

其他插件集成说明

协作插件	集成方式
dsh-code-check	环境差异常是代码检查结果不一致的根因，两者配合定位
dsh-http-client	代理类环境变量（HTTP_PROXY 等）会影响请求，出问题先来本插件核对
dsh-fs-inspector	定位到 PATH 中某目录异常膨胀/缺失时，用 dir_size 下钻
dsh-workspace-journal	环境快照可写入日志，形成"环境何时变过"的长期记录

FAQ

Q：为什么有些变量值显示为 ***？ 按名称关键词自动屏蔽（token/key/secret 等）。这是刻意的安全设计，避免凭据进入对话上下文。

Q：能看到 PATH 的每一段吗？ 可以，PATH 会按分隔符拆分为列表展示，便于逐段核对。

Q：Windows 上为什么找不到某些命令？ Windows 下 npm/git 等常是 .cmd 包装，需要经 shell 调用。locate_command 会指出实际文件类型，辅助判断。

Q：会修改环境吗？ 不会，纯读取。