dsh-dotenv-toolkit

dsh-dotenv-toolkit

DeepSeek Harness 的 .env 环境配置工具箱：parse_env 解析 .env 为键值对、diff_env 对比 .env 与 .env.example 找缺失 / 多余 / 值不一致、mask_env 对敏感键脱敏展示。只读、零运行时依赖，帮你把环境配置管清楚又防泄露。

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

功能说明

.env 是项目的敏感配置仓：里面躺着 API Key、数据库密码、令牌。看得时候怕泄露、排查环境差异时怕漏配。本插件用三档工具把 .env 管理起来：

• 解析（parse_env）：把 .env 文本解析成键值对，自动识别敏感键并脱敏展示（只留首尾 4 位 + 长度），输出键、值、是否引号包裹与行号。
• 对比（diff_env）：对比 .env 与 .env.example，找出缺失键（example 有而 .env 没有，建议补充）、多余键（.env 有而 example 没有，可能已废弃）与值不一致的键。用于环境配置一致性检查。
• 脱敏（mask_env）：完整展示 .env，但自动识别敏感键（键名含 secret / token / password / api_key 等提示词）并脱敏，其余键原样展示。安全地看环境配置。

解析是启发式的：支持注释、空行、export 前缀、单双引号值、值内等号与行尾内联注释，不做 shell 语义完整展开。核心安全约束：敏感键绝不输出完整值。

安装

npm install dsh-dotenv-toolkit

安装后在 cordis.patch.yml 中加入：

- insert:
    - id: dotenv-toolkit
      name: "dsh-dotenv-toolkit"

使用说明

parse_env

解析 .env 为键值对。path 传 .env 文件或所在目录；mask 控制是否对敏感键脱敏（默认 true）；show 控制列出多少。

文件：E:\project\.env；解析到键 5 个
键值对（前 5 / 共 5）：
1. APP_NAME=myapp
2. PORT=8080
3. API_KEY=abc1…cret（len=15）（敏感，已脱敏）
4. DB_URL=postgres://localhost/db
5. LEGACY_KEY=old
其中敏感键 1 个已脱敏展示，避免泄露完整值。
说明：启发式解析，不做 shell 语义完整展开；export 前缀与引号已处理。

参数：path（必填）；max_size；show（默认 20）；mask（默认 true）；max_chars。

用户：这个 .env 里配了哪些键，别把密钥打出来

助手：调用 parse_env，path=.env，输出键值对且敏感键自动脱敏

diff_env

对比 .env 与 .env.example。path 传 .env 文件或目录；example 指定 .env.example 路径（缺省在 .env 同目录找）；top 控制每类列出多少。

.env：E:\project\.env
.env.example：E:\project\.env.example
.env 键 5 个，.env.example 键 5 个
缺失键（.env.example 有但 .env 没有，建议补充，共 1）：
1. NEW_RELIC_KEY（example 值：please-set）
多余键（.env 有但 .env.example 没有，可能已废弃，共 1）：
1. LEGACY_KEY（.env 值：old）
值不同（两文件都有但值不一致，共 1）：
1. API_KEY：.env=abc1…cret ｜ example=changeme
说明：仅比较键集合与值；大小写敏感，顺序不参与比较。敏感键值已脱敏。

参数：path（必填）；example（可选）；max_size；top（默认 20）；max_chars。

用户：我的 .env 跟 .env.example 比差了什么、多了什么

助手：调用 diff_env，path=.env，列出缺失 / 多余 / 值不一致

mask_env

完整展示 .env 内容，敏感键脱敏。path 传 .env 文件或目录；visible 控制脱敏保留的首尾字符数（默认 4，上限 8）。

文件：E:\project\.env；键 5 个（敏感键已脱敏）
APP_NAME=myapp
PORT=8080
API_KEY=abc1…cret（敏感）
DB_URL=postgres://localhost/db
LEGACY_KEY=old
说明：识别到敏感键 1 个并脱敏，绝不输出完整敏感值。

参数：path（必填）；max_size；visible（默认 4）；max_chars。

用户：把 .env 完整展示一遍，但密钥要打码

助手：调用 mask_env，path=.env，完整展示且敏感键脱敏

典型场景

• 环境配置一致性：上线前 diff_env 对比 .env 与 .env.example，确认没漏配、没残留废弃键。
• 安全查看配置：需要看 .env 内容但怕泄露时用 mask_env，敏感键自动打码。
• 排查环境差异：本地与 CI 配置不一致时，diff_env 快速定位缺失 / 多出的键。
• 新同事环境搭建：diff_env 告诉新成员缺哪些键、example 值是多少，照着补。
• 模板维护：.env.example 该更新哪些键，diff_env 的多余键提示能反向暴露。
• CI 门禁：对 .env.example 做语法检查，防止模板里混入真实密钥或残缺键。

安全边界

• 只读：三个工具都不写入、不修改、不删除文件；只读取 .env / .env.example 做文本解析。
• 脱敏为核心约束：敏感键（键名含 secret / token / password / passwd / api_key / access_key / private_key / auth / credential / client_secret / jwt / cipher 等）一律脱敏，只留首尾 4 位（可调 1~8）+ 长度，绝不输出完整值。
• 不访问网络：解析全部在本地完成，无任何外部请求，也不外发任何内容。
• 启发式解析，非权威：不做 shell 语义完整展开（不解析 $(...) 命令替换、变量展开、多行折叠）；敏感识别靠键名提示词，个别命名不规范的敏感键可能漏判。
• 限制规模：max_size 跳过超大文件，二进制文件不解析。

其他插件集成说明

协作插件	集成方式
dsh-credential-scan	dotenv-toolkit 管 .env 文件本身，credential-scan 扫描整个目录的密钥泄漏，内外互补
dsh-template-render	把 diff_env 的差异清单渲染成 Markdown 报告发给团队
dsh-env-inspector	dotenv-toolkit 看 .env 静态配置，env-inspector 看运行时 process.env，两视角对照
dsh-deps-audit	环境配置与依赖一起纳入上线前的完整性检查
dsh-chart-ascii	把各环境配置差异数量画成条形图，直观对比

版本说明

• 0.1.0（2026-10-10）：初始版本。
  • parse_env：解析 .env 为键值对，支持注释 / 空行 / export 前缀 / 单双引号 / 值内等号 / 行尾内联注释；敏感键自动脱敏
  • diff_env：对比 .env 与 .env.example，输出缺失键 / 多余键 / 值不一致；敏感值脱敏
  • mask_env：完整展示 .env 且敏感键脱敏，可调脱敏保留位数
  • 敏感识别：键名小写含 secret/token/password/api_key 等提示词；脱敏只留首尾 + 长度
  • 只读、二进制拒绝、大小上限

RoadMap

v0.2（计划）

• 增加 .env.local / .env.production 等多文件支持，按优先级分层展示
• 支持变量展开（${VAR}）与引用校验（引用了未定义键）
• 增加 check_env：校验必填键、类型提示（端口应为数字等）

v0.3（展望）

• 输出可选 format=json，便于脚本消费配置审计结果
• 增加与 Git 集成的差异提示（该键在最近提交中是否被改过）
• 支持更多敏感识别规则（自定义正则、熵值辅助判定）

FAQ

Q：怎么判断一个键是否敏感？ 键名小写后包含 secret / token / password / passwd / pass / api_key / apikey / access_key / private_key / auth / credential / client_secret / jwt / cipher / pwd 等提示词之一即视为敏感。对命名不规范的敏感键（如 ABC=xxx）可能漏判，可用 parse_env 的 mask=false 谨慎核对。

Q：脱敏后还能看出来什么？ maskValue 保留首尾各若干位（默认 4，可调）+ 总长度，如 abc1…cret（len=15）。这样能区分不同密钥、判断是否为空，但无法还原完整值。

Q：diff_env 的缺失 / 多余 / 值不同怎么理解？ 以 .env.example 为「标准模板」：缺失键 = example 有而 .env 没有（本地没配，建议补充）；多余键 = .env 有而 example 没有（模板没收录，可能已废弃或新加）；值不同 = 两文件都有但值不一致（通常正常，仅提示）。

Q：为什么不做 shell 语义完整展开？ 展开 $(cmd)、${VAR}、多行折叠属于 shell 语义，需要执行环境且可能触发命令，超出「只读、安全」边界。本插件只做静态 .env 子集解析，足够覆盖绝大多数配置管理场景。

Q：会执行 .env 里的内容吗？ 不会。只读文本解析，不 source、不 eval、不加载 .env 到进程环境，也不运行任何内容。

Q：.env 里有敏感值，我截图给同事看会不会泄露？ 用 mask_env 再展示：敏感键自动打码，只留首尾 + 长度，同事能看出配了哪些键、值是否为空，但看不到完整密钥。

源码与发布地址

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

许可证

MIT