二稿核验说明(2026-10-15):本文为“河洛序”教程二稿,已按官方规范与文档修订。旧实验日志单独标为“一稿留存输出”,不代表本次在Windows上的复跑;本次环境与结果见本批核验记录。示例中的“星河笔记”、账号、订单、价格与政策均为虚构教学数据。
一句话定义
版本控制系统记录显式保存的文件版本及其关系,支持查看差异、追溯和协作合并。它不会自动保存每次键盘修改;能恢复到哪些状态,取决于已保存的对象、引用与保留策略。
为什么重要
- 可回退:提示词、配置、代码改坏了,可以精确回到“昨天还能用的那一版”,而不是靠
prompt_final_v3_真的最终版.txt。 - 可追溯:每次改动都有作者、时间、说明,出问题时可查看提交中的作者、时间和说明,再结合评审记录分析原因。
- 可协作:多人同时改同一个项目,工具尝试文本合并;即使没有报告冲突,仍需检查语义兼容性。
- AI 项目尤其需要:模型效果的变化往往来自提示词、数据切分、依赖版本的微小改动;没有版本控制,回归测试(k4.eval.regression-test)就无从对比。
原理 / 图解
本例用三件事建立入门模型:存快照、算差异、做合并。
| 概念 | 含义 | 现代实现(Git)的做法 |
|---|---|---|
| 快照 / 提交 | 某一时刻整套文件的状态 + 作者、时间、说明、父提交 | 每次提交保存完整目录树,未改动的文件复用旧对象 |
| 内容寻址 | 用内容的哈希值作为对象的“地址” | Git常见SHA-1格式,也可按工具支持选择SHA-256格式 |
| 差异 diff | 两个版本逐行比较的结果 | 按需计算,不是存储格式 |
| 三方合并 | 以两条分支的共同祖先为参照判断谁改了什么 | 默认 ort 合并策略 |
| 集中式 vs 分布式 | 历史集中保存(如SVN;工作副本还可带有局部元数据)还是普通完整克隆可包含可达历史(Git、Mercurial) | 分布式:本地即可提交、查看历史 |
Pro Git 第 1 章“关于版本控制”介绍了本地、集中式、分布式三类 VCS:https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control;Git 以快照而非差异存储数据:https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F
三方合并为什么需要共同祖先:
规则可以写成一张表:对每一行,若 ours = theirs 则直接取;若 ours = base,说明只有对方改了,取 theirs;若 theirs = base,取 ours;否则冲突。
适用边界与核验要点
版本图反映提交关系,作者字段和说明不等于经过认证的身份或真实动机。Git 的快照是逻辑模型,打包对象仍可使用增量压缩。通常的完整克隆包含可达历史,但浅克隆、部分克隆和单分支克隆是例外。文本合并成功只说明工具没有报告文本冲突,语义冲突仍需评审和测试。本例按同一行号比较,要求三份输入等长、对应位置已经对齐;12位十六进制截断哈希也不适合作为生产对象库的唯一标识。
本次检索核对的主要依据(2026-10-15):
- Pro Git:Git的快照模型:逻辑快照、本地操作与已提交数据。
- git merge官方手册:自动合并、冲突和合并状态。
可运行示例
用Python标准库演示内容寻址、快照、差异与已对齐行的三方比较。它是内存玩具模型,不调用Git。
# 文件:examples/01_version_control.py
"""用 60 行 Python 实现一个“玩具版本控制”:内容寻址存储 + 快照 + 差异 + 三方合并。"""
import hashlib, difflib, json
store = {} # 对象库:hash -> 内容(与 Git 的 .git/objects 同一思想)
def put(data: bytes) -> str:
h = hashlib.sha256(data).hexdigest()[:12]
store[h] = data
return h
def commit(files: dict, parent, msg):
tree = {name: put(text.encode()) for name, text in sorted(files.items())} # 每个文件内容 -> 对象
meta = json.dumps({"tree": tree, "parent": parent, "msg": msg}, sort_keys=True).encode()
return put(meta)
def files_of(c):
tree = json.loads(store[c])["tree"]
return {n: store[h].decode() for n, h in tree.items()}
print("① 两次提交(快照,而不是差异)")
v1 = commit({"prompt.txt": "你是星河笔记客服。\n回答要简洁。\n", "README": "demo\n"}, None, "初始版本")
v2 = commit({"prompt.txt": "你是星河笔记客服。\n回答要简洁。\n不知道就说不知道。\n", "README": "demo\n"}, v1, "加入弃答规则")
log, c = [], v2
while c:
m = json.loads(store[c]); log.append(f" {c} {m['msg']} parent={m['parent']}"); c = m["parent"]
print("\n".join(log))
t1, t2 = json.loads(store[v1])["tree"], json.loads(store[v2])["tree"]
print(" README 两个版本的对象 hash 相同(未改动的文件不重复存储):", t1["README"] == t2["README"])
print(" 对象库中对象数:", len(store))
print("\n② v1 → v2 的差异(unified diff)")
a, b = files_of(v1)["prompt.txt"], files_of(v2)["prompt.txt"]
print("".join(difflib.unified_diff(a.splitlines(True), b.splitlines(True), "v1/prompt.txt", "v2/prompt.txt")))
print("③ 三方合并:以共同祖先 base 为参照,判断哪一方改了哪一行")
def merge3(base, ours, theirs):
out, conflicts = [], 0
for i, (b, o, t) in enumerate(zip(base, ours, theirs)):
if o == t: out.append(o) # 两边一致
elif o == b: out.append(t) # 只有对方改了 -> 取对方
elif t == b: out.append(o) # 只有我们改了 -> 取我们
else: # 两边都改了同一行 -> 冲突
conflicts += 1
out += ["<<<<<<< ours", o, "=======", t, ">>>>>>> theirs"]
return out, conflicts
base = ["语气:礼貌", "长度:100 字以内", "语言:中文"]
ours = ["语气:礼貌", "长度:50 字以内", "语言:中文"] # A 改长度
theirs = ["语气:亲切", "长度:100 字以内", "语言:中文"] # B 改语气
m, k = merge3(base, ours, theirs); print(" 不同行各改各的 → 冲突数", k, "→", m)
theirs2 = ["语气:礼貌", "长度:80 字以内", "语言:中文"] # B 也改了长度
m, k = merge3(base, ours, theirs2); print(" 同一行都改了 → 冲突数", k); print("\n".join(" " + x for x in m))
print("\n④ 两方合并(没有 base)为什么不够:只看 ours 与 theirs,无法知道“谁改了”")
print(" ours 第1行=", ours[0], " theirs 第1行=", theirs[0], " → 不知道该取哪个,只能报冲突")
一稿留存输出
以下日志按一稿保留,来自一稿声称的原环境;不是本次复跑结果。二稿代码改动后可产生不同输出,实际复跑状态以本批核验记录为准。
① 两次提交(快照,而不是差异)
abef9633776a 加入弃答规则 parent=568d179b6d01
568d179b6d01 初始版本 parent=None
README 两个版本的对象 hash 相同(未改动的文件不重复存储): True
对象库中对象数: 5
② v1 → v2 的差异(unified diff)
--- v1/prompt.txt
+++ v2/prompt.txt
@@ -1,2 +1,3 @@
你是星河笔记客服。
回答要简洁。
+不知道就说不知道。
③ 三方合并:以共同祖先 base 为参照,判断哪一方改了哪一行
不同行各改各的 → 冲突数 0 → ['语气:亲切', '长度:50 字以内', '语言:中文']
同一行都改了 → 冲突数 1
语气:礼貌
<<<<<<< ours
长度:50 字以内
=======
长度:80 字以内
>>>>>>> theirs
语言:中文
④ 两方合并(没有 base)为什么不够:只看 ours 与 theirs,无法知道“谁改了”
ours 第1行= 语气:礼貌 theirs 第1行= 语气:亲切 → 不知道该取哪个,只能报冲突
- ① 两次提交共产生 5 个对象:v1 的 2 个文件内容 + 1 个提交元数据,v2 只新增了改动过的
prompt.txt和 1 个提交元数据;README内容没变,两个版本指向同一个对象 hash(输出True)。这就是“存快照但不浪费空间”的秘密。 - ② 差异是从两个快照现算出来的,
+不知道就说不知道。表示新增一行。 - ③ A 改长度、B 改语气,因为改的是不同行,三方合并自动得到
['语气:亲切', '长度:50 字以内', '语言:中文'];两人都改了“长度”这一行时,冲突数为 1,并生成与 Git 相同风格的<<<<<<</=======/>>>>>>>冲突标记。 - ④ 如果没有共同祖先,“礼貌”和“亲切”谁是新值无从判断——这就是 三方合并通常需要共同祖先;无关历史等特殊情形须另行处理 的原因。
- 说明:真实工具按“最长公共子序列”等算法对齐行,能处理插入、删除;本例为简化只按行号逐行比较。
自测
问题: 两个人修改了不同文件,Git 自动合并成功,是否可以据此认定程序兼容?
参考答案: 不可以。两项修改可能分别改变函数签名和调用方假设;合并成功没有验证行为。应检查接口约定并运行相关测试。
常见误区
- “版本控制就是备份”:备份只保存副本;版本控制还记录因果关系(父提交)、说明与作者,并支持合并。
- “VCS 存的是每次的差异”:Git 存的是快照,差异按需计算见上方 Pro Git 链接;早期一些 VCS(如 RCS)确实以差异存储。
- “只有代码才需要版本控制”:提示词、评测集、配置、文档都应纳入;大型二进制(模型权重、数据集)更适合 Git LFS、DVC 等工具。
- “冲突说明合并工具不好”:冲突是工具拒绝替你猜,两人改了同一处时必须由人决定。
与 AI 开发的关系
- 把提示词与评测集和代码放在同一个仓库、同一个提交里,模型效果的每次变化都能追溯到具体改动。
- 让 AI 编程助手改代码时,先提交一个干净版本,改坏了用版本控制一键回退,比让模型“改回去”可靠得多。
- 合并冲突时,三方信息(base、ours、theirs)是给 AI 助手解释冲突的最佳上下文。
延伸阅读
- Pro Git(中文版):https://git-scm.com/book/zh/v2
- DVC(数据与模型版本管理):https://dvc.org/doc
- Git LFS:https://git-lfs.com/
尚未验证的范围
- 玩具合并不实现插入、删除和重命名的对齐,也不检测语义冲突;不据此评估真实VCS的正确性。
本次示例运行范围
2026-10-15:通过。玩具快照/diff/按行号合并;非真实VCS兼容性测试。
“一稿留存输出”保留原字,不是二稿代码新生成的结果;其原结论须结合二稿修订与边界阅读。
配套代码与核验资料