Arcaeon

arcaeon

记录 Agent 执行过的操作，Agent 无法悄悄改写；任何心存疑虑的人都可以自行核查。

Agent 写入的每一行都会与上一行进行哈希链接。修改一行、删除一行或调换两行，核查都会指出链条断裂的位置。把文件交给其他人，他们无需向你索取任何东西，就能运行相同的核查。

一个包。一个命令：arcaeon <verb>。

安装

pip install arcaeon

Python 3.10 或更高版本。基础安装零依赖。这意味着 pip 只会安装 arcaeon，不会安装其他内容：没有协议 SDK、加密库或解析器。下面“记录”“证明”和“保存”列表中的所有操作都使用 Python 标准库。这也意味着导入时不会联网。托管操作会在运行时建立连接，另外还有少数明确说明的选项也会联网：proxy --pin-witness 和 receipt cite，后者会在线查询每条引用。其他所有操作都能离线使用。

较重的功能以额外依赖包的形式提供。只添加你需要的功能：

extra	添加的内容	会安装的依赖
arcaeon[mcp]	arcaeon mcp（MCP 服务，以及 arcaeon mcp --tools）、vet serve、vet probe	MCP Python SDK 及其依赖（约 30 个包，包括 cryptography）
arcaeon[ts]	vet 的 TypeScript 检查	tree-sitter
arcaeon[sign]	已签名的 vet 报告（badge --receipt，以及 SIGNED 而非 UNSIGNED 封印）、回执签名检查	cryptography
arcaeon[all]	全部三项	以上所有依赖

pip install "arcaeon[mcp]"

其他安装方式，仍使用同一个包：

pipx install "arcaeon[mcp]"

pipx 会将 arcaeon 安装在独立环境中，与其他 Python 包隔离，同时仍会将 arcaeon 添加到你的路径中。

uvx arcaeon demo

uvx（来自 uv）可运行一次而不保留安装：演示会记录两行、修改其中一个词，并显示 BROKEN 行。

py -m pip install --user arcaeon

在 Windows 上，如果找不到 pip，可使用 Python 随附的 py 启动器仅为当前用户安装，无需管理员权限。

60 秒快速上手

记录两行，检查它们，修改历史中的一个词，再次检查。以下命令可直接在 PowerShell、cmd 和 POSIX shell 中运行。--field KEY=VALUE 会为你构建行，因此无需引用 JSON；这在 Windows 上很重要，因为 PowerShell 5.1 会在 arcaeon 收到 JSON 参数之前，去掉其中的双引号，例如 '{"tool": "search"}'。

$ arcaeon log agent.jsonl --field tool=search --field query=weather
<the new row's chain value>
$ arcaeon log agent.jsonl --field tool=send_email --field to=ops
<the new row's chain value>
$ arcaeon verify agent.jsonl
{
 "verdict": "VERIFIED",
 "ok": true,
 "rows": 2,
...
(exit 0)
$ python -c "import pathlib; p = pathlib.Path('agent.jsonl'); p.write_text(p.read_text().replace('weather', 'sunshine'))"
$ arcaeon verify agent.jsonl
{
 "verdict": "BROKEN",
 "ok": false,
...
 "first_break": "line 1: chain mismatch",
...
(exit 1)

这就是全部原理。我们只修改了第一行中的一个词，核查便发现了它并指出所在行。退出码 0 表示 VERIFIED。退出码 1 表示 BROKEN。CI 门禁只需依据退出码即可。

它无法发现的问题：有人删除了末尾几行。请参阅下文的限制，以及解决方案 arcaeon pin。

命令

分为三个系列。完整参考文档，包含用法和示例，见docs/VERBS.md。

记录：记下发生了什么

• log：向账本添加一行 JSON。
• verify：检查账本的链。结果为 VERIFIED、BROKEN 或 COULD NOT LOOK。
• receipt：签发或检查可供他人验证的便携回执。
• once：证明某个副作用（退款、电子邮件）只执行了一次，而非两次。
• proxy：置于 MCP 服务前端，并记录每次工具调用。
• pin：将账本当前的头部交给见证方、本地文件或托管服务。
• deal：记录双方的购买流程，逐步留存记录。

证明：检查写入的内容

• reconcile：对齐记录相同调用的两份记录。结果为 MATCHED、MISSING、ALTERED 或 COULD NOT LOOK。
• audit：检查日志、固定其头部，或将其导出为一个完整包。
• vet：读取 MCP 服务的源代码并评定它。不运行任何代码。
• badge：为 MCP 服务生成免费的 Markdown 徽章和 JSON 报告。
• seal：与徽章相同，但由托管见证方封印。付费。
• baseline：在更改前后分别对固定探测集评分。
• compact：检查一份说明上下文压缩丢弃了哪些内容的回执。

保存：减少令牌消耗

• distill：将工具的输出压缩到令牌预算以内，并记录删去了哪些内容。
• dedup：从文本列表中删除近似重复项。
• meter：统计你自己的工具按键的使用次数，并设置每月上限。

以及

• stamp、credits、buy：托管入口（见下文）。
• mcp：MCP 服务（见下文）。
• selftest：运行所有内置自检。
• version：打印软件包及各部分的版本。

托管入口

stamp、pin --remote、seal 和 credits 会通过 HTTPS 与托管见证服务 witness.arcaeon.io 通信，且仅在你运行它们时才会通信。buy 会读取软件包中附带的 优惠文件，不会发出请求。

• arcaeon stamp FILE：发送文件的 sha256 和大小，绝不发送文件内容。 无需密钥，每日免费额度内均可使用。
• arcaeon pin LEDGER --ns NAME --remote：将账本的头部记录到托管见证服务。 需要 ARCAEON_KEY。
• arcaeon seal PATH：为 MCP 服务评级， 然后封存报告。只需要 ARCAEON_KEY，不需要其他内容，并会使用 1 个积分。见证服务的 pin 就是封存：它会记录账本的头部，不会检查你本机上的签名。安装 arcaeon[sign] 附加项， 并在 MCP_VET_RECEIPT_KEY 中设置签名密钥后，报告也会签名，封存结果会显示 SIGNED； 在基础安装中，结果会显示 UNSIGNED，但同样会封存。没有 ARCAEON_KEY 时不会发送任何内容， 你仍会获得免费徽章，但程序会以状态码 3 退出。密钥只能在其自身的命名空间前缀下固定记录； 你无需知道自己的前缀。如果默认命名空间遭拒，seal 会从拒绝信息中读取你的前缀（不消耗积分）， 并在 <prefix>-sealed-scans 下固定记录。--ns 仍可让你自行选择。
• arcaeon credits：显示你的余额。需要 ARCAEON_KEY。查询免费。
• arcaeon buy：打印结账链接。不会打开任何内容，也不会收取卡款。 付款将在 Stripe 页面上完成。

ARCAEON_KEY 是唯一需要设置的项。请像对待密码一样保护它：密钥泄露后，别人可以用你的名义固定记录。 有关套餐和价格，请参阅 arcaeon.io/pricing。

AI 入口

pip install "arcaeon[mcp]"
arcaeon mcp

arcaeon mcp 会通过 stdio 启动 MCP 服务。它会向 Agent 提供账本、 vet 和见证工具。arcaeon mcp --tools 会列出这些工具，但不会启动任何内容； 它也需要 [mcp] 附加项（在基础安装中，它会打印 pip install 'arcaeon[mcp]' 提示并以状态码 2 退出）。

给 MCP 注册表条目的一则说明：在 0.9 之前，uvx arcaeon 会启动此 服务。此版本发布后的 30 天内，如果没有动词且 stdin 不是终端，它仍会这样运行。 现在请将客户端指向 arcaeon mcp。此回退机制将在 1.0.0 中移除。

退出码

所有动词共用一张表。每个词的含义各用两句话说明，详见 docs/WORDS.md。

code	含义
0	正常：VERIFIED、MATCHED、COMPARED、评级结果良好，或命令按说明完成
1	发现问题：BROKEN、MISSING、ALTERED、严重级别的评级，或收据校验未通过
2	用法错误：无法对提供的内容启动此动词
3	无法检查：未发现问题，但并非所有内容都能检查

3 永远不代表通过。只将 0 视为绿色的门禁会在遇到 3 时失败，这正是预期行为。

多条日志，一个摘要：将这三个计数并列显示。arcaeon 对多条日志生成的任何摘要都会分别显示 VERIFIED、 BROKEN 和 COULD NOT LOOK 的数量，绝不会合并成一个比率。“98% verified”会掩盖剩下的 2% 究竟是已损坏还是根本没有读取，而这两种情况需要截然不同的周一应对方案。如果你根据退出码构建自己的仪表板，也请保留这三列。

在 0.9 之前，有些旧工具对相同词语使用了不同的代码（例如 reconcile 用 2 表示 COULD NOT LOOK）。对于 0.9.x 版本，在动词上使用 --legacy-exit 会返回 旧工具自身的代码，因此在你完成改接期间，原先连接到它的门禁仍能正常工作。此标记将在 1.0.0 中移除。MIGRATION.md 列出了所有变更过的代码。

局限

简而言之，细节如下：

• 可发现篡改，但无法阻止篡改。 任何能写入该文件的人仍然可以更改它。但他们无法在不被检查发现并指出具体行的情况下进行更改。
• 只有一个见证方，而且由我们运营。 托管见证服务 witness.arcaeon.io 由我们这些软件包的开发者运营。那里保存的固定记录展示了我们记录时你的日志头部的状态；它不是一个与你无关的第二方为你背书。
• 每日锚定的是时钟，不是某个机构。 见证服务每天将其固定记录存储锚定到一个公共时间戳。这能确定这些固定记录何时存在，但并不能说明它们是否正确，也没有人在背后核验它们。
• 外部读者无法知道生成固定记录时是谁运营了见证服务。 如今，对于某条固定记录生成时由谁运营，你只能相信我们。这种情况会一直持续，直到我们发布托管记录，而我们目前还没有发布。
• 我们可以复现，你暂时还不行。 重新运行某份账本背后的会话，需要当时的模型、工具服务及其状态；运行者拥有这些，而外部读者没有。在有办法交出这些内容之前，替代方案是代理的请求和响应摘要：arcaeon proxy 写入的每一行调用记录都包含请求的 args_digest 和响应的 result_digest。有了这些字节，你可以检查它们是否就是穿过接口边界的内容；但你无法重新运行调用来得到它们。

哈希链能证明什么：写入后，记录行没有被原地更改。中间的编辑、删除或重排都会破坏其后所有链接，而 verify 会指出第一个损坏的行。

它不能证明什么：

• 截断。 删除最新的若干行，剩下的内容仍然可以通过检查。仅靠哈希链无法发现这一点。固定记录可以：一旦见证服务保存了你的日志头部（行数和链），更短或被改写的日志就无法再与之匹配。
• 真实性。 哈希链记录的是写入的内容，无论真假。要将某行与他人可以再次获取的事实关联起来，请将该事实的摘要存入该行。
• 作者身份。 谁写了某行只是该行中的数据，并非签名。从第一行开始重写整个日志的人也可以改写这些信息。由你控制范围之外的一方持有的固定记录，才是他们无法移动的内容。

固定记录能证明什么：相对于见证服务看到的内容，日志没有被截短或改写，但仅限于最近一次固定记录时的状态。两次固定记录之间最长的间隔，就是你实际面临的风险窗口。自己保存的固定记录文件只能证明机制有效，并不代表存在外部第三方。托管见证服务使用的是持有者密钥，而不是签名。

reconcile 能证明什么，按其自身措辞：

• MATCHED 表示两个记录器意见一致；串通的 Agent 侧和工具侧可以写出两份相互一致的谎言记录。
• 没有经过任何一个已插桩接口边界的调用，不会出现在任何一份记录中；从不调用的 Agent，或通过未包装通道调用的 Agent，在这里不可见。
• 摘要比较的是内容（规范化 JSON），而不是字节：在传输过程中进行不改变含义的重新序列化，按设计会被判为 MATCHED。
• 没有见证固定记录时，两份记录即使被一致地截断或改写，仍然会相互匹配；固定记录可以将这种风险限定在其之后写入的行。

vet 和 badge 报告的是它们对所读取字节执行自身检查后发现的内容。它们不代表人工审查，也不是安全认证。

写入速度不快。每条 log 记录（Ledger.append）都会在下一条开始前刷新并同步到磁盘；在普通笔记本电脑磁盘上，每行约需 18 ms：写入 102,000 行约需 22 分钟。读取速度很快（同一个 50 MB 日志约需 2.5 秒即可完成验证）。

交易

arcaeon deal 会记录 Agent 发起的一笔购买。买方的 Agent 和卖方都会在各自的账本上写入相同的步骤（授权、确认、付款、发货、交付、取消）。任何一方，或拿到双方文件的任何人，都可以使用 arcaeon deal dispute 对照这些记录，并获得一个判定：MATCHED、MISSING、ALTERED 或 COULD NOT LOOK。相关步骤和完整示例见 docs/DEAL.md。

如果你使用过旧软件包

0.9 之前，这个项目由 13 个软件包组成：arcaeon-ledger、arcaeon-adapter、arcaeon-receipt、arcaeon-audit、arcaeon-mcp-vet、arcaeon-once、arcaeon-compact、arcaeon-continuity、arcaeon-baseline、arcaeon-dedup、arcaeon-distill、arcaeon-meter 和 arcaeon-all。每个旧名称都会发布最后一个版本，安装 arcaeon，并继续支持旧导入方式和旧命令，同时发出警告，指出新的导入方式。升级当天不会有任何功能中断。MIGRATION.md 列出了每个名称对应的新旧导入方式和命令，以及发生变化的退出码。shims/README.md 说明了旧名称如何转发。

许可证

MIT。请参阅 LICENSE。