env-doctor

env-doctor · Environment and global package checkup, ledger, and installation discipline

This machine has many agent applications that bundle their own runtimes (Hermes, Deck, Wukong, Eigent……), plus multiple package managers coexisting — nvm / uv / pipx / brew / bun — and all the friction shows up at the seams: who comes first in PATH, who owns node/python, which prefix global packages land in, which link is dead. This skill uses "deterministic checkup + ledger + installation discipline" to turn the geological layers into something auditable: when something gets dirty it is immediately visible, and every change has a paper trail. (The mental model is the same as brew doctor / npm doctor: environment doctor.)

Hard discipline (all agents must follow, before any environment write operation)

1. Global installs only go to whitelisted locations, and after installing you must record it in the ledger（record subcommand, it's a one-command affair):
   • Node packages:npm i -g, and npm must be that of the current nvm default version (use npm prefix -g to verify; if not, stop first and report);
   • Python CLI：uv tool install(or pipx install），do not pip install --user hand-install CLIs;
   • System dependencies:brew install；
   • bun global should be used as little as possible; if installed, it must be recorded in the ledger.
2. Three types of operations are prohibited by default, unless the user explicitly authorizes it for that occasion and it is recorded in the ledger immediately after completion: modifying shell rc files (~/.zshenv / ~/.zprofile / ~/.zshrc / ~/.profile); registering LaunchAgents or cron; adding or repointing runtime shims such as node/npm/npx/python in ~/.local/bin .
3. ~/.local/bin is the machine's only shim layer: the node/npm/npx links here determine the default runtime for all shells (including clean shells launched by launchd). Repointing is only allowed to follow the nvm default, and it must be recorded in the ledger.
4. After upgrading vendor applications, run a checkup first: run env-doctor.sh; if it reports 🚨 (shim drift, usually because Hermes and the like have grabbed the node link back for themselves),only report to the user, do not change it back on your own—that may be a deliberate dependency of that application.
5. To determine the ownership of a runtime/package, look at links and prefixes, not appearances：which -a node + readlink to read the real target,npm prefix -g / pip -V to see the real landing point; matching version numbers do not mean it is the same node (this machine once had 4 coexisting, and pip had multiple sets: user/brew/uv).

Checkup (deterministic detection)

bash "<本skill目录>/scripts/env-doctor.sh"               # 快速体检（本地信息，秒级）
bash "<本skill目录>/scripts/env-doctor.sh" full          # 深度体检（追加 brew outdated，需网络）
bash "<本skill目录>/scripts/env-doctor.sh" snapshot      # 立漂移基线（rc 哈希 + LaunchAgents 名单）
bash "<本skill目录>/scripts/env-doctor.sh" record "说明"  # 记账

Output eight sections: ① node/npm/npx shim ownership comparison (✅/🚨) ② Actual PATH resolution and interpreter landscape (full list of node and python3) ③ Each package manager and global landing points (npm global list / uv tools / pipx / pip --user / bun / brew leaves and services / cron overview) ④ Cache sizes (npm/bun/uv/pip/ brew) ⑤ ~/.local/bin all symlinks and dead links ⑥ LaunchAgents and cron details ⑦ Ledger tail ⑧ Environment drift comparison—rc file hashes and LaunchAgents list diffed against the last snapshot baseline, reporting 🚨added/changed, ℹ️disappeared. Exit codes:0 normal;2 shim drift detected (see 🚨 marker);3 unable to resolve nvm default, unverified. Section 8 environment-surface drift is only reported and not counted in the exit code (see DECISIONS D7). Agent inspections go by exit code; full mode additionally reports the list of outdated brew packages. After confirming the changes are legitimate, rerun snapshot to re-establish the baseline and keep the ledger.

Ledger

The ledger is at ~/.config/env-ledger.md(plain text, appended as you go), one entry per line: - 日期 时间 — 谁做了什么、如何回滚. Who touched the environment and how to restore it—check here, no archaeology. Any global install/uninstall, shim retargeting, rc modification, or LaunchAgent addition/removal must have a line.

Known baseline

Current machine state (the distribution of the 4 node instances, where each package manager lands, Hermes self-management boundaries, historical fix and rollback commands) see references/known-baseline.md. When the baseline drifts, update that file and keep the ledger.

Dependencies

No external hard dependencies: bash 3.2+ and standard macOS commands; when npm/uv/pipx/brew are missing, the corresponding sections automatically degrade.

Deployment

~/.agents/skills/env-doctor → this directory (symlink), effective across agents.