项目简介

MnemoPay SDK 是一个专为 AI Agent（人工智能代理）设计的支付与记忆基础设施开发工具包。该项目由 Jeremiah Omiagbo 创建，采用 Apache 2.0 开源许可证，为开发者提供了将货币化能力、持久化记忆和身份验证集成到 AI 代理应用中的完整解决方案。资料来源：README.md

MnemoPay 不仅仅是一个 Stripe 包装器，而是一个为代理原生构建的完整支付系统，支持 Stripe、Paystack 和 Lightning（加密货币）三种支付通道。资料来源：site/index.html

核心版本信息

资料来源：README.md:27

技术架构

MnemoPay SDK 的架构采用分层模块化设计，集成了多个核心子系统。以下是整体架构示意图：

graph TB
    subgraph 顶层
        G[GOVERNANCE<br/>Charter · FiscalGate<br/>Article 12 · MerkleAudit]
    end
    
    subgraph 核心功能层
        M[Memory<br/>remember · recall<br/>reinforce · forget]
        P[Payments<br/>charge · settle<br/>refund · dispute]
        I[Identity<br/>KYA · tokens<br/>perms · killswitch]
    end
    
    subgraph 高级功能层
        C[Agent Credit Score<br/>300-850 评分<br/>5组件评分体系]
        B[Behavioral Finance<br/>前景理论<br/>行为引导]
        A[Anomaly Detection<br/>EWMA + 指纹识别]
    end
    
    G --> M
    G --> P
    G --> I
    I --> C
    C --> B
    B --> A

资料来源：README.md:28-42

核心子系统详解

记忆系统（Memory）

记忆系统为 AI Agent 提供了持久化和检索信息的能力，支持以下核心操作：

该系统支持命名空间隔离，允许按业务领域组织记忆数据。资料来源：integrations/python-hosted/README.md

支付系统（Payments）

支付系统支持完整的交易生命周期管理：

graph LR
    A[charge<br/>扣款] --> B[escrow<br/>资金托管]
    B --> C{人工审批}
    C -->|通过| D[settle<br/>结算]
    C -->|拒绝| E[refund<br/>退款]
    D --> F[(Ledger<br/>账本记录)]
    E --> F

资料来源：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

行为金融模块（Behavioral Finance）

基于前景理论（Prospect Theory）设计，提供用户行为引导和激励优化功能。该模块帮助开发者构建更符合用户心理预期的交易体验。资料来源：README.md:38

异常检测模块（Anomaly Detection）

采用指数加权移动平均（EWMA）算法结合指纹识别技术，实时监控和识别可疑交易行为。资料来源：README.md:39

治理系统（Governance）

治理模块包含四个核心组件：

该模块负责任务范围界定、预算执行和审计捆绑。资料来源：README.md:29-30

开发工作流

基于 MnemoPay SDK 构建应用的标准流程包含四个步骤：

graph TD
    A[1. 安装<br/>npm install @mnemopay/sdk] --> B[2. 初始化<br/>MnemoPay.quick agent-id]
    B --> C[3. 交易操作<br/>charge · settle · refund]
    C --> D[4. 规模扩展<br/>自主购物 · 多代理商务 · 信用评分]

资料来源：site/index.legacy.html

中间件集成

MnemoPay SDK 提供与主流 AI 框架的中间件集成：

资料来源：README.md:11-17

Python SDK 功能

Python 集成包 mnemopay 提供了完整的功能接口：

主要方法

资料来源：integrations/python-hosted/README.md

仪表板功能

MnemoPay 提供了一个功能丰富的 Web 仪表板（dashboard/index.html），包含以下模块：

资料来源：dashboard/index.html

套餐定价

交易手续费：Pro 套餐按已结算交易的 1.5% 收取额外费用。资料来源：site/index.html

商业模式与防欺诈

MnemoPay 提供了一个 chargeback（chargeback 防止）计算器工具，帮助用户评估 AI 代理引发的退款争议的实际成本，以及加密签名收据能为 SaaS 平台节省的费用。资料来源：site/calculator.html

相关资源

概述

「快速开始」是 MnemoPay SDK 为开发者提供的最短路径集成方案。通过极简的初始化流程，开发者可以在数分钟内为 AI Agent 集成记忆管理、支付处理、身份认证和信用评分四大核心能力。

核心特性：

• 零配置启动：MnemoPay.quick("agent-id") 一行代码完成全部初始化
• 完整能力栈：内存记忆、钱包交易、KYA 身份验证、Agent 信用评分
• 多支付通道：支持 Stripe、Paystack、Lightning 三种主流支付轨道
• 中间件生态：开箱即用的 OpenAI、Anthropic、LangGraph 集成

资料来源：README.md:1-20

安装

环境要求

安装命令

npm install @mnemopay/sdk
# 或
pnpm add @mnemopay/sdk

资料来源：site/index.legacy.html:50-55

基础使用

快速初始化

使用 MnemoPay.quick() 方法实现零配置启动：

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 方法

#### 内存管理

// 存储用户偏好
await mnemopay.remember("user_pref", {
  name: "张三",
  tier: "premium"
});

// 检索相关记忆
const memories = await mnemopay.recall("用户 偏好 premium");

#### 支付交易

// 发起收款
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

工作流程

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 中间件

import { mnemoPayMiddleware } from "@mnemopay/sdk/middleware/openai";

将 MnemoPay 支付能力无缝集成到 OpenAI 的 Agent 框架中。

Anthropic 中间件

import { mnemoPayMiddleware } from "@mnemopay/sdk/middleware/anthropic";

支持 Anthropic Claude 模型的支付回调集成。

LangGraph 工具集成

import { mnemoPayTools } from "@mnemopay/sdk/langgraph";

提供 LangGraph 可调用的支付工具节点。

资料来源：README.md:35-45

生产环境配置

生产模式初始化

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"
});

配置选项

生产检查清单

• [ ] 使用正式环境 API Key
• [ ] 配置 Webhook 端点
• [ ] 选择合适的持久化方案（生产环境推荐 SQLite）
• [ ] 设置支付通道（Stripe/Paystack/Lightning）
• [ ] 配置 KYA（Know Your Agent）验证流程

资料来源：examples/06-production.ts, site/index.html, site/index.legacy.html

架构概览

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

模块职责

资料来源：README.md:15-45

错误处理

常见错误

错误处理示例

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 身份验证");
  }
}

下一步

概述

MnemoPay SDK 的内存与记忆系统是整个 SDK 的核心模块，负责为 AI Agent 提供持久化记忆能力。该系统使 Agent 能够跨会话保持上下文，实现真正的连续性和个性化交互。

核心功能包括：

• 语义记忆存储：通过 remember 方法存储记忆，支持重要度评分和标签系统
• 混合检索引擎：recall 方法支持语义搜索和混合检索模式
• 知识图谱：基于实体和关系构建知识网络，支持图结构查询
• 观察点再生：自动更新实体关联的观察点内容
• 行为强化：基于交互结果自动调整记忆权重
• 完整性校验：使用 Merkle 树结构确保记忆数据不可篡改

资料来源：README.md

概述

MnemoPay 的账本与支付系统是专为 AI Agent 设计的金融基础设施层，提供从充值、托管到结算、退款的全链路资金管理能力。该系统并非简单的支付网关封装，而是一套完整的双账本（Double-Entry Ledger）机制，确保每一笔资金流向都有精确的借方和贷方记录。

核心价值主张：

• 支持 Stripe（全球）、Paystack（非洲）、Lightning（BTC 微支付）三条真实支付通道
• 统一的 API 接口，屏蔽底层通道差异
• 内置交易托管（Escrow）机制，人类审批后才释放资金
• 交易事件 Webhook 推送，支持 HMAC-SHA256 签名验签

资料来源：README.md

系统架构概览

身份与认证系统采用分层架构设计，各层之间职责明确、解耦清晰。

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 的身份系统包含以下核心组件：

资料来源：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 的身份证明、资质文件、权限声明等信息。

graph LR
    B[Bundle] --> K[KYA 凭证]
    B --> P[Permissions 权限]
    B --> T[Tokens 代币]
    B --> R[Reputation 信誉]

Bundle 的设计使得身份信息可以作为一个整体进行传输和验证，同时支持选择性披露。

资料来源：src/identity/bundle.ts

钱包模块（Wallet）

钱包模块管理 Agent 的资金、信誉评分和交易历史。

#### 账户状态管理

Dashboard 中的账户状态管理展示了钱包与身份系统的集成方式：

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 的登录、登出和会话状态维护。

#### 登录流程

sequenceDiagram
    participant Agent
    participant SessionPanel
    participant Network
    participant Identity
    
    Agent->>SessionPanel: 请求登录
    SessionPanel->>Network: 验证凭证
    Network->>Identity: 验证身份
    Identity-->>Network: 验证结果
    Network-->>SessionPanel: 会话令牌
    SessionPanel-->>Agent: 登录成功

#### 会话状态管理

Dashboard 组件中实现了完整的会话状态管理：

const [session, setSession] = useState(null);
const [accountId, setAccountIdState] = useState(getAccountId());
const [connected, setConnected] = useState(false);

关键状态变量：

资料来源：dashboard/index.html:167-172

权限控制模块

权限模块实现细粒度的访问控制和安全策略。

#### Permissions 权限矩阵

MnemoPay 采用基于角色的访问控制（RBAC）与属性基访问控制（ABAC）混合模型：

graph TD
    R[Request] --> P{Permissions Check}
    P -->|有权限| A[Allow]
    P -->|无权限| K{KillSwitch}
    K -->|触发熔断| B[Block]
    K -->|未触发| D[Deny]

#### KillSwitch 熔断机制

KillSwitch 是安全防护的最后一道防线，在检测到异常行为时自动触发：

资料来源：README.md:46-48

网络通信与验证

网络层架构

网络层负责所有身份相关的通信请求，包括验证、签发、更新等操作。

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 核验级别

身份凭证要求

L3 及以上级别需要提供：

• 法定身份证明（身份证、护照）
• 地址证明（水电费账单）
• 企业注册文件（适用于 L4）

资料来源：README.md:41-44

Agent 信用评分

Agent 信用评分是 MnemoPay 的核心创新之一，为 AI Agent 提供可量化的信用指标。

评分计算模型

graph LR
    A[行为数据] --> B[实时监控]
    B --> C[EWMA 统计]
    C --> D[异常检测]
    D --> E[评分更新]
    E --> F[信用报告]

评分维度

异常检测机制

系统采用 EWMA（指数加权移动平均）+ 指纹识别双重机制进行异常检测：

• EWMA：检测交易金额、频率的统计异常
• 指纹识别：识别设备、IP、行为模式的异常

资料来源：README.md:51-54

安全性设计

安全层级

graph TD
    subgraph 安全防护
        S1[身份标识]
        S2[通信加密]
        S3[权限验证]
        S4[行为监控]
        S5[熔断保护]
    end
    
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5

威胁防护措施

快速开始

初始化身份

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); // 信誉评分

管理会话

// 登录
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();

权限检查

// 检查权限
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 能够像企业一样拥有身份、管理资金、建立信誉，为自主经济奠定基础。

概述

代理信用评分系统（Agent Credit Scoring System）是 MnemoPay SDK 的核心组件之一，为 AI 代理提供类似人类信用评分的信任评估机制。该系统采用 300-850 的评分范围，模拟传统 FICO 信用评分模型，针对 AI 代理的交易行为、支付历史和可靠性进行多维度评估。

代理信用评分直接影响交易手续费率、交易限额以及系统对异常行为的容忍度。评分越高的代理可享受更低的手续费（Enterprise 级别最低至 1.0%）和更高的交易限额，而评分较低的代理将面临更严格的监控甚至自动封禁。

资料来源：README.md

系统架构

代理信用评分系统由多个协同工作的模块组成，采用五组件评分架构，结合行为金融学和异常检测技术。

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 模块是评分系统的基础实现，负责计算代理的基础信用分值。该模块采用双余额记账系统追踪代理的财务状况，通过分析交易历史计算综合评分。

评分计算考虑以下因素：

资料来源：src/fico.ts

行为金融分析模块

行为金融分析模块运用前景理论（Prospect Theory）和 nudge 机制，对代理的决策模式进行深度分析。该模块通过观察代理在相似场景下的历史决策，识别风险偏好和交易行为模式。

graph LR
    A[交易行为数据] --> B[行为模式识别]
    B --> C{前景理论分析}
    C --> D[损失厌恶系数]
    C --> E[风险偏好曲线]
    C --> F[决策偏差检测]
    D --> G[行为评分调整]
    E --> G
    F --> G
    G --> H[最终行为分数]

该模块的核心功能包括：

• 损失厌恶评估：测量代理对损失的敏感程度，量化代理在面临潜在损失时的决策倾向
• 风险偏好曲线：基于前景理论建模代理的风险承担意愿，高风险偏好代理在市场波动时可能做出更激进的决策
• 决策偏差检测：识别代理行为中的系统性偏差，如锚定效应、可得性启发等认知偏差
• Nudge 机制：根据代理的行为模式自动施加微小的决策引导，优化交易结果

资料来源：src/behavioral.ts

子代理成本追踪模块

子代理成本追踪模块专门针对多代理系统设计，记录和归因子代理的资源消耗。该模块维护每个子代理的成本中心，支持成本分配和内部结算。

graph TD
    A[父代理] --> B[子代理成本记录]
    B --> C[资源消耗追踪]
    C --> D[成本归因分析]
    D --> E[内部结算]
    E --> F[成本效率评分]
    F --> G[父代理信用影响]

关键功能：

• 资源消耗追踪：记录 CPU、内存、API 调用等资源使用情况
• 成本归因：将子代理产生的成本准确归属到对应的父代理
• 效率评分：基于成本消耗与交易价值的比率计算效率分数

资料来源：src/subagent-cost.ts

异常检测模块

异常检测模块采用指数加权移动平均（EWMA）和指纹识别技术，实时监控代理行为，识别潜在的欺诈或异常活动。

graph TD
    A[交易数据流] --> B[EWMA统计监控]
    A --> C[行为指纹生成]
    B --> D{异常判定}
    C --> D
    D -->|正常| E[更新基准线]
    D -->|异常| F[触发警报]
    D -->|严重| G[自动封禁]
    F --> H[人工审核队列]

检测机制：

资料来源：README.md

评分计算流程

初始化阶段

代理首次初始化时，系统基于 Ed25519 加密身份创建唯一标识符，并分配初始信用评分。

// 初始化代理并获取信用评分
const agent = MnemoPay.quick("billing-agent", {
  stripe: { secretKey: process.env.STRIPE_SECRET_KEY }
});

// 信用评分将在首次交易后计算
console.log(agent.id); // Ed25519 派生身份

动态评分更新

评分系统采用流式计算模式，每次交易完成后自动更新评分。

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: 新评分生效

评分应用场景

手续费等级

信用评分直接决定代理的交易手续费率：

资料来源：site/index.html

交易限额

评分决定代理的即时交易限额和日累计限额：

• 高评分代理（750+）：无单笔限额，日限额根据账户历史自动调整
• 中等评分代理（550-749）：单笔限额 $10,000，日限额 $100,000
• 低评分代理（300-549）：单笔限额 $1,000，日限额 $5,000，需要人工审批

自动风控

评分系统与风控引擎深度集成：

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

// 仪表盘显示的代理信息结构
interface AgentProfile {
  wallet: number;          // 钱包余额
  reputation: number;       // 信誉分数 (0-1)
  memoriesCount: number;    // 记忆条目数
  transactionsCount: number;// 交易总数
}

API 参考

获取代理评分

const score = await agent.getCreditScore();
// 返回: { score: number, factors: CreditFactor[] }

更新行为数据

await agent.updateBehavioralData({
  transactionPattern: 'conservative',
  riskTolerance: 0.3,
  lossAversion: 2.5
});

查询子代理成本

const costReport = await agent.getSubagentCosts({
  period: '30d',
  groupBy: 'subagent'
});

总结

代理信用评分系统是 MnemoPay SDK 的核心信任基础设施，通过五组件评分架构、行为金融分析和实时异常检测，为 AI 代理提供可量化的信任评估。评分系统与支付引擎深度集成，直接影响手续费率、交易限额和风控策略，确保只有可靠的代理能够参与金融交易。

概述

行为金融引擎是 MnemoPay SDK v1.4.0+ 中的核心模块之一，专注于将行为经济学原理（特别是前景理论/Prospect Theory）与 AI Agent 的支付决策系统相结合。该引擎通过实时干预和引导机制，优化 Agent 的金融行为，降低系统性风险，并提升整体支付生态的健康度。

资料来源：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

工作原理

前景理论集成

行为金融引擎基于 Kahneman 和 Tversky 的前景理论（Prospect Theory）设计。该理论的核心洞察是：人类（及 AI Agent）在面对收益和损失时表现出非对称的风险偏好：

• 确定效应：倾向于选择确定的收益而非概率收益
• 反射效应：在损失面前表现为风险寻求
• 损失厌恶：对损失的敏感度高于等量收益（约 2.25 倍）
• 参考点依赖：决策结果取决于相对于参考点的变化

资料来源：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 触发场景
if (transaction.amount > threshold * reputationScore) {
  applyNudge({
    type: 'DELAY_CONFIRMATION',
    message: '建议在执行前等待确认',
    cooldown: 30000 // 30秒冷却
  });
}

资料来源：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

与 Agent Credit Score 的交互

行为金融引擎的输出直接影响 Agent Credit Score（300-850 分）：

graph TD
    A[交易完成] --> B[行为评估]
    B --> C{决策质量评分}
    C -->|理性决策| D[+信用分]
    C -->|异常交易| E[-信用分]
    C -->|高风险拦截| F[大幅扣分 + 标记]
    D --> G[更新5维评分模型]
    E --> G
    F --> G

评分反馈闭环

引擎在每次交易结算（settle）时触发信用反馈循环：

// 行为反馈机制
onSettle(transaction) {
  const behaviorScore = evaluateDecisionQuality(transaction);
  const creditImpact = behaviorScore * FEEDBACK_LOOP_WEIGHT; // 0.05
  updateCreditScore(creditImpact);
}

资料来源：dashboard/index.html - 信用评分衰减注释

配置参数

实时参数调整

引擎支持基于市场条件的动态参数调整：

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

应用场景

场景一：代理购物（Autonomous Shopping）

当 Agent 代表用户执行购买决策时：

1. 交易前：评估用户历史偏好和风险承受能力
2. 交易中：应用前景理论框架调整购买确认流程
3. 交易后：基于结算结果更新 Agent 信用评分

// 自动购物中的行为金融干预
const shoppingAgent = MnemoPay.quick("shopping-agent");
const purchase = await shoppingAgent.charge(299.00, "Enterprise plan");

// 引擎自动评估：
// - 金额是否超出代理信用上限
// - 交易频率是否异常
// - 交易对手风险评分

场景二：多代理商业（Multi-Agent Commerce）

在多 Agent 协作场景中，行为金融引擎提供：

• 信任传递：基于信用评分的行为担保
• 争议预防：Nudge 机制减少事后纠纷
• 清算优化：前景理论驱动的最优结算时机选择

资料来源：site/index.legacy.html - 规模扩展场景

监控与仪表板

行为金融引擎的各项指标可在 MnemoPay Dashboard 中实时监控：

// Dashboard 展示的关键指标
interface BehavioralMetrics {
  reputation: number;              // 当前声誉值 (0-1)
  ceiling: number;                 // 当前计费上限 ($)
  decay: number;                   // 衰减率
  feedbackLoop: string;            // 反馈循环状态
  overLimit: boolean;              // 是否超限
}

Dashboard 面板通过以下组件展示引擎状态：

资料来源：dashboard/index.html - 计费面板代码

技术特性

无侵入集成

行为金融引擎作为 SDK 中间件层实现，对业务逻辑无侵入：

// 中间件注册方式
import { mnemoPayMiddleware } from "@mnemopay/sdk/middleware/openai";
// 或
import { mnemoPayMiddleware } from "@mnemopay/sdk/middleware/anthropic";

跨平台支持

引擎通过标准化接口支持多种 AI 框架：

资料来源：README.md - Middleware

哈希链完整性

所有行为金融决策通过 Merkle 树记录，确保审计可追溯：

MerkleAudit 包含：
├── 行为决策记录
├── Nudge 触发历史
├── 信用评分变更
└── 异常处理日志

资料来源：README.md - Architecture

版本演进

资料来源：README.md - 版本信息

总结

行为金融引擎是 MnemoPay SDK 区别于传统支付网关的核心创新点之一。通过将 Kahneman 和 Tversky 的行为经济学理论与现代 AI Agent 系统相结合，引擎实现了：

• 风险可控：通过前景理论框架和 Nudge 机制预防非理性交易
• 信用驱动：基于行为质量动态调整 Agent 信用评分
• 可审计性：Merkle 树记录确保所有决策可追溯验证
• 实时干预：EWMA 异常检测与行为金融评估双重保障

概述

异常检测系统是 MnemoPay SDK 的核心安全组件之一，旨在保护 AI Agent 的交易行为和财务操作免受欺诈、滥用和异常模式的侵害。该系统采用多层次检测策略，结合统计学方法（EWMA）、行为监控、地理增强分析和机器学习模型，实现实时的交易风险评估和异常预警。

根据项目架构文档，异常检测系统与其他组件（记忆系统、支付系统、身份系统）并列，共同构成了 MnemoPay SDK 的四大支柱。资料来源：README.md:11

核心架构

模块组成

系统架构图

graph TB
    subgraph 异常检测系统
        A[交易事件输入] --> B[行为监控器<br/>BehaviorMonitor]
        B --> C[EWMA 检测器]
        B --> D[速度限制检查<br/>Velocity Check]
        C --> E[金丝雀系统<br/>CanarySystem]
        D --> E
        E --> F[地理欺诈检测<br/>Geo-Fraud]
        F --> G[ML 欺诈检测<br/>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

核心配置参数

使用示例

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

行为指标表

金丝雀系统

功能概述

金丝雀系统（CanarySystem）是一种渐进式发布和灰度检测机制，用于在生产环境中验证新交易模式或检测潜在的异常行为。它通过引入一小部分"金丝雀"交易来测试系统的响应，并将结果与基线进行对比。

资料来源：CLAUDE.md:14

工作流程

graph LR
    A[新交易模式] --> B[金丝雀采样<br/>10% 流量]
    B --> C{模式匹配?}
    C -->|是| D[执行交易]
    C -->|否| E[记录异常]
    D --> F[监控系统响应]
    F --> G{响应正常?}
    G -->|是| H[扩大流量]
    G -->|否| I[回滚/告警]

金丝雀配置

interface CanaryConfig {
  sample_rate: number;      // 采样比例 (0-1)
  timeout_ms: number;       // 超时时间
  alert_on_fail: boolean;   // 失败时告警
  auto_rollback: boolean;   // 自动回滚
}

地理欺诈检测

地理增强分析

fraud.ts 模块实现了基于地理位置的欺诈检测功能，通过分析交易的地理分布来识别潜在的欺诈行为。资料来源：CLAUDE.md:13

检测机制

集成测试

项目包含专门的地理欺诈测试文件 geo-fraud.test.ts，覆盖以下场景：

• 地理信号处理
• 信任评分计算
• 制裁名单检查
• 不可能旅行检测

资料来源：README.md:40-43

机器学习欺诈检测

fraud-ml 模块

fraud-ml.ts 模块使用机器学习算法来识别复杂的欺诈模式。该模块提供了基于历史数据的模型训练和实时推理能力。

资料来源：CLAUDE.md:13

模型特征

预测接口

interface FraudPrediction {
  score: number;          // 欺诈概率 (0-1)
  risk_level: 'low' | 'medium' | 'high';
  factors: string[];      // 主要风险因素
  confidence: number;      // 预测置信度
}

速度限制检查

速率限制机制

速度限制（Velocity Check）是防止滥用和欺诈的第一道防线，通过限制单位时间内的操作次数来实现。

graph TD
    A[请求到达] --> B{速率限制检查}
    B -->|通过| C[处理交易]
    B -->|超限| D[返回 429 Too Many Requests]
    C --> E[更新计数器]
    E --> F[滑动窗口刷新]

配置参数

重放攻击检测

重放检测机制

异常检测系统还包括对重放攻击（Replay Attack）的防护，通过以下机制实现：

1. 时间戳验证：检查请求时间戳是否在有效窗口内（默认 300 秒）
2. Nonce 管理：跟踪已处理的 Nonce 值，防止重复执行
3. 签名校验：验证 HMAC-SHA256 签名的有效性

interface ReplayCheckResult {
  valid: boolean;
  reason?: string;        // 失败原因
  timestamp_age?: number; // 时间戳年龄（秒）
}

资料来源：src/mcp/server.ts:24-30

与其他模块的集成

模块依赖关系

graph TB
    ANOMALY[异常检测系统] --> IDENTITY[身份系统]
    ANOMALY --> LEDGER[账本系统]
    ANOMALY --> MEMORY[记忆系统]
    ANOMALY --> NETWORK[网络系统]
    
    IDENTITY -->|权限信息| ANOMALY
    MEMORY -->|行为基线| ANOMALY
    NETWORK -->|交易图谱| ANOMALY
    LEDGER -->|审计日志| ANOMALY

集成点

测试覆盖

测试文件

项目为异常检测系统提供了全面的测试覆盖：

资料来源：README.md:35-46

运行测试

# 运行所有异常检测相关测试
npm test -- anomaly

# 运行地理欺诈测试
npm test -- geo-fraud

# 运行压力测试
npm test -- stress-200k

配置最佳实践

生产环境配置建议

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
  }
};

告警阈值调整

总结

异常检测系统是 MnemoPay SDK 保障 AI Agent 交易安全的核心防线，通过 EWMA 统计方法、行为监控、金丝雀验证、地理增强分析和机器学习模型的协同工作，实现了多层次、多维度的欺诈防护。该系统与身份系统、记忆系统、账本系统和网络系统紧密集成，形成完整的安全生态。开发者可根据具体业务场景调整检测参数，在安全性与用户体验之间取得平衡。

概述

支付轨道（Payment Rails）是 MnemoPay SDK 中处理实际资金流转的核心模块，为 AI Agent 提供统一抽象的支付接口。无论底层使用 Stripe、Paystack 还是 Lightning Network，开发者都可通过相同的 API 进行扣款、托管、结算和退款操作。

支付轨道的设计目标包括：

• 统一抽象：不同支付渠道使用相同的方法签名，降低集成复杂度
• 多渠道支持：覆盖全球主要支付区域，包括非洲、欧洲、北美和加密货币
• 安全托管：支持人工审批后才释放资金，防止 Agent 未经授权的消费
• 可扩展架构：预留扩展接口，便于添加新的支付轨道

资料来源：README.md

支持的支付轨道

MnemoPay SDK 目前支持六种支付轨道，分为稳定版和预览版两类。

资料来源：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

核心架构

轨道接口设计

所有支付轨道继承自统一的基类接口，确保 API 一致性：

classDiagram
    class PaymentRail {
        <<abstract>>
        +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

交易流程

支付轨道支持完整的交易生命周期管理：

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

快速开始

导入支付轨道

import {
  PaystackRail, StripeRail, LightningRail,    // 稳定版
  StripeMPPRail, X402Rail, GoogleAP2Rail,      // 预览版
} from "@mnemopay/sdk";

初始化支付轨道

Stripe 稳定配置：

const stripe = new StripeRail(process.env.STRIPE_SECRET_KEY!);

Paystack 非洲支付：

const paystack = new PaystackRail(process.env.PAYSTACK_SECRET_KEY!);

Lightning BTC 微支付：

const lightning = new LightningRail(LND_URL, MACAROON);

预览版支付轨道：

// 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

与 Agent 集成

初始化 Agent 时指定支付轨道：

const agent = MnemoPay.quick("my-agent", {
  rail: new StripeRail(process.env.STRIPE_SECRET_KEY!),
  // 其他配置...
});

各支付轨道详解

StripeRail

StripeRail 是面向全球市场的支付轨道，支持 135+ 种货币和信用卡、借记卡支付。

核心方法：

安全特性：

• 手动捕获模式支持真正的资金托管
• PaymentIntents API 提供 3D Secure 支持
• Webhook 签名验证

资料来源：src/rails/stripe-mpp.ts

PaystackRail

PaystackRail 专注于非洲市场，深度集成当地银行系统。

支持货币：

• NGN（尼日利亚奈拉）
• GHS（加纳塞地）
• ZAR（南非兰特）
• KES（肯尼亚先令）

特色功能：

• 23 家尼日利亚银行预映射
• HMAC-SHA512 Webhook 安全校验
• 移动支付和银行转账支持

const paystack = new PaystackRail(process.env.PAYSTACK_SECRET_KEY!);

// 非洲本地支付
await paystack.charge(5000, {
  currency: 'NGN',
  email: '[email protected]',
  bank: '044' // Access Bank
});

资料来源：src/rails/paystack.ts

LightningRail

LightningRail 专为比特币微支付设计，支持子美分级的小额交易。

技术特性：

• 即时结算（相较于链上 BTC）
• 极低手续费，适合微支付场景
• 依赖 LND（Lightning Network Daemon）

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 转账。

核心流程：

graph LR
    A[请求授权] --> B[生成 transferWithAuthorization]
    B --> C[用户签名授权]
    C --> D[执行 USDC 转账]
    D --> E[交易确认]

配置参数：

const x402 = new X402Rail({
  signer: yourEip3009Signer,
  recipient: '0x...'
});

资料来源：src/rails/x402.ts

GoogleAP2Rail

GoogleAP2Rail 基于 FIDO Alliance 的 AP2 v0.2 标准，提供 mandate 驱动的结算机制。

Mandate 概念：

Mandate 是用户预先授权的支付指令，允许商户在特定条件下自动扣款。

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

StripeMPPRail

StripeMPPRail（Marketplace Payments）允许通过 Stripe 实现加密货币存款和结算。

应用场景：

• 多方分账场景
• 加密货币与法币混合支付
• Tempo 生态内的资金流转

const mpp = new StripeMPPRail(process.env.STRIPE_SECRET_KEY!);

await mpp.charge(1000, {
  currency: 'usdc',
  destination: 'tempo_address_xxx'
});

资料来源：src/rails/stripe-mpp.ts

托管与结算

托管机制

支付轨道支持资金托管（Escrow）功能，确保交易经过人工审批后再释放：

graph TD
    A[charge 调用] --> B[资金进入托管状态]
    B --> C[等待人工审批]
    C --> D{审批结果}
    D -->|通过| E[settle 结算]
    D -->|拒绝| F[refund 退款]
    
    E --> G[资金释放给商户]
    F --> H[资金退回用户]

Agent 消费限制

Agent 的支付行为受以下限制保护：

资料来源：dashboard/index.html

Webhook 处理

支付轨道提供统一的 Webhook 接口处理各渠道的异步通知：

// 定义 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 状态轮询

错误处理

错误类型

重试策略

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 集成

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 网页抓取

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

LLM 中间件集成

支付轨道可作为 LLM API 调用的计费中间件：

OpenAI 中间件

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 中间件

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

安全考虑

密钥管理

• 支付渠道密钥应存储在环境变量或密钥管理服务
• 切勿将密钥硬编码或提交到版本控制
• 生产环境应使用独立的 Stripe/Paystack 密钥

签名验证

所有 Webhook 回调必须验证签名：

async function verifyWebhook(rail: PaymentRail, payload: Buffer, signature: string) {
  return await rail.verifySignature(payload, signature);
}

交易限额

建议为不同信任级别的 Agent 设置交易限额：

总结

支付轨道是 MnemoPay SDK 的核心组件，为 AI Agent 提供安全、统一的支付能力。通过支持 Stripe、Paystack、Lightning 等多种渠道，开发者可以灵活选择适合目标市场的支付方式。稳定版轨道已通过生产验证，预览版轨道则为加密货币和新型支付协议提供了实验基础。

无论选择哪种支付轨道，统一的 API 设计确保了代码的可移植性，而托管机制则保障了资金安全，防止 Agent 未经授权的消费行为。

概述

MnemoPay SDK 的治理与合规框架是为 AI Agent 提供的一套完整的经济治理、安全审计和监管合规系统。该框架确保 Agent 在执行支付、记忆存储和资源使用等关键操作时遵循预定义的业务规则、预算限制和法规要求。

根据架构文档，治理框架包含以下核心组件：

资料来源：README.md - Architecture

核心架构

治理框架采用分层架构设计，从运行时决策到长期审计形成完整闭环：

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 的任务范围、操作权限和资源配额。它是所有治理决策的第一道关卡。

核心配置

资料来源：src/governance/charter.ts

财务门控 (FiscalGate)

预算执行机制

FiscalGate 负责在交易执行前验证预算是否充足，并在操作完成后更新实际支出。

graph LR
    A[charge 请求] --> B[获取宪章预算]
    B --> C{当前支出}
    C --> D{支出 + 本次金额 <= 预算?}
    D -->|是| E[执行 charge]
    D -->|否| F[触发 overLimit]
    E --> G[更新计量 metering]
    F --> H[记录违规事件]

计量数据模型

interface Metering {
  total: number;        // 总支出
  seats: number;         // 活跃席位
  missions: Mission[];   // 任务记录
  overLimit: boolean;    // 是否超限
}

资料来源：src/governance/runtime.ts

策略系统 (Policy)

策略引擎架构

策略系统提供可扩展的规则引擎，支持自定义合规策略和第三方监管要求。

EU AI Act 合规

根据 EU AI Act Annex IV 要求，系统实现了以下合规检查：

资料来源：src/governance/policies/eu-ai-act.ts

策略配置示例

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

审计系统 (Audit)

审计链架构

审计系统采用默克尔树（Merkle Tree）结构确保审计记录的不可篡改性。

graph TD
    A[操作事件] --> B[生成审计记录]
    B --> C[计算哈希]
    C --> D[添加到叶节点]
    D --> E{批量达到阈值?}
    E -->|是| F[计算默克尔根]
    E -->|否| G[缓存待处理]
    F --> H[发布到审计链]
    H --> I[存储证明]

审计记录结构

默克尔证明

每个审计记录包含指向前一记录的哈希链接，形成链式结构：

interface AuditRecord {
  record: AuditData;
  prevHash: string;
  merkleProof?: MerkleProof;
}

资料来源：src/governance/audit-chain.ts

审计 Bundle

审计 Bundle 是批量打包的审计记录，支持高效的批量验证和存储：

interface AuditBundle {
  id: string;
  records: AuditRecord[];
  merkleRoot: string;
  timestamp: number;
  signature: string;
}

资料来源：src/governance/audit.ts

运行时治理 (Runtime)

运行时决策流程

运行时系统负责在操作执行期间进行实时监控和干预。

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[返回结果]

异常处理

运行时支持多种异常类型：

资料来源：src/governance/runtime.ts

空间治理 (Spatial)

概念定义

空间治理定义了 Agent 的操作边界和资源隔离域。

interface SpatialContext {
  namespace: string;      // 命名空间标识
  boundaries: Boundary[]; // 边界限制
  isolation: boolean;     // 是否隔离
}

边界类型

资料来源：src/governance/spatial.ts

审批流程 (Approval)

工作流状态机

关键操作需要人工审批，审批流程遵循状态机模式：

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]

审批配置

资料来源：src/governance/approval.ts

合规框架集成

EU AI Act 合规清单

根据 Annex IV 要求，MnemoPay SDK 实现了以下技术文档要求：

资料来源：compliance/eu-ai-act-annex-iv.md

Agent 信任证明 (AAIF)

系统支持 Agent 身份和行为的信任证明机制：

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

快速开始

初始化治理上下文

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
});

执行受治理的操作

const result = await ctx.execute('payment:charge', {
  amount: 50,
  currency: 'USD',
  recipient: 'agent-123'
});

// 审计记录自动生成
console.log(result.auditId); // 审计追踪ID

API 参考

GovernanceContext

资料来源：src/governance/index.ts

最佳实践

1. 宪章配置

• 遵循最小权限原则，仅授予必要权限
• 设置合理的预算上限和 TTL
• 定期审核和更新宪章版本

2. 审计策略

• 确保所有敏感操作都生成审计记录
• 定期导出和验证审计 Bundle
• 保留足够长度的审计历史（建议 365+ 天）

3. 合规检查

• 对高风险操作启用人工审批
• 定期运行 EU AI Act 合规检查
• 维护完整的信任证明链

Pitfall Log / 踩坑日志

项目：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