English | 简体中文
worldcheck 是编码代理的测试世界检查点工具。 给每个任务一份可播种的一次性测试世界:一条命令拉起 compose + seed.sql,验证前打一个 checkpoint,验证后输出机器可核验的变更对比——文件增删改、行级增删改、schema 是否被动过。Agent 声称的「测试通过」,从此可以被复核。
免费开源(MIT),单一 Go 二进制,无配置文件,只依赖本机 Docker。
把一个涉及数据库的任务交给 Coding Agent:它会自己发明测试数据、自己起环境、自己验证,然后报告「测试通过」。你看到的是绿色,看不到的是它在那个世界里改了什么——为了让自己的测试变绿,它可能改掉一条 fixture 行,甚至悄悄改掉表结构。
问题不在测试本身,而在验证环境不可审计:那个世界是 agent 私自搭的,没有基线,无法重置,也就无法回答「为了凑绿,它到底动了什么」。
worldcheck 从源头接手这件事:世界由工具播种,状态由工具度量,验证前由工具打点。v0.2 交付了完整的一对能力——可复现的种子世界(m1)与检查点 + 变更对比(m2):checkpoint 在验证前定格世界的文件基线与数据库快照,diff 事后回答它到底动了什么。
一个二进制,一个外部依赖(Docker CLI,通过 stdio 调用,不用 SDK,不与 daemon 版本耦合):
- provisioner ——
up读取世界目录里的compose.yml与seed.sql:docker compose down -v清空旧世界,up -d起服务,自己对目标库跑一条真实查询、等它真的能应答(不是等 socket 能连——postgres 镜像的 initdb 临时服务也会接连接),psql灌入种子,pg_dump抓取完整状态; - checkpoint ——
checkpoint <label>记录每个容器的docker diff文件基线,并把数据库快照存进世界目录的checkpoints/; - differ ——
diff <label>重新采集两者并对比:文件系统的 A/C/D、按主键对齐的行级增删改、schema 是否变化; - manifest / report(终端部分) —— 种子 sha256、服务与镜像、每张表的行数、整体状态指纹写进
manifest.json;status与diff把它渲染成表格。
没有常驻进程,没有自己的数据库,没有 Kubernetes。状态只存在于 Docker(compose 卷)和世界目录里:manifest.json、checkpoints/,以及未来 m3 的 worldcheck.html。
go install github.com/SuperMarioYL/worldcheck/cmd/worldcheck@latest或从源码构建(需要 Go 1.24+):
git clone https://github.com/SuperMarioYL/worldcheck.git
cd worldcheck && go build ./cmd/worldcheck运行环境要求:本机 Docker daemon 在跑(macOS / Linux;Windows 不在范围内)。无需任何配置文件。
自带的世界是 worlds/postgres-starter:一个 postgres:16-alpine 单服务 compose 项目加一份种子 SQL,镜像很小,拉取不会拖垮「一分钟内看到结果」的预算。
1. 播种世界(真实输出,见 docs/demo-results.json):
$ worldcheck up --world worlds/postgres-starter
world postgres-starter provisioned (project wc-postgres-starter)
service db (postgres:16-alpine)
table projects: 3 rows
table tasks: 6 rows
table users: 4 rows
manifest written to manifest.json
seeded-state fingerprint: bbc332815fe79e0680b313ee0ce12ead8bb24cc39cf3e0d94533de00cf8e1b3dup 永远从零开始:先清空这个世界的卷,再播种;播种前它会自己等目标数据库能应答真实查询,所以你的世界不需要在 compose 里写 healthcheck。世界是一次性的,up 从不往旧状态上叠加。
2. 验证前打一个检查点:
$ worldcheck checkpoint t1 --world worlds/postgres-starter
checkpoint t1 recorded
filesystem baseline: 4 path(s) across 1 container(s)
database snapshot: sha256:bbc332815fe7
record: checkpoints/t1.json3. 让验证跑起来,然后看它动了什么:
$ worldcheck diff t1 --world worlds/postgres-starter
checkpoint t1
mutations files 1 added / 1 changed / 0 deleted; rows 0 inserted / 1 updated / 0 deleted; schema unchanged
KIND CONTAINER PATH
ADDED wc-postgres-starter-db-1 /tmp/agent-note
CHANGED wc-postgres-starter-db-1 /tmp
KIND ROW
UPDATED tasks[id=6] = 6 | 3 | keep diffs mechanical | f -> 6 | 3 | keep diffs mechanical | t上面这一次 diff 抓住的,正是一个偷偷把自己那条 fixture 改绿、又在世界里留下文件的 agent。行级对比按主键对齐(主键从数据库目录里读,不是猜的);schema 有没有被动过单独给一个布尔结论。
4. 查看状态与指纹:
$ worldcheck status --world worlds/postgres-starter
world postgres-starter
project wc-postgres-starter
seed seed.sql (sha256:2a2fb32475ae)
database app
provisioned 2026-10-22 19:28:43 UTC (worldcheck 0.2.0)
SERVICE IMAGE
db postgres:16-alpine
TABLE ROWS
projects 3
tasks 6
users 4
fingerprint (sha256:pgdump-schema-and-data-sorted-lines)
bbc332815fe79e0680b313ee0ce12ead8bb24cc39cf3e0d94533de00cf8e1b3d验收标准,一条命令验证:改一行 seed.sql,重跑 up,指纹必然改变;不改,指纹必然不变:
$ echo 'UPDATE tasks SET done = true WHERE project_id = 2;' >> worlds/postgres-starter/seed.sql
$ worldcheck up --world worlds/postgres-starter | tail -1
seeded-state fingerprint: 63d0e70e2f5465aa5f376217b788827bcad18fbf802bd198493ca806ff485eff指纹覆盖的是世界的完整状态——schema 加数据,不只是数据。所以只加一个索引、只去掉一个 NOT NULL 也会让指纹改变,不会被当成「什么都没发生」。
下面这段演示记录了 m2 的完整闭环:播种 → 检查点 → agent 悄悄改绿 → 变更对比当场抓住(每一帧都是真实命令与真实输出,与 docs/demo-results.json 记录的运行对应;帧间隔切换,非录屏)。
这份仓库所在机器上 vhs 无法完成编码,所以提交的 GIF 是由真实会话记录渲染的静态帧;仓库同时带有 docs/demo.tape(vhs 脚本)与 docs/demo-record.sh(一键重录脚本),在 vhs 可用的环境跑一次即可替换为真正的终端录屏。计划中的最终演示(run 把验证命令与变更对比合成一份对账报告)依赖 m3,将在该里程碑落地后重新录制替换。
| 能力 | 状态 | 说明 |
|---|---|---|
worldcheck up --world <dir> |
已实现 | 清空重播世界:compose 起服务、等数据库就绪、灌种子、写 manifest.json、打印指纹 |
worldcheck status --world <dir> |
已实现 | 从清单打印服务、表行数与状态指纹 |
| 状态指纹 | 已实现 | 完整 pg_dump(schema + 数据)去噪排序后取 sha256;同种子必同指纹,改数据或改 schema 必改指纹 |
worldcheck checkpoint <label> --world <dir> |
已实现 | 验证前定格:每个容器的 docker diff 文件基线 + 数据库快照,存进 checkpoints/ |
worldcheck diff <label> --world <dir> |
已实现 | 对比检查点之后的文件 A/C/D、按主键对齐的行级增删改,以及 schema 是否变化 |
worldcheck run -- <verify-cmd> |
路线图(m3) | 串起 checkpoint → 执行 → 对比 → 对账报告 |
明确的非目标:不做 Web 界面(报告是静态 HTML);不做 MCP 或「通用 agent 协议」;checkpoint/diff 只支持 Postgres,本地 Docker only;不做回滚——worldcheck 只审计,不倒带;diff 纯机械(docker diff + pg_dump),不引入 LLM 判断。
没有配置文件,一切从世界目录读取:
worlds/postgres-starter/
├── compose.yml # 世界定义:服务、镜像(healthcheck 可选,worldcheck 自己会等就绪)
├── seed.sql # 基线状态:建表 + 固定种子数据
├── manifest.json # 生成物(up 写入,不入库):种子清单 + 状态指纹
└── checkpoints/ # 生成物(checkpoint 写入,不入库):<label>.json + <label>.dump
复制这个目录就是你的新世界。provisioner 遵守两条约定:compose 里必须有一个名为 db 的 Postgres 服务;POSTGRES_USER / POSTGRES_DB 环境变量告诉它种子和指纹走哪条通道——这两个变量既可以写成映射(POSTGRES_USER: postgres),也可以写成 docker compose config 会归一化成的列表形式(- POSTGRES_USER=postgres)。默认不发布宿主机端口——两个世界不会抢 5432,agent 的验证命令通过 compose 项目访问数据库(docker compose -p wc-postgres-starter exec db psql ...);需要宿主机套接字时,在你的世界副本里加 ports: 映射即可。
检查点标签会变成 checkpoints/ 下的文件名,所以只接受字母、数字、点、横线和下划线。
- m1 — 播种世界(已完成):
up+status+ 种子清单 + 状态指纹。 - m2 — 快照与对比(已完成,即本版本):
checkpoint <label>在验证前定格世界;diff <label>输出机器可核验的文件 A/C/D、按主键对齐的行级增删改与 schema 变化。 - m3 — 运行与对账:
run --label <label> -- <verify-cmd>串起 checkpoint → 验证 → 对比,渲染终端 +worldcheck.html对账报告,验证命令失败即非零退出;录制完整演示。
MIT © 2026 SuperMarioYL。欢迎 issue 与 PR。
MIT © 2026 SuperMarioYL
