AgentSkillsCN

env-guard

开发环境守卫。检测环境变化、诊断报错归属（环境 vs 代码）、适配终端差异。在命令失败、环境异常、需要环境信息时激活。

中文原作
SKILL.md
--- frontmatter
name: env-guard
description: 开发环境守卫。检测环境变化、诊断报错归属（环境 vs 代码）、适配终端差异。在命令失败、环境异常、需要环境信息时激活。
triggers:
  - 命令执行失败或报错
  - 报错信息包含环境相关关键词（EADDRINUSE、command not found、is not recognized 等）
  - 用户提到环境、终端、版本、端口等话题
  - 需要确认开发环境是否满足项目要求

env-guard — 开发环境守卫

你是什么

env-guard 是一个 PowerShell 7+ CLI 工具（env-guard.ps1），用于探测开发环境状态、对比快照变化、诊断报错是环境问题还是代码问题。

脚本位置（二选一）：

  • •项目根目录: ./env-guard.ps1
  • •全局安装: env-guard（已加入 PATH）

命令参考

powershell
# 显示当前环境
env-guard

# 保存 baseline 快照
env-guard -Save

# 对比当前环境和 baseline
env-guard -Diff

# 智能入口（无 baseline → Save，过期 → Diff，未过期 → 跳过）
env-guard -Auto

# 诊断报错归属
env-guard -Diagnose -ErrorMessage "完整的报错信息"

# 检查项目环境要求
env-guard -Check
env-guard -Check -Mode enforce
env-guard -Check -Mode adapt

# 端口健康检查
env-guard -ProcessCheck -Port 3000

流程一：开工

执行 env-guard -Auto 作为第一步操作。

  • •没有 baseline → 自动拍快照保存
  • •baseline 过期 → 自动对比并报告变化
  • •baseline 有效 → 跳过，零开销

如果报告了变化，先理解变化内容再开始任务。

流程二：命令失败时（核心流程）

严格按顺序执行：

第 1 步：诊断归属

powershell
env-guard -Diagnose -ErrorMessage "粘贴完整报错信息"

第 2 步：根据诊断结果分支

env 得分 > code 得分 → 环境问题：

powershell
env-guard -Diff

根据 Diff 结果修复环境（切版本、释放端口、设代理等），不改代码。

code 得分 > env 得分 → 代码问题： 正常 debug，修代码。

得分持平 → 不确定： 先跑 env-guard -Diff 排除环境因素，再决定。

第 3 步：绝不跳过诊断直接改代码

流程三：环境检查

确认环境是否满足项目要求：

  • •env-guard -Check — 按配置的默认模式检查
  • •env-guard -Check -Mode enforce — 不满足则阻止
  • •env-guard -Check -Mode adapt — 不满足则输出当前终端的兼容命令

流程四：端口/进程检查

确认服务是否存活：

powershell
env-guard -ProcessCheck -Port 3000

返回 JSON 格式的端口状态、占用进程、PID、健康状态。

命令映射

当终端类型变化时，使用 .env-guard.json 中 commands 字段的映射表。

在生成终端命令前，先确认当前终端类型。 示例映射：

操作pwshcmdbash
HTTP GETInvoke-RestMethod -Uri $URLcurl -s $URLcurl -s $URL
删除文件夹Remove-Item -Recurse -Force $PATHrmdir /s /q $PATHrm -rf $PATH
杀端口Get-Process ... | Stop-Processnetstat + taskkillkill -9 $(lsof -t -i:$PORT)

诊断速查

报错关键词归属典型动作
is not recognized as环境检查 PATH、工具安装
command not found环境检查 PATH、工具安装
EADDRINUSE环境释放端口
EACCES / permission denied环境检查权限
scripts is disabled环境设置执行策略
ETIMEDOUT / ECONNREFUSED环境检查代理、网络
SyntaxError代码修代码
TypeError代码修代码
is not a function代码修代码
ReferenceError代码修代码
Cannot find module两栖先检查 node_modules 是否存在

相关文件

文件用途
.env-guard.json项目环境要求、命令映射、错误模式配置
.env-baseline.json环境快照（自动生成，已加入 .gitignore）
env-guard.ps1CLI 工具本体