把一個動作變成可驗證的事實

第一步:決定要公證哪個動作

不要「全部都記」。收據是公開的、而且刪不掉,噪音會永久留著。

三條互通鐵則

🔴 違反的症狀是「收據被拒收」,不是程式報錯——所以特別難查。下面的客戶端已經在本地就把三條擋掉了。

metadata 的命名地雷

最容易踩的一個。Registry 有一份私密關鍵字黑名單,而且是把欄位名切開底線、逐段比對的—— 所以「加個後綴就好」的直覺在這裡是錯的。

# ❌ 這些都會讓【整張收據】被拒收
prompt_hash      # 切出 prompt ⇒ 中
user_email       # 切出 email ⇒ 中
raw_count        # 切出 raw ⇒ 中
session_id       # 切出 session ⇒ 中

# ✅ 換個名字就好,語意完全不變
content_digest   text_digest   actor_ref   order_ref   tenant_ref

這是刻意的,不是 bug。它擋的是「不小心把客戶資料公證出去」。完整黑名單(28 個,出現在收據任何一層、任何一段都會被擋):

api_key   api_keys   access_token   auth_token   authorization   cookie   cookies   credential   credentials   email   full_receipt   html   image   messages   ocr_text   password   private_key   prompt   raw   raw_content   request_body   response   secret   screenshot   session   token   transcript   user_content

只放不可還原的值

收據公開可查、而且 append-only——發出去就收不回來。

🔴 收據是附帶效果,不是前置條件

Registry 掛掉、金鑰沒設、網路不通,你的主要功能都必須照常完成。反過來絕不可以。

// ✅ 對的形狀
const result = await doTheActualWork();      // 先把正事做完
try {
  recordReceipt(result);                     // 非同步,別讓使用者等網路
} catch { /* 記錄失敗絕不能影響上面那行 */ }
return result;                               // 原封不動回去

另外三件實務上很值得做的:預設關閉(沒明確打開就一個位元組都不送);送不出去先簽好落地到 outbox 之後補送——收據 id 在簽章當下就固定,補送走冪等路徑不會變成兩筆;兩層都擋——呼叫端 try/catch,記錄函式自己也不拋例外。

客戶端

零相依,只用 Node 內建 crypto。canonical JSON 與 Registry 逐位元相同、三條鐵則本地先擋、黑名單本地先掃、預設關閉。

⬇ 下載 agentoath-client.mjs

// 存成 lib/agentoath.mjs 直接 import
import { Identity, RegistryClient, buildSignedReceipt, sha256Json } from "./lib/agentoath.mjs";

// 1. 產生身分(私鑰存進環境變數,絕不進版控)
const id = Identity.generate();
console.log(id.did, id.privateKey);

// 2. 註冊一次就好(冪等,重跑不會變成兩個身分)
const c = new RegistryClient({ apiKey: process.env.AGENTOATH_KEY, enabled: true });
await c.registerIdentity(id, { name: "my-service", platform: "my-platform" });

// 3. 每次值得公證的動作
const receipt = buildSignedReceipt(id, {
  receiptId: `verdict-$${orderId}`,
  action: "compliance.verdict.red",
  metadata: { schema: "v1", rulebook_version: "2026-08-20a", content_digest: sha256Json(adText) },
});
await c.publishReceipt(receipt);

🔴 不要自己重寫 canonical JSON。 兩邊差一個位元,簽章就永遠驗不過,而症狀是「收據被拒收」不是報錯。 用附的這份,或照 GET /api/v1/registry 的規格逐字實作。 Python 端的等價實作是 json.dumps(v, ensure_ascii=False, sort_keys=True, separators=(",", ":"))。

怎麼證明你真的接上了

🔴 不要看「沒有錯誤」——那不是證據。證據的形狀是狀態翻轉。

# 跑之前
curl -s $REGISTRY/api/v1/agents/$DID/status
# → receipt_count: 0

# 觸發一次【真實】的動作(不要用測試假資料)

# 跑之後
curl -s $REGISTRY/api/v1/agents/$DID/status
# → receipt_count: 1   ← 這個 0→1 才是證據

# 負對照:同一張收據改掉任一欄位,必須翻成 valid=false
curl -s -X POST $REGISTRY/api/v1/receipts/verify \
  -H "Content-Type: application/json" \
  -d '{"receipt": <改過一個欄位的收據>, "from_public_key": "<你的公鑰>"}'
# → {"valid": false, ...}

兩格都要驗。 只驗「正的通過」不夠——那有可能是它對什麼都說通過。 負對照真的翻成 false,才證明簽章在保護內容。

常見卡點