agent-decision-receipts

Agent 决策回执

概述

日志记录某项操作已发生。回执具有防篡改特性：它记录执行者、操作内容和所依据的策略，并经过签名，因此任何后续编辑都会破坏签名。这项技能会为具有重大影响的 Agent 操作生成回执，并在之后仅凭证书进行验证：无需数据库、无需网络，也无需信任签发者。

密码学功能不由这项技能提供。它使用开源的 OpenAgentOntology 回执原语（Apache-2.0），该原语会使用 Ed25519 以及后量子算法 ML-DSA-65（FIPS 204）+ SLH-DSA（FIPS 205）为每份回执签名（前提是已安装后量子后端）。这项技能负责决策层：何时生成、写入哪些内容，以及如何验证。安装一次即可，无需为每项技能单独配置密码学功能。

只做三项决策：

1. 此操作是否需要回执？ — 具有副作用 + 影响重大 + 可供日后举证 = 需要。
2. 生成回执 — 构建操作清单，并使用 OAO 原语签名。
3. 验证回执 — 仅凭证书重新计算哈希并检查各项签名。

这项技能不是日志分析。日志描述已发生的事情，且可以被悄悄编辑。回执会在执行前或执行时生成，编辑会导致回执失效。调试时使用日志；举证时使用回执。

这项技能不是托管公证服务。它会生成本地自签名回执，任何人都可以离线验证。跨组织验证（一个组织向另一个组织举证）属于独立的托管服务，不在此处的范围内。

这项技能不是法律意见。它生成的证据旨在支持符合 FRE 902(13)/(14) 风格的认证，以及符合《欧盟 AI 法案》第 12 条的记录保存要求。特定回执是否会被采纳，应咨询法律顾问。

快速开始

# Install the open-source receipt primitive (Apache-2.0). Add [pq] for the post-quantum legs.
pip install "openagentontology[pq]"

# 1. Build + validate an action manifest (stdlib only, no crypto, no network)
python scripts/build_action_manifest.py --agent my-deploy-agent --operation deploy \
    --target prod/api --policy "EU AI Act Art 12" --out action.json

# 2. Mint the receipt over it (Ed25519 + post-quantum legs)
python -c "import json,openagentontology.receipt as r; \
  print(json.dumps(r.mint_receipt(json.load(open('action.json')), decision='ACTION_GOVERNED')))" > receipt.json

# 3. Verify from the cert alone (no DB, no network)
python -c "import json,openagentontology.receipt as r; \
  print(r.verify_receipt(json.load(open('receipt.json'))))"
# -> {'ok': True, 'sig_ok': True, ... 'reason': 'verified from the cert alone via: ed25519, ml_dsa, slh_dsa'}

依赖说明。 这项技能会委托 openagentontology 进行签名（Apache-2.0，可选择通过 pip install 安装）。此处随附的脚本仅使用标准库，不会增加仓库依赖；该软件包由操作人员安装（BYO-library 模式）。如果未安装该软件包，构建步骤仍可正常运行——只有生成和验证需要它。

核心工作流

以下三项决策就是这项技能的全部内容：决定是否生成回执、生成回执，然后验证。

决策 1：此操作是否需要回执？

只有当操作同时满足以下三项条件时，才生成回执：

测试	满足以下条件时生成回执……
具有副作用	会写入、发送、部署、删除、付款、授予访问权限，或更改外部状态
影响重大	错误操作会造成经济损失、违反合规要求，或伤害他人
可供日后举证	他人（审计员、保险公司、监管机构、法院、交易对手）可能会询问“Agent 做了什么，为什么这么做？”

只读、可撤销、无关紧要的操作不需要回执。为所有操作生成回执，重要信号就会被淹没；什么回执都不生成，关键操作就无法举证。

高信号触发条件（默认生成回执）：deploy、delete、pay/wire/refund、grant_access、export/egress、批准或拒绝索赔，以及任何会在高风险 AI 系统下影响个人的模型决策。

决策 2：签发回执

操作清单可以是任何描述 Agent 执行了什么操作的 ASCII 安全字典。以下 4 个键是必需的——如果缺少任何一个，build_action_manifest.py 就会拒绝该清单（退出码为 2）。另外两个键会自动添加：

键	是否必需？	内容
agent_id	必需	执行操作的 Agent
operation	必需	操作动词（deploy / delete / pay / decide / ...）
target	必需	操作对象
policy	必需	约束该操作的规则（例如 "EU AI Act Art 12"、"internal change-control"）
inputs_hash	自动添加	--inputs 的哈希，因此无需以明文存储完整载荷（省略 --inputs 时，默认为空内容的哈希）
decision_label	自动添加	回执决策标签（默认为 ACTION_GOVERNED）

mint_receipt(manifest, decision=...) 会将完整清单哈希后写入回执证据，对规范化正文签名，并返回一份回执，其中包含：evidence_hash、signature_b64（Ed25519），以及在安装了 [pq] 时的 ml_dsa_signature_b64 + slh_dsa_signature_b64。每种签名算法都对相同的字节签名；任意一种验证通过即可证明真实性。

完整回执架构和后量子加密的理由，请参见 references/receipt-fields.md。

决策 3：验证回执

verify_receipt(receipt) 会重新计算 sha256(canonical(evidence))，将其与 evidence_hash 比较，然后检查其后端支持的每种签名算法。它会返回 {ok, hash_ok, sig_ok, legs, reason}。操作中的任何一个字节被修改都会导致 hash_ok 验证失败；伪造签名则会导致相应的签名验证失败。验证只需要回执，无需回调签发方。

正是这一特性让它成为证据：即使审查者不信任签发方，也仍然可以完全离线地确认回执完整且真实。

反面模式

• 回执应针对决策，而非日志。 事后针对一条日志记录签发回执，证明不了任何事情。应在操作发生时针对该操作签发回执。
• 将签名密钥与回执存放在一起。 如果密钥遭到泄露，签名便毫无意义。应像对待任何签名密钥一样保管它；切勿将其提交到代码库。
• 有后量子签名算法可用时仍仅使用 Ed25519。 回执是长期有效的证据。应使用后量子签名算法（ML-DSA-65 + SLH-DSA）签署回执，使其在未来量子计算机可能破解 Ed25519 时仍可验证。请安装 [pq]。
• 在清单中放入原始机密或 PII。 清单会被哈希后写入证据，并且可以从回执中还原。应携带哈希（inputs_hash），而非明文。
• 称其为“可采纳证据”。 它是旨在支持 FRE 902(13)/(14) 式认证的证据。可采纳性由法院决定，而非由工具宣称。
• 缺少加密功能时伪造签名。 该原语会明确标记为 unsigned。切勿将未签名的回执说成已签名。

交叉引用

• ra-qm-team/skills/eu-ai-act-specialist/ — 确定 AI 系统的风险等级和第 12 条义务；本技能会签发这些义务所要求的逐操作记录。
• ra-qm-team/skills/iso42001-specialist/ — AI 管理体系控制；回执是这些控制所要求的逐决策证据。
• OpenAgentOntology（Apache-2.0）：本技能所使用的开源回执原语——pip install "openagentontology[pq]"。