envspeak

EnvSpeak

MCP 服务和命令行工具，可解析 .env 文件、Docker Compose 与 Kubernetes 中的配置／环境变量级联——告诉 AI Agent（以及你）变量在运行时的实际取值，以及原因。

这与 CSS 级联的问题模式相同：多个来源、并不直观的优先级规则，以及一个值仅仅因为定义位置而“胜出”——只是应用于应用配置，而不是样式表。stylesafe 和 stylespeak 是同类项目，用于处理 CSS。

问题

真实应用的配置可能来自 .env、.env.local、.env.production、docker-compose.yml（environment: 与 env_file:）、Kubernetes ConfigMap／Secret 对象，以及代码中的硬编码回退值——超过 5 个层级，每一层都有自己的优先级规则，而这些规则组合起来的结果并不像你猜测的那样。最常见的陷阱是：普通的 .env.local 会覆盖 .env.production，除非你也有 .env.production.local——因为在常见的 dotenv 级联中，“本地”优先级高于“特定环境”。编辑配置的 Agent 无从得知变量实际会解析为什么值，也不知道更改某一层会造成什么影响。

工具

• resolve_variable —— DATABASE_URL 实际会解析为什么值，哪个文件优先？
• trace_variable —— 列出此变量在所有领域和环境中的每一处设置。
• impact_preview —— 如果我在这个文件中更改此值，下游会发生什么变化？哪些内容会被更高优先级的设置屏蔽？
• config_manifest —— 压缩后的全项目摘要：每个变量、其来源以及风险热点（存放在受版本控制文件中的密钥、代码中读取但没有回退值且没有任何来源的变量）。
• diff_environments —— 在两种环境／服务／工作负载下解析每个变量，查看它们的实际差异。

安装

npm install -g @patrizzos/envspeak

作为 MCP 服务

{
  "mcpServers": {
    "envspeak": {
      "command": "envspeak"
    }
  }
}

作为命令行工具

envspeak resolve DATABASE_URL --environment production
envspeak trace LOG_LEVEL
envspeak impact --file .env --variable LOG_LEVEL --newValue debug
envspeak manifest
envspeak diff --a '{"nodeEnv":"development"}' --b '{"nodeEnv":"production"}'

如果省略 --files，envspeak 会在 --projectRoot 下（默认为当前目录）自动发现 .env*、Compose 和 Kubernetes 清单文件。使用 --files a,b,c 可明确限定范围——推荐用于 MCP 调用，以便 Agent 精确控制读取的内容。

编码的优先级约定

dotenv（Next.js/Vite 风格，事实上的标准）：process.env（Shell）> .env.[env].local > .env.local > .env.[env] > .env > 代码回退值（process.env.X || 'default'）。注意，.env.local 的优先级高于 .env.[env]——这就是上文提到的陷阱。

Docker Compose：docker compose run -e（命令行）> environment: > env_file:（冲突时列表中的最后一个文件优先）> Dockerfile ENV（不分析）。

Kubernetes：内联 env: 始终覆盖 envFrom:（批量导入 ConfigMap／Secret；在这些条目中，列表中的最后一项优先）。环境变量值会在 Pod 启动时固定——编辑被引用的 ConfigMap／Secret 不会影响正在运行的 Pod，除非重启或执行滚动更新。impact_preview 会标记这一点。

每个结果都包含一个 confidence 级别和一条 caveat 字符串，因为 Shell 导出的覆盖值或通过命令行传入的覆盖值始终可能存在，而且静态分析无法看到——envspeak 会明确说明这一点，而不会假装自己拥有并不存在的确定性。

安全

• 零运行时依赖。 用于解析 Compose/Kubernetes 文件的 YAML 子集解析器是手写的，而非从 npm 引入，因此不存在第三方供应链风险面。npm audit 从设计上就不会发现问题。
• 防范路径遍历。 文件读取会基于 projectRoot 解析路径，并拒绝访问其范围之外的文件，即使工具调用传入了精心构造的相对路径也不例外。
• 防范原型污染。 从 YAML 内容中解析出的对象键（__proto__、constructor、prototype）绝不会用于属性赋值。
• 默认对机密信息脱敏。 Kubernetes Secret 值只会显示为 ab***yz，绝不会显示完整内容，无论是通过哪个工具获取。
• 机密信息可能性启发式检测。 变量名和取值形式（AWS 密钥、GitHub 令牌、PEM 块、高熵凭据形式的字符串）会被标记、与 .gitignore 进行交叉比对，并作为 secretFlag / 风险热点呈现，而非在未经提示的情况下直接传递。
• 有界且不回溯的正则表达式。 用于扫描代码默认值的模式匹配会限制匹配长度，并避免嵌套量词，以防在大型文件上触发 ReDoS。
• 无论这些防护如何运作，envspeak 都会读取你指定的任何文件——请限制 Agent 可传入的 files 列表，就像限制任何具有文件系统访问权限的工具一样。

开发

npm test   # zero dependencies — no install step needed

许可证

MIT