# https://github.com/mnemopay/mnemopay-sdk 项目说明书
生成时间：2026-05-15 05:38:18 UTC
## 目录
- [项目概述](#getting-started)
- [快速开始](#quick-start)
- [内存与记忆系统](#memory-system)
- [账本与支付系统](#ledger-payments)
- [身份与认证系统](#identity-auth)
- [代理信用评分系统](#credit-score)
- [行为金融引擎](#behavioral-finance)
- [异常检测系统](#anomaly-detection)
- [支付轨道](#payment-rails)
- [治理与合规框架](#governance)
## 项目概述
### 相关页面
相关主题：[快速开始](#quick-start), [内存与记忆系统](#memory-system), [代理信用评分系统](#credit-score)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
- [dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)
- [site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)
- [site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)
- [site/calculator.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/calculator.html)
- [integrations/python-hosted/README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/python-hosted/README.md)
# 项目概述
## 项目简介
MnemoPay SDK 是一个专为 AI Agent（人工智能代理）设计的支付与记忆基础设施开发工具包。该项目由 Jeremiah Omiagbo 创建，采用 Apache 2.0 开源许可证，为开发者提供了将货币化能力、持久化记忆和身份验证集成到 AI 代理应用中的完整解决方案。资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
MnemoPay 不仅仅是一个 Stripe 包装器，而是一个为代理原生构建的完整支付系统，支持 Stripe、Paystack 和 Lightning（加密货币）三种支付通道。资料来源：[site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)
## 核心版本信息
| 版本类型 | 版本号 | 说明 |
|---------|--------|------|
| 稳定版 | v1.5.0 | 通过 `latest` 标签分发 |
| 预发布版 | v1.6.0-alpha | 当前 alpha 测试版本 |
资料来源：[README.md:27](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
## 技术架构
MnemoPay SDK 的架构采用分层模块化设计，集成了多个核心子系统。以下是整体架构示意图：
```mermaid
graph TB
subgraph 顶层
G[GOVERNANCE
Charter · FiscalGate
Article 12 · MerkleAudit]
end
subgraph 核心功能层
M[Memory
remember · recall
reinforce · forget]
P[Payments
charge · settle
refund · dispute]
I[Identity
KYA · tokens
perms · killswitch]
end
subgraph 高级功能层
C[Agent Credit Score
300-850 评分
5组件评分体系]
B[Behavioral Finance
前景理论
行为引导]
A[Anomaly Detection
EWMA + 指纹识别]
end
G --> M
G --> P
G --> I
I --> C
C --> B
B --> A
```
资料来源：[README.md:28-42](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
## 核心子系统详解
### 记忆系统（Memory）
记忆系统为 AI Agent 提供了持久化和检索信息的能力，支持以下核心操作：
| 方法 | 功能描述 |
|------|----------|
| `remember()` | 存储新记忆内容 |
| `recall()` | 检索相关记忆 |
| `reinforce()` | 强化重要记忆 |
| `forget()` | 删除指定记忆 |
该系统支持命名空间隔离，允许按业务领域组织记忆数据。资料来源：[integrations/python-hosted/README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/python-hosted/README.md)
### 支付系统（Payments）
支付系统支持完整的交易生命周期管理：
```mermaid
graph LR
A[charge
扣款] --> B[escrow
资金托管]
B --> C{人工审批}
C -->|通过| D[settle
结算]
C -->|拒绝| E[refund
退款]
D --> F[(Ledger
账本记录)]
E --> F
```
| 支付通道 | 支持地区 | 特色功能 |
|---------|---------|---------|
| Paystack | 非洲（NGN, GHS, ZAR, KES） | 23家尼日利亚银行预映射，HMAC-SHA512 安全验证 |
| Stripe | 全球（USD, EUR, GBP） | 手动捕获实现真实托管，支持135+种货币 |
| Lightning | 加密货币 | 闪电网络即时结算 |
资料来源：[site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)
### 身份系统（Identity）
身份系统包含四个关键组件：
- **KYA（Know Your Agent）**：代理身份验证
- **Tokens**：代币管理机制
- **Permissions**：权限控制系统
- **Killswitch**：紧急终止开关
### Agent 信用评分（Agent Credit Score）
MnemoPay 引入了一套基于 300-850 分值范围的信用评分体系，参考了传统金融信用评分模型。该评分系统包含五个核心评估维度：
1. 支付历史分析
2. 交易行为模式
3. 账户活跃度
4. 风险指标评估
5. 身份验证等级
资料来源：[README.md:33](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
### 行为金融模块（Behavioral Finance）
基于前景理论（Prospect Theory）设计，提供用户行为引导和激励优化功能。该模块帮助开发者构建更符合用户心理预期的交易体验。资料来源：[README.md:38](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
### 异常检测模块（Anomaly Detection）
采用指数加权移动平均（EWMA）算法结合指纹识别技术，实时监控和识别可疑交易行为。资料来源：[README.md:39](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
### 治理系统（Governance）
治理模块包含四个核心组件：
| 组件 | 功能 |
|------|------|
| Charter | 代理行为宪章 |
| FiscalGate | 财务门控机制 |
| Article 12 | 第12条合规条款 |
| MerkleAudit | 默克尔树审计 |
该模块负责任务范围界定、预算执行和审计捆绑。资料来源：[README.md:29-30](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
## 开发工作流
基于 MnemoPay SDK 构建应用的标准流程包含四个步骤：
```mermaid
graph TD
A[1. 安装
npm install @mnemopay/sdk] --> B[2. 初始化
MnemoPay.quick agent-id]
B --> C[3. 交易操作
charge · settle · refund]
C --> D[4. 规模扩展
自主购物 · 多代理商务 · 信用评分]
```
资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)
## 中间件集成
MnemoPay SDK 提供与主流 AI 框架的中间件集成：
| 框架 | 导入路径 | 说明 |
|------|---------|------|
| OpenAI | `@mnemopay/sdk/middleware/openai` | OpenAI API 中间件 |
| Anthropic | `@mnemopay/sdk/middleware/anthropic` | Claude API 中间件 |
| LangGraph | `@mnemopay/sdk/langgraph` | LangGraph 工具集成 |
资料来源：[README.md:11-17](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
## Python SDK 功能
Python 集成包 `mnemopay` 提供了完整的功能接口：
### 主要方法
| 方法 | 参数 | 返回值 |
|------|------|--------|
| `remember(content, namespace, tags, importance)` | 内容、命名空间、标签、重要性 | 记忆 ID |
| `recall(query, namespace, limit, mode)` | 查询词、命名空间、限制数、模式 | 相关记忆列表 |
| `reason(query, namespace, limit, mode)` | 查询词、命名空间、限制数、模式 | 推理结果 |
| `charge(amount, reason)` | 金额、原因 | 交易 ID |
| `settle(tx_id)` | 交易 ID | 结算状态 |
| `usage_report()` | - | 使用量报告 |
| `audit_events(limit)` | 限制数 | 审计事件列表 |
资料来源：[integrations/python-hosted/README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/python-hosted/README.md)
## 仪表板功能
MnemoPay 提供了一个功能丰富的 Web 仪表板（`dashboard/index.html`），包含以下模块：
| 模块 | 功能描述 |
|------|----------|
| 账户概览 | 钱包余额、信誉评分、记忆数量、交易计数 |
| 交易历史 | 完整交易记录与状态追踪 |
| 实时日志 | 系统运行日志与事件流 |
| 记忆管理 | 记忆 CRUD 操作与搜索 |
| GitHub 监控 | 追踪上游仓库状态与 PR |
| 计量仪表 | LLM 调用限额、席位数量 |
| 任务管理 | 任务状态与完成进度 |
资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)
## 套餐定价
| 套餐 | 价格 | 特性 |
|------|------|------|
| Starter | 免费 | 基础 SDK、10个代理、Stripe/Paystack/Lightning、Agent 信用评分 |
| Pro | $49/月 | Starter 全部 + 文件/SQLite 持久化、交易分析仪表板、Webhook 通知、地理位置信任档案 |
交易手续费：Pro 套餐按已结算交易的 1.5% 收取额外费用。资料来源：[site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)
## 商业模式与防欺诈
MnemoPay 提供了一个 chargeback（chargeback 防止）计算器工具，帮助用户评估 AI 代理引发的退款争议的实际成本，以及加密签名收据能为 SaaS 平台节省的费用。资料来源：[site/calculator.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/calculator.html)
## 相关资源
| 资源类型 | 链接 |
|---------|------|
| npm 包 | [@mnemopay/sdk](https://www.npmjs.com/package/@mnemopay/sdk) |
| GitHub 仓库 | github.com/mnemopay/mnemopay-sdk |
| 官方网站 | mnemopay.com |
| 商业联系 | info@getbizsuite.com |
---
## 快速开始
### 相关页面
相关主题：[项目概述](#getting-started), [内存与记忆系统](#memory-system), [账本与支付系统](#ledger-payments)
相关源码文件
以下源码文件用于生成本页说明：
- [examples/01-quick-start.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/examples/01-quick-start.ts)
- [examples/06-production.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/examples/06-production.ts)
- [src/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/index.ts)
- [src/client.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/client.ts)
- [README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
- [site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)
- [site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)
# 快速开始
## 概述
「快速开始」是 MnemoPay SDK 为开发者提供的最短路径集成方案。通过极简的初始化流程，开发者可以在数分钟内为 AI Agent 集成记忆管理、支付处理、身份认证和信用评分四大核心能力。
核心特性：
- **零配置启动**：`MnemoPay.quick("agent-id")` 一行代码完成全部初始化
- **完整能力栈**：内存记忆、钱包交易、KYA 身份验证、Agent 信用评分
- **多支付通道**：支持 Stripe、Paystack、Lightning 三种主流支付轨道
- **中间件生态**：开箱即用的 OpenAI、Anthropic、LangGraph 集成
资料来源：[README.md:1-20]()
## 安装
### 环境要求
| 依赖项 | 最低版本 | 说明 |
|--------|----------|------|
| Node.js | 18.0+ | SDK 运行时环境 |
| npm/pnpm/yarn | 最新版 | 包管理器 |
| API Key | MnemoPay 平台获取 | 连接后端服务 |
### 安装命令
```bash
npm install @mnemopay/sdk
# 或
pnpm add @mnemopay/sdk
```
资料来源：[site/index.legacy.html:50-55]()
## 基础使用
### 快速初始化
使用 `MnemoPay.quick()` 方法实现零配置启动：
```typescript
import { MnemoPay } from "@mnemopay/sdk";
// 方式一：快速初始化（推荐）
const mnemopay = MnemoPay.quick("my-agent-id");
// 方式二：显式配置
const mnemopay = MnemoPay.quick("my-agent-id", {
apiKey: "mnemo_live_sk_xxxx",
environment: "production"
});
```
`quick()` 方法自动完成以下初始化：
1. 创建 Agent 身份标识
2. 初始化内存存储（remember/recall）
3. 配置钱包和支付通道
4. 建立与管理平台的连接
资料来源：[README.md:55-70](), [site/index.legacy.html:56-60]()
### 核心 API 方法
#### 内存管理
| 方法 | 功能 | 返回值 |
|------|------|--------|
| `remember(key, value)` | 存储记忆 | `Promise` |
| `recall(query)` | 检索记忆 | `Promise` |
| `reinforce(memoryId)` | 强化记忆权重 | `Promise` |
| `forget(memoryId)` | 删除记忆 | `Promise` |
```typescript
// 存储用户偏好
await mnemopay.remember("user_pref", {
name: "张三",
tier: "premium"
});
// 检索相关记忆
const memories = await mnemopay.recall("用户 偏好 premium");
```
#### 支付交易
| 方法 | 功能 | 状态 |
|------|------|------|
| `charge(amount, reason)` | 请求收款 | 资金进入托管 |
| `settle(transactionId)` | 确认结算 | 资金释放给 Agent |
| `refund(transactionId)` | 退款 | 资金退回用户 |
```typescript
// 发起收款
const tx = await mnemopay.charge(25.00, "API调用费用");
console.log(`交易 ID: ${tx.id}`);
// 结算交易
await mnemopay.settle(tx.id);
// 退款
await mnemopay.refund(tx.id);
```
资料来源：[site/index.legacy.html:62-70]()
## 工作流程
```mermaid
graph TD
A[安装 SDK] --> B[快速初始化]
B --> C[Agent 获取身份]
C --> D{选择操作}
D --> E[内存管理]
D --> F[支付交易]
D --> G[身份验证]
D --> H[信用查询]
E --> E1[remember/recall]
F --> F1[charge/settle/refund]
G --> G1[KYA 验证]
H --> H1[信用评分查询]
F1 -->|资金托管| I[Escrow]
I --> J{人类审批}
J -->|批准| K[settle]
J -->|拒绝| L[refund]
```
### 支付流程详解
1. **Charge（收款请求）**：Agent 调用 `charge()` 后，资金进入第三方托管
2. **Escrow（资金托管）**：资金暂存于 Stripe/Paystack/Lightning，直至人工审批
3. **Settle（确认结算）**：人工审核通过后，`settle()` 将资金释放给 Agent
4. **Refund（退款处理）**：交易被拒绝时调用，资金退回用户
资料来源：[site/index.legacy.html:63-68](), [README.md:65-72]()
## 中间件集成
### OpenAI 中间件
```typescript
import { mnemoPayMiddleware } from "@mnemopay/sdk/middleware/openai";
```
将 MnemoPay 支付能力无缝集成到 OpenAI 的 Agent 框架中。
### Anthropic 中间件
```typescript
import { mnemoPayMiddleware } from "@mnemopay/sdk/middleware/anthropic";
```
支持 Anthropic Claude 模型的支付回调集成。
### LangGraph 工具集成
```typescript
import { mnemoPayTools } from "@mnemopay/sdk/langgraph";
```
提供 LangGraph 可调用的支付工具节点。
资料来源：[README.md:35-45]()
## 生产环境配置
### 生产模式初始化
```typescript
import { MnemoPay } from "@mnemopay/sdk";
const mnemopay = MnemoPay.quick("production-agent", {
apiKey: process.env.MNEMO_API_KEY,
environment: "production",
persistence: "sqlite", // 数据持久化
webhookUrl: "https://yourapp.com/webhooks/mnemopay"
});
```
### 配置选项
| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `apiKey` | `string` | 环境变量 | MnemoPay API 密钥 |
| `environment` | `"development" \| "production"` | `"development"` | 运行环境 |
| `persistence` | `"memory" \| "file" \| "sqlite"` | `"memory"` | 数据存储方式 |
| `webhookUrl` | `string` | `null` | Webhook 回调地址 |
### 生产检查清单
- [ ] 使用正式环境 API Key
- [ ] 配置 Webhook 端点
- [ ] 选择合适的持久化方案（生产环境推荐 SQLite）
- [ ] 设置支付通道（Stripe/Paystack/Lightning）
- [ ] 配置 KYA（Know Your Agent）验证流程
资料来源：[examples/06-production.ts](), [site/index.html](), [site/index.legacy.html]()
## 架构概览
```mermaid
graph TB
subgraph "MnemoPay SDK v1.6.0"
A[MnemoPay.quick] --> B[Client]
B --> C[Memory 模块]
B --> D[Payments 模块]
B --> E[Identity 模块]
B --> F[Credit Score 模块]
end
C --> G[(本地存储)]
D --> H[Stripe]
D --> I[Paystack]
D --> J[Lightning]
E --> K[Token 验证]
F --> L[行为分析]
M[OpenAI 中间件] --> B
N[Anthropic 中间件] --> B
O[LangGraph 工具] --> B
```
### 模块职责
| 模块 | 核心功能 | API |
|------|----------|-----|
| Memory | 记忆存储与检索 | `remember`, `recall`, `reinforce`, `forget` |
| Payments | 支付交易处理 | `charge`, `settle`, `refund`, `dispute` |
| Identity | Agent 身份验证 | KYA、Token、Permissions |
| Credit Score | 信用评分系统 | 300-850 分信用评估 |
资料来源：[README.md:15-45]()
## 错误处理
### 常见错误
| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| `AUTH_FAILED` | API Key 无效 | 检查并更新 API Key |
| `INSUFFICIENT_FUNDS` | 余额不足 | 确保账户有足够资金 |
| `TRANSACTION_NOT_FOUND` | 交易不存在 | 检查交易 ID |
| `AGENT_NOT_VERIFIED` | Agent 未验证 | 完成 KYA 流程 |
### 错误处理示例
```typescript
try {
const tx = await mnemopay.charge(100, "服务费");
} catch (error) {
if (error.code === "AUTH_FAILED") {
console.error("请检查 API Key 配置");
} else if (error.code === "AGENT_NOT_VERIFIED") {
console.error("请先完成 Agent 身份验证");
}
}
```
## 下一步
| 资源 | 说明 |
|------|------|
| [完整 API 文档]() | 详细的 SDK API 参考 |
| [支付集成指南]() | Stripe/Paystack/Lightning 配置 |
| [记忆系统详解]() | 高级记忆管理功能 |
| [Agent 信用评分]() | 信用评分机制说明 |
| [Dashboard 使用指南]() | 管理平台功能介绍 |
---
**版本信息**：当前版本 v1.6.0-alpha，`latest` 稳定版为 v1.5.0
资料来源：[README.md:10-12]()
---
## 内存与记忆系统
### 相关页面
相关主题：[项目概述](#getting-started), [异常检测系统](#anomaly-detection), [治理与合规框架](#governance)
相关源码文件
以下源码文件用于生成本页说明：
- [src/recall/engine.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/engine.ts)
- [src/recall/entities.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/entities.ts)
- [src/recall/graph.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/graph.ts)
- [src/recall/hyde.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/hyde.ts)
- [src/recall/observations.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/observations.ts)
- [src/recall/persistence/memory.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/persistence/memory.ts)
- [src/recall/persistence/neon.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/persistence/neon.ts)
- [src/recall/persistence/sqlite.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/persistence/sqlite.ts)
- [src/integrity.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/integrity.ts)
- [src/identity/bundle.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity/bundle.ts)
# 内存与记忆系统
## 概述
MnemoPay SDK 的内存与记忆系统是整个 SDK 的核心模块，负责为 AI Agent 提供持久化记忆能力。该系统使 Agent 能够跨会话保持上下文，实现真正的连续性和个性化交互。
核心功能包括：
- **语义记忆存储**：通过 `remember` 方法存储记忆，支持重要度评分和标签系统
- **混合检索引擎**：`recall` 方法支持语义搜索和混合检索模式
- **知识图谱**：基于实体和关系构建知识网络，支持图结构查询
- **观察点再生**：自动更新实体关联的观察点内容
- **行为强化**：基于交互结果自动调整记忆权重
- **完整性校验**：使用 Merkle 树结构确保记忆数据不可篡改
资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
---
## 系统架构
### 模块分层
```
┌─────────────────────────────────────────────────────────────┐
│ SDK 入口层 │
│ MnemoPay.quick() / MnemoPay() │
├─────────────────────────────────────────────────────────────┤
│ 核心 API 层 │
│ remember | recall | reinforce | forget │
├──────────────┬──────────────┬───────────────┬────────────────┤
│ 检索引擎 │ 实体管理 │ 知识图谱 │ 观察点系统 │
│ recall/ │ recall/ │ recall/ │ recall/ │
│ engine.ts │ entities.ts │ graph.ts │ observations │
├──────────────┴──────────────┴───────────────┴────────────────┤
│ 持久化适配层 │
│ memory.ts | sqlite.ts | neon.ts │
├─────────────────────────────────────────────────────────────┤
│ 完整性校验层 │
│ integrity.ts │
└─────────────────────────────────────────────────────────────┘
```
### 记忆数据结构
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 记忆唯一标识符 |
| `content` | string | 记忆内容 |
| `importance` | number | 重要度评分 (0-1) |
| `tags` | string[] | 标签数组 |
| `factType` | string | 事实类型 (fact/opinion) |
| `entityIds` | string[] | 关联实体ID |
| `createdAt` | number | 创建时间戳 |
| `updatedAt` | number | 更新时间戳 |
资料来源：[src/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/index.ts)
---
## 核心 API
### 记忆存储：remember()
`remember()` 方法用于存储新的记忆条目。
```typescript
const memory = await agent.remember({
content: "用户偏好深色主题",
tags: ["preference", "ui"],
importance: 0.8,
factType: "fact"
});
```
**参数说明：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `content` | string | 是 | - | 记忆内容 |
| `namespace` | string | 否 | "default" | 命名空间隔离 |
| `tags` | string[] | 否 | [] | 标签数组 |
| `importance` | number | 否 | 0.7 | 重要度 (0-1) |
| `factType` | string | 否 | "fact" | 事实类型 |
**副作用：**
- 自动触发观点强化（针对 `factType: "opinion"`）
- 触发关联实体的观察点再生
- 写入持久化存储
- 触发 `memory:stored` 事件
资料来源：[integrations/openclaw/SKILL.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/openclaw/SKILL.md)
### 记忆检索：recall()
`recall()` 方法支持语义检索和混合模式查询。
```typescript
const results = await agent.recall({
query: "用户的支付偏好",
namespace: "default",
limit: 8,
mode: "hybrid"
});
```
**检索模式：**
| 模式 | 说明 |
|------|------|
| `semantic` | 纯语义向量检索 |
| `keyword` | 关键词精确匹配 |
| `hybrid` | 语义+关键词混合检索 |
**参数说明：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `query` | string | 是 | - | 查询文本 |
| `namespace` | string | 否 | "default" | 命名空间 |
| `limit` | number | 否 | 8 | 返回结果数量 |
| `mode` | string | 否 | "hybrid" | 检索模式 |
资料来源：[integrations/python-hosted/README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/python-hosted/README.md)
### 记忆强化：reinforce()
增强记忆的重要度评分，用于正向反馈循环。
```typescript
await agent.reinforce(memoryId, {
boost: 0.1 // 增量范围: 0.01 - 0.5
});
```
**使用场景：**
- 记忆引导了成功的决策
- 用户确认了建议的价值
- 交互产生了正面结果
资料来源：[integrations/openclaw/SKILL.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/openclaw/SKILL.md)
### 记忆遗忘：forget()
永久删除指定记忆。
```typescript
await agent.forget(memoryId);
```
**使用场景：**
- 记忆内容已过期
- 用户请求删除隐私数据
- 记忆信息不再准确
### 记忆整合：consolidate()
清理低于衰减阈值的过期记忆，保持存储高效。
```typescript
await agent.consolidate({
decayThreshold: 0.2
});
```
---
## 检索引擎
### 混合检索策略
检索引擎采用多阶段检索流程：
```mermaid
graph TD
A[用户查询] --> B[查询预处理]
B --> C{检索模式}
C -->|semantic| D[向量相似度检索]
C -->|keyword| E[BM25排序]
C -->|hybrid| F[并行双路检索]
F --> G[倒数排名融合]
D --> G
E --> G
G --> H[结果重排序]
H --> I[Top-K 结果]
I --> J[相关性过滤]
J --> K[返回记忆列表]
```
### HyDE 生成增强
HyDE (Hypothetical Document Embeddings) 技术用于提升检索质量：
1. 使用语言模型生成假设性答案
2. 将假设性答案向量化
3. 使用假设向量检索相关记忆
4. 融合假设检索与直接检索结果
```typescript
// hyde.ts 核心逻辑
const hypotheticalDoc = await generateHypotheticalDoc(query);
const hypotheticalEmbedding = await embed(hypotheticalDoc);
const hydeResults = await vectorSearch(hypotheticalEmbedding);
```
### 查询扩展
引擎支持自动查询扩展，包括：
- 同义词替换
- 上下文窗口扩展
- 时间敏感查询优化
---
## 知识图谱
### 图结构
知识图谱由实体和边组成：
```mermaid
graph LR
A[实体: 用户] -->|关联| B[记忆: 偏好设置]
A -->|拥有| C[实体: 支付方式]
B -->|触发| D[记忆: 购买历史]
C -->|使用| E[记忆: 交易记录]
```
### 图操作 API
```typescript
// 获取命名空间的图结构
const graph = await agent.graph({
namespace: "default",
limit: 200
});
// 图统计信息
console.log(graph.stats);
// { entities: 42, edges: 128, memories: 256 }
```
### 实体管理
实体是知识图谱的节点，具有以下属性：
| 属性 | 说明 |
|------|------|
| `id` | 实体唯一标识 |
| `name` | 实体名称 |
| `type` | 实体类型 |
| `observations` | 观察点列表 |
| `memoryCount` | 关联记忆数 |
### 观察点系统
观察点是实体的语义摘要，自动从关联记忆中生成：
```typescript
interface Observation {
id: string;
entityId: string;
content: string; // 观察点摘要
sourceMemoryIds: string[];
confidence: number;
updatedAt: number;
}
```
**观察点再生流程：**
1. 新记忆存储时，识别关联实体
2. 异步触发观察点再生任务
3. 聚合实体相关记忆生成新摘要
4. 更新观察点内容
资料来源：[src/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/index.ts)
---
## 持久化层
### 存储适配器
系统支持多种存储后端：
| 适配器 | 适用场景 | 特点 |
|--------|----------|------|
| `memory.ts` | 开发/测试 | 内存存储，快速迭代 |
| `sqlite.ts` | 单机部署 | 本地持久化，轻量 |
| `neon.ts` | 生产环境 | Postgres Serverless，分布式 |
### 命名空间隔离
```typescript
// 切换命名空间
await agent.namespace("user-123");
// 导出命名空间数据
const export = await agent.export_namespace("user-123");
// 删除命名空间
await agent.delete_namespace("user-123");
```
### 数据持久化流程
```mermaid
graph TD
A[记忆写入请求] --> B{存储适配器}
B -->|开发模式| C[内存存储]
B -->|单机部署| D[SQLite 写入]
B -->|生产环境| E[Neon Postgres]
C --> F[Merkle 树更新]
D --> F
E --> F
F --> G[根哈希保存]
G --> H[完整性证明生成]
```
---
## 完整性校验
### Merkle 内存完整性
系统使用 Merkle 树结构确保记忆数据不可篡改：
```typescript
interface MerkleProof {
memoryId: string;
value: string;
path: string[]; // 兄弟节点哈希
position: 'left' | 'right';
rootHash: string;
}
```
### 审计事件
所有记忆操作都会记录审计日志：
```typescript
await agent.audit("memory:stored", {
id: mem.id,
tags: safeTags,
importance: mem.importance,
factType: mem.factType
});
```
**可审计事件类型：**
| 事件 | 说明 |
|------|------|
| `memory:stored` | 记忆存储 |
| `memory:retrieved` | 记忆检索 |
| `memory:updated` | 记忆更新 |
| `memory:deleted` | 记忆删除 |
| `memory:reinforced` | 记忆强化 |
资料来源：[src/integrity.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/integrity.ts)
---
## 行为经济学集成
### 观点强化机制
对于 `factType: "opinion"` 的记忆，系统应用行为经济学中的观点强化机制：
```typescript
import { applyOpinionReinforcement } from "./behavioral.js";
await applyOpinionReinforcement({
newMemory: mem,
memories: this.memories,
recallEngine: this.recallEngine
});
```
### 自适应学习
系统采用自适应学习策略：
1. **记忆衰减**：长时间未访问的记忆重要度逐渐降低
2. **访问频率加权**：频繁访问的记忆获得权重提升
3. **关联强度**：实体关联越多的记忆越难被遗忘
---
## 仪表盘可视化
MnemoPay 仪表盘提供记忆系统的可视化监控：
```mermaid
graph TD
A[仪表盘] --> B[记忆列表]
A --> C[推理追踪]
A --> D[知识图谱]
A --> E[交易历史]
B -->|显示| F[记忆ID]
B -->|显示| G[重要度分数]
B -->|显示| H[记忆内容]
C -->|显示| I[推理步骤]
C -->|显示| J[置信度]
C -->|显示| K[实体引用]
D -->|显示| L[实体节点]
D -->|显示| M[边关系]
```
### 记忆列表显示
```
┌─────────────────────────────────────────────────────┐
│ ID │ Score │ Memory Content │
├─────────────┼───────┼───────────────────────────────┤
│ a1b2c3d4... │ 0.85 │ 用户偏好深色主题 │
│ e5f6g7h8... │ 0.72 │ 经常在周末进行购物 │
│ i9j0k1l2... │ 0.65 │ 倾向于使用信用卡支付 │
└─────────────┴───────┴───────────────────────────────┘
```
资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)
---
## 使用示例
### Python Hosted SDK
```python
from mnemopay import Client
client = Client(api_key="your-api-key")
# 存储记忆
client.remember(
content="用户喜欢在周五晚上购物",
namespace="default",
tags=["preference", "shopping"],
importance=0.8
)
# 检索记忆
results = client.recall(
query="购物偏好",
namespace="default",
limit=8,
mode="hybrid"
)
# 获取知识图谱
graph = client.graph(namespace="default", limit=200)
print(f"实体数: {graph.stats['entities']}")
```
### JavaScript SDK
```typescript
import MnemoPay from "@mnemopay/sdk";
const agent = await MnemoPay.quick("agent-001");
// 存储记忆
await agent.remember({
content: "用户偏好深色主题",
tags: ["preference", "ui"],
importance: 0.8
});
// 检索记忆
const memories = await agent.recall({
query: "用户界面偏好",
limit: 8
});
// 获取图谱
const graph = await agent.graph();
```
---
## 配置选项
| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `maxMemories` | number | 10000 | 最大记忆存储量 |
| `decayRate` | number | 0.01 | 记忆衰减率 |
| `consolidationThreshold` | number | 0.1 | 整合阈值 |
| `storageBackend` | string | "memory" | 存储后端 |
| `embeddingModel` | string | "default" | 向量模型 |
| `maxRecallResults` | number | 8 | 最大检索结果 |
---
## 性能指标
### LongMemEval 基准
MnemoPay 在 LongMemEval 基准测试中达到：
| 版本 | 分数 | 说明 |
|------|------|------|
| v1.3.0 | 66.9% | 多会话检索基线 |
| v1.4.0 | 77.2% | 优化后的检索引擎 |
资料来源：[site/journal/v1-4-0-longmemeval-77-2.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/journal/v1-4-0-longmemeval-77-2.html)
### 压力测试
系统已通过 100 万次操作的连续压力测试，验证了内存管理的稳定性和数据完整性。
---
## 最佳实践
1. **合理设置重要度**：根据记忆的实际价值设置 0-1 之间的评分
2. **使用标签系统**：通过标签组织记忆，便于后续检索
3. **定期整合**：使用 `consolidate()` 清理过期记忆
4. **命名空间隔离**：为不同用户或场景使用独立命名空间
5. **监控使用量**：通过 `usage_report()` 监控记忆存储和 API 调用
6. **启用完整性校验**：生产环境务必启用 Merkle 完整性验证
---
## 账本与支付系统
### 相关页面
相关主题：[快速开始](#quick-start), [支付轨道](#payment-rails), [身份与认证系统](#identity-auth)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mcp/server.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/mcp/server.ts)
- [README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
- [dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)
- [site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)
- [site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)
# 账本与支付系统
## 概述
MnemoPay 的账本与支付系统是专为 AI Agent 设计的金融基础设施层，提供从充值、托管到结算、退款的全链路资金管理能力。该系统并非简单的支付网关封装，而是一套完整的双账本（Double-Entry Ledger）机制，确保每一笔资金流向都有精确的借方和贷方记录。
核心价值主张：
- 支持 Stripe（全球）、Paystack（非洲）、Lightning（BTC 微支付）三条真实支付通道
- 统一的 API 接口，屏蔽底层通道差异
- 内置交易托管（Escrow）机制，人类审批后才释放资金
- 交易事件 Webhook 推送，支持 HMAC-SHA256 签名验签
资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
---
## 架构设计
### 支付系统分层
```
┌─────────────────────────────────────────────────────────┐
│ 业务接口层 │
│ charge() / settle() / refund() / transfer() │
├─────────────────────────────────────────────────────────┤
│ 支付通道层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Stripe │ │ Paystack │ │ Lightning│ │
│ └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────────────────┤
│ 账本核心层 │
│ Double-Entry Ledger │
├─────────────────────────────────────────────────────────┤
│ 存储层 │
│ SQLite / Webhook Events │
└─────────────────────────────────────────────────────────┘
```
资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)
### 托管与结算流程
```
graph TD
A[Agent 调用 charge()] --> B[资金进入 Escrow 托管]
B --> C{人工审批}
C -->|批准| D[调用 settle() 释放资金]
C -->|拒绝| E[调用 refund() 原路退回]
D --> F[商户收到结算款项]
E --> G[资金退回买家]
```
资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)
---
## 支付通道
### 通道对比
| 通道 | 覆盖地区 | 支持货币 | 特色功能 |
|------|----------|----------|----------|
| **Stripe** | 全球 | USD, EUR, GBP 等 135+ 货币 | 手动捕获（Manual Capture）实现真正的 Escrow |
| **Paystack** | 非洲 | NGN, GHS, ZAR, KES | 23 家尼日利亚银行预映射，HMAC-SHA512 安全验证 |
| **Lightning** | 全球 | BTC | 微支付场景，实时到账 |
资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)
### Stripe 集成
Stripe 提供全球覆盖的信用卡支付能力。MnemoPay 使用 PaymentIntents API 实现手动捕获模式，确保资金在托管状态下等待授权：
```typescript
// 核心支付操作
charge() // 收款并进入托管
settle() // 释放托管资金
refund() // 退款回原支付渠道
```
资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)
### Paystack 集成
针对非洲市场优化，支持多种本地支付方式：
- Checkout（网页结账）
- 保存的卡片（Saved Cards）
- 银行转账（Bank Transfer）
- Webhook 验证（HMAC-SHA512）
```typescript
// Paystack 转账事件
transfer.success // 转账完成
transfer.failed // 转账失败
```
资料来源：[src/mcp/server.ts:1-50](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/mcp/server.ts)
---
## Webhook 事件系统
### 事件类型
| 事件名称 | 触发时机 | 描述 |
|----------|----------|------|
| `charge.success` | 扣款成功进入托管 | 交易已被接受并锁定在 Escrow |
| `charge.failed` | 扣款失败 | 因名誉分上限、欺诈检测、授权违规等原因被拒绝 |
| `settle` | 释放托管资金 | Escrow 已释放，资金已划转 |
| `refund` | 交易回滚 | 资金已原路退回 |
| `transfer.success` | Paystack 提现完成 | 资金已到达目标账户 |
| `transfer.failed` | Paystack 提现失败 | 提现操作异常 |
| `*` | 通配符订阅 | 订阅所有事件类型 |
资料来源：[src/mcp/server.ts:1-50](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/mcp/server.ts)
### 签名验证机制
每条 Webhook POST 请求都携带 `X-MnemoPay-Signature` 头，格式为：
```
X-MnemoPay-Signature: t=,v1=
```
其中 `v1` 的计算方式：
```
v1 = HMAC-SHA256(secret, timestamp + '.' + request_body)
```
**安全建议**：验证 `now - t < 300秒`，防止重放攻击。签名密钥在调用 `webhook_register` 时返回一次，务必在调用返回前持久化存储。
```typescript
// Webhook 验证伪代码
const isValid = hmacSha256(secret, `${timestamp}.${body}`) === signature;
const isRecent = Date.now() - timestamp < 300000; // 5分钟内
if (!isValid || !isRecent) reject();
```
资料来源：[src/mcp/server.ts:1-50](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/mcp/server.ts)
---
## 双账本机制
### 核心概念
MnemoPay 采用双记账（Double-Entry）原则，每笔交易都产生两条对应的账目记录：
- **借方条目（Debit）**：资金流出账户
- **贷方条目（Credit）**：资金流入账户
这确保了账目平衡，任何时刻资产总计等于负债总计。
### 交易状态流转
```
graph LR
A[Created] --> B[Held - Escrow中]
B -->|Approve| C[Settled - 已结算]
B -->|Reject| D[Refunded - 已退款]
C --> E[Completed]
D --> E
```
资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)
---
## 自助购物与结账执行
### 购物流程
MnemoPay 支持 AI Agent 自动执行购物操作，所有购买都必须经过 Escrow 托管：
1. Agent 搜索商品、比较价格
2. 选择最优方案，发起购买请求
3. 资金进入托管状态
4. **人类审批**后才真正扣款
5. 禁止 Agent 未经授权自行消费
```typescript
// 购物相关 API
shop_checkout // 浏览器自动化结账
```
资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)
### 结账策略
| 策略 | 适用平台 | 说明 |
|------|----------|------|
| Shopify 策略 | Shopify 店铺 | 原生检测，优化选择器 |
| 通用策略 | 其他平台 | 回退到通用结账启发式算法 |
资料来源：[src/mcp/server.ts:1-50](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/mcp/server.ts)
---
## 仪表盘监控
### 交易概览
MnemoPay Dashboard 提供实时交易监控能力：
| 监控指标 | 说明 |
|----------|------|
| Wallet 余额 | 当前可用余额 |
| Reputation 信誉分 | Agent 信用评分（0-1） |
| Memories Count | 记忆条目数 |
| Transactions Count | 累计交易数 |
资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)
### 任务与进度追踪
每个支付任务都包含状态标记：
```typescript
{
id: string,
done: boolean, // true = Complete, false = In Progress
// ...
}
```
资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)
---
## SDK 快速开始
### 安装
```bash
npm install @mnemopay/sdk
```
### 初始化
```typescript
import { MnemoPay } from "@mnemopay/sdk";
const mnemo = MnemoPay.quick("agent-id");
// 自动分配：记忆存储 + 钱包 + 身份
```
### 基础支付操作
```typescript
// 收款（进入托管）
await mnemo.charge({ amount: 1000, currency: "USD" });
// 释放托管（需人工授权）
await mnemo.settle({ transactionId: "tx_xxx" });
// 退款
await mnemo.refund({ transactionId: "tx_xxx" });
```
资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)
---
## 与传统支付方案对比
| 特性 | MnemoPay | 传统 Stripe 封装 | Payman |
|------|----------|------------------|--------|
| 支付通道 | 多通道统一 API | 单通道 | 单一 |
| Escrow 托管 | 原生支持 | 需手动实现 | 不支持 |
| 双账本 | 内置 | 需额外开发 | 不支持 |
| AI Agent 身份 | Ed25519 | 无 | 无 |
| Agent 信用评分 | 300-850 分 | 无 | 无 |
| 行为异常检测 | EWMA + 指纹 | 无 | 无 |
资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)
---
## 总结
MnemoPay 的账本与支付系统为 AI Agent 提供了一套完整、合规、可审计的金融操作基础设施：
- **真实性**：接入 Stripe、Paystack、Lightning 三大真实支付通道
- **安全性**：HMAC-SHA256 签名验签、300秒重放保护、名誉分风控
- **合规性**：双账本确保每笔资金有据可查，Escrow 托管保障资金安全
- **可观测性**：完整的事件 Webhook + Dashboard 实时监控
通过这套系统，AI Agent 可以在受控环境下安全地处理货币事务，同时保留人类最终决策权。
---
## 身份与认证系统
### 相关页面
相关主题：[账本与支付系统](#ledger-payments), [治理与合规框架](#governance)
相关源码文件
以下源码文件用于生成本页说明：
- [src/identity.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity.ts)
- [src/identity/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity/index.ts)
- [src/identity/did.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity/did.ts)
- [src/identity/wallet.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity/wallet.ts)
- [src/identity/bundle.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity/bundle.ts)
- [src/network.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/network.ts)
# 身份与认证系统
MnemoPay SDK 的身份与认证系统是整个平台的核心基础设施，为 AI Agent 提供完整的身份标识、钱包管理、权限控制和安全验证机制。该系统基于去中心化身份（DID）理念构建，同时集成了传统的 KYC/KYB 流程以满足监管合规要求。
## 系统架构概览
身份与认证系统采用分层架构设计，各层之间职责明确、解耦清晰。
```mermaid
graph TD
subgraph 身份层
DID[DID 标识符]
BUNDLE[身份凭证包]
KYA[Know Your Agent]
end
subgraph 钱包层
WALLET[钱包余额]
TOKEN[Token 管理]
REPUTATION[信誉评分]
end
subgraph 权限层
PERMS[权限控制]
KILLSWITCH[熔断机制]
end
subgraph 网络层
NETWORK[网络通信]
VERIFY[身份验证]
end
DID --> BUNDLE
BUNDLE --> WALLET
BUNDLE --> TOKEN
WALLET --> REPUTATION
BUNDLE --> PERMS
PERMS --> KILLSWITCH
NETWORK --> VERIFY
VERIFY --> DID
```
根据架构文档，MnemoPay SDK 的身份系统包含以下核心组件：
| 组件 | 功能描述 | 层级归属 |
|------|---------|----------|
| DID | 去中心化身份标识符 | 身份层 |
| KYA | Know Your Agent 身份核验 | 身份层 |
| Bundle | 身份凭证包管理 | 身份层 |
| Wallet | 钱包余额与交易 | 钱包层 |
| Token | 代币化管理 | 钱包层 |
| Permissions | 权限访问控制 | 权限层 |
| KillSwitch | 熔断/紧急停止 | 权限层 |
| Reputation | 信誉评分系统 | 钱包层 |
资料来源：[README.md:30-50]()
## 核心模块详解
### 身份标识模块（Identity）
身份标识模块是整个认证系统的根基，为每个 Agent 生成唯一的去中心化身份。
#### DID 去中心化标识符
DID（Decentralized Identifier）是 MnemoPay 系统中 Agent 的唯一身份标识。DID 标识符遵循 W3C DID Core 规范，支持自主管理、跨平台互操作。
根据架构设计，DID 模块负责：
- 生成符合规范的 DID 标识符
- 管理 DID 文档（DID Document）
- 支持 DID 解析与验证
资料来源：[src/identity/did.ts]()
#### Bundle 身份凭证包
Bundle 是身份凭证的聚合容器，包含 Agent 的身份证明、资质文件、权限声明等信息。
```mermaid
graph LR
B[Bundle] --> K[KYA 凭证]
B --> P[Permissions 权限]
B --> T[Tokens 代币]
B --> R[Reputation 信誉]
```
Bundle 的设计使得身份信息可以作为一个整体进行传输和验证，同时支持选择性披露。
资料来源：[src/identity/bundle.ts]()
### 钱包模块（Wallet）
钱包模块管理 Agent 的资金、信誉评分和交易历史。
#### 账户状态管理
Dashboard 中的账户状态管理展示了钱包与身份系统的集成方式：
```typescript
const [profile, setProfile] = useState({
wallet: 0,
reputation: 0.5,
memoriesCount: 0,
transactionsCount: 0
});
```
账户状态包含：
- `wallet`: 钱包余额
- `reputation`: 信誉评分（初始值 0.5）
- `memoriesCount`: 记忆数量
- `transactionsCount`: 交易次数
资料来源：[dashboard/index.html:175-181]()
#### 信誉评分系统
信誉评分采用 300-850 分制，与 FICO 信用评分类似。评分由五个组成部分构成：
| 评分维度 | 说明 |
|---------|------|
| 支付历史 | 按时支付的比例 |
| 使用时长 | 账户存在时间 |
| 信用类型 | 使用的产品多样性 |
| 新信用 | 最近的开户行为 |
| 余额利用率 | 信用使用率 |
信誉评分直接影响：
- 单次交易额度上限
- 费率折扣
- 访问高级功能权限
资料来源：[README.md:42-50]()
### 会话管理模块
会话模块处理 Agent 的登录、登出和会话状态维护。
#### 登录流程
```mermaid
sequenceDiagram
participant Agent
participant SessionPanel
participant Network
participant Identity
Agent->>SessionPanel: 请求登录
SessionPanel->>Network: 验证凭证
Network->>Identity: 验证身份
Identity-->>Network: 验证结果
Network-->>SessionPanel: 会话令牌
SessionPanel-->>Agent: 登录成功
```
#### 会话状态管理
Dashboard 组件中实现了完整的会话状态管理：
```typescript
const [session, setSession] = useState(null);
const [accountId, setAccountIdState] = useState(getAccountId());
const [connected, setConnected] = useState(false);
```
关键状态变量：
| 变量 | 类型 | 说明 |
|------|------|------|
| `session` | object | 当前会话对象 |
| `accountId` | string | 账户唯一标识符 |
| `connected` | boolean | 连接状态 |
资料来源：[dashboard/index.html:167-172]()
### 权限控制模块
权限模块实现细粒度的访问控制和安全策略。
#### Permissions 权限矩阵
MnemoPay 采用基于角色的访问控制（RBAC）与属性基访问控制（ABAC）混合模型：
```mermaid
graph TD
R[Request] --> P{Permissions Check}
P -->|有权限| A[Allow]
P -->|无权限| K{KillSwitch}
K -->|触发熔断| B[Block]
K -->|未触发| D[Deny]
```
#### KillSwitch 熔断机制
KillSwitch 是安全防护的最后一道防线，在检测到异常行为时自动触发：
| 触发条件 | 动作 |
|---------|------|
| 异常交易模式 | 暂停交易 |
| 信誉分骤降 | 锁定账户 |
| 可疑 IP | 二次验证 |
| API 限流 | 服务降级 |
资料来源：[README.md:46-48]()
## 网络通信与验证
### 网络层架构
网络层负责所有身份相关的通信请求，包括验证、签发、更新等操作。
```mermaid
graph TD
subgraph 客户端
SDK[SDK 客户端]
ID[身份模块]
end
subgraph 服务端
API[API 网关]
AUTH[认证服务]
IDV[身份服务]
end
SDK --> API
ID --> NETWORK[网络模块]
NETWORK --> API
API --> AUTH
AUTH --> IDV
IDV --> DATABASE[(数据库)]
```
资料来源：[src/network.ts]()
### 身份验证流程
身份验证采用多层验证机制：
1. **令牌验证**：检查 JWT 令牌的合法性
2. **签名验证**：验证消息签名的正确性
3. **状态检查**：验证账户未被锁定或禁用
4. **权限检查**：确认操作在授权范围内
## KYA（Know Your Agent）体系
KYA 是 MnemoPay 的身份核验框架，类似于传统金融的 KYC（Know Your Customer）流程。
### KYA 核验级别
| 级别 | 核验内容 | 限额 | 适用场景 |
|------|---------|------|---------|
| L1 | 邮箱验证 | $100/日 | 开发测试 |
| L2 | 手机验证 | $1,000/日 | 小规模部署 |
| L3 | 身份证明 | $10,000/日 | 生产环境 |
| L4 | 企业认证 | 无限制 | 企业客户 |
### 身份凭证要求
L3 及以上级别需要提供：
- 法定身份证明（身份证、护照）
- 地址证明（水电费账单）
- 企业注册文件（适用于 L4）
资料来源：[README.md:41-44]()
## Agent 信用评分
Agent 信用评分是 MnemoPay 的核心创新之一，为 AI Agent 提供可量化的信用指标。
### 评分计算模型
```mermaid
graph LR
A[行为数据] --> B[实时监控]
B --> C[EWMA 统计]
C --> D[异常检测]
D --> E[评分更新]
E --> F[信用报告]
```
### 评分维度
| 维度 | 权重 | 影响因素 |
|------|------|---------|
| 支付可靠性 | 35% | 按时支付比例 |
| 交易历史 | 25% | 交易数量与频率 |
| 账户稳定性 | 20% | 账户存续时间 |
| 风险行为 | 15% | 异常交易检测 |
| 信用多样性 | 5% | 产品使用广度 |
### 异常检测机制
系统采用 EWMA（指数加权移动平均）+ 指纹识别双重机制进行异常检测：
- **EWMA**：检测交易金额、频率的统计异常
- **指纹识别**：识别设备、IP、行为模式的异常
资料来源：[README.md:51-54]()
## 安全性设计
### 安全层级
```mermaid
graph TD
subgraph 安全防护
S1[身份标识]
S2[通信加密]
S3[权限验证]
S4[行为监控]
S5[熔断保护]
end
S1 --> S2
S2 --> S3
S3 --> S4
S4 --> S5
```
### 威胁防护措施
| 威胁类型 | 防护机制 |
|---------|---------|
| 重放攻击 | 时间戳 + 随机数 |
| 中间人攻击 | TLS 1.3 + 证书固定 |
| 权限提升 | 最小权限原则 |
| 账户盗用 | 多因素认证 |
| 交易欺诈 | 实时风险评估 |
## 快速开始
### 初始化身份
```typescript
import { MnemoPay } from '@mnemopay/sdk';
const mnemo = MnemoPay.quick('agent-id');
// 获取身份信息
const identity = await mnemo.identity.get();
console.log(identity.did); // DID 标识符
console.log(identity.wallet); // 钱包余额
console.log(identity.reputation); // 信誉评分
```
### 管理会话
```typescript
// 登录
await mnemo.session.login({
accountId: 'your-account-id'
});
// 获取当前会话
const session = await mnemo.session.current();
console.log(session.token); // 会话令牌
console.log(session.expiresAt); // 过期时间
// 登出
await mnemo.session.logout();
```
### 权限检查
```typescript
// 检查权限
const hasPermission = await mnemo.identity.checkPermission({
action: 'charge',
resource: 'wallet'
});
if (hasPermission) {
// 执行操作
} else {
// 触发 KillSwitch 或提示权限不足
}
```
## 总结
MnemoPay 的身份与认证系统为 AI Agent 提供了企业级的身份管理能力：
- **去中心化身份**：基于 DID 的自主身份标识
- **完整的钱包系统**：资金、信誉、交易一体化管理
- **细粒度权限控制**：RBAC + ABAC 混合模型
- **多层安全防护**：从身份验证到行为监控的全链路保护
- **信用评分体系**：300-850 分制的 Agent 信用评分
- **KYA 合规框架**：满足监管要求的身份核验流程
这套系统使 AI Agent 能够像企业一样拥有身份、管理资金、建立信誉，为自主经济奠定基础。
---
## 代理信用评分系统
### 相关页面
相关主题：[异常检测系统](#anomaly-detection), [治理与合规框架](#governance)
相关源码文件
以下源码文件用于生成本页说明：
- [src/fico.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/fico.ts)
- [src/behavioral.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/behavioral.ts)
- [src/subagent-cost.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/subagent-cost.ts)
- [dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)
- [README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
# 代理信用评分系统
## 概述
代理信用评分系统（Agent Credit Scoring System）是 MnemoPay SDK 的核心组件之一，为 AI 代理提供类似人类信用评分的信任评估机制。该系统采用 300-850 的评分范围，模拟传统 FICO 信用评分模型，针对 AI 代理的交易行为、支付历史和可靠性进行多维度评估。
代理信用评分直接影响交易手续费率、交易限额以及系统对异常行为的容忍度。评分越高的代理可享受更低的手续费（Enterprise 级别最低至 1.0%）和更高的交易限额，而评分较低的代理将面临更严格的监控甚至自动封禁。
资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
## 系统架构
代理信用评分系统由多个协同工作的模块组成，采用五组件评分架构，结合行为金融学和异常检测技术。
```mermaid
graph TD
A[代理身份创建] --> B[评分系统初始化]
B --> C{评分组件}
C --> D[FICO基础评分]
C --> E[行为金融分析]
C --> F[异常检测]
C --> G[支付历史]
C --> H[可靠性评估]
D --> I[综合评分 300-850]
E --> I
F --> I
G --> I
H --> I
I --> J[手续费计算]
I --> K[交易限额]
I --> L[风险控制]
```
## 核心组件
### FICO 基础评分模块
FICO 模块是评分系统的基础实现，负责计算代理的基础信用分值。该模块采用双余额记账系统追踪代理的财务状况，通过分析交易历史计算综合评分。
评分计算考虑以下因素：
| 因素 | 权重范围 | 说明 |
|------|----------|------|
| 支付历史 | 35% | 按时支付的比例和频率 |
| 信用利用率 | 30% | 当前信用额度使用情况 |
| 账户时长 | 15% | 账户活跃时间 |
| 信用类型 | 10% | 使用的支付渠道多样性 |
| 新信用查询 | 10% | 短期内新增信用申请 |
资料来源：[src/fico.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/fico.ts)
### 行为金融分析模块
行为金融分析模块运用前景理论（Prospect Theory）和 nudge 机制，对代理的决策模式进行深度分析。该模块通过观察代理在相似场景下的历史决策，识别风险偏好和交易行为模式。
```mermaid
graph LR
A[交易行为数据] --> B[行为模式识别]
B --> C{前景理论分析}
C --> D[损失厌恶系数]
C --> E[风险偏好曲线]
C --> F[决策偏差检测]
D --> G[行为评分调整]
E --> G
F --> G
G --> H[最终行为分数]
```
该模块的核心功能包括：
- **损失厌恶评估**：测量代理对损失的敏感程度，量化代理在面临潜在损失时的决策倾向
- **风险偏好曲线**：基于前景理论建模代理的风险承担意愿，高风险偏好代理在市场波动时可能做出更激进的决策
- **决策偏差检测**：识别代理行为中的系统性偏差，如锚定效应、可得性启发等认知偏差
- **Nudge 机制**：根据代理的行为模式自动施加微小的决策引导，优化交易结果
资料来源：[src/behavioral.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/behavioral.ts)
### 子代理成本追踪模块
子代理成本追踪模块专门针对多代理系统设计，记录和归因子代理的资源消耗。该模块维护每个子代理的成本中心，支持成本分配和内部结算。
```mermaid
graph TD
A[父代理] --> B[子代理成本记录]
B --> C[资源消耗追踪]
C --> D[成本归因分析]
D --> E[内部结算]
E --> F[成本效率评分]
F --> G[父代理信用影响]
```
关键功能：
- **资源消耗追踪**：记录 CPU、内存、API 调用等资源使用情况
- **成本归因**：将子代理产生的成本准确归属到对应的父代理
- **效率评分**：基于成本消耗与交易价值的比率计算效率分数
资料来源：[src/subagent-cost.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/subagent-cost.ts)
### 异常检测模块
异常检测模块采用指数加权移动平均（EWMA）和指纹识别技术，实时监控代理行为，识别潜在的欺诈或异常活动。
```mermaid
graph TD
A[交易数据流] --> B[EWMA统计监控]
A --> C[行为指纹生成]
B --> D{异常判定}
C --> D
D -->|正常| E[更新基准线]
D -->|异常| F[触发警报]
D -->|严重| G[自动封禁]
F --> H[人工审核队列]
```
检测机制：
| 检测类型 | 技术方案 | 响应级别 |
|----------|----------|----------|
| 交易频率异常 | EWMA 动态阈值 | 警报 |
| 金额异常 | 统计分布偏离检测 | 警报 |
| 行为指纹异常 | 多维特征匹配 | 人工审核 |
| 串通检测 | 图关系分析 | 自动封禁 |
资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
## 评分计算流程
### 初始化阶段
代理首次初始化时，系统基于 Ed25519 加密身份创建唯一标识符，并分配初始信用评分。
```typescript
// 初始化代理并获取信用评分
const agent = MnemoPay.quick("billing-agent", {
stripe: { secretKey: process.env.STRIPE_SECRET_KEY }
});
// 信用评分将在首次交易后计算
console.log(agent.id); // Ed25519 派生身份
```
### 动态评分更新
评分系统采用流式计算模式，每次交易完成后自动更新评分。
```mermaid
sequenceDiagram
participant A as 代理
participant B as 评分系统
participant C as 支付引擎
participant D as 异常检测
A->>C: charge() 请求
C->>D: 提交交易
D->>D: 异常检测
D-->>C: 检测结果
C->>B: 交易完成事件
B->>B: 计算评分增量
B->>B: 更新综合评分
B-->>A: 新评分生效
```
## 评分应用场景
### 手续费等级
信用评分直接决定代理的交易手续费率：
| 评分范围 | 等级 | 手续费率 | 适用计划 |
|----------|------|----------|----------|
| 750-850 | Excellent | 1.0% | Enterprise |
| 650-749 | Good | 1.5% | Pro |
| 550-649 | Fair | 2.0% | Starter |
| 300-549 | Poor | 冻结交易 | 审核中 |
资料来源：[site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)
### 交易限额
评分决定代理的即时交易限额和日累计限额：
- **高评分代理（750+）**：无单笔限额，日限额根据账户历史自动调整
- **中等评分代理（550-749）**：单笔限额 $10,000，日限额 $100,000
- **低评分代理（300-549）**：单笔限额 $1,000，日限额 $5,000，需要人工审批
### 自动风控
评分系统与风控引擎深度集成：
```mermaid
graph TD
A[交易请求] --> B{信用评分检查}
B -->|≥750| C[直接放行]
B -->|650-749| D[简化验证]
B -->|550-649| E[标准验证]
B -->|300-549| F[拒绝交易]
D --> G{EWMA异常检测}
E --> G
G -->|正常| H[人工确认]
G -->|异常| F
C --> I[执行交易]
H --> I
```
## 仪表盘集成
代理信用评分通过 MnemoPay 仪表盘实时展示，便于开发者监控代理健康状况。
资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)
```typescript
// 仪表盘显示的代理信息结构
interface AgentProfile {
wallet: number; // 钱包余额
reputation: number; // 信誉分数 (0-1)
memoriesCount: number; // 记忆条目数
transactionsCount: number;// 交易总数
}
```
## API 参考
### 获取代理评分
```typescript
const score = await agent.getCreditScore();
// 返回: { score: number, factors: CreditFactor[] }
```
### 更新行为数据
```typescript
await agent.updateBehavioralData({
transactionPattern: 'conservative',
riskTolerance: 0.3,
lossAversion: 2.5
});
```
### 查询子代理成本
```typescript
const costReport = await agent.getSubagentCosts({
period: '30d',
groupBy: 'subagent'
});
```
## 总结
代理信用评分系统是 MnemoPay SDK 的核心信任基础设施，通过五组件评分架构、行为金融分析和实时异常检测，为 AI 代理提供可量化的信任评估。评分系统与支付引擎深度集成，直接影响手续费率、交易限额和风控策略，确保只有可靠的代理能够参与金融交易。
---
## 行为金融引擎
### 相关页面
相关主题：[代理信用评分系统](#credit-score), [异常检测系统](#anomaly-detection)
相关源码文件
以下源码文件用于生成本页说明：
- [src/behavioral.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/behavioral.ts)
- [src/reasoning/post-processor.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/reasoning/post-processor.ts)
# 行为金融引擎
## 概述
行为金融引擎是 MnemoPay SDK v1.4.0+ 中的核心模块之一，专注于将行为经济学原理（特别是前景理论/Prospect Theory）与 AI Agent 的支付决策系统相结合。该引擎通过实时干预和引导机制，优化 Agent 的金融行为，降低系统性风险，并提升整体支付生态的健康度。
资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
## 核心定位
MnemoPay SDK 的整体架构将行为金融引擎置于**Agent Credit Score（代理信用评分）**与**支付系统**之间的关键位置：
```
┌──────────────────────────────────────────────────────────────────┐
│ GOVERNANCE Charter · FiscalGate · Article 12 · MerkleAudit │
├──────────┬──────────┬───────────┬─────────────────────────────────┤
│ Memory │ Payments │ Identity │ Agent Credit Score (300-850) │
│ │ │ │ 5-component scoring │
├──────────┴──────────┴───────────┼─────────────────────────────────┤
│ │ Behavioral Finance │
│ │ prospect theory, nudges │
├────────────────────────────────┴─────────────────────────────────┤
│ │ Anomaly Detection │
│ │ EWMA + fingerprinting │
└─────────────────────────────────────────────────────────────────┘
```
资料来源：[README.md:Architecture](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
## 工作原理
### 前景理论集成
行为金融引擎基于 Kahneman 和 Tversky 的前景理论（Prospect Theory）设计。该理论的核心洞察是：**人类（及 AI Agent）在面对收益和损失时表现出非对称的风险偏好**：
- **确定效应**：倾向于选择确定的收益而非概率收益
- **反射效应**：在损失面前表现为风险寻求
- **损失厌恶**：对损失的敏感度高于等量收益（约 2.25 倍）
- **参考点依赖**：决策结果取决于相对于参考点的变化
资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
### 决策干预流程
```
graph TD
A[交易请求 charge/settle] --> B{行为金融引擎评估}
B --> C[计算即时效用]
C --> D{参考点比较}
D -->|收益框架| E[应用确定效应权重]
D -->|损失框架| F[应用损失厌恶权重]
E --> G[决策调整]
F --> G
G --> H{风险阈值检查}
H -->|通过| I[执行交易]
H -->|警告| J[发送Nudge提示]
H -->|拒绝| K[阻止交易]
```
## Nudge 机制
### 行为助推设计
引擎内置多种 Nudge（行为助推）策略，用于温和引导 Agent 行为：
| Nudge 类型 | 触发场景 | 响应方式 |
|-----------|---------|---------|
| 延迟确认 | 大额交易 | 建议冷却期 |
| 风险提示 | 异常模式 | 警告信息 |
| 历史参照 | 新交易对手 | 展示信用历史 |
| 阈值预警 | 接近限额 | 提前通知 |
### Nudge 实现模式
```typescript
// 典型 Nudge 触发场景
if (transaction.amount > threshold * reputationScore) {
applyNudge({
type: 'DELAY_CONFIRMATION',
message: '建议在执行前等待确认',
cooldown: 30000 // 30秒冷却
});
}
```
资料来源：[src/behavioral.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/behavioral.ts)
## 与异常检测的协同
行为金融引擎与 EWMA（指数加权移动平均）异常检测系统紧密协作：
```
graph LR
A[行为数据流] --> B[EWMA 异常检测]
B --> C{异常判断}
C -->|正常| D[行为金融引擎正常决策]
C -->|轻度异常| E[应用风险权重]
C -->|重度异常| F[触发 Killswitch]
E --> G[更新参考点]
F --> H[阻止交易 + 记录审计]
```
### 双重验证机制
1. **EWMA 层**：基于统计的时间序列异常检测，识别交易速度和频率异常
2. **行为金融层**：基于决策心理学的规范性分析，识别不理性交易行为
两层结合确保：
- 统计异常 → 实时拦截
- 行为异常 → Nudge 引导 + 长期跟踪
资料来源：[README.md - Anomaly Detection](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
## 与 Agent Credit Score 的交互
行为金融引擎的输出直接影响 **Agent Credit Score（300-850 分）**：
```mermaid
graph TD
A[交易完成] --> B[行为评估]
B --> C{决策质量评分}
C -->|理性决策| D[+信用分]
C -->|异常交易| E[-信用分]
C -->|高风险拦截| F[大幅扣分 + 标记]
D --> G[更新5维评分模型]
E --> G
F --> G
```
### 评分反馈闭环
引擎在每次交易结算（settle）时触发信用反馈循环：
```typescript
// 行为反馈机制
onSettle(transaction) {
const behaviorScore = evaluateDecisionQuality(transaction);
const creditImpact = behaviorScore * FEEDBACK_LOOP_WEIGHT; // 0.05
updateCreditScore(creditImpact);
}
```
资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html) - 信用评分衰减注释
## 配置参数
| 参数 | 默认值 | 说明 |
|------|-------|------|
| `lossAversion` | 2.25 | 损失厌恶系数 |
| `referencePointDecay` | 0.05 | 参考点衰减率（半衰期约14小时）|
| `nudgeThreshold` | 动态 | Nudge 触发阈值 |
| `prospectWeighting` | 0.61 | 概率加权函数参数 |
### 实时参数调整
引擎支持基于市场条件的动态参数调整：
```typescript
interface BehavioralConfig {
lossAversion: number; // 范围: 1.5-3.0
decay: number; // 范围: 0.01-0.1
feedbackLoopWeight: number; // 范围: 0.01-0.1
ceilingMultiplier: number; // 信用分上限系数
}
```
资料来源：[src/behavioral.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/behavioral.ts)
## 应用场景
### 场景一：代理购物（Autonomous Shopping）
当 Agent 代表用户执行购买决策时：
1. **交易前**：评估用户历史偏好和风险承受能力
2. **交易中**：应用前景理论框架调整购买确认流程
3. **交易后**：基于结算结果更新 Agent 信用评分
```typescript
// 自动购物中的行为金融干预
const shoppingAgent = MnemoPay.quick("shopping-agent");
const purchase = await shoppingAgent.charge(299.00, "Enterprise plan");
// 引擎自动评估：
// - 金额是否超出代理信用上限
// - 交易频率是否异常
// - 交易对手风险评分
```
### 场景二：多代理商业（Multi-Agent Commerce）
在多 Agent 协作场景中，行为金融引擎提供：
- **信任传递**：基于信用评分的行为担保
- **争议预防**：Nudge 机制减少事后纠纷
- **清算优化**：前景理论驱动的最优结算时机选择
资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html) - 规模扩展场景
## 监控与仪表板
行为金融引擎的各项指标可在 MnemoPay Dashboard 中实时监控：
```typescript
// Dashboard 展示的关键指标
interface BehavioralMetrics {
reputation: number; // 当前声誉值 (0-1)
ceiling: number; // 当前计费上限 ($)
decay: number; // 衰减率
feedbackLoop: string; // 反馈循环状态
overLimit: boolean; // 是否超限
}
```
Dashboard 面板通过以下组件展示引擎状态：
| 面板区域 | 显示内容 | 数据来源 |
|---------|---------|---------|
| Reputation | 实时声誉分数 | `profile.reputation` |
| Credit Ceiling | 动态计算上限 | `500 * reputation` |
| Plan Gate | 限额状态指示 | `missions.overLimit` |
| Active Sessions | 行为异常会话 | `session` 数据 |
资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html) - 计费面板代码
## 技术特性
### 无侵入集成
行为金融引擎作为 SDK 中间件层实现，对业务逻辑无侵入：
```typescript
// 中间件注册方式
import { mnemoPayMiddleware } from "@mnemopay/sdk/middleware/openai";
// 或
import { mnemoPayMiddleware } from "@mnemopay/sdk/middleware/anthropic";
```
### 跨平台支持
引擎通过标准化接口支持多种 AI 框架：
| 框架 | 集成方式 |
|-----|---------|
| OpenAI | `mnemoPayMiddleware` |
| Anthropic | `mnemoPayMiddleware` |
| LangGraph | `mnemoPayTools` |
资料来源：[README.md - Middleware](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
### 哈希链完整性
所有行为金融决策通过 Merkle 树记录，确保审计可追溯：
```
MerkleAudit 包含：
├── 行为决策记录
├── Nudge 触发历史
├── 信用评分变更
└── 异常处理日志
```
资料来源：[README.md - Architecture](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
## 版本演进
| 版本 | 关键更新 |
|-----|---------|
| v1.4.0 | 首次引入行为金融引擎，集成前景理论和 Nudge 机制 |
| v1.5.0 | 稳定版发布，架构与 Alpha 版保持一致 |
| v1.6.0-alpha | 持续优化行为模型参数 |
资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md) - 版本信息
## 总结
行为金融引擎是 MnemoPay SDK 区别于传统支付网关的核心创新点之一。通过将 Kahneman 和 Tversky 的行为经济学理论与现代 AI Agent 系统相结合，引擎实现了：
- **风险可控**：通过前景理论框架和 Nudge 机制预防非理性交易
- **信用驱动**：基于行为质量动态调整 Agent 信用评分
- **可审计性**：Merkle 树记录确保所有决策可追溯验证
- **实时干预**：EWMA 异常检测与行为金融评估双重保障
---
## 异常检测系统
### 相关页面
相关主题：[代理信用评分系统](#credit-score), [治理与合规框架](#governance), [身份与认证系统](#identity-auth)
相关源码文件
以下源码文件用于生成本页说明：
- [src/anomaly.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/anomaly.ts)
- [src/fraud.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/fraud.ts)
- [src/fraud-ml.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/fraud-ml.ts)
- [src/recall/rerank.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/rerank.ts)
- [CLAUDE.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/CLAUDE.md)
- [README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
# 异常检测系统
## 概述
异常检测系统是 MnemoPay SDK 的核心安全组件之一，旨在保护 AI Agent 的交易行为和财务操作免受欺诈、滥用和异常模式的侵害。该系统采用多层次检测策略，结合统计学方法（EWMA）、行为监控、地理增强分析和机器学习模型，实现实时的交易风险评估和异常预警。
根据项目架构文档，异常检测系统与其他组件（记忆系统、支付系统、身份系统）并列，共同构成了 MnemoPay SDK 的四大支柱。资料来源：[README.md:11]()
## 核心架构
### 模块组成
| 模块 | 文件路径 | 主要功能 |
|------|----------|----------|
| `anomaly.ts` | `src/anomaly.ts` | EWMA 指数加权移动平均检测、行为监控、金丝雀系统 |
| `fraud.ts` | `src/fraud.ts` | 地理增强欺诈检测、速度限制、费用分析 |
| `fraud-ml.ts` | `src/fraud-ml.ts` | 机器学习驱动的欺诈模式识别 |
| `rerank.ts` | `src/recall/rerank.ts` | 记忆检索重排序（异常关联分析） |
### 系统架构图
```mermaid
graph TB
subgraph 异常检测系统
A[交易事件输入] --> B[行为监控器
BehaviorMonitor]
B --> C[EWMA 检测器]
B --> D[速度限制检查
Velocity Check]
C --> E[金丝雀系统
CanarySystem]
D --> E
E --> F[地理欺诈检测
Geo-Fraud]
F --> G[ML 欺诈检测
fraud-ml]
G --> H[风险评分引擎]
end
H --> I{风险等级判定}
I -->|低风险| J[允许交易]
I -->|中风险| K[标记审查]
I -->|高风险| L[阻断交易]
M[记忆系统] -->|行为特征| B
N[身份系统] -->|权限信息| G
```
## EWMA 异常检测
### 算法原理
EWMA（Exponentially Weighted Moving Average，指数加权移动平均）是一种统计过程控制方法，用于检测时间序列数据中的异常波动。MnemoPay SDK 使用 EWMA 来监控 Agent 的交易行为模式，当实时指标偏离历史基线超过预设阈值时触发告警。
资料来源：[CLAUDE.md:14]()
### 核心配置参数
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `decay_factor` | EWMA 衰减因子，控制历史数据的权重 | `0.95` |
| `alert_threshold` | 告警触发阈值（标准差倍数） | `3.0` |
| `warmup_period` | 预热期样本数（建立基线前不告警） | `100` |
| `reset_on_drift` | 检测到漂移时是否重置基线 | `true` |
### 使用示例
```typescript
import { AnomalyDetector, EWMAConfig } from '@mnemopay/sdk';
const config: EWMAConfig = {
decay_factor: 0.95,
alert_threshold: 3.0,
warmup_period: 100,
reset_on_drift: true
};
const detector = new AnomalyDetector(config);
// 监控交易金额异常
const result = detector.checkTransaction({
agentId: 'agent-001',
amount: 150.00,
timestamp: Date.now()
});
if (result.anomaly) {
console.log(`检测到异常: ${result.reason}, 置信度: ${result.confidence}`);
}
```
## 行为监控系统
### BehaviorMonitor
行为监控器是异常检测系统的核心组件，持续追踪 Agent 的多维度行为指标：
- **交易频率**：单位时间内的交易数量
- **平均交易金额**：历史交易的平均值和标准差
- **时间模式**：交易发生的时间分布特征
- **地理分布**：交易来源的地理位置变化
- **交互模式**：与其他 Agent 的交互频率和类型
资料来源：[CLAUDE.md:14]()
### 行为指标表
| 指标类型 | 监控内容 | 异常阈值 |
|----------|----------|----------|
| `velocity` | 交易速率 | > 10 tx/min |
| `amount_deviation` | 金额偏离度 | > 3σ |
| `geo_entropy` | 地理熵值 | < 0.2 |
| `session_count` | 会话数量 | 异常激增 |
| `api_error_rate` | API 错误率 | > 5% |
## 金丝雀系统
### 功能概述
金丝雀系统（CanarySystem）是一种渐进式发布和灰度检测机制，用于在生产环境中验证新交易模式或检测潜在的异常行为。它通过引入一小部分"金丝雀"交易来测试系统的响应，并将结果与基线进行对比。
资料来源：[CLAUDE.md:14]()
### 工作流程
```mermaid
graph LR
A[新交易模式] --> B[金丝雀采样
10% 流量]
B --> C{模式匹配?}
C -->|是| D[执行交易]
C -->|否| E[记录异常]
D --> F[监控系统响应]
F --> G{响应正常?}
G -->|是| H[扩大流量]
G -->|否| I[回滚/告警]
```
### 金丝雀配置
```typescript
interface CanaryConfig {
sample_rate: number; // 采样比例 (0-1)
timeout_ms: number; // 超时时间
alert_on_fail: boolean; // 失败时告警
auto_rollback: boolean; // 自动回滚
}
```
## 地理欺诈检测
### 地理增强分析
`fraud.ts` 模块实现了基于地理位置的欺诈检测功能，通过分析交易的地理分布来识别潜在的欺诈行为。资料来源：[CLAUDE.md:13]()
### 检测机制
| 检测类型 | 说明 | 阈值配置 |
|----------|------|----------|
| `velocity_geo` | 地理速度异常（不可能的旅行） | 500 km/h |
| `sanctions_check` | 制裁名单匹配 | 精确匹配 |
| `proxy_vpn` | 代理/VPN 使用检测 | 概率 > 0.7 |
| `geo_trust_score` | 地理信任评分 | < 0.3 |
### 集成测试
项目包含专门的地理欺诈测试文件 `geo-fraud.test.ts`，覆盖以下场景：
- 地理信号处理
- 信任评分计算
- 制裁名单检查
- 不可能旅行检测
资料来源：[README.md:40-43]()
## 机器学习欺诈检测
### fraud-ml 模块
`fraud-ml.ts` 模块使用机器学习算法来识别复杂的欺诈模式。该模块提供了基于历史数据的模型训练和实时推理能力。
资料来源：[CLAUDE.md:13]()
### 模型特征
| 特征类别 | 特征名称 | 数据类型 |
|----------|----------|----------|
| 交易特征 | `amount`, `frequency`, `time_gap` | float |
| 行为特征 | `session_length`, `error_rate` | float |
| 网络特征 | `counterparty_count`, `graph_centrality` | float |
| 历史特征 | `chargeback_rate`, `dispute_count` | float |
### 预测接口
```typescript
interface FraudPrediction {
score: number; // 欺诈概率 (0-1)
risk_level: 'low' | 'medium' | 'high';
factors: string[]; // 主要风险因素
confidence: number; // 预测置信度
}
```
## 速度限制检查
### 速率限制机制
速度限制（Velocity Check）是防止滥用和欺诈的第一道防线，通过限制单位时间内的操作次数来实现。
```mermaid
graph TD
A[请求到达] --> B{速率限制检查}
B -->|通过| C[处理交易]
B -->|超限| D[返回 429 Too Many Requests]
C --> E[更新计数器]
E --> F[滑动窗口刷新]
```
### 配置参数
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `max_per_minute` | 每分钟最大请求数 | 60 |
| `max_per_hour` | 每小时最大请求数 | 1000 |
| `max_per_day` | 每天最大请求数 | 10000 |
| `burst_allowance` | 突发容许量 | 10 |
## 重放攻击检测
### 重放检测机制
异常检测系统还包括对重放攻击（Replay Attack）的防护，通过以下机制实现：
1. **时间戳验证**：检查请求时间戳是否在有效窗口内（默认 300 秒）
2. **Nonce 管理**：跟踪已处理的 Nonce 值，防止重复执行
3. **签名校验**：验证 HMAC-SHA256 签名的有效性
```typescript
interface ReplayCheckResult {
valid: boolean;
reason?: string; // 失败原因
timestamp_age?: number; // 时间戳年龄（秒）
}
```
资料来源：[src/mcp/server.ts:24-30]()
## 与其他模块的集成
### 模块依赖关系
```mermaid
graph TB
ANOMALY[异常检测系统] --> IDENTITY[身份系统]
ANOMALY --> LEDGER[账本系统]
ANOMALY --> MEMORY[记忆系统]
ANOMALY --> NETWORK[网络系统]
IDENTITY -->|权限信息| ANOMALY
MEMORY -->|行为基线| ANOMALY
NETWORK -->|交易图谱| ANOMALY
LEDGER -->|审计日志| ANOMALY
```
### 集成点
| 集成模块 | 集成方式 | 数据流向 |
|----------|----------|----------|
| 身份系统 | CapabilityToken 验证 | 输入 |
| 记忆系统 | 行为基线查询 | 输入 |
| 账本系统 | 双录审计日志 | 输出 |
| 网络系统 | 交易图谱分析 | 双向 |
## 测试覆盖
### 测试文件
项目为异常检测系统提供了全面的测试覆盖：
| 测试文件 | 覆盖范围 | 测试数量 |
|----------|----------|----------|
| `core.test.ts` | EWMA、Canary、基线漂移 | 核心功能 |
| `fraud.test.ts` | 速度限制、异常检测、费用分析、争议处理、重放检测 | 8+ 场景 |
| `geo-fraud.test.ts` | 地理信号、信任评分、制裁检查 | 地理场景 |
| `stress-200k.test.ts` | 高并发下的异常检测稳定性 | 200K 操作 |
资料来源：[README.md:35-46]()
### 运行测试
```bash
# 运行所有异常检测相关测试
npm test -- anomaly
# 运行地理欺诈测试
npm test -- geo-fraud
# 运行压力测试
npm test -- stress-200k
```
## 配置最佳实践
### 生产环境配置建议
```typescript
const productionConfig = {
anomaly: {
decay_factor: 0.98, // 更敏感的衰减
alert_threshold: 2.5, // 降低阈值提高灵敏度
warmup_period: 500, // 更长的预热期
reset_on_drift: false // 不自动重置，需人工介入
},
canary: {
sample_rate: 0.01, // 1% 采样
timeout_ms: 5000,
alert_on_fail: true,
auto_rollback: true
},
geo_fraud: {
velocity_threshold: 300, // km/h
trust_score_threshold: 0.5,
sanctions_check_enabled: true
},
rate_limit: {
max_per_minute: 30,
max_per_hour: 500,
max_per_day: 5000
}
};
```
### 告警阈值调整
| 风险等级 | EWMA 倍数 | 地理评分 | 建议操作 |
|----------|-----------|----------|----------|
| 低风险 | < 2σ | > 0.7 | 允许通过 |
| 中风险 | 2-3σ | 0.4-0.7 | 添加人工审核 |
| 高风险 | > 3σ | < 0.4 | 自动阻断 |
## 总结
异常检测系统是 MnemoPay SDK 保障 AI Agent 交易安全的核心防线，通过 EWMA 统计方法、行为监控、金丝雀验证、地理增强分析和机器学习模型的协同工作，实现了多层次、多维度的欺诈防护。该系统与身份系统、记忆系统、账本系统和网络系统紧密集成，形成完整的安全生态。开发者可根据具体业务场景调整检测参数，在安全性与用户体验之间取得平衡。
---
## 支付轨道
### 相关页面
相关主题：[账本与支付系统](#ledger-payments), [治理与合规框架](#governance)
相关源码文件
以下源码文件用于生成本页说明：
- [src/rails/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/index.ts)
- [src/rails/stripe-mpp.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/stripe-mpp.ts)
- [src/rails/x402.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/x402.ts)
- [src/rails/google-ap2.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/google-ap2.ts)
- [src/rails/paystack.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/paystack.ts)
- [src/commerce/providers/shopify.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/commerce/providers/shopify.ts)
- [src/commerce/providers/firecrawl.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/commerce/providers/firecrawl.ts)
- [examples/02-openai-middleware.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/examples/02-openai-middleware.ts)
- [examples/03-anthropic-middleware.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/examples/03-anthropic-middleware.ts)
# 支付轨道
## 概述
支付轨道（Payment Rails）是 MnemoPay SDK 中处理实际资金流转的核心模块，为 AI Agent 提供统一抽象的支付接口。无论底层使用 Stripe、Paystack 还是 Lightning Network，开发者都可通过相同的 API 进行扣款、托管、结算和退款操作。
支付轨道的设计目标包括：
- **统一抽象**：不同支付渠道使用相同的方法签名，降低集成复杂度
- **多渠道支持**：覆盖全球主要支付区域，包括非洲、欧洲、北美和加密货币
- **安全托管**：支持人工审批后才释放资金，防止 Agent 未经授权的消费
- **可扩展架构**：预留扩展接口，便于添加新的支付轨道
资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
## 支持的支付轨道
MnemoPay SDK 目前支持六种支付轨道，分为稳定版和预览版两类。
| 轨道名称 | 覆盖区域 | 状态 | 通道标签 |
|---------|---------|------|---------|
| `StripeRail` | 全球（USD, EUR, GBP） | 稳定版 | `latest` |
| `PaystackRail` | 非洲（NGN, GHS, ZAR, KES） | 稳定版 | `latest` |
| `LightningRail` | BTC 微支付 | 稳定版 | `latest` |
| `StripeMPPRail` | Tempo 加密货币存款 | 预览版 | `alpha` |
| `X402Rail` | Base USDC（EIP-3009） | 预览版 | `alpha` |
| `GoogleAP2Rail` | AP2 v0.2 FIDO Alliance | 预览版 | `alpha` |
资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
### 稳定版轨道
稳定版支付轨道经过生产环境验证，适合对可靠性要求较高的应用场景：
- **StripeRail**：支持 135+ 种货币，采用 PaymentIntents API，支持手动捕获实现真正的托管功能
- **PaystackRail**：覆盖 23 家尼日利亚银行，集成 HMAC-SHA512 安全校验
- **LightningRail**：专为 BTC 子美分级微支付设计
### 预览版轨道
预览版支付轨道处于活跃开发阶段，可能存在 API 变更：
- **StripeMPPRail**：通过 Stripe Marketplace Payments 实现加密货币存款
- **X402Rail**：使用 EIP-3009 的 `transferWithAuthorization` 实现 Base 链上的 USDC 转账
- **GoogleAP2Rail**：基于 FIDO Alliance AP2 v0.2 的 mandate 驱动结算
资料来源：[src/rails/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/index.ts)
## 核心架构
### 轨道接口设计
所有支付轨道继承自统一的基类接口，确保 API 一致性：
```mermaid
classDiagram
class PaymentRail {
<>
+charge(amount, metadata) Promise~ChargeResult~
+settle(txId) Promise~SettleResult~
+refund(txId, amount) Promise~RefundResult~
+webhook(payload) Promise~WebhookResult~
}
class StripeRail {
+stripe: Stripe
+charge()
+settle()
+refund()
}
class PaystackRail {
+paystack: Paystack
+charge()
+settle()
+refund()
}
class LightningRail {
+lnd: LNDClient
+charge()
+settle()
}
PaymentRail <|-- StripeRail
PaymentRail <|-- PaystackRail
PaymentRail <|-- LightningRail
```
### 交易流程
支付轨道支持完整的交易生命周期管理：
```mermaid
graph TD
A[Agent 请求扣款] --> B{支付轨道选择}
B --> C[StripeRail]
B --> D[PaystackRail]
B --> E[LightningRail]
C --> F[创建 PaymentIntent]
D --> G[初始化 Paystack Transaction]
E --> H[创建 Lightning Invoice]
F --> I{用户确认}
G --> I
H --> I
I -->|确认| J[资金托管]
I -->|拒绝| K[交易取消]
J --> L{人工审批}
L -->|通过| M[结算 settle]
L -->|拒绝| N[退款 refund]
M --> O[资金释放给商户]
N --> P[资金退回用户]
```
资料来源：[src/rails/stripe-mpp.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/stripe-mpp.ts)
## 快速开始
### 导入支付轨道
```typescript
import {
PaystackRail, StripeRail, LightningRail, // 稳定版
StripeMPPRail, X402Rail, GoogleAP2Rail, // 预览版
} from "@mnemopay/sdk";
```
### 初始化支付轨道
**Stripe 稳定配置：**
```typescript
const stripe = new StripeRail(process.env.STRIPE_SECRET_KEY!);
```
**Paystack 非洲支付：**
```typescript
const paystack = new PaystackRail(process.env.PAYSTACK_SECRET_KEY!);
```
**Lightning BTC 微支付：**
```typescript
const lightning = new LightningRail(LND_URL, MACAROON);
```
**预览版支付轨道：**
```typescript
// Stripe MPP 加密货币存款
const mpp = new StripeMPPRail(process.env.STRIPE_SECRET_KEY!);
// X402 USDC 转账
const x402 = new X402Rail({ signer: yourEip3009Signer });
// Google AP2 FIDO 结算
const ap2 = new GoogleAP2Rail({ mandate, endpoint, signer });
```
资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
### 与 Agent 集成
初始化 Agent 时指定支付轨道：
```typescript
const agent = MnemoPay.quick("my-agent", {
rail: new StripeRail(process.env.STRIPE_SECRET_KEY!),
// 其他配置...
});
```
## 各支付轨道详解
### StripeRail
StripeRail 是面向全球市场的支付轨道，支持 135+ 种货币和信用卡、借记卡支付。
**核心方法：**
| 方法 | 参数 | 返回值 | 说明 |
|-----|------|-------|------|
| `charge` | `amount`, `currency`, `metadata` | `ChargeResult` | 创建扣款请求 |
| `settle` | `txId` | `SettleResult` | 结算已托管的交易 |
| `refund` | `txId`, `amount?` | `RefundResult` | 退款交易 |
| `createIntent` | `params` | `PaymentIntent` | 创建 PaymentIntent |
**安全特性：**
- 手动捕获模式支持真正的资金托管
- PaymentIntents API 提供 3D Secure 支持
- Webhook 签名验证
资料来源：[src/rails/stripe-mpp.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/stripe-mpp.ts)
### PaystackRail
PaystackRail 专注于非洲市场，深度集成当地银行系统。
**支持货币：**
- NGN（尼日利亚奈拉）
- GHS（加纳塞地）
- ZAR（南非兰特）
- KES（肯尼亚先令）
**特色功能：**
- 23 家尼日利亚银行预映射
- HMAC-SHA512 Webhook 安全校验
- 移动支付和银行转账支持
```typescript
const paystack = new PaystackRail(process.env.PAYSTACK_SECRET_KEY!);
// 非洲本地支付
await paystack.charge(5000, {
currency: 'NGN',
email: 'customer@example.com',
bank: '044' // Access Bank
});
```
资料来源：[src/rails/paystack.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/paystack.ts)
### LightningRail
LightningRail 专为比特币微支付设计，支持子美分级的小额交易。
**技术特性：**
- 即时结算（相较于链上 BTC）
- 极低手续费，适合微支付场景
- 依赖 LND（Lightning Network Daemon）
```typescript
const lightning = new LightningRail(LND_URL, MACAROON);
// 创建 Lightning Invoice
const invoice = await lightning.charge(100, {
description: 'API调用费用',
expiry: 3600 // 1小时过期
});
```
### X402Rail
X402Rail 实现 EIP-3009 标准，在 Base 区块链上支持 USDC 转账。
**核心流程：**
```mermaid
graph LR
A[请求授权] --> B[生成 transferWithAuthorization]
B --> C[用户签名授权]
C --> D[执行 USDC 转账]
D --> E[交易确认]
```
**配置参数：**
| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| `signer` | `EIP3009Signer` | 是 | EIP-3009 签名器实例 |
| `recipient` | `string` | 否 | 默认收款地址 |
| `domain` | `string` | 否 | EIP-712 域名 |
```typescript
const x402 = new X402Rail({
signer: yourEip3009Signer,
recipient: '0x...'
});
```
资料来源：[src/rails/x402.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/x402.ts)
### GoogleAP2Rail
GoogleAP2Rail 基于 FIDO Alliance 的 AP2 v0.2 标准，提供 mandate 驱动的结算机制。
**Mandate 概念：**
Mandate 是用户预先授权的支付指令，允许商户在特定条件下自动扣款。
```typescript
const ap2 = new GoogleAP2Rail({
mandate: {
id: 'mandate_xxx',
maxAmount: 10000,
currency: 'USD',
frequency: 'per_use'
},
endpoint: 'https://api.google.com/ap2/v2',
signer: yourSigner
});
```
资料来源：[src/rails/google-ap2.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/google-ap2.ts)
### StripeMPPRail
StripeMPPRail（Marketplace Payments）允许通过 Stripe 实现加密货币存款和结算。
**应用场景：**
- 多方分账场景
- 加密货币与法币混合支付
- Tempo 生态内的资金流转
```typescript
const mpp = new StripeMPPRail(process.env.STRIPE_SECRET_KEY!);
await mpp.charge(1000, {
currency: 'usdc',
destination: 'tempo_address_xxx'
});
```
资料来源：[src/rails/stripe-mpp.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/stripe-mpp.ts)
## 托管与结算
### 托管机制
支付轨道支持资金托管（Escrow）功能，确保交易经过人工审批后再释放：
```mermaid
graph TD
A[charge 调用] --> B[资金进入托管状态]
B --> C[等待人工审批]
C --> D{审批结果}
D -->|通过| E[settle 结算]
D -->|拒绝| F[refund 退款]
E --> G[资金释放给商户]
F --> H[资金退回用户]
```
### Agent 消费限制
Agent 的支付行为受以下限制保护：
| 限制类型 | 说明 | 配置方式 |
|---------|------|---------|
| `llmCapCents` | LLM 调用费用上限 | 账户级别设置 |
| `seats` | 授权席位数量 | 订阅计划决定 |
| `missionLimit` | 任务执行次数限制 | 计划配额 |
资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)
## Webhook 处理
支付轨道提供统一的 Webhook 接口处理各渠道的异步通知：
```typescript
// 定义 Webhook 处理函数
async function handleWebhook(rail: PaymentRail, payload: WebhookPayload) {
switch (payload.type) {
case 'payment.pending':
// 等待用户确认
break;
case 'payment.succeeded':
// 支付成功，进入托管
break;
case 'payment.failed':
// 支付失败
break;
case 'settlement.completed':
// 结算完成
break;
}
}
```
**安全验证：**
- Stripe：验证 `Stripe-Signature` 头
- Paystack：HMAC-SHA512 签名校验
- Lightning：Invoice 状态轮询
## 错误处理
### 错误类型
| 错误码 | 说明 | 处理建议 |
|-------|------|---------|
| `INSUFFICIENT_FUNDS` | 余额不足 | 提示用户充值 |
| `RAIL_UNAVAILABLE` | 支付渠道不可用 | 切换备用渠道 |
| `KYC_REQUIRED` | 需要完成身份验证 | 引导用户 KYC |
| `FRAUD_SUSPECTED` | 欺诈嫌疑 | 拒绝交易并标记 |
| `SETTLEMENT_LIMIT` | 达到结算限额 | 分批结算 |
### 重试策略
```typescript
async function chargeWithRetry(rail: PaymentRail, amount: number, retries = 3) {
for (let i = 0; i < retries; i++) {
try {
return await rail.charge(amount, {});
} catch (error) {
if (error.code === 'RAIL_UNAVAILABLE' && i < retries - 1) {
await delay(1000 * (i + 1)); // 指数退避
continue;
}
throw error;
}
}
}
```
## 商业购物集成
支付轨道可与商业购物模块配合，实现 Agent 的自主采购：
### Shopify 集成
```typescript
import { ShopifyProvider } from "@mnemopay/commerce/providers/shopify";
const shopify = new ShopifyProvider({
shop: 'your-store.myshopify.com',
token: process.env.SHOPIFY_TOKEN
});
// Agent 搜索商品
const products = await shopify.search({
query: 'wireless headphones',
price_max: 100
});
// 购买流程通过支付轨道托管
```
### Firecrawl 网页抓取
```typescript
import { FirecrawlProvider } from "@mnemopay/commerce/providers/firecrawl";
const firecrawl = new FirecrawlProvider({
apiKey: process.env.FIRECRAWL_KEY
});
// Agent 抓取电商网站比价
const prices = await firecrawl.scrape({
url: 'https://example.com/products',
query: 'price'
});
```
资料来源：[src/commerce/providers/shopify.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/commerce/providers/shopify.ts)
## LLM 中间件集成
支付轨道可作为 LLM API 调用的计费中间件：
### OpenAI 中间件
```typescript
import { createOpenAIMiddleware } from "@mnemopay/sdk/middleware/openai";
const middleware = createOpenAIMiddleware({
rail: new StripeRail(process.env.STRIPE_SECRET_KEY!),
costPerToken: 0.0001
});
app.use('/v1/chat/completions', middleware);
```
### Anthropic 中间件
```typescript
import { createAnthropicMiddleware } from "@mnemopay/sdk/middleware/anthropic";
const middleware = createAnthropicMiddleware({
rail: new StripeRail(process.env.STRIPE_SECRET_KEY!),
modelCosts: {
'claude-3-opus': 0.015,
'claude-3-sonnet': 0.003
}
});
```
资料来源：[examples/02-openai-middleware.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/examples/02-openai-middleware.ts)
## 安全考虑
### 密钥管理
- 支付渠道密钥应存储在环境变量或密钥管理服务
- 切勿将密钥硬编码或提交到版本控制
- 生产环境应使用独立的 Stripe/Paystack 密钥
### 签名验证
所有 Webhook 回调必须验证签名：
```typescript
async function verifyWebhook(rail: PaymentRail, payload: Buffer, signature: string) {
return await rail.verifySignature(payload, signature);
}
```
### 交易限额
建议为不同信任级别的 Agent 设置交易限额：
| Agent 等级 | 单笔限额 | 日累计限额 |
|-----------|---------|-----------|
| 新建 | $10 | $50 |
| 已验证 | $100 | $500 |
| 高信用 | $1000 | $10000 |
| 企业 | 自定义 | 自定义 |
## 总结
支付轨道是 MnemoPay SDK 的核心组件，为 AI Agent 提供安全、统一的支付能力。通过支持 Stripe、Paystack、Lightning 等多种渠道，开发者可以灵活选择适合目标市场的支付方式。稳定版轨道已通过生产验证，预览版轨道则为加密货币和新型支付协议提供了实验基础。
无论选择哪种支付轨道，统一的 API 设计确保了代码的可移植性，而托管机制则保障了资金安全，防止 Agent 未经授权的消费行为。
---
## 治理与合规框架
### 相关页面
相关主题：[身份与认证系统](#identity-auth), [异常检测系统](#anomaly-detection), [代理信用评分系统](#credit-score)
相关源码文件
以下源码文件用于生成本页说明：
- [src/governance/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/index.ts)
- [src/governance/charter.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/charter.ts)
- [src/governance/policy.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/policy.ts)
- [src/governance/policies/eu-ai-act.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/policies/eu-ai-act.ts)
- [src/governance/audit.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/audit.ts)
- [src/governance/audit-chain.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/audit-chain.ts)
- [src/governance/spatial.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/spatial.ts)
- [src/governance/runtime.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/runtime.ts)
- [src/governance/approval.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/approval.ts)
- [compliance/eu-ai-act-annex-iv.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/compliance/eu-ai-act-annex-iv.md)
- [docs/aaif-rfc-agent-trust-attestation.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/docs/aaif-rfc-agent-trust-attestation.md)
# 治理与合规框架
## 概述
MnemoPay SDK 的治理与合规框架是为 AI Agent 提供的一套完整的经济治理、安全审计和监管合规系统。该框架确保 Agent 在执行支付、记忆存储和资源使用等关键操作时遵循预定义的业务规则、预算限制和法规要求。
根据架构文档，治理框架包含以下核心组件：
| 组件 | 功能 | 类别 |
|------|------|------|
| Charter (宪章) | 定义 Agent 任务范围和权限边界 | 任务治理 |
| FiscalGate (财务门控) | 预算执行和费用控制 | 财务治理 |
| Article 12 (第12条) | EU AI Act 合规要求 | 法规合规 |
| MerkleAudit (默克尔审计) | 加密审计链和不可篡改记录 | 审计追溯 |
资料来源：[README.md - Architecture](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)
## 核心架构
治理框架采用分层架构设计，从运行时决策到长期审计形成完整闭环：
```mermaid
graph TD
A[Agent 请求] --> B[宪章验证 Charter]
B --> C{权限检查}
C -->|通过| D[FiscalGate 预算验证]
C -->|拒绝| E[请求拦截]
D --> F{预算充足?}
F -->|是| G[Article 12 合规检查]
F -->|否| H[预算超限拦截]
G --> I{合规判定}
I -->|通过| J[运行时 Runtime]
I -->|拒绝| K[合规拦截]
J --> L[操作执行]
L --> M[审计记录 Audit]
M --> N[审计链 Chain]
N --> O[默克尔根 MerkleRoot]
```
## 宪章系统 (Charter)
### 功能定义
宪章系统定义了每个 Agent 的任务范围、操作权限和资源配额。它是所有治理决策的第一道关卡。
### 核心配置
| 参数 | 类型 | 说明 |
|------|------|------|
| `scope` | string[] | 允许的操作类型列表 |
| `maxBudget` | number | 最大预算限额 |
| `permissions` | Permission[] | 细粒度权限配置 |
| `ttl` | number | 宪章有效期（秒） |
| `version` | string | 宪章版本号 |
资料来源：[src/governance/charter.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/charter.ts)
## 财务门控 (FiscalGate)
### 预算执行机制
FiscalGate 负责在交易执行前验证预算是否充足，并在操作完成后更新实际支出。
```mermaid
graph LR
A[charge 请求] --> B[获取宪章预算]
B --> C{当前支出}
C --> D{支出 + 本次金额 <= 预算?}
D -->|是| E[执行 charge]
D -->|否| F[触发 overLimit]
E --> G[更新计量 metering]
F --> H[记录违规事件]
```
### 计量数据模型
```typescript
interface Metering {
total: number; // 总支出
seats: number; // 活跃席位
missions: Mission[]; // 任务记录
overLimit: boolean; // 是否超限
}
```
资料来源：[src/governance/runtime.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/runtime.ts)
## 策略系统 (Policy)
### 策略引擎架构
策略系统提供可扩展的规则引擎，支持自定义合规策略和第三方监管要求。
### EU AI Act 合规
根据 EU AI Act Annex IV 要求，系统实现了以下合规检查：
| 检查项 | 描述 | 风险等级 |
|--------|------|----------|
| 目的限制 | 验证操作符合声明用途 | 高 |
| 人类监督 | 确保关键决策有人工介入 | 高 |
| 准确性 | 验证模型输出的可靠性 | 中 |
| 韧性 | 错误处理和异常恢复 | 中 |
| 安全性 | 数据保护和访问控制 | 高 |
| 透明性 | 操作日志和可解释性 | 中 |
资料来源：[src/governance/policies/eu-ai-act.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/policies/eu-ai-act.ts)
### 策略配置示例
```typescript
const policy = {
id: 'eu-ai-act-high-risk',
version: '1.0',
rules: [
{ type: 'human_oversight', threshold: 0.95 },
{ type: 'data_minimization', scope: ['pii', 'financial'] },
{ type: 'audit_trail', retention: 365 }
]
};
```
资料来源：[src/governance/policy.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/policy.ts)
## 审计系统 (Audit)
### 审计链架构
审计系统采用默克尔树（Merkle Tree）结构确保审计记录的不可篡改性。
```mermaid
graph TD
A[操作事件] --> B[生成审计记录]
B --> C[计算哈希]
C --> D[添加到叶节点]
D --> E{批量达到阈值?}
E -->|是| F[计算默克尔根]
E -->|否| G[缓存待处理]
F --> H[发布到审计链]
H --> I[存储证明]
```
### 审计记录结构
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 唯一标识符 |
| `timestamp` | number | Unix 时间戳 |
| `agentId` | string | Agent 标识 |
| `action` | string | 操作类型 |
| `result` | string | 执行结果 |
| `metadata` | object | 附加元数据 |
| `hash` | string | 记录哈希值 |
### 默克尔证明
每个审计记录包含指向前一记录的哈希链接，形成链式结构：
```typescript
interface AuditRecord {
record: AuditData;
prevHash: string;
merkleProof?: MerkleProof;
}
```
资料来源：[src/governance/audit-chain.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/audit-chain.ts)
### 审计 Bundle
审计 Bundle 是批量打包的审计记录，支持高效的批量验证和存储：
```typescript
interface AuditBundle {
id: string;
records: AuditRecord[];
merkleRoot: string;
timestamp: number;
signature: string;
}
```
资料来源：[src/governance/audit.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/audit.ts)
## 运行时治理 (Runtime)
### 运行时决策流程
运行时系统负责在操作执行期间进行实时监控和干预。
```mermaid
graph TD
A[操作开始] --> B[加载宪章]
B --> C[权限检查]
C --> D{权限验证}
D -->|通过| E[加载策略]
D -->|拒绝| F[抛出 PolicyViolation]
E --> G[执行前钩子 preHook]
G --> H{前置条件满足?}
H -->|是| I[执行业务逻辑]
H -->|否| J[拒绝操作]
I --> K[执行后钩子 postHook]
K --> L[更新审计链]
L --> M[返回结果]
```
### 异常处理
运行时支持多种异常类型：
| 异常类型 | 触发条件 | 处理策略 |
|----------|----------|----------|
| `PolicyViolation` | 策略检查失败 | 拒绝并记录 |
| `BudgetExceeded` | 预算超限 | 冻结操作 |
| `PermissionDenied` | 权限不足 | 降级或拒绝 |
| `ComplianceFailure` | 合规检查失败 | 阻断交易 |
资料来源：[src/governance/runtime.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/runtime.ts)
## 空间治理 (Spatial)
### 概念定义
空间治理定义了 Agent 的操作边界和资源隔离域。
```typescript
interface SpatialContext {
namespace: string; // 命名空间标识
boundaries: Boundary[]; // 边界限制
isolation: boolean; // 是否隔离
}
```
### 边界类型
| 类型 | 说明 | 约束 |
|------|------|------|
| `memory` | 记忆存储边界 | 存储量上限 |
| `compute` | 计算资源边界 | CPU/内存配额 |
| `network` | 网络访问边界 | 出站请求限制 |
| `finance` | 财务操作边界 | 交易金额限制 |
资料来源：[src/governance/spatial.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/spatial.ts)
## 审批流程 (Approval)
### 工作流状态机
关键操作需要人工审批，审批流程遵循状态机模式：
```mermaid
graph LR
A[Pending] -->|提交| B[Awaiting Review]
B -->|批准| C[Approved]
B -->|拒绝| D[Rejected]
C -->|执行| E[Completed]
D -->|申诉| F[Under Appeal]
F -->|重新审查| B
E -->|失败| G[Failed]
```
### 审批配置
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `requireApproval` | true | 是否需要审批 |
| `approvers` | string[] | 审批者列表 |
| `timeout` | 86400 | 超时时间（秒） |
| `autoEscalate` | false | 超时自动升级 |
资料来源：[src/governance/approval.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/approval.ts)
## 合规框架集成
### EU AI Act 合规清单
根据 Annex IV 要求，MnemoPay SDK 实现了以下技术文档要求：
| 要求 | 实现状态 | 组件 |
|------|----------|------|
| 系统描述 | ✅ | Charter |
| 训练数据来源 | ✅ | Memory Module |
| 模型架构 | ✅ | Agent Core |
| 决策逻辑 | ✅ | Runtime |
| 人类监督措施 | ✅ | Approval |
| 准确性评估 | ✅ | Audit |
| 风险评估报告 | ✅ | Policy Engine |
资料来源：[compliance/eu-ai-act-annex-iv.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/compliance/eu-ai-act-annex-iv.md)
### Agent 信任证明 (AAIF)
系统支持 Agent 身份和行为的信任证明机制：
```typescript
interface AgentTrustAttestation {
agentId: string;
charterHash: string;
auditRoot: string;
complianceLevel: 'basic' | 'standard' | 'enhanced';
issuedAt: number;
expiresAt: number;
signature: string;
}
```
资料来源：[docs/aaif-rfc-agent-trust-attestation.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/docs/aaif-rfc-agent-trust-attestation.md)
## 快速开始
### 初始化治理上下文
```typescript
import { GovernanceContext } from '@mnemopay/sdk/governance';
const ctx = new GovernanceContext({
charter: {
scope: ['memory:remember', 'memory:recall', 'payment:charge'],
maxBudget: 1000,
permissions: ['read:profile', 'write:transaction']
},
policy: 'eu-ai-act-standard',
requireApproval: true
});
```
### 执行受治理的操作
```typescript
const result = await ctx.execute('payment:charge', {
amount: 50,
currency: 'USD',
recipient: 'agent-123'
});
// 审计记录自动生成
console.log(result.auditId); // 审计追踪ID
```
## API 参考
### GovernanceContext
| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `execute(action, params)` | 操作类型, 参数对象 | ExecutionResult | 执行受治理操作 |
| `verifyPolicy(record)` | 审计记录 | boolean | 验证策略合规性 |
| `getMerkleProof(auditId)` | 审计ID | MerkleProof | 获取默克尔证明 |
| `exportAuditBundle()` | 无 | AuditBundle | 导出审计包 |
资料来源：[src/governance/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/index.ts)
## 最佳实践
### 1. 宪章配置
- 遵循最小权限原则，仅授予必要权限
- 设置合理的预算上限和 TTL
- 定期审核和更新宪章版本
### 2. 审计策略
- 确保所有敏感操作都生成审计记录
- 定期导出和验证审计 Bundle
- 保留足够长度的审计历史（建议 365+ 天）
### 3. 合规检查
- 对高风险操作启用人工审批
- 定期运行 EU AI Act 合规检查
- 维护完整的信任证明链
---
---
## Doramagic 踩坑日志
项目：mnemopay/mnemopay-sdk
摘要：发现 8 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 涉及密钥、隐私或敏感领域。
## 1. 安全/权限坑 · 涉及密钥、隐私或敏感领域
- 严重度：high
- 证据强度：source_linked
- 发现：项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。
- 对用户的影响：金融、交易、隐私和密钥场景必须比普通工具更保守。
- 建议检查：补敏感数据流、密钥存储和权限边界审查。
- 防护动作：敏感领域或密钥场景必须保守推荐并要求人工复核。
- 证据：packet_text.keyword_scan | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | matched secret / private key / privacy / trading / finance keyword
## 2. 身份坑 · 仓库名和安装名不一致
- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `mnemopay-sdk` 与安装入口 `@mnemopay/sdk` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- 复现命令：`npm install @mnemopay/sdk`
- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- 证据：identity.distribution | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | repo=mnemopay-sdk; install=@mnemopay/sdk
## 3. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | README/documentation is current enough for a first validation pass.
## 4. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | last_activity_observed missing
## 5. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | no_demo; severity=medium
## 6. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | no_demo; severity=medium
## 7. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | issue_or_pr_quality=unknown
## 8. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | release_recency=unknown