quantumpipes/capsule

# Capsule Protocol **用于自主AI的密码学签名内存层。** 每个AI操作都会产生一个Capsule——一个不可篡改、内容可寻址的记录，记录了发生的事情、原因、审批人以及结果。使用SHA3-256和Ed25519进行密封，并通过链式结构保证时间完整性。可在任何语言中验证。 [](https://opensource.org/licenses/Apache-2.0) [](./spec/) [](./conformance/) [](#cryptographic-seal) [](./reference/python/) [](./AGENTS.md) ## 协议 Capsule是一个密码学密封的单个AI操作记录。它通过六个必需部分捕获完整的审计跟踪： ``` ┌─────────────────────────────────────────────────────────┐ │ CAPSULE │ ├─────────────┬───────────────────────────────────────────┤ │ 1. Trigger │ What initiated this action? │ │ 2. Context │ What was the state of the system? │ │ 3. Reasoning│ Why was this decision made? │ │ 4. Authority│ Who or what approved it? │ │ 5. Execution│ What tools were called? │ │ 6. Outcome │ Did it succeed? What changed? │ ├─────────────┴───────────────────────────────────────────┤ │ SHA3-256 hash │ Ed25519 signature │ ML-DSA-65 (opt.) │ │ Previous hash │ Sequence number │ Timestamp │ └─────────────────────────────────────────────────────────┘ ``` 每个Capsule都使用SHA3-256进行哈希，并用Ed25519签名。每个记录都包含前一个记录的哈希，形成一个链条，任何记录的篡改都会使后续所有记录失效。 ``` ∀ action: ∃ capsule "For every action, there exists a Capsule." ``` ## 为何使用Capsules AI系统做出成千上万的自主决策。当出现问题——或监管者询问“为什么AI会那样做？”——你需要问题提出之前就存在的证据。 Capsules解决了日志记录无法解决的三个问题： **1. 执行前推理捕获** 第3部分（推理）记录了AI的分析、考虑过的选项、选择的选项以及拒绝替代方案的原因——所有这些都在第5部分（执行）运行之前捕获。这是审议的同期证据，而非事后重构。 **2. 密码学篡改证据** 每个Capsule在创建时都会进行哈希和签名。如果有人之后修改内容，哈希会变化，签名会失败，链条会断裂。这是每个独立记录的特性，而非存储层的特性。 **3. 跨语言互操作性** Capsule协议规范定义了字节级序列化规则。在Python中密封的Capsule可以在TypeScript、Go或Rust中验证。所有实现对相同输入都会生成相同的规范JSON，并通过16个黄金测试向量进行验证。 ## 内容寻址 每个密封的Capsule都可以通过其SHA3-256哈希使用`capsule://` URI方案进行寻址： ``` capsule://sha3_4cb02d65a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef12 ``` URI中的哈希即为验证依据。获取内容后，重新计算哈希并确认真实性。不需要注册表。 代理可以引用其他代理的决策。合规报告可以引用特定记录。审计追踪成为可验证的、互相链接的证据网络。 ``` capsule://sha3_C → previous_hash → capsule://sha3_B → previous_hash → capsule://sha3_A ``` 参见 [URI Scheme 规范](./spec/uri-scheme.md)。 ## 哈希链条 每个Capsule记录前一个Capsule的SHA3-256哈希。这创建了一个链条，修改、删除或插入任何记录都会立即被发现。 ``` Capsule #0 Capsule #1 Capsule #2 ┌──────────┐ ┌──────────┐ ┌──────────┐ │ hash: A │◀───────│ prev: A │◀───────│ prev: B │ │ prev: ∅ │ │ hash: B │ │ hash: C │ └──────────┘ └──────────┘ └──────────┘ ``` 无需共识机制。无需分布式账本。仅使用SHA3-256哈希将一条记录链接到下一条。 ### 并发保护（v1.5.0+） 对同一链条的并发写入由`seal_and_store()`自动处理： 1. **唯一约束** — 数据库拒绝重复的序列号（在SQLite上为`UNIQUE(sequence)`，在PostgreSQL上为`UNIQUE(tenant_id, sequence)`） 2. **乐观重试** — 发生冲突时，`seal_and_store()`会重新读取链头，重新计算序列号，重新密封并重试（最多3次） 3. **`ChainConflictError`** — 当所有重试在极端竞争下耗尽时抛出 ``` from qp_capsule import Capsule, CapsuleChain, CapsuleStorage, Seal from qp_capsule.exceptions import ChainConflictError storage = CapsuleStorage() chain = CapsuleChain(storage) seal = Seal() # 安全用于并发使用 — 在序列冲突时自动重试 capsule = await chain.seal_and_store( Capsule(trigger=TriggerSection(source="agent", request="deploy")), seal=seal, tenant_id="org-123", ) # 多租户：每个租户拥有独立的链 await chain.seal_and_store(capsule_a, seal=seal, tenant_id="tenant-a") await chain.seal_and_store(capsule_b, seal=seal, tenant_id="tenant-b") ``` ## 密码学密封 每个Capsule使用两层密码学架构进行密封： | 层 | 算法 | 标准 | 目的 | |---|---|---|---| | | 内容完整性 | SHA3-256 | FIPS 202 | 抗篡改哈希 | | | 经典签名 | Ed25519 | RFC 8032 / FIPS 186-5 | 真实性与不可否认性 | | | 后量子签名 | ML-DSA-65 | FIPS 204 | 可选量子抗性保护 | | | 时间完整性 | 哈希链条 | CPS v1.0 | 顺序与完整性 | 不使用已弃用的密码学。没有运行时网络依赖。支持离线操作。 ## 规范 **Capsule协议规范（CPS）** 定义了完整的协议： | 文档 | 内容 | |---|---| | [CPS v1.0](./spec/) | 记录结构、规范序列化、密封算法、哈希链条规则 | | [URI Scheme](./spec/uri-scheme.md) | `capsule://` 内容可寻址引用 | | [一致性测试套件](./conformance/) | 16个黄金向量（有效） + 15个负向量（无效） | 规范与语言无关。任何通过一致性测试套件的实现都可以密封和验证由其他任何实现生成的Capsules。 ## 示例Capsule ``` { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "type": "agent", "trigger": { "source": "deploy-bot", "request": "Deploy service v2.4 to production" }, "reasoning": { "options_considered": ["Deploy v2.4", "Rollback to v2.3", "Do nothing"], "selected_option": "Deploy v2.4", "confidence": 0.92 }, "authority": { "type": "human_approved", "approver": "ops-lead" }, "execution": { "tool_calls": [{ "tool": "kubectl_apply", "success": true, "duration_ms": 3200 }] }, "outcome": { "status": "success", "summary": "Deployed v2.4 to prod-us-east" }, "hash": "4cb02d65...", "signature": "a3f8b2c1...", "previous_hash": "7d2e9f41...", "sequence": 42 } ``` 六个部分。使用SHA3-256进行哈希。使用Ed25519签名。与前一条记录链接。在执行前捕获推理。 更多示例请参见 [`examples/`](./examples/)。 ## 探索与你的AI编码代理的契合度 将此提示粘贴到Claude Code、Cursor、Codex或任何其他代理中： ``` Read the Capsule Protocol README and AGENTS.md at https://github.com/quantumpipes/capsule. Then survey my codebase for every place an AI agent takes autonomous action (tool calls, LLM completions, scheduled jobs, deploy triggers) and currently lacks a tamper-evident audit trail. For each, explain what a capsule would record. Recommend the single highest-leverage place to start, with concrete files and functions to change. ``` ## 实现 ### 参考实现 这些实现位于本仓库中，并为每种语言定义了正确行为： | 语言 | 状态 | 安装 | 源码 | |---|---|---|---| | **Python** | v1.3.0 — 创建、密封、验证、链式、存储、CLI | `pip install qp-capsule` | [`reference/python/`](./reference/python/) | | **TypeScript** | v0.0.1 — 创建、密封、验证、链式 | `npm install @quantumpipes/capsule` | [`reference/typescript/`](./reference/typescript/) | ### 生态库 这些库将协议扩展到新的语言和框架： | 库 | 用途 | 安装 | 源码 | |---|---|---|---| | **[capsule-go](https://github.com/quantumpipes/capsule-go)** | 在Go中验证Capsules | `go get github.com/quantumpipes/capsule-go` | [quantumpipes/capsule-go](https://github.com/quantumpipes/capsule-go) | | **[capsule-litellm](https://github.com/quantumpipes/capsule-litellm)** | 为LiteLLM提供自动审计追踪 | `pip install capsule-litellm` | [quantumpipes/capsule-litellm](https://github.com/quantumpipes/capsule-litellm) | | capsule-rust | 在Rust中验证Capsules | — | 计划中 | 所有实现必须通过[一致性测试套件](./conformance/)。规范是事实上的唯一来源。 ## 快速启动（Python） ``` pip install qp-capsule ``` ``` from qp_capsule import Capsule, Seal, CapsuleType, TriggerSection capsule = Capsule( type=CapsuleType.AGENT, trigger=TriggerSection( source="deploy-bot", request="Deploy service v2.4 to production", ), ) seal = Seal() seal.seal(capsule) assert seal.verify(capsule) ``` ## 快速启动（Go — 验证） ``` go get github.com/quantumpipes/capsule-go ``` ``` import capsule "github.com/quantumpipes/capsule-go" // Verify a capsule's hash integrity valid := capsule.VerifyHash(capsuleDict, expectedHash) // Verify an Ed25519 signature valid := capsule.VerifySignature(hashHex, signatureHex, publicKeyHex) // Verify an entire chain (structural + cryptographic) errs := capsule.VerifyChainFull(sealedCapsules) ``` Go库仅提供验证功能，按设计如此。在任何语言中密封，在Go中验证——基础设施工具、CI门控和审计管道可以在不依赖完整SDK的情况下验证Capsules。 ### 快速启动（LiteLLM 集成） ``` pip install capsule-litellm ``` ``` import litellm from capsule_litellm import CapsuleLogger litellm.callbacks = [CapsuleLogger()] # 每次 LLM 调用现在都会自动生成密封的 Capsule response = litellm.completion( model="gpt-4o", messages=[{"role": "user", "content": "Deploy service v2.4"}], ) ``` 两行代码。每次调用`litellm.completion()`和`litellm.acompletion()`都会生成一个密封的、哈希链式Capsule，包含模型身份、SHA3-256提示哈希、token指标和延迟——无需修改应用代码。 ### 快速启动（TypeScript） ``` npm install @quantumpipes/capsule ``` ``` import { createCapsule, seal, verify, generateKeyPair } from "@quantumpipes/capsule"; const capsule = createCapsule({ type: "agent", trigger: { type: "user_request", source: "deploy-bot", timestamp: new Date().toISOString().replace("Z", "+00:00"), request: "Deploy service v2.4 to production", correlation_id: null, user_id: null, }, }); const { privateKey, publicKey } = generateKeyPair(); await seal(capsule, privateKey); console.log(await verify(capsule, await publicKey)); // true ``` ### CLI Python包包含一个用于验证、检查和密钥管理的CLI： ``` capsule verify chain.json # Structural verification capsule verify --full --db capsules.db # + SHA3-256 recomputation capsule verify --signatures --json chain.json # + Ed25519, JSON output capsule inspect --db capsules.db --seq 47 # Full 6-section display capsule keys info # Epoch history capsule keys rotate # Rotate to new key (no downtime) capsule hash document.pdf # SHA3-256 of any file ``` 退出代码：`0` = 通过，`1` = 失败，`2` = 错误。设计用于CI/CD门控：`capsule verify --quiet && deploy`。 参见 [Python参考文档](./reference/python/) 获取完整指南。 ## 合规性 Capsule在协议层面映射到11个监管框架。每个映射都记录了协议满足哪些控制项，以及哪些需要应用层补充控制。 | 框架 | 控制项 | 重点 | |---|---|---| | [NIST SP 800-53](./docs/compliance/nist-sp-800-53.md) | AU-2 到 AU-12，SC-13，SC-28，SI-7 | 审计、完整性、密码学 | | [NIST AI RMF](./docs/compliance/nist-ai-rmf.md) | GOVERN、MAP、MEASURE、MANAGE | AI风险管理 | | [EU AI Act](./docs/compliance/eu-ai-act.md) | 第12、13、14条 | 记录保存、透明度、监督 | | [SOC 2](./docs/compliance/soc2.md) | CC6.1、CC7.2、CC7.3、CC7.4、CC8.1 | 信任服务标准 | | [ISO 27001](./docs/compliance/iso27001.md) | A.8.15 到 A.8.25 | 附录A控制项 | | [HIPAA](./docs/compliance/hipaa.md) | §164.308、§164.312 | 安全规则保障 | | [GDPR](./docs/compliance/gdpr.md) | 第5、25、30、32、35条 | 数据保护 | | [PCI DSS](./docs/compliance/pci-dss.md) | 要求10、11.5、11.6 | 日志记录、变更检测 | | [FedRAMP](./docs/compliance/fedramp.md) | AU-9(3)、AU-10、SI-7、CM-3 | 联邦云 | | [FINRA](./docs/compliance/finra.md) | SEC 17a-4、REC-2、Rule 3110 | 财务记录保存 | | [CMMC](./docs/compliance/cmmc.md) | AU.L2-3.3.x、SC.L2-3.13.x | DoD CUI保护 | 参见 [合规概览](./docs/compliance/) 了解FIPS算法详细信息和适用范围。 ## 文档 | 文档 | 目标读者 | |---|---| | [架构](./docs/architecture.md) | 开发者、审计员 | | [安全评估](./docs/security.md) | CISO、安全团队 | | [合规映射](./docs/compliance/) | 监管者、GRC | | [为何使用Capsules](./docs/why-capsules.md) | 决策者、架构师 | | [实现者指南](./docs/implementors-guide.md) | SDK作者 | | [CLI参考](./docs/architecture.md#cli) | DevOps、审计员 | ## 贡献 参见 [CONTRIBUTING.md](./CONTRIBUTING.md)。协议变更需通过[CPS变更提案](https://github.com/quantumpipes/capsule/issues/new?template=spec-change.md)流程。任何语言的实现贡献都欢迎。 ## 许可与专利 [Apache License 2.0](./LICENSE) 附带[额外专利授权](./PATENTS.md)。你可自由将专利创新用于任何目的，包括商业用途。 **∀ action: ∃ capsule** 一个开放协议 · [Python](./reference/python/) · [TypeScript](./reference/typescript/) · [Go](https://github.com/quantumpipes/capsule-go) · [LiteLLM](https://github.com/quantumpipes/capsule-litellm) · [一致性测试套件](./conformance/) 适用于任何语言 [规范](./spec/) · [一致性](./conformance/) · [安全策略](./SECURITY.md) · [专利授权](./PATENTS.md) Copyright 2026 [Quantum Pipes Technologies, LLC](https://quantumpipes.com)