Agent Receipts

日志告诉你发生了什么。回执证明了它。

Live Demo agent-receipts MCP server npm version License: MIT macOS Windows Linux

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

真实世界示例

我构建了 ModQuote —— 一个面向汽车维修店的多租户 SaaS。在开发过程中，我大量使用 Claude Code 来审计和修复代码库。

问题在于：当出现问题时，我无法证明 Claude 收到了什么输入、它修改了什么，或者输出是否符合预期。

有了 Agent Receipts，现在每一次 Claude Code 会话都会生成已签名的回执：

输入哈希：精确证明 Claude 看到了什么代码
输出哈希：精确证明它产生了什么结果
约束：在延迟激增或成本超出预算时发出警报
链式调用：展示多步审计会话的完整序列

当修复效果不如预期时，我可以调取回执，验证签名，并查看确切的输入/输出哈希 —— 无需猜测，也不会出现“Claude 一定是误解了”的情况。

这就是日志与回执的区别。日志告诉你发生了什么。回执证明了它。

快速入门：MCP Server

将 Agent Receipts MCP server 添加到你的 AI 工具配置中，每一次操作都会自动获得加密回执。

平台支持：macOS、Windows 和 Linux —— 需要 Node.js 18+

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

Claude Code

添加到项目根目录的 .mcp.json 中：

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

Cursor

添加到项目根目录的 .cursor/mcp.json 中：

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

快速入门：SDK

npm install @agent-receipts/sdk

import { AgentReceipts } from '@agent-receipts/sdk'

const ar = new AgentReceipts()

const receipt = await ar.track({
  action: 'generate_report',
  input: { query: 'Q4 revenue' },
  output: { total: 142000 },
})

console.log(receipt.receipt_id)  // rcpt_8f3k2j4n...
console.log(receipt.signature)   // ed25519 signature

快速入门：CLI

npx @agent-receipts/cli init          # Generate signing keys
npx @agent-receipts/cli keys          # Show public key
npx @agent-receipts/cli list          # List all receipts
npx @agent-receipts/cli verify <id>   # Verify a receipt signature

工作原理

Agent 执行操作 —— API 调用、代码生成、数据查询
输入/输出进行 SHA-256 哈希处理 —— 原始数据永远不会离开你的机器
创建回执 —— 包含操作、哈希、时间戳、Agent ID 和元数据
回执进行 Ed25519 签名 —— 使用本地生成的私钥
任何人均可验证 —— 分享你的公钥；接收者可独立验证

MCP 工具参考

MCP server 暴露了 14 个可供 AI Agent 直接调用的工具：

工具	描述	关键参数
`track_action`	追踪带有自动哈希的 Agent 操作	`action`, `input`, `output`, `constraints`
`create_receipt`	使用预计算哈希创建回执	`action`, `input_hash`, `output_hash`, `constraints`
`complete_receipt`	使用结果完成待处理的回执	`receipt_id`, `output`, `status`
`verify_receipt`	验证回执的加密签名	`receipt_id`
`get_receipt`	通过 ID 获取回执	`receipt_id`
`list_receipts`	列出回执（支持过滤）	`agent_id`, `status`, `chain_id`
`get_chain`	按时间戳顺序获取链中的所有回执	`chain_id`
`get_public_key`	导出用于验证的 Ed25519 公钥	—
`judge_receipt`	启动 AI Judge 对回执进行评估	`receipt_id`, `rubric`
`complete_judgment`	使用结果完成待处理的评估	`receipt_id`, `verdict`, `score`, `criteria`
`get_judgments`	获取回执的所有评估结果	`receipt_id`
`cleanup`	删除过期回执 (TTL)	`dry_run`
`generate_invoice`	根据日期范围内的回执生成发票	`from`, `to`, `format`, `agent_id`
`get_started`	显示带有使用示例的入门指南	—

SDK API 参考

`new AgentReceipts(config?)`

const ar = new AgentReceipts({
  dataDir: '~/.agent-receipts',  // optional, defaults to ~/.agent-receipts
})

`ar.track(params)` — 追踪已完成的操作

const receipt = await ar.track({
  action: 'analyze_data',
  input: { dataset: 'sales_2024' },
  output: { summary: 'Revenue up 12%' },
  agent_id: 'analyst-v2',
  chain_id: 'chain_abc',              // optional, auto-generated if omitted
  parent_receipt_id: 'rcpt_prev',     // optional, links to parent receipt
})

`ar.start(params)` — 开始一个待处理的回执

const receipt = await ar.start({
  action: 'long_running_task',
  input: { job_id: '12345' },
})

`ar.complete(receiptId, params)` — 完成一个待处理的回执

const completed = await ar.complete(receipt.receipt_id, {
  output: { result: 'done' },
  status: 'completed',
})

`ar.verify(receiptId)` — 验证回执签名

const { verified, receipt } = await ar.verify('rcpt_8f3k2j4n')
// verified: true | false

`ar.get(receiptId)` — 通过 ID 获取回执

const receipt = await ar.get('rcpt_8f3k2j4n')

`ar.list(filter?)` — 列出回执

const result = await ar.list({ agent_id: 'my-agent', status: 'completed' })
// result.data: ActionReceipt[]
// result.pagination: { page, limit, total, total_pages, has_next, has_prev }

`ar.getPublicKey()` — 获取签名公钥

const publicKey = await ar.getPublicKey()
// 64-char hex string (Ed25519 public key)

`ar.track()` 配合约束使用

const receipt = await ar.track({
  action: 'generate_summary',
  input: { document_id: 'doc-q4-2024' },
  output: { summary: 'Revenue grew 12% YoY...' },
  latency_ms: 1200,
  cost_usd: 0.005,
  constraints: [
    { type: 'max_latency_ms', value: 5000 },
    { type: 'max_cost_usd', value: 0.01 },
    { type: 'min_confidence', value: 0.8 },
  ],
})
// receipt.constraint_result.passed → true/false

`ar.getJudgments(receiptId)` — 获取评估结果

const judgments = await ar.getJudgments('rcpt_8f3k2j4n')

`ar.cleanup()` — 删除过期回执

const { deleted, remaining } = await ar.cleanup()

`ar.generateInvoice(params)` — 根据回执生成发票

const invoice = await ar.generateInvoice({
  from: '2026-01-01',
  to: '2026-01-31',
  agent_id: 'my-agent',       // optional filter
  group_by: 'agent',          // optional: agent | action | day
})

CLI 参考

命令	描述
`init`	创建数据目录并生成签名密钥
`keys`	显示公钥
`keys --export`	导出 JSON 格式公钥
`keys --import <hex>`	导入私钥 (64 位十六进制字符)
`inspect <id	file>`	格式化打印回执内容
`verify <id	file>`	验证回执签名
`verify <id	file> --key `	使用外部公钥进行验证
`list`	列出回执 (默认: 50)
`list --agent <id> --status <s>`	按 Agent 或状态过滤
`list --json`	以 JSON 格式输出
`chain <chain_id>`	显示链中的所有回执
`chain <chain_id> --tree`	以可视化树状结构显示链
`stats`	显示回执统计汇总
`judgments <id>`	列出回执的评估结果
`cleanup`	删除过期回执
`cleanup --dry-run`	预览将要删除的内容
`export <id>`	将单个回执导出为 JSON
`export --all`	将所有回执导出为紧凑 JSON
`export --all --pretty`	将所有回执导出为格式化 JSON
`invoice --from <date> --to <date>`	根据日期范围生成发票
`invoice --format <fmt>`	输出为 json, csv, md 或 html
`seed --demo`	植入演示数据用于测试
`seed --demo --count <n>`	植入指定数量的演示回执
`seed --demo --clean`	植入前删除所有回执
`watch`	实时监控新回执
`watch --agent <id>`	按 Agent、操作或状态过滤监控

回执格式

{
  "receipt_id": "rcpt_8f3k2j4n",
  "chain_id": "chain_x9f2k",
  "parent_receipt_id": null,
  "receipt_type": "action",
  "agent_id": "my-agent",
  "org_id": "my-org",
  "action": "generate_report",
  "status": "completed",
  "input_hash": "sha256:abc123...",
  "output_hash": "sha256:def456...",
  "output_summary": "Generated Q4 report",
  "model": "claude-sonnet-4-20250514",
  "timestamp": "2026-02-07T14:32:01.442Z",
  "completed_at": "2026-02-07T14:32:02.100Z",
  "latency_ms": 658,
  "cost_usd": 0.003,
  "signature": "ed25519:<hex>"
}

输入和输出在客户端使用 SHA-256 进行哈希处理。原始数据永远不会离开你的环境。回执中仅存储哈希值。

验证

将你的公钥分享给任何需要验证你回执的人：

# Export your public key
npx @agent-receipts/cli keys --export

# Verify a receipt with an external public key
npx @agent-receipts/cli verify receipt.json --key <public-key-hex>

验证过程会重新计算回执确定性字段上的 Ed25519 签名，并确认其与存储的签名匹配。无需网络请求 —— 完全离线。

配置

环境变量	描述	默认值
`AGENT_RECEIPTS_DATA_DIR`	数据目录路径	`~/.agent-receipts`
`AGENT_RECEIPTS_AGENT_ID`	默认 Agent ID	`local-agent`
`AGENT_RECEIPTS_ORG_ID`	组织 ID	`local-org`
`AGENT_RECEIPTS_ENVIRONMENT`	环境标签 (`development`, `production`, `staging`, `test`)	`production`
`RECEIPT_SIGNING_PRIVATE_KEY`	Ed25519 私钥 (hex)	自动生成

存储

所有数据均本地存储在数据目录中：

~/.agent-receipts/
├── keys/
│   ├── private.key          # Ed25519 private key (mode 0600)
│   └── public.key           # Ed25519 public key
├── receipts/
│   └── *.json               # Legacy JSON files (auto-migrated)
├── receipts.db              # SQLite database (primary storage)
└── config.json              # Agent and org configuration

从 v0.2.7 版本开始，回执存储在 SQLite 中，支持索引查询以实现快速过滤和分页。现有的 JSON 回执文件会在首次启动时自动迁移。

架构

┌─────────────────────────────────────────────┐
│                  CLI                         │
│           @agent-receipts/cli                 │
├─────────────────────────────────────────────┤
│           SDK            │   MCP Server      │
│   @agent-receipts/sdk     │ @agent-receipts/   │
│                          │   mcp-server      │
├──────────────────────────┴──────────────────┤
│              Crypto + Schema                 │
│   @agent-receipts/crypto  @agent-receipts/     │
│                            schema            │
└─────────────────────────────────────────────┘

schema — Zod 模式、TypeScript 类型、Action Receipt Protocol 的 JSON Schema
crypto — Ed25519 密钥生成、签名、验证、规范化序列化
mcp-server — 带有回执引擎、存储和密钥管理的 MCP 协议服务器
sdk — 封装引擎的高级 Node.js SDK
cli — 用于检查、验证和管理回执的命令行工具
dashboard — 用于可视化和管理回执的 Mission Control Web UI

仪表盘 (Mission Control)

可视化系统中的每一个回执、链、Agent、约束和评估。

npx @agent-receipts/dashboard

在 http://localhost:3274 打开 Mission Control —— 可视化、验证并管理所有回执。

功能：实时回执流、链可视化、约束健康监控、评估分数、签名验证、发票生成、深色模式、全局搜索。

13 个页面：概览、回执、回执详情、链、链详情、Agent、Agent 详情、约束、评估、发票、验证、设置、工作原理。

示例

示例	描述
`examples/basic`	带有验证的简单操作追踪
`examples/chained`	带有父/子回执链接的多步流水线
`examples/pipeline`	带有链式回执的文档分析流水线
`examples/constraints`	带有通过/失败规则的约束验证
`examples/judge`	带有评估准则的 AI Judge 评估
`examples/ttl`	回执 TTL 和清理

包

包	描述
`@agent-receipts/schema`	Action Receipt Protocol 的 Zod 模式和 TypeScript 类型
`@agent-receipts/crypto`	Ed25519 签名、验证和密钥管理
`@agent-receipts/mcp-server`	带有回执引擎和存储的 MCP 协议服务器
`@agent-receipts/sdk`	用于追踪和验证回执的高级 Node.js SDK
`@agent-receipts/cli`	用于管理回执的命令行工具
`@agent-receipts/dashboard`	Mission Control Web UI — `npx @agent-receipts/dashboard`

路线图

[x] 本地优先的回执存储 (带索引查询的 SQLite)
[x] Ed25519 签名和验证
[x] 带有 14 个工具的 MCP 服务器
[x] Node.js SDK
[x] 具备完整命令集的 CLI
[x] 约束验证 (6 种内置类型)
[x] 基于评估准则的 AI Judge
[x] 输出模式验证 (JSON Schema)
[x] 回执 TTL 和清理
[x] 发票生成 (JSON, CSV, Markdown, HTML)
[x] Mission Control 仪表盘 (13 个页面，深色模式，搜索)
[x] 仪表盘 npm 包 — npx @agent-receipts/dashboard
[x] 在 agent-receipts-web.vercel.app 上的在线演示
[ ] 回执锚定到区块链/时间戳服务
[ ] 多 Agent 回执共享协议
[ ] 回执压缩和归档
[ ] 托管层级及云数据库

开发

pnpm install
pnpm build
pnpm test
pnpm dev

许可证

MIT — 见 LICENSE

agent-receipts

Agent Receipts

真实世界示例

快速入门：MCP Server

Claude Desktop

Claude Code

Cursor

快速入门：SDK

快速入门：CLI

工作原理

MCP 工具参考

SDK API 参考

`new AgentReceipts(config?)`

`ar.track(params)` — 追踪已完成的操作

`ar.start(params)` — 开始一个待处理的回执

`ar.complete(receiptId, params)` — 完成一个待处理的回执

`ar.verify(receiptId)` — 验证回执签名

`ar.get(receiptId)` — 通过 ID 获取回执

`ar.list(filter?)` — 列出回执

`ar.getPublicKey()` — 获取签名公钥

`ar.track()` 配合约束使用

`ar.getJudgments(receiptId)` — 获取评估结果

`ar.cleanup()` — 删除过期回执

`ar.generateInvoice(params)` — 根据回执生成发票

CLI 参考

回执格式

验证

配置

存储

架构

仪表盘 (Mission Control)

示例

包

路线图

开发

许可证

Resources

Tools

Latest Blog Posts

MCP directory API

Agent Receipts

真实世界示例

快速入门：MCP Server

Claude Desktop

Claude Code

Cursor

快速入门：SDK

快速入门：CLI

工作原理

MCP 工具参考

SDK API 参考

new AgentReceipts(config?)

ar.track(params) — 追踪已完成的操作

ar.start(params) — 开始一个待处理的回执

ar.complete(receiptId, params) — 完成一个待处理的回执

ar.verify(receiptId) — 验证回执签名

ar.get(receiptId) — 通过 ID 获取回执

ar.list(filter?) — 列出回执

ar.getPublicKey() — 获取签名公钥

ar.track() 配合约束使用

ar.getJudgments(receiptId) — 获取评估结果

ar.cleanup() — 删除过期回执

ar.generateInvoice(params) — 根据回执生成发票

CLI 参考

回执格式

验证

配置

存储

架构

仪表盘 (Mission Control)

示例

包

路线图

开发

许可证

Resources

Tools

Latest Blog Posts

MCP directory API

`new AgentReceipts(config?)`

`ar.track(params)` — 追踪已完成的操作

`ar.start(params)` — 开始一个待处理的回执

`ar.complete(receiptId, params)` — 完成一个待处理的回执

`ar.verify(receiptId)` — 验证回执签名

`ar.get(receiptId)` — 通过 ID 获取回执

`ar.list(filter?)` — 列出回执

`ar.getPublicKey()` — 获取签名公钥

`ar.track()` 配合约束使用

`ar.getJudgments(receiptId)` — 获取评估结果

`ar.cleanup()` — 删除过期回执

`ar.generateInvoice(params)` — 根据回执生成发票