16 纯文本的威力
把知识保存在可读、可搜索、可比较且能被脚本处理的纯文本中，同时显式管理编码与结构约定。
学习目标
- 能把一个封闭工具里的配置或规则迁成可读的纯文本，并写出编码和结构约定
- 能用版本控制、差异比较和脚本处理复核一次变化，说明谁能读取这份知识
- 能回答：如果同一份知识只能由一个应用打开，如何找出迁移边界并恢复可验证的文本源？
为什么纯文本不可压缩
想象一张贴在玻璃上的值班表：人可以直接读，复印机可以复制，另一组人也能在旁边标出改动。若值班表被锁进只有一台机器能打开的盒子里，内容也许还在，却很难搜索、比较、备份或交接。
本章解决的就是这个交接问题。把知识留在一种人和普通工具都能看见的表面，变更就能留下痕迹；如果跳过这一步，团队会把“文件能打开”误当成“知识仍然可用”。
本章的验收路线
先把一个真实对象写成文本，再沿着“编码 → 结构 → 历史 → 读取”逐站检查。实验台允许你播放、暂停、单步或拖动，另外可以移除一个结构约定，观察首个拒绝点是否出现在预期位置。
下面的静态图先给全景；随后实验台把每个站点展开。不要先记结论，先预测：如果拿掉结构格式，版本历史还能可靠地告诉我们改了什么吗？
概念：让知识拥有可迁移的表面
纯文本：人和工具都能接近的源
↡用普通字符保存、可以直接阅读和处理的内容，不依赖某个专有应用才能看懂。不是“没有格式”，而是把内容的基本意义放在通用字符上。规则、命令、配置、接口示例和小型数据都可以用它保存；人能搜索，版本工具能比较，脚本也能批量检查。
需要注意边界：纯文本不会自动让内容正确。它只把知识从封闭容器里取出来，剩下的语义、权限和校验仍然要写清楚。一个人人看得见但含义不明的文件，仍然不能成为可靠的源。
编码：同一串字符的共同约定
↡把字符映射为字节、再从字节还原字符的规则；读写双方必须使用同一约定。决定文件里的字节如何还原成字符。UTF-8 是常见选择，但关键不是背下名称，而是在仓库或接口边界声明它，并用包含中文、换行和特殊符号的样本验证读回结果。
编码错位常常看起来像“文件损坏”：中文变成乱码，脚本匹配不到键名，差异比较突然出现整文件变化。修复时应回到原始字节和声明，不要在乱码上直接编辑，因为那会把显示问题误写成内容变化。
结构格式：让机器知道每个值的位置
↡约定键、值、列表和层级如何排列，使人可读的文本也能被程序稳定解析。是内容的骨架。键值、列表、缩进或分隔符都必须有明确约定；人可以读懂“超时是三十秒”，脚本也应能稳定找到同一个字段。
结构格式不是把文件变复杂。它是在内容变大、需要生成或校验时，把“这一段文字代表什么”从猜测变成规则。格式一旦改变，要同时更新解析器、样例和迁移说明。
版本控制：给文本变化留历史
↡保存文本在不同时间点的快照、作者和差异，允许比较、审阅并回到较早状态的机制。让改动成为可追溯的事件。一次提交应说明变了哪个对象、为什么变、谁确认；审阅者能查看差异，发现误删或意外格式化，而不是只收到一份最新文件。
文本很适合版本控制，因为相邻版本的变化可以被压缩成少量行。二进制容器往往只能说“整个文件变了”，这并不等于内容真的全部改变。
差异比较与工具独立
↡把两个文本状态对齐，指出新增、删除和修改位置的过程。是变更的证据，不是装饰。比较前要冻结编码、换行和结构约定，否则格式化工具制造的噪声会遮住真正的业务变化。
↡知识不被单一应用的界面或私有存储锁住，至少能由另一种普通工具读取、验证或迁移。也不意味着完全不用专用工具，而是专用工具不成为唯一出口。保留文本源、导出规则和最小读取脚本，才能在应用停止维护、团队换工具或需要批处理时继续工作。
提示25：将知识用纯文本保存
提示25的重点不是把所有东西都强行改成一个文件，而是先问：“这份知识的最小可迁移表示是什么？”部署参数、查询、接口样例、构建规则和文档索引通常可以先保存成文本；图片、压缩包或大型二进制则需要另外记录元数据、生成方式和导出边界。
例如，下面的配置同时对人和脚本可见：
service = "catalog"
timeout_seconds = 30
retry_limit = 2
owners = ["platform", "catalog"]它的价值不在 TOML 这个名字，而在三件可复核的事：字段含义写得出来，读写双方的编码与结构约定一致，变更能在版本历史中显示。换工具时，可以先写一个小读取器验证同一输入，再逐步迁移界面，不必把业务知识重新猜一遍。
把“能导出”误当成“已迁移”仍然不够。迁移验收至少要包含原对象、文本样本、编码声明、结构校验、一次差异、一个独立读取者和失败时的回退文件。
从文本源到长期读取：五站复核
这条链把一个抽象建议变成可运行的检查：知识先进入文本表示，文本在编码和结构约定下成为可比较的版本，最后交给人或脚本读取。每一站都要记录输入、输出和拒绝条件；只有最后显示“读取成功”，不能证明中间没有悄悄变形。
第一步：写出最小文本源
选一份团队真的会交接的知识，例如服务配置或接口样例。删掉应用自动生成的无关状态，只保留字段名、值、单位、默认值和 owner。先预测：如果另一个编辑器没有原应用插件，它仍能读出哪些信息？
第二步：声明编码与结构
将编码、换行和结构格式写入项目约定，并用正常样本、边界样本和非法样本各跑一次读取。结构缺失时，程序应该拒绝并给出位置；静默猜测会把乱码或错位值写回源文件。
第三步：留下差异并让另一种工具读取
提交一次只改一个字段的变化，观察差异是否只显示这一处。再用不依赖原应用的读取器抽取同一个值；若读取器只能靠点击路径才能工作，就还没有达到工具独立。
当前：第 1 步 · 知识：先挑一个可交接对象
第 1 / 5 步 · 知识：先挑一个可交接对象
先猜下一站会改变什么，再用单步或播放验证。
一个可复核的文本迁移记录
text_migration:
object: catalog service timeout
source: catalog.toml
encoding: UTF-8
format: TOML key-value structure
change: retry_limit 2 -> 3
diff: one field changed; owner remains platform
independent_reader: config-check --file catalog.toml
first_rejection: missing format declaration
recovery: restore declaration, validate, then replay the diff这份记录把“文件存在”与“知识可复核”分开。独立复核者可以拿到同一文本、工具版本和边界样本，重放读取；如果结论不同，先比较首个分叉，再决定是编码、结构还是工具实现需要修正。
常见误区
小结
- 纯文本把知识放到人和普通工具都能接近的表面。
- 编码与结构约定决定文本能否稳定还原和解析。
- 版本控制与差异比较让变化可以审阅、回退和交接。
- 工具独立要求保留文本源和至少一种独立读取路径。
- 迁移验收要保存正常、边界、故障样本及恢复动作。
练习：把建议变成可运行的证据
练习
问题 1： 对提示25：将知识用纯文本保存，选择一个你所在项目的配置对象。写出它的文本源、编码、结构格式、owner 和一个不应纳入文本源的界面状态。
问题 2： 版本中只有一行 retry_limit 改变，但差异比较显示整文件变化。请列出两个排查顺序，并说明为什么不能先接受这份差异。
问题 3： 动手修改 Tpp20Topic16PlainTextLab 的故障分支：把“移除结构格式”改成“使用错误编码”，并保留首差、拒绝原因和重置路径。用三行记录正常、故障、恢复样本。
名词解释
名词解释
本章出现的专业名词，用大白话再讲一遍。
- 纯文本
用普通字符保存的内容，人可以直接阅读，搜索工具和脚本也能处理；它不是“没有格式”，而是不用某个专有界面才能理解基本内容。
- 编码
把字符变成字节、再把字节还原成字符的共同约定；读写两端不一致，就会出现乱码或错误差异。
- 结构格式
规定键、值、列表和层级如何排列的骨架，让程序能稳定找到每个值，也让人能检查它的意义。
- 版本控制
保存文件在不同时间的快照、作者和变化，方便审阅、回退与追问“谁为什么改了这里”。
- 差异比较
对齐两个文本状态并指出新增、删除和修改的位置；比较前必须先固定编码和表示规则。
- 工具独立
知识不被单一应用锁住，换一个普通编辑器、解析器或脚本仍能读取、验证或迁移它。