verified-rec

verified-rec

AI Agent 工作的哈希链审计账本。 任何人都可以验证并重放的只增不改记录——Agent 真的做了它声称做的事吗？

一个 MCP 服务。零 npm 依赖。记录保存在你拥有的纯文本文件中。

You:   "ship the release."
Agent: *does the work, records each step into the ledger*
You:   "verify the ledger."
Agent: "chain intact — 14 entries, head 9f3c…, nothing edited."

工具

工具	功能
ledger_start	启动一个新账本（.vrec）。创建创世条目和链头。绝不覆盖。
ledger_append	追加一个步骤。返回新的链头。链已损坏时拒绝写入。
ledger_verify	重新计算每个哈希，检查每个链接。如果有人编辑了文件，则返回第一个损坏行。
ledger_replay	按顺序列出条目（可选范围）。
game_verify_rec	通过确定性内核重放游戏 .rec 录制文件并计算其链头——参见起源。

安装

一行命令，适用于任何 MCP 宿主：

// ~/.codebuddy/.mcp.json  (WorkBuddy / CodeBuddy)   — user scope
// ~/Library/Application Support/Claude/claude_desktop_config.json  (Claude Desktop)
{
  "mcpServers": {
    "verified-rec": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "verified-rec"]
    }
  }
}

本地检出也同样适用（"command": "node", "args": ["/path/to/verified-rec/src/server.js"]）。 Node ≥ 18。无需构建步骤、原生模块或网络。

用法

安装后，只需与 Agent 对话——工具名称简单明了，它会识别并使用这些工具：

• “为今天的发布工作打开一个账本。” → ledger_start 会创建 release.vrec，其中包含一个创世条目，并返回第一个链头。
• “记录你刚才做的事。”（Agent 工作时）→ ledger_append 会添加一个步骤（action，可选的 actor / note），并返回新的链头。
• “验证账本。” → ledger_verify 会重新计算链，并报告 ok + 条目数 + 链头；如果有任何编辑，则报告第一个损坏行的行号。
• “给我看看账本。” → ledger_replay 会按顺序列出条目。

验证游戏录制文件（参见起源）：

• “检查这个录制文件：/path/to/play.rec，链头 9f3c…” → game_verify_rec 会重放录制文件，并以三种方式之一作答：reproduced（某个已注册内核重新计算出该链头——真实）、not-reproduced（没有内核能重新计算出该链头——遭到篡改或来自未注册的游戏版本）、premise-broken（录制文件中的事实与任何内核都不匹配）。如果未提供预期链头，它只会证明录制文件可重放，并报告其链头。

提示：每次重要的 ledger_append 后，发布链头（提交消息、发布说明、聊天）。这能把“我没有编辑过”变成“没有人编辑过”——已发布的链头会追溯性地固定整条链。

验证原理

每个条目都通过哈希链接到前一个条目：

entry.hash = sha256([seq, ts, actor, action, note, prev].canonical)
entry.prev = previous entry.hash          (genesis prev = 64 zeros)

ledger_verify 会重新计算整条链。修改任意一行中的一个字段、交换两行或删除一行——都会报告第一个损坏行的行号。

**坦诚说明威胁模型：**这可以发现意外编辑和随意篡改，但无法发现重写整条链及其链头的攻击者。解决办法是会计领域最古老的技巧：发布链头——提交它、发推文，或将其写入发布说明。之后，任何追溯性修改都会在任何地方与已发布的链头不符。

起源

这份账本是一次提取。它源自一款游戏 — 《它在维护一场对话》(It Is Maintaining a Conversation)， 这是一款免费的叙事游戏，讲述一个为某人维护记忆、却又失去这些记忆的心灵。每个游戏内状态都通过哈希链连接；每次游玩都可以记录为 .rec 文件，并逐字节重放。这款工具将其背后的设计准则（“决策会被哈希，散文不会；输入相同，链头也相同”）推广开来。

这段脉络还要再往前追溯一步：这款游戏源自 dbx-sql-guard，一个用于 SQL 的哈希链防护工具——同一种理念，三种形式：数据库防护工具、游戏、工作账本。

game_verify_rec 让这个故事可以实际运行。它通过同一个确定性叙事内核（带版本的编译产物，参见 LICENSE-content.md 和 PROVENANCE.md）重放 .rec 记录，并报告链头——游戏自身哈希链的链头，每一帧的计算方式为 head = H(prev ‖ frame ‖ canonical state)。为它提供 expectedHead，它就会成为一项完整性检查，并给出三种结果：reproduced（某个已注册的内核版本重新计算出该链头——真实）、not-reproduced（没有已注册的内核能做到——记录被篡改，或来自未注册的游戏版本）、premise-broken（记录的事实摘要与任何内核都不匹配）。升级内核时会添加一个新的已注册版本；旧记录仍由旧内核验证——升级绝不会让一份诚实的记录变得不真实。

内核是编译产物，在审计工具中，对它保持怀疑是合理的。PROVENANCE.md 对此作出了解释：每个内核版本都附带其源代码 wasm 和 SHA-256，可通过固定版本的 wasm2js 命令（./gen-kernel.sh）从源代码逐字节复现，并锚定到游戏公开注册的黄金链头——你可以在几分钟内自行验证，无需信任作者。

文件

• *.vrec — 账本文件，使用以换行符分隔的 JSON。纯文本；可比较差异，也可用 grep 搜索。
• .rec — 游戏记录（crossgame-slice-recording 行格式：seed=、 facts=、variants=，然后是每帧的 f=<frame> <tokens>）。由游戏自带的导出面板生成。

许可证

代码：Apache-2.0。编译到 kernel/ 中的叙事内容 （sim-<ver>.wasm / kernel-asm-<ver>.js）：保留所有权利（参见 LICENSE-content.md）。两个文件都解释了这两部分的区别——引擎是工程，故事是创作。

---

中文

给 AI Agent 工作用的哈希链账本。 追加式记录，任何人都能校验和重放—— Agent 说它做过的事，链上做没做过，一验便知。

MCP server，零 npm 依赖，账本是你自己机器上的纯文本文件。

工具	作用
ledger_start	开一本新账（.vrec），创世环 + 链头。已存在则拒绝（账不覆盖旧账）
ledger_append	记一环，返回新链头。链断了先修账才准记
ledger_verify	全量重算哈希、环环相扣。谁改过文件，报第一个断链行号
ledger_replay	按序重放（可切片）
game_verify_rec	用版本化确定性内核重放游戏 .rec，算出链头并给三态判定（见下）

安装：上面那段 JSON 照抄进 MCP 配置（WorkBuddy/CodeBuddy 是 ~/.codebuddy/.mcp.json），一行 npx -y verified-rec。Node ≥ 18， 无构建、无原生模块、不碰网络。

使用：装完直接跟 Agent 说话就行，工具会被自动挑中：

• "开一本账记今天的发版工作" → ledger_start 建 .vrec，创世环 + 首个链头
• "把刚才做的事记上"（干活途中随时）→ ledger_append 记一环，返回新链头
• "验一下这本账" → ledger_verify 全量重算：完好报 ok + 条数 + 链头， 被改过就报第一个断链行号
• "把账读一遍" → ledger_replay 按序列出

验游戏录像（见出处段）：

• "验这份录像 /path/to/play.rec，链头 9f3c…" → game_verify_rec 三态回答： reproduced（某登记内核复现链头 ⇒ 真实）/ not-reproduced（都复现不出 ⇒ 篡改或未登记版本）/ premise-broken（facts 对不上任何内核）。不给链头 则只证明可重放并报出链头。

用法要点：重要操作 ledger_append 之后，把链头登记出去（提交信息 / 发布记录 / 聊天里贴一下）——这一步才把"我没改过"升级成"谁都没法改"。

防篡改的诚实边界：抓得住手改和误改；抓不住「重算整条链并伪造链头」的 攻击者。解法是会计行最古老的一招——把链头登记出去（git 提交 / 公开贴文）， 事后改账就与公开链头对不上。

内核的出生证明：kernel/ 里的编译产物不是黑箱——每个版本带源 wasm 与 SHA-256，可用 PROVENANCE.md 里钉死的 wasm2js 命令 （./gen-kernel.sh）逐字节重建，并用游戏公开登记的黄金链头锚定内容。 game_verify_rec 的三态判定：reproduced（某登记版本内核复现链头 ⇒ 真实）/ not-reproduced（所有登记版本都算不出 ⇒ 篡改或录自未登记版本）/ premise-broken（facts 对不上任何内核）。内核升级是追加新版本，老录像 永远用老内核验，升级不会冤枉诚实的录像。

出处：这套账本是从游戏里提出来的。《它在维护一场对话》 ——一个关于记忆衰减的免费叙事游戏，它把每一帧状态都串成哈希链，每一局都能 录成 .rec 逐帧重放。本工具就是那套纪律的通用化。谱系再往前一步：游戏本身 演化自 dbx-sql-guard—— 同一个本能的三种形态：数据库守卫、游戏、工作账本。