1. 环境资产盘点为什么总在出事后才想起你有没有过这种时刻新项目要复现一个半年前跑通的脚本pip install报了一堆版本冲突你盯着pip list里 90 多个包完全想不起来当初是哪个版本配哪个库。或者同事问你「你本地 Claude Code 那个 Skill 装哪了」你翻遍~/.claude、项目根目录、甚至回收站最后发现它藏在某个早就忘了的.claude/skills子目录里。这类问题的本质不是「你不会管理环境」而是环境状态从来没有被记录过。pip 有pip listnpm 有npm ls -g但它们各说各话互不认识AI Agent 工具Claude Code、OpenClaw、Codex、Cursor的 Skills 和 Rules 目录更是散落在用户主目录和各个项目文件夹里没有任何统一入口。你装了什么、装在哪、是全局还是项目级、什么时候装的——全靠记忆。我试过用pip freeze requirements.txt来记账但那只覆盖 Python 包npm 全局包和 AI Agent 配置完全漏掉。也试过手动维护一个 Markdown 清单坚持了不到两周就放弃了因为每次装新东西都要手动更新太反人性。env-recorder 就是冲着这个场景写的一个 Python 脚本跑一次把 pip 包、npm 全局包、四大 AI Agent 的 Skills/Rules 全部扫出来存成带时间戳的快照还能用--diff对比两次快照的差异。它不解决依赖冲突也不做自动化安装只回答一个问题这台电脑上到底装了什么。适合谁用经常折腾 AI 编程工具、同时维护多个 Python/Node 项目、或者需要在新机器上快速重建环境的开发者。下面我把安装、配置、扫描范围、diff 对比和常见报错全部拆开讲你可以直接跟着操作。2. 前置准备Python 环境与 env-recorder 获取env-recorder 本身是一个 Python 脚本所以第一步是确认你的机器上有可用的 Python 解释器。它不依赖任何第三方库标准库就能跑这一点对「环境已经乱到不敢乱装包」的人来说很友好——你不需要先pip install一堆东西才能用它。先检查 Python 版本。打开终端Windows 用 PowerShell 或 CMDmacOS/Linux 用默认终端执行python --version如果输出Python 3.8及以上即可。如果提示command not found试试python3 --version。Windows 上如果两个都没有需要先去 python.org 下载安装包安装时勾选「Add Python to PATH」。这一步是基础不展开。确认 Python 可用后获取 env-recorder。它托管在 GitHub 上直接 clonegit clone https://github.com/mixuecoding/env-recorder.git cd env-recorder如果你没有 git也可以直接在 GitHub 页面点「Code」→「Download ZIP」解压后进入目录。目录结构很简单核心就是record_env.py一个文件加上一个用于网页查看器的静态资源文件夹。这里有个前置认知需要说清楚env-recorder 扫描的是当前用户的环境包括全局 pip 包、全局 npm 包、以及用户主目录下的 AI Agent 配置目录。它不会去扫描系统级安装的包比如/usr/lib/python3下的系统包也不会修改任何东西纯读取。所以你可以放心跑不会把环境搞坏。另外如果你同时用多个 Python 虚拟环境env-recorder 默认扫描的是当前激活的 Python 解释器对应的 pip 包。也就是说你先source venv/bin/activate再跑脚本它记录的就是这个 venv 里的包不激活就直接跑记录的是全局 Python 的包。这个行为在后面的扫描范围配置里会再展开。npm 部分需要你的机器上装了 Node.js 和 npm。检查npm --version有版本号输出即可。如果 npm 没装env-recorder 会跳过 npm 扫描并在输出里提示不会报错中断。AI Agent 部分则是纯文件系统扫描不依赖对应工具是否安装只要目录存在就能识别。3. 可复制配置扫描范围与运行参数env-recorder 的设计是「零配置也能跑但你可以用参数精细控制扫描范围」。先看最基础的运行方式python record_env.py这条命令会做四件事扫描 pip 包、扫描 npm 全局包、扫描 AI Agent 的 Skills/Rules 目录、把结果存成一份带时间戳的快照。输出大概长这样AI Agents: 24 个 Claude Code 全局 (2): agent-reach, anysearch OpenClaw 全局 (2): agent-reach, khazix-skills-main Codex 全局 (1): .system Codex Rules 全局 (1): default.rules Claude Code [AiTools] (17): animejs, gsap, hyperframes... Claude Code [Test] (1): wechat-writing Pip: 89 个 (89 全局 0 项目) npm: 10 个 (10 全局 0 项目)如果你想把扫描范围固定下来避免每次手动传参可以在项目目录下建一个配置文件。env-recorder 支持读取同目录下的env_recorder.toml格式如下[scan] # 是否扫描 pip 包 pip true # 是否扫描 npm 全局包 npm true # 是否扫描 AI Agent 配置 agents true [agents] # 要扫描的 Agent 类型可多选 targets [claude, openclaw, codex, cursor] # 额外要扫描的项目目录会递归查找 .claude/skills 等 project_dirs [/Users/yourname/projects, /Users/yourname/work] [snapshot] # 保留最近多少条快照 keep 50 # 快照存储目录 dir ./snapshots这个 TOML 文件里几个关键点project_dirs是你希望 env-recorder 去递归查找项目级 Skills 的根目录。比如你把所有项目放在~/projects下就填这个路径它会自动找到~/projects/foo/.claude/skills这类目录。keep 50表示只保留最近 50 条快照超出的自动清理避免快照目录无限膨胀。如果你不想用 TOML也可以用命令行参数临时覆盖python record_env.py --no-npm --agents claude,codex --project-dirs ~/projects常用参数对照如下参数作用示例--no-pip跳过 pip 扫描python record_env.py --no-pip--no-npm跳过 npm 扫描python record_env.py --no-npm--agents指定扫描的 Agent--agents claude,openclaw--project-dirs指定项目根目录--project-dirs ~/work,~/side--diff对比最近两次快照python record_env.py --diff--web启动网页查看器python record_env.py --web--keep保留快照数量--keep 100这里要提醒一个容易踩的点--project-dirs传多个路径时用逗号分隔不要用空格。空格会被 shell 拆成多个参数导致解析错误。另外路径里如果有空格比如 Windows 的C:\Users\My Name\projects需要用引号包起来。配置好之后建议把「跑一次 env-recorder」加进你的日常习惯每次pip install完新包、或者在 Claude Code 里加了新 Skill就跑一下python record_env.py。这样快照序列本身就是一部环境变更史。4. 验证请求跑一次扫描并 diff 两台机器配置就绪后先跑一次完整扫描确认输出符合预期python record_env.py如果一切正常你会看到类似第 3 节里的分类输出并且在./snapshots目录下生成一个 JSON 文件文件名带时间戳比如snapshot_20250612_143022.json。打开这个 JSON结构大致是{ timestamp: 2025-06-12T14:30:22, pip: { global: [{name: requests, version: 2.31.0}, ...], project: [] }, npm: { global: [{name: claude-code, version: 1.2.3}, ...] }, agents: { claude: {global: [agent-reach, anysearch], projects: {...}}, openclaw: {global: [agent-reach, khazix-skills-main]}, codex: {global: [.system], rules: [default.rules]} } }这个 JSON 就是「环境快照」的原始数据。你可以把它提交到 git 仓库或者同步到网盘作为环境备份。接下来验证 diff 功能。先手动装一个包制造变化pip install cowsay然后再跑一次扫描python record_env.py现在快照目录里有两份 JSON 了。执行 diffpython record_env.py --diff输出会明确告诉你两次快照之间多了什么、少了什么、什么升级了对比: snapshot_20250612_143022.json - snapshot_20250612_144510.json Pip 新增: cowsay6.1 npm 无变化 Agents 无变化这个 diff 能力在「两台机器环境对比」场景下特别有用。假设你有一台旧笔记本和一台新台式机想把旧机器的环境复刻到新机器上操作流程是在旧机器上跑python record_env.py把生成的 JSON 拷到新机器在新机器上也跑一次然后用 diff 对比两份快照。差异部分就是你需要在新机器上补装的东西。如果你想把 diff 结果导出成文件方便分享可以重定向输出python record_env.py --diff env_diff.txt网页查看器也值得一试。执行python record_env.py --web它会在本地起一个 HTTP 服务默认端口 8080浏览器打开http://localhost:8080就能看到图形化界面支持搜索包名、按类型筛选、可视化对比两次快照。89 个 pip 包在终端里滚屏很痛苦网页里搜索框一敲就定位到了。这个查看器是纯本地运行的数据不出机器。5. 常见报错排查401、local proxy failed、reading choices、OAuthenv-recorder 本身不涉及网络请求和鉴权所以它不会报 401 或 OAuth 错误。但你在用它盘点环境时很可能会顺带排查其他工具的问题。下面这几类报错是实际使用中高频出现的我按「报错原文 → 原因 → 解决」的结构列出来。报错一npm: command not found或FileNotFoundError: [WinError 2]这是 Windows 上最典型的坑。npm 在 Windows 上实际是npm.cmd文件Python 的subprocess直接调npm会找不到可执行文件。env-recorder 内部已经做了处理它会先探测 Node.js 安装路径然后优先调用npm.cmd。如果你仍然遇到这个报错说明 Node.js 没装或者没在 PATH 里。解决方式是重新安装 Node.js 并确保勾选「Add to PATH」或者手动在 TOML 里指定 npm 路径[npm] binary C:/Program Files/nodejs/npm.cmd报错二local proxy failed或connection refused这个报错通常出现在你跑其他 AI 工具比如 Claude Code、Codex时而不是 env-recorder 本身。原因是这些工具需要访问模型 API而你的网络配置或代理设置有问题。排查顺序先确认curl https://taotoken.net/api能否通注意这是 API 地址不带 UTM如果不通检查你的网络环境。如果通但工具仍报错检查工具自己的配置文件里 Base URL 是否写对。以 Claude Code 为例它的配置在~/.claude/settings.json需要确保ANTHROPIC_BASE_URL指向正确的地址。这里不展开代理配置细节只提醒一点env-recorder 扫描的是文件系统不碰网络所以它跑不通和 API 连不上是两码事别混在一起排查。报错三reading choices或invalid response format这类报错一般出现在调用模型 API 时返回的 JSON 结构不符合预期。常见原因是 Base URL 配错了请求打到了错误的端点。比如你把https://taotoken.net/api写成了https://taotoken.net/api/v1/chat之类的错误路径。正确的做法是只填 Base URL让 SDK 自己拼接路径。以 OpenAI 兼容的 SDK 为例from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_key你的Key )注意base_url结尾不要多加/v1除非文档明确要求。很多「reading choices」报错都是因为路径重复拼接导致的。报错四OAuth token expired或authentication failed如果你在用 Codex 或 Claude Code 的 OAuth 登录方式token 过期后会报这个。解决方式是重新登录或者改用 API Key 方式。以 Codex 为例它的鉴权信息存在~/.codex/auth.json结构大致是{ OPENAI_API_KEY: sk-..., base_url: https://taotoken.net/api }如果你要切换到 API Key 方式把auth.json里的OPENAI_API_KEY换成你的 Keybase_url指向https://taotoken.net/api即可。改完后跑一次python record_env.py快照里会记录这个配置文件的状态方便你回溯「什么时候改的鉴权方式」。报错五CORS policy blocked网页查看器打不开数据这是 env-recorder 网页查看器在file://协议下的经典问题。浏览器出于安全策略禁止file://页面用fetch读取本地 JSON。env-recorder 的解决方式是起一个本地 HTTP 服务器所以你必须用python record_env.py --web来打开查看器而不是直接双击 HTML 文件。如果你看到控制台报 CORS 错误检查是不是直接打开了index.html。排查完这些回到 env-recorder 本身它的报错信息都很直白基本是「某个目录不存在」或「某个命令找不到」按提示补上即可。它不会静默失败每个扫描模块失败都会在输出里标注。6. 把环境快照变成日常习惯CTA 与长期用法env-recorder 的价值不在于跑一次而在于持续跑。我的用法是把它和几个日常动作绑定每次pip install完、每次在 Claude Code 里加完 Skill、每次换机器都跑一次python record_env.py。快照序列积累下来你就有了一个可以回溯的环境变更日志。如果你同时用多个 AI 编程工具建议把它们的配置也纳入盘点范围。Claude Code 的 Skills 在~/.claude/skillsOpenClaw 在~/.openclaw/skillsCodex 在~/.codex/skills和~/.codex/rulesCursor 在~/.cursor/rules。env-recorder 默认会扫这些目录你只需要在 TOML 里确认targets包含了你用的工具。对于需要长期维护多个项目环境的开发者可以考虑把快照 JSON 提交到 git配合 CI 定期跑 diff这样环境漂移会第一时间暴露。如果你在团队里做环境标准化可以把一份「基准快照」放进仓库新成员入职时跑一次 diff就知道自己缺什么。如果你在配置模型接入时需要查 Key 和管理额度可以走 API Keys 页面需要对照接入参数和示例代码看接入文档想先验证模型连通性用模型对话页面直接试如果是长期编码或 Agent 场景Coding Plan 更合适。这几个入口按你的实际需求选不用全走一遍。最后回到那个问题你的电脑上到底装了什么跑一次 env-recorder答案就在那份 JSON 里。它不宏大不智能但当你需要回答这个问题的时候它是你手边最快的那把尺子。