第3章 基础工具
用纯文本、Shell、编辑器、版本控制、调试、文本处理和工程日记放大个人能力。
学习目标
- 能把纯文本、Shell、编辑器、版本控制、调试、文本处理和工程日记组合成可复现工具链
- 能在工具链发生故障时定位首个因果分叉，用可观察证据而不是熟练度或猜测修复
- 能保存输入、命令、版本、失败日志和恢复动作，让另一个人可以重建工作结果
第3章 基础工具
本页依据 David Thomas、Andrew Hunt《程序员修炼之道：通向务实的最高境界（第2版·20周年版）》，云风译，电子工业出版社，2020 年 4 月，ISBN 9787121384356 的公开中文目录，独立重构 第3章 基础工具。正文、代码、图示、实验和练习都是本课程重新设计的教学材料，不复制原书正文、插图、练习答案或代码。
基础工具的价值不在于记住某个命令，而在于把工作变成可读、可组合、可撤销、可定位和可复盘的反馈回路。纯文本提供可读表示，Shell 组合小动作，编辑器减少机械成本，版本控制保存历史，调试验证因果，文本处理放大批量反馈，工程日记把决定留给未来的自己和团队。
三个会让工具链失效的陷阱
五个词组成可复现工具链
<Term def="人和工具都能读取、搜索、比较和批量处理的表示形式，并明确编码与结构约定。">可读表示</Term>让知识与配置不被专属软件锁住。文本可读不等于格式没有规则，编码、换行和字段约定也必须记录。
<Term def="把小命令按明确输入、输出和错误边界连接起来的组合方式。">组合工具</Term>让重复操作可以审计和重放。管道越长，越需要中间输出、退出码和最小失败样本。
<Term def="以可撤销、可观察和可批量的方式改变文本或代码的动作，包括编辑器命令和脚本。">自动变换</Term>减少机械成本，但不能跳过语义验证。每次变换都应说明影响范围和回退方法。
<Term def="记录代码、配置、文档和工具脚本的可比较状态，使变更可以定位、恢复和解释。">历史追踪</Term>不是单纯备份。提交信息、差异、版本和验证结果共同解释“为什么这样改”。
<Term def="保存时间、输入、命令、假设、观察、失败和决定的外部记忆，使未来的人能重建路径。">工程日记</Term>把调试和工具选择从个人经验变成团队资产。
五个词形成依赖链：没有可读表示，组合工具无法稳定接收；没有组合工具，自动变换难以批量重放；没有历史追踪，变换无法定位和回退；没有工程日记，证据无法跨时间复核。
正式目录与实践边界
16 纯文本的威力
把知识保存在可读、可搜索、可比较和可自动处理的纯文本中，同时显式管理编码与结构约定。
目录提示：提示25：将知识用纯文本保存。本课程把它作为可失败命题进入实验，不把它当作脱离边界的口号。
17 Shell游戏
把 Shell 当成可组合的工作台，用小工具、管道和脚本将重复操作变成可审计流程。每一步都要保留输入、输出、退出码和异常处理。
目录提示：提示26：发挥 Shell 命令的威力。当命令会修改文件或触达生产数据时，先用沙盒和小样本验证。
18 加强编辑能力
通过可编程编辑、结构化导航和批量变换减少机械成本，同时保留可撤销与验证边界。宏和脚本应该是可读、可审查的代码，不是不可解释的手势。
目录提示：提示27：游刃有余地使用编辑器。编辑器自动化越强，越需要版本控制和变更预览。
19 版本控制
把代码、配置、文档和自动化全部纳入版本控制，使每个可发布状态都能定位、比较和恢复。提交应说明动机、影响和验证，避免只留下“更新文件”。
目录提示：提示28：永远使用版本控制。不能纳入版本控制的外部依赖，应在工程日记中留下版本和获取方式。
20 调试
以复现、观测、假设和证伪驱动调试，先制造失败测试，再修首个因果分叉。错误信息是输入证据，不是需要被情绪化责备的对象。
目录提示：提示29：去解决问题，而不是责备、提示30：不要恐慌、提示31：修代码前先让代码在测试中失败、提示32：读一下那些该死的出错信息、提示33：“select”没出问题、提示34：不要假设，要证明。这些提示都需要通过复现和反例缩小范围。
21 文本处理
学习一种文本处理语言，把日志、数据、代码和配置的批量检查转成快速、可重复的程序。先定义输入格式、异常格式和输出验收，再扩展处理范围。
目录提示：提示35：学习一门文本处理语言。工具不能代替对数据含义和隐私边界的判断。
22 工程日记
用工程日记保存日期、问题、决定、命令和结果，建立跨时间的外部记忆与决策轨迹。它不是流水账，而是未来复现和回退所需的证据包。
该 Topic 在中文版目录中没有单列编号提示，因此以标题命题、练习和本章依赖共同确定验收边界。
工具链合同
type ToolRun = {
input: string;
command: string;
toolVersions: string[];
output: string;
firstDifference: string;
historyRef: string;
journalEntry: string;
decision: "keep" | "rollback" | "escalate";
};
function isReplayable(run: ToolRun) {
return (
run.input.length > 0 &&
run.command.length > 0 &&
run.toolVersions.length > 0 &&
run.output.length > 0 &&
run.firstDifference.length > 0 &&
run.historyRef.length > 0 &&
run.journalEntry.length > 0
);
}这个合同不要求所有工具都一样，也不要求每次运行都成功。它要求每次结果都能说明输入、工具版本、输出、首个差异、历史位置和工程日记；无法重放时就回退、缩小范围或升级，而不是继续扩大修改。
四步建立可复现反馈
1. 固定可读输入
把需求、配置、日志或代码样本保存为可搜索文本，记录编码、换行、字段和敏感数据边界。先选最小代表样本，不直接对全量数据操作。
Interactive lab
选择工具链样本，定位首个变化
输入
批量脚本遇到较大数据量，输出仍成功但运行时间和范围改变。
首个变化
边界先发生变化，不能把小样本结论推广到全量。
裁决动作
缩小输入、加中间观测并设定容量门槛。
先固定输入和基线，再运行命令；工具的速度不能替代差异、日志和回退。
正常、边界与单一故障证据
| 样本 | 只改变的变量 | 预期判定 | 必存证据 |
|---|---|---|---|
| 正常 | 输入、版本、命令和记录完整 | 工具链闭合，结果可重放 | 输入、命令、输出、差异和日记 |
| 边界 | 文件编码、权限、数据量或工具版本越过阈值 | 停止扩大，明确回退或升级 | 阈值、退出码、原状态、替代方案 |
| 单一故障 | 一个命令、依赖、状态或记录缺失 | 首个差异暴露并恢复 | 首差、错误上下文、历史和回归 |
最小证据包与反例
证据包包含输入身份、编码与结构、命令或编辑动作、工具和依赖版本、初始状态、输出、退出码、差异、提交或版本引用、失败日志、工程日记、复核人和恢复动作。覆盖率、格式化结果或最后一张截图只能辅助定位，不能独立证明工具链可靠。
反例不是“这个工具不好用”。它必须在相同前提下产生相反结果，或指出前提在目标环境不成立。例如 Shell 在本地成功但在空格文件名上破坏路径，编辑器宏在不同编码下改坏文本，或调试结论只在一个版本成立。发现反例后，先保留失败输入，再缩小边界、修复脚本并重放。
术语表
名词解释
本章出现的专业名词，用大白话再讲一遍。
- 可读表示
人和工具都能读取、搜索、比较和批量处理的表示形式，以及它的编码和结构约定。
- 组合工具
把小命令按明确输入、输出和错误边界连接起来的组合方式。
- 自动变换
以可撤销、可观察和可批量的方式改变文本或代码的动作。
- 历史追踪
记录可比较状态，使变更可以定位、恢复和解释。
- 工程日记
保存时间、输入、命令、假设、观察、失败和决定的外部记忆。
练习
练习
问题 1： 一条 Shell 管道在你的样本上成功，但换成带空格的文件名后会改错文件。你会怎样定位和修复？
问题 2： 编辑器宏一次改动了数百个文件，结果只有最后的差异，没有中间记录。下一次如何设计？
问题 3： 调试者说“这个依赖应该没问题”，但没有失败测试或工程日记。你会要求哪些证据？
本章回顾
第3章 基础工具的关键不是掌握一套神奇命令，而是让可读表示、组合工具、自动变换、历史追踪和工程日记形成可复现依赖。纯文本、Shell、编辑器、版本控制、调试、文本处理和工程日记都要接受正常、边界和单一故障样本；能定位首差并让别人重建，才是把工具变成能力。