Gnomon：为智能体打造的 Postgres 数据 Git

仓库文件导航

Gnomon

为 Postgres 数据打造的 Git，专为 agent 而生。给 agent 一个属于它自己的、你真实数据库的分支，只需一个连接字符串。查看它改动了每一个字段，正确就合并进 main，不正确就撤销。

Gnomon 运行在你已有的 Postgres 内部。一个扩展，没有副本，没有第二个数据库。

        create extension gnomon;
select gnomon.track('orders');                    -- 从此刻开始记录历史，不回填

select gnomon.create_branch('agent/refunds');
select gnomon.use('agent/refunds');

-- 从这里开始的每条查询都在该分支上执行
update orders set status = 'refunded' where id = 4182;

select * from gnomon.diff('agent/refunds');       -- 它改动的每一行和每个字段
select gnomon.merge('agent/refunds');             -- 三方合并、类型感知，冲突以行的形式呈现
select gnomon.undo_merge(1);                      -- 再撤销回去
      

• 文档：https://gnomon.bitsinfra.com/

• 安装：在 PostgreSQL 15-18 上 create extension gnomon，自托管或托管服务（RDS、Aurora、Supabase）均可。参见 Installation。

• 刚接触？教程只需十分钟。

瞬间得到一个生产分支

分支从 main 读取全部内容，只保留它改动的部分，因此无论你的数据库多大，它都能瞬间打开，且不复制任何数据。给每次 agent 运行、每个 pull request 和每个测试都分配一个分支。

你的应用无需改动。分支就是一个连接字符串：把一个会话指向它，它原本就在运行的查询便会读写该分支，而不是 main。

schema 变更也会一并带上。在分支上运行迁移来新增列、重命名列或创建表，main 会保持原样直到合并，合并时新的结构和它的数据会一起带过来。

像审查代码一样审查数据

每个分支都附带 diff：它改动的每一行、每个字段，改动前与改动后。在浏览器里审查，对单独一行添加评论，并排解决冲突。agent 完成后，Gnomon 会打开审查页面并把链接发给你。

添加用 SQL 编写的检查，Gnomon 会在允许合并落地之前，先在合并后的结果上运行它们。一次批准只覆盖你所看到的内容：如果分支之后又发生变化，它会重新回到你手上。

懂你数据的合并

当 main 和分支改动了同一个值时，Gnomon 不会简单地选一边。计数相加，JSON 按键合并，文本按行合并。真正冲突的内容会成为 conflict，交由人来裁决，或由查询来解决。

分支之间也能互相合并，不只并入 main，单个事务还可以从一个分支挑到另一个分支上。撤销同样如此：撤回一个事务、某个 agent 今天下午做的所有事，或者一整次合并。

任何一个时刻，原样重现

Gnomon 会保留你追踪的每一张表的历史。用你已有的查询，读取整个数据库在任意时刻的样子，每次都会得到相同的结果。当 agent 做出决策时，你能确切看到它当时看到的内容。

        -- 十月底尚未结清的发票
select gnomon.use('main', '2026-10-31 23:59');
select sum(amount) from invoices where status = 'open';
      

同样的历史会在发生时实时流出，发送到 Kafka、NATS 或 webhook，并以保留已删除行的 snapshot 形式进入 dbt。更早的历史可以迁移到对象存储，当查询涉及那么早的数据时，Gnomon 会把它取回来。

当某个原本通过的检查开始失败时，gnomon bisect 会找出破坏它的那个事务：谁做的、什么时候、为什么。

可以放心交给 agent

一条命令就能给 agent 一个数据库角色、一条专属分支和一个连接字符串。无论用什么构建，它需要的就这些。它读写自己的分支，数据库拒绝其余一切，包括 main，哪怕 agent 点名要求。

        # 一个数据库角色、一条专属分支和一个连接字符串
gnomon agent create support-bot
      

• 只合并你允许的内容。合并是留给你选定的人，或留给你写下规则的 agent：最多二十行、仅限这些表、所有检查通过。无论 agent 被告知什么，Postgres 都会强制执行。

• 未经你批准，什么都不会外流。agent 排队的邮件、webhook 和付款都留在它的分支上，直到合并。

• 每一处变更都有名字。每处变更记录 agent、运行和它给出的理由。

• 重放它看到的内容。Gnomon 记录每次读取的时刻，因此重放会精确返回 agent 读到的那些行。

• 同时尝试几种方式。从同一时刻开始多次尝试，比较它们的变更和检查，保留最好的一个。

• 停掉它，再收回。一条命令即可将 agent 锁在外面、关闭它的分支并撤销它合并的内容，从最新的开始。

• 为你的 agent 做好准备。Gnomon MCP server 可以运行在 agent 的机器上或通过 HTTP 提供，让 agent 探索 schema、试做变更而不保留，并把它的分支回退到检查点。

把它构建进你的产品

TypeScript 和 Python SDK 为 agent 承担的每个任务提供一次运行：一条专属分支，限制已设好。合并它、送审，或放手。

        import { Gnomon } from "@bitsinfra/gnomon";
import { nodePostgres } from "@bitsinfra/gnomon/pg";

const gnomon = new Gnomon({
  app: nodePostgres(appPool),   // your application's own login
  runs: nodePostgres(runsPool), // one login shared by every agent run
});

// A branch for this task, discarded unless it's merged or submitted
await using run = await gnomon.startRun({
  task: "Refund order 4182",
  actor: "support-bot",
});
await run.sql("update orders set status = 'refunded' where id = 4182");

const { checks, changes } = await run.summary();
if (checks.passed && changes.rows <= 20) await run.merge();
else await run.submit({ title: "Refund order 4182" });
      

即使共享同一个数据库登录，各次运行也无法读取彼此的分支。带上你已在使用的 agent 框架：Anthropic SDK、Claude Agent SDK、Vercel AI SDK、OpenAI Agents SDK、LangChain 或任何 MCP 客户端，都会得到同样几个工具，绑定到一次运行。它们通过你的驱动和 ORM 工作，从 node-postgres 和 Prisma 到 psycopg 和 Django。而在你的测试中，每个测试都有一条自己的分支，来自同一个已播种的数据库。

        npm install @bitsinfra/gnomon      # TypeScript
pip install gnomon-postgres  # Python
      

盒子里有什么

文档

一切都在 https://gnomon.bitsinfra.com/ ，同样的页面也存在于 docs 中：

• 安装与教程

• 概念：分支、坐标、合并

文章标题：Gnomon. 面向 agent 的 Postgres 数据版 Git

正文：

• agent、run 与 SDK，MCP server

• 分支、schema 变更、评审、合并

• 历史与时间旅行、变更流

• SQL 参考、CLI 参考、错误

• 运维、安全、基准测试

• 面向编码 agent 的 llms.txt

许可证

Gnomon 是在 PostgreSQL License 下开源的。欢迎贡献：见 CONTRIBUTING.md。安全问题请按 SECURITY.md 中所述私下报告。