Vek：给 AI Agent 的执行历史装上 git 语义

AI Agent 生态里最拥挤的部分，往往不是底层，而是上层。

大家热衷于讨论 planner、workflow、orchestrator、multi-agent、memory、tool use，热衷于再发明一层更厚的框架。可真正到了系统开始长期运行的时候，一个更底层的问题会浮出来：

这些执行历史，到底应该怎么被保存、追踪、分叉、回放与比较？

代码世界有 Git。模型世界有 prompt。那 agent world 呢？

这就是 Vek 试图回答的问题。

它不是新的 agent framework，不试图接管你的 planning、routing 或 workflow。相反，它做了一件更克制、也更基础的事：

把每一次 tool call 的输入与输出，都存成不可变、可寻址、可分叉、可回放的执行对象。

换句话说，Vek 想做的不是 agent 的“大脑”，而是它的执行历史层。

问题不在编排，而在历史

今天的大多数 agent 系统，都更关注“怎么让它做事”，而较少关注“做过的事如何被严肃地管理”。

于是我们常常会遇到几类问题：

• 一次 agent 运行里调用了几十个工具，但事后很难精确知道每一步的输入输出是什么
• 多轮尝试之后，分叉实验混在一起，很难回到某个关键节点重新出发
• 不同路径得到不同结果，却缺少一种结构化的方式去比较它们
• 日志是有的，trace 是有的，但它们更像观测数据，而不是一种可以操作的历史对象

也就是说，很多系统已经有了“观察性”，却还没有真正拥有“版本控制式的执行历史”。

Vek 的切入点正好在这里。它没有去扩大 agent 的能力边界，而是试图让 agent 的执行过程本身变得像代码历史一样可管理。

它本质上是什么

从 README 和源码来看，Vek 的定义非常清晰：

Content-addressed execution store for AI agents — git semantics for agent tool calls.

这句话里有两个关键词。

1. Content-addressed

Vek 不直接把一次 tool call 当成一条普通日志写进去，而是先把输入与输出做确定性序列化，然后计算哈希。

在 src/vek/core.py 里，它采用的是接近 Git 的做法：

SHA-256("blob" + " " + size + "\0" + content)
SHA-256("node" + " " + size + "\0" + content)

这里的意义非常大。

• 相同内容只存一份
• 内容一旦写入，就有稳定身份
• “输入是什么”“输出是什么”不再只是附属字段，而是独立对象

这让 agent 的执行记录从“字符串日志”变成了“内容寻址对象”。

2. Git semantics

Vek 不是简单借用 Git 的语言来装饰自己，它确实在把 Git 的一些核心语义迁移到 agent execution history 上。

从 src/vek/api.py 可以看到一整套操作：

• store
• session
• branch
• fork
• merge
• diff
• replay
• tag
• fsck
• gc
• export/import

所以它不是一个“agent 运行日志查看器”，而更像是：

一个面向 tool-call history 的极简版本控制层。

底层数据模型：objects、nodes、refs

如果只看概念描述，Vek 很容易被误解成“又一个 tracing package”。真正让它站住脚的，是它的数据模型很干净。

在 src/vek/db.py 里，SQLite schema 非常直接：

objects  - content-addressed blob store
nodes    - execution DAG vertices
refs     - named pointers to nodes

这几乎就是 Git 的翻译版。

objects

objects 存的是输入和输出本身。

不是“某个 node 附带了 input/output 文本”，而是 input/output 先变成独立 blob，再由 node 去引用它们。这样做的好处是：

• 相同输入可以天然 dedup
• 相同输出也可以天然 dedup
• 节点和内容被拆开，结构更稳

nodes

nodes 才是真正的执行步骤。它包含：

• tool
• input_hash
• output_hash
• parent_hash
• timestamp
• merge_parent

这说明 Vek 记录的不是“某次调用”，而是“位于执行图中的一次调用”。

一旦 parent_hash 存在，工具调用就从孤立事件变成了历史链条的一部分。

refs

refs 是分支和标签指针。
这也意味着 Vek 的 branch/fork/tag 不是运行时临时状态，而是持久化在仓库里的命名引用。

这一步很关键，因为它把“实验路径”这件事从业务层逻辑，下降成了一个基础设施原语。

Session 的价值：不是批量写入，而是原子历史段

Vek 一个很聪明但不喧哗的设计，在 src/vek/session.py 里。

表面看，with vek.session() as s: 只是一个上下文管理器，用来连续记录多次调用。
但它真正做的是两件更重要的事：

1. 自动把本次 session 内的每一步串成线性历史段
2. 把整段写入放进单个 SQLite transaction 中，做到原子提交或回滚

这意味着 session 不是“方便 API”，而是一种很接近 commit boundary 的东西。

如果 session 中途异常，整段历史可以回滚；如果 session 正常结束，这一段链路才整体成立。

从 agent engineering 的角度看，这个语义比表面更重要，因为它暗示了一种未来可能：

agent 的一次完整思考/执行周期，不只是连续若干调用，而是可被整体提交的执行事务。

Hook 和 Wrap：它的克制，反而是优点

在 src/vek/hooks.py 里，Vek 提供了两种非常轻的接入方式：

• @vek.wrap
• vek.hook(dispatch_fn)

这让我觉得它最有气质的一点是：

它没有试图先定义 agent，再要求 agent 迁就它。

相反，它承认外部世界已经有各种 harness、dispatcher、tool registry、agent loop，于是它只做一件事：

给你一个足够轻的入口，把执行过程挂进自己的历史层。

这和很多 agent framework 的思路正相反。后者通常先定义抽象，再要求你把世界塞进去。Vek 的做法更像底层基础设施：

你继续用你的系统，我只负责让执行历史可管理。

这正是我觉得它值得认真看的地方。

真正有意思的部分：branch、merge、replay、diff

如果说 store 只是证明它能记录 history，那么 branch / merge / replay / diff 才真正暴露了它的野心。

branch / fork

在 Vek 里，agent 的执行路径不必永远是一条线。

你可以从某个节点 fork 出新的分支，沿着另一条路径继续试验。这意味着：

• 不同 prompt 方案可以从同一祖先继续
• 不同 tool strategy 可以并行探索
• 某一步出现坏结果时，不必覆盖历史，而是从旧节点另起分支

一旦 execution history 支持分叉，agent 的“尝试”就不再只是临时状态，而变成了一种可以被管理的实验图。

merge

src/vek/api.py 里已经实现了 merge node，tool 名字是 __merge__，并记录双亲：

• parent_hash
• merge_parent

这件事的意义不只是“和 git 更像了”，而是开始触碰一个很少被认真讨论的问题：

当 agent 沿两条路径做过不同尝试之后，我们如何定义“合并”它们的结果？

今天的 Vek 给出的还是一个结构层答案，而不是语义层答案。它先把 merge 这件事作为历史原语记录下来，至于真正怎么 resolve 语义冲突，还没有进一步展开。

但仅仅做到这一步，就已经比大量只能线性回放的 agent trace 系统更前进了一层。

replay

replay 的存在，让执行历史第一次真正变成“可回到现场”的东西。

不是看日志摘要，而是从 root 到 tip，把每一步的 input/output materialise 出来。
这对于 debugging、analysis、benchmarking、agent eval 都是非常重要的能力。

diff

diff 也是很有意思的一环。
Vek 在 src/vek/graph.py 里实现的是结构化 JSON diff，而不是纯文本 diff。

这非常适合 agent world，因为很多工具输入输出本来就是 JSON-compatible 对象。
换句话说，它在试图把“比较两次 agent 执行”这件事，从文本层提到结构层。

它为什么不是框架，反而更有价值

我最近越来越认同一个判断：

agent 开发不应该先被框架化，而应该先被身体化。

所谓“身体化”，包括：

• tool registry
• execution loop
• context/state
• memory layer
• execution history

Vek 很适合放在这个语境里看。

它没有去定义 planner、state machine、workflow DSL，也没有试图跟 LangChain、AutoGen、LangGraph 在“编排能力”上竞争。
它更像是在说：

你们继续争论上层框架，我先把执行历史这件更基础的事认真做出来。

这也是为什么我觉得 Vek 的方向比“又一个 agent framework”更值得写。

框架在很多时候提供的是秩序，但也经常带来遮蔽。
而像 Vek 这样的底层层，提供的不是抽象控制权，而是：

历史的可见性、可操作性与可验证性。

它的边界也很清楚

一个项目越值得认真写，越不该只写它的优点。

Vek 现在仍然是 alpha，而且边界非常明确。

1. 它已经有 DAG 语义，但底层遍历还没有完全 DAG 化

merge_parent 已经进入 schema，merge 也已实现。
但 src/vek/db.py 里的 walk() 仍然只沿 parent_hash 回溯，不沿 merge_parent 走。

这意味着：

• 它的图模型已经开始形成
• 但很多底层遍历还是“单链历史优先”

也就是说，Vek 正在从线性历史走向真正的 execution DAG，但还没彻底走完。

2. 并发故事已经开始，但还没有完全闭环

README 里提到：

• SQLite WAL
• busy timeout
• HEAD.lock

这些都说明它已经意识到并发写入的问题。
但从实现上看，锁的覆盖范围和 async 情况下的边界，仍然有继续收紧的空间。

3. 它更像 provenance layer，而不是严格可复现实验机

Vek 当前很适合做：

• execution history capture
• chain replay
• branch experiment tracking
• diff / audit / export

但如果你想把它当成“任意 Python 对象都能百分之百 deterministically replay 的执行机”，现在还不现实。

这不是缺点，而是定位问题。
我更愿意把它理解成：

一个正在成型的 execution provenance layer。

Vek 真正重要的地方

如果只把 Vek 看成一个 Python 小库，它会显得过于克制。
但如果把它放回 agent infrastructure 的脉络里，它就会开始变得有分量。

因为它触碰的是一个越来越重要、却还没被广泛标准化的问题：

AI Agent 的执行历史，应该拥有像代码历史那样的第一公民地位。

代码有 Git，不只是因为代码需要备份，而是因为：

• 代码会演化
• 代码会分叉
• 代码需要回滚
• 代码需要对比
• 代码需要被审计

而 agent execution 迟早也会遇到同样的问题。

当一个 agent 不再只是“帮你调一个 API”，而是要在真实系统里运行、试错、调用工具、长期积累路径时，execution history 迟早会变成基础设施，而不是附属日志。

从这个角度看，Vek 的价值并不只在于它现在已经实现了多少，而在于它选对了问题。

它不是在问：

怎样让 agent 再多一个能力？

而是在问：

当 agent 开始真正运行之后，我们用什么来管理它的历史？

这是一个更底层，也更长期的问题。

结语

我很喜欢 Vek 的地方，在于它没有试图显得更大。

它不假装自己是完整 agent platform，也不急着把自己包装成 orchestration framework。
它只是做了一层小而硬的东西：给 AI Agent 的 tool-call history 装上 content-addressing、branch、merge、replay 和 diff。

在今天这个 agent 生态里，这种克制反而显得难得。

对我来说，Vek 最有价值的启发不是“可以拿来直接替代什么”，而是提醒我们：

Agent 不只需要更聪明的大脑，也需要更可靠的身体。

而 execution history，正是这具身体的一部分。

项目地址

GitHub: AVIDS2/vek