Env Doctor

env-doctor · 环境与全局包体检、账本与安装纪律

本机装了大量自带运行时的 agent 应用（Hermes、Deck、Wukong、Eigent……），加上 nvm / uv / pipx / brew / bun 多套包管理器并存，摩擦全部出现在接缝处：谁排 PATH 前面、 node/python 归谁、全局包装进哪个 prefix、哪个链接死了。本 skill 用「确定性体检 + 账本 + 安装纪律」把地质层变成可查账的：脏了立刻可见，每次变更有据可查。 （心智模型同 brew doctor / npm doctor：环境医生。）

硬纪律（所有 agent 必须遵守，先于任何环境写操作）

1. 全局安装只走白名单落点，装完必须记账（record 子命令，一条命令的事）：
   • Node 包：npm i -g，且 npm 必须是 nvm 当前默认版本 的（用 npm prefix -g 核对，不是则先停下报告）；
   • Python CLI：uv tool install（或 pipx install），不要 pip install --user 手装 CLI；
   • 系统依赖：brew install；
   • bun 全局尽量少用，装了必记账。
2. 三类操作默认禁止，除非用户当次明示授权且完成后立即记账：修改 shell rc 文件 （~/.zshenv / ~/.zprofile / ~/.zshrc / ~/.profile）；注册 LaunchAgent 或 cron；在 ~/.local/bin 新增或改指 node/npm/npx/python 等运行时垫片。
3. ~/.local/bin 是全机唯一垫片层：这里的 node/npm/npx 链接决定所有 shell（包括 launchd 拉起的干净 shell）的默认运行时。只允许跟随 nvm default 重指，且必须记账。
4. 厂商应用升级后先体检：跑一次 env-doctor.sh，若报 🚨（垫片漂移，多为 Hermes 等把 node 链接抢回自家），只报告用户，不擅自改回——那可能是该应用有意的依赖。
5. 判断运行时/包的归属看链接与 prefix，不看表面：which -a node + readlink 读 出真实目标，npm prefix -g / pip -V 看真实落点；版本号一致不代表是同一个 node（本机曾有 4 个并存、pip 有 user/brew/uv 多套）。

体检（确定性检测）

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 "说明"  # 记账

输出八段：① node/npm/npx 垫片归属比对（✅/🚨）＋nvm 版本目录健康扫描（0 字节损坏）与垫片半迁移告警 ② PATH 实际解析与解释器版图（agent 壳 PATH 缺垫片层时显式提示；node 与 python3 全量清单）③ 各包管理器与全局落点（npm 全局清单 / uv tools / pipx / pip --user / bun / brew leaves 与 services / cron 概览）④ 缓存体积（npm/bun/uv/pip/ brew）⑤ ~/.local/bin 全部符号链接与死链 ⑥ LaunchAgents 与 cron 明细 ⑦ 账本尾部 ⑧ 环境漂移对照——rc 文件哈希与 LaunchAgents 名单 diff 上次 snapshot 基线，报 🚨新增/变更、ℹ️消失。 退出码：0 正常；2 检测到垫片漂移（见 🚨 标记）；3 无法解析 nvm 默认、未验证。 第 8 节环境面漂移只报告不计入退出码（见 DECISIONS D7）。agent 巡检以退出码为准； full 模式额外报告 brew 过时包清单。变更确认合法后重跑 snapshot 重立基线并记账。

记账

账本在 ~/.config/env-ledger.md（纯文本，随写随追加），每行一条： - 日期 时间 — 谁做了什么、如何回滚。环境被谁动过、怎么还原，查这里，不做考古。 任何全局安装/卸载、垫片改指、rc 修改、LaunchAgent 增删，都要有一行。

已知基线

机器现状（4 个 node 的分布、各包管理器落点、Hermes 自管边界、历史修复与回滚命令） 见 references/known-baseline.md。基线漂移时更新该 文件并记账。

依赖

无外部硬依赖：bash 3.2+ 与 macOS 标准命令；npm/uv/pipx/brew 缺失时对应段自动降级。

部署

~/.agents/skills/env-doctor → 本目录（符号链接），跨 agent 生效。