系列导航
- 上一篇：AI Agent 工程实践（44）：Regression——改一次为什么能搞坏十个地方
- 下一篇：AI Agent 工程实践（46）：模型换了，Agent 为什么突然变笨
发布时间：2026-08-15 标签：AI Agent｜工程实践｜版本控制｜可复现
上一篇讲了回归，说要"对比改动前后的表现"。
但这里藏着一个更尴尬的问题，是我在一次排查中撞上的：
我修完一个 bug，想复现"修之前"的表现来做对比，结果发现——我根本复现不出来了。
不是代码没存，而是：我当时用的是哪个模型？哪个 Prompt 版本？哪套工具？哪个评估集？
我一样都答不上来。
那一刻我才明白：Agent 的"版本"，根本不是一个 git commit 能说清的。
问题背景
这是第五阶段的第十篇。前面有了评估集（第 43 篇）和回归门槛（第 44 篇），但它们都依赖一个前提——你能精确复现"某个历史版本"的 Agent。
而这个前提，在 Agent 项目里，意外地脆弱。
传统项目里，git checkout 某个commit，就能回到过去。因为传统软件的"版本"，就是代码的版本。但 Agent 不一样——代码只是影响它行为的一小部分。 同一个代码，换个模型、换个 Prompt、换套工具描述，输出可能天差地别。
所以这一篇要回答的问题很直接：Agent 的"版本控制"，到底该控制什么？
错误尝试：把 Agent 版本 = 代码版本
我的翻车现场，就是典型的"用 git 管 Agent"。
我把所有代码都提交了 git，自认为版本管理已经做得很规范。直到那次排查：我想复现"上周那个还不错的版本"，git checkout 回去，代码确实回来了，但跑出来的结果，和上周完全对不上。
排查了半天才找到原因：上周跑的时候，用的是 deepseek-chat 的某个快照，现在那个快照已经被官方更新了。 代码一样，模型变了，行为就变了。
更糟的是，我还发现另外几个"隐藏变量"：Prompt 我是直接写在代码里的，但中间改过好几次没记录；工具的 description 也调过；连评估集本身都加过题。
代码版本只是冰山一角。 水面之下，还有模型、Prompt、规则、工具、数据集——它们任何一个变了，Agent 的行为都会变，而你用 git 根本管不住它们。
关键观察：Agent 版本是一个"六元组"
想通了这件事，Agent 的版本定义就清晰了。它不是一维的（代码），而是六维的联合版本：
Agent Version = Code + Model + Prompt + Rule + Tool + Knowledge + Dataset
等一下，这是七项。我细说这七项分别是什么、为什么每一项都影响行为：
| Code | 编排逻辑、节点实现 | 流程变了，输出当然变 |
| Model | 底层大模型及其版本 | 能力、风格、甚至幻觉率都变 |
| Prompt | system/user 提示词 | 直接改变 Agent 的"行为倾向" |
| Rule | 业务规则、约束 | 边界变了，结论可能翻盘 |
| Tool | 工具集及其描述 | 工具选错，满盘皆输 |
| Knowledge | 注入的知识、RAG 库 | 依据变了，答案就变 |
| Dataset | 评估集本身 | 尺子变了，分数不可比 |
核心洞察：
当你的 Agent 出了 bug，你问的第一句不该是"代码改成啥了"，而是"这个结果是用哪个版本的哪个模型跑的"。
最终方案：agent.lock 锁住六元组
既然版本是七维的，那"版本控制"就要把这七维都钉死。我落地成一个 agent.lock 文件——每次跑评估或上线前，先把当前七维的组合记录并锁定：
# repo_doctor/agent.lock —— Agent 版本的唯一事实源
version: "1.4"
components:
code:
commit: "a3f9c21"
model:
provider: "deepseek"
name: "deepseek-chat"
snapshot: "2026-08-10" # 关键：模型也有版本，要钉快照
prompt:
version: "v12"
hash: "e9b2…"
rules:
version: "v7"
tools:
version: "v4"
schema_hash: "7c1d…"
knowledge:
version: "v2"
rag_index: "2026-08-01"
dataset:
version: "v3"
count: 25
有了这份 lock，"复现一个 Agent"才第一次成为可能：不是 checkout 代码，而是按 lock 文件，把七维全部还原到历史状态。
架构图 / 流程图
版本控制的对象，从"代码"扩展到了"七维"，画出来是这个对比：
这张图一句话总结：传统项目管"代码"，Agent 项目管"代码 + 六个会变的行为变量"。
代码或配置示例
锁住七维后，还要能"校验"——防止有人改了某维却忘了更新 lock。一个校验脚本：
# repo_doctor/version/check.py —— 启动前校验七维是否与 lock 一致
def verify_lock(lock: dict, runtime: dict) -> list:
mismatches = []
for key in ["code", "model", "prompt", "rules", "tools", "knowledge", "dataset"]:
if lock[key]["version"] != runtime[key]["version"]:
mismatches.append(key)
if mismatches:
print(f"[版本漂移] 以下维度与 agent.lock 不一致：{mismatches}")
return mismatches
这个校验的价值在于：它把"版本漂移"从隐性变成了显性。 以前你改了 Prompt 忘了记录，谁都不知道；现在启动时一比对，漂移立刻暴露。
设计权衡
| 只用 git 管 Agent | 熟悉、省事 | 管不住模型/Prompt/数据，行为漂移 | 代码只是七维之一 |
| 每维单独管理、各自记录 | 精细 | 割裂，复现时东拼西凑 | 无法一键还原 |
| agent.lock 七维联合锁定 | 可一键复现、可校验漂移 | 维护成本略高 | 把"复现"变成可执行动作 |
一个诚实的提醒：七维里，最容易被忽略、也最容易翻车的是 Model。 很多人以为"模型名一样就行"，但实际上同一模型名的 API 背后，厂商会静默更新快照。所以 lock 里一定要钉"模型快照/日期"，而不只是名字——这个坑，下一篇（模型实验）会正面撞上。
总结
✅ Agent 版本 ≠ 代码版本，而是 Code/Model/Prompt/Rule/Tool/Knowledge/Dataset 七维联合。 ✅ 传统 git 管不住模型、Prompt、数据的漂移。 ✅ 落地 agent.lock，把七维钉死，实现可复现。 ✅ 铁律：当 Agent 出 bug，先问"这个结果是用哪个版本的哪个模型跑的"。 ✅ 最易被忽略的是 Model 快照——下一篇专门做实验验证。
参考资料
- ML 领域 Model Registry（如 MLflow）的做法 → 为什么引用：模型版本化是 Agent 版本化的先驱，思路直接借鉴。
- Prompt versioning 工具（如 LangSmith Prompts）→ 为什么引用：Prompt 作为一等版本对象，是七维锁定的关键一环。
系列导航
- 上一篇：AI Agent 工程实践（44）：Regression——改一次为什么能搞坏十个地方
- 下一篇：AI Agent 工程实践（46）：模型换了，Agent 为什么突然变笨
本文是 [AI Agent 工程实践] 系列的第 45 篇。
