environment-awareness

环境感知

概述

AI Agent 最常见的失败情形：在 Windows 上运行 Linux 命令、项目使用 pnpm 却运行 npm、忽略已激活的虚拟环境。每条错误命令都会浪费时间，还可能造成实际损害。

**核心原则：**运行任何 shell 命令之前，都要先检测环境。现在探测一次，可以避免之后十次命令失败。

没有例外。没有变通方法。没有捷径。

首要准则

NO SHELL COMMANDS WITHOUT KNOWING THE TARGET ENVIRONMENT

如果尚未确认操作系统、shell 和包管理器，就无权运行命令。

适用时机

每次会话开始时必须执行：

• 在任何新对话中的首次交互
• 切换到不同的项目或代码仓库
• 进入容器、虚拟机或远程机器后

以下情况也必须执行：

• 命令因“找不到”或“无法识别”而失败
• 安装依赖或运行构建脚本
• 编写特定于平台的代码（文件路径、进程管理、网络）
• 诊断“在我的机器上能运行”的问题

以下情况也不要跳过：

• 你认为自己已经了解环境时（务必验证，不要假设）
• 用户随口提到其操作系统时（也要确认 shell 和工具链）
• 在 CI/CD 中工作时（运行器的环境与本地机器不同）

入口流程

BEFORE running any shell command:

1. PLATFORM: Have you confirmed OS and architecture?
2. SHELL: Do you know which shell is interpreting your commands?
3. PACKAGE MANAGER: Have you checked for lockfiles?
4. RUNTIMES: Do you know which language runtimes are available?
5. VIRTUAL ENV: Are there active virtual environments or version managers?

If any answer is NO: probe first, command second.

检测流程图

digraph env_detect {
    rankdir=TB;
    node [shape=box, style=filled, fillcolor="#e8e8e8"];

    start [label="Session Start", shape=oval, fillcolor="#ccffcc"];
    os [label="1. Detect OS\nprocess.platform\nor uname", shape=diamond, fillcolor="#ffffcc"];
    shell [label="2. Detect Shell\n$SHELL / $PSVersionTable\n/ COMSPEC", shape=diamond, fillcolor="#ffffcc"];
    pkg [label="3. Detect Package Manager\nCheck lockfiles\nin project root", shape=diamond, fillcolor="#ffffcc"];
    runtime [label="4. Detect Runtimes\nnode/python/go\n--version", shape=diamond, fillcolor="#ffffcc"];
    venv [label="5. Check Virtual Envs\nVIRTUAL_ENV / CONDA\nnvm / rbenv", shape=diamond, fillcolor="#ffffcc"];
    container [label="6. Container Check\n/.dockerenv\nor cgroup", shape=diamond, fillcolor="#ffffcc"];
    ready [label="Environment Known\nProceed with\ncorrect commands", shape=oval, fillcolor="#ccffcc"];

    start -> os -> shell -> pkg -> runtime -> venv -> container -> ready;
}

检测清单

每次会话运行一次此流程。检测结果将为之后的每条命令提供依据。

1. 操作系统

方法	适用环境	命令
环境变量	Claude Code / Node	在工具上下文中检查 process.platform
uname	Linux、macOS、Git Bash	uname -s
系统信息	Windows（任意 shell）	systeminfo 或 ver

主要区别：

• win32 = Windows（无论是 32 位还是 64 位）
• darwin = macOS
• linux = Linux 或 WSL（使用 grep -i microsoft /proc/version 进一步检查是否为 WSL）

2. Shell

**切勿假设是 bash。**仅 Windows 就有 CMD、PowerShell、Git Bash 和 WSL。

检查项	命令	可获取的信息
Shell 变量	echo $SHELL	默认 shell（Unix）
PowerShell 检查	$PSVersionTable	PowerShell 版本
进程名称	echo $0	当前 shell（Unix）
COMSPEC	echo %COMSPEC%	CMD 路径（Windows）

**重要：**在 Windows 上，Claude Code / AI Agent 的 shell 上下文通常是 Git Bash，但用户的终端可能是 PowerShell。生成供用户复制的命令时，必须与用户使用的 shell 相匹配。

3. 包管理器

检测优先级——先检查锁文件：

锁文件	包管理器
bun.lockb 或 bun.lock	bun
pnpm-lock.yaml	pnpm
yarn.lock	yarn
package-lock.json	npm

如果没有找到锁文件：

1. 检查 package.json 中的 packageManager 字段
2. 检查是否全局安装：which pnpm || which yarn || which bun
3. 仅在万不得已时才默认使用 npm

对于非 JS 项目：

文件	管理器
Pipfile.lock	pipenv
poetry.lock	poetry
uv.lock	uv
requirements.txt	pip
go.sum	go modules
Cargo.lock	cargo
Gemfile.lock	bundler

4. 运行时版本

首次使用时再探测，不要提前检查。只检查项目实际需要的内容。

node --version      # Node.js
python3 --version   # Python (use python3, not python, on macOS/Linux)
go version          # Go
rustc --version     # Rust
java --version      # Java
ruby --version      # Ruby

5. 虚拟环境

信号	表示
$VIRTUAL_ENV 已设置	Python venv/virtualenv 已激活
$CONDA_DEFAULT_ENV 已设置	Conda 环境已激活
.python-version 文件	已固定 pyenv 版本
.nvmrc 或 .node-version 文件	已固定 Node 版本
.ruby-version 文件	已固定 rbenv/rvm 版本
.tool-versions 文件	使用 asdf 版本管理器

**检测到版本管理器时：**使用其命令（nvm use、pyenv shell），不要假设全局运行时版本正确。

6. 容器检测

检查	是否在容器内？
/.dockerenv 存在	Docker
grep -q container /proc/1/cgroup 2>/dev/null	Docker/Podman
已设置 $container 环境变量	Podman
printenv KUBERNETES_SERVICE_HOST	Kubernetes pod

系统清单

确认平台和 shell 后，检查用户已安装的工具、数据库、云 CLI 和服务。该清单会直接用于规划——如果用户安装了 SQLite，但没有 PostgreSQL，或者有 Docker，但没有 Podman，下游技能（例如 deployment-advisor 和 task-planning）就能据此给出更明智的建议，而不是靠猜测。

何时运行

• 始终： Git、GitHub CLI（许多 GodMode 技能都需要）
• 如果项目涉及数据： 数据库 CLI
• 如果项目要部署： 云和容器工具
• 如果项目要处理媒体或结构化数据： ffmpeg、jq、curl
• 切勿盲目运行完整清单。 根据项目类型选择检查项。静态网站不需要探测 MongoDB。

清单检查项

静默运行每项相关检查，并重定向 stderr，以免缺失工具产生噪声：

数据库：

工具	检查	备注
PostgreSQL	psql --version 2>/dev/null	如果备份很重要，也检查 pg_dump
MySQL / MariaDB	mysql --version 2>/dev/null	MariaDB 会在版本字符串中标明自身
SQLite	sqlite3 --version 2>/dev/null	macOS 和 Linux 通常会预装
MongoDB	mongod --version 2>/dev/null	现代 shell 还需检查 mongosh
Redis	redis-server --version 2>/dev/null	还需检查 redis-cli

云和托管 CLI：

工具	检查
AWS CLI	aws --version 2>/dev/null
Google Cloud	gcloud --version 2>/dev/null
Azure CLI	az --version 2>/dev/null
Vercel	vercel --version 2>/dev/null
Supabase	supabase --version 2>/dev/null
Fly.io	fly version 2>/dev/null
Netlify	netlify --version 2>/dev/null
Railway	railway --version 2>/dev/null

容器工具：

工具	检查
Docker	docker --version 2>/dev/null
Docker Compose	docker compose version 2>/dev/null
Podman	podman --version 2>/dev/null

开发者工具：

工具	检查
Git	git --version 2>/dev/null
GitHub CLI	gh --version 2>/dev/null
curl	curl --version 2>/dev/null
jq	jq --version 2>/dev/null
ffmpeg	ffmpeg -version 2>/dev/null

报告格式

简洁地报告结果。不要直接输出原始版本信息，而应提取版本号并进行概述：

Available: PostgreSQL 16.2, Docker 27.1, gh 2.45, SQLite 3.43
Not found: Redis, AWS CLI, Podman

原则

1. 静默处理错误并强制退出码为 0。 始终将 stderr 重定向到 /dev/null，并在串联的版本检查末尾追加 ; true。缺失工具会返回非零退出码，在 Claude Code 中显示为红色错误。工具缺失是一条信息，而非失败——输出绝不能显示红色。

   # WRONG: last missing tool causes exit 127 (red error in Claude Code)
   psql --version 2>/dev/null; redis-server --version 2>/dev/null; mongod --version 2>/dev/null
   
   # RIGHT: force clean exit regardless of which tools are missing
   psql --version 2>/dev/null; redis-server --version 2>/dev/null; mongod --version 2>/dev/null; true
   

2. 限定项目范围。 只检查与代码库相关的类别。查看项目配置文件、Dockerfile、CI 配置或部署清单，以判断哪些内容与项目相关。
3. 检查一次，反复引用。 将结果保存在工作上下文中。除非用户安装了新工具，否则不要在会话中途重新探测。
4. 为下游技能提供信息。 清单会直接帮助 deployment-advisor 判断（可以部署到哪里？）、帮助 task-planning 识别（有哪些限制？），并帮助 project-bootstrap 确定（需要安装什么？）。

特定平台的命令映射

请根据检测到的环境使用正确的命令：

操作	Linux/macOS	Windows CMD	Windows PowerShell	Windows 上的 Git Bash
列出文件	ls -la	dir	Get-ChildItem	ls -la
查找进程	ps aux | grep	tasklist	Get-Process	ps aux | grep
设置环境变量	export VAR=val	set VAR=val	$env:VAR = "val"	export VAR=val
空设备	/dev/null	NUL	$null	/dev/null
路径分隔符	:	;	;	:
删除文件	rm file	del file	Remove-Item file	rm file
查找文件	find . -name	dir /s /b	Get-ChildItem -Recurse	find . -name
检查端口	lsof -i :PORT	netstat -an	Get-NetTCPConnection	netstat -an

何时探测，何时假定

类别	操作	原因
操作系统	始终探测	会影响每条命令的语法
Shell	始终探测	决定引号、管道和重定向的用法
包管理器	始终探测	使用错误的包管理器会破坏锁文件
运行时版本	首次使用时探测	只有运行该运行时时才有影响
虚拟环境	相关时探测	环境错误会导致安装到错误位置
容器	行为异常时探测	容器缺少许多主机工具

认知陷阱

自我安慰	实际情况
“大概是 Linux”	30% 的开发者使用 Windows，另有 25% 使用 macOS。先探测。
“bash 是通用的”	Windows CMD 和 PowerShell 的语法有本质区别。Git Bash 确实存在，但不一定可用。
“npm 是默认选择”	在 pnpm 项目中使用 npm 会破坏锁文件并导致 CI 失败。
“命令失败了再修就行”	路径语法错误的 rm -rf 仍可能删除数据。安装失败也会留下损坏的状态。
“用户说是 Windows，所以就是 PowerShell”	也可能是 CMD、Git Bash、WSL 或 Cygwin。要确认 Shell，而不只是操作系统。
“CI 和本地环境一样”	CI 运行器使用不同的操作系统、Shell 和工具版本。也要在那里进行探测。

防护措施——暂停并检测

如果发现自己正在做以下事情，请停下来：

• 不确定 Shell 是否支持 ls，就运行 ls
• 未确认是类 Unix Shell，就使用 /dev/null
• 未检查是否存在其他锁文件，就运行 npm install
• 未检查版本，就使用 python 而非 python3
• 假定 ~ 会正确展开（它在 CMD 中不会展开）
• 未确认操作系统，就使用 / 编写路径字符串
• 未确认是 GNU 还是 BSD，就使用 grep 标志
• 不确定 Shell 是否支持 |，就使用管道连接命令

此列表中的每一项都意味着：暂停执行命令。先探测。

集成

互补技能：

• godmode:project-bootstrap —— 项目设置期间会运行环境检测
• godmode:fault-diagnosis —— 环境不匹配是导致神秘故障的常见根因
• godmode:workspace-isolation —— Worktree 和容器设置需要使用正确的平台命令
• godmode:deployment-advisor —— 系统清单结果可直接用于部署建议和平台选择

归根结底

One detection probe now > ten failed commands later

先了解操作系统、Shell 和包管理器，再执行第一条命令。每一次会话都如此。