paceproof

PaceProof

PaceProof 可验证来自任意提供方、由 Ed25519 签名的计算证明记录，并准确告知你哪些记录真实可信。

缺少签名、签名格式错误或签名遭到篡改的记录，绝不会被计入“已验证”总数；每次都会单独统计并报告，无论是人类可读输出还是 --json 输出。

PaceProof 不会签名或生成证明。它是一个中立、只读的接入、验证、报告和仪表板层，用于处理已在其他地方签名的记录。将已签名记录所在的目录、文件或 URL 提供给它，它就会以可验证的方式告知你实际运行了什么计算、由谁运行，以及每条记录的签名是否均通过验证。

安装

paceproof-cli 已发布到 npm 和 PyPI：

npm install -g paceproof-cli
# or
pip install paceproof-cli

这两种命令都会安装 paceproof 二进制文件。如果需要与 PATH 上的其他工具区分，两个仓库中也都提供了 paceproof-cli 作为别名。

如需从源代码构建（适用于参与贡献，或想使用仓库的确切状态，而非已发布版本）：

TypeScript（npm 包，包含 MCP 服务）：

git clone https://github.com/RudrenduPaul/PaceProof.git
cd PaceProof/packages/cli-ts
npm install
npm run build
node dist/bin.js --help

Python（PyPI 包，独立重新实现）：

git clone https://github.com/RudrenduPaul/PaceProof.git
cd PaceProof/packages/cli-py
pip install -e .
paceproof --help

撰写本文档时，我们在干净环境中实际运行了上文发布的 npm install -g paceproof-cli 和 pip install paceproof-cli 命令。下方快速入门中的输出也来自这些安装的实际运行结果，并非伪造。

目录

• 功能
• 快速入门
• CLI 命令参考
• 库 API 参考
• 验证原理
• 对比
• PaceProof 是什么，以及它为何存在
• 常见问题
• 参与贡献
• 许可证

快速入门

paceproof init
paceproof report ./paceproof-example

paceproof init 会生成一对全新的 Ed25519 示例密钥，以及 7 条示例证明记录：其中 3 条签名有效，另有 4 条特意设置了错误（负载遭篡改、签名使用了错误的密钥、签名格式错误、缺少签名），这样 verify/report 就能展示真实的失败情况，而不只是顺利运行的情况。

使用实际运行的已发布 npm 包得到的真实输出：

$ paceproof report ./paceproof-example

PaceProof report -- source: ./paceproof-example
generated at: 2026-08-04T02:54:30.898Z

== VERIFIED ==
  records: 3
  compute total: 144.50 gpu_hours

== UNVERIFIED (never counted in verified totals above) ==
  records: 4
  compute total: 1009 gpu_hours
  reasons:
    - rec-004: signature does not match record contents
    - rec-005: signature does not match record contents
    - rec-006: signature must decode to 64 bytes, got 4
    - rec-007: schema validation failed: (root) must have required property 'signature'

== BY PROVIDER ==
  acme-cloud: verified=132 gpu_hours (2 records); unverified_count=0
  beta-compute: verified=12.50 gpu_hours (1 records); unverified_count=0
  gamma-hpc: verified=(none); unverified_count=2
  delta-cloud: verified=(none); unverified_count=2

== BY WORKLOAD TYPE ==
  training: verified=128 gpu_hours (1 records); unverified_count=1
  inference: verified=12.50 gpu_hours (1 records); unverified_count=1
  idle: verified=4 gpu_hours (1 records); unverified_count=1
  unknown: verified=(none); unverified_count=1

只要有任何记录验证失败，verify 就会以非零状态码退出（实际运行得到的退出码为 1，其中有 4 条未验证记录）：

$ paceproof verify ./paceproof-example
Verified: 3
Unverified: 4
  FAIL rec-004: signature does not match record contents
  FAIL rec-005: signature does not match record contents
  FAIL rec-006: signature must decode to 64 bytes, got 4
  FAIL rec-007: schema validation failed: (root) must have required property 'signature'
$ echo $?
1

使用相同的数据渲染仪表板：

paceproof dashboard ./paceproof-example --out dashboard.html

撰写本文档时，我们分别使用 paceproof-example 运行了 TypeScript 和 Python 版本，两者得到的已验证/未验证计数和总数均与上文所示一致。

功能

• 可插拔的数据源适配器。 ingest 通过有文档说明的 Adapter 接口（TypeScript 接口、Python ABC）将任意输入规范化为规范模式。随附的 jsonl 适配器可读取已采用规范格式的换行分隔 JSON；针对特定提供方的适配器（例如 ComputeLedger 原生导出格式的适配器）实现相同接口即可，无需修改聚合器、报告渲染器或 CLI 接线。
• Ed25519 验证，并严格区分已验证与未验证数据。 每条记录都会检查模式有效性和签名有效性。任何一项检查未通过的记录都不会被悄然合并到已验证的总数中：已验证和未验证记录的数量及计算总量分别从互不重叠的数据集中计算，并在每份报告中并列显示。
• 两个独立且经过一致性测试的实现。 TypeScript 软件包（npm）和 Python 软件包（PyPI）是彼此独立的真正实现，而不是对其中一个的封装。对于相同输入，两者生成的 report --json 输出逐字节一致；CI 作业会使用共享测试样例，双向比较 TypeScript CLI 与 Python CLI 的输出，任何差异都会导致构建失败。
• 自包含的静态 HTML 仪表板。 paceproof dashboard 会生成单个 HTML 文件，包含内嵌 CSS，且不含 JavaScript：没有 CDN 字体、外部脚本或任何形式的远程请求。目前仅提供简洁的浅色主题；尚无深色模式开关。
• 供 Agent 调用的 MCP 服务。 paceproof mcp 会启动一个 Model Context Protocol 服务，将 verify、ingest 和 report 作为可调用工具公开，使编排 Agent 能以编程方式调用 PaceProof，而不必通过面向用户的 CLI 执行 shell 命令。工具处理器只是对 CLI 本身调用的同一组聚合和报告函数进行轻量封装，MCP 路径不会另行实现一套逻辑。
• 从设计之初就注重安全，而非事后补救。 聚合桶使用 Object.create(null) 创建，因此攻击者控制的 provider 或 compute_unit 字段（例如 "__proto__"）无法污染 Object.prototype。PaceProof 唯一会进行的网络调用（ingest <url>）设有 30 秒超时和 50 MiB 响应大小上限；限制依据实际流式传输的字节数强制执行，而非信任 Content-Length 标头。每个模式字段都有明确的最大长度，避免在验证开始前利用超大输入耗尽内存。

CLI 命令参考

下方每张表均摘自已发布的 paceproof-cli npm 软件包（v0.1.0）的实际 --help 输出。

paceproof init [path]

创建示例目录，其中包含示例密钥对，以及签名有效和无效的示例记录。

参数	描述
path	要创建的目录（默认：./paceproof-example）

paceproof verify <path>

验证在 <path> 下找到的每条记录的 Ed25519 签名。

选项	描述
--json	输出结构化 JSON，而非人类可读的表格
--adapter <name>	用于读取输入的适配器（默认：jsonl）

paceproof ingest <path-or-url>

使用指定适配器处理输入，并以 JSONL 格式输出规范化的规范模式记录。

选项	描述
--adapter <name>	要使用的适配器（默认：jsonl）
--out <file>	将 JSONL 输出写入文件，而非标准输出

paceproof report <path>

导入并验证 <path> 中的记录，然后汇总生成报告。

选项	描述
--json	输出结构化 JSON，而非人类可读的表格
--adapter <name>	用于读取输入的适配器（默认：jsonl）

paceproof dashboard <path>

根据报告生成单个自包含的静态 HTML 仪表板。

选项	描述
--out <file>	HTML 文件路径（默认：paceproof-dashboard.html）
--adapter <name>	用于读取输入的适配器（默认：jsonl）

paceproof mcp

启动一个 MCP 服务，将 verify、ingest 和 report 暴露为可调用的工具。目前仅提供 TypeScript 包：从 Python 包运行 paceproof mcp 会打印一条指向 npm 包的消息，并以非零状态码退出。

每条命令在失败或验证失败时都会返回实际的非零退出码，并且每个子命令都支持 --help。

库 API 参考

npm 包也会直接导出其内部实现（package.json 中的 main/types 指向实际库代码，而不只是 CLI 入口），供需要构建自定义适配器，或将验证逻辑嵌入其他工具而非通过 shell 调用 CLI 的开发者使用。此接口仅支持 TypeScript；Python 包只提供 paceproof CLI，没有文档化的导入 API。

import { getAdapter, verifyRecords, summarize } from 'paceproof-cli';
import type { Adapter } from 'paceproof-cli';

const records = await getAdapter('jsonl').read('./paceproof-example/records.jsonl');
const outcomes = verifyRecords(records);
const report = summarize(outcomes);

导出项	签名	功能
Adapter	interface Adapter { readonly name: string; read(input: string): Promise<RawRecord[]> }	如上所述的扩展点。实现此接口，即可将新提供方的导出格式规范化为规范记录。
getAdapter(name)	(name: string) => Adapter	按名称查找已注册的适配器（内置提供 jsonl）；如果名称未注册，则抛出异常。
verifyRecord(raw)	(raw: RawRecord) => VerificationOutcome	对单条记录进行架构验证和签名验证。
verifyRecords(raws)	(raws: RawRecord[]) => VerificationOutcome[]	对一批记录运行 verifyRecord。
summarize(outcomes)	(outcomes: VerificationOutcome[]) => ReportSummary	将验证结果汇总为与 paceproof report --json 输出相同的已验证／未验证（按提供方和工作负载类型分类）结构。
verifyRecordSignature(record)	(record: AttestationRecord) => SignatureCheckResult	仅检查 Ed25519 签名（架构验证单独进行），并根据下文所述的规范 JSON 编码进行验证。
canonicalizeRecord(record)	(record: Record<string, unknown>) => Uint8Array	生成计算和验证签名所依据的规范字节编码：键按字典序排序、使用 UTF-8、不含无意义空白。
buildCli()	() => Command	返回已发布 CLI 自身运行的 Commander.js Command 实例，供你嵌入或扩展，而非重新实现参数解析。

目前没有单独生成的 API 文档站点（CI 中尚未构建 TypeDoc）——在此类站点建成之前，上表即为参考。所有签名均于 2026-08-03 直接从 packages/cli-ts/src/ 中检索得出，并非凭记忆重构。

验证机制

每条证明记录都是一个 JSON 对象，并根据单一的规范 JSON Schema（schema/attestation-record.schema.json）进行验证。TypeScript 和 Python 软件包附带并据此验证的都是同一个文件，逐字节完全一致。记录必须包含 record_id、issued_at、provider、hardware、workload_type、compute_amount、compute_unit、issuer_public_key 和 signature；每个字符串字段都有明确的最大长度，因此格式错误或超出长度限制的输入会立即失败，而不是先解析再限制长度。

signature 字段是对其他所有字段的规范 JSON 编码进行的 Ed25519 签名：对象键按字典序排序，采用 UTF-8 编码，不含无意义的空格，数字不带前导 + 号或不必要的尾随零。对于同一条记录，两种实现生成的规范 JSON 字节完全一致，因此，一种实现验证通过的签名，用另一种实现也能验证通过。

只有同时通过两项检查的记录才算“已验证”：Schema 验证通过，且签名验证通过。其他任何情况（缺少签名、签名解码后的字节长度不正确、签名与负载不匹配、签名使用了错误的密钥）都属于“未验证”。在聚合器代码中，这两类记录始终互斥，不只是报告呈现时看起来互斥：已验证和未验证的计算总量分别累计在不同的数据结构中，并且不存在将未验证记录的 compute_amount 计入已验证总量的代码路径。若报告工具悄悄混淆“声明的”与“已证明的”数值，就会把无法验证的声明包装成看似已验证的结果，从而违背审计跟踪的意义。

对比

下方的 Star 数量和描述已于 2026-08-03 对照各项目的 GitHub API 列表和 README 实时核查；没有任何内容是编造的，也没有沿用记忆中的信息。

项目	Star 数量	功能	与 PaceProof 的区别
meghabyte/verifiable-training	10	Stanford NeurIPS 2024 研究代码（“Optimistic Verifiable Training by Controlling Hardware Nondeterminism”），通过消除硬件非确定性，使训练运行在不同 GPU 上都能复现出字节完全一致的权重；随后在检查点上构建 Merkle 树，供验证器审计。	在权重层面证明所声称的特定训练确实发生过，属于用于生成证明的研究原型，而非数据导入／验证／报告工具。没有适配器，不支持从多个提供商导入已有的签名记录，没有 CLI，不支持跨语言一致性，也没有 MCP 接口。
skypilot-org/skypilot	10,441	跨 20 多个云平台、Kubernetes 和 Slurm 的多云 AI 计算编排与成本感知调度。	提供成本和利用率的可见性与调度，而非加密验证。它从不检查签名，也不会将“已验证”数值与“声称”数值区分开；完全不涉及证明记录格式。
opencost/opencost	6,659	Kubernetes 和云成本监控及分摊可见性（Apache 2.0，最初名为 Kubecost）。	与 SkyPilot 属于同一类别：通过账单和指标数据提供使用量与成本的可见性，而非加密证明。不支持 Ed25519 验证，不区分已验证／未验证数据，也没有证明记录架构。
RudrenduPaul/ComputeLedger	0	与提供商无关的 CLI、库和 MCP 服务，用于使用 Ed25519 签名对计算使用收据（GPU 小时数、硬件、工作负载类型）进行签名、哈希链式链接和独立验证，并维护具有防篡改能力的本地账本。	互补而非竞争：这是同一作者的关联项目，负责该问题中生成证明的部分。PaceProof 负责导入／验证／报告的部分。将其指向来自 ComputeLedger 或任何其他 Ed25519 签名来源的记录，即可查看哪些记录通过验证。

截至 2026-08-03，对可直接比较的“从多个提供商导入带签名的计算证明记录、验证 Ed25519 签名，并将已验证和未验证的总量分开”的工具进行更广泛搜索后，没有发现其他符合这一特定组合的工具。最接近的相邻类别是通用硬件远程证明验证（例如 veraison/services，47 个 Star，支持 TPM／SEV-SNP／SGX／TDX 证据）：这是不同的证明领域（硬件启动／运行时状态，而非计算使用记录），不包含计算证明架构、适配器模型或计算小时数报告。

PaceProof 是什么，以及它为何存在

随着围绕计算的讨论越来越多，越来越难以独立验证 AI 实验室、云服务提供商和基础设施运营商对计算用量的说法。2026 年 7 月，一千多名来自 OpenAI、Anthropic、Google DeepMind 和 Meta 的员工签署了真实的「Pacing the Frontier」公开信，呼吁采用可验证的工具来放缓前沿 AI 的发展。这是该行业讨论的一个例子，此处仅将其作为背景。PaceProof 与这封公开信没有关联，不是应签署者的任何请求而开发，也不声称获得其认可或与其合作。

先明确说明这份 README 必须清楚表达的一点：现实中并不存在「Verified Slowdown」条约，如今也没有此类条约。 这个说法来自 ai-2027.com 上的一个推测性预测情景，并非任何实际的国际协议、法律或监管机构的产物。PaceProof 不会实施、执行或认证对任何条约、法律或法规的合规情况，因为不存在适用于此工具的此类条约、法律或法规。

PaceProof 实际上是一个中立、可通过密码学验证的报告层，用于处理你已有的计算证明数据。如果你（或与你合作的提供商）已经生成签名证明记录，无论是通过 ComputeLedger、自定义签名流程，还是任何其他能够生成 Ed25519 签名记录的方式，PaceProof 都会告诉你哪些记录通过了密码学验证，并仅汇总通过验证的记录，同时将其与未通过验证的记录严格区分。这对内部审计跟踪和跨提供商用量透明度很有帮助。它不是、也不声称是针对不存在法规的合规软件。

常见问题

PaceProof 是什么？它与通用成本监控工具有何不同？ PaceProof 是一个只读 CLI 和 MCP 服务，用于验证计算证明记录上的 Ed25519 签名，并报告总量；已验证和未验证的数据严格分开，绝不合并。SkyPilot 或 OpenCost 等成本可见性工具报告计费系统所称的用量；PaceProof 报告密码学签名实际能够证明的内容，并将其他所有内容标记为未验证，而不是默默将其计入。

PaceProof 能否提供法律或监管合规保障？ 不能。不存在 PaceProof 需要遵守的真实「Verified Slowdown」条约或类似法规，PaceProof 也不作任何合规声明。它会验证你提供的记录上的 Ed25519 签名并报告结果。请将其输出视为密码学验证报告，而非法律或监管认证。

PaceProof 会签署或生成证明记录吗？ 不会。PaceProof 是只读的：它会接收、验证并报告在其他地方已签名的记录。如果你需要生成带签名的计算证明记录，那是另一项工作；签名方面请参阅同一作者开发的姊妹项目 ComputeLedger。

PaceProof 与 ComputeLedger 有何不同？ 两者相辅相成，并非竞争关系，且由同一作者开发。ComputeLedger 会对计算用量收据进行签名并构建哈希链；PaceProof 则会接收并验证已签名的记录，这些记录可以来自 ComputeLedger，也可以来自任何其他使用 Ed25519 签名的来源。如果你需要生成带签名的记录，请使用 ComputeLedger。如果你需要独立验证已有记录，请使用 PaceProof。 签名错误的记录会怎样处理？会直接被丢弃吗？ 不会。未通过架构验证或签名验证的记录绝不会被丢弃或悄然排除。它会计入 unverified_count，其计算量会单独汇总到 unverified_compute_total_by_unit，并同时报告具体失败原因（载荷被篡改、密钥错误、签名格式错误、缺少字段）。失败记录的任何信息都不会从输出中消失。

我能为导出格式不是 JSONL 的提供商添加支持吗？ 可以，这正是适配器接口的用途。实现 Adapter 接口（TypeScript）或 Adapter ABC（Python）：提供一个 name 和一个返回已规范化为规范架构记录的 read(input) 方法。除了注册新适配器的名称外，无需修改聚合器、报告渲染器或现有 CLI 接线。

paceproof ingest <url> 会发起任意网络请求吗？ 只会发起你明确要求的那一次请求。其他所有命令都只操作本地文件。ingest <url> 是整个工具中唯一需要显式启用的网络请求，并且有严格限制：30 秒超时，响应上限为 50 MiB。上限根据实际流式传输的字节数强制执行，而不只是依据远程服务可能伪造的 Content-Length 标头。

PaceProof 能在 Windows、macOS 和 Linux 上运行吗？ npm 包需要 Node.js 18 或更高版本，且没有特定操作系统的代码，因此只要 Node 能运行，它就能运行，包括 Windows、macOS 和 Linux。Python 包需要 Python 3.10 或更高版本，在 PyPI 上标记为 OS Independent。两者都是纯用户态工具，没有原生编译依赖。

为什么要提供两个实现，而不是一个带绑定的 CLI？ 这样，每个包都能作为真正独立的工具，从各自的原生包注册表（npm 或 PyPI）安装，而无需引入另一种语言的运行时。共享的 JSON Schema 文件和跨语言一致性测试套件（在 CI 中双向运行）可确保两者的 report --json 输出一致，因此选择哪种实现不会影响结果。

Python 包中提供 MCP 服务吗？ 目前还没有。paceproof mcp 暂时仅支持 TypeScript：从 Python 包运行时会输出一条指向 npm 包的提示消息，并以非零状态码退出。其他所有命令（init、verify、ingest、report、dashboard）都有完整且独立的 Python 实现。

PaceProof 使用什么许可证？我可以将它用于商业用途吗？ MIT。你可以将 PaceProof 用于商业用途、修改和再分发，无需支付版税，也无需开源自己的代码；你只需按照 MIT 许可证条款保留版权声明和许可证文本。

贡献

CI（.github/workflows/ci.yml）会在每次推送到 main 以及针对 main 的每个 PR 上运行三个任务：TypeScript lint、类型检查和测试；Python lint（ruff）、类型检查（mypy --strict）和测试（pytest），覆盖 Python 3.10 和 3.13；以及跨语言一致性任务，该任务会构建 TypeScript CLI、安装 Python CLI，并通过子进程让双方分别针对对方的 CLI 运行一致性测试。

要在本地运行所有任务：

# TypeScript
cd packages/cli-ts
npm install
npm run lint
npm run typecheck
npm test        # 60 tests, Vitest

# Python
cd packages/cli-py
pip install -e ".[dev]"
ruff check src tests
mypy src
pytest -q       # 52 tests

如果你修改架构，请更新仓库根目录下的 schema/attestation-record.schema.json 以及 packages/cli-ts/schema/ 和 packages/cli-py/src/paceproof_cli/schema/ 下的副本，并更新两种实现中的验证逻辑。每个包的测试套件中都有一项一致性测试，用于检查本地架构副本与根目录文件是否一致；如果两者出现偏差，CI 将失败。

请参阅 ARCHITECTURE.md，了解完整的仓库布局、计算签名所依据的规范 JSON 规则，以及适配器接口和 MCP 服务如何协同工作。

许可证

MIT。请参阅 LICENSE。