第 8 章：综合验收与排错 — 完成一次开机自检¶
📋 本章概览¶
| 项目 | 内容 |
|---|---|
| 学习时长 | 12 分钟 |
| 核心概念 | 验收清单、PATH、版本冲突、日志、可复现环境 |
| 核心比喻 | 环境验收像给一台新机器做开机自检 |
| 实践任务 | 从空目录验证 C/C++、Python、Git 和包管理器 |
| 难度等级 | ★★★☆☆ |
验收的意义是证明“以后还能再做一次”¶
环境配置完成的标志，不是某条命令今天碰巧输出了版本号，而是你能在一个新目录中重复关键步骤，知道项目依赖从哪里来，知道哪些文件不该提交，也知道出现差异时该先比较什么。验收清单把一次性的安装动作变成可以交接的证据。
遇到失败时，不要把所有工具都重装一遍。先判断是命令不存在、路径指向错误、版本不匹配、依赖未隔离，还是项目本身的问题。把每次检查的结果写下来，最终形成环境报告；它既是给未来自己的说明，也能让别人更快帮你定位。
8.1 最小验收清单¶
- 终端能打开目标项目目录。
- C/C++ 编译器能输出版本并编译 Hello 程序。
- Python 能创建虚拟环境并安装依赖。
- Git 能初始化、提交和查看状态。
.env、密钥和虚拟环境目录不会进入 Git。
8.2 常见故障定位¶
| 现象 | 优先检查 |
|---|---|
| 命令找不到 | 工具是否安装、PATH 是否包含安装目录、是否需要重启终端 |
| 编译器找不到头文件 | 使用了错误的开发者终端或工具链 |
| pip 装到了别处 | 使用 python -m pip，检查虚拟环境是否激活 |
| Git 提交包含密钥 | 立即撤销密钥、加入 .gitignore，再检查提交历史 |
| 不同电脑结果不同 | 记录系统、工具版本和依赖清单 |
密钥泄露的停止边界
发现 API Key 出现在命令历史、日志或 Git 提交中时，立即停止继续使用它，去服务商后台撤销并重新生成。仅删除文件或修改最后一次提交不能保证旧密钥已经安全。
8.3 生成环境报告¶
环境报告可以记录版本，但不能包含秘密：
OS: Windows 11 / macOS / Ubuntu
Compiler: GCC or Clang version
Python: version
Git: version
Package manager: version
Project dependency file: requirements.txt or package-lock.json
✅ 验证步骤¶
从一个新目录完成一次完整验收，并把报告提交到 Git。随后执行 git status --ignored，确认 .venv/ 和 .env 被忽略；用文本搜索确认报告中没有 sk-、token 或密码。
📝 本章总结¶
- 环境问题要按“安装—路径—版本—项目隔离”顺序排查。
- 可复现环境需要版本记录和依赖清单。
- 发现秘密泄露时，先撤销密钥，再清理记录。
✏️ 课后练习¶
- 把验收命令整理成一个 PowerShell 或 Bash 脚本。
- 在另一台电脑或容器中复现同一份环境报告。
🔮 学完之后¶
你可以继续学习“Agent 工具入门”，把已经准备好的终端、Git 和项目目录交给一个受控的编码助手。