kaminocorp/cream

## 什么是 Cream？ Cream 位于 AI 智能体和支付提供商（Stripe、Airwallex、 Coinbase 等）之间，负责管理每一笔交易。把它想象成一个专门用于资金的 API 网关。 智能体从不直接与 Stripe 通信。它与 Cream 通信，由 Cream 决定**是否**允许该支付、**由哪个**提供商处理，以及**为什么** — 然后将所有内容Immutable地记录下来。 **核心问题：** AI 智能体正在获得真正的经济自主权，但管理、审计和执行其支付的基础设施尚不存在。没有单一的提供商能覆盖所有支付渠道、地区和智能体框架。 Cream 填补了这一空白。 ### 核心功能 - **统一 API** — 一个接口支持卡支付、跨境转账和稳定币微支付。智能体无需知道哪个提供商执行了交易。 - **策略引擎** — 在任何资金流动前按优先级顺序评估的声明式规则。金额上限、速度限制、类别限制、地理控制、重复检测 — 12 种内置规则类型。 - **结构化说明** — 每个支付请求必须包含机器可读的结构化理由。没有说明，就没有支付。这为每笔交易创建了智能体编写的审计追踪。 - **智能路由** — 根据成本、延迟、健康状况和通道自动选择最优提供商。熔断器将流量从降级的提供商转移。故障转移是自动的。 - **人工介入** — 策略规则可以要求对任何交易类别进行人工审批。运营者可以通过仪表板或 Slack 通知批准或拒绝。 - **Immutable 审计账本** — 每笔支付的每个步骤（请求、说明、策略决策、路由选择、提供商响应）都写入仅追加日志。数据库在物理上阻止更新和删除。 - **原生 MCP** — AI 智能体开箱即用地通过 Model Context Protocol 连接。Claude、GPT-4、LangChain、LangGraph — 任何支持 MCP 的工具都能与 Cream 配合工作。 ## 架构设计 Cream 的后端是一个 Rust workspace，包含 6 个 crate，呈严格的依赖有向无环图分层： ``` +----------+ | models | Pure types. Zero business logic. +----+-----+ | +---------------+---------------+----------------+ | | | | +----v----+ +-----v-----+ +-----v-----+ +-----v-----+ | audit | | policy | | providers | | router | +---------+ +-----------+ +-----------+ +-----------+ | | | | +---------------+-------+-------+----------------+ | +----v----+ | api | Axum HTTP server. Wires everything together. +---------+ +------------------+ | mcp-server (TS) | TypeScript sidecar. Calls the REST API. +------------------+ ``` | Crate | 职责 | |-------|------| | **`models`** | 支付状态机、类型化 ID、货币枚举、策略规则类型。其他所有 crate 都导入这个。 | | **`policy`** | 规则评估引擎。12 种内置规则类型。无状态 — 接收上下文，返回裁决。无数据库依赖。 | | **`providers`** | `PaymentProvider` trait + 工厂注册表。添加新提供商 = 实现 trait + 注册。核心逻辑零改动。 | | **`router`** | 提供商评分、Redis 熔断器、跨提供商幂等性保护。 | | **`audit`** | 仅追加写入路径和Immutable账本的查询接口。 | | **`api`** | Axum HTTP 服务器。12 个 REST 端点、认证中间件、速率限制、支付生命周期编排器。 | **MCP 服务器**是一个独立的 TypeScript 项目，使用官方 `@modelcontextprotocol/sdk`。它将 MCP 工具调用转换为 REST API 调用 — 零业务逻辑。 ## 支付流程 每笔支付都遵循 8 步确定性管道： ``` [Agent] --> POST /v1/payments (with justification) | [1] Schema validation [2] Agent identity resolution + policy profile loaded [3] Justification evaluation (structural + category checks) [4] Policy engine (rules evaluated in priority order) | BLOCK / ESCALATE / APPROVE | [5] Routing engine (score providers, check circuit breakers) [6] Provider execution (dispatch + automatic failover) [7] Settlement confirmation [8] Audit write (immutable, append-only) | [Agent] <-- { payment_id, status, provider } ``` **延迟目标：** 已批准自主交易的端到端延迟低于 300ms。 ## 技术栈 | 层级 | 技术选型 | 原因 | |-------|-----------|-----| | **核心后端** | Rust (Axum) | 性能、编译时正确性、开源社区认可 | | **数据库** | PostgreSQL (SQLx) | 编译时检查查询、仅追加式审计强制执行 | | **缓存/锁** | Redis | 速率限制、熔断器、跨提供商幂等锁 | | **MCP 服务器** | TypeScript | 官方 `@modelcontextprotocol/sdk` 实现最大生态系统兼容性 | | **仪表板** | Next.js 15 + shadcn/ui | App Router、React Server Components、完善的运营者 UI | | **任务运行器** | justfile | 现代、跨平台命令运行器 | | **基础设施** | Docker Compose | 一键式本地开发环境 | ### 设计原则 - **单租户设计。** 每个运营者一个部署。干净、可分叉、可自托管。 - **Trait 边界无处不在。** 认证、审计、提供商、可观测性 — 全部在 trait 后面。在不触碰核心逻辑的情况下插入你自己的实现。 - **金钱使用 `rust_decimal`，绝不用浮点数。** 数据库中使用 `NUMERIC(19,4)`。支付路径中绝无浮点数。 - **跨提供商幂等性。** Redis 分布式锁防止即使在提供商故障转移期间也不会重复扣款。 ## 快速开始 ### 前置条件 - Rust（stable） - Node.js 20+ - Docker & Docker Compose - [just](https://github.com/casey/just)（任务运行器） ### 本地开发 ``` # 克隆仓库 git clone https://github.com/crimson-sun/cream.git cd cream # 启动 Postgres + Redis just up # 运行数据库迁移 just migrate # 构建后端 just build # 运行 API 服务器 just run-api # 在另一个终端中，启动 MCP 服务器 just run-mcp # 在另一个终端中，启动前端 just fe-dev ``` ### 可用命令 ``` just # List all commands just up # Start Docker services (Postgres + Redis) just down # Stop Docker services just build # Build all Rust crates just check # Type-check without building just test # Run unit tests just test-integration # Run integration tests (requires Docker services) just clippy # Lint with Clippy just fmt # Format code just run-api # Start the API server just run-mcp # Start the MCP server just fe-dev # Start the frontend dev server just fe-build # Build the frontend ``` ## API 概览 ### REST 端点 | 方法 | 端点 | 描述 | |--------|----------|-------------| | `POST` | `/v1/payments` | 发起带有说明的支付 | | `GET` | `/v1/payments/{id}` | 获取支付状态和审计记录 | | `POST` | `/v1/payments/{id}/approve` | 批准升级的支付 | | `POST` | `/v1/payments/{id}/reject` | 拒绝升级的支付 | | `POST` | `/v1/cards` | 发行限定范围的虚拟卡 | | `PATCH` | `/v1/cards/{id}` | 更新卡控制 | | `DELETE` | `/v1/cards/{id}` | 撤销卡 | | `GET` | `/v1/audit` | 查询审计日志 | | `GET` | `/v1/agents/{id}/policy` | 获取智能体的策略配置 | | `PUT` | `/v1/agents/{id}/policy` | 更新智能体的策略配置 | | `GET` | `/v1/providers/health` | 提供商健康状态 | | `POST` | `/v1/webhooks` | 注册 webhook 端点 | ### MCP 工具 通过 MCP 连接的智能体可以使用： - `initiate_payment` — 发起带有结构化说明的支付 - `get_payment_status` — 检查支付状态 - `create_virtual_card` — 发行限定范围的虚拟卡 - `get_my_policy` — 获取当前策略规则 - `get_audit_history` — 查询历史交易 - `check_provider_health` — 检查提供商可用性 ## 路线图 ### 阶段 1：脚手架（当前） - [x] 项目文档和架构设计 - [ ] Monorepo 骨架、Docker Compose、justfile、CI - [ ] 核心领域模型（支付状态机、类型化 ID、策略类型） - [ ] 数据库 schema 和迁移（9 张表、仅追加式审计） - [ ] 策略引擎（12 种内置规则类型） - [ ] Provider trait + 模拟提供商 - [ ] 路由引擎（评分、熔断器、幂等性） - [ ] API 服务器（12 个端点、认证、速率限制、编排器） - [ ] MCP 服务器（TypeScript、6 个工具） - [ ] 前端骨架（8 个仪表板页面） - [ ] CI 流水线（GitHub Actions） ### 阶段 2：提供商集成 - [ ] Stripe Issuing + PaymentIntents - [ ] Airwallex Issuing + Payouts - [ ] Coinbase x402 + AgentKit ### 阶段 3：生产就绪前端 - [ ] 实时交易推送 - [ ] 包含批准/拒绝流程的升级队列 - [ ] 策略编辑器（可视化构建器） - [ ] 审计日志浏览器（支持说明搜索） - [ ] 提供商健康仪表板 - [ ] 智能体管理 UI ### 阶段 4：运维成熟度 - [ ] Webhook 投递 + Slack 升级集成 - [ ] 运营者入职流程 - [ ] 安全加固（凭证轮换、mTLS） - [ ] 可观测性存根（接入你自己的平台） - [ ] API 文档（OpenAPI 规范） - [ ] 负载测试和 E2E 测试套件 ### 未来：亚太区扩展 - [ ] PayNow（新加坡） - [ ] GrabPay（东南亚） - [ ] UPI / Razorpay（印度） ### 未来：协议层 - [ ] Stripe ACP（智能体商务协议） - [ ] Google AP2（智能体支付协议） - [ ] Visa 智能体可信协议（TAP） ## 项目结构 ``` cream/ ├── backend/ │ ├── Cargo.toml # Rust workspace │ ├── crates/ │ │ ├── api/ # Axum HTTP server │ │ ├── audit/ # Append-only audit ledger │ │ ├── models/ # Domain types and state machines │ │ ├── policy/ # Policy evaluation engine │ │ ├── providers/ # Payment provider trait + implementations │ │ └── router/ # Provider routing and circuit breakers │ ├── mcp-server/ # TypeScript MCP server │ └── migrations/ # PostgreSQL migrations ├── frontend/ # Next.js 15 dashboard ├── assets/ # Logo and brand assets ├── docs/ │ ├── tldr.md # 5-minute architecture overview │ ├── background.md # AI agent payments landscape research │ ├── vision.md # Full product specification │ └── executing/ │ ├── implementation-plan.md # Detailed scaffold blueprint │ └── next-phases.md # Post-scaffold roadmap ├── docker-compose.yml # Postgres + Redis ├── justfile # Task runner commands └── LICENSE # Apache 2.0 ``` ## 贡献指南 Cream 是开源的，我们欢迎贡献。项目处于早期开发阶段 — 有很多工作要做。 **适合新手的领域：** - 策略引擎规则实现 - 提供商集成（为你喜欢的 PSP 实现 `PaymentProvider` trait） - 前端仪表板组件 - 文档和示例 架构设计考虑了贡献者体验。每个主要系统（认证、审计、提供商、可观测性）都在 trait 边界后面 — 你可以添加新实现而不触碰核心逻辑。 请参阅 `docs/executing/implementation-plan.md` 获取完整的技术蓝图。 ## 许可证 Cream 根据 [Apache License 2.0](LICENSE) 获得许可。

标签：AI代理, API网关, MCP协议, REST API, Rust, 交易监控, 加密货币, 可视化界面, 合规, 多提供商路由, 审计日志, 微支付, 搜索引擎查询, 支付控制平面, 支付系统, 支付集成, 测试用例, 熔断器, 稳定币, 策略引擎, 结构化审计, 网络安全挑战, 网络流量审计, 自动化支付, 请求拦截, 资金控制, 通知系统, 金融科技, 风控系统