用途
TraceFold 的定位是：AI 智能体不应做出不可逆的更改。它在效果落地之前先托管（escrow）该效果的逆操作，或者拒绝该效果落地，并签发任何人都可以离线验证的收据。它明确指出自己不是可观测性工具（Not an observability tool），而是位于效果发生之前（It sits before the effect）。
主要能力
- 效果前托管逆操作：在 AI 智能体的写操作落地之前，由钩子将写操作交给托管，先确保逆操作存在，否则拒绝该效果。
- 可逆撤销：通过
gx undo <txid>发起新的变换，不会删除数据，而是将原写入取代（superseded）。 - 字节级校验：对已恢复文件执行
sha256sum，其结果与写入前的哈希完全一致。 - 离线可验证收据：通过
gx receipt verify --pretty验证签名、规范 CID 和包含性，全部离线完成，无需信任第三方。 - 离线验证网页：打开 tracefold.github.io/tracefold/verify.html，粘贴收据和密钥即可验证，100% 通过标签页内 WebAssembly 运行，网络请求严格为 0。
- 确定性复现演示：examples/openclaw-plugin-demo/ 运行相同的 before_tool_call 托管路径（落地前拒绝、之后取回），针对真实的 gx 二进制和真实文件系统，脚本化完成，无需 API 密钥。
使用方式
- 安装一个二进制文件
gx，即上述演示所运行的 CLI（gx undo、gx receipt verify）。它已发布在 crates.io 上，版本 0.1.2，采用 Apache-2.0 许可，也可从源码构建。 - 该仓库的标签在 v0.1.1-alpha 之后不再附带预构建二进制文件，而该版本仅为 Linux x86_64；多平台构建见 issue #7。
- 文档索引：docs/README.md 列出了本仓库所有文档与文章的阅读顺序。
- 正式技术报告：docs/TRACEFOLD_TR.md 包含完整数学证明与收据编码。
- 形式化验证规范：lean/README.md 提供机器检查的 Lean 4 定理套件。
- 排除分类法：docs/LIMITS.md 列明由测试强制执行的范畴边界与限制。
- 适配器指南：docs/ADAPTER_GUIDE.md 说明将新基板连接到托管门需要什么、成本如何衡量以及一致性要求。
- 错误分类：docs/ERROR_TAXONOMY.md 提供错误分类与退出码规范。
- 可恢复性机制：docs/RECOVERABILITY.md 定义可逆执行状态。
- 开发树测试：docs/DEVELOPMENT_TREE_TESTS.md 提供全谱系测试探针分类法。
- 用户也可在自己的克隆中运行 tools/e2e.sh 以获得来自本机的数值。
适用场景
适用于需要让 AI 智能体执行写入操作、但又要求这些操作可逆或可拒绝的场景，尤其是针对真实仓库而非夹具的写操作。示例演示展示了一个真实的 OpenClaw 智能体（deepseek/deepseek-chat，真实 API 调用而非夹具）派发写工具调用，gx 的 before_tool_call 钩子触发并将写入在落地前交给托管；写入提交后，gx undo <txid> 发起新的变换取代原写入；随后进行字节校验和离线收据验证。
限制
- 项目刻意不提供 CI/构建徽章。原因如实说明：本仓库从未携带过工作流文件，没有任何提交触及 .github/workflows/，此处可见的所有 Actions 运行均为 GitHub 自身的默认设置（CodeQL 和 Pages），自 2026 年 9 月 1 日起在推送时完成。下一句描述的 CI 来自本仓库同步自的私有树。f65aac2f 在此处无法解析，也是因为在该账号被计费阻塞期间（req/908），它从 2026-08-15T17:25:29Z 起的任何推送都运行了零个任务；最后一次运行时覆盖了本项目 17 个工作区 crate 中的 16 个。TypeScript SDK 的测试从未在 CI 下运行过。本页任何内容均非由本仓库的构建产生。仓库状态依据 GitHub API 于 2026 年 9 月 4 日检查；完整且有日期的细节见 docs/LIMITS.md 第 8 项。
- 关于 db/ 子项目：它是自包含 crate，将 Markdown 语料编译为可寻址原子，在只追加日志中记录其接纳内容，并回答来自可删除并重建的 SQLite 索引的查询。采用 Apache-2.0 许可。它是自己的 cargo 工作区，而非根目录工作区的成员，因此此处的
cargo build --workspace不会触及它，本仓库的任何检查也不覆盖它——需单独构建和测试：cd db && cargo test -p db（添加时 21 项控制全部通过）。在测量语料上，对同一问题它返回的字节数比 grep 少 14.7 倍，但耗时约 62 毫秒，而 grep 仅需 2 毫秒；该权衡以及测试装置拒绝计时的两行均在 db/README.md 中。 - 定价与收费：此处发布的一切均免费——验证、收据、自托管——只要单个人使用就一直免费。没有任何东西出售，付费不会改变你获得的内容。若仍希望资助，仅有一个渠道：通过 Stripe 的“pay what you want”支持 TraceFold（2026 年 9 月 1 日从 Polar 改为 Stripe，因 Polar 结账账户的入驻未完成）。无论哪种方式都不承诺任何回报。
- 项目还援引了一篇基础论文《A Mechanical World Model for Agents》（DOI: 10.5281/zenodo.22168558），以及面向智能体的机械世界模型。其他未在以上资料中明确提供的细节暂未提供。
