文档快照锁 fbzz/readproof

Website · Docs · Install · Quickstart · Example agent · MCP · DeepSeek Harness · Roadmap

Readproof 给智能体读的每份文档一个稳定标识、一套新鲜度策略、一份内容寻址快照——并把每次运行记录成 manifest，你可以对它做 diff，可以逐字节重放而不碰线上源，也可以把它当作证据交出去。

模型是概率性的，但很多上下文故障其实是基础设施问题。
智能体的可靠性，上限由上下文的可靠性决定。

它不是向量数据库，不是可观测性工具，不是提示词注册表，不是记忆系统。它位于这些东西之下，让它们的输入变得可复现。安装期 lockfile（Microsoft APM、skills-lock.json）锁定智能体的静态配置；Readproof 锁定的是运行时文档，按每次运行。

六十秒，从头到尾

1. 给文档一个标识和一套新鲜度策略，然后记录一次运行。

readproof resource add readproof://demo/policies/refunds \
--source-type filesystem --path policies/refunds.md --policy require_fresh
readproof run --id run-a readproof://demo/policies/refunds
Committed manifest manifest_01M0GQH8K8… for run run-a (1 entry)

2. 源变了。后一次运行会捕捉到——diff 会明说原因。

printf 'Products can be refunded within 14 days.\n' > policies/refunds.mdtext
readproof run --id run-b readproof://demo/policies/refunds
readproof diff run-a run-b
text
~ readproof://demo/policies/refunds
why: source revision sha256:c8b0bb212e93 → sha256:8f4b00474456
-Products can be refunded within 30 days.
+Products can be refunded within 14 days.

3. 从存储中重放第一次运行——文件已经没了或变了，字节还在——并证明它。
text
readproof replay run-a
readproof evidence export run-a --with-content --out bundle.json
readproof evidence verify bundle.json
text
Products can be refunded within 30 days.
Replay verified: SHA256 match for 1/1 entries.
evidence verified: 1 entry, merkle root a9b73469f1a6…, replay match 1/1

SHA256(original) == SHA256(replay) 是测试，不是口号：参考 demo 在 SQLite、Postgres + MinIO，以及一次真实的 HTTP 往返上都断言了这一点（examples/refund-agent）。

为什么

| 你见过的故障 | Readproof 怎么处理 |
| 「周二还好好的。」 策略、价格表或运维手册变了，智能体悄悄按另一个版本回答。 | 每次运行都会记录它读了每份文档的哪个修订版；readproof diff run-a run-b 会指出变化的源修订版和观测时间，然后打印统一 diff。 |
| 「能一模一样地重跑一次吗？」 追踪工具只留字符串；源一变，它们就没法再把字节交给你。 | readproof replay 从内容寻址存储重建一次运行的输入，并重新校验每个哈希——不联网，不碰源。严格模式：任何不匹配都以非零码退出。 |
| 「智能体参考了哪些数据？」 EU AI Act 第 12 条日志要求（附件 III，2026 年 8 月 2 日起）和 SOC 2 审计问的正是这个。 | readproof evidence export 写出一份 in-toto Statement，其 subject 是覆盖该次运行的 Merkle root；verify 可在任何地方校验它。这不是法律意见——但它是记录。 |

工作原理

- 身份 —— readproof://<namespace>/<path>，与字节实际存在哪里无关。
- 策略 —— require_fresh（每次解析都重新校验）、allow_stale --max-age（在 TTL 内复用），或用 tag 固定一个已审阅的快照：…@prod 交付的正是那个快照，不抓取，也不查策略。晋升只是移动一个指针；它会被记录，也可回退。
- 快照 —— 不可变，内容寻址；字节相同的会去重成一个 blob。
- 清单 —— 一次运行被交付内容的按序列表，以哈希标识；条目会记录它们挂载时用的 ref，所以之后移动 tag 永远不会改变已提交清单重放出的内容。
- 证据 — 按需从清单派生；Go 命令行与 TypeScript SDK 产出字节级一致的 bundle，同一个 Merkle 根会出现在本次运行的 OpenTelemetry span 上。

深入阅读：docs/architecture.md。

快速开始

安装 bash

Go 1.26+ — lands in $(go env GOPATH)/bin

go install github.com/fbzz/readproof/cmd/readproof@latest
go install github.com/fbzz/readproof/cmd/readproofd@latest # only if you run the server

macOS — the cask installs both binaries

brew install fbzz/tap/readproof

或者从 GitHub Releases 下载对应平台的预编译压缩包： readproof_<version>_<os>_<arch>.tar.gz（Windows 上是 .zip），里面包含 readproof、readproofd、LICENSE、NOTICE 和这份 README。

说白了：等这个仓库公开、第一个 release 切出来之后，上面三种方式都能用。在那之前，从源码构建 —— 反正下面内嵌的走查流程也是这么做的。

内嵌模式

一个二进制，一个本地 .readproof/ 目录，不需要任何服务： bash
git clone https://github.com/fbzz/readproof.git
cd readproof
go build -o readproof ./cmd/readproof # Go 1.26+

identity + source + freshness policy

./readproof resource add readproof://demo/policies/refunds \
--source-type filesystem \
--path examples/refund-agent/policies/refunds.md \
--policy require_fresh

./readproof run --id run-a readproof://demo/policies/refunds
./readproof replay run-a

客户端/服务端模式

Postgres + 兼容 S3 的存储，所有客户端共用一个 HTTP API： bash

Postgres, MinIO, an OTel collector and readproofd, from a clean clone

cp .env.example .env
docker compose up -d --build

every command now talks to the server

export READPROOF_SERVER_URL=http://localhost:8080
./readproof get readproof://demo/policies/refunds

跑在容器里的 readproofd 看不到你宿主机的文件系统；这种场景请用 GitHub/HTTP 源，或者把 readproofd 跑在宿主机上：

bash
--filesystem-root allow-lists the directories a filesystem source may read.
Without one, readproofd refuses filesystem sources outright — registering a resource would otherwise let any caller read any file the server can. readproofd --data-dir ~/.readproof --filesystem-root "$PWD"

同样的默认拒绝也适用于 ${VAR} 请求头（--header-env-allow NAME）和私有网络目标（--allow-private-sources）。这些都不适用于内嵌命令行，它以你的身份读你自己的文件。参见 docs/api.md 和 SECURITY.md。

接入你的编码智能体

两分钟，两条路任选 —— 或者都来。

A. 把工具交给智能体（MCP）。
bash

Claude Code

claude mcp add readproof -- readproof mcp --data-dir ~/.readproof

DeepSeek Harness

dsh plugin --profile web add ./integrations/deepseek-harness/dsh-plugin-readproof && dsh web

Cursor / Claude Desktop (mcpServers):

{"command": "readproof", "args": ["mcp", "--data-dir", "~/.readproof"]}

智能体会拿到 readproof_resolve、readproof_run_、readproof_diff、readproof_replay、readproof_tag_、readproof_evidence_export；每次 resources/read 都会在 _meta 里带上来源信息。详见 docs/mcp.md。

B. 让智能体养成习惯（技能）。 安装技能文件，或者把下面这段贴进 CLAUDE.md、AGENTS.md 或 .cursor/rules/readproof.mdc。
bash
mkdir -p .claude/skills/readproof && curl -fsSL \
https://raw.githubusercontent.com/fbzz/readproof/main/skills/readproof/SKILL.md \
-o .claude/skills/readproof/SKILL.md
markdown

Readproof — record exactly what you read

When a task reads a document that must be reproducible (policies, runbooks,
specs, prices), read it through Readproof, never directly:
1. readproof run start <task-id>
2. readproof run mount <task-id> readproof://<ns>/<path>[@prod] ← use the bytes it prints
3. readproof run commit <task-id> → put the manifest id in your output / PR / ticket
Single shot: readproof run --id <task-id> <uri> <uri>… Register once: readproof resource add readproof://<ns>/<path> --source-type filesystem|github|http … --policy require_fresh|allow_stale Explain a change: readproof diff Reproduce: readproof replay <id> Prove: readproof evidence export <id> --out bundle.json readproof evidence verify bundle.json Deploy a document by moving a tag (readproof tag set <uri> prod <snapshot>), never by editing the file in place. Never paste secrets into resource
definitions (use ${ENV_VAR} headers); never touch the data directory by hand.

带完整安装步骤、策略和禁忌事项的版本：skills/readproof/SKILL.md。

你能得到什么

| 命令行 readproof | resource · get · inspect · history · run · manifest · diff · replay · tag · evidence · mcp —— 内嵌模式与 --server 模式完全一致 |
| 服务端 readproofd | JSON API（/v1/resources、/v1/tags、/v1/resolve、/v1/runs、/v1/manifests、/v1/diff、/v1/replay），可选 bearer 认证，SQLite 或 Postgres + S3 |
| MCP 服务端 readproof mcp | 资源以 readproof:// URI 暴露，来源信息放在 _meta，13 个工具 —— 支持 Claude Code、Claude Desktop、Cursor（docs/mcp.md） |
| DeepSeek Harness 插件 | 原生 bundle，注册同样的 13 个工具，每个 DSH 会话对应一次 Readproof run，另带零代码 MCP overlay（integrations/deepseek-harness） |
| TypeScript SDK @readproof/sdk | 带类型、零依赖的客户端；run().mount()…commit()、tag、diff、replay、buildEvidence()（sdk/typescript） |
| OpenTelemetry | 每个流水线阶段都有追踪；GenAI 属性（gen_ai.data_source.id）；commit span 携带证据 Merkle root；内容永不附加（docs/observability.md） |
| Evidence | in-toto Statement v1，条目上的 Merkle root，脱敏后的资源定义，重放检查；verify 可离线运行（docs/evidence.md） |

示例

| examples/support-agent | 一个跑在 Ollama 开放模型上的客服智能体——每张工单跑一次，策略会变，diff 解释差异，replay 返回旧字节，Go 命令行验证证据，固定的 @prod 内部风格保持不变。npm run scenario。指南。 |
| examples/langgraph-ts | LangGraph.js：挂载到节点内部，把 manifest id 存进 checkpoint，再从它重放。 |
| examples/refund-agent | 不变量的参考走查，从 shell 驱动；自动化版本在 go test ./... 里运行。 |

文档

| 网站 · 文档 | 覆盖全部接口的指南式文档 |
| docs/architecture.md | 数据模型、内部实现、命令行与 HTTP 参考、SDK、可观测性、测试 |
| docs/api.md · docs/mcp.md · docs/evidence.md · docs/observability.md | 端点 schema · MCP 配置 · bundle 格式及其证明内容 · span、属性、指标 |
| docs/roadmap.md · CHANGELOG.md · docs/rename.md | 后续计划 · 变更记录 · Ctx → Readproof 映射 |
| docs/releasing.md | 如何发布（tag → 二进制、cask、npm） |

状态

v0.3.2 — Apache-2.0。稳定的核心（身份、策略、标签、快照、manifest、溯源感知 diff、严格重放、证据），MCP 服务器，OpenTelemetry，TypeScript SDK，SQLite 或 Postgres + S3，DeepSeek Harness 插件，三个可运行示例。CI 运行 Go build/vet/test、SDK 与示例测试套件、DSH 插件测试套件，以及一个 Docker Compose 集成任务——每次 push 都会针对构建出的 readproofd 镜像重放 demo。

接下来，按顺序（docs/roadmap.md）：Python SDK、基于 HTTP API 的 trace-context 传播、MCP HTTP 传输、源策略文件（允许列表）、签名并可通过 OCI 分发的证据 bundle、tag promote、更多适配器。

安全注册资源就是告诉 readproofd：读哪个文件、连哪个地址、发自己哪些环境变量——这三项在服务端默认全部拒绝（--filesystem-root、--header-env-allow、--allow-private-sources 分别放开它们），在源适配器里强制执行，每个重定向跳转和拨号时都检查。另外：静态存储中不放明文凭据（环境变量引用在抓取时才解析；处处脱敏）、可选的 API-key 认证、带标签的仅开发用 Compose 凭据、依赖扫描、非 root 容器。尚未支持：进程内 TLS 终止和限流（请放在反向代理后面运行）、签名 bundle。漏洞请私下报告——见 SECURITY.md。

贡献

go build ./... && go vet ./... && gofmt -l . && go test ./... 必须全绿，且不依赖任何外部服务；SDK、示例和插件各自都有 npm test。约定、实机基础设施测试块和提 PR 前的检查清单都在 CONTRIBUTING.md。

社区 —— 问题和想法发到 Discussions，bug 和功能请求发到 Issues，漏洞请通过 SECURITY.md 私下报告。所有参与者都须遵守 Code of Conduct。

许可证

Apache-2.0 · NOTICE

为那些必须为智能体读了什么负责的团队而构建。