webaesbyamin/agent-receipts

# Agent Receipts **加密签名证明，证实 AI Agent 确实执行了它所声称的操作。** [](https://glama.ai/mcp/servers/webaesbyamin/agent-receipts) [](https://www.npmjs.com/package/@agent-receipts/sdk) [](./LICENSE) Agent Receipts 是一个本地优先、开源的系统，用于为自主 Agent 的操作创建可验证、不可篡改的收据。每一个操作都经过 Ed25519 签名、内容哈希和链式链接 —— 无需托管的 API。可用作 MCP server、Node.js SDK 或 CLI。 ## 现实世界示例 我构建了 ModQuote —— 一个面向汽车维修店的多租户 SaaS。在开发过程中，我广泛使用 Claude Code 来审计和修复代码库。 问题在于：当出现问题时，我无法证明 Claude 接收了什么输入、它修改了什么，或者输出是否符合预期。 有了 Agent Receipts，现在每个 Claude Code 会话都会生成签名收据： - **Input hash（输入哈希）** 确切证明了 Claude 看到的代码内容 - **Output hash（输出哈希）** 确切证明了它生成的内容 - **Constraints（约束）** 能够捕捉延迟峰值或成本超出预算的情况 - **Chains（链）** 展示多步审计会话的完整序列 当修复未按预期工作时，我可以调出收据，验证签名，并查看确切的输入/输出哈希 —— 无需猜测，无需“Claude 肯定误解了”。 这就是日志和收据的区别。日志告诉你发生了什么。收据能证明发生了什么。 ## 快速开始：MCP Server 将 Agent Receipts MCP server 添加到你的 AI 工具配置中，每个操作都会自动获得加密收据。 ### 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 # Verify a receipt signature ``` ## 工作原理 1. **Agent 执行一个操作** —— API 调用、代码生成、数据查找 2. **输入/输出进行 SHA-256 哈希** —— 原始数据不会离开你的机器 3. **创建收据** —— 操作、哈希、时间戳、Agent ID、元数据 4. **收据经 Ed25519 签名** —— 使用本地生成的私钥 5. **任何人都可以验证** —— 分享你的公钥；接收方独立验证 ## 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 ` | 导入私钥 (64 个十六进制字符) | | `inspect ` | 美化打印收据 | | `verify ` | 验证收据签名 | | `verify --key ` | 使用外部公钥验证 | | `list` | 列出收据 (默认: 50) | | `list --agent --status ` | 按 Agent 或状态过滤 | | `list --json` | 输出为 JSON | | `chain ` | 显示链中的所有收据 | | `chain --tree` | 以可视化树状图显示链 | | `stats` | 显示汇总收据统计信息 | | `judgments ` | 列出收据的判定 | | `cleanup` | 删除过期收据 | | `cleanup --dry-run` | 预览将被删除的内容 | | `export ` | 将单个收据导出为 JSON | | `export --all` | 将所有收据导出为紧凑 JSON | | `export --all --pretty` | 将所有收据导出为格式化 JSON | | `invoice --from --to ` | 从日期范围内的收据生成发票 | | `invoice --format ` | 输出为 json, csv, md, 或 html | | `seed --demo` | 填充演示数据以进行测试 | | `seed --demo --count ` | 填充自定义数量的演示收据 | | `seed --demo --clean` | 在填充前删除所有收据 | | `watch` | 实时监听新收据 | | `watch --agent ` | 按 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:" } ``` 输入和输出在客户端使用 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 ``` 验证过程会根据收据的确定性字段重新计算 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 私钥 | 自动生成 | ## 存储 所有数据本地存储在数据目录中： ``` ~/.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** — Action Receipt Protocol 的 Zod schemas、TypeScript 类型、JSON Schema - **crypto** — Ed25519 密钥生成、签名、验证、规范序列化 - **mcp-server** — 带有收据引擎、存储和密钥管理的 MCP 协议服务器 - **sdk** — 封装引擎的高级 Node.js SDK - **cli** — 用于检查、验证和管理收据的命令行工具 - **dashboard** — 用于可视化和管理收据的 Mission Control Web UI ## Dashboard (Mission Control) 可视化你系统中的每一个收据、链、Agent、约束和判定。 ``` npx @agent-receipts/dashboard ``` 在 http://localhost:3274 打开 Mission Control —— 可视化、验证和管理所有收据。 功能：实时收据流、链可视化、约束健康监控、判定分数、签名验证、发票生成、暗黑模式、全局搜索。 13 个页面：Overview, Receipts, Receipt Detail, Chains, Chain Detail, Agents, Agent Detail, Constraints, Judgments, Invoices, Verify, Settings, How It Works。 ## 示例 | 示例 | 描述 | |---------|-------------| | [`examples/basic`](./examples/basic) | 带验证的简单操作跟踪 | | [`examples/chained`](./examples/chained) | 带父/子收据链接的多步骤 pipeline | | [`examples/pipeline`](./examples/pipeline) | 带链式收据的文档分析 pipeline | | [`examples/constraints`](./examples/constraints) | 带通过/失败规则的约束验证 | | [`examples/judge`](./examples/judge) | 带评分标准的 AI Judge 评估 | | [`examples/ttl`](./examples/ttl) | 收据 TTL 和清理 | ## 包 | 包 | 描述 | |---------|-------------| | `@agent-receipts/schema` | Action Receipt Protocol 的 Zod schemas 和 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 server - [x] Node.js SDK - [x] 带完整命令集的 CLI - [x] 约束验证 (6 种内置类型) - [x] 带基于评分标准评估的 AI Judge - [x] 输出 schema 验证 - [x] 收据 TTL 和清理 - [x] 发票生成 (JSON, CSV, Markdown, HTML) - [x] Mission Control dashboard (13 个页面，暗黑模式，搜索) - [x] Dashboard npm 包 — `npx @agent-receipts/dashboard` - [x] 在线演示地址 [agent-receipts-web.vercel.app](https://agent-receipts-web.vercel.app/) - [ ] 收据锚定到区块链/时间戳服务 - [ ] 多 Agent 收据共享协议 - [ ] 收据压缩和归档 - [ ] 带云数据库的托管层 ## 开发 ``` pnpm install pnpm build pnpm test pnpm dev ``` ## 许可证 MIT — 详见 [LICENSE](./LICENSE)