{
"canonical_name": "mnemopay/mnemopay-sdk",
"compilation_id": "pack_e3a880e9aec142e3a591f50051c59cb0",
"created_at": "2026-05-15T06:09:19.168081+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npm install @mnemopay/sdk` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npm install @mnemopay/sdk",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_b4be2a78e42843819cab1bf4c00bac72"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_cc7826a84c7d2d02e2e33477ea309cf2",
"canonical_name": "mnemopay/mnemopay-sdk",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/mnemopay/mnemopay-sdk",
"slug": "mnemopay-sdk",
"source_packet_id": "phit_4d003b454d5d45c992fc5d6d46ae3342",
"source_validation_id": "dval_f51821c637ca4c598b463bd39c40f528"
},
"merchandising": {
"best_for": "需要数据分析与投资研究能力，并使用 local_cli的用户",
"github_forks": 1,
"github_stars": 5,
"one_liner_en": "Trust & reputation layer for AI agents. Agent Credit Score (300-850) + Merkle-anchored ledger + behavioral finance + EWMA anomaly detection. Memory + payments + identity + fraud in one SDK. npm i @mnemopay/sdk",
"one_liner_zh": "Trust & reputation layer for AI agents. Agent Credit Score (300-850) + Merkle-anchored ledger + behavioral finance + EWMA anomaly detection. Memory + payments + identity + fraud in one SDK. npm i @mnemopay/sdk",
"primary_category": {
"category_id": "data-market-research",
"confidence": "high",
"name_en": "Data & Market Research",
"name_zh": "数据分析与投资研究",
"reason": "strong category phrase match from project identity and outcome"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "mnemopay-sdk",
"title_zh": "mnemopay-sdk 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Multi-agent Collaboration",
"label_zh": "多 Agent 协作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-multi-agent-collaboration",
"type": "core_capability"
},
{
"label_en": "Multi-role Workflow",
"label_zh": "多角色协作流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-multi-role-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_4d003b454d5d45c992fc5d6d46ae3342",
"page_model": {
"artifacts": {
"artifact_slug": "mnemopay-sdk",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npm install @mnemopay/sdk",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/mnemopay/mnemopay-sdk#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"多 Agent 协作",
"多角色协作流程",
"评测体系"
],
"eyebrow": "数据分析与投资研究",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要数据分析与投资研究能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Trust & reputation layer for AI agents. Agent Credit Score (300-850) + Merkle-anchored ledger + behavioral finance + EWMA anomaly detection. Memory + payments + identity + fraud in one SDK. npm i @mnemopay/sdk"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。",
"category": "安全/权限坑",
"evidence": [
"packet_text.keyword_scan | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | matched secret / private key / privacy / trading / finance keyword"
],
"severity": "high",
"suggested_check": "补敏感数据流、密钥存储和权限边界审查。",
"title": "涉及密钥、隐私或敏感领域",
"user_impact": "金融、交易、隐私和密钥场景必须比普通工具更保守。"
},
{
"body": "仓库名 `mnemopay-sdk` 与安装入口 `@mnemopay/sdk` 不完全一致。",
"category": "身份坑",
"evidence": [
"identity.distribution | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | repo=mnemopay-sdk; install=@mnemopay/sdk"
],
"severity": "medium",
"suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。",
"title": "仓库名和安装名不一致",
"user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 8 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 涉及密钥、隐私或敏感领域。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 3,
"forks": 1,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 5
},
"source_url": "https://github.com/mnemopay/mnemopay-sdk",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Trust & reputation layer for AI agents. Agent Credit Score (300-850) + Merkle-anchored ledger + behavioral finance + EWMA anomaly detection. Memory + payments + identity + fraud in one SDK. npm i @mnemopay/sdk",
"title": "mnemopay-sdk 能力包",
"trial_prompt": "# mnemopay-sdk - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mnemopay-sdk 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的数据分析与投资研究任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. getting-started：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. memory-system：内存与记忆系统。围绕“内存与记忆系统”模拟一次用户任务，不展示安装或运行结果。\n4. ledger-payments：账本与支付系统。围绕“账本与支付系统”模拟一次用户任务，不展示安装或运行结果。\n5. identity-auth：身份与认证系统。围绕“身份与认证系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. getting-started\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. memory-system\n输入：用户提供的“内存与记忆系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. ledger-payments\n输入：用户提供的“账本与支付系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. identity-auth\n输入：用户提供的“身份与认证系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / getting-started：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / quick-start：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / memory-system：Step 3 必须围绕“内存与记忆系统”形成一个小中间产物，并等待用户确认。\n- Step 4 / ledger-payments：Step 4 必须围绕“账本与支付系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / identity-auth：Step 5 必须围绕“身份与认证系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/mnemopay/mnemopay-sdk\n- https://github.com/mnemopay/mnemopay-sdk#readme\n- claude-plugin/skills/balance/SKILL.md\n- claude-plugin/skills/charge/SKILL.md\n- claude-plugin/skills/fico/SKILL.md\n- claude-plugin/skills/history/SKILL.md\n- claude-plugin/skills/recall/SKILL.md\n- claude-plugin/skills/remember/SKILL.md\n- claude-plugin/skills/settle/SKILL.md\n- claude-plugin/skills/shop/SKILL.md\n- integrations/openclaw/SKILL.md\n- README.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mnemopay-sdk 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_release: v0.9.0 — Autonomous Commerce + Universal Client（https://github.com/mnemopay/mnemopay-sdk/releases/tag/v0.9.0）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_release",
"source": "github",
"title": "v0.9.0 — Autonomous Commerce + Universal Client",
"url": "https://github.com/mnemopay/mnemopay-sdk/releases/tag/v0.9.0"
}
],
"status": "已收录 1 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "数据分析与投资研究",
"desc": "Trust & reputation layer for AI agents. Agent Credit Score (300-850) + Merkle-anchored ledger + behavioral finance + EWMA anomaly detection. Memory + payments + identity + fraud in one SDK. npm i @mnemopay/sdk",
"effort": "安装已验证",
"forks": 1,
"icon": "chart",
"name": "mnemopay-sdk 能力包",
"risk": "需复核",
"slug": "mnemopay-sdk",
"stars": 5,
"tags": [
"MCP 工具",
"知识库问答",
"多 Agent 协作",
"多角色协作流程",
"评测体系"
],
"thumb": "green",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/mnemopay/mnemopay-sdk 项目说明书\n\n生成时间：2026-05-15 05:38:18 UTC\n\n## 目录\n\n- [项目概述](#getting-started)\n- [快速开始](#quick-start)\n- [内存与记忆系统](#memory-system)\n- [账本与支付系统](#ledger-payments)\n- [身份与认证系统](#identity-auth)\n- [代理信用评分系统](#credit-score)\n- [行为金融引擎](#behavioral-finance)\n- [异常检测系统](#anomaly-detection)\n- [支付轨道](#payment-rails)\n- [治理与合规框架](#governance)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[快速开始](#quick-start), [内存与记忆系统](#memory-system), [代理信用评分系统](#credit-score)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n- [dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n- [site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)\n- [site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n- [site/calculator.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/calculator.html)\n- [integrations/python-hosted/README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/python-hosted/README.md)\n \n\n# 项目概述\n\n## 项目简介\n\nMnemoPay SDK 是一个专为 AI Agent（人工智能代理）设计的支付与记忆基础设施开发工具包。该项目由 Jeremiah Omiagbo 创建，采用 Apache 2.0 开源许可证，为开发者提供了将货币化能力、持久化记忆和身份验证集成到 AI 代理应用中的完整解决方案。资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\nMnemoPay 不仅仅是一个 Stripe 包装器，而是一个为代理原生构建的完整支付系统，支持 Stripe、Paystack 和 Lightning（加密货币）三种支付通道。资料来源：[site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)\n\n## 核心版本信息\n\n| 版本类型 | 版本号 | 说明 |\n|---------|--------|------|\n| 稳定版 | v1.5.0 | 通过 `latest` 标签分发 |\n| 预发布版 | v1.6.0-alpha | 当前 alpha 测试版本 |\n\n资料来源：[README.md:27](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 技术架构\n\nMnemoPay SDK 的架构采用分层模块化设计，集成了多个核心子系统。以下是整体架构示意图：\n\n```mermaid\ngraph TB\n subgraph 顶层\n G[GOVERNANCE
Charter · FiscalGate
Article 12 · MerkleAudit]\n end\n \n subgraph 核心功能层\n M[Memory
remember · recall
reinforce · forget]\n P[Payments
charge · settle
refund · dispute]\n I[Identity
KYA · tokens
perms · killswitch]\n end\n \n subgraph 高级功能层\n C[Agent Credit Score
300-850 评分
5组件评分体系]\n B[Behavioral Finance
前景理论
行为引导]\n A[Anomaly Detection
EWMA + 指纹识别]\n end\n \n G --> M\n G --> P\n G --> I\n I --> C\n C --> B\n B --> A\n```\n\n资料来源：[README.md:28-42](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 核心子系统详解\n\n### 记忆系统（Memory）\n\n记忆系统为 AI Agent 提供了持久化和检索信息的能力，支持以下核心操作：\n\n| 方法 | 功能描述 |\n|------|----------|\n| `remember()` | 存储新记忆内容 |\n| `recall()` | 检索相关记忆 |\n| `reinforce()` | 强化重要记忆 |\n| `forget()` | 删除指定记忆 |\n\n该系统支持命名空间隔离，允许按业务领域组织记忆数据。资料来源：[integrations/python-hosted/README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/python-hosted/README.md)\n\n### 支付系统（Payments）\n\n支付系统支持完整的交易生命周期管理：\n\n```mermaid\ngraph LR\n A[charge
扣款] --> B[escrow
资金托管]\n B --> C{人工审批}\n C -->|通过| D[settle
结算]\n C -->|拒绝| E[refund
退款]\n D --> F[(Ledger
账本记录)]\n E --> F\n```\n\n| 支付通道 | 支持地区 | 特色功能 |\n|---------|---------|---------|\n| Paystack | 非洲（NGN, GHS, ZAR, KES） | 23家尼日利亚银行预映射，HMAC-SHA512 安全验证 |\n| Stripe | 全球（USD, EUR, GBP） | 手动捕获实现真实托管，支持135+种货币 |\n| Lightning | 加密货币 | 闪电网络即时结算 |\n\n资料来源：[site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)\n\n### 身份系统（Identity）\n\n身份系统包含四个关键组件：\n\n- **KYA（Know Your Agent）**：代理身份验证\n- **Tokens**：代币管理机制\n- **Permissions**：权限控制系统\n- **Killswitch**：紧急终止开关\n\n### Agent 信用评分（Agent Credit Score）\n\nMnemoPay 引入了一套基于 300-850 分值范围的信用评分体系，参考了传统金融信用评分模型。该评分系统包含五个核心评估维度：\n\n1. 支付历史分析\n2. 交易行为模式\n3. 账户活跃度\n4. 风险指标评估\n5. 身份验证等级\n\n资料来源：[README.md:33](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n### 行为金融模块（Behavioral Finance）\n\n基于前景理论（Prospect Theory）设计，提供用户行为引导和激励优化功能。该模块帮助开发者构建更符合用户心理预期的交易体验。资料来源：[README.md:38](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n### 异常检测模块（Anomaly Detection）\n\n采用指数加权移动平均（EWMA）算法结合指纹识别技术，实时监控和识别可疑交易行为。资料来源：[README.md:39](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n### 治理系统（Governance）\n\n治理模块包含四个核心组件：\n\n| 组件 | 功能 |\n|------|------|\n| Charter | 代理行为宪章 |\n| FiscalGate | 财务门控机制 |\n| Article 12 | 第12条合规条款 |\n| MerkleAudit | 默克尔树审计 |\n\n该模块负责任务范围界定、预算执行和审计捆绑。资料来源：[README.md:29-30](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 开发工作流\n\n基于 MnemoPay SDK 构建应用的标准流程包含四个步骤：\n\n```mermaid\ngraph TD\n A[1. 安装
npm install @mnemopay/sdk] --> B[2. 初始化
MnemoPay.quick agent-id]\n B --> C[3. 交易操作
charge · settle · refund]\n C --> D[4. 规模扩展
自主购物 · 多代理商务 · 信用评分]\n```\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n\n## 中间件集成\n\nMnemoPay SDK 提供与主流 AI 框架的中间件集成：\n\n| 框架 | 导入路径 | 说明 |\n|------|---------|------|\n| OpenAI | `@mnemopay/sdk/middleware/openai` | OpenAI API 中间件 |\n| Anthropic | `@mnemopay/sdk/middleware/anthropic` | Claude API 中间件 |\n| LangGraph | `@mnemopay/sdk/langgraph` | LangGraph 工具集成 |\n\n资料来源：[README.md:11-17](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## Python SDK 功能\n\nPython 集成包 `mnemopay` 提供了完整的功能接口：\n\n### 主要方法\n\n| 方法 | 参数 | 返回值 |\n|------|------|--------|\n| `remember(content, namespace, tags, importance)` | 内容、命名空间、标签、重要性 | 记忆 ID |\n| `recall(query, namespace, limit, mode)` | 查询词、命名空间、限制数、模式 | 相关记忆列表 |\n| `reason(query, namespace, limit, mode)` | 查询词、命名空间、限制数、模式 | 推理结果 |\n| `charge(amount, reason)` | 金额、原因 | 交易 ID |\n| `settle(tx_id)` | 交易 ID | 结算状态 |\n| `usage_report()` | - | 使用量报告 |\n| `audit_events(limit)` | 限制数 | 审计事件列表 |\n\n资料来源：[integrations/python-hosted/README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/python-hosted/README.md)\n\n## 仪表板功能\n\nMnemoPay 提供了一个功能丰富的 Web 仪表板（`dashboard/index.html`），包含以下模块：\n\n| 模块 | 功能描述 |\n|------|----------|\n| 账户概览 | 钱包余额、信誉评分、记忆数量、交易计数 |\n| 交易历史 | 完整交易记录与状态追踪 |\n| 实时日志 | 系统运行日志与事件流 |\n| 记忆管理 | 记忆 CRUD 操作与搜索 |\n| GitHub 监控 | 追踪上游仓库状态与 PR |\n| 计量仪表 | LLM 调用限额、席位数量 |\n| 任务管理 | 任务状态与完成进度 |\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n\n## 套餐定价\n\n| 套餐 | 价格 | 特性 |\n|------|------|------|\n| Starter | 免费 | 基础 SDK、10个代理、Stripe/Paystack/Lightning、Agent 信用评分 |\n| Pro | $49/月 | Starter 全部 + 文件/SQLite 持久化、交易分析仪表板、Webhook 通知、地理位置信任档案 |\n\n交易手续费：Pro 套餐按已结算交易的 1.5% 收取额外费用。资料来源：[site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)\n\n## 商业模式与防欺诈\n\nMnemoPay 提供了一个 chargeback（chargeback 防止）计算器工具，帮助用户评估 AI 代理引发的退款争议的实际成本，以及加密签名收据能为 SaaS 平台节省的费用。资料来源：[site/calculator.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/calculator.html)\n\n## 相关资源\n\n| 资源类型 | 链接 |\n|---------|------|\n| npm 包 | [@mnemopay/sdk](https://www.npmjs.com/package/@mnemopay/sdk) |\n| GitHub 仓库 | github.com/mnemopay/mnemopay-sdk |\n| 官方网站 | mnemopay.com |\n| 商业联系 | info@getbizsuite.com |\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目概述](#getting-started), [内存与记忆系统](#memory-system), [账本与支付系统](#ledger-payments)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/01-quick-start.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/examples/01-quick-start.ts)\n- [examples/06-production.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/examples/06-production.ts)\n- [src/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/index.ts)\n- [src/client.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/client.ts)\n- [README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n- [site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n- [site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)\n \n\n# 快速开始\n\n## 概述\n\n「快速开始」是 MnemoPay SDK 为开发者提供的最短路径集成方案。通过极简的初始化流程，开发者可以在数分钟内为 AI Agent 集成记忆管理、支付处理、身份认证和信用评分四大核心能力。\n\n核心特性：\n- **零配置启动**：`MnemoPay.quick(\"agent-id\")` 一行代码完成全部初始化\n- **完整能力栈**：内存记忆、钱包交易、KYA 身份验证、Agent 信用评分\n- **多支付通道**：支持 Stripe、Paystack、Lightning 三种主流支付轨道\n- **中间件生态**：开箱即用的 OpenAI、Anthropic、LangGraph 集成\n\n资料来源：[README.md:1-20]()\n\n## 安装\n\n### 环境要求\n\n| 依赖项 | 最低版本 | 说明 |\n|--------|----------|------|\n| Node.js | 18.0+ | SDK 运行时环境 |\n| npm/pnpm/yarn | 最新版 | 包管理器 |\n| API Key | MnemoPay 平台获取 | 连接后端服务 |\n\n### 安装命令\n\n```bash\nnpm install @mnemopay/sdk\n# 或\npnpm add @mnemopay/sdk\n```\n\n资料来源：[site/index.legacy.html:50-55]()\n\n## 基础使用\n\n### 快速初始化\n\n使用 `MnemoPay.quick()` 方法实现零配置启动：\n\n```typescript\nimport { MnemoPay } from \"@mnemopay/sdk\";\n\n// 方式一：快速初始化（推荐）\nconst mnemopay = MnemoPay.quick(\"my-agent-id\");\n\n// 方式二：显式配置\nconst mnemopay = MnemoPay.quick(\"my-agent-id\", {\n apiKey: \"mnemo_live_sk_xxxx\",\n environment: \"production\"\n});\n```\n\n`quick()` 方法自动完成以下初始化：\n1. 创建 Agent 身份标识\n2. 初始化内存存储（remember/recall）\n3. 配置钱包和支付通道\n4. 建立与管理平台的连接\n\n资料来源：[README.md:55-70](), [site/index.legacy.html:56-60]()\n\n### 核心 API 方法\n\n#### 内存管理\n\n| 方法 | 功能 | 返回值 |\n|------|------|--------|\n| `remember(key, value)` | 存储记忆 | `Promise` |\n| `recall(query)` | 检索记忆 | `Promise` |\n| `reinforce(memoryId)` | 强化记忆权重 | `Promise` |\n| `forget(memoryId)` | 删除记忆 | `Promise` |\n\n```typescript\n// 存储用户偏好\nawait mnemopay.remember(\"user_pref\", {\n name: \"张三\",\n tier: \"premium\"\n});\n\n// 检索相关记忆\nconst memories = await mnemopay.recall(\"用户 偏好 premium\");\n```\n\n#### 支付交易\n\n| 方法 | 功能 | 状态 |\n|------|------|------|\n| `charge(amount, reason)` | 请求收款 | 资金进入托管 |\n| `settle(transactionId)` | 确认结算 | 资金释放给 Agent |\n| `refund(transactionId)` | 退款 | 资金退回用户 |\n\n```typescript\n// 发起收款\nconst tx = await mnemopay.charge(25.00, \"API调用费用\");\nconsole.log(`交易 ID: ${tx.id}`);\n\n// 结算交易\nawait mnemopay.settle(tx.id);\n\n// 退款\nawait mnemopay.refund(tx.id);\n```\n\n资料来源：[site/index.legacy.html:62-70]()\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[安装 SDK] --> B[快速初始化]\n B --> C[Agent 获取身份]\n C --> D{选择操作}\n \n D --> E[内存管理]\n D --> F[支付交易]\n D --> G[身份验证]\n D --> H[信用查询]\n \n E --> E1[remember/recall]\n F --> F1[charge/settle/refund]\n G --> G1[KYA 验证]\n H --> H1[信用评分查询]\n \n F1 -->|资金托管| I[Escrow]\n I --> J{人类审批}\n J -->|批准| K[settle]\n J -->|拒绝| L[refund]\n```\n\n### 支付流程详解\n\n1. **Charge（收款请求）**：Agent 调用 `charge()` 后，资金进入第三方托管\n2. **Escrow（资金托管）**：资金暂存于 Stripe/Paystack/Lightning，直至人工审批\n3. **Settle（确认结算）**：人工审核通过后，`settle()` 将资金释放给 Agent\n4. **Refund（退款处理）**：交易被拒绝时调用，资金退回用户\n\n资料来源：[site/index.legacy.html:63-68](), [README.md:65-72]()\n\n## 中间件集成\n\n### OpenAI 中间件\n\n```typescript\nimport { mnemoPayMiddleware } from \"@mnemopay/sdk/middleware/openai\";\n```\n\n将 MnemoPay 支付能力无缝集成到 OpenAI 的 Agent 框架中。\n\n### Anthropic 中间件\n\n```typescript\nimport { mnemoPayMiddleware } from \"@mnemopay/sdk/middleware/anthropic\";\n```\n\n支持 Anthropic Claude 模型的支付回调集成。\n\n### LangGraph 工具集成\n\n```typescript\nimport { mnemoPayTools } from \"@mnemopay/sdk/langgraph\";\n```\n\n提供 LangGraph 可调用的支付工具节点。\n\n资料来源：[README.md:35-45]()\n\n## 生产环境配置\n\n### 生产模式初始化\n\n```typescript\nimport { MnemoPay } from \"@mnemopay/sdk\";\n\nconst mnemopay = MnemoPay.quick(\"production-agent\", {\n apiKey: process.env.MNEMO_API_KEY,\n environment: \"production\",\n persistence: \"sqlite\", // 数据持久化\n webhookUrl: \"https://yourapp.com/webhooks/mnemopay\"\n});\n```\n\n### 配置选项\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `apiKey` | `string` | 环境变量 | MnemoPay API 密钥 |\n| `environment` | `\"development\" \\| \"production\"` | `\"development\"` | 运行环境 |\n| `persistence` | `\"memory\" \\| \"file\" \\| \"sqlite\"` | `\"memory\"` | 数据存储方式 |\n| `webhookUrl` | `string` | `null` | Webhook 回调地址 |\n\n### 生产检查清单\n\n- [ ] 使用正式环境 API Key\n- [ ] 配置 Webhook 端点\n- [ ] 选择合适的持久化方案（生产环境推荐 SQLite）\n- [ ] 设置支付通道（Stripe/Paystack/Lightning）\n- [ ] 配置 KYA（Know Your Agent）验证流程\n\n资料来源：[examples/06-production.ts](), [site/index.html](), [site/index.legacy.html]()\n\n## 架构概览\n\n```mermaid\ngraph TB\n subgraph \"MnemoPay SDK v1.6.0\"\n A[MnemoPay.quick] --> B[Client]\n B --> C[Memory 模块]\n B --> D[Payments 模块]\n B --> E[Identity 模块]\n B --> F[Credit Score 模块]\n end\n \n C --> G[(本地存储)]\n D --> H[Stripe]\n D --> I[Paystack]\n D --> J[Lightning]\n E --> K[Token 验证]\n F --> L[行为分析]\n \n M[OpenAI 中间件] --> B\n N[Anthropic 中间件] --> B\n O[LangGraph 工具] --> B\n```\n\n### 模块职责\n\n| 模块 | 核心功能 | API |\n|------|----------|-----|\n| Memory | 记忆存储与检索 | `remember`, `recall`, `reinforce`, `forget` |\n| Payments | 支付交易处理 | `charge`, `settle`, `refund`, `dispute` |\n| Identity | Agent 身份验证 | KYA、Token、Permissions |\n| Credit Score | 信用评分系统 | 300-850 分信用评估 |\n\n资料来源：[README.md:15-45]()\n\n## 错误处理\n\n### 常见错误\n\n| 错误码 | 说明 | 解决方案 |\n|--------|------|----------|\n| `AUTH_FAILED` | API Key 无效 | 检查并更新 API Key |\n| `INSUFFICIENT_FUNDS` | 余额不足 | 确保账户有足够资金 |\n| `TRANSACTION_NOT_FOUND` | 交易不存在 | 检查交易 ID |\n| `AGENT_NOT_VERIFIED` | Agent 未验证 | 完成 KYA 流程 |\n\n### 错误处理示例\n\n```typescript\ntry {\n const tx = await mnemopay.charge(100, \"服务费\");\n} catch (error) {\n if (error.code === \"AUTH_FAILED\") {\n console.error(\"请检查 API Key 配置\");\n } else if (error.code === \"AGENT_NOT_VERIFIED\") {\n console.error(\"请先完成 Agent 身份验证\");\n }\n}\n```\n\n## 下一步\n\n| 资源 | 说明 |\n|------|------|\n| [完整 API 文档]() | 详细的 SDK API 参考 |\n| [支付集成指南]() | Stripe/Paystack/Lightning 配置 |\n| [记忆系统详解]() | 高级记忆管理功能 |\n| [Agent 信用评分]() | 信用评分机制说明 |\n| [Dashboard 使用指南]() | 管理平台功能介绍 |\n\n---\n\n**版本信息**：当前版本 v1.6.0-alpha，`latest` 稳定版为 v1.5.0\n\n资料来源：[README.md:10-12]()\n\n---\n\n\n\n## 内存与记忆系统\n\n### 相关页面\n\n相关主题：[项目概述](#getting-started), [异常检测系统](#anomaly-detection), [治理与合规框架](#governance)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/recall/engine.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/engine.ts)\n- [src/recall/entities.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/entities.ts)\n- [src/recall/graph.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/graph.ts)\n- [src/recall/hyde.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/hyde.ts)\n- [src/recall/observations.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/observations.ts)\n- [src/recall/persistence/memory.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/persistence/memory.ts)\n- [src/recall/persistence/neon.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/persistence/neon.ts)\n- [src/recall/persistence/sqlite.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/persistence/sqlite.ts)\n- [src/integrity.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/integrity.ts)\n- [src/identity/bundle.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity/bundle.ts)\n \n\n# 内存与记忆系统\n\n## 概述\n\nMnemoPay SDK 的内存与记忆系统是整个 SDK 的核心模块，负责为 AI Agent 提供持久化记忆能力。该系统使 Agent 能够跨会话保持上下文，实现真正的连续性和个性化交互。\n\n核心功能包括：\n\n- **语义记忆存储**：通过 `remember` 方法存储记忆，支持重要度评分和标签系统\n- **混合检索引擎**：`recall` 方法支持语义搜索和混合检索模式\n- **知识图谱**：基于实体和关系构建知识网络，支持图结构查询\n- **观察点再生**：自动更新实体关联的观察点内容\n- **行为强化**：基于交互结果自动调整记忆权重\n- **完整性校验**：使用 Merkle 树结构确保记忆数据不可篡改\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n---\n\n## 系统架构\n\n### 模块分层\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ SDK 入口层 │\n│ MnemoPay.quick() / MnemoPay() │\n├─────────────────────────────────────────────────────────────┤\n│ 核心 API 层 │\n│ remember | recall | reinforce | forget │\n├──────────────┬──────────────┬───────────────┬────────────────┤\n│ 检索引擎 │ 实体管理 │ 知识图谱 │ 观察点系统 │\n│ recall/ │ recall/ │ recall/ │ recall/ │\n│ engine.ts │ entities.ts │ graph.ts │ observations │\n├──────────────┴──────────────┴───────────────┴────────────────┤\n│ 持久化适配层 │\n│ memory.ts | sqlite.ts | neon.ts │\n├─────────────────────────────────────────────────────────────┤\n│ 完整性校验层 │\n│ integrity.ts │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 记忆数据结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 记忆唯一标识符 |\n| `content` | string | 记忆内容 |\n| `importance` | number | 重要度评分 (0-1) |\n| `tags` | string[] | 标签数组 |\n| `factType` | string | 事实类型 (fact/opinion) |\n| `entityIds` | string[] | 关联实体ID |\n| `createdAt` | number | 创建时间戳 |\n| `updatedAt` | number | 更新时间戳 |\n\n资料来源：[src/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/index.ts)\n\n---\n\n## 核心 API\n\n### 记忆存储：remember()\n\n`remember()` 方法用于存储新的记忆条目。\n\n```typescript\nconst memory = await agent.remember({\n content: \"用户偏好深色主题\",\n tags: [\"preference\", \"ui\"],\n importance: 0.8,\n factType: \"fact\"\n});\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `content` | string | 是 | - | 记忆内容 |\n| `namespace` | string | 否 | \"default\" | 命名空间隔离 |\n| `tags` | string[] | 否 | [] | 标签数组 |\n| `importance` | number | 否 | 0.7 | 重要度 (0-1) |\n| `factType` | string | 否 | \"fact\" | 事实类型 |\n\n**副作用：**\n\n- 自动触发观点强化（针对 `factType: \"opinion\"`）\n- 触发关联实体的观察点再生\n- 写入持久化存储\n- 触发 `memory:stored` 事件\n\n资料来源：[integrations/openclaw/SKILL.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/openclaw/SKILL.md)\n\n### 记忆检索：recall()\n\n`recall()` 方法支持语义检索和混合模式查询。\n\n```typescript\nconst results = await agent.recall({\n query: \"用户的支付偏好\",\n namespace: \"default\",\n limit: 8,\n mode: \"hybrid\"\n});\n```\n\n**检索模式：**\n\n| 模式 | 说明 |\n|------|------|\n| `semantic` | 纯语义向量检索 |\n| `keyword` | 关键词精确匹配 |\n| `hybrid` | 语义+关键词混合检索 |\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `query` | string | 是 | - | 查询文本 |\n| `namespace` | string | 否 | \"default\" | 命名空间 |\n| `limit` | number | 否 | 8 | 返回结果数量 |\n| `mode` | string | 否 | \"hybrid\" | 检索模式 |\n\n资料来源：[integrations/python-hosted/README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/python-hosted/README.md)\n\n### 记忆强化：reinforce()\n\n增强记忆的重要度评分，用于正向反馈循环。\n\n```typescript\nawait agent.reinforce(memoryId, {\n boost: 0.1 // 增量范围: 0.01 - 0.5\n});\n```\n\n**使用场景：**\n\n- 记忆引导了成功的决策\n- 用户确认了建议的价值\n- 交互产生了正面结果\n\n资料来源：[integrations/openclaw/SKILL.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/openclaw/SKILL.md)\n\n### 记忆遗忘：forget()\n\n永久删除指定记忆。\n\n```typescript\nawait agent.forget(memoryId);\n```\n\n**使用场景：**\n\n- 记忆内容已过期\n- 用户请求删除隐私数据\n- 记忆信息不再准确\n\n### 记忆整合：consolidate()\n\n清理低于衰减阈值的过期记忆，保持存储高效。\n\n```typescript\nawait agent.consolidate({\n decayThreshold: 0.2\n});\n```\n\n---\n\n## 检索引擎\n\n### 混合检索策略\n\n检索引擎采用多阶段检索流程：\n\n```mermaid\ngraph TD\n A[用户查询] --> B[查询预处理]\n B --> C{检索模式}\n C -->|semantic| D[向量相似度检索]\n C -->|keyword| E[BM25排序]\n C -->|hybrid| F[并行双路检索]\n F --> G[倒数排名融合]\n D --> G\n E --> G\n G --> H[结果重排序]\n H --> I[Top-K 结果]\n I --> J[相关性过滤]\n J --> K[返回记忆列表]\n```\n\n### HyDE 生成增强\n\nHyDE (Hypothetical Document Embeddings) 技术用于提升检索质量：\n\n1. 使用语言模型生成假设性答案\n2. 将假设性答案向量化\n3. 使用假设向量检索相关记忆\n4. 融合假设检索与直接检索结果\n\n```typescript\n// hyde.ts 核心逻辑\nconst hypotheticalDoc = await generateHypotheticalDoc(query);\nconst hypotheticalEmbedding = await embed(hypotheticalDoc);\nconst hydeResults = await vectorSearch(hypotheticalEmbedding);\n```\n\n### 查询扩展\n\n引擎支持自动查询扩展，包括：\n\n- 同义词替换\n- 上下文窗口扩展\n- 时间敏感查询优化\n\n---\n\n## 知识图谱\n\n### 图结构\n\n知识图谱由实体和边组成：\n\n```mermaid\ngraph LR\n A[实体: 用户] -->|关联| B[记忆: 偏好设置]\n A -->|拥有| C[实体: 支付方式]\n B -->|触发| D[记忆: 购买历史]\n C -->|使用| E[记忆: 交易记录]\n```\n\n### 图操作 API\n\n```typescript\n// 获取命名空间的图结构\nconst graph = await agent.graph({\n namespace: \"default\",\n limit: 200\n});\n\n// 图统计信息\nconsole.log(graph.stats);\n// { entities: 42, edges: 128, memories: 256 }\n```\n\n### 实体管理\n\n实体是知识图谱的节点，具有以下属性：\n\n| 属性 | 说明 |\n|------|------|\n| `id` | 实体唯一标识 |\n| `name` | 实体名称 |\n| `type` | 实体类型 |\n| `observations` | 观察点列表 |\n| `memoryCount` | 关联记忆数 |\n\n### 观察点系统\n\n观察点是实体的语义摘要，自动从关联记忆中生成：\n\n```typescript\ninterface Observation {\n id: string;\n entityId: string;\n content: string; // 观察点摘要\n sourceMemoryIds: string[];\n confidence: number;\n updatedAt: number;\n}\n```\n\n**观察点再生流程：**\n\n1. 新记忆存储时，识别关联实体\n2. 异步触发观察点再生任务\n3. 聚合实体相关记忆生成新摘要\n4. 更新观察点内容\n\n资料来源：[src/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/index.ts)\n\n---\n\n## 持久化层\n\n### 存储适配器\n\n系统支持多种存储后端：\n\n| 适配器 | 适用场景 | 特点 |\n|--------|----------|------|\n| `memory.ts` | 开发/测试 | 内存存储，快速迭代 |\n| `sqlite.ts` | 单机部署 | 本地持久化，轻量 |\n| `neon.ts` | 生产环境 | Postgres Serverless，分布式 |\n\n### 命名空间隔离\n\n```typescript\n// 切换命名空间\nawait agent.namespace(\"user-123\");\n\n// 导出命名空间数据\nconst export = await agent.export_namespace(\"user-123\");\n\n// 删除命名空间\nawait agent.delete_namespace(\"user-123\");\n```\n\n### 数据持久化流程\n\n```mermaid\ngraph TD\n A[记忆写入请求] --> B{存储适配器}\n B -->|开发模式| C[内存存储]\n B -->|单机部署| D[SQLite 写入]\n B -->|生产环境| E[Neon Postgres]\n C --> F[Merkle 树更新]\n D --> F\n E --> F\n F --> G[根哈希保存]\n G --> H[完整性证明生成]\n```\n\n---\n\n## 完整性校验\n\n### Merkle 内存完整性\n\n系统使用 Merkle 树结构确保记忆数据不可篡改：\n\n```typescript\ninterface MerkleProof {\n memoryId: string;\n value: string;\n path: string[]; // 兄弟节点哈希\n position: 'left' | 'right';\n rootHash: string;\n}\n```\n\n### 审计事件\n\n所有记忆操作都会记录审计日志：\n\n```typescript\nawait agent.audit(\"memory:stored\", {\n id: mem.id,\n tags: safeTags,\n importance: mem.importance,\n factType: mem.factType\n});\n```\n\n**可审计事件类型：**\n\n| 事件 | 说明 |\n|------|------|\n| `memory:stored` | 记忆存储 |\n| `memory:retrieved` | 记忆检索 |\n| `memory:updated` | 记忆更新 |\n| `memory:deleted` | 记忆删除 |\n| `memory:reinforced` | 记忆强化 |\n\n资料来源：[src/integrity.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/integrity.ts)\n\n---\n\n## 行为经济学集成\n\n### 观点强化机制\n\n对于 `factType: \"opinion\"` 的记忆，系统应用行为经济学中的观点强化机制：\n\n```typescript\nimport { applyOpinionReinforcement } from \"./behavioral.js\";\n\nawait applyOpinionReinforcement({\n newMemory: mem,\n memories: this.memories,\n recallEngine: this.recallEngine\n});\n```\n\n### 自适应学习\n\n系统采用自适应学习策略：\n\n1. **记忆衰减**：长时间未访问的记忆重要度逐渐降低\n2. **访问频率加权**：频繁访问的记忆获得权重提升\n3. **关联强度**：实体关联越多的记忆越难被遗忘\n\n---\n\n## 仪表盘可视化\n\nMnemoPay 仪表盘提供记忆系统的可视化监控：\n\n```mermaid\ngraph TD\n A[仪表盘] --> B[记忆列表]\n A --> C[推理追踪]\n A --> D[知识图谱]\n A --> E[交易历史]\n B -->|显示| F[记忆ID]\n B -->|显示| G[重要度分数]\n B -->|显示| H[记忆内容]\n C -->|显示| I[推理步骤]\n C -->|显示| J[置信度]\n C -->|显示| K[实体引用]\n D -->|显示| L[实体节点]\n D -->|显示| M[边关系]\n```\n\n### 记忆列表显示\n\n```\n┌─────────────────────────────────────────────────────┐\n│ ID │ Score │ Memory Content │\n├─────────────┼───────┼───────────────────────────────┤\n│ a1b2c3d4... │ 0.85 │ 用户偏好深色主题 │\n│ e5f6g7h8... │ 0.72 │ 经常在周末进行购物 │\n│ i9j0k1l2... │ 0.65 │ 倾向于使用信用卡支付 │\n└─────────────┴───────┴───────────────────────────────┘\n```\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n\n---\n\n## 使用示例\n\n### Python Hosted SDK\n\n```python\nfrom mnemopay import Client\n\nclient = Client(api_key=\"your-api-key\")\n\n# 存储记忆\nclient.remember(\n content=\"用户喜欢在周五晚上购物\",\n namespace=\"default\",\n tags=[\"preference\", \"shopping\"],\n importance=0.8\n)\n\n# 检索记忆\nresults = client.recall(\n query=\"购物偏好\",\n namespace=\"default\",\n limit=8,\n mode=\"hybrid\"\n)\n\n# 获取知识图谱\ngraph = client.graph(namespace=\"default\", limit=200)\nprint(f\"实体数: {graph.stats['entities']}\")\n```\n\n### JavaScript SDK\n\n```typescript\nimport MnemoPay from \"@mnemopay/sdk\";\n\nconst agent = await MnemoPay.quick(\"agent-001\");\n\n// 存储记忆\nawait agent.remember({\n content: \"用户偏好深色主题\",\n tags: [\"preference\", \"ui\"],\n importance: 0.8\n});\n\n// 检索记忆\nconst memories = await agent.recall({\n query: \"用户界面偏好\",\n limit: 8\n});\n\n// 获取图谱\nconst graph = await agent.graph();\n```\n\n---\n\n## 配置选项\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `maxMemories` | number | 10000 | 最大记忆存储量 |\n| `decayRate` | number | 0.01 | 记忆衰减率 |\n| `consolidationThreshold` | number | 0.1 | 整合阈值 |\n| `storageBackend` | string | \"memory\" | 存储后端 |\n| `embeddingModel` | string | \"default\" | 向量模型 |\n| `maxRecallResults` | number | 8 | 最大检索结果 |\n\n---\n\n## 性能指标\n\n### LongMemEval 基准\n\nMnemoPay 在 LongMemEval 基准测试中达到：\n\n| 版本 | 分数 | 说明 |\n|------|------|------|\n| v1.3.0 | 66.9% | 多会话检索基线 |\n| v1.4.0 | 77.2% | 优化后的检索引擎 |\n\n资料来源：[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)\n\n### 压力测试\n\n系统已通过 100 万次操作的连续压力测试，验证了内存管理的稳定性和数据完整性。\n\n---\n\n## 最佳实践\n\n1. **合理设置重要度**：根据记忆的实际价值设置 0-1 之间的评分\n2. **使用标签系统**：通过标签组织记忆，便于后续检索\n3. **定期整合**：使用 `consolidate()` 清理过期记忆\n4. **命名空间隔离**：为不同用户或场景使用独立命名空间\n5. **监控使用量**：通过 `usage_report()` 监控记忆存储和 API 调用\n6. **启用完整性校验**：生产环境务必启用 Merkle 完整性验证\n\n---\n\n\n\n## 账本与支付系统\n\n### 相关页面\n\n相关主题：[快速开始](#quick-start), [支付轨道](#payment-rails), [身份与认证系统](#identity-auth)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp/server.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/mcp/server.ts)\n- [README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n- [dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n- [site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n- [site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)\n \n\n# 账本与支付系统\n\n## 概述\n\nMnemoPay 的账本与支付系统是专为 AI Agent 设计的金融基础设施层，提供从充值、托管到结算、退款的全链路资金管理能力。该系统并非简单的支付网关封装，而是一套完整的双账本（Double-Entry Ledger）机制，确保每一笔资金流向都有精确的借方和贷方记录。\n\n核心价值主张：\n\n- 支持 Stripe（全球）、Paystack（非洲）、Lightning（BTC 微支付）三条真实支付通道\n- 统一的 API 接口，屏蔽底层通道差异\n- 内置交易托管（Escrow）机制，人类审批后才释放资金\n- 交易事件 Webhook 推送，支持 HMAC-SHA256 签名验签\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n---\n\n## 架构设计\n\n### 支付系统分层\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ 业务接口层 │\n│ charge() / settle() / refund() / transfer() │\n├─────────────────────────────────────────────────────────┤\n│ 支付通道层 │\n│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │\n│ │ Stripe │ │ Paystack │ │ Lightning│ │\n│ └──────────┘ └──────────┘ └──────────┘ │\n├─────────────────────────────────────────────────────────┤\n│ 账本核心层 │\n│ Double-Entry Ledger │\n├─────────────────────────────────────────────────────────┤\n│ 存储层 │\n│ SQLite / Webhook Events │\n└─────────────────────────────────────────────────────────┘\n```\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n\n### 托管与结算流程\n\n```\ngraph TD\n A[Agent 调用 charge()] --> B[资金进入 Escrow 托管]\n B --> C{人工审批}\n C -->|批准| D[调用 settle() 释放资金]\n C -->|拒绝| E[调用 refund() 原路退回]\n D --> F[商户收到结算款项]\n E --> G[资金退回买家]\n```\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n\n---\n\n## 支付通道\n\n### 通道对比\n\n| 通道 | 覆盖地区 | 支持货币 | 特色功能 |\n|------|----------|----------|----------|\n| **Stripe** | 全球 | USD, EUR, GBP 等 135+ 货币 | 手动捕获（Manual Capture）实现真正的 Escrow |\n| **Paystack** | 非洲 | NGN, GHS, ZAR, KES | 23 家尼日利亚银行预映射，HMAC-SHA512 安全验证 |\n| **Lightning** | 全球 | BTC | 微支付场景，实时到账 |\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n\n### Stripe 集成\n\nStripe 提供全球覆盖的信用卡支付能力。MnemoPay 使用 PaymentIntents API 实现手动捕获模式，确保资金在托管状态下等待授权：\n\n```typescript\n// 核心支付操作\ncharge() // 收款并进入托管\nsettle() // 释放托管资金\nrefund() // 退款回原支付渠道\n```\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n\n### Paystack 集成\n\n针对非洲市场优化，支持多种本地支付方式：\n\n- Checkout（网页结账）\n- 保存的卡片（Saved Cards）\n- 银行转账（Bank Transfer）\n- Webhook 验证（HMAC-SHA512）\n\n```typescript\n// Paystack 转账事件\ntransfer.success // 转账完成\ntransfer.failed // 转账失败\n```\n\n资料来源：[src/mcp/server.ts:1-50](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/mcp/server.ts)\n\n---\n\n## Webhook 事件系统\n\n### 事件类型\n\n| 事件名称 | 触发时机 | 描述 |\n|----------|----------|------|\n| `charge.success` | 扣款成功进入托管 | 交易已被接受并锁定在 Escrow |\n| `charge.failed` | 扣款失败 | 因名誉分上限、欺诈检测、授权违规等原因被拒绝 |\n| `settle` | 释放托管资金 | Escrow 已释放，资金已划转 |\n| `refund` | 交易回滚 | 资金已原路退回 |\n| `transfer.success` | Paystack 提现完成 | 资金已到达目标账户 |\n| `transfer.failed` | Paystack 提现失败 | 提现操作异常 |\n| `*` | 通配符订阅 | 订阅所有事件类型 |\n\n资料来源：[src/mcp/server.ts:1-50](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/mcp/server.ts)\n\n### 签名验证机制\n\n每条 Webhook POST 请求都携带 `X-MnemoPay-Signature` 头，格式为：\n\n```\nX-MnemoPay-Signature: t=,v1=\n```\n\n其中 `v1` 的计算方式：\n\n```\nv1 = HMAC-SHA256(secret, timestamp + '.' + request_body)\n```\n\n**安全建议**：验证 `now - t < 300秒`，防止重放攻击。签名密钥在调用 `webhook_register` 时返回一次，务必在调用返回前持久化存储。\n\n```typescript\n// Webhook 验证伪代码\nconst isValid = hmacSha256(secret, `${timestamp}.${body}`) === signature;\nconst isRecent = Date.now() - timestamp < 300000; // 5分钟内\nif (!isValid || !isRecent) reject();\n```\n\n资料来源：[src/mcp/server.ts:1-50](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/mcp/server.ts)\n\n---\n\n## 双账本机制\n\n### 核心概念\n\nMnemoPay 采用双记账（Double-Entry）原则，每笔交易都产生两条对应的账目记录：\n\n- **借方条目（Debit）**：资金流出账户\n- **贷方条目（Credit）**：资金流入账户\n\n这确保了账目平衡，任何时刻资产总计等于负债总计。\n\n### 交易状态流转\n\n```\ngraph LR\n A[Created] --> B[Held - Escrow中]\n B -->|Approve| C[Settled - 已结算]\n B -->|Reject| D[Refunded - 已退款]\n C --> E[Completed]\n D --> E\n```\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n\n---\n\n## 自助购物与结账执行\n\n### 购物流程\n\nMnemoPay 支持 AI Agent 自动执行购物操作，所有购买都必须经过 Escrow 托管：\n\n1. Agent 搜索商品、比较价格\n2. 选择最优方案，发起购买请求\n3. 资金进入托管状态\n4. **人类审批**后才真正扣款\n5. 禁止 Agent 未经授权自行消费\n\n```typescript\n// 购物相关 API\nshop_checkout // 浏览器自动化结账\n```\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n\n### 结账策略\n\n| 策略 | 适用平台 | 说明 |\n|------|----------|------|\n| Shopify 策略 | Shopify 店铺 | 原生检测，优化选择器 |\n| 通用策略 | 其他平台 | 回退到通用结账启发式算法 |\n\n资料来源：[src/mcp/server.ts:1-50](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/mcp/server.ts)\n\n---\n\n## 仪表盘监控\n\n### 交易概览\n\nMnemoPay Dashboard 提供实时交易监控能力：\n\n| 监控指标 | 说明 |\n|----------|------|\n| Wallet 余额 | 当前可用余额 |\n| Reputation 信誉分 | Agent 信用评分（0-1） |\n| Memories Count | 记忆条目数 |\n| Transactions Count | 累计交易数 |\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n\n### 任务与进度追踪\n\n每个支付任务都包含状态标记：\n\n```typescript\n{\n id: string,\n done: boolean, // true = Complete, false = In Progress\n // ...\n}\n```\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n\n---\n\n## SDK 快速开始\n\n### 安装\n\n```bash\nnpm install @mnemopay/sdk\n```\n\n### 初始化\n\n```typescript\nimport { MnemoPay } from \"@mnemopay/sdk\";\n\nconst mnemo = MnemoPay.quick(\"agent-id\");\n// 自动分配：记忆存储 + 钱包 + 身份\n```\n\n### 基础支付操作\n\n```typescript\n// 收款（进入托管）\nawait mnemo.charge({ amount: 1000, currency: \"USD\" });\n\n// 释放托管（需人工授权）\nawait mnemo.settle({ transactionId: \"tx_xxx\" });\n\n// 退款\nawait mnemo.refund({ transactionId: \"tx_xxx\" });\n```\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n\n---\n\n## 与传统支付方案对比\n\n| 特性 | MnemoPay | 传统 Stripe 封装 | Payman |\n|------|----------|------------------|--------|\n| 支付通道 | 多通道统一 API | 单通道 | 单一 |\n| Escrow 托管 | 原生支持 | 需手动实现 | 不支持 |\n| 双账本 | 内置 | 需额外开发 | 不支持 |\n| AI Agent 身份 | Ed25519 | 无 | 无 |\n| Agent 信用评分 | 300-850 分 | 无 | 无 |\n| 行为异常检测 | EWMA + 指纹 | 无 | 无 |\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n\n---\n\n## 总结\n\nMnemoPay 的账本与支付系统为 AI Agent 提供了一套完整、合规、可审计的金融操作基础设施：\n\n- **真实性**：接入 Stripe、Paystack、Lightning 三大真实支付通道\n- **安全性**：HMAC-SHA256 签名验签、300秒重放保护、名誉分风控\n- **合规性**：双账本确保每笔资金有据可查，Escrow 托管保障资金安全\n- **可观测性**：完整的事件 Webhook + Dashboard 实时监控\n\n通过这套系统，AI Agent 可以在受控环境下安全地处理货币事务，同时保留人类最终决策权。\n\n---\n\n\n\n## 身份与认证系统\n\n### 相关页面\n\n相关主题：[账本与支付系统](#ledger-payments), [治理与合规框架](#governance)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/identity.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity.ts)\n- [src/identity/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity/index.ts)\n- [src/identity/did.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity/did.ts)\n- [src/identity/wallet.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity/wallet.ts)\n- [src/identity/bundle.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity/bundle.ts)\n- [src/network.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/network.ts)\n \n\n# 身份与认证系统\n\nMnemoPay SDK 的身份与认证系统是整个平台的核心基础设施，为 AI Agent 提供完整的身份标识、钱包管理、权限控制和安全验证机制。该系统基于去中心化身份（DID）理念构建，同时集成了传统的 KYC/KYB 流程以满足监管合规要求。\n\n## 系统架构概览\n\n身份与认证系统采用分层架构设计，各层之间职责明确、解耦清晰。\n\n```mermaid\ngraph TD\n subgraph 身份层\n DID[DID 标识符]\n BUNDLE[身份凭证包]\n KYA[Know Your Agent]\n end\n \n subgraph 钱包层\n WALLET[钱包余额]\n TOKEN[Token 管理]\n REPUTATION[信誉评分]\n end\n \n subgraph 权限层\n PERMS[权限控制]\n KILLSWITCH[熔断机制]\n end\n \n subgraph 网络层\n NETWORK[网络通信]\n VERIFY[身份验证]\n end\n \n DID --> BUNDLE\n BUNDLE --> WALLET\n BUNDLE --> TOKEN\n WALLET --> REPUTATION\n BUNDLE --> PERMS\n PERMS --> KILLSWITCH\n NETWORK --> VERIFY\n VERIFY --> DID\n```\n\n根据架构文档，MnemoPay SDK 的身份系统包含以下核心组件：\n\n| 组件 | 功能描述 | 层级归属 |\n|------|---------|----------|\n| DID | 去中心化身份标识符 | 身份层 |\n| KYA | Know Your Agent 身份核验 | 身份层 |\n| Bundle | 身份凭证包管理 | 身份层 |\n| Wallet | 钱包余额与交易 | 钱包层 |\n| Token | 代币化管理 | 钱包层 |\n| Permissions | 权限访问控制 | 权限层 |\n| KillSwitch | 熔断/紧急停止 | 权限层 |\n| Reputation | 信誉评分系统 | 钱包层 |\n\n资料来源：[README.md:30-50]()\n\n## 核心模块详解\n\n### 身份标识模块（Identity）\n\n身份标识模块是整个认证系统的根基，为每个 Agent 生成唯一的去中心化身份。\n\n#### DID 去中心化标识符\n\nDID（Decentralized Identifier）是 MnemoPay 系统中 Agent 的唯一身份标识。DID 标识符遵循 W3C DID Core 规范，支持自主管理、跨平台互操作。\n\n根据架构设计，DID 模块负责：\n- 生成符合规范的 DID 标识符\n- 管理 DID 文档（DID Document）\n- 支持 DID 解析与验证\n\n资料来源：[src/identity/did.ts]()\n\n#### Bundle 身份凭证包\n\nBundle 是身份凭证的聚合容器，包含 Agent 的身份证明、资质文件、权限声明等信息。\n\n```mermaid\ngraph LR\n B[Bundle] --> K[KYA 凭证]\n B --> P[Permissions 权限]\n B --> T[Tokens 代币]\n B --> R[Reputation 信誉]\n```\n\nBundle 的设计使得身份信息可以作为一个整体进行传输和验证，同时支持选择性披露。\n\n资料来源：[src/identity/bundle.ts]()\n\n### 钱包模块（Wallet）\n\n钱包模块管理 Agent 的资金、信誉评分和交易历史。\n\n#### 账户状态管理\n\nDashboard 中的账户状态管理展示了钱包与身份系统的集成方式：\n\n```typescript\nconst [profile, setProfile] = useState({\n wallet: 0,\n reputation: 0.5,\n memoriesCount: 0,\n transactionsCount: 0\n});\n```\n\n账户状态包含：\n- `wallet`: 钱包余额\n- `reputation`: 信誉评分（初始值 0.5）\n- `memoriesCount`: 记忆数量\n- `transactionsCount`: 交易次数\n\n资料来源：[dashboard/index.html:175-181]()\n\n#### 信誉评分系统\n\n信誉评分采用 300-850 分制，与 FICO 信用评分类似。评分由五个组成部分构成：\n\n| 评分维度 | 说明 |\n|---------|------|\n| 支付历史 | 按时支付的比例 |\n| 使用时长 | 账户存在时间 |\n| 信用类型 | 使用的产品多样性 |\n| 新信用 | 最近的开户行为 |\n| 余额利用率 | 信用使用率 |\n\n信誉评分直接影响：\n- 单次交易额度上限\n- 费率折扣\n- 访问高级功能权限\n\n资料来源：[README.md:42-50]()\n\n### 会话管理模块\n\n会话模块处理 Agent 的登录、登出和会话状态维护。\n\n#### 登录流程\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant SessionPanel\n participant Network\n participant Identity\n \n Agent->>SessionPanel: 请求登录\n SessionPanel->>Network: 验证凭证\n Network->>Identity: 验证身份\n Identity-->>Network: 验证结果\n Network-->>SessionPanel: 会话令牌\n SessionPanel-->>Agent: 登录成功\n```\n\n#### 会话状态管理\n\nDashboard 组件中实现了完整的会话状态管理：\n\n```typescript\nconst [session, setSession] = useState(null);\nconst [accountId, setAccountIdState] = useState(getAccountId());\nconst [connected, setConnected] = useState(false);\n```\n\n关键状态变量：\n\n| 变量 | 类型 | 说明 |\n|------|------|------|\n| `session` | object | 当前会话对象 |\n| `accountId` | string | 账户唯一标识符 |\n| `connected` | boolean | 连接状态 |\n\n资料来源：[dashboard/index.html:167-172]()\n\n### 权限控制模块\n\n权限模块实现细粒度的访问控制和安全策略。\n\n#### Permissions 权限矩阵\n\nMnemoPay 采用基于角色的访问控制（RBAC）与属性基访问控制（ABAC）混合模型：\n\n```mermaid\ngraph TD\n R[Request] --> P{Permissions Check}\n P -->|有权限| A[Allow]\n P -->|无权限| K{KillSwitch}\n K -->|触发熔断| B[Block]\n K -->|未触发| D[Deny]\n```\n\n#### KillSwitch 熔断机制\n\nKillSwitch 是安全防护的最后一道防线，在检测到异常行为时自动触发：\n\n| 触发条件 | 动作 |\n|---------|------|\n| 异常交易模式 | 暂停交易 |\n| 信誉分骤降 | 锁定账户 |\n| 可疑 IP | 二次验证 |\n| API 限流 | 服务降级 |\n\n资料来源：[README.md:46-48]()\n\n## 网络通信与验证\n\n### 网络层架构\n\n网络层负责所有身份相关的通信请求，包括验证、签发、更新等操作。\n\n```mermaid\ngraph TD\n subgraph 客户端\n SDK[SDK 客户端]\n ID[身份模块]\n end\n \n subgraph 服务端\n API[API 网关]\n AUTH[认证服务]\n IDV[身份服务]\n end\n \n SDK --> API\n ID --> NETWORK[网络模块]\n NETWORK --> API\n API --> AUTH\n AUTH --> IDV\n IDV --> DATABASE[(数据库)]\n```\n\n资料来源：[src/network.ts]()\n\n### 身份验证流程\n\n身份验证采用多层验证机制：\n\n1. **令牌验证**：检查 JWT 令牌的合法性\n2. **签名验证**：验证消息签名的正确性\n3. **状态检查**：验证账户未被锁定或禁用\n4. **权限检查**：确认操作在授权范围内\n\n## KYA（Know Your Agent）体系\n\nKYA 是 MnemoPay 的身份核验框架，类似于传统金融的 KYC（Know Your Customer）流程。\n\n### KYA 核验级别\n\n| 级别 | 核验内容 | 限额 | 适用场景 |\n|------|---------|------|---------|\n| L1 | 邮箱验证 | $100/日 | 开发测试 |\n| L2 | 手机验证 | $1,000/日 | 小规模部署 |\n| L3 | 身份证明 | $10,000/日 | 生产环境 |\n| L4 | 企业认证 | 无限制 | 企业客户 |\n\n### 身份凭证要求\n\nL3 及以上级别需要提供：\n- 法定身份证明（身份证、护照）\n- 地址证明（水电费账单）\n- 企业注册文件（适用于 L4）\n\n资料来源：[README.md:41-44]()\n\n## Agent 信用评分\n\nAgent 信用评分是 MnemoPay 的核心创新之一，为 AI Agent 提供可量化的信用指标。\n\n### 评分计算模型\n\n```mermaid\ngraph LR\n A[行为数据] --> B[实时监控]\n B --> C[EWMA 统计]\n C --> D[异常检测]\n D --> E[评分更新]\n E --> F[信用报告]\n```\n\n### 评分维度\n\n| 维度 | 权重 | 影响因素 |\n|------|------|---------|\n| 支付可靠性 | 35% | 按时支付比例 |\n| 交易历史 | 25% | 交易数量与频率 |\n| 账户稳定性 | 20% | 账户存续时间 |\n| 风险行为 | 15% | 异常交易检测 |\n| 信用多样性 | 5% | 产品使用广度 |\n\n### 异常检测机制\n\n系统采用 EWMA（指数加权移动平均）+ 指纹识别双重机制进行异常检测：\n\n- **EWMA**：检测交易金额、频率的统计异常\n- **指纹识别**：识别设备、IP、行为模式的异常\n\n资料来源：[README.md:51-54]()\n\n## 安全性设计\n\n### 安全层级\n\n```mermaid\ngraph TD\n subgraph 安全防护\n S1[身份标识]\n S2[通信加密]\n S3[权限验证]\n S4[行为监控]\n S5[熔断保护]\n end\n \n S1 --> S2\n S2 --> S3\n S3 --> S4\n S4 --> S5\n```\n\n### 威胁防护措施\n\n| 威胁类型 | 防护机制 |\n|---------|---------|\n| 重放攻击 | 时间戳 + 随机数 |\n| 中间人攻击 | TLS 1.3 + 证书固定 |\n| 权限提升 | 最小权限原则 |\n| 账户盗用 | 多因素认证 |\n| 交易欺诈 | 实时风险评估 |\n\n## 快速开始\n\n### 初始化身份\n\n```typescript\nimport { MnemoPay } from '@mnemopay/sdk';\n\nconst mnemo = MnemoPay.quick('agent-id');\n\n// 获取身份信息\nconst identity = await mnemo.identity.get();\nconsole.log(identity.did); // DID 标识符\nconsole.log(identity.wallet); // 钱包余额\nconsole.log(identity.reputation); // 信誉评分\n```\n\n### 管理会话\n\n```typescript\n// 登录\nawait mnemo.session.login({\n accountId: 'your-account-id'\n});\n\n// 获取当前会话\nconst session = await mnemo.session.current();\nconsole.log(session.token); // 会话令牌\nconsole.log(session.expiresAt); // 过期时间\n\n// 登出\nawait mnemo.session.logout();\n```\n\n### 权限检查\n\n```typescript\n// 检查权限\nconst hasPermission = await mnemo.identity.checkPermission({\n action: 'charge',\n resource: 'wallet'\n});\n\nif (hasPermission) {\n // 执行操作\n} else {\n // 触发 KillSwitch 或提示权限不足\n}\n```\n\n## 总结\n\nMnemoPay 的身份与认证系统为 AI Agent 提供了企业级的身份管理能力：\n\n- **去中心化身份**：基于 DID 的自主身份标识\n- **完整的钱包系统**：资金、信誉、交易一体化管理\n- **细粒度权限控制**：RBAC + ABAC 混合模型\n- **多层安全防护**：从身份验证到行为监控的全链路保护\n- **信用评分体系**：300-850 分制的 Agent 信用评分\n- **KYA 合规框架**：满足监管要求的身份核验流程\n\n这套系统使 AI Agent 能够像企业一样拥有身份、管理资金、建立信誉，为自主经济奠定基础。\n\n---\n\n\n\n## 代理信用评分系统\n\n### 相关页面\n\n相关主题：[异常检测系统](#anomaly-detection), [治理与合规框架](#governance)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/fico.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/fico.ts)\n- [src/behavioral.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/behavioral.ts)\n- [src/subagent-cost.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/subagent-cost.ts)\n- [dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n- [README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n \n\n# 代理信用评分系统\n\n## 概述\n\n代理信用评分系统（Agent Credit Scoring System）是 MnemoPay SDK 的核心组件之一，为 AI 代理提供类似人类信用评分的信任评估机制。该系统采用 300-850 的评分范围，模拟传统 FICO 信用评分模型，针对 AI 代理的交易行为、支付历史和可靠性进行多维度评估。\n\n代理信用评分直接影响交易手续费率、交易限额以及系统对异常行为的容忍度。评分越高的代理可享受更低的手续费（Enterprise 级别最低至 1.0%）和更高的交易限额，而评分较低的代理将面临更严格的监控甚至自动封禁。\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 系统架构\n\n代理信用评分系统由多个协同工作的模块组成，采用五组件评分架构，结合行为金融学和异常检测技术。\n\n```mermaid\ngraph TD\n A[代理身份创建] --> B[评分系统初始化]\n B --> C{评分组件}\n C --> D[FICO基础评分]\n C --> E[行为金融分析]\n C --> F[异常检测]\n C --> G[支付历史]\n C --> H[可靠性评估]\n D --> I[综合评分 300-850]\n E --> I\n F --> I\n G --> I\n H --> I\n I --> J[手续费计算]\n I --> K[交易限额]\n I --> L[风险控制]\n```\n\n## 核心组件\n\n### FICO 基础评分模块\n\nFICO 模块是评分系统的基础实现，负责计算代理的基础信用分值。该模块采用双余额记账系统追踪代理的财务状况，通过分析交易历史计算综合评分。\n\n评分计算考虑以下因素：\n\n| 因素 | 权重范围 | 说明 |\n|------|----------|------|\n| 支付历史 | 35% | 按时支付的比例和频率 |\n| 信用利用率 | 30% | 当前信用额度使用情况 |\n| 账户时长 | 15% | 账户活跃时间 |\n| 信用类型 | 10% | 使用的支付渠道多样性 |\n| 新信用查询 | 10% | 短期内新增信用申请 |\n\n资料来源：[src/fico.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/fico.ts)\n\n### 行为金融分析模块\n\n行为金融分析模块运用前景理论（Prospect Theory）和 nudge 机制，对代理的决策模式进行深度分析。该模块通过观察代理在相似场景下的历史决策，识别风险偏好和交易行为模式。\n\n```mermaid\ngraph LR\n A[交易行为数据] --> B[行为模式识别]\n B --> C{前景理论分析}\n C --> D[损失厌恶系数]\n C --> E[风险偏好曲线]\n C --> F[决策偏差检测]\n D --> G[行为评分调整]\n E --> G\n F --> G\n G --> H[最终行为分数]\n```\n\n该模块的核心功能包括：\n\n- **损失厌恶评估**：测量代理对损失的敏感程度，量化代理在面临潜在损失时的决策倾向\n- **风险偏好曲线**：基于前景理论建模代理的风险承担意愿，高风险偏好代理在市场波动时可能做出更激进的决策\n- **决策偏差检测**：识别代理行为中的系统性偏差，如锚定效应、可得性启发等认知偏差\n- **Nudge 机制**：根据代理的行为模式自动施加微小的决策引导，优化交易结果\n\n资料来源：[src/behavioral.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/behavioral.ts)\n\n### 子代理成本追踪模块\n\n子代理成本追踪模块专门针对多代理系统设计，记录和归因子代理的资源消耗。该模块维护每个子代理的成本中心，支持成本分配和内部结算。\n\n```mermaid\ngraph TD\n A[父代理] --> B[子代理成本记录]\n B --> C[资源消耗追踪]\n C --> D[成本归因分析]\n D --> E[内部结算]\n E --> F[成本效率评分]\n F --> G[父代理信用影响]\n```\n\n关键功能：\n\n- **资源消耗追踪**：记录 CPU、内存、API 调用等资源使用情况\n- **成本归因**：将子代理产生的成本准确归属到对应的父代理\n- **效率评分**：基于成本消耗与交易价值的比率计算效率分数\n\n资料来源：[src/subagent-cost.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/subagent-cost.ts)\n\n### 异常检测模块\n\n异常检测模块采用指数加权移动平均（EWMA）和指纹识别技术，实时监控代理行为，识别潜在的欺诈或异常活动。\n\n```mermaid\ngraph TD\n A[交易数据流] --> B[EWMA统计监控]\n A --> C[行为指纹生成]\n B --> D{异常判定}\n C --> D\n D -->|正常| E[更新基准线]\n D -->|异常| F[触发警报]\n D -->|严重| G[自动封禁]\n F --> H[人工审核队列]\n```\n\n检测机制：\n\n| 检测类型 | 技术方案 | 响应级别 |\n|----------|----------|----------|\n| 交易频率异常 | EWMA 动态阈值 | 警报 |\n| 金额异常 | 统计分布偏离检测 | 警报 |\n| 行为指纹异常 | 多维特征匹配 | 人工审核 |\n| 串通检测 | 图关系分析 | 自动封禁 |\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 评分计算流程\n\n### 初始化阶段\n\n代理首次初始化时，系统基于 Ed25519 加密身份创建唯一标识符，并分配初始信用评分。\n\n```typescript\n// 初始化代理并获取信用评分\nconst agent = MnemoPay.quick(\"billing-agent\", {\n stripe: { secretKey: process.env.STRIPE_SECRET_KEY }\n});\n\n// 信用评分将在首次交易后计算\nconsole.log(agent.id); // Ed25519 派生身份\n```\n\n### 动态评分更新\n\n评分系统采用流式计算模式，每次交易完成后自动更新评分。\n\n```mermaid\nsequenceDiagram\n participant A as 代理\n participant B as 评分系统\n participant C as 支付引擎\n participant D as 异常检测\n \n A->>C: charge() 请求\n C->>D: 提交交易\n D->>D: 异常检测\n D-->>C: 检测结果\n C->>B: 交易完成事件\n B->>B: 计算评分增量\n B->>B: 更新综合评分\n B-->>A: 新评分生效\n```\n\n## 评分应用场景\n\n### 手续费等级\n\n信用评分直接决定代理的交易手续费率：\n\n| 评分范围 | 等级 | 手续费率 | 适用计划 |\n|----------|------|----------|----------|\n| 750-850 | Excellent | 1.0% | Enterprise |\n| 650-749 | Good | 1.5% | Pro |\n| 550-649 | Fair | 2.0% | Starter |\n| 300-549 | Poor | 冻结交易 | 审核中 |\n\n资料来源：[site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)\n\n### 交易限额\n\n评分决定代理的即时交易限额和日累计限额：\n\n- **高评分代理（750+）**：无单笔限额，日限额根据账户历史自动调整\n- **中等评分代理（550-749）**：单笔限额 $10,000，日限额 $100,000\n- **低评分代理（300-549）**：单笔限额 $1,000，日限额 $5,000，需要人工审批\n\n### 自动风控\n\n评分系统与风控引擎深度集成：\n\n```mermaid\ngraph TD\n A[交易请求] --> B{信用评分检查}\n B -->|≥750| C[直接放行]\n B -->|650-749| D[简化验证]\n B -->|550-649| E[标准验证]\n B -->|300-549| F[拒绝交易]\n D --> G{EWMA异常检测}\n E --> G\n G -->|正常| H[人工确认]\n G -->|异常| F\n C --> I[执行交易]\n H --> I\n```\n\n## 仪表盘集成\n\n代理信用评分通过 MnemoPay 仪表盘实时展示，便于开发者监控代理健康状况。\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n\n```typescript\n// 仪表盘显示的代理信息结构\ninterface AgentProfile {\n wallet: number; // 钱包余额\n reputation: number; // 信誉分数 (0-1)\n memoriesCount: number; // 记忆条目数\n transactionsCount: number;// 交易总数\n}\n```\n\n## API 参考\n\n### 获取代理评分\n\n```typescript\nconst score = await agent.getCreditScore();\n// 返回: { score: number, factors: CreditFactor[] }\n```\n\n### 更新行为数据\n\n```typescript\nawait agent.updateBehavioralData({\n transactionPattern: 'conservative',\n riskTolerance: 0.3,\n lossAversion: 2.5\n});\n```\n\n### 查询子代理成本\n\n```typescript\nconst costReport = await agent.getSubagentCosts({\n period: '30d',\n groupBy: 'subagent'\n});\n```\n\n## 总结\n\n代理信用评分系统是 MnemoPay SDK 的核心信任基础设施，通过五组件评分架构、行为金融分析和实时异常检测，为 AI 代理提供可量化的信任评估。评分系统与支付引擎深度集成，直接影响手续费率、交易限额和风控策略，确保只有可靠的代理能够参与金融交易。\n\n---\n\n\n\n## 行为金融引擎\n\n### 相关页面\n\n相关主题：[代理信用评分系统](#credit-score), [异常检测系统](#anomaly-detection)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/behavioral.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/behavioral.ts)\n- [src/reasoning/post-processor.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/reasoning/post-processor.ts)\n \n\n# 行为金融引擎\n\n## 概述\n\n行为金融引擎是 MnemoPay SDK v1.4.0+ 中的核心模块之一，专注于将行为经济学原理（特别是前景理论/Prospect Theory）与 AI Agent 的支付决策系统相结合。该引擎通过实时干预和引导机制，优化 Agent 的金融行为，降低系统性风险，并提升整体支付生态的健康度。\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 核心定位\n\nMnemoPay SDK 的整体架构将行为金融引擎置于**Agent Credit Score（代理信用评分）**与**支付系统**之间的关键位置：\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│ GOVERNANCE Charter · FiscalGate · Article 12 · MerkleAudit │\n├──────────┬──────────┬───────────┬─────────────────────────────────┤\n│ Memory │ Payments │ Identity │ Agent Credit Score (300-850) │\n│ │ │ │ 5-component scoring │\n├──────────┴──────────┴───────────┼─────────────────────────────────┤\n│ │ Behavioral Finance │\n│ │ prospect theory, nudges │\n├────────────────────────────────┴─────────────────────────────────┤\n│ │ Anomaly Detection │\n│ │ EWMA + fingerprinting │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n资料来源：[README.md:Architecture](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 工作原理\n\n### 前景理论集成\n\n行为金融引擎基于 Kahneman 和 Tversky 的前景理论（Prospect Theory）设计。该理论的核心洞察是：**人类（及 AI Agent）在面对收益和损失时表现出非对称的风险偏好**：\n\n- **确定效应**：倾向于选择确定的收益而非概率收益\n- **反射效应**：在损失面前表现为风险寻求\n- **损失厌恶**：对损失的敏感度高于等量收益（约 2.25 倍）\n- **参考点依赖**：决策结果取决于相对于参考点的变化\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n### 决策干预流程\n\n```\ngraph TD\n A[交易请求 charge/settle] --> B{行为金融引擎评估}\n B --> C[计算即时效用]\n C --> D{参考点比较}\n D -->|收益框架| E[应用确定效应权重]\n D -->|损失框架| F[应用损失厌恶权重]\n E --> G[决策调整]\n F --> G\n G --> H{风险阈值检查}\n H -->|通过| I[执行交易]\n H -->|警告| J[发送Nudge提示]\n H -->|拒绝| K[阻止交易]\n```\n\n## Nudge 机制\n\n### 行为助推设计\n\n引擎内置多种 Nudge（行为助推）策略，用于温和引导 Agent 行为：\n\n| Nudge 类型 | 触发场景 | 响应方式 |\n|-----------|---------|---------|\n| 延迟确认 | 大额交易 | 建议冷却期 |\n| 风险提示 | 异常模式 | 警告信息 |\n| 历史参照 | 新交易对手 | 展示信用历史 |\n| 阈值预警 | 接近限额 | 提前通知 |\n\n### Nudge 实现模式\n\n```typescript\n// 典型 Nudge 触发场景\nif (transaction.amount > threshold * reputationScore) {\n applyNudge({\n type: 'DELAY_CONFIRMATION',\n message: '建议在执行前等待确认',\n cooldown: 30000 // 30秒冷却\n });\n}\n```\n\n资料来源：[src/behavioral.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/behavioral.ts)\n\n## 与异常检测的协同\n\n行为金融引擎与 EWMA（指数加权移动平均）异常检测系统紧密协作：\n\n```\ngraph LR\n A[行为数据流] --> B[EWMA 异常检测]\n B --> C{异常判断}\n C -->|正常| D[行为金融引擎正常决策]\n C -->|轻度异常| E[应用风险权重]\n C -->|重度异常| F[触发 Killswitch]\n E --> G[更新参考点]\n F --> H[阻止交易 + 记录审计]\n```\n\n### 双重验证机制\n\n1. **EWMA 层**：基于统计的时间序列异常检测，识别交易速度和频率异常\n2. **行为金融层**：基于决策心理学的规范性分析，识别不理性交易行为\n\n两层结合确保：\n- 统计异常 → 实时拦截\n- 行为异常 → Nudge 引导 + 长期跟踪\n\n资料来源：[README.md - Anomaly Detection](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 与 Agent Credit Score 的交互\n\n行为金融引擎的输出直接影响 **Agent Credit Score（300-850 分）**：\n\n```mermaid\ngraph TD\n A[交易完成] --> B[行为评估]\n B --> C{决策质量评分}\n C -->|理性决策| D[+信用分]\n C -->|异常交易| E[-信用分]\n C -->|高风险拦截| F[大幅扣分 + 标记]\n D --> G[更新5维评分模型]\n E --> G\n F --> G\n```\n\n### 评分反馈闭环\n\n引擎在每次交易结算（settle）时触发信用反馈循环：\n\n```typescript\n// 行为反馈机制\nonSettle(transaction) {\n const behaviorScore = evaluateDecisionQuality(transaction);\n const creditImpact = behaviorScore * FEEDBACK_LOOP_WEIGHT; // 0.05\n updateCreditScore(creditImpact);\n}\n```\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html) - 信用评分衰减注释\n\n## 配置参数\n\n| 参数 | 默认值 | 说明 |\n|------|-------|------|\n| `lossAversion` | 2.25 | 损失厌恶系数 |\n| `referencePointDecay` | 0.05 | 参考点衰减率（半衰期约14小时）|\n| `nudgeThreshold` | 动态 | Nudge 触发阈值 |\n| `prospectWeighting` | 0.61 | 概率加权函数参数 |\n\n### 实时参数调整\n\n引擎支持基于市场条件的动态参数调整：\n\n```typescript\ninterface BehavioralConfig {\n lossAversion: number; // 范围: 1.5-3.0\n decay: number; // 范围: 0.01-0.1\n feedbackLoopWeight: number; // 范围: 0.01-0.1\n ceilingMultiplier: number; // 信用分上限系数\n}\n```\n\n资料来源：[src/behavioral.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/behavioral.ts)\n\n## 应用场景\n\n### 场景一：代理购物（Autonomous Shopping）\n\n当 Agent 代表用户执行购买决策时：\n\n1. **交易前**：评估用户历史偏好和风险承受能力\n2. **交易中**：应用前景理论框架调整购买确认流程\n3. **交易后**：基于结算结果更新 Agent 信用评分\n\n```typescript\n// 自动购物中的行为金融干预\nconst shoppingAgent = MnemoPay.quick(\"shopping-agent\");\nconst purchase = await shoppingAgent.charge(299.00, \"Enterprise plan\");\n\n// 引擎自动评估：\n// - 金额是否超出代理信用上限\n// - 交易频率是否异常\n// - 交易对手风险评分\n```\n\n### 场景二：多代理商业（Multi-Agent Commerce）\n\n在多 Agent 协作场景中，行为金融引擎提供：\n\n- **信任传递**：基于信用评分的行为担保\n- **争议预防**：Nudge 机制减少事后纠纷\n- **清算优化**：前景理论驱动的最优结算时机选择\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html) - 规模扩展场景\n\n## 监控与仪表板\n\n行为金融引擎的各项指标可在 MnemoPay Dashboard 中实时监控：\n\n```typescript\n// Dashboard 展示的关键指标\ninterface BehavioralMetrics {\n reputation: number; // 当前声誉值 (0-1)\n ceiling: number; // 当前计费上限 ($)\n decay: number; // 衰减率\n feedbackLoop: string; // 反馈循环状态\n overLimit: boolean; // 是否超限\n}\n```\n\nDashboard 面板通过以下组件展示引擎状态：\n\n| 面板区域 | 显示内容 | 数据来源 |\n|---------|---------|---------|\n| Reputation | 实时声誉分数 | `profile.reputation` |\n| Credit Ceiling | 动态计算上限 | `500 * reputation` |\n| Plan Gate | 限额状态指示 | `missions.overLimit` |\n| Active Sessions | 行为异常会话 | `session` 数据 |\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html) - 计费面板代码\n\n## 技术特性\n\n### 无侵入集成\n\n行为金融引擎作为 SDK 中间件层实现，对业务逻辑无侵入：\n\n```typescript\n// 中间件注册方式\nimport { mnemoPayMiddleware } from \"@mnemopay/sdk/middleware/openai\";\n// 或\nimport { mnemoPayMiddleware } from \"@mnemopay/sdk/middleware/anthropic\";\n```\n\n### 跨平台支持\n\n引擎通过标准化接口支持多种 AI 框架：\n\n| 框架 | 集成方式 |\n|-----|---------|\n| OpenAI | `mnemoPayMiddleware` |\n| Anthropic | `mnemoPayMiddleware` |\n| LangGraph | `mnemoPayTools` |\n\n资料来源：[README.md - Middleware](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n### 哈希链完整性\n\n所有行为金融决策通过 Merkle 树记录，确保审计可追溯：\n\n```\nMerkleAudit 包含：\n├── 行为决策记录\n├── Nudge 触发历史\n├── 信用评分变更\n└── 异常处理日志\n```\n\n资料来源：[README.md - Architecture](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 版本演进\n\n| 版本 | 关键更新 |\n|-----|---------|\n| v1.4.0 | 首次引入行为金融引擎，集成前景理论和 Nudge 机制 |\n| v1.5.0 | 稳定版发布，架构与 Alpha 版保持一致 |\n| v1.6.0-alpha | 持续优化行为模型参数 |\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md) - 版本信息\n\n## 总结\n\n行为金融引擎是 MnemoPay SDK 区别于传统支付网关的核心创新点之一。通过将 Kahneman 和 Tversky 的行为经济学理论与现代 AI Agent 系统相结合，引擎实现了：\n\n- **风险可控**：通过前景理论框架和 Nudge 机制预防非理性交易\n- **信用驱动**：基于行为质量动态调整 Agent 信用评分\n- **可审计性**：Merkle 树记录确保所有决策可追溯验证\n- **实时干预**：EWMA 异常检测与行为金融评估双重保障\n\n---\n\n\n\n## 异常检测系统\n\n### 相关页面\n\n相关主题：[代理信用评分系统](#credit-score), [治理与合规框架](#governance), [身份与认证系统](#identity-auth)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/anomaly.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/anomaly.ts)\n- [src/fraud.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/fraud.ts)\n- [src/fraud-ml.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/fraud-ml.ts)\n- [src/recall/rerank.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/rerank.ts)\n- [CLAUDE.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/CLAUDE.md)\n- [README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n \n\n# 异常检测系统\n\n## 概述\n\n异常检测系统是 MnemoPay SDK 的核心安全组件之一，旨在保护 AI Agent 的交易行为和财务操作免受欺诈、滥用和异常模式的侵害。该系统采用多层次检测策略，结合统计学方法（EWMA）、行为监控、地理增强分析和机器学习模型，实现实时的交易风险评估和异常预警。\n\n根据项目架构文档，异常检测系统与其他组件（记忆系统、支付系统、身份系统）并列，共同构成了 MnemoPay SDK 的四大支柱。资料来源：[README.md:11]()\n\n## 核心架构\n\n### 模块组成\n\n| 模块 | 文件路径 | 主要功能 |\n|------|----------|----------|\n| `anomaly.ts` | `src/anomaly.ts` | EWMA 指数加权移动平均检测、行为监控、金丝雀系统 |\n| `fraud.ts` | `src/fraud.ts` | 地理增强欺诈检测、速度限制、费用分析 |\n| `fraud-ml.ts` | `src/fraud-ml.ts` | 机器学习驱动的欺诈模式识别 |\n| `rerank.ts` | `src/recall/rerank.ts` | 记忆检索重排序（异常关联分析） |\n\n### 系统架构图\n\n```mermaid\ngraph TB\n subgraph 异常检测系统\n A[交易事件输入] --> B[行为监控器
BehaviorMonitor]\n B --> C[EWMA 检测器]\n B --> D[速度限制检查
Velocity Check]\n C --> E[金丝雀系统
CanarySystem]\n D --> E\n E --> F[地理欺诈检测
Geo-Fraud]\n F --> G[ML 欺诈检测
fraud-ml]\n G --> H[风险评分引擎]\n end\n \n H --> I{风险等级判定}\n I -->|低风险| J[允许交易]\n I -->|中风险| K[标记审查]\n I -->|高风险| L[阻断交易]\n \n M[记忆系统] -->|行为特征| B\n N[身份系统] -->|权限信息| G\n```\n\n## EWMA 异常检测\n\n### 算法原理\n\nEWMA（Exponentially Weighted Moving Average，指数加权移动平均）是一种统计过程控制方法，用于检测时间序列数据中的异常波动。MnemoPay SDK 使用 EWMA 来监控 Agent 的交易行为模式，当实时指标偏离历史基线超过预设阈值时触发告警。\n\n资料来源：[CLAUDE.md:14]()\n\n### 核心配置参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `decay_factor` | EWMA 衰减因子，控制历史数据的权重 | `0.95` |\n| `alert_threshold` | 告警触发阈值（标准差倍数） | `3.0` |\n| `warmup_period` | 预热期样本数（建立基线前不告警） | `100` |\n| `reset_on_drift` | 检测到漂移时是否重置基线 | `true` |\n\n### 使用示例\n\n```typescript\nimport { AnomalyDetector, EWMAConfig } from '@mnemopay/sdk';\n\nconst config: EWMAConfig = {\n decay_factor: 0.95,\n alert_threshold: 3.0,\n warmup_period: 100,\n reset_on_drift: true\n};\n\nconst detector = new AnomalyDetector(config);\n\n// 监控交易金额异常\nconst result = detector.checkTransaction({\n agentId: 'agent-001',\n amount: 150.00,\n timestamp: Date.now()\n});\n\nif (result.anomaly) {\n console.log(`检测到异常: ${result.reason}, 置信度: ${result.confidence}`);\n}\n```\n\n## 行为监控系统\n\n### BehaviorMonitor\n\n行为监控器是异常检测系统的核心组件，持续追踪 Agent 的多维度行为指标：\n\n- **交易频率**：单位时间内的交易数量\n- **平均交易金额**：历史交易的平均值和标准差\n- **时间模式**：交易发生的时间分布特征\n- **地理分布**：交易来源的地理位置变化\n- **交互模式**：与其他 Agent 的交互频率和类型\n\n资料来源：[CLAUDE.md:14]()\n\n### 行为指标表\n\n| 指标类型 | 监控内容 | 异常阈值 |\n|----------|----------|----------|\n| `velocity` | 交易速率 | > 10 tx/min |\n| `amount_deviation` | 金额偏离度 | > 3σ |\n| `geo_entropy` | 地理熵值 | < 0.2 |\n| `session_count` | 会话数量 | 异常激增 |\n| `api_error_rate` | API 错误率 | > 5% |\n\n## 金丝雀系统\n\n### 功能概述\n\n金丝雀系统（CanarySystem）是一种渐进式发布和灰度检测机制，用于在生产环境中验证新交易模式或检测潜在的异常行为。它通过引入一小部分\"金丝雀\"交易来测试系统的响应，并将结果与基线进行对比。\n\n资料来源：[CLAUDE.md:14]()\n\n### 工作流程\n\n```mermaid\ngraph LR\n A[新交易模式] --> B[金丝雀采样
10% 流量]\n B --> C{模式匹配?}\n C -->|是| D[执行交易]\n C -->|否| E[记录异常]\n D --> F[监控系统响应]\n F --> G{响应正常?}\n G -->|是| H[扩大流量]\n G -->|否| I[回滚/告警]\n```\n\n### 金丝雀配置\n\n```typescript\ninterface CanaryConfig {\n sample_rate: number; // 采样比例 (0-1)\n timeout_ms: number; // 超时时间\n alert_on_fail: boolean; // 失败时告警\n auto_rollback: boolean; // 自动回滚\n}\n```\n\n## 地理欺诈检测\n\n### 地理增强分析\n\n`fraud.ts` 模块实现了基于地理位置的欺诈检测功能，通过分析交易的地理分布来识别潜在的欺诈行为。资料来源：[CLAUDE.md:13]()\n\n### 检测机制\n\n| 检测类型 | 说明 | 阈值配置 |\n|----------|------|----------|\n| `velocity_geo` | 地理速度异常（不可能的旅行） | 500 km/h |\n| `sanctions_check` | 制裁名单匹配 | 精确匹配 |\n| `proxy_vpn` | 代理/VPN 使用检测 | 概率 > 0.7 |\n| `geo_trust_score` | 地理信任评分 | < 0.3 |\n\n### 集成测试\n\n项目包含专门的地理欺诈测试文件 `geo-fraud.test.ts`，覆盖以下场景：\n\n- 地理信号处理\n- 信任评分计算\n- 制裁名单检查\n- 不可能旅行检测\n\n资料来源：[README.md:40-43]()\n\n## 机器学习欺诈检测\n\n### fraud-ml 模块\n\n`fraud-ml.ts` 模块使用机器学习算法来识别复杂的欺诈模式。该模块提供了基于历史数据的模型训练和实时推理能力。\n\n资料来源：[CLAUDE.md:13]()\n\n### 模型特征\n\n| 特征类别 | 特征名称 | 数据类型 |\n|----------|----------|----------|\n| 交易特征 | `amount`, `frequency`, `time_gap` | float |\n| 行为特征 | `session_length`, `error_rate` | float |\n| 网络特征 | `counterparty_count`, `graph_centrality` | float |\n| 历史特征 | `chargeback_rate`, `dispute_count` | float |\n\n### 预测接口\n\n```typescript\ninterface FraudPrediction {\n score: number; // 欺诈概率 (0-1)\n risk_level: 'low' | 'medium' | 'high';\n factors: string[]; // 主要风险因素\n confidence: number; // 预测置信度\n}\n```\n\n## 速度限制检查\n\n### 速率限制机制\n\n速度限制（Velocity Check）是防止滥用和欺诈的第一道防线，通过限制单位时间内的操作次数来实现。\n\n```mermaid\ngraph TD\n A[请求到达] --> B{速率限制检查}\n B -->|通过| C[处理交易]\n B -->|超限| D[返回 429 Too Many Requests]\n C --> E[更新计数器]\n E --> F[滑动窗口刷新]\n```\n\n### 配置参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `max_per_minute` | 每分钟最大请求数 | 60 |\n| `max_per_hour` | 每小时最大请求数 | 1000 |\n| `max_per_day` | 每天最大请求数 | 10000 |\n| `burst_allowance` | 突发容许量 | 10 |\n\n## 重放攻击检测\n\n### 重放检测机制\n\n异常检测系统还包括对重放攻击（Replay Attack）的防护，通过以下机制实现：\n\n1. **时间戳验证**：检查请求时间戳是否在有效窗口内（默认 300 秒）\n2. **Nonce 管理**：跟踪已处理的 Nonce 值，防止重复执行\n3. **签名校验**：验证 HMAC-SHA256 签名的有效性\n\n```typescript\ninterface ReplayCheckResult {\n valid: boolean;\n reason?: string; // 失败原因\n timestamp_age?: number; // 时间戳年龄（秒）\n}\n```\n\n资料来源：[src/mcp/server.ts:24-30]()\n\n## 与其他模块的集成\n\n### 模块依赖关系\n\n```mermaid\ngraph TB\n ANOMALY[异常检测系统] --> IDENTITY[身份系统]\n ANOMALY --> LEDGER[账本系统]\n ANOMALY --> MEMORY[记忆系统]\n ANOMALY --> NETWORK[网络系统]\n \n IDENTITY -->|权限信息| ANOMALY\n MEMORY -->|行为基线| ANOMALY\n NETWORK -->|交易图谱| ANOMALY\n LEDGER -->|审计日志| ANOMALY\n```\n\n### 集成点\n\n| 集成模块 | 集成方式 | 数据流向 |\n|----------|----------|----------|\n| 身份系统 | CapabilityToken 验证 | 输入 |\n| 记忆系统 | 行为基线查询 | 输入 |\n| 账本系统 | 双录审计日志 | 输出 |\n| 网络系统 | 交易图谱分析 | 双向 |\n\n## 测试覆盖\n\n### 测试文件\n\n项目为异常检测系统提供了全面的测试覆盖：\n\n| 测试文件 | 覆盖范围 | 测试数量 |\n|----------|----------|----------|\n| `core.test.ts` | EWMA、Canary、基线漂移 | 核心功能 |\n| `fraud.test.ts` | 速度限制、异常检测、费用分析、争议处理、重放检测 | 8+ 场景 |\n| `geo-fraud.test.ts` | 地理信号、信任评分、制裁检查 | 地理场景 |\n| `stress-200k.test.ts` | 高并发下的异常检测稳定性 | 200K 操作 |\n\n资料来源：[README.md:35-46]()\n\n### 运行测试\n\n```bash\n# 运行所有异常检测相关测试\nnpm test -- anomaly\n\n# 运行地理欺诈测试\nnpm test -- geo-fraud\n\n# 运行压力测试\nnpm test -- stress-200k\n```\n\n## 配置最佳实践\n\n### 生产环境配置建议\n\n```typescript\nconst productionConfig = {\n anomaly: {\n decay_factor: 0.98, // 更敏感的衰减\n alert_threshold: 2.5, // 降低阈值提高灵敏度\n warmup_period: 500, // 更长的预热期\n reset_on_drift: false // 不自动重置，需人工介入\n },\n canary: {\n sample_rate: 0.01, // 1% 采样\n timeout_ms: 5000,\n alert_on_fail: true,\n auto_rollback: true\n },\n geo_fraud: {\n velocity_threshold: 300, // km/h\n trust_score_threshold: 0.5,\n sanctions_check_enabled: true\n },\n rate_limit: {\n max_per_minute: 30,\n max_per_hour: 500,\n max_per_day: 5000\n }\n};\n```\n\n### 告警阈值调整\n\n| 风险等级 | EWMA 倍数 | 地理评分 | 建议操作 |\n|----------|-----------|----------|----------|\n| 低风险 | < 2σ | > 0.7 | 允许通过 |\n| 中风险 | 2-3σ | 0.4-0.7 | 添加人工审核 |\n| 高风险 | > 3σ | < 0.4 | 自动阻断 |\n\n## 总结\n\n异常检测系统是 MnemoPay SDK 保障 AI Agent 交易安全的核心防线，通过 EWMA 统计方法、行为监控、金丝雀验证、地理增强分析和机器学习模型的协同工作，实现了多层次、多维度的欺诈防护。该系统与身份系统、记忆系统、账本系统和网络系统紧密集成，形成完整的安全生态。开发者可根据具体业务场景调整检测参数，在安全性与用户体验之间取得平衡。\n\n---\n\n\n\n## 支付轨道\n\n### 相关页面\n\n相关主题：[账本与支付系统](#ledger-payments), [治理与合规框架](#governance)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/rails/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/index.ts)\n- [src/rails/stripe-mpp.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/stripe-mpp.ts)\n- [src/rails/x402.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/x402.ts)\n- [src/rails/google-ap2.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/google-ap2.ts)\n- [src/rails/paystack.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/paystack.ts)\n- [src/commerce/providers/shopify.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/commerce/providers/shopify.ts)\n- [src/commerce/providers/firecrawl.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/commerce/providers/firecrawl.ts)\n- [examples/02-openai-middleware.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/examples/02-openai-middleware.ts)\n- [examples/03-anthropic-middleware.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/examples/03-anthropic-middleware.ts)\n \n\n# 支付轨道\n\n## 概述\n\n支付轨道（Payment Rails）是 MnemoPay SDK 中处理实际资金流转的核心模块，为 AI Agent 提供统一抽象的支付接口。无论底层使用 Stripe、Paystack 还是 Lightning Network，开发者都可通过相同的 API 进行扣款、托管、结算和退款操作。\n\n支付轨道的设计目标包括：\n\n- **统一抽象**：不同支付渠道使用相同的方法签名，降低集成复杂度\n- **多渠道支持**：覆盖全球主要支付区域，包括非洲、欧洲、北美和加密货币\n- **安全托管**：支持人工审批后才释放资金，防止 Agent 未经授权的消费\n- **可扩展架构**：预留扩展接口，便于添加新的支付轨道\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 支持的支付轨道\n\nMnemoPay SDK 目前支持六种支付轨道，分为稳定版和预览版两类。\n\n| 轨道名称 | 覆盖区域 | 状态 | 通道标签 |\n|---------|---------|------|---------|\n| `StripeRail` | 全球（USD, EUR, GBP） | 稳定版 | `latest` |\n| `PaystackRail` | 非洲（NGN, GHS, ZAR, KES） | 稳定版 | `latest` |\n| `LightningRail` | BTC 微支付 | 稳定版 | `latest` |\n| `StripeMPPRail` | Tempo 加密货币存款 | 预览版 | `alpha` |\n| `X402Rail` | Base USDC（EIP-3009） | 预览版 | `alpha` |\n| `GoogleAP2Rail` | AP2 v0.2 FIDO Alliance | 预览版 | `alpha` |\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n### 稳定版轨道\n\n稳定版支付轨道经过生产环境验证，适合对可靠性要求较高的应用场景：\n\n- **StripeRail**：支持 135+ 种货币，采用 PaymentIntents API，支持手动捕获实现真正的托管功能\n- **PaystackRail**：覆盖 23 家尼日利亚银行，集成 HMAC-SHA512 安全校验\n- **LightningRail**：专为 BTC 子美分级微支付设计\n\n### 预览版轨道\n\n预览版支付轨道处于活跃开发阶段，可能存在 API 变更：\n\n- **StripeMPPRail**：通过 Stripe Marketplace Payments 实现加密货币存款\n- **X402Rail**：使用 EIP-3009 的 `transferWithAuthorization` 实现 Base 链上的 USDC 转账\n- **GoogleAP2Rail**：基于 FIDO Alliance AP2 v0.2 的 mandate 驱动结算\n\n资料来源：[src/rails/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/index.ts)\n\n## 核心架构\n\n### 轨道接口设计\n\n所有支付轨道继承自统一的基类接口，确保 API 一致性：\n\n```mermaid\nclassDiagram\n class PaymentRail {\n <>\n +charge(amount, metadata) Promise~ChargeResult~\n +settle(txId) Promise~SettleResult~\n +refund(txId, amount) Promise~RefundResult~\n +webhook(payload) Promise~WebhookResult~\n }\n \n class StripeRail {\n +stripe: Stripe\n +charge()\n +settle()\n +refund()\n }\n \n class PaystackRail {\n +paystack: Paystack\n +charge()\n +settle()\n +refund()\n }\n \n class LightningRail {\n +lnd: LNDClient\n +charge()\n +settle()\n }\n \n PaymentRail <|-- StripeRail\n PaymentRail <|-- PaystackRail\n PaymentRail <|-- LightningRail\n```\n\n### 交易流程\n\n支付轨道支持完整的交易生命周期管理：\n\n```mermaid\ngraph TD\n A[Agent 请求扣款] --> B{支付轨道选择}\n B --> C[StripeRail]\n B --> D[PaystackRail]\n B --> E[LightningRail]\n \n C --> F[创建 PaymentIntent]\n D --> G[初始化 Paystack Transaction]\n E --> H[创建 Lightning Invoice]\n \n F --> I{用户确认}\n G --> I\n H --> I\n \n I -->|确认| J[资金托管]\n I -->|拒绝| K[交易取消]\n \n J --> L{人工审批}\n L -->|通过| M[结算 settle]\n L -->|拒绝| N[退款 refund]\n \n M --> O[资金释放给商户]\n N --> P[资金退回用户]\n```\n\n资料来源：[src/rails/stripe-mpp.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/stripe-mpp.ts)\n\n## 快速开始\n\n### 导入支付轨道\n\n```typescript\nimport {\n PaystackRail, StripeRail, LightningRail, // 稳定版\n StripeMPPRail, X402Rail, GoogleAP2Rail, // 预览版\n} from \"@mnemopay/sdk\";\n```\n\n### 初始化支付轨道\n\n**Stripe 稳定配置：**\n\n```typescript\nconst stripe = new StripeRail(process.env.STRIPE_SECRET_KEY!);\n```\n\n**Paystack 非洲支付：**\n\n```typescript\nconst paystack = new PaystackRail(process.env.PAYSTACK_SECRET_KEY!);\n```\n\n**Lightning BTC 微支付：**\n\n```typescript\nconst lightning = new LightningRail(LND_URL, MACAROON);\n```\n\n**预览版支付轨道：**\n\n```typescript\n// Stripe MPP 加密货币存款\nconst mpp = new StripeMPPRail(process.env.STRIPE_SECRET_KEY!);\n\n// X402 USDC 转账\nconst x402 = new X402Rail({ signer: yourEip3009Signer });\n\n// Google AP2 FIDO 结算\nconst ap2 = new GoogleAP2Rail({ mandate, endpoint, signer });\n```\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n### 与 Agent 集成\n\n初始化 Agent 时指定支付轨道：\n\n```typescript\nconst agent = MnemoPay.quick(\"my-agent\", {\n rail: new StripeRail(process.env.STRIPE_SECRET_KEY!),\n // 其他配置...\n});\n```\n\n## 各支付轨道详解\n\n### StripeRail\n\nStripeRail 是面向全球市场的支付轨道，支持 135+ 种货币和信用卡、借记卡支付。\n\n**核心方法：**\n\n| 方法 | 参数 | 返回值 | 说明 |\n|-----|------|-------|------|\n| `charge` | `amount`, `currency`, `metadata` | `ChargeResult` | 创建扣款请求 |\n| `settle` | `txId` | `SettleResult` | 结算已托管的交易 |\n| `refund` | `txId`, `amount?` | `RefundResult` | 退款交易 |\n| `createIntent` | `params` | `PaymentIntent` | 创建 PaymentIntent |\n\n**安全特性：**\n\n- 手动捕获模式支持真正的资金托管\n- PaymentIntents API 提供 3D Secure 支持\n- Webhook 签名验证\n\n资料来源：[src/rails/stripe-mpp.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/stripe-mpp.ts)\n\n### PaystackRail\n\nPaystackRail 专注于非洲市场，深度集成当地银行系统。\n\n**支持货币：**\n\n- NGN（尼日利亚奈拉）\n- GHS（加纳塞地）\n- ZAR（南非兰特）\n- KES（肯尼亚先令）\n\n**特色功能：**\n\n- 23 家尼日利亚银行预映射\n- HMAC-SHA512 Webhook 安全校验\n- 移动支付和银行转账支持\n\n```typescript\nconst paystack = new PaystackRail(process.env.PAYSTACK_SECRET_KEY!);\n\n// 非洲本地支付\nawait paystack.charge(5000, {\n currency: 'NGN',\n email: 'customer@example.com',\n bank: '044' // Access Bank\n});\n```\n\n资料来源：[src/rails/paystack.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/paystack.ts)\n\n### LightningRail\n\nLightningRail 专为比特币微支付设计，支持子美分级的小额交易。\n\n**技术特性：**\n\n- 即时结算（相较于链上 BTC）\n- 极低手续费，适合微支付场景\n- 依赖 LND（Lightning Network Daemon）\n\n```typescript\nconst lightning = new LightningRail(LND_URL, MACAROON);\n\n// 创建 Lightning Invoice\nconst invoice = await lightning.charge(100, {\n description: 'API调用费用',\n expiry: 3600 // 1小时过期\n});\n```\n\n### X402Rail\n\nX402Rail 实现 EIP-3009 标准，在 Base 区块链上支持 USDC 转账。\n\n**核心流程：**\n\n```mermaid\ngraph LR\n A[请求授权] --> B[生成 transferWithAuthorization]\n B --> C[用户签名授权]\n C --> D[执行 USDC 转账]\n D --> E[交易确认]\n```\n\n**配置参数：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|-----|------|-----|------|\n| `signer` | `EIP3009Signer` | 是 | EIP-3009 签名器实例 |\n| `recipient` | `string` | 否 | 默认收款地址 |\n| `domain` | `string` | 否 | EIP-712 域名 |\n\n```typescript\nconst x402 = new X402Rail({\n signer: yourEip3009Signer,\n recipient: '0x...'\n});\n```\n\n资料来源：[src/rails/x402.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/x402.ts)\n\n### GoogleAP2Rail\n\nGoogleAP2Rail 基于 FIDO Alliance 的 AP2 v0.2 标准，提供 mandate 驱动的结算机制。\n\n**Mandate 概念：**\n\nMandate 是用户预先授权的支付指令，允许商户在特定条件下自动扣款。\n\n```typescript\nconst ap2 = new GoogleAP2Rail({\n mandate: {\n id: 'mandate_xxx',\n maxAmount: 10000,\n currency: 'USD',\n frequency: 'per_use'\n },\n endpoint: 'https://api.google.com/ap2/v2',\n signer: yourSigner\n});\n```\n\n资料来源：[src/rails/google-ap2.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/google-ap2.ts)\n\n### StripeMPPRail\n\nStripeMPPRail（Marketplace Payments）允许通过 Stripe 实现加密货币存款和结算。\n\n**应用场景：**\n\n- 多方分账场景\n- 加密货币与法币混合支付\n- Tempo 生态内的资金流转\n\n```typescript\nconst mpp = new StripeMPPRail(process.env.STRIPE_SECRET_KEY!);\n\nawait mpp.charge(1000, {\n currency: 'usdc',\n destination: 'tempo_address_xxx'\n});\n```\n\n资料来源：[src/rails/stripe-mpp.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/stripe-mpp.ts)\n\n## 托管与结算\n\n### 托管机制\n\n支付轨道支持资金托管（Escrow）功能，确保交易经过人工审批后再释放：\n\n```mermaid\ngraph TD\n A[charge 调用] --> B[资金进入托管状态]\n B --> C[等待人工审批]\n C --> D{审批结果}\n D -->|通过| E[settle 结算]\n D -->|拒绝| F[refund 退款]\n \n E --> G[资金释放给商户]\n F --> H[资金退回用户]\n```\n\n### Agent 消费限制\n\nAgent 的支付行为受以下限制保护：\n\n| 限制类型 | 说明 | 配置方式 |\n|---------|------|---------|\n| `llmCapCents` | LLM 调用费用上限 | 账户级别设置 |\n| `seats` | 授权席位数量 | 订阅计划决定 |\n| `missionLimit` | 任务执行次数限制 | 计划配额 |\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n\n## Webhook 处理\n\n支付轨道提供统一的 Webhook 接口处理各渠道的异步通知：\n\n```typescript\n// 定义 Webhook 处理函数\nasync function handleWebhook(rail: PaymentRail, payload: WebhookPayload) {\n switch (payload.type) {\n case 'payment.pending':\n // 等待用户确认\n break;\n case 'payment.succeeded':\n // 支付成功，进入托管\n break;\n case 'payment.failed':\n // 支付失败\n break;\n case 'settlement.completed':\n // 结算完成\n break;\n }\n}\n```\n\n**安全验证：**\n\n- Stripe：验证 `Stripe-Signature` 头\n- Paystack：HMAC-SHA512 签名校验\n- Lightning：Invoice 状态轮询\n\n## 错误处理\n\n### 错误类型\n\n| 错误码 | 说明 | 处理建议 |\n|-------|------|---------|\n| `INSUFFICIENT_FUNDS` | 余额不足 | 提示用户充值 |\n| `RAIL_UNAVAILABLE` | 支付渠道不可用 | 切换备用渠道 |\n| `KYC_REQUIRED` | 需要完成身份验证 | 引导用户 KYC |\n| `FRAUD_SUSPECTED` | 欺诈嫌疑 | 拒绝交易并标记 |\n| `SETTLEMENT_LIMIT` | 达到结算限额 | 分批结算 |\n\n### 重试策略\n\n```typescript\nasync function chargeWithRetry(rail: PaymentRail, amount: number, retries = 3) {\n for (let i = 0; i < retries; i++) {\n try {\n return await rail.charge(amount, {});\n } catch (error) {\n if (error.code === 'RAIL_UNAVAILABLE' && i < retries - 1) {\n await delay(1000 * (i + 1)); // 指数退避\n continue;\n }\n throw error;\n }\n }\n}\n```\n\n## 商业购物集成\n\n支付轨道可与商业购物模块配合，实现 Agent 的自主采购：\n\n### Shopify 集成\n\n```typescript\nimport { ShopifyProvider } from \"@mnemopay/commerce/providers/shopify\";\n\nconst shopify = new ShopifyProvider({\n shop: 'your-store.myshopify.com',\n token: process.env.SHOPIFY_TOKEN\n});\n\n// Agent 搜索商品\nconst products = await shopify.search({\n query: 'wireless headphones',\n price_max: 100\n});\n\n// 购买流程通过支付轨道托管\n```\n\n### Firecrawl 网页抓取\n\n```typescript\nimport { FirecrawlProvider } from \"@mnemopay/commerce/providers/firecrawl\";\n\nconst firecrawl = new FirecrawlProvider({\n apiKey: process.env.FIRECRAWL_KEY\n});\n\n// Agent 抓取电商网站比价\nconst prices = await firecrawl.scrape({\n url: 'https://example.com/products',\n query: 'price'\n});\n```\n\n资料来源：[src/commerce/providers/shopify.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/commerce/providers/shopify.ts)\n\n## LLM 中间件集成\n\n支付轨道可作为 LLM API 调用的计费中间件：\n\n### OpenAI 中间件\n\n```typescript\nimport { createOpenAIMiddleware } from \"@mnemopay/sdk/middleware/openai\";\n\nconst middleware = createOpenAIMiddleware({\n rail: new StripeRail(process.env.STRIPE_SECRET_KEY!),\n costPerToken: 0.0001\n});\n\napp.use('/v1/chat/completions', middleware);\n```\n\n### Anthropic 中间件\n\n```typescript\nimport { createAnthropicMiddleware } from \"@mnemopay/sdk/middleware/anthropic\";\n\nconst middleware = createAnthropicMiddleware({\n rail: new StripeRail(process.env.STRIPE_SECRET_KEY!),\n modelCosts: {\n 'claude-3-opus': 0.015,\n 'claude-3-sonnet': 0.003\n }\n});\n```\n\n资料来源：[examples/02-openai-middleware.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/examples/02-openai-middleware.ts)\n\n## 安全考虑\n\n### 密钥管理\n\n- 支付渠道密钥应存储在环境变量或密钥管理服务\n- 切勿将密钥硬编码或提交到版本控制\n- 生产环境应使用独立的 Stripe/Paystack 密钥\n\n### 签名验证\n\n所有 Webhook 回调必须验证签名：\n\n```typescript\nasync function verifyWebhook(rail: PaymentRail, payload: Buffer, signature: string) {\n return await rail.verifySignature(payload, signature);\n}\n```\n\n### 交易限额\n\n建议为不同信任级别的 Agent 设置交易限额：\n\n| Agent 等级 | 单笔限额 | 日累计限额 |\n|-----------|---------|-----------|\n| 新建 | $10 | $50 |\n| 已验证 | $100 | $500 |\n| 高信用 | $1000 | $10000 |\n| 企业 | 自定义 | 自定义 |\n\n## 总结\n\n支付轨道是 MnemoPay SDK 的核心组件，为 AI Agent 提供安全、统一的支付能力。通过支持 Stripe、Paystack、Lightning 等多种渠道，开发者可以灵活选择适合目标市场的支付方式。稳定版轨道已通过生产验证，预览版轨道则为加密货币和新型支付协议提供了实验基础。\n\n无论选择哪种支付轨道，统一的 API 设计确保了代码的可移植性，而托管机制则保障了资金安全，防止 Agent 未经授权的消费行为。\n\n---\n\n\n\n## 治理与合规框架\n\n### 相关页面\n\n相关主题：[身份与认证系统](#identity-auth), [异常检测系统](#anomaly-detection), [代理信用评分系统](#credit-score)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/governance/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/index.ts)\n- [src/governance/charter.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/charter.ts)\n- [src/governance/policy.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/policy.ts)\n- [src/governance/policies/eu-ai-act.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/policies/eu-ai-act.ts)\n- [src/governance/audit.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/audit.ts)\n- [src/governance/audit-chain.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/audit-chain.ts)\n- [src/governance/spatial.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/spatial.ts)\n- [src/governance/runtime.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/runtime.ts)\n- [src/governance/approval.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/approval.ts)\n- [compliance/eu-ai-act-annex-iv.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/compliance/eu-ai-act-annex-iv.md)\n- [docs/aaif-rfc-agent-trust-attestation.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/docs/aaif-rfc-agent-trust-attestation.md)\n \n\n# 治理与合规框架\n\n## 概述\n\nMnemoPay SDK 的治理与合规框架是为 AI Agent 提供的一套完整的经济治理、安全审计和监管合规系统。该框架确保 Agent 在执行支付、记忆存储和资源使用等关键操作时遵循预定义的业务规则、预算限制和法规要求。\n\n根据架构文档，治理框架包含以下核心组件：\n\n| 组件 | 功能 | 类别 |\n|------|------|------|\n| Charter (宪章) | 定义 Agent 任务范围和权限边界 | 任务治理 |\n| FiscalGate (财务门控) | 预算执行和费用控制 | 财务治理 |\n| Article 12 (第12条) | EU AI Act 合规要求 | 法规合规 |\n| MerkleAudit (默克尔审计) | 加密审计链和不可篡改记录 | 审计追溯 |\n\n资料来源：[README.md - Architecture](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 核心架构\n\n治理框架采用分层架构设计，从运行时决策到长期审计形成完整闭环：\n\n```mermaid\ngraph TD\n A[Agent 请求] --> B[宪章验证 Charter]\n B --> C{权限检查}\n C -->|通过| D[FiscalGate 预算验证]\n C -->|拒绝| E[请求拦截]\n D --> F{预算充足?}\n F -->|是| G[Article 12 合规检查]\n F -->|否| H[预算超限拦截]\n G --> I{合规判定}\n I -->|通过| J[运行时 Runtime]\n I -->|拒绝| K[合规拦截]\n J --> L[操作执行]\n L --> M[审计记录 Audit]\n M --> N[审计链 Chain]\n N --> O[默克尔根 MerkleRoot]\n```\n\n## 宪章系统 (Charter)\n\n### 功能定义\n\n宪章系统定义了每个 Agent 的任务范围、操作权限和资源配额。它是所有治理决策的第一道关卡。\n\n### 核心配置\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `scope` | string[] | 允许的操作类型列表 |\n| `maxBudget` | number | 最大预算限额 |\n| `permissions` | Permission[] | 细粒度权限配置 |\n| `ttl` | number | 宪章有效期（秒） |\n| `version` | string | 宪章版本号 |\n\n资料来源：[src/governance/charter.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/charter.ts)\n\n## 财务门控 (FiscalGate)\n\n### 预算执行机制\n\nFiscalGate 负责在交易执行前验证预算是否充足，并在操作完成后更新实际支出。\n\n```mermaid\ngraph LR\n A[charge 请求] --> B[获取宪章预算]\n B --> C{当前支出}\n C --> D{支出 + 本次金额 <= 预算?}\n D -->|是| E[执行 charge]\n D -->|否| F[触发 overLimit]\n E --> G[更新计量 metering]\n F --> H[记录违规事件]\n```\n\n### 计量数据模型\n\n```typescript\ninterface Metering {\n total: number; // 总支出\n seats: number; // 活跃席位\n missions: Mission[]; // 任务记录\n overLimit: boolean; // 是否超限\n}\n```\n\n资料来源：[src/governance/runtime.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/runtime.ts)\n\n## 策略系统 (Policy)\n\n### 策略引擎架构\n\n策略系统提供可扩展的规则引擎，支持自定义合规策略和第三方监管要求。\n\n### EU AI Act 合规\n\n根据 EU AI Act Annex IV 要求，系统实现了以下合规检查：\n\n| 检查项 | 描述 | 风险等级 |\n|--------|------|----------|\n| 目的限制 | 验证操作符合声明用途 | 高 |\n| 人类监督 | 确保关键决策有人工介入 | 高 |\n| 准确性 | 验证模型输出的可靠性 | 中 |\n| 韧性 | 错误处理和异常恢复 | 中 |\n| 安全性 | 数据保护和访问控制 | 高 |\n| 透明性 | 操作日志和可解释性 | 中 |\n\n资料来源：[src/governance/policies/eu-ai-act.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/policies/eu-ai-act.ts)\n\n### 策略配置示例\n\n```typescript\nconst policy = {\n id: 'eu-ai-act-high-risk',\n version: '1.0',\n rules: [\n { type: 'human_oversight', threshold: 0.95 },\n { type: 'data_minimization', scope: ['pii', 'financial'] },\n { type: 'audit_trail', retention: 365 }\n ]\n};\n```\n\n资料来源：[src/governance/policy.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/policy.ts)\n\n## 审计系统 (Audit)\n\n### 审计链架构\n\n审计系统采用默克尔树（Merkle Tree）结构确保审计记录的不可篡改性。\n\n```mermaid\ngraph TD\n A[操作事件] --> B[生成审计记录]\n B --> C[计算哈希]\n C --> D[添加到叶节点]\n D --> E{批量达到阈值?}\n E -->|是| F[计算默克尔根]\n E -->|否| G[缓存待处理]\n F --> H[发布到审计链]\n H --> I[存储证明]\n```\n\n### 审计记录结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 唯一标识符 |\n| `timestamp` | number | Unix 时间戳 |\n| `agentId` | string | Agent 标识 |\n| `action` | string | 操作类型 |\n| `result` | string | 执行结果 |\n| `metadata` | object | 附加元数据 |\n| `hash` | string | 记录哈希值 |\n\n### 默克尔证明\n\n每个审计记录包含指向前一记录的哈希链接，形成链式结构：\n\n```typescript\ninterface AuditRecord {\n record: AuditData;\n prevHash: string;\n merkleProof?: MerkleProof;\n}\n```\n\n资料来源：[src/governance/audit-chain.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/audit-chain.ts)\n\n### 审计 Bundle\n\n审计 Bundle 是批量打包的审计记录，支持高效的批量验证和存储：\n\n```typescript\ninterface AuditBundle {\n id: string;\n records: AuditRecord[];\n merkleRoot: string;\n timestamp: number;\n signature: string;\n}\n```\n\n资料来源：[src/governance/audit.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/audit.ts)\n\n## 运行时治理 (Runtime)\n\n### 运行时决策流程\n\n运行时系统负责在操作执行期间进行实时监控和干预。\n\n```mermaid\ngraph TD\n A[操作开始] --> B[加载宪章]\n B --> C[权限检查]\n C --> D{权限验证}\n D -->|通过| E[加载策略]\n D -->|拒绝| F[抛出 PolicyViolation]\n E --> G[执行前钩子 preHook]\n G --> H{前置条件满足?}\n H -->|是| I[执行业务逻辑]\n H -->|否| J[拒绝操作]\n I --> K[执行后钩子 postHook]\n K --> L[更新审计链]\n L --> M[返回结果]\n```\n\n### 异常处理\n\n运行时支持多种异常类型：\n\n| 异常类型 | 触发条件 | 处理策略 |\n|----------|----------|----------|\n| `PolicyViolation` | 策略检查失败 | 拒绝并记录 |\n| `BudgetExceeded` | 预算超限 | 冻结操作 |\n| `PermissionDenied` | 权限不足 | 降级或拒绝 |\n| `ComplianceFailure` | 合规检查失败 | 阻断交易 |\n\n资料来源：[src/governance/runtime.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/runtime.ts)\n\n## 空间治理 (Spatial)\n\n### 概念定义\n\n空间治理定义了 Agent 的操作边界和资源隔离域。\n\n```typescript\ninterface SpatialContext {\n namespace: string; // 命名空间标识\n boundaries: Boundary[]; // 边界限制\n isolation: boolean; // 是否隔离\n}\n```\n\n### 边界类型\n\n| 类型 | 说明 | 约束 |\n|------|------|------|\n| `memory` | 记忆存储边界 | 存储量上限 |\n| `compute` | 计算资源边界 | CPU/内存配额 |\n| `network` | 网络访问边界 | 出站请求限制 |\n| `finance` | 财务操作边界 | 交易金额限制 |\n\n资料来源：[src/governance/spatial.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/spatial.ts)\n\n## 审批流程 (Approval)\n\n### 工作流状态机\n\n关键操作需要人工审批，审批流程遵循状态机模式：\n\n```mermaid\ngraph LR\n A[Pending] -->|提交| B[Awaiting Review]\n B -->|批准| C[Approved]\n B -->|拒绝| D[Rejected]\n C -->|执行| E[Completed]\n D -->|申诉| F[Under Appeal]\n F -->|重新审查| B\n E -->|失败| G[Failed]\n```\n\n### 审批配置\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `requireApproval` | true | 是否需要审批 |\n| `approvers` | string[] | 审批者列表 |\n| `timeout` | 86400 | 超时时间（秒） |\n| `autoEscalate` | false | 超时自动升级 |\n\n资料来源：[src/governance/approval.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/approval.ts)\n\n## 合规框架集成\n\n### EU AI Act 合规清单\n\n根据 Annex IV 要求，MnemoPay SDK 实现了以下技术文档要求：\n\n| 要求 | 实现状态 | 组件 |\n|------|----------|------|\n| 系统描述 | ✅ | Charter |\n| 训练数据来源 | ✅ | Memory Module |\n| 模型架构 | ✅ | Agent Core |\n| 决策逻辑 | ✅ | Runtime |\n| 人类监督措施 | ✅ | Approval |\n| 准确性评估 | ✅ | Audit |\n| 风险评估报告 | ✅ | Policy Engine |\n\n资料来源：[compliance/eu-ai-act-annex-iv.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/compliance/eu-ai-act-annex-iv.md)\n\n### Agent 信任证明 (AAIF)\n\n系统支持 Agent 身份和行为的信任证明机制：\n\n```typescript\ninterface AgentTrustAttestation {\n agentId: string;\n charterHash: string;\n auditRoot: string;\n complianceLevel: 'basic' | 'standard' | 'enhanced';\n issuedAt: number;\n expiresAt: number;\n signature: string;\n}\n```\n\n资料来源：[docs/aaif-rfc-agent-trust-attestation.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/docs/aaif-rfc-agent-trust-attestation.md)\n\n## 快速开始\n\n### 初始化治理上下文\n\n```typescript\nimport { GovernanceContext } from '@mnemopay/sdk/governance';\n\nconst ctx = new GovernanceContext({\n charter: {\n scope: ['memory:remember', 'memory:recall', 'payment:charge'],\n maxBudget: 1000,\n permissions: ['read:profile', 'write:transaction']\n },\n policy: 'eu-ai-act-standard',\n requireApproval: true\n});\n```\n\n### 执行受治理的操作\n\n```typescript\nconst result = await ctx.execute('payment:charge', {\n amount: 50,\n currency: 'USD',\n recipient: 'agent-123'\n});\n\n// 审计记录自动生成\nconsole.log(result.auditId); // 审计追踪ID\n```\n\n## API 参考\n\n### GovernanceContext\n\n| 方法 | 参数 | 返回值 | 说明 |\n|------|------|--------|------|\n| `execute(action, params)` | 操作类型, 参数对象 | ExecutionResult | 执行受治理操作 |\n| `verifyPolicy(record)` | 审计记录 | boolean | 验证策略合规性 |\n| `getMerkleProof(auditId)` | 审计ID | MerkleProof | 获取默克尔证明 |\n| `exportAuditBundle()` | 无 | AuditBundle | 导出审计包 |\n\n资料来源：[src/governance/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/index.ts)\n\n## 最佳实践\n\n### 1. 宪章配置\n\n- 遵循最小权限原则，仅授予必要权限\n- 设置合理的预算上限和 TTL\n- 定期审核和更新宪章版本\n\n### 2. 审计策略\n\n- 确保所有敏感操作都生成审计记录\n- 定期导出和验证审计 Bundle\n- 保留足够长度的审计历史（建议 365+ 天）\n\n### 3. 合规检查\n\n- 对高风险操作启用人工审批\n- 定期运行 EU AI Act 合规检查\n- 维护完整的信任证明链\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：mnemopay/mnemopay-sdk\n\n摘要：发现 8 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 涉及密钥、隐私或敏感领域。\n\n## 1. 安全/权限坑 · 涉及密钥、隐私或敏感领域\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。\n- 对用户的影响：金融、交易、隐私和密钥场景必须比普通工具更保守。\n- 建议检查：补敏感数据流、密钥存储和权限边界审查。\n- 防护动作：敏感领域或密钥场景必须保守推荐并要求人工复核。\n- 证据：packet_text.keyword_scan | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | matched secret / private key / privacy / trading / finance keyword\n\n## 2. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `mnemopay-sdk` 与安装入口 `@mnemopay/sdk` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npm install @mnemopay/sdk`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | repo=mnemopay-sdk; install=@mnemopay/sdk\n\n## 3. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | README/documentation is current enough for a first validation pass.\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | no_demo; severity=medium\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | release_recency=unknown\n\n\n",
"markdown_key": "mnemopay-sdk",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1197975871",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/mnemopay/mnemopay-sdk"
},
{
"evidence_id": "art_797bd2c621934f13bff10e9e3de1dc3e",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/mnemopay/mnemopay-sdk#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "mnemopay-sdk 说明书",
"toc": [
"https://github.com/mnemopay/mnemopay-sdk 项目说明书",
"目录",
"项目概述",
"项目简介",
"核心版本信息",
"技术架构",
"核心子系统详解",
"开发工作流",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": false,
"repo_commit": null,
"repo_inspection_error": null,
"repo_inspection_files": [],
"repo_inspection_verified": false,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @mnemopay/sdk - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @mnemopay/sdk 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`claude-plugin/skills/balance/SKILL.md`, `claude-plugin/skills/charge/SKILL.md`, `claude-plugin/skills/fico/SKILL.md`, `claude-plugin/skills/history/SKILL.md` 等 Claim：`clm_0005` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`claude-plugin/skills/balance/SKILL.md`, `claude-plugin/skills/charge/SKILL.md`, `claude-plugin/skills/fico/SKILL.md`, `claude-plugin/skills/history/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`claude-plugin/.claude-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0003` supported 0.86\n\n## 怎么开始\n\n- `npm install @mnemopay/sdk # stable (v1.5.x)` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npm install @mnemopay/sdk@alpha # v1.6.x preview — Stripe MPP + x402 + Google AP2 rails` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npm install @mnemopay/sdk@alpha` 证据：`README.md` Claim：`clm_0007` supported 0.86, `clm_0008` supported 0.86\n- `npx @mnemopay/sdk init` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `claude mcp add mnemopay -s user -- npx -y @mnemopay/sdk` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `npx @mnemopay/sdk --tools=all # all 40 tools` 证据：`README.md` Claim：`clm_0011` supported 0.86\n- `npx @mnemopay/sdk --tools=agent # essentials + commerce + hitl + payments + webhooks` 证据：`README.md` Claim：`clm_0012` supported 0.86\n- `npx @mnemopay/sdk --tools=fico # Agent Credit Score only` 证据：`README.md` Claim：`clm_0013` supported 0.86\n- `npm install # install deps` 证据：`CLAUDE.md` Claim：`clm_0014` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`claude-plugin/skills/balance/SKILL.md`, `claude-plugin/skills/charge/SKILL.md`, `claude-plugin/skills/fico/SKILL.md`, `claude-plugin/skills/history/SKILL.md` 等 Claim：`clm_0005` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`claude-plugin/skills/balance/SKILL.md`, `claude-plugin/skills/charge/SKILL.md`, `claude-plugin/skills/fico/SKILL.md`, `claude-plugin/skills/history/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：多宿主安装与分发**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`claude-plugin/.claude-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0003` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`CLAUDE.md`, `GEMINI.md`, `claude-plugin/.claude-plugin/plugin.json`, `claude-plugin/skills/balance/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`claude-plugin/.claude-plugin/plugin.json`\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`CLAUDE.md`, `README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`CLAUDE.md`, `GEMINI.md`, `claude-plugin/.claude-plugin/plugin.json`, `claude-plugin/skills/balance/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`CLAUDE.md`, `README.md`, `claude-plugin/.claude-plugin/plugin.json`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `claude-plugin/README.md`, `src/mcp/server.ts`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0015` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`claude-plugin/.claude-plugin/plugin.json` Claim：`clm_0016` supported 0.86\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0017` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`claude-plugin/skills/balance/SKILL.md`, `claude-plugin/skills/charge/SKILL.md`, `claude-plugin/skills/fico/SKILL.md`, `claude-plugin/skills/history/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`claude-plugin/.claude-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0003` supported 0.86\n\n### 上下文规模\n\n- 文件总数：301\n- 重要文件覆盖：40/301\n- 证据索引条目：80\n- 角色 / Skill 条目：9\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @mnemopay/sdk 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @mnemopay/sdk 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @mnemopay/sdk 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 9 个角色 / Skill / 项目文档条目。\n\n- **balance**（skill）：Check the current balance and financial status of an AI agent. Use when the user asks about funds, balance, or how much money is available. 激活提示：当用户任务与“balance”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`claude-plugin/skills/balance/SKILL.md`\n- **charge**（skill）：Charge an AI agent for a service or tool invocation. Use when the user wants to bill for API calls, tool usage, or any metered service. 激活提示：当用户任务与“charge”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`claude-plugin/skills/charge/SKILL.md`\n- **fico**（skill）：Check the Agent FICO credit score 300-850 and reputation of an AI agent. Use when the user asks about creditworthiness, trust, reputation, or agent scoring. 激活提示：当用户任务与“fico”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`claude-plugin/skills/fico/SKILL.md`\n- **history**（skill）：View transaction history and financial records. Use when the user asks about past transactions, spending, or payment history. 激活提示：当用户任务与“history”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`claude-plugin/skills/history/SKILL.md`\n- **recall**（skill）：Search and retrieve information from the agent's persistent memory. Use when the user asks to recall, look up, or find previously stored information. 激活提示：当用户任务与“recall”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`claude-plugin/skills/recall/SKILL.md`\n- **remember**（skill）：Store information in the agent's persistent memory. Use when the user wants to save facts, preferences, decisions, or any data for future recall. 激活提示：当用户任务与“remember”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`claude-plugin/skills/remember/SKILL.md`\n- **settle**（skill）：Settle pending transactions and release escrow. Use when the user wants to finalize payments, release held funds, or settle outstanding balances. 激活提示：当用户任务与“settle”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`claude-plugin/skills/settle/SKILL.md`\n- **shop**（skill）：Search for products and make purchases using autonomous shopping with escrow. Use when the user wants to buy something, search for products, or manage orders. 激活提示：当用户任务与“shop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`claude-plugin/skills/shop/SKILL.md`\n- **mnemopay**（skill）： 激活提示：当用户任务与“mnemopay”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`integrations/openclaw/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **MnemoPay SDK**（documentation）：AI agent trust & reputation SDK — memory + payments + identity + Agent Credit Score in one package. 证据：`CLAUDE.md`\n- **MnemoPay SDK - Context & Instructions**（documentation）：MnemoPay SDK - Context & Instructions 证据：`GEMINI.md`\n- **MnemoPay**（documentation）：The governance layer for AI agents that handle money. Charter-driven mission scope, FiscalGate budget enforcement, EU AI Act Article 12 audit bundles, Agent Credit Score 300-850 , and a tamper-evident MerkleAudit chain — across every payment rail an agent will ever touch. 证据：`README.md`\n- **MnemoPay Claude Code Plugin**（documentation）：Payment infrastructure for AI agents. Gives Claude Code a full financial stack: charge for services, manage balances, shop autonomously with escrow, track credit scores, and persist memories with cryptographic integrity. 证据：`claude-plugin/README.md`\n- **AgentOps-Bench**（documentation）：A public, reproducible benchmark for evaluating production agent deployments — not just memory, not just planning, not just tool use. Four pillars: memory , payments , identity , integrity . 证据：`benchmark/agentops-bench/README.md`\n- **LongMemEval Benchmark for MnemoPay**（documentation）：Benchmark adapter for LongMemEval https://github.com/xiaowu0162/LongMemEval ICLR 2025 , evaluating MnemoPay's memory system on 500 long-term conversation memory questions across 5 cognitive abilities. 证据：`benchmark/longmemeval/README.md`\n- **MnemoPay for Agno**（documentation）：Give any Agno agent persistent memory and micropayment capabilities. 证据：`integrations/agno/README.md`\n- **MnemoPay for Microsoft AutoGen**（documentation）：Give any AutoGen agent persistent memory and micropayment capabilities. 证据：`integrations/autogen/README.md`\n- **MnemoPay for Composio**（documentation）：Give any Composio-powered agent persistent memory and micropayments. Works with every framework Composio supports CrewAI, AutoGen, LangChain, Agno, etc. . 证据：`integrations/composio/README.md`\n- **MnemoPay for CrewAI**（documentation）：Give any CrewAI crew persistent cognitive memory and micropayment capabilities. 证据：`integrations/crewai/README.md`\n- **MnemoPay for Goose**（documentation）：Give any Goose https://github.com/block/goose agent persistent memory, micropayments, and fraud-aware trust scoring. 证据：`integrations/goose/README.md`\n- **MnemoPay Plugin for Hermes Agent**（documentation）：Give Hermes persistent cognitive memory and a micropayment wallet. 证据：`integrations/hermes-plugin/README.md`\n- **MnemoPay for Huawei AgentArts**（documentation）：Connect MnemoPay to Huawei's AgentArts https://www.huaweicloud.com/intl/en-us/product/pangulargemodels.html platform as an MCP service. 证据：`integrations/huawei-agentarts/README.md`\n- **MnemoPay x Lightning Network**（documentation）：Bridge MnemoPay's memory and trust layer with Lightning Network payments. 证据：`integrations/lightning/README.md`\n- **MnemoPay for OpenAI Agents SDK**（documentation）：Give any OpenAI agent persistent memory and micropayment capabilities. 证据：`integrations/openai-agents/README.md`\n- **MnemoPay for Pydantic AI**（documentation）：Give any Pydantic AI agent persistent memory and micropayment capabilities. 证据：`integrations/pydantic-ai/README.md`\n- **MnemoPay hosted Python client**（documentation）：Dependency-free Python client for the hosted MnemoPay API. 证据：`integrations/python-hosted/README.md`\n- **MnemoPay x x402 Trust Middleware**（documentation）：Add persistent memory, trust scoring, and fraud detection to x402 https://x402.org payments. 证据：`integrations/x402/README.md`\n- **Package**（package_manifest）：{ \"name\": \"mnemopay-dashboard\", \"version\": \"0.2.0\", \"private\": true, \"type\": \"commonjs\", \"description\": \"Hosted MnemoPay console/dashboard\", \"scripts\": { \"start\": \"node server.js\", \"test:unit\": \"node auth-email.test.cjs && node console-postgres-store.test.cjs && node stripe-billing.test.cjs && node drip-queue.test.cjs && node logger.test.cjs && node rate-limit.test.cjs && node metrics.test.cjs && node idempotency.test.cjs\", \"test:smoke\": \"node server.smoke.test.cjs\", \"test\": \"npm run test:unit && npm run test:smoke\" }, \"dependencies\": { \"@mnemopay/sdk\": \"^1.5.0\", \"better-sqlite3\": \"^11.5.0\", \"pg\": \"^8.16.3\" }, \"optionalDependencies\": { \"@xenova/transformers\": \"^2.17.2\" } } 证据：`dashboard/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@mnemopay/sdk\", \"mcpName\": \"com.mnemopay/sdk\", \"version\": \"1.8.0-alpha.0\", \"description\": \"Production payment infrastructure for AI agents — real Stripe/Paystack/Lightning rails, autonomous shopping with escrow, Agent Credit Score 300-850 , Ed25519 identity, behavioral finance, Merkle integrity, anomaly detection, human-in-the-loop approval. Battle-tested.\", \"main\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" }, \"./middleware/openai\": { \"import\": \"./dist/middleware/openai.js\", \"types\": \"./dist/middleware/openai.d.ts\" }, \"./middleware/anthropic\": { \"import\": \"./dist/middleware/anthropic.js\", \"types\": \".… 证据：`package.json`\n- **Contributing to MnemoPay SDK**（documentation）：Thanks for your interest. MnemoPay is the trust + reputation substrate for AI agents that handle money — every PR touches code that real agents will use to authorize real payments, so the bar is high. 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"@mnemopay/benchmark-longmemeval\", \"version\": \"1.0.0\", \"private\": true, \"description\": \"LongMemEval ICLR 2025 benchmark adapter for MnemoPay memory system\", \"type\": \"module\", \"scripts\": { \"download\": \"bash scripts/download-data.sh\", \"ingest\": \"tsx ingest.ts\", \"evaluate\": \"tsx evaluate.ts\", \"bench\": \"bash run.sh\", \"bench:oracle\": \"bash run.sh oracle\", \"bench:small\": \"bash run.sh s\", \"bench:medium\": \"bash run.sh m\" }, \"dependencies\": { \"@anthropic-ai/sdk\": \"^0.39.0\", \"@mnemopay/sdk\": \"file:../../\" }, \"devDependencies\": { \"tsx\": \"^4.19.0\", \"@types/node\": \"^22.0.0\", \"typescript\": \"^5.7.0\" } } 证据：`benchmark/longmemeval/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@mnemopay/langchain\", \"version\": \"1.1.0\", \"description\": \"MnemoPay tools for LangChain/LangGraph — agent memory + wallet\", \"main\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" } }, \"files\": \"dist\", \"README.md\" , \"scripts\": { \"build\": \"tsc\", \"prepublishOnly\": \"npm run build\" }, \"keywords\": \"langchain\", \"langgraph\", \"mnemopay\", \"agent\", \"memory\", \"wallet\", \"tools\" , \"author\": \"Jeremiah Omiagbo \", \"license\": \"MIT\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/mnemopay/mnemopay-sdk.git\", \"directory\": \"integrations/langchain\" }, \"homepage\": \"https://github.com/mnemopay/mnemopay-sdk/tree/main/int… 证据：`integrations/langchain/package.json`\n- **Balance**（skill_instruction）：Use the MnemoPay MCP balance tool to check the agent's current balance. 证据：`claude-plugin/skills/balance/SKILL.md`\n- **Charge**（skill_instruction）：Use the MnemoPay MCP charge tool to bill an agent for a service. 证据：`claude-plugin/skills/charge/SKILL.md`\n- **Agent FICO Score**（skill_instruction）：Use the MnemoPay MCP agent fico score tool to check an agent's credit score. 证据：`claude-plugin/skills/fico/SKILL.md`\n- **Transaction History**（skill_instruction）：Use the MnemoPay MCP history tool to view past transactions. 证据：`claude-plugin/skills/history/SKILL.md`\n- **Recall**（skill_instruction）：Use the MnemoPay MCP recall tool to search persistent memory. 证据：`claude-plugin/skills/recall/SKILL.md`\n- **Remember**（skill_instruction）：Use the MnemoPay MCP remember tool to store information in persistent memory. 证据：`claude-plugin/skills/remember/SKILL.md`\n- **Settle**（skill_instruction）：Use the MnemoPay MCP settle tool to finalize pending transactions. 证据：`claude-plugin/skills/settle/SKILL.md`\n- **Shop**（skill_instruction）：Use MnemoPay's commerce tools for autonomous shopping with escrow protection. 证据：`claude-plugin/skills/shop/SKILL.md`\n- **MnemoPay — Agent Memory + Wallet**（skill_instruction）：Give any AI agent persistent memory and a micropayment wallet. MnemoPay unifies cognitive memory Mnemosyne and escrow economics AgentPay into a single MCP server. The core innovation: payment outcomes reinforce the memories that led to successful decisions. 证据：`integrations/openclaw/SKILL.md`\n- **Plugin**（structured_config）：{ \"name\": \"mnemopay\", \"description\": \"Payment infrastructure for AI agents — Agent Credit Score 300-850 , real payment rails Stripe/Paystack/Lightning , autonomous shopping with escrow, hash-chained ledger, behavioral finance. 100K-operation stress tested.\", \"version\": \"1.2.0\", \"author\": { \"name\": \"Jeremiah Omiagbo\", \"url\": \"https://github.com/mnemopay\" }, \"homepage\": \"https://github.com/mnemopay/mnemopay-sdk\", \"repository\": \"https://github.com/mnemopay/mnemopay-sdk\", \"license\": \"Apache-2.0\" } 证据：`claude-plugin/.claude-plugin/plugin.json`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Auto-Observer Middleware — Design Note**（documentation）：Auto-Observer Middleware — Design Note 证据：`docs/AUTO-OBSERVER-DESIGN.md`\n- **Work Pattern reusable**（documentation）：Paste this block into any repo's CLAUDE.md to install the research → build → automate discipline. Jerry wants this across every project. 证据：`docs/CLAUDE-WORK-PATTERN.md`\n- **MnemoPay product upgrade roadmap**（documentation）：Use this as the public product frame: 证据：`docs/PRODUCT-UPGRADE-ROADMAP-2026-05.md`\n- **RFC: Agent Trust Attestation Protocol ATAP**（documentation）：RFC: Agent Trust Attestation Protocol ATAP 证据：`docs/aaif-rfc-agent-trust-attestation.md`\n- **Agent Memory State-of-the-Art — Deep Research Pass 2026-04-20**（documentation）：Agent Memory State-of-the-Art — Deep Research Pass 2026-04-20 证据：`docs/agent-memory-sota-2026-04.md`\n- **Claude Agent SDK + MnemoPay Integration Guide**（documentation）：Claude Agent SDK + MnemoPay Integration Guide 证据：`docs/agent-sdk-guide.md`\n- **Claude Design — Paste-Ready Prompts for MnemoPay**（documentation）：Claude Design — Paste-Ready Prompts for MnemoPay 证据：`docs/pitch/claude-design-prompts.md`\n- **MnemoPay — EU AI Act Pitch targeted**（documentation）：MnemoPay — EU AI Act Pitch targeted 证据：`docs/pitch/eu-ai-act-pitch.md`\n- **MnemoPay — Seed Round Deck 2026**（documentation）：Use this as a the source-of-truth script when talking through the deck, and b the content to paste into Claude Design see claude-design-prompts.md for the design brief . 证据：`docs/pitch/investor-deck.md`\n- **Linux Foundation reply — Christina Harter + Matt White**（documentation）：Linux Foundation reply — Christina Harter + Matt White 证据：`docs/pitch/linux-foundation-reply.md`\n- **MnemoPay — One-Pager**（documentation）：Paste the design brief from claude-design-prompts.md § 2 into Claude Design for the visual PDF. This file is the copy source-of-truth. 证据：`docs/pitch/one-pager.md`\n- **MCP Hive Founding-100 \"Project Ignite\" application — MnemoPay**（documentation）：MCP Hive Founding-100 \"Project Ignite\" application — MnemoPay 证据：`docs/strategy-2026-05-06/mcp-hive-application.md`\n- **Praetor → MnemoPay merge + repo split — execution plan**（documentation）：Praetor → MnemoPay merge + repo split — execution plan 证据：`docs/strategy-2026-05-06/praetor-split-execution-plan.md`\n- **Strategy session 2026-05-06 — what was decided + what was drafted**（documentation）：Strategy session 2026-05-06 — what was decided + what was drafted 证据：`docs/strategy-2026-05-06/session-summary.md`\n- **MnemoPay SDK — Benchmarks**（documentation）：Reproducible stress benchmarks for the MnemoPay SDK. Numbers below are from actual runs on commodity hardware — no ad-hoc synthetic shortcuts, no mocking of the payment path. Every operation goes through the same code paths a production agent would take. 证据：`BENCHMARKS.md`\n- **Changelog**（documentation）：All notable changes to @mnemopay/sdk are documented here. Format follows Keep a Changelog https://keepachangelog.com/en/1.1.0/ ; versions follow SemVer https://semver.org/ . 证据：`CHANGELOG.md`\n- **MnemoPay Design System Stripe-Inspired**（documentation）：MnemoPay Design System Stripe-Inspired 证据：`DESIGN.md`\n- **Security Policy**（documentation）：Version Supported --------- ----------- 1.7.x Yes — current stable 1.8.x-alpha Yes — preview channel 1.6.x Critical fixes only < 1.6 No 证据：`SECURITY.md`\n- **Annex IV Technical Documentation — @mnemopay/sdk**（documentation）：Annex IV Technical Documentation — @mnemopay/sdk 证据：`compliance/eu-ai-act-annex-iv.md`\n- **MnemoPay dashboard deployment**（documentation）：This dashboard is the hosted MnemoPay console: Brain, billing, usage, audit, members, and developer keys. 证据：`dashboard/DEPLOYMENT.md`\n- **vectorless RAG, in 500 lines of typescript**（documentation）：vectorless RAG, in 500 lines of typescript 证据：`marketing/blog-treeindex-vectorless-rag.md`\n- **Tweet drafts — TreeIndex launch**（documentation）：Two options. The single is the standalone post; the thread is for when the blog goes live and we need amplification. 证据：`marketing/tweet-treeindex-launch.md`\n- **SOC 2 prep**（documentation）：MnemoPay is not ready for a Type II audit yet, but it can start collecting evidence now. This file is the operating checklist until a formal compliance tool is adopted. 证据：`ops/SOC2-PREP-2026-05.md`\n- **Workflow Functional Audit — 2026-04-23**（documentation）：Workflow Functional Audit — 2026-04-23 证据：`ops/workflow-audit-2026-04-23.md`\n- **MnemoPay — Premium Video Scripts Production-Ready**（documentation）：MnemoPay — Premium Video Scripts Production-Ready HeyGen Avatar Shot + Seedance 2.0 Voiceover: Confident, measured, slightly amused 证据：`site/video-scripts-v2.md`\n- **MnemoPay Video Ad Scripts**（documentation）：MnemoPay Video Ad Scripts HeyGen Avatar Shot + Seedance 2.0 证据：`site/video-scripts.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`CLAUDE.md`, `GEMINI.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`CLAUDE.md`, `GEMINI.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n - source_paths: README.md, package.json, LICENSE, NOTICE\n- **快速开始**：importance `high`\n - source_paths: examples/01-quick-start.ts, examples/06-production.ts, src/index.ts, src/client.ts\n- **内存与记忆系统**：importance `high`\n - source_paths: src/recall/engine.ts, src/recall/entities.ts, src/recall/graph.ts, src/recall/hyde.ts, src/recall/observations.ts\n- **账本与支付系统**：importance `high`\n - source_paths: src/ledger.ts, src/commerce.ts, src/commerce/checkout/executor.ts, src/commerce/checkout/strategies/generic.ts, src/commerce/checkout/strategies/shopify.ts\n- **身份与认证系统**：importance `high`\n - source_paths: src/identity.ts, src/identity/index.ts, src/identity/did.ts, src/identity/wallet.ts, src/identity/bundle.ts\n- **代理信用评分系统**：importance `high`\n - source_paths: src/fico.ts, src/behavioral.ts, src/subagent-cost.ts\n- **行为金融引擎**：importance `medium`\n - source_paths: src/behavioral.ts, src/reasoning/post-processor.ts\n- **异常检测系统**：importance `high`\n - source_paths: src/anomaly.ts, src/fraud.ts, src/fraud-ml.ts, src/recall/rerank.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: false\n- repo_inspection_verified: false\n- repo_commit: `unknown`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 涉及密钥、隐私或敏感领域\n\n- Trigger: 项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。\n- Host AI rule: 补敏感数据流、密钥存储和权限边界审查。\n- Why it matters: 金融、交易、隐私和密钥场景必须比普通工具更保守。\n- Evidence: packet_text.keyword_scan | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | matched secret / private key / privacy / trading / finance keyword\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `mnemopay-sdk` 与安装入口 `@mnemopay/sdk` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | repo=mnemopay-sdk; install=@mnemopay/sdk\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：mnemopay/mnemopay-sdk\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 涉及密钥、隐私或敏感领域（high）：金融、交易、隐私和密钥场景必须比普通工具更保守。 建议检查：补敏感数据流、密钥存储和权限边界审查。\n- 仓库名和安装名不一致（medium）：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/mnemopay/mnemopay-sdk 项目说明书\n\n生成时间：2026-05-15 05:38:18 UTC\n\n## 目录\n\n- [项目概述](#getting-started)\n- [快速开始](#quick-start)\n- [内存与记忆系统](#memory-system)\n- [账本与支付系统](#ledger-payments)\n- [身份与认证系统](#identity-auth)\n- [代理信用评分系统](#credit-score)\n- [行为金融引擎](#behavioral-finance)\n- [异常检测系统](#anomaly-detection)\n- [支付轨道](#payment-rails)\n- [治理与合规框架](#governance)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[快速开始](#quick-start), [内存与记忆系统](#memory-system), [代理信用评分系统](#credit-score)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n- [dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n- [site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)\n- [site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n- [site/calculator.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/calculator.html)\n- [integrations/python-hosted/README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/python-hosted/README.md)\n \n\n# 项目概述\n\n## 项目简介\n\nMnemoPay SDK 是一个专为 AI Agent（人工智能代理）设计的支付与记忆基础设施开发工具包。该项目由 Jeremiah Omiagbo 创建，采用 Apache 2.0 开源许可证，为开发者提供了将货币化能力、持久化记忆和身份验证集成到 AI 代理应用中的完整解决方案。资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\nMnemoPay 不仅仅是一个 Stripe 包装器，而是一个为代理原生构建的完整支付系统，支持 Stripe、Paystack 和 Lightning（加密货币）三种支付通道。资料来源：[site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)\n\n## 核心版本信息\n\n| 版本类型 | 版本号 | 说明 |\n|---------|--------|------|\n| 稳定版 | v1.5.0 | 通过 `latest` 标签分发 |\n| 预发布版 | v1.6.0-alpha | 当前 alpha 测试版本 |\n\n资料来源：[README.md:27](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 技术架构\n\nMnemoPay SDK 的架构采用分层模块化设计，集成了多个核心子系统。以下是整体架构示意图：\n\n```mermaid\ngraph TB\n subgraph 顶层\n G[GOVERNANCE
Charter · FiscalGate
Article 12 · MerkleAudit]\n end\n \n subgraph 核心功能层\n M[Memory
remember · recall
reinforce · forget]\n P[Payments
charge · settle
refund · dispute]\n I[Identity
KYA · tokens
perms · killswitch]\n end\n \n subgraph 高级功能层\n C[Agent Credit Score
300-850 评分
5组件评分体系]\n B[Behavioral Finance
前景理论
行为引导]\n A[Anomaly Detection
EWMA + 指纹识别]\n end\n \n G --> M\n G --> P\n G --> I\n I --> C\n C --> B\n B --> A\n```\n\n资料来源：[README.md:28-42](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 核心子系统详解\n\n### 记忆系统（Memory）\n\n记忆系统为 AI Agent 提供了持久化和检索信息的能力，支持以下核心操作：\n\n| 方法 | 功能描述 |\n|------|----------|\n| `remember()` | 存储新记忆内容 |\n| `recall()` | 检索相关记忆 |\n| `reinforce()` | 强化重要记忆 |\n| `forget()` | 删除指定记忆 |\n\n该系统支持命名空间隔离，允许按业务领域组织记忆数据。资料来源：[integrations/python-hosted/README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/python-hosted/README.md)\n\n### 支付系统（Payments）\n\n支付系统支持完整的交易生命周期管理：\n\n```mermaid\ngraph LR\n A[charge
扣款] --> B[escrow
资金托管]\n B --> C{人工审批}\n C -->|通过| D[settle
结算]\n C -->|拒绝| E[refund
退款]\n D --> F[(Ledger
账本记录)]\n E --> F\n```\n\n| 支付通道 | 支持地区 | 特色功能 |\n|---------|---------|---------|\n| Paystack | 非洲（NGN, GHS, ZAR, KES） | 23家尼日利亚银行预映射，HMAC-SHA512 安全验证 |\n| Stripe | 全球（USD, EUR, GBP） | 手动捕获实现真实托管，支持135+种货币 |\n| Lightning | 加密货币 | 闪电网络即时结算 |\n\n资料来源：[site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)\n\n### 身份系统（Identity）\n\n身份系统包含四个关键组件：\n\n- **KYA（Know Your Agent）**：代理身份验证\n- **Tokens**：代币管理机制\n- **Permissions**：权限控制系统\n- **Killswitch**：紧急终止开关\n\n### Agent 信用评分（Agent Credit Score）\n\nMnemoPay 引入了一套基于 300-850 分值范围的信用评分体系，参考了传统金融信用评分模型。该评分系统包含五个核心评估维度：\n\n1. 支付历史分析\n2. 交易行为模式\n3. 账户活跃度\n4. 风险指标评估\n5. 身份验证等级\n\n资料来源：[README.md:33](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n### 行为金融模块（Behavioral Finance）\n\n基于前景理论（Prospect Theory）设计，提供用户行为引导和激励优化功能。该模块帮助开发者构建更符合用户心理预期的交易体验。资料来源：[README.md:38](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n### 异常检测模块（Anomaly Detection）\n\n采用指数加权移动平均（EWMA）算法结合指纹识别技术，实时监控和识别可疑交易行为。资料来源：[README.md:39](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n### 治理系统（Governance）\n\n治理模块包含四个核心组件：\n\n| 组件 | 功能 |\n|------|------|\n| Charter | 代理行为宪章 |\n| FiscalGate | 财务门控机制 |\n| Article 12 | 第12条合规条款 |\n| MerkleAudit | 默克尔树审计 |\n\n该模块负责任务范围界定、预算执行和审计捆绑。资料来源：[README.md:29-30](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 开发工作流\n\n基于 MnemoPay SDK 构建应用的标准流程包含四个步骤：\n\n```mermaid\ngraph TD\n A[1. 安装
npm install @mnemopay/sdk] --> B[2. 初始化
MnemoPay.quick agent-id]\n B --> C[3. 交易操作
charge · settle · refund]\n C --> D[4. 规模扩展
自主购物 · 多代理商务 · 信用评分]\n```\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n\n## 中间件集成\n\nMnemoPay SDK 提供与主流 AI 框架的中间件集成：\n\n| 框架 | 导入路径 | 说明 |\n|------|---------|------|\n| OpenAI | `@mnemopay/sdk/middleware/openai` | OpenAI API 中间件 |\n| Anthropic | `@mnemopay/sdk/middleware/anthropic` | Claude API 中间件 |\n| LangGraph | `@mnemopay/sdk/langgraph` | LangGraph 工具集成 |\n\n资料来源：[README.md:11-17](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## Python SDK 功能\n\nPython 集成包 `mnemopay` 提供了完整的功能接口：\n\n### 主要方法\n\n| 方法 | 参数 | 返回值 |\n|------|------|--------|\n| `remember(content, namespace, tags, importance)` | 内容、命名空间、标签、重要性 | 记忆 ID |\n| `recall(query, namespace, limit, mode)` | 查询词、命名空间、限制数、模式 | 相关记忆列表 |\n| `reason(query, namespace, limit, mode)` | 查询词、命名空间、限制数、模式 | 推理结果 |\n| `charge(amount, reason)` | 金额、原因 | 交易 ID |\n| `settle(tx_id)` | 交易 ID | 结算状态 |\n| `usage_report()` | - | 使用量报告 |\n| `audit_events(limit)` | 限制数 | 审计事件列表 |\n\n资料来源：[integrations/python-hosted/README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/python-hosted/README.md)\n\n## 仪表板功能\n\nMnemoPay 提供了一个功能丰富的 Web 仪表板（`dashboard/index.html`），包含以下模块：\n\n| 模块 | 功能描述 |\n|------|----------|\n| 账户概览 | 钱包余额、信誉评分、记忆数量、交易计数 |\n| 交易历史 | 完整交易记录与状态追踪 |\n| 实时日志 | 系统运行日志与事件流 |\n| 记忆管理 | 记忆 CRUD 操作与搜索 |\n| GitHub 监控 | 追踪上游仓库状态与 PR |\n| 计量仪表 | LLM 调用限额、席位数量 |\n| 任务管理 | 任务状态与完成进度 |\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n\n## 套餐定价\n\n| 套餐 | 价格 | 特性 |\n|------|------|------|\n| Starter | 免费 | 基础 SDK、10个代理、Stripe/Paystack/Lightning、Agent 信用评分 |\n| Pro | $49/月 | Starter 全部 + 文件/SQLite 持久化、交易分析仪表板、Webhook 通知、地理位置信任档案 |\n\n交易手续费：Pro 套餐按已结算交易的 1.5% 收取额外费用。资料来源：[site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)\n\n## 商业模式与防欺诈\n\nMnemoPay 提供了一个 chargeback（chargeback 防止）计算器工具，帮助用户评估 AI 代理引发的退款争议的实际成本，以及加密签名收据能为 SaaS 平台节省的费用。资料来源：[site/calculator.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/calculator.html)\n\n## 相关资源\n\n| 资源类型 | 链接 |\n|---------|------|\n| npm 包 | [@mnemopay/sdk](https://www.npmjs.com/package/@mnemopay/sdk) |\n| GitHub 仓库 | github.com/mnemopay/mnemopay-sdk |\n| 官方网站 | mnemopay.com |\n| 商业联系 | info@getbizsuite.com |\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目概述](#getting-started), [内存与记忆系统](#memory-system), [账本与支付系统](#ledger-payments)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/01-quick-start.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/examples/01-quick-start.ts)\n- [examples/06-production.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/examples/06-production.ts)\n- [src/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/index.ts)\n- [src/client.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/client.ts)\n- [README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n- [site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n- [site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)\n \n\n# 快速开始\n\n## 概述\n\n「快速开始」是 MnemoPay SDK 为开发者提供的最短路径集成方案。通过极简的初始化流程，开发者可以在数分钟内为 AI Agent 集成记忆管理、支付处理、身份认证和信用评分四大核心能力。\n\n核心特性：\n- **零配置启动**：`MnemoPay.quick(\"agent-id\")` 一行代码完成全部初始化\n- **完整能力栈**：内存记忆、钱包交易、KYA 身份验证、Agent 信用评分\n- **多支付通道**：支持 Stripe、Paystack、Lightning 三种主流支付轨道\n- **中间件生态**：开箱即用的 OpenAI、Anthropic、LangGraph 集成\n\n资料来源：[README.md:1-20]()\n\n## 安装\n\n### 环境要求\n\n| 依赖项 | 最低版本 | 说明 |\n|--------|----------|------|\n| Node.js | 18.0+ | SDK 运行时环境 |\n| npm/pnpm/yarn | 最新版 | 包管理器 |\n| API Key | MnemoPay 平台获取 | 连接后端服务 |\n\n### 安装命令\n\n```bash\nnpm install @mnemopay/sdk\n# 或\npnpm add @mnemopay/sdk\n```\n\n资料来源：[site/index.legacy.html:50-55]()\n\n## 基础使用\n\n### 快速初始化\n\n使用 `MnemoPay.quick()` 方法实现零配置启动：\n\n```typescript\nimport { MnemoPay } from \"@mnemopay/sdk\";\n\n// 方式一：快速初始化（推荐）\nconst mnemopay = MnemoPay.quick(\"my-agent-id\");\n\n// 方式二：显式配置\nconst mnemopay = MnemoPay.quick(\"my-agent-id\", {\n apiKey: \"mnemo_live_sk_xxxx\",\n environment: \"production\"\n});\n```\n\n`quick()` 方法自动完成以下初始化：\n1. 创建 Agent 身份标识\n2. 初始化内存存储（remember/recall）\n3. 配置钱包和支付通道\n4. 建立与管理平台的连接\n\n资料来源：[README.md:55-70](), [site/index.legacy.html:56-60]()\n\n### 核心 API 方法\n\n#### 内存管理\n\n| 方法 | 功能 | 返回值 |\n|------|------|--------|\n| `remember(key, value)` | 存储记忆 | `Promise` |\n| `recall(query)` | 检索记忆 | `Promise` |\n| `reinforce(memoryId)` | 强化记忆权重 | `Promise` |\n| `forget(memoryId)` | 删除记忆 | `Promise` |\n\n```typescript\n// 存储用户偏好\nawait mnemopay.remember(\"user_pref\", {\n name: \"张三\",\n tier: \"premium\"\n});\n\n// 检索相关记忆\nconst memories = await mnemopay.recall(\"用户 偏好 premium\");\n```\n\n#### 支付交易\n\n| 方法 | 功能 | 状态 |\n|------|------|------|\n| `charge(amount, reason)` | 请求收款 | 资金进入托管 |\n| `settle(transactionId)` | 确认结算 | 资金释放给 Agent |\n| `refund(transactionId)` | 退款 | 资金退回用户 |\n\n```typescript\n// 发起收款\nconst tx = await mnemopay.charge(25.00, \"API调用费用\");\nconsole.log(`交易 ID: ${tx.id}`);\n\n// 结算交易\nawait mnemopay.settle(tx.id);\n\n// 退款\nawait mnemopay.refund(tx.id);\n```\n\n资料来源：[site/index.legacy.html:62-70]()\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[安装 SDK] --> B[快速初始化]\n B --> C[Agent 获取身份]\n C --> D{选择操作}\n \n D --> E[内存管理]\n D --> F[支付交易]\n D --> G[身份验证]\n D --> H[信用查询]\n \n E --> E1[remember/recall]\n F --> F1[charge/settle/refund]\n G --> G1[KYA 验证]\n H --> H1[信用评分查询]\n \n F1 -->|资金托管| I[Escrow]\n I --> J{人类审批}\n J -->|批准| K[settle]\n J -->|拒绝| L[refund]\n```\n\n### 支付流程详解\n\n1. **Charge（收款请求）**：Agent 调用 `charge()` 后，资金进入第三方托管\n2. **Escrow（资金托管）**：资金暂存于 Stripe/Paystack/Lightning，直至人工审批\n3. **Settle（确认结算）**：人工审核通过后，`settle()` 将资金释放给 Agent\n4. **Refund（退款处理）**：交易被拒绝时调用，资金退回用户\n\n资料来源：[site/index.legacy.html:63-68](), [README.md:65-72]()\n\n## 中间件集成\n\n### OpenAI 中间件\n\n```typescript\nimport { mnemoPayMiddleware } from \"@mnemopay/sdk/middleware/openai\";\n```\n\n将 MnemoPay 支付能力无缝集成到 OpenAI 的 Agent 框架中。\n\n### Anthropic 中间件\n\n```typescript\nimport { mnemoPayMiddleware } from \"@mnemopay/sdk/middleware/anthropic\";\n```\n\n支持 Anthropic Claude 模型的支付回调集成。\n\n### LangGraph 工具集成\n\n```typescript\nimport { mnemoPayTools } from \"@mnemopay/sdk/langgraph\";\n```\n\n提供 LangGraph 可调用的支付工具节点。\n\n资料来源：[README.md:35-45]()\n\n## 生产环境配置\n\n### 生产模式初始化\n\n```typescript\nimport { MnemoPay } from \"@mnemopay/sdk\";\n\nconst mnemopay = MnemoPay.quick(\"production-agent\", {\n apiKey: process.env.MNEMO_API_KEY,\n environment: \"production\",\n persistence: \"sqlite\", // 数据持久化\n webhookUrl: \"https://yourapp.com/webhooks/mnemopay\"\n});\n```\n\n### 配置选项\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `apiKey` | `string` | 环境变量 | MnemoPay API 密钥 |\n| `environment` | `\"development\" \\| \"production\"` | `\"development\"` | 运行环境 |\n| `persistence` | `\"memory\" \\| \"file\" \\| \"sqlite\"` | `\"memory\"` | 数据存储方式 |\n| `webhookUrl` | `string` | `null` | Webhook 回调地址 |\n\n### 生产检查清单\n\n- [ ] 使用正式环境 API Key\n- [ ] 配置 Webhook 端点\n- [ ] 选择合适的持久化方案（生产环境推荐 SQLite）\n- [ ] 设置支付通道（Stripe/Paystack/Lightning）\n- [ ] 配置 KYA（Know Your Agent）验证流程\n\n资料来源：[examples/06-production.ts](), [site/index.html](), [site/index.legacy.html]()\n\n## 架构概览\n\n```mermaid\ngraph TB\n subgraph \"MnemoPay SDK v1.6.0\"\n A[MnemoPay.quick] --> B[Client]\n B --> C[Memory 模块]\n B --> D[Payments 模块]\n B --> E[Identity 模块]\n B --> F[Credit Score 模块]\n end\n \n C --> G[(本地存储)]\n D --> H[Stripe]\n D --> I[Paystack]\n D --> J[Lightning]\n E --> K[Token 验证]\n F --> L[行为分析]\n \n M[OpenAI 中间件] --> B\n N[Anthropic 中间件] --> B\n O[LangGraph 工具] --> B\n```\n\n### 模块职责\n\n| 模块 | 核心功能 | API |\n|------|----------|-----|\n| Memory | 记忆存储与检索 | `remember`, `recall`, `reinforce`, `forget` |\n| Payments | 支付交易处理 | `charge`, `settle`, `refund`, `dispute` |\n| Identity | Agent 身份验证 | KYA、Token、Permissions |\n| Credit Score | 信用评分系统 | 300-850 分信用评估 |\n\n资料来源：[README.md:15-45]()\n\n## 错误处理\n\n### 常见错误\n\n| 错误码 | 说明 | 解决方案 |\n|--------|------|----------|\n| `AUTH_FAILED` | API Key 无效 | 检查并更新 API Key |\n| `INSUFFICIENT_FUNDS` | 余额不足 | 确保账户有足够资金 |\n| `TRANSACTION_NOT_FOUND` | 交易不存在 | 检查交易 ID |\n| `AGENT_NOT_VERIFIED` | Agent 未验证 | 完成 KYA 流程 |\n\n### 错误处理示例\n\n```typescript\ntry {\n const tx = await mnemopay.charge(100, \"服务费\");\n} catch (error) {\n if (error.code === \"AUTH_FAILED\") {\n console.error(\"请检查 API Key 配置\");\n } else if (error.code === \"AGENT_NOT_VERIFIED\") {\n console.error(\"请先完成 Agent 身份验证\");\n }\n}\n```\n\n## 下一步\n\n| 资源 | 说明 |\n|------|------|\n| [完整 API 文档]() | 详细的 SDK API 参考 |\n| [支付集成指南]() | Stripe/Paystack/Lightning 配置 |\n| [记忆系统详解]() | 高级记忆管理功能 |\n| [Agent 信用评分]() | 信用评分机制说明 |\n| [Dashboard 使用指南]() | 管理平台功能介绍 |\n\n---\n\n**版本信息**：当前版本 v1.6.0-alpha，`latest` 稳定版为 v1.5.0\n\n资料来源：[README.md:10-12]()\n\n---\n\n\n\n## 内存与记忆系统\n\n### 相关页面\n\n相关主题：[项目概述](#getting-started), [异常检测系统](#anomaly-detection), [治理与合规框架](#governance)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/recall/engine.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/engine.ts)\n- [src/recall/entities.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/entities.ts)\n- [src/recall/graph.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/graph.ts)\n- [src/recall/hyde.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/hyde.ts)\n- [src/recall/observations.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/observations.ts)\n- [src/recall/persistence/memory.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/persistence/memory.ts)\n- [src/recall/persistence/neon.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/persistence/neon.ts)\n- [src/recall/persistence/sqlite.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/persistence/sqlite.ts)\n- [src/integrity.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/integrity.ts)\n- [src/identity/bundle.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity/bundle.ts)\n \n\n# 内存与记忆系统\n\n## 概述\n\nMnemoPay SDK 的内存与记忆系统是整个 SDK 的核心模块，负责为 AI Agent 提供持久化记忆能力。该系统使 Agent 能够跨会话保持上下文，实现真正的连续性和个性化交互。\n\n核心功能包括：\n\n- **语义记忆存储**：通过 `remember` 方法存储记忆，支持重要度评分和标签系统\n- **混合检索引擎**：`recall` 方法支持语义搜索和混合检索模式\n- **知识图谱**：基于实体和关系构建知识网络，支持图结构查询\n- **观察点再生**：自动更新实体关联的观察点内容\n- **行为强化**：基于交互结果自动调整记忆权重\n- **完整性校验**：使用 Merkle 树结构确保记忆数据不可篡改\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n---\n\n## 系统架构\n\n### 模块分层\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ SDK 入口层 │\n│ MnemoPay.quick() / MnemoPay() │\n├─────────────────────────────────────────────────────────────┤\n│ 核心 API 层 │\n│ remember | recall | reinforce | forget │\n├──────────────┬──────────────┬───────────────┬────────────────┤\n│ 检索引擎 │ 实体管理 │ 知识图谱 │ 观察点系统 │\n│ recall/ │ recall/ │ recall/ │ recall/ │\n│ engine.ts │ entities.ts │ graph.ts │ observations │\n├──────────────┴──────────────┴───────────────┴────────────────┤\n│ 持久化适配层 │\n│ memory.ts | sqlite.ts | neon.ts │\n├─────────────────────────────────────────────────────────────┤\n│ 完整性校验层 │\n│ integrity.ts │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 记忆数据结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 记忆唯一标识符 |\n| `content` | string | 记忆内容 |\n| `importance` | number | 重要度评分 (0-1) |\n| `tags` | string[] | 标签数组 |\n| `factType` | string | 事实类型 (fact/opinion) |\n| `entityIds` | string[] | 关联实体ID |\n| `createdAt` | number | 创建时间戳 |\n| `updatedAt` | number | 更新时间戳 |\n\n资料来源：[src/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/index.ts)\n\n---\n\n## 核心 API\n\n### 记忆存储：remember()\n\n`remember()` 方法用于存储新的记忆条目。\n\n```typescript\nconst memory = await agent.remember({\n content: \"用户偏好深色主题\",\n tags: [\"preference\", \"ui\"],\n importance: 0.8,\n factType: \"fact\"\n});\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `content` | string | 是 | - | 记忆内容 |\n| `namespace` | string | 否 | \"default\" | 命名空间隔离 |\n| `tags` | string[] | 否 | [] | 标签数组 |\n| `importance` | number | 否 | 0.7 | 重要度 (0-1) |\n| `factType` | string | 否 | \"fact\" | 事实类型 |\n\n**副作用：**\n\n- 自动触发观点强化（针对 `factType: \"opinion\"`）\n- 触发关联实体的观察点再生\n- 写入持久化存储\n- 触发 `memory:stored` 事件\n\n资料来源：[integrations/openclaw/SKILL.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/openclaw/SKILL.md)\n\n### 记忆检索：recall()\n\n`recall()` 方法支持语义检索和混合模式查询。\n\n```typescript\nconst results = await agent.recall({\n query: \"用户的支付偏好\",\n namespace: \"default\",\n limit: 8,\n mode: \"hybrid\"\n});\n```\n\n**检索模式：**\n\n| 模式 | 说明 |\n|------|------|\n| `semantic` | 纯语义向量检索 |\n| `keyword` | 关键词精确匹配 |\n| `hybrid` | 语义+关键词混合检索 |\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `query` | string | 是 | - | 查询文本 |\n| `namespace` | string | 否 | \"default\" | 命名空间 |\n| `limit` | number | 否 | 8 | 返回结果数量 |\n| `mode` | string | 否 | \"hybrid\" | 检索模式 |\n\n资料来源：[integrations/python-hosted/README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/python-hosted/README.md)\n\n### 记忆强化：reinforce()\n\n增强记忆的重要度评分，用于正向反馈循环。\n\n```typescript\nawait agent.reinforce(memoryId, {\n boost: 0.1 // 增量范围: 0.01 - 0.5\n});\n```\n\n**使用场景：**\n\n- 记忆引导了成功的决策\n- 用户确认了建议的价值\n- 交互产生了正面结果\n\n资料来源：[integrations/openclaw/SKILL.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/integrations/openclaw/SKILL.md)\n\n### 记忆遗忘：forget()\n\n永久删除指定记忆。\n\n```typescript\nawait agent.forget(memoryId);\n```\n\n**使用场景：**\n\n- 记忆内容已过期\n- 用户请求删除隐私数据\n- 记忆信息不再准确\n\n### 记忆整合：consolidate()\n\n清理低于衰减阈值的过期记忆，保持存储高效。\n\n```typescript\nawait agent.consolidate({\n decayThreshold: 0.2\n});\n```\n\n---\n\n## 检索引擎\n\n### 混合检索策略\n\n检索引擎采用多阶段检索流程：\n\n```mermaid\ngraph TD\n A[用户查询] --> B[查询预处理]\n B --> C{检索模式}\n C -->|semantic| D[向量相似度检索]\n C -->|keyword| E[BM25排序]\n C -->|hybrid| F[并行双路检索]\n F --> G[倒数排名融合]\n D --> G\n E --> G\n G --> H[结果重排序]\n H --> I[Top-K 结果]\n I --> J[相关性过滤]\n J --> K[返回记忆列表]\n```\n\n### HyDE 生成增强\n\nHyDE (Hypothetical Document Embeddings) 技术用于提升检索质量：\n\n1. 使用语言模型生成假设性答案\n2. 将假设性答案向量化\n3. 使用假设向量检索相关记忆\n4. 融合假设检索与直接检索结果\n\n```typescript\n// hyde.ts 核心逻辑\nconst hypotheticalDoc = await generateHypotheticalDoc(query);\nconst hypotheticalEmbedding = await embed(hypotheticalDoc);\nconst hydeResults = await vectorSearch(hypotheticalEmbedding);\n```\n\n### 查询扩展\n\n引擎支持自动查询扩展，包括：\n\n- 同义词替换\n- 上下文窗口扩展\n- 时间敏感查询优化\n\n---\n\n## 知识图谱\n\n### 图结构\n\n知识图谱由实体和边组成：\n\n```mermaid\ngraph LR\n A[实体: 用户] -->|关联| B[记忆: 偏好设置]\n A -->|拥有| C[实体: 支付方式]\n B -->|触发| D[记忆: 购买历史]\n C -->|使用| E[记忆: 交易记录]\n```\n\n### 图操作 API\n\n```typescript\n// 获取命名空间的图结构\nconst graph = await agent.graph({\n namespace: \"default\",\n limit: 200\n});\n\n// 图统计信息\nconsole.log(graph.stats);\n// { entities: 42, edges: 128, memories: 256 }\n```\n\n### 实体管理\n\n实体是知识图谱的节点，具有以下属性：\n\n| 属性 | 说明 |\n|------|------|\n| `id` | 实体唯一标识 |\n| `name` | 实体名称 |\n| `type` | 实体类型 |\n| `observations` | 观察点列表 |\n| `memoryCount` | 关联记忆数 |\n\n### 观察点系统\n\n观察点是实体的语义摘要，自动从关联记忆中生成：\n\n```typescript\ninterface Observation {\n id: string;\n entityId: string;\n content: string; // 观察点摘要\n sourceMemoryIds: string[];\n confidence: number;\n updatedAt: number;\n}\n```\n\n**观察点再生流程：**\n\n1. 新记忆存储时，识别关联实体\n2. 异步触发观察点再生任务\n3. 聚合实体相关记忆生成新摘要\n4. 更新观察点内容\n\n资料来源：[src/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/index.ts)\n\n---\n\n## 持久化层\n\n### 存储适配器\n\n系统支持多种存储后端：\n\n| 适配器 | 适用场景 | 特点 |\n|--------|----------|------|\n| `memory.ts` | 开发/测试 | 内存存储，快速迭代 |\n| `sqlite.ts` | 单机部署 | 本地持久化，轻量 |\n| `neon.ts` | 生产环境 | Postgres Serverless，分布式 |\n\n### 命名空间隔离\n\n```typescript\n// 切换命名空间\nawait agent.namespace(\"user-123\");\n\n// 导出命名空间数据\nconst export = await agent.export_namespace(\"user-123\");\n\n// 删除命名空间\nawait agent.delete_namespace(\"user-123\");\n```\n\n### 数据持久化流程\n\n```mermaid\ngraph TD\n A[记忆写入请求] --> B{存储适配器}\n B -->|开发模式| C[内存存储]\n B -->|单机部署| D[SQLite 写入]\n B -->|生产环境| E[Neon Postgres]\n C --> F[Merkle 树更新]\n D --> F\n E --> F\n F --> G[根哈希保存]\n G --> H[完整性证明生成]\n```\n\n---\n\n## 完整性校验\n\n### Merkle 内存完整性\n\n系统使用 Merkle 树结构确保记忆数据不可篡改：\n\n```typescript\ninterface MerkleProof {\n memoryId: string;\n value: string;\n path: string[]; // 兄弟节点哈希\n position: 'left' | 'right';\n rootHash: string;\n}\n```\n\n### 审计事件\n\n所有记忆操作都会记录审计日志：\n\n```typescript\nawait agent.audit(\"memory:stored\", {\n id: mem.id,\n tags: safeTags,\n importance: mem.importance,\n factType: mem.factType\n});\n```\n\n**可审计事件类型：**\n\n| 事件 | 说明 |\n|------|------|\n| `memory:stored` | 记忆存储 |\n| `memory:retrieved` | 记忆检索 |\n| `memory:updated` | 记忆更新 |\n| `memory:deleted` | 记忆删除 |\n| `memory:reinforced` | 记忆强化 |\n\n资料来源：[src/integrity.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/integrity.ts)\n\n---\n\n## 行为经济学集成\n\n### 观点强化机制\n\n对于 `factType: \"opinion\"` 的记忆，系统应用行为经济学中的观点强化机制：\n\n```typescript\nimport { applyOpinionReinforcement } from \"./behavioral.js\";\n\nawait applyOpinionReinforcement({\n newMemory: mem,\n memories: this.memories,\n recallEngine: this.recallEngine\n});\n```\n\n### 自适应学习\n\n系统采用自适应学习策略：\n\n1. **记忆衰减**：长时间未访问的记忆重要度逐渐降低\n2. **访问频率加权**：频繁访问的记忆获得权重提升\n3. **关联强度**：实体关联越多的记忆越难被遗忘\n\n---\n\n## 仪表盘可视化\n\nMnemoPay 仪表盘提供记忆系统的可视化监控：\n\n```mermaid\ngraph TD\n A[仪表盘] --> B[记忆列表]\n A --> C[推理追踪]\n A --> D[知识图谱]\n A --> E[交易历史]\n B -->|显示| F[记忆ID]\n B -->|显示| G[重要度分数]\n B -->|显示| H[记忆内容]\n C -->|显示| I[推理步骤]\n C -->|显示| J[置信度]\n C -->|显示| K[实体引用]\n D -->|显示| L[实体节点]\n D -->|显示| M[边关系]\n```\n\n### 记忆列表显示\n\n```\n┌─────────────────────────────────────────────────────┐\n│ ID │ Score │ Memory Content │\n├─────────────┼───────┼───────────────────────────────┤\n│ a1b2c3d4... │ 0.85 │ 用户偏好深色主题 │\n│ e5f6g7h8... │ 0.72 │ 经常在周末进行购物 │\n│ i9j0k1l2... │ 0.65 │ 倾向于使用信用卡支付 │\n└─────────────┴───────┴───────────────────────────────┘\n```\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n\n---\n\n## 使用示例\n\n### Python Hosted SDK\n\n```python\nfrom mnemopay import Client\n\nclient = Client(api_key=\"your-api-key\")\n\n# 存储记忆\nclient.remember(\n content=\"用户喜欢在周五晚上购物\",\n namespace=\"default\",\n tags=[\"preference\", \"shopping\"],\n importance=0.8\n)\n\n# 检索记忆\nresults = client.recall(\n query=\"购物偏好\",\n namespace=\"default\",\n limit=8,\n mode=\"hybrid\"\n)\n\n# 获取知识图谱\ngraph = client.graph(namespace=\"default\", limit=200)\nprint(f\"实体数: {graph.stats['entities']}\")\n```\n\n### JavaScript SDK\n\n```typescript\nimport MnemoPay from \"@mnemopay/sdk\";\n\nconst agent = await MnemoPay.quick(\"agent-001\");\n\n// 存储记忆\nawait agent.remember({\n content: \"用户偏好深色主题\",\n tags: [\"preference\", \"ui\"],\n importance: 0.8\n});\n\n// 检索记忆\nconst memories = await agent.recall({\n query: \"用户界面偏好\",\n limit: 8\n});\n\n// 获取图谱\nconst graph = await agent.graph();\n```\n\n---\n\n## 配置选项\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `maxMemories` | number | 10000 | 最大记忆存储量 |\n| `decayRate` | number | 0.01 | 记忆衰减率 |\n| `consolidationThreshold` | number | 0.1 | 整合阈值 |\n| `storageBackend` | string | \"memory\" | 存储后端 |\n| `embeddingModel` | string | \"default\" | 向量模型 |\n| `maxRecallResults` | number | 8 | 最大检索结果 |\n\n---\n\n## 性能指标\n\n### LongMemEval 基准\n\nMnemoPay 在 LongMemEval 基准测试中达到：\n\n| 版本 | 分数 | 说明 |\n|------|------|------|\n| v1.3.0 | 66.9% | 多会话检索基线 |\n| v1.4.0 | 77.2% | 优化后的检索引擎 |\n\n资料来源：[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)\n\n### 压力测试\n\n系统已通过 100 万次操作的连续压力测试，验证了内存管理的稳定性和数据完整性。\n\n---\n\n## 最佳实践\n\n1. **合理设置重要度**：根据记忆的实际价值设置 0-1 之间的评分\n2. **使用标签系统**：通过标签组织记忆，便于后续检索\n3. **定期整合**：使用 `consolidate()` 清理过期记忆\n4. **命名空间隔离**：为不同用户或场景使用独立命名空间\n5. **监控使用量**：通过 `usage_report()` 监控记忆存储和 API 调用\n6. **启用完整性校验**：生产环境务必启用 Merkle 完整性验证\n\n---\n\n\n\n## 账本与支付系统\n\n### 相关页面\n\n相关主题：[快速开始](#quick-start), [支付轨道](#payment-rails), [身份与认证系统](#identity-auth)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp/server.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/mcp/server.ts)\n- [README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n- [dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n- [site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n- [site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)\n \n\n# 账本与支付系统\n\n## 概述\n\nMnemoPay 的账本与支付系统是专为 AI Agent 设计的金融基础设施层，提供从充值、托管到结算、退款的全链路资金管理能力。该系统并非简单的支付网关封装，而是一套完整的双账本（Double-Entry Ledger）机制，确保每一笔资金流向都有精确的借方和贷方记录。\n\n核心价值主张：\n\n- 支持 Stripe（全球）、Paystack（非洲）、Lightning（BTC 微支付）三条真实支付通道\n- 统一的 API 接口，屏蔽底层通道差异\n- 内置交易托管（Escrow）机制，人类审批后才释放资金\n- 交易事件 Webhook 推送，支持 HMAC-SHA256 签名验签\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n---\n\n## 架构设计\n\n### 支付系统分层\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ 业务接口层 │\n│ charge() / settle() / refund() / transfer() │\n├─────────────────────────────────────────────────────────┤\n│ 支付通道层 │\n│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │\n│ │ Stripe │ │ Paystack │ │ Lightning│ │\n│ └──────────┘ └──────────┘ └──────────┘ │\n├─────────────────────────────────────────────────────────┤\n│ 账本核心层 │\n│ Double-Entry Ledger │\n├─────────────────────────────────────────────────────────┤\n│ 存储层 │\n│ SQLite / Webhook Events │\n└─────────────────────────────────────────────────────────┘\n```\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n\n### 托管与结算流程\n\n```\ngraph TD\n A[Agent 调用 charge()] --> B[资金进入 Escrow 托管]\n B --> C{人工审批}\n C -->|批准| D[调用 settle() 释放资金]\n C -->|拒绝| E[调用 refund() 原路退回]\n D --> F[商户收到结算款项]\n E --> G[资金退回买家]\n```\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n\n---\n\n## 支付通道\n\n### 通道对比\n\n| 通道 | 覆盖地区 | 支持货币 | 特色功能 |\n|------|----------|----------|----------|\n| **Stripe** | 全球 | USD, EUR, GBP 等 135+ 货币 | 手动捕获（Manual Capture）实现真正的 Escrow |\n| **Paystack** | 非洲 | NGN, GHS, ZAR, KES | 23 家尼日利亚银行预映射，HMAC-SHA512 安全验证 |\n| **Lightning** | 全球 | BTC | 微支付场景，实时到账 |\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n\n### Stripe 集成\n\nStripe 提供全球覆盖的信用卡支付能力。MnemoPay 使用 PaymentIntents API 实现手动捕获模式，确保资金在托管状态下等待授权：\n\n```typescript\n// 核心支付操作\ncharge() // 收款并进入托管\nsettle() // 释放托管资金\nrefund() // 退款回原支付渠道\n```\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n\n### Paystack 集成\n\n针对非洲市场优化，支持多种本地支付方式：\n\n- Checkout（网页结账）\n- 保存的卡片（Saved Cards）\n- 银行转账（Bank Transfer）\n- Webhook 验证（HMAC-SHA512）\n\n```typescript\n// Paystack 转账事件\ntransfer.success // 转账完成\ntransfer.failed // 转账失败\n```\n\n资料来源：[src/mcp/server.ts:1-50](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/mcp/server.ts)\n\n---\n\n## Webhook 事件系统\n\n### 事件类型\n\n| 事件名称 | 触发时机 | 描述 |\n|----------|----------|------|\n| `charge.success` | 扣款成功进入托管 | 交易已被接受并锁定在 Escrow |\n| `charge.failed` | 扣款失败 | 因名誉分上限、欺诈检测、授权违规等原因被拒绝 |\n| `settle` | 释放托管资金 | Escrow 已释放，资金已划转 |\n| `refund` | 交易回滚 | 资金已原路退回 |\n| `transfer.success` | Paystack 提现完成 | 资金已到达目标账户 |\n| `transfer.failed` | Paystack 提现失败 | 提现操作异常 |\n| `*` | 通配符订阅 | 订阅所有事件类型 |\n\n资料来源：[src/mcp/server.ts:1-50](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/mcp/server.ts)\n\n### 签名验证机制\n\n每条 Webhook POST 请求都携带 `X-MnemoPay-Signature` 头，格式为：\n\n```\nX-MnemoPay-Signature: t=,v1=\n```\n\n其中 `v1` 的计算方式：\n\n```\nv1 = HMAC-SHA256(secret, timestamp + '.' + request_body)\n```\n\n**安全建议**：验证 `now - t < 300秒`，防止重放攻击。签名密钥在调用 `webhook_register` 时返回一次，务必在调用返回前持久化存储。\n\n```typescript\n// Webhook 验证伪代码\nconst isValid = hmacSha256(secret, `${timestamp}.${body}`) === signature;\nconst isRecent = Date.now() - timestamp < 300000; // 5分钟内\nif (!isValid || !isRecent) reject();\n```\n\n资料来源：[src/mcp/server.ts:1-50](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/mcp/server.ts)\n\n---\n\n## 双账本机制\n\n### 核心概念\n\nMnemoPay 采用双记账（Double-Entry）原则，每笔交易都产生两条对应的账目记录：\n\n- **借方条目（Debit）**：资金流出账户\n- **贷方条目（Credit）**：资金流入账户\n\n这确保了账目平衡，任何时刻资产总计等于负债总计。\n\n### 交易状态流转\n\n```\ngraph LR\n A[Created] --> B[Held - Escrow中]\n B -->|Approve| C[Settled - 已结算]\n B -->|Reject| D[Refunded - 已退款]\n C --> E[Completed]\n D --> E\n```\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n\n---\n\n## 自助购物与结账执行\n\n### 购物流程\n\nMnemoPay 支持 AI Agent 自动执行购物操作，所有购买都必须经过 Escrow 托管：\n\n1. Agent 搜索商品、比较价格\n2. 选择最优方案，发起购买请求\n3. 资金进入托管状态\n4. **人类审批**后才真正扣款\n5. 禁止 Agent 未经授权自行消费\n\n```typescript\n// 购物相关 API\nshop_checkout // 浏览器自动化结账\n```\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n\n### 结账策略\n\n| 策略 | 适用平台 | 说明 |\n|------|----------|------|\n| Shopify 策略 | Shopify 店铺 | 原生检测，优化选择器 |\n| 通用策略 | 其他平台 | 回退到通用结账启发式算法 |\n\n资料来源：[src/mcp/server.ts:1-50](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/mcp/server.ts)\n\n---\n\n## 仪表盘监控\n\n### 交易概览\n\nMnemoPay Dashboard 提供实时交易监控能力：\n\n| 监控指标 | 说明 |\n|----------|------|\n| Wallet 余额 | 当前可用余额 |\n| Reputation 信誉分 | Agent 信用评分（0-1） |\n| Memories Count | 记忆条目数 |\n| Transactions Count | 累计交易数 |\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n\n### 任务与进度追踪\n\n每个支付任务都包含状态标记：\n\n```typescript\n{\n id: string,\n done: boolean, // true = Complete, false = In Progress\n // ...\n}\n```\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n\n---\n\n## SDK 快速开始\n\n### 安装\n\n```bash\nnpm install @mnemopay/sdk\n```\n\n### 初始化\n\n```typescript\nimport { MnemoPay } from \"@mnemopay/sdk\";\n\nconst mnemo = MnemoPay.quick(\"agent-id\");\n// 自动分配：记忆存储 + 钱包 + 身份\n```\n\n### 基础支付操作\n\n```typescript\n// 收款（进入托管）\nawait mnemo.charge({ amount: 1000, currency: \"USD\" });\n\n// 释放托管（需人工授权）\nawait mnemo.settle({ transactionId: \"tx_xxx\" });\n\n// 退款\nawait mnemo.refund({ transactionId: \"tx_xxx\" });\n```\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n\n---\n\n## 与传统支付方案对比\n\n| 特性 | MnemoPay | 传统 Stripe 封装 | Payman |\n|------|----------|------------------|--------|\n| 支付通道 | 多通道统一 API | 单通道 | 单一 |\n| Escrow 托管 | 原生支持 | 需手动实现 | 不支持 |\n| 双账本 | 内置 | 需额外开发 | 不支持 |\n| AI Agent 身份 | Ed25519 | 无 | 无 |\n| Agent 信用评分 | 300-850 分 | 无 | 无 |\n| 行为异常检测 | EWMA + 指纹 | 无 | 无 |\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html)\n\n---\n\n## 总结\n\nMnemoPay 的账本与支付系统为 AI Agent 提供了一套完整、合规、可审计的金融操作基础设施：\n\n- **真实性**：接入 Stripe、Paystack、Lightning 三大真实支付通道\n- **安全性**：HMAC-SHA256 签名验签、300秒重放保护、名誉分风控\n- **合规性**：双账本确保每笔资金有据可查，Escrow 托管保障资金安全\n- **可观测性**：完整的事件 Webhook + Dashboard 实时监控\n\n通过这套系统，AI Agent 可以在受控环境下安全地处理货币事务，同时保留人类最终决策权。\n\n---\n\n\n\n## 身份与认证系统\n\n### 相关页面\n\n相关主题：[账本与支付系统](#ledger-payments), [治理与合规框架](#governance)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/identity.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity.ts)\n- [src/identity/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity/index.ts)\n- [src/identity/did.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity/did.ts)\n- [src/identity/wallet.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity/wallet.ts)\n- [src/identity/bundle.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/identity/bundle.ts)\n- [src/network.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/network.ts)\n \n\n# 身份与认证系统\n\nMnemoPay SDK 的身份与认证系统是整个平台的核心基础设施，为 AI Agent 提供完整的身份标识、钱包管理、权限控制和安全验证机制。该系统基于去中心化身份（DID）理念构建，同时集成了传统的 KYC/KYB 流程以满足监管合规要求。\n\n## 系统架构概览\n\n身份与认证系统采用分层架构设计，各层之间职责明确、解耦清晰。\n\n```mermaid\ngraph TD\n subgraph 身份层\n DID[DID 标识符]\n BUNDLE[身份凭证包]\n KYA[Know Your Agent]\n end\n \n subgraph 钱包层\n WALLET[钱包余额]\n TOKEN[Token 管理]\n REPUTATION[信誉评分]\n end\n \n subgraph 权限层\n PERMS[权限控制]\n KILLSWITCH[熔断机制]\n end\n \n subgraph 网络层\n NETWORK[网络通信]\n VERIFY[身份验证]\n end\n \n DID --> BUNDLE\n BUNDLE --> WALLET\n BUNDLE --> TOKEN\n WALLET --> REPUTATION\n BUNDLE --> PERMS\n PERMS --> KILLSWITCH\n NETWORK --> VERIFY\n VERIFY --> DID\n```\n\n根据架构文档，MnemoPay SDK 的身份系统包含以下核心组件：\n\n| 组件 | 功能描述 | 层级归属 |\n|------|---------|----------|\n| DID | 去中心化身份标识符 | 身份层 |\n| KYA | Know Your Agent 身份核验 | 身份层 |\n| Bundle | 身份凭证包管理 | 身份层 |\n| Wallet | 钱包余额与交易 | 钱包层 |\n| Token | 代币化管理 | 钱包层 |\n| Permissions | 权限访问控制 | 权限层 |\n| KillSwitch | 熔断/紧急停止 | 权限层 |\n| Reputation | 信誉评分系统 | 钱包层 |\n\n资料来源：[README.md:30-50]()\n\n## 核心模块详解\n\n### 身份标识模块（Identity）\n\n身份标识模块是整个认证系统的根基，为每个 Agent 生成唯一的去中心化身份。\n\n#### DID 去中心化标识符\n\nDID（Decentralized Identifier）是 MnemoPay 系统中 Agent 的唯一身份标识。DID 标识符遵循 W3C DID Core 规范，支持自主管理、跨平台互操作。\n\n根据架构设计，DID 模块负责：\n- 生成符合规范的 DID 标识符\n- 管理 DID 文档（DID Document）\n- 支持 DID 解析与验证\n\n资料来源：[src/identity/did.ts]()\n\n#### Bundle 身份凭证包\n\nBundle 是身份凭证的聚合容器，包含 Agent 的身份证明、资质文件、权限声明等信息。\n\n```mermaid\ngraph LR\n B[Bundle] --> K[KYA 凭证]\n B --> P[Permissions 权限]\n B --> T[Tokens 代币]\n B --> R[Reputation 信誉]\n```\n\nBundle 的设计使得身份信息可以作为一个整体进行传输和验证，同时支持选择性披露。\n\n资料来源：[src/identity/bundle.ts]()\n\n### 钱包模块（Wallet）\n\n钱包模块管理 Agent 的资金、信誉评分和交易历史。\n\n#### 账户状态管理\n\nDashboard 中的账户状态管理展示了钱包与身份系统的集成方式：\n\n```typescript\nconst [profile, setProfile] = useState({\n wallet: 0,\n reputation: 0.5,\n memoriesCount: 0,\n transactionsCount: 0\n});\n```\n\n账户状态包含：\n- `wallet`: 钱包余额\n- `reputation`: 信誉评分（初始值 0.5）\n- `memoriesCount`: 记忆数量\n- `transactionsCount`: 交易次数\n\n资料来源：[dashboard/index.html:175-181]()\n\n#### 信誉评分系统\n\n信誉评分采用 300-850 分制，与 FICO 信用评分类似。评分由五个组成部分构成：\n\n| 评分维度 | 说明 |\n|---------|------|\n| 支付历史 | 按时支付的比例 |\n| 使用时长 | 账户存在时间 |\n| 信用类型 | 使用的产品多样性 |\n| 新信用 | 最近的开户行为 |\n| 余额利用率 | 信用使用率 |\n\n信誉评分直接影响：\n- 单次交易额度上限\n- 费率折扣\n- 访问高级功能权限\n\n资料来源：[README.md:42-50]()\n\n### 会话管理模块\n\n会话模块处理 Agent 的登录、登出和会话状态维护。\n\n#### 登录流程\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant SessionPanel\n participant Network\n participant Identity\n \n Agent->>SessionPanel: 请求登录\n SessionPanel->>Network: 验证凭证\n Network->>Identity: 验证身份\n Identity-->>Network: 验证结果\n Network-->>SessionPanel: 会话令牌\n SessionPanel-->>Agent: 登录成功\n```\n\n#### 会话状态管理\n\nDashboard 组件中实现了完整的会话状态管理：\n\n```typescript\nconst [session, setSession] = useState(null);\nconst [accountId, setAccountIdState] = useState(getAccountId());\nconst [connected, setConnected] = useState(false);\n```\n\n关键状态变量：\n\n| 变量 | 类型 | 说明 |\n|------|------|------|\n| `session` | object | 当前会话对象 |\n| `accountId` | string | 账户唯一标识符 |\n| `connected` | boolean | 连接状态 |\n\n资料来源：[dashboard/index.html:167-172]()\n\n### 权限控制模块\n\n权限模块实现细粒度的访问控制和安全策略。\n\n#### Permissions 权限矩阵\n\nMnemoPay 采用基于角色的访问控制（RBAC）与属性基访问控制（ABAC）混合模型：\n\n```mermaid\ngraph TD\n R[Request] --> P{Permissions Check}\n P -->|有权限| A[Allow]\n P -->|无权限| K{KillSwitch}\n K -->|触发熔断| B[Block]\n K -->|未触发| D[Deny]\n```\n\n#### KillSwitch 熔断机制\n\nKillSwitch 是安全防护的最后一道防线，在检测到异常行为时自动触发：\n\n| 触发条件 | 动作 |\n|---------|------|\n| 异常交易模式 | 暂停交易 |\n| 信誉分骤降 | 锁定账户 |\n| 可疑 IP | 二次验证 |\n| API 限流 | 服务降级 |\n\n资料来源：[README.md:46-48]()\n\n## 网络通信与验证\n\n### 网络层架构\n\n网络层负责所有身份相关的通信请求，包括验证、签发、更新等操作。\n\n```mermaid\ngraph TD\n subgraph 客户端\n SDK[SDK 客户端]\n ID[身份模块]\n end\n \n subgraph 服务端\n API[API 网关]\n AUTH[认证服务]\n IDV[身份服务]\n end\n \n SDK --> API\n ID --> NETWORK[网络模块]\n NETWORK --> API\n API --> AUTH\n AUTH --> IDV\n IDV --> DATABASE[(数据库)]\n```\n\n资料来源：[src/network.ts]()\n\n### 身份验证流程\n\n身份验证采用多层验证机制：\n\n1. **令牌验证**：检查 JWT 令牌的合法性\n2. **签名验证**：验证消息签名的正确性\n3. **状态检查**：验证账户未被锁定或禁用\n4. **权限检查**：确认操作在授权范围内\n\n## KYA（Know Your Agent）体系\n\nKYA 是 MnemoPay 的身份核验框架，类似于传统金融的 KYC（Know Your Customer）流程。\n\n### KYA 核验级别\n\n| 级别 | 核验内容 | 限额 | 适用场景 |\n|------|---------|------|---------|\n| L1 | 邮箱验证 | $100/日 | 开发测试 |\n| L2 | 手机验证 | $1,000/日 | 小规模部署 |\n| L3 | 身份证明 | $10,000/日 | 生产环境 |\n| L4 | 企业认证 | 无限制 | 企业客户 |\n\n### 身份凭证要求\n\nL3 及以上级别需要提供：\n- 法定身份证明（身份证、护照）\n- 地址证明（水电费账单）\n- 企业注册文件（适用于 L4）\n\n资料来源：[README.md:41-44]()\n\n## Agent 信用评分\n\nAgent 信用评分是 MnemoPay 的核心创新之一，为 AI Agent 提供可量化的信用指标。\n\n### 评分计算模型\n\n```mermaid\ngraph LR\n A[行为数据] --> B[实时监控]\n B --> C[EWMA 统计]\n C --> D[异常检测]\n D --> E[评分更新]\n E --> F[信用报告]\n```\n\n### 评分维度\n\n| 维度 | 权重 | 影响因素 |\n|------|------|---------|\n| 支付可靠性 | 35% | 按时支付比例 |\n| 交易历史 | 25% | 交易数量与频率 |\n| 账户稳定性 | 20% | 账户存续时间 |\n| 风险行为 | 15% | 异常交易检测 |\n| 信用多样性 | 5% | 产品使用广度 |\n\n### 异常检测机制\n\n系统采用 EWMA（指数加权移动平均）+ 指纹识别双重机制进行异常检测：\n\n- **EWMA**：检测交易金额、频率的统计异常\n- **指纹识别**：识别设备、IP、行为模式的异常\n\n资料来源：[README.md:51-54]()\n\n## 安全性设计\n\n### 安全层级\n\n```mermaid\ngraph TD\n subgraph 安全防护\n S1[身份标识]\n S2[通信加密]\n S3[权限验证]\n S4[行为监控]\n S5[熔断保护]\n end\n \n S1 --> S2\n S2 --> S3\n S3 --> S4\n S4 --> S5\n```\n\n### 威胁防护措施\n\n| 威胁类型 | 防护机制 |\n|---------|---------|\n| 重放攻击 | 时间戳 + 随机数 |\n| 中间人攻击 | TLS 1.3 + 证书固定 |\n| 权限提升 | 最小权限原则 |\n| 账户盗用 | 多因素认证 |\n| 交易欺诈 | 实时风险评估 |\n\n## 快速开始\n\n### 初始化身份\n\n```typescript\nimport { MnemoPay } from '@mnemopay/sdk';\n\nconst mnemo = MnemoPay.quick('agent-id');\n\n// 获取身份信息\nconst identity = await mnemo.identity.get();\nconsole.log(identity.did); // DID 标识符\nconsole.log(identity.wallet); // 钱包余额\nconsole.log(identity.reputation); // 信誉评分\n```\n\n### 管理会话\n\n```typescript\n// 登录\nawait mnemo.session.login({\n accountId: 'your-account-id'\n});\n\n// 获取当前会话\nconst session = await mnemo.session.current();\nconsole.log(session.token); // 会话令牌\nconsole.log(session.expiresAt); // 过期时间\n\n// 登出\nawait mnemo.session.logout();\n```\n\n### 权限检查\n\n```typescript\n// 检查权限\nconst hasPermission = await mnemo.identity.checkPermission({\n action: 'charge',\n resource: 'wallet'\n});\n\nif (hasPermission) {\n // 执行操作\n} else {\n // 触发 KillSwitch 或提示权限不足\n}\n```\n\n## 总结\n\nMnemoPay 的身份与认证系统为 AI Agent 提供了企业级的身份管理能力：\n\n- **去中心化身份**：基于 DID 的自主身份标识\n- **完整的钱包系统**：资金、信誉、交易一体化管理\n- **细粒度权限控制**：RBAC + ABAC 混合模型\n- **多层安全防护**：从身份验证到行为监控的全链路保护\n- **信用评分体系**：300-850 分制的 Agent 信用评分\n- **KYA 合规框架**：满足监管要求的身份核验流程\n\n这套系统使 AI Agent 能够像企业一样拥有身份、管理资金、建立信誉，为自主经济奠定基础。\n\n---\n\n\n\n## 代理信用评分系统\n\n### 相关页面\n\n相关主题：[异常检测系统](#anomaly-detection), [治理与合规框架](#governance)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/fico.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/fico.ts)\n- [src/behavioral.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/behavioral.ts)\n- [src/subagent-cost.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/subagent-cost.ts)\n- [dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n- [README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n \n\n# 代理信用评分系统\n\n## 概述\n\n代理信用评分系统（Agent Credit Scoring System）是 MnemoPay SDK 的核心组件之一，为 AI 代理提供类似人类信用评分的信任评估机制。该系统采用 300-850 的评分范围，模拟传统 FICO 信用评分模型，针对 AI 代理的交易行为、支付历史和可靠性进行多维度评估。\n\n代理信用评分直接影响交易手续费率、交易限额以及系统对异常行为的容忍度。评分越高的代理可享受更低的手续费（Enterprise 级别最低至 1.0%）和更高的交易限额，而评分较低的代理将面临更严格的监控甚至自动封禁。\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 系统架构\n\n代理信用评分系统由多个协同工作的模块组成，采用五组件评分架构，结合行为金融学和异常检测技术。\n\n```mermaid\ngraph TD\n A[代理身份创建] --> B[评分系统初始化]\n B --> C{评分组件}\n C --> D[FICO基础评分]\n C --> E[行为金融分析]\n C --> F[异常检测]\n C --> G[支付历史]\n C --> H[可靠性评估]\n D --> I[综合评分 300-850]\n E --> I\n F --> I\n G --> I\n H --> I\n I --> J[手续费计算]\n I --> K[交易限额]\n I --> L[风险控制]\n```\n\n## 核心组件\n\n### FICO 基础评分模块\n\nFICO 模块是评分系统的基础实现，负责计算代理的基础信用分值。该模块采用双余额记账系统追踪代理的财务状况，通过分析交易历史计算综合评分。\n\n评分计算考虑以下因素：\n\n| 因素 | 权重范围 | 说明 |\n|------|----------|------|\n| 支付历史 | 35% | 按时支付的比例和频率 |\n| 信用利用率 | 30% | 当前信用额度使用情况 |\n| 账户时长 | 15% | 账户活跃时间 |\n| 信用类型 | 10% | 使用的支付渠道多样性 |\n| 新信用查询 | 10% | 短期内新增信用申请 |\n\n资料来源：[src/fico.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/fico.ts)\n\n### 行为金融分析模块\n\n行为金融分析模块运用前景理论（Prospect Theory）和 nudge 机制，对代理的决策模式进行深度分析。该模块通过观察代理在相似场景下的历史决策，识别风险偏好和交易行为模式。\n\n```mermaid\ngraph LR\n A[交易行为数据] --> B[行为模式识别]\n B --> C{前景理论分析}\n C --> D[损失厌恶系数]\n C --> E[风险偏好曲线]\n C --> F[决策偏差检测]\n D --> G[行为评分调整]\n E --> G\n F --> G\n G --> H[最终行为分数]\n```\n\n该模块的核心功能包括：\n\n- **损失厌恶评估**：测量代理对损失的敏感程度，量化代理在面临潜在损失时的决策倾向\n- **风险偏好曲线**：基于前景理论建模代理的风险承担意愿，高风险偏好代理在市场波动时可能做出更激进的决策\n- **决策偏差检测**：识别代理行为中的系统性偏差，如锚定效应、可得性启发等认知偏差\n- **Nudge 机制**：根据代理的行为模式自动施加微小的决策引导，优化交易结果\n\n资料来源：[src/behavioral.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/behavioral.ts)\n\n### 子代理成本追踪模块\n\n子代理成本追踪模块专门针对多代理系统设计，记录和归因子代理的资源消耗。该模块维护每个子代理的成本中心，支持成本分配和内部结算。\n\n```mermaid\ngraph TD\n A[父代理] --> B[子代理成本记录]\n B --> C[资源消耗追踪]\n C --> D[成本归因分析]\n D --> E[内部结算]\n E --> F[成本效率评分]\n F --> G[父代理信用影响]\n```\n\n关键功能：\n\n- **资源消耗追踪**：记录 CPU、内存、API 调用等资源使用情况\n- **成本归因**：将子代理产生的成本准确归属到对应的父代理\n- **效率评分**：基于成本消耗与交易价值的比率计算效率分数\n\n资料来源：[src/subagent-cost.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/subagent-cost.ts)\n\n### 异常检测模块\n\n异常检测模块采用指数加权移动平均（EWMA）和指纹识别技术，实时监控代理行为，识别潜在的欺诈或异常活动。\n\n```mermaid\ngraph TD\n A[交易数据流] --> B[EWMA统计监控]\n A --> C[行为指纹生成]\n B --> D{异常判定}\n C --> D\n D -->|正常| E[更新基准线]\n D -->|异常| F[触发警报]\n D -->|严重| G[自动封禁]\n F --> H[人工审核队列]\n```\n\n检测机制：\n\n| 检测类型 | 技术方案 | 响应级别 |\n|----------|----------|----------|\n| 交易频率异常 | EWMA 动态阈值 | 警报 |\n| 金额异常 | 统计分布偏离检测 | 警报 |\n| 行为指纹异常 | 多维特征匹配 | 人工审核 |\n| 串通检测 | 图关系分析 | 自动封禁 |\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 评分计算流程\n\n### 初始化阶段\n\n代理首次初始化时，系统基于 Ed25519 加密身份创建唯一标识符，并分配初始信用评分。\n\n```typescript\n// 初始化代理并获取信用评分\nconst agent = MnemoPay.quick(\"billing-agent\", {\n stripe: { secretKey: process.env.STRIPE_SECRET_KEY }\n});\n\n// 信用评分将在首次交易后计算\nconsole.log(agent.id); // Ed25519 派生身份\n```\n\n### 动态评分更新\n\n评分系统采用流式计算模式，每次交易完成后自动更新评分。\n\n```mermaid\nsequenceDiagram\n participant A as 代理\n participant B as 评分系统\n participant C as 支付引擎\n participant D as 异常检测\n \n A->>C: charge() 请求\n C->>D: 提交交易\n D->>D: 异常检测\n D-->>C: 检测结果\n C->>B: 交易完成事件\n B->>B: 计算评分增量\n B->>B: 更新综合评分\n B-->>A: 新评分生效\n```\n\n## 评分应用场景\n\n### 手续费等级\n\n信用评分直接决定代理的交易手续费率：\n\n| 评分范围 | 等级 | 手续费率 | 适用计划 |\n|----------|------|----------|----------|\n| 750-850 | Excellent | 1.0% | Enterprise |\n| 650-749 | Good | 1.5% | Pro |\n| 550-649 | Fair | 2.0% | Starter |\n| 300-549 | Poor | 冻结交易 | 审核中 |\n\n资料来源：[site/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.html)\n\n### 交易限额\n\n评分决定代理的即时交易限额和日累计限额：\n\n- **高评分代理（750+）**：无单笔限额，日限额根据账户历史自动调整\n- **中等评分代理（550-749）**：单笔限额 $10,000，日限额 $100,000\n- **低评分代理（300-549）**：单笔限额 $1,000，日限额 $5,000，需要人工审批\n\n### 自动风控\n\n评分系统与风控引擎深度集成：\n\n```mermaid\ngraph TD\n A[交易请求] --> B{信用评分检查}\n B -->|≥750| C[直接放行]\n B -->|650-749| D[简化验证]\n B -->|550-649| E[标准验证]\n B -->|300-549| F[拒绝交易]\n D --> G{EWMA异常检测}\n E --> G\n G -->|正常| H[人工确认]\n G -->|异常| F\n C --> I[执行交易]\n H --> I\n```\n\n## 仪表盘集成\n\n代理信用评分通过 MnemoPay 仪表盘实时展示，便于开发者监控代理健康状况。\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n\n```typescript\n// 仪表盘显示的代理信息结构\ninterface AgentProfile {\n wallet: number; // 钱包余额\n reputation: number; // 信誉分数 (0-1)\n memoriesCount: number; // 记忆条目数\n transactionsCount: number;// 交易总数\n}\n```\n\n## API 参考\n\n### 获取代理评分\n\n```typescript\nconst score = await agent.getCreditScore();\n// 返回: { score: number, factors: CreditFactor[] }\n```\n\n### 更新行为数据\n\n```typescript\nawait agent.updateBehavioralData({\n transactionPattern: 'conservative',\n riskTolerance: 0.3,\n lossAversion: 2.5\n});\n```\n\n### 查询子代理成本\n\n```typescript\nconst costReport = await agent.getSubagentCosts({\n period: '30d',\n groupBy: 'subagent'\n});\n```\n\n## 总结\n\n代理信用评分系统是 MnemoPay SDK 的核心信任基础设施，通过五组件评分架构、行为金融分析和实时异常检测，为 AI 代理提供可量化的信任评估。评分系统与支付引擎深度集成，直接影响手续费率、交易限额和风控策略，确保只有可靠的代理能够参与金融交易。\n\n---\n\n\n\n## 行为金融引擎\n\n### 相关页面\n\n相关主题：[代理信用评分系统](#credit-score), [异常检测系统](#anomaly-detection)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/behavioral.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/behavioral.ts)\n- [src/reasoning/post-processor.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/reasoning/post-processor.ts)\n \n\n# 行为金融引擎\n\n## 概述\n\n行为金融引擎是 MnemoPay SDK v1.4.0+ 中的核心模块之一，专注于将行为经济学原理（特别是前景理论/Prospect Theory）与 AI Agent 的支付决策系统相结合。该引擎通过实时干预和引导机制，优化 Agent 的金融行为，降低系统性风险，并提升整体支付生态的健康度。\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 核心定位\n\nMnemoPay SDK 的整体架构将行为金融引擎置于**Agent Credit Score（代理信用评分）**与**支付系统**之间的关键位置：\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│ GOVERNANCE Charter · FiscalGate · Article 12 · MerkleAudit │\n├──────────┬──────────┬───────────┬─────────────────────────────────┤\n│ Memory │ Payments │ Identity │ Agent Credit Score (300-850) │\n│ │ │ │ 5-component scoring │\n├──────────┴──────────┴───────────┼─────────────────────────────────┤\n│ │ Behavioral Finance │\n│ │ prospect theory, nudges │\n├────────────────────────────────┴─────────────────────────────────┤\n│ │ Anomaly Detection │\n│ │ EWMA + fingerprinting │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n资料来源：[README.md:Architecture](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 工作原理\n\n### 前景理论集成\n\n行为金融引擎基于 Kahneman 和 Tversky 的前景理论（Prospect Theory）设计。该理论的核心洞察是：**人类（及 AI Agent）在面对收益和损失时表现出非对称的风险偏好**：\n\n- **确定效应**：倾向于选择确定的收益而非概率收益\n- **反射效应**：在损失面前表现为风险寻求\n- **损失厌恶**：对损失的敏感度高于等量收益（约 2.25 倍）\n- **参考点依赖**：决策结果取决于相对于参考点的变化\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n### 决策干预流程\n\n```\ngraph TD\n A[交易请求 charge/settle] --> B{行为金融引擎评估}\n B --> C[计算即时效用]\n C --> D{参考点比较}\n D -->|收益框架| E[应用确定效应权重]\n D -->|损失框架| F[应用损失厌恶权重]\n E --> G[决策调整]\n F --> G\n G --> H{风险阈值检查}\n H -->|通过| I[执行交易]\n H -->|警告| J[发送Nudge提示]\n H -->|拒绝| K[阻止交易]\n```\n\n## Nudge 机制\n\n### 行为助推设计\n\n引擎内置多种 Nudge（行为助推）策略，用于温和引导 Agent 行为：\n\n| Nudge 类型 | 触发场景 | 响应方式 |\n|-----------|---------|---------|\n| 延迟确认 | 大额交易 | 建议冷却期 |\n| 风险提示 | 异常模式 | 警告信息 |\n| 历史参照 | 新交易对手 | 展示信用历史 |\n| 阈值预警 | 接近限额 | 提前通知 |\n\n### Nudge 实现模式\n\n```typescript\n// 典型 Nudge 触发场景\nif (transaction.amount > threshold * reputationScore) {\n applyNudge({\n type: 'DELAY_CONFIRMATION',\n message: '建议在执行前等待确认',\n cooldown: 30000 // 30秒冷却\n });\n}\n```\n\n资料来源：[src/behavioral.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/behavioral.ts)\n\n## 与异常检测的协同\n\n行为金融引擎与 EWMA（指数加权移动平均）异常检测系统紧密协作：\n\n```\ngraph LR\n A[行为数据流] --> B[EWMA 异常检测]\n B --> C{异常判断}\n C -->|正常| D[行为金融引擎正常决策]\n C -->|轻度异常| E[应用风险权重]\n C -->|重度异常| F[触发 Killswitch]\n E --> G[更新参考点]\n F --> H[阻止交易 + 记录审计]\n```\n\n### 双重验证机制\n\n1. **EWMA 层**：基于统计的时间序列异常检测，识别交易速度和频率异常\n2. **行为金融层**：基于决策心理学的规范性分析，识别不理性交易行为\n\n两层结合确保：\n- 统计异常 → 实时拦截\n- 行为异常 → Nudge 引导 + 长期跟踪\n\n资料来源：[README.md - Anomaly Detection](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 与 Agent Credit Score 的交互\n\n行为金融引擎的输出直接影响 **Agent Credit Score（300-850 分）**：\n\n```mermaid\ngraph TD\n A[交易完成] --> B[行为评估]\n B --> C{决策质量评分}\n C -->|理性决策| D[+信用分]\n C -->|异常交易| E[-信用分]\n C -->|高风险拦截| F[大幅扣分 + 标记]\n D --> G[更新5维评分模型]\n E --> G\n F --> G\n```\n\n### 评分反馈闭环\n\n引擎在每次交易结算（settle）时触发信用反馈循环：\n\n```typescript\n// 行为反馈机制\nonSettle(transaction) {\n const behaviorScore = evaluateDecisionQuality(transaction);\n const creditImpact = behaviorScore * FEEDBACK_LOOP_WEIGHT; // 0.05\n updateCreditScore(creditImpact);\n}\n```\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html) - 信用评分衰减注释\n\n## 配置参数\n\n| 参数 | 默认值 | 说明 |\n|------|-------|------|\n| `lossAversion` | 2.25 | 损失厌恶系数 |\n| `referencePointDecay` | 0.05 | 参考点衰减率（半衰期约14小时）|\n| `nudgeThreshold` | 动态 | Nudge 触发阈值 |\n| `prospectWeighting` | 0.61 | 概率加权函数参数 |\n\n### 实时参数调整\n\n引擎支持基于市场条件的动态参数调整：\n\n```typescript\ninterface BehavioralConfig {\n lossAversion: number; // 范围: 1.5-3.0\n decay: number; // 范围: 0.01-0.1\n feedbackLoopWeight: number; // 范围: 0.01-0.1\n ceilingMultiplier: number; // 信用分上限系数\n}\n```\n\n资料来源：[src/behavioral.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/behavioral.ts)\n\n## 应用场景\n\n### 场景一：代理购物（Autonomous Shopping）\n\n当 Agent 代表用户执行购买决策时：\n\n1. **交易前**：评估用户历史偏好和风险承受能力\n2. **交易中**：应用前景理论框架调整购买确认流程\n3. **交易后**：基于结算结果更新 Agent 信用评分\n\n```typescript\n// 自动购物中的行为金融干预\nconst shoppingAgent = MnemoPay.quick(\"shopping-agent\");\nconst purchase = await shoppingAgent.charge(299.00, \"Enterprise plan\");\n\n// 引擎自动评估：\n// - 金额是否超出代理信用上限\n// - 交易频率是否异常\n// - 交易对手风险评分\n```\n\n### 场景二：多代理商业（Multi-Agent Commerce）\n\n在多 Agent 协作场景中，行为金融引擎提供：\n\n- **信任传递**：基于信用评分的行为担保\n- **争议预防**：Nudge 机制减少事后纠纷\n- **清算优化**：前景理论驱动的最优结算时机选择\n\n资料来源：[site/index.legacy.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/site/index.legacy.html) - 规模扩展场景\n\n## 监控与仪表板\n\n行为金融引擎的各项指标可在 MnemoPay Dashboard 中实时监控：\n\n```typescript\n// Dashboard 展示的关键指标\ninterface BehavioralMetrics {\n reputation: number; // 当前声誉值 (0-1)\n ceiling: number; // 当前计费上限 ($)\n decay: number; // 衰减率\n feedbackLoop: string; // 反馈循环状态\n overLimit: boolean; // 是否超限\n}\n```\n\nDashboard 面板通过以下组件展示引擎状态：\n\n| 面板区域 | 显示内容 | 数据来源 |\n|---------|---------|---------|\n| Reputation | 实时声誉分数 | `profile.reputation` |\n| Credit Ceiling | 动态计算上限 | `500 * reputation` |\n| Plan Gate | 限额状态指示 | `missions.overLimit` |\n| Active Sessions | 行为异常会话 | `session` 数据 |\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html) - 计费面板代码\n\n## 技术特性\n\n### 无侵入集成\n\n行为金融引擎作为 SDK 中间件层实现，对业务逻辑无侵入：\n\n```typescript\n// 中间件注册方式\nimport { mnemoPayMiddleware } from \"@mnemopay/sdk/middleware/openai\";\n// 或\nimport { mnemoPayMiddleware } from \"@mnemopay/sdk/middleware/anthropic\";\n```\n\n### 跨平台支持\n\n引擎通过标准化接口支持多种 AI 框架：\n\n| 框架 | 集成方式 |\n|-----|---------|\n| OpenAI | `mnemoPayMiddleware` |\n| Anthropic | `mnemoPayMiddleware` |\n| LangGraph | `mnemoPayTools` |\n\n资料来源：[README.md - Middleware](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n### 哈希链完整性\n\n所有行为金融决策通过 Merkle 树记录，确保审计可追溯：\n\n```\nMerkleAudit 包含：\n├── 行为决策记录\n├── Nudge 触发历史\n├── 信用评分变更\n└── 异常处理日志\n```\n\n资料来源：[README.md - Architecture](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 版本演进\n\n| 版本 | 关键更新 |\n|-----|---------|\n| v1.4.0 | 首次引入行为金融引擎，集成前景理论和 Nudge 机制 |\n| v1.5.0 | 稳定版发布，架构与 Alpha 版保持一致 |\n| v1.6.0-alpha | 持续优化行为模型参数 |\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md) - 版本信息\n\n## 总结\n\n行为金融引擎是 MnemoPay SDK 区别于传统支付网关的核心创新点之一。通过将 Kahneman 和 Tversky 的行为经济学理论与现代 AI Agent 系统相结合，引擎实现了：\n\n- **风险可控**：通过前景理论框架和 Nudge 机制预防非理性交易\n- **信用驱动**：基于行为质量动态调整 Agent 信用评分\n- **可审计性**：Merkle 树记录确保所有决策可追溯验证\n- **实时干预**：EWMA 异常检测与行为金融评估双重保障\n\n---\n\n\n\n## 异常检测系统\n\n### 相关页面\n\n相关主题：[代理信用评分系统](#credit-score), [治理与合规框架](#governance), [身份与认证系统](#identity-auth)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/anomaly.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/anomaly.ts)\n- [src/fraud.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/fraud.ts)\n- [src/fraud-ml.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/fraud-ml.ts)\n- [src/recall/rerank.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/recall/rerank.ts)\n- [CLAUDE.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/CLAUDE.md)\n- [README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n \n\n# 异常检测系统\n\n## 概述\n\n异常检测系统是 MnemoPay SDK 的核心安全组件之一，旨在保护 AI Agent 的交易行为和财务操作免受欺诈、滥用和异常模式的侵害。该系统采用多层次检测策略，结合统计学方法（EWMA）、行为监控、地理增强分析和机器学习模型，实现实时的交易风险评估和异常预警。\n\n根据项目架构文档，异常检测系统与其他组件（记忆系统、支付系统、身份系统）并列，共同构成了 MnemoPay SDK 的四大支柱。资料来源：[README.md:11]()\n\n## 核心架构\n\n### 模块组成\n\n| 模块 | 文件路径 | 主要功能 |\n|------|----------|----------|\n| `anomaly.ts` | `src/anomaly.ts` | EWMA 指数加权移动平均检测、行为监控、金丝雀系统 |\n| `fraud.ts` | `src/fraud.ts` | 地理增强欺诈检测、速度限制、费用分析 |\n| `fraud-ml.ts` | `src/fraud-ml.ts` | 机器学习驱动的欺诈模式识别 |\n| `rerank.ts` | `src/recall/rerank.ts` | 记忆检索重排序（异常关联分析） |\n\n### 系统架构图\n\n```mermaid\ngraph TB\n subgraph 异常检测系统\n A[交易事件输入] --> B[行为监控器
BehaviorMonitor]\n B --> C[EWMA 检测器]\n B --> D[速度限制检查
Velocity Check]\n C --> E[金丝雀系统
CanarySystem]\n D --> E\n E --> F[地理欺诈检测
Geo-Fraud]\n F --> G[ML 欺诈检测
fraud-ml]\n G --> H[风险评分引擎]\n end\n \n H --> I{风险等级判定}\n I -->|低风险| J[允许交易]\n I -->|中风险| K[标记审查]\n I -->|高风险| L[阻断交易]\n \n M[记忆系统] -->|行为特征| B\n N[身份系统] -->|权限信息| G\n```\n\n## EWMA 异常检测\n\n### 算法原理\n\nEWMA（Exponentially Weighted Moving Average，指数加权移动平均）是一种统计过程控制方法，用于检测时间序列数据中的异常波动。MnemoPay SDK 使用 EWMA 来监控 Agent 的交易行为模式，当实时指标偏离历史基线超过预设阈值时触发告警。\n\n资料来源：[CLAUDE.md:14]()\n\n### 核心配置参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `decay_factor` | EWMA 衰减因子，控制历史数据的权重 | `0.95` |\n| `alert_threshold` | 告警触发阈值（标准差倍数） | `3.0` |\n| `warmup_period` | 预热期样本数（建立基线前不告警） | `100` |\n| `reset_on_drift` | 检测到漂移时是否重置基线 | `true` |\n\n### 使用示例\n\n```typescript\nimport { AnomalyDetector, EWMAConfig } from '@mnemopay/sdk';\n\nconst config: EWMAConfig = {\n decay_factor: 0.95,\n alert_threshold: 3.0,\n warmup_period: 100,\n reset_on_drift: true\n};\n\nconst detector = new AnomalyDetector(config);\n\n// 监控交易金额异常\nconst result = detector.checkTransaction({\n agentId: 'agent-001',\n amount: 150.00,\n timestamp: Date.now()\n});\n\nif (result.anomaly) {\n console.log(`检测到异常: ${result.reason}, 置信度: ${result.confidence}`);\n}\n```\n\n## 行为监控系统\n\n### BehaviorMonitor\n\n行为监控器是异常检测系统的核心组件，持续追踪 Agent 的多维度行为指标：\n\n- **交易频率**：单位时间内的交易数量\n- **平均交易金额**：历史交易的平均值和标准差\n- **时间模式**：交易发生的时间分布特征\n- **地理分布**：交易来源的地理位置变化\n- **交互模式**：与其他 Agent 的交互频率和类型\n\n资料来源：[CLAUDE.md:14]()\n\n### 行为指标表\n\n| 指标类型 | 监控内容 | 异常阈值 |\n|----------|----------|----------|\n| `velocity` | 交易速率 | > 10 tx/min |\n| `amount_deviation` | 金额偏离度 | > 3σ |\n| `geo_entropy` | 地理熵值 | < 0.2 |\n| `session_count` | 会话数量 | 异常激增 |\n| `api_error_rate` | API 错误率 | > 5% |\n\n## 金丝雀系统\n\n### 功能概述\n\n金丝雀系统（CanarySystem）是一种渐进式发布和灰度检测机制，用于在生产环境中验证新交易模式或检测潜在的异常行为。它通过引入一小部分\"金丝雀\"交易来测试系统的响应，并将结果与基线进行对比。\n\n资料来源：[CLAUDE.md:14]()\n\n### 工作流程\n\n```mermaid\ngraph LR\n A[新交易模式] --> B[金丝雀采样
10% 流量]\n B --> C{模式匹配?}\n C -->|是| D[执行交易]\n C -->|否| E[记录异常]\n D --> F[监控系统响应]\n F --> G{响应正常?}\n G -->|是| H[扩大流量]\n G -->|否| I[回滚/告警]\n```\n\n### 金丝雀配置\n\n```typescript\ninterface CanaryConfig {\n sample_rate: number; // 采样比例 (0-1)\n timeout_ms: number; // 超时时间\n alert_on_fail: boolean; // 失败时告警\n auto_rollback: boolean; // 自动回滚\n}\n```\n\n## 地理欺诈检测\n\n### 地理增强分析\n\n`fraud.ts` 模块实现了基于地理位置的欺诈检测功能，通过分析交易的地理分布来识别潜在的欺诈行为。资料来源：[CLAUDE.md:13]()\n\n### 检测机制\n\n| 检测类型 | 说明 | 阈值配置 |\n|----------|------|----------|\n| `velocity_geo` | 地理速度异常（不可能的旅行） | 500 km/h |\n| `sanctions_check` | 制裁名单匹配 | 精确匹配 |\n| `proxy_vpn` | 代理/VPN 使用检测 | 概率 > 0.7 |\n| `geo_trust_score` | 地理信任评分 | < 0.3 |\n\n### 集成测试\n\n项目包含专门的地理欺诈测试文件 `geo-fraud.test.ts`，覆盖以下场景：\n\n- 地理信号处理\n- 信任评分计算\n- 制裁名单检查\n- 不可能旅行检测\n\n资料来源：[README.md:40-43]()\n\n## 机器学习欺诈检测\n\n### fraud-ml 模块\n\n`fraud-ml.ts` 模块使用机器学习算法来识别复杂的欺诈模式。该模块提供了基于历史数据的模型训练和实时推理能力。\n\n资料来源：[CLAUDE.md:13]()\n\n### 模型特征\n\n| 特征类别 | 特征名称 | 数据类型 |\n|----------|----------|----------|\n| 交易特征 | `amount`, `frequency`, `time_gap` | float |\n| 行为特征 | `session_length`, `error_rate` | float |\n| 网络特征 | `counterparty_count`, `graph_centrality` | float |\n| 历史特征 | `chargeback_rate`, `dispute_count` | float |\n\n### 预测接口\n\n```typescript\ninterface FraudPrediction {\n score: number; // 欺诈概率 (0-1)\n risk_level: 'low' | 'medium' | 'high';\n factors: string[]; // 主要风险因素\n confidence: number; // 预测置信度\n}\n```\n\n## 速度限制检查\n\n### 速率限制机制\n\n速度限制（Velocity Check）是防止滥用和欺诈的第一道防线，通过限制单位时间内的操作次数来实现。\n\n```mermaid\ngraph TD\n A[请求到达] --> B{速率限制检查}\n B -->|通过| C[处理交易]\n B -->|超限| D[返回 429 Too Many Requests]\n C --> E[更新计数器]\n E --> F[滑动窗口刷新]\n```\n\n### 配置参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `max_per_minute` | 每分钟最大请求数 | 60 |\n| `max_per_hour` | 每小时最大请求数 | 1000 |\n| `max_per_day` | 每天最大请求数 | 10000 |\n| `burst_allowance` | 突发容许量 | 10 |\n\n## 重放攻击检测\n\n### 重放检测机制\n\n异常检测系统还包括对重放攻击（Replay Attack）的防护，通过以下机制实现：\n\n1. **时间戳验证**：检查请求时间戳是否在有效窗口内（默认 300 秒）\n2. **Nonce 管理**：跟踪已处理的 Nonce 值，防止重复执行\n3. **签名校验**：验证 HMAC-SHA256 签名的有效性\n\n```typescript\ninterface ReplayCheckResult {\n valid: boolean;\n reason?: string; // 失败原因\n timestamp_age?: number; // 时间戳年龄（秒）\n}\n```\n\n资料来源：[src/mcp/server.ts:24-30]()\n\n## 与其他模块的集成\n\n### 模块依赖关系\n\n```mermaid\ngraph TB\n ANOMALY[异常检测系统] --> IDENTITY[身份系统]\n ANOMALY --> LEDGER[账本系统]\n ANOMALY --> MEMORY[记忆系统]\n ANOMALY --> NETWORK[网络系统]\n \n IDENTITY -->|权限信息| ANOMALY\n MEMORY -->|行为基线| ANOMALY\n NETWORK -->|交易图谱| ANOMALY\n LEDGER -->|审计日志| ANOMALY\n```\n\n### 集成点\n\n| 集成模块 | 集成方式 | 数据流向 |\n|----------|----------|----------|\n| 身份系统 | CapabilityToken 验证 | 输入 |\n| 记忆系统 | 行为基线查询 | 输入 |\n| 账本系统 | 双录审计日志 | 输出 |\n| 网络系统 | 交易图谱分析 | 双向 |\n\n## 测试覆盖\n\n### 测试文件\n\n项目为异常检测系统提供了全面的测试覆盖：\n\n| 测试文件 | 覆盖范围 | 测试数量 |\n|----------|----------|----------|\n| `core.test.ts` | EWMA、Canary、基线漂移 | 核心功能 |\n| `fraud.test.ts` | 速度限制、异常检测、费用分析、争议处理、重放检测 | 8+ 场景 |\n| `geo-fraud.test.ts` | 地理信号、信任评分、制裁检查 | 地理场景 |\n| `stress-200k.test.ts` | 高并发下的异常检测稳定性 | 200K 操作 |\n\n资料来源：[README.md:35-46]()\n\n### 运行测试\n\n```bash\n# 运行所有异常检测相关测试\nnpm test -- anomaly\n\n# 运行地理欺诈测试\nnpm test -- geo-fraud\n\n# 运行压力测试\nnpm test -- stress-200k\n```\n\n## 配置最佳实践\n\n### 生产环境配置建议\n\n```typescript\nconst productionConfig = {\n anomaly: {\n decay_factor: 0.98, // 更敏感的衰减\n alert_threshold: 2.5, // 降低阈值提高灵敏度\n warmup_period: 500, // 更长的预热期\n reset_on_drift: false // 不自动重置，需人工介入\n },\n canary: {\n sample_rate: 0.01, // 1% 采样\n timeout_ms: 5000,\n alert_on_fail: true,\n auto_rollback: true\n },\n geo_fraud: {\n velocity_threshold: 300, // km/h\n trust_score_threshold: 0.5,\n sanctions_check_enabled: true\n },\n rate_limit: {\n max_per_minute: 30,\n max_per_hour: 500,\n max_per_day: 5000\n }\n};\n```\n\n### 告警阈值调整\n\n| 风险等级 | EWMA 倍数 | 地理评分 | 建议操作 |\n|----------|-----------|----------|----------|\n| 低风险 | < 2σ | > 0.7 | 允许通过 |\n| 中风险 | 2-3σ | 0.4-0.7 | 添加人工审核 |\n| 高风险 | > 3σ | < 0.4 | 自动阻断 |\n\n## 总结\n\n异常检测系统是 MnemoPay SDK 保障 AI Agent 交易安全的核心防线，通过 EWMA 统计方法、行为监控、金丝雀验证、地理增强分析和机器学习模型的协同工作，实现了多层次、多维度的欺诈防护。该系统与身份系统、记忆系统、账本系统和网络系统紧密集成，形成完整的安全生态。开发者可根据具体业务场景调整检测参数，在安全性与用户体验之间取得平衡。\n\n---\n\n\n\n## 支付轨道\n\n### 相关页面\n\n相关主题：[账本与支付系统](#ledger-payments), [治理与合规框架](#governance)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/rails/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/index.ts)\n- [src/rails/stripe-mpp.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/stripe-mpp.ts)\n- [src/rails/x402.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/x402.ts)\n- [src/rails/google-ap2.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/google-ap2.ts)\n- [src/rails/paystack.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/paystack.ts)\n- [src/commerce/providers/shopify.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/commerce/providers/shopify.ts)\n- [src/commerce/providers/firecrawl.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/commerce/providers/firecrawl.ts)\n- [examples/02-openai-middleware.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/examples/02-openai-middleware.ts)\n- [examples/03-anthropic-middleware.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/examples/03-anthropic-middleware.ts)\n \n\n# 支付轨道\n\n## 概述\n\n支付轨道（Payment Rails）是 MnemoPay SDK 中处理实际资金流转的核心模块，为 AI Agent 提供统一抽象的支付接口。无论底层使用 Stripe、Paystack 还是 Lightning Network，开发者都可通过相同的 API 进行扣款、托管、结算和退款操作。\n\n支付轨道的设计目标包括：\n\n- **统一抽象**：不同支付渠道使用相同的方法签名，降低集成复杂度\n- **多渠道支持**：覆盖全球主要支付区域，包括非洲、欧洲、北美和加密货币\n- **安全托管**：支持人工审批后才释放资金，防止 Agent 未经授权的消费\n- **可扩展架构**：预留扩展接口，便于添加新的支付轨道\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 支持的支付轨道\n\nMnemoPay SDK 目前支持六种支付轨道，分为稳定版和预览版两类。\n\n| 轨道名称 | 覆盖区域 | 状态 | 通道标签 |\n|---------|---------|------|---------|\n| `StripeRail` | 全球（USD, EUR, GBP） | 稳定版 | `latest` |\n| `PaystackRail` | 非洲（NGN, GHS, ZAR, KES） | 稳定版 | `latest` |\n| `LightningRail` | BTC 微支付 | 稳定版 | `latest` |\n| `StripeMPPRail` | Tempo 加密货币存款 | 预览版 | `alpha` |\n| `X402Rail` | Base USDC（EIP-3009） | 预览版 | `alpha` |\n| `GoogleAP2Rail` | AP2 v0.2 FIDO Alliance | 预览版 | `alpha` |\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n### 稳定版轨道\n\n稳定版支付轨道经过生产环境验证，适合对可靠性要求较高的应用场景：\n\n- **StripeRail**：支持 135+ 种货币，采用 PaymentIntents API，支持手动捕获实现真正的托管功能\n- **PaystackRail**：覆盖 23 家尼日利亚银行，集成 HMAC-SHA512 安全校验\n- **LightningRail**：专为 BTC 子美分级微支付设计\n\n### 预览版轨道\n\n预览版支付轨道处于活跃开发阶段，可能存在 API 变更：\n\n- **StripeMPPRail**：通过 Stripe Marketplace Payments 实现加密货币存款\n- **X402Rail**：使用 EIP-3009 的 `transferWithAuthorization` 实现 Base 链上的 USDC 转账\n- **GoogleAP2Rail**：基于 FIDO Alliance AP2 v0.2 的 mandate 驱动结算\n\n资料来源：[src/rails/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/index.ts)\n\n## 核心架构\n\n### 轨道接口设计\n\n所有支付轨道继承自统一的基类接口，确保 API 一致性：\n\n```mermaid\nclassDiagram\n class PaymentRail {\n <>\n +charge(amount, metadata) Promise~ChargeResult~\n +settle(txId) Promise~SettleResult~\n +refund(txId, amount) Promise~RefundResult~\n +webhook(payload) Promise~WebhookResult~\n }\n \n class StripeRail {\n +stripe: Stripe\n +charge()\n +settle()\n +refund()\n }\n \n class PaystackRail {\n +paystack: Paystack\n +charge()\n +settle()\n +refund()\n }\n \n class LightningRail {\n +lnd: LNDClient\n +charge()\n +settle()\n }\n \n PaymentRail <|-- StripeRail\n PaymentRail <|-- PaystackRail\n PaymentRail <|-- LightningRail\n```\n\n### 交易流程\n\n支付轨道支持完整的交易生命周期管理：\n\n```mermaid\ngraph TD\n A[Agent 请求扣款] --> B{支付轨道选择}\n B --> C[StripeRail]\n B --> D[PaystackRail]\n B --> E[LightningRail]\n \n C --> F[创建 PaymentIntent]\n D --> G[初始化 Paystack Transaction]\n E --> H[创建 Lightning Invoice]\n \n F --> I{用户确认}\n G --> I\n H --> I\n \n I -->|确认| J[资金托管]\n I -->|拒绝| K[交易取消]\n \n J --> L{人工审批}\n L -->|通过| M[结算 settle]\n L -->|拒绝| N[退款 refund]\n \n M --> O[资金释放给商户]\n N --> P[资金退回用户]\n```\n\n资料来源：[src/rails/stripe-mpp.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/stripe-mpp.ts)\n\n## 快速开始\n\n### 导入支付轨道\n\n```typescript\nimport {\n PaystackRail, StripeRail, LightningRail, // 稳定版\n StripeMPPRail, X402Rail, GoogleAP2Rail, // 预览版\n} from \"@mnemopay/sdk\";\n```\n\n### 初始化支付轨道\n\n**Stripe 稳定配置：**\n\n```typescript\nconst stripe = new StripeRail(process.env.STRIPE_SECRET_KEY!);\n```\n\n**Paystack 非洲支付：**\n\n```typescript\nconst paystack = new PaystackRail(process.env.PAYSTACK_SECRET_KEY!);\n```\n\n**Lightning BTC 微支付：**\n\n```typescript\nconst lightning = new LightningRail(LND_URL, MACAROON);\n```\n\n**预览版支付轨道：**\n\n```typescript\n// Stripe MPP 加密货币存款\nconst mpp = new StripeMPPRail(process.env.STRIPE_SECRET_KEY!);\n\n// X402 USDC 转账\nconst x402 = new X402Rail({ signer: yourEip3009Signer });\n\n// Google AP2 FIDO 结算\nconst ap2 = new GoogleAP2Rail({ mandate, endpoint, signer });\n```\n\n资料来源：[README.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n### 与 Agent 集成\n\n初始化 Agent 时指定支付轨道：\n\n```typescript\nconst agent = MnemoPay.quick(\"my-agent\", {\n rail: new StripeRail(process.env.STRIPE_SECRET_KEY!),\n // 其他配置...\n});\n```\n\n## 各支付轨道详解\n\n### StripeRail\n\nStripeRail 是面向全球市场的支付轨道，支持 135+ 种货币和信用卡、借记卡支付。\n\n**核心方法：**\n\n| 方法 | 参数 | 返回值 | 说明 |\n|-----|------|-------|------|\n| `charge` | `amount`, `currency`, `metadata` | `ChargeResult` | 创建扣款请求 |\n| `settle` | `txId` | `SettleResult` | 结算已托管的交易 |\n| `refund` | `txId`, `amount?` | `RefundResult` | 退款交易 |\n| `createIntent` | `params` | `PaymentIntent` | 创建 PaymentIntent |\n\n**安全特性：**\n\n- 手动捕获模式支持真正的资金托管\n- PaymentIntents API 提供 3D Secure 支持\n- Webhook 签名验证\n\n资料来源：[src/rails/stripe-mpp.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/stripe-mpp.ts)\n\n### PaystackRail\n\nPaystackRail 专注于非洲市场，深度集成当地银行系统。\n\n**支持货币：**\n\n- NGN（尼日利亚奈拉）\n- GHS（加纳塞地）\n- ZAR（南非兰特）\n- KES（肯尼亚先令）\n\n**特色功能：**\n\n- 23 家尼日利亚银行预映射\n- HMAC-SHA512 Webhook 安全校验\n- 移动支付和银行转账支持\n\n```typescript\nconst paystack = new PaystackRail(process.env.PAYSTACK_SECRET_KEY!);\n\n// 非洲本地支付\nawait paystack.charge(5000, {\n currency: 'NGN',\n email: 'customer@example.com',\n bank: '044' // Access Bank\n});\n```\n\n资料来源：[src/rails/paystack.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/paystack.ts)\n\n### LightningRail\n\nLightningRail 专为比特币微支付设计，支持子美分级的小额交易。\n\n**技术特性：**\n\n- 即时结算（相较于链上 BTC）\n- 极低手续费，适合微支付场景\n- 依赖 LND（Lightning Network Daemon）\n\n```typescript\nconst lightning = new LightningRail(LND_URL, MACAROON);\n\n// 创建 Lightning Invoice\nconst invoice = await lightning.charge(100, {\n description: 'API调用费用',\n expiry: 3600 // 1小时过期\n});\n```\n\n### X402Rail\n\nX402Rail 实现 EIP-3009 标准，在 Base 区块链上支持 USDC 转账。\n\n**核心流程：**\n\n```mermaid\ngraph LR\n A[请求授权] --> B[生成 transferWithAuthorization]\n B --> C[用户签名授权]\n C --> D[执行 USDC 转账]\n D --> E[交易确认]\n```\n\n**配置参数：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|-----|------|-----|------|\n| `signer` | `EIP3009Signer` | 是 | EIP-3009 签名器实例 |\n| `recipient` | `string` | 否 | 默认收款地址 |\n| `domain` | `string` | 否 | EIP-712 域名 |\n\n```typescript\nconst x402 = new X402Rail({\n signer: yourEip3009Signer,\n recipient: '0x...'\n});\n```\n\n资料来源：[src/rails/x402.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/x402.ts)\n\n### GoogleAP2Rail\n\nGoogleAP2Rail 基于 FIDO Alliance 的 AP2 v0.2 标准，提供 mandate 驱动的结算机制。\n\n**Mandate 概念：**\n\nMandate 是用户预先授权的支付指令，允许商户在特定条件下自动扣款。\n\n```typescript\nconst ap2 = new GoogleAP2Rail({\n mandate: {\n id: 'mandate_xxx',\n maxAmount: 10000,\n currency: 'USD',\n frequency: 'per_use'\n },\n endpoint: 'https://api.google.com/ap2/v2',\n signer: yourSigner\n});\n```\n\n资料来源：[src/rails/google-ap2.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/google-ap2.ts)\n\n### StripeMPPRail\n\nStripeMPPRail（Marketplace Payments）允许通过 Stripe 实现加密货币存款和结算。\n\n**应用场景：**\n\n- 多方分账场景\n- 加密货币与法币混合支付\n- Tempo 生态内的资金流转\n\n```typescript\nconst mpp = new StripeMPPRail(process.env.STRIPE_SECRET_KEY!);\n\nawait mpp.charge(1000, {\n currency: 'usdc',\n destination: 'tempo_address_xxx'\n});\n```\n\n资料来源：[src/rails/stripe-mpp.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/rails/stripe-mpp.ts)\n\n## 托管与结算\n\n### 托管机制\n\n支付轨道支持资金托管（Escrow）功能，确保交易经过人工审批后再释放：\n\n```mermaid\ngraph TD\n A[charge 调用] --> B[资金进入托管状态]\n B --> C[等待人工审批]\n C --> D{审批结果}\n D -->|通过| E[settle 结算]\n D -->|拒绝| F[refund 退款]\n \n E --> G[资金释放给商户]\n F --> H[资金退回用户]\n```\n\n### Agent 消费限制\n\nAgent 的支付行为受以下限制保护：\n\n| 限制类型 | 说明 | 配置方式 |\n|---------|------|---------|\n| `llmCapCents` | LLM 调用费用上限 | 账户级别设置 |\n| `seats` | 授权席位数量 | 订阅计划决定 |\n| `missionLimit` | 任务执行次数限制 | 计划配额 |\n\n资料来源：[dashboard/index.html](https://github.com/mnemopay/mnemopay-sdk/blob/main/dashboard/index.html)\n\n## Webhook 处理\n\n支付轨道提供统一的 Webhook 接口处理各渠道的异步通知：\n\n```typescript\n// 定义 Webhook 处理函数\nasync function handleWebhook(rail: PaymentRail, payload: WebhookPayload) {\n switch (payload.type) {\n case 'payment.pending':\n // 等待用户确认\n break;\n case 'payment.succeeded':\n // 支付成功，进入托管\n break;\n case 'payment.failed':\n // 支付失败\n break;\n case 'settlement.completed':\n // 结算完成\n break;\n }\n}\n```\n\n**安全验证：**\n\n- Stripe：验证 `Stripe-Signature` 头\n- Paystack：HMAC-SHA512 签名校验\n- Lightning：Invoice 状态轮询\n\n## 错误处理\n\n### 错误类型\n\n| 错误码 | 说明 | 处理建议 |\n|-------|------|---------|\n| `INSUFFICIENT_FUNDS` | 余额不足 | 提示用户充值 |\n| `RAIL_UNAVAILABLE` | 支付渠道不可用 | 切换备用渠道 |\n| `KYC_REQUIRED` | 需要完成身份验证 | 引导用户 KYC |\n| `FRAUD_SUSPECTED` | 欺诈嫌疑 | 拒绝交易并标记 |\n| `SETTLEMENT_LIMIT` | 达到结算限额 | 分批结算 |\n\n### 重试策略\n\n```typescript\nasync function chargeWithRetry(rail: PaymentRail, amount: number, retries = 3) {\n for (let i = 0; i < retries; i++) {\n try {\n return await rail.charge(amount, {});\n } catch (error) {\n if (error.code === 'RAIL_UNAVAILABLE' && i < retries - 1) {\n await delay(1000 * (i + 1)); // 指数退避\n continue;\n }\n throw error;\n }\n }\n}\n```\n\n## 商业购物集成\n\n支付轨道可与商业购物模块配合，实现 Agent 的自主采购：\n\n### Shopify 集成\n\n```typescript\nimport { ShopifyProvider } from \"@mnemopay/commerce/providers/shopify\";\n\nconst shopify = new ShopifyProvider({\n shop: 'your-store.myshopify.com',\n token: process.env.SHOPIFY_TOKEN\n});\n\n// Agent 搜索商品\nconst products = await shopify.search({\n query: 'wireless headphones',\n price_max: 100\n});\n\n// 购买流程通过支付轨道托管\n```\n\n### Firecrawl 网页抓取\n\n```typescript\nimport { FirecrawlProvider } from \"@mnemopay/commerce/providers/firecrawl\";\n\nconst firecrawl = new FirecrawlProvider({\n apiKey: process.env.FIRECRAWL_KEY\n});\n\n// Agent 抓取电商网站比价\nconst prices = await firecrawl.scrape({\n url: 'https://example.com/products',\n query: 'price'\n});\n```\n\n资料来源：[src/commerce/providers/shopify.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/commerce/providers/shopify.ts)\n\n## LLM 中间件集成\n\n支付轨道可作为 LLM API 调用的计费中间件：\n\n### OpenAI 中间件\n\n```typescript\nimport { createOpenAIMiddleware } from \"@mnemopay/sdk/middleware/openai\";\n\nconst middleware = createOpenAIMiddleware({\n rail: new StripeRail(process.env.STRIPE_SECRET_KEY!),\n costPerToken: 0.0001\n});\n\napp.use('/v1/chat/completions', middleware);\n```\n\n### Anthropic 中间件\n\n```typescript\nimport { createAnthropicMiddleware } from \"@mnemopay/sdk/middleware/anthropic\";\n\nconst middleware = createAnthropicMiddleware({\n rail: new StripeRail(process.env.STRIPE_SECRET_KEY!),\n modelCosts: {\n 'claude-3-opus': 0.015,\n 'claude-3-sonnet': 0.003\n }\n});\n```\n\n资料来源：[examples/02-openai-middleware.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/examples/02-openai-middleware.ts)\n\n## 安全考虑\n\n### 密钥管理\n\n- 支付渠道密钥应存储在环境变量或密钥管理服务\n- 切勿将密钥硬编码或提交到版本控制\n- 生产环境应使用独立的 Stripe/Paystack 密钥\n\n### 签名验证\n\n所有 Webhook 回调必须验证签名：\n\n```typescript\nasync function verifyWebhook(rail: PaymentRail, payload: Buffer, signature: string) {\n return await rail.verifySignature(payload, signature);\n}\n```\n\n### 交易限额\n\n建议为不同信任级别的 Agent 设置交易限额：\n\n| Agent 等级 | 单笔限额 | 日累计限额 |\n|-----------|---------|-----------|\n| 新建 | $10 | $50 |\n| 已验证 | $100 | $500 |\n| 高信用 | $1000 | $10000 |\n| 企业 | 自定义 | 自定义 |\n\n## 总结\n\n支付轨道是 MnemoPay SDK 的核心组件，为 AI Agent 提供安全、统一的支付能力。通过支持 Stripe、Paystack、Lightning 等多种渠道，开发者可以灵活选择适合目标市场的支付方式。稳定版轨道已通过生产验证，预览版轨道则为加密货币和新型支付协议提供了实验基础。\n\n无论选择哪种支付轨道，统一的 API 设计确保了代码的可移植性，而托管机制则保障了资金安全，防止 Agent 未经授权的消费行为。\n\n---\n\n\n\n## 治理与合规框架\n\n### 相关页面\n\n相关主题：[身份与认证系统](#identity-auth), [异常检测系统](#anomaly-detection), [代理信用评分系统](#credit-score)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/governance/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/index.ts)\n- [src/governance/charter.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/charter.ts)\n- [src/governance/policy.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/policy.ts)\n- [src/governance/policies/eu-ai-act.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/policies/eu-ai-act.ts)\n- [src/governance/audit.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/audit.ts)\n- [src/governance/audit-chain.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/audit-chain.ts)\n- [src/governance/spatial.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/spatial.ts)\n- [src/governance/runtime.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/runtime.ts)\n- [src/governance/approval.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/approval.ts)\n- [compliance/eu-ai-act-annex-iv.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/compliance/eu-ai-act-annex-iv.md)\n- [docs/aaif-rfc-agent-trust-attestation.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/docs/aaif-rfc-agent-trust-attestation.md)\n \n\n# 治理与合规框架\n\n## 概述\n\nMnemoPay SDK 的治理与合规框架是为 AI Agent 提供的一套完整的经济治理、安全审计和监管合规系统。该框架确保 Agent 在执行支付、记忆存储和资源使用等关键操作时遵循预定义的业务规则、预算限制和法规要求。\n\n根据架构文档，治理框架包含以下核心组件：\n\n| 组件 | 功能 | 类别 |\n|------|------|------|\n| Charter (宪章) | 定义 Agent 任务范围和权限边界 | 任务治理 |\n| FiscalGate (财务门控) | 预算执行和费用控制 | 财务治理 |\n| Article 12 (第12条) | EU AI Act 合规要求 | 法规合规 |\n| MerkleAudit (默克尔审计) | 加密审计链和不可篡改记录 | 审计追溯 |\n\n资料来源：[README.md - Architecture](https://github.com/mnemopay/mnemopay-sdk/blob/main/README.md)\n\n## 核心架构\n\n治理框架采用分层架构设计，从运行时决策到长期审计形成完整闭环：\n\n```mermaid\ngraph TD\n A[Agent 请求] --> B[宪章验证 Charter]\n B --> C{权限检查}\n C -->|通过| D[FiscalGate 预算验证]\n C -->|拒绝| E[请求拦截]\n D --> F{预算充足?}\n F -->|是| G[Article 12 合规检查]\n F -->|否| H[预算超限拦截]\n G --> I{合规判定}\n I -->|通过| J[运行时 Runtime]\n I -->|拒绝| K[合规拦截]\n J --> L[操作执行]\n L --> M[审计记录 Audit]\n M --> N[审计链 Chain]\n N --> O[默克尔根 MerkleRoot]\n```\n\n## 宪章系统 (Charter)\n\n### 功能定义\n\n宪章系统定义了每个 Agent 的任务范围、操作权限和资源配额。它是所有治理决策的第一道关卡。\n\n### 核心配置\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `scope` | string[] | 允许的操作类型列表 |\n| `maxBudget` | number | 最大预算限额 |\n| `permissions` | Permission[] | 细粒度权限配置 |\n| `ttl` | number | 宪章有效期（秒） |\n| `version` | string | 宪章版本号 |\n\n资料来源：[src/governance/charter.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/charter.ts)\n\n## 财务门控 (FiscalGate)\n\n### 预算执行机制\n\nFiscalGate 负责在交易执行前验证预算是否充足，并在操作完成后更新实际支出。\n\n```mermaid\ngraph LR\n A[charge 请求] --> B[获取宪章预算]\n B --> C{当前支出}\n C --> D{支出 + 本次金额 <= 预算?}\n D -->|是| E[执行 charge]\n D -->|否| F[触发 overLimit]\n E --> G[更新计量 metering]\n F --> H[记录违规事件]\n```\n\n### 计量数据模型\n\n```typescript\ninterface Metering {\n total: number; // 总支出\n seats: number; // 活跃席位\n missions: Mission[]; // 任务记录\n overLimit: boolean; // 是否超限\n}\n```\n\n资料来源：[src/governance/runtime.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/runtime.ts)\n\n## 策略系统 (Policy)\n\n### 策略引擎架构\n\n策略系统提供可扩展的规则引擎，支持自定义合规策略和第三方监管要求。\n\n### EU AI Act 合规\n\n根据 EU AI Act Annex IV 要求，系统实现了以下合规检查：\n\n| 检查项 | 描述 | 风险等级 |\n|--------|------|----------|\n| 目的限制 | 验证操作符合声明用途 | 高 |\n| 人类监督 | 确保关键决策有人工介入 | 高 |\n| 准确性 | 验证模型输出的可靠性 | 中 |\n| 韧性 | 错误处理和异常恢复 | 中 |\n| 安全性 | 数据保护和访问控制 | 高 |\n| 透明性 | 操作日志和可解释性 | 中 |\n\n资料来源：[src/governance/policies/eu-ai-act.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/policies/eu-ai-act.ts)\n\n### 策略配置示例\n\n```typescript\nconst policy = {\n id: 'eu-ai-act-high-risk',\n version: '1.0',\n rules: [\n { type: 'human_oversight', threshold: 0.95 },\n { type: 'data_minimization', scope: ['pii', 'financial'] },\n { type: 'audit_trail', retention: 365 }\n ]\n};\n```\n\n资料来源：[src/governance/policy.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/policy.ts)\n\n## 审计系统 (Audit)\n\n### 审计链架构\n\n审计系统采用默克尔树（Merkle Tree）结构确保审计记录的不可篡改性。\n\n```mermaid\ngraph TD\n A[操作事件] --> B[生成审计记录]\n B --> C[计算哈希]\n C --> D[添加到叶节点]\n D --> E{批量达到阈值?}\n E -->|是| F[计算默克尔根]\n E -->|否| G[缓存待处理]\n F --> H[发布到审计链]\n H --> I[存储证明]\n```\n\n### 审计记录结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 唯一标识符 |\n| `timestamp` | number | Unix 时间戳 |\n| `agentId` | string | Agent 标识 |\n| `action` | string | 操作类型 |\n| `result` | string | 执行结果 |\n| `metadata` | object | 附加元数据 |\n| `hash` | string | 记录哈希值 |\n\n### 默克尔证明\n\n每个审计记录包含指向前一记录的哈希链接，形成链式结构：\n\n```typescript\ninterface AuditRecord {\n record: AuditData;\n prevHash: string;\n merkleProof?: MerkleProof;\n}\n```\n\n资料来源：[src/governance/audit-chain.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/audit-chain.ts)\n\n### 审计 Bundle\n\n审计 Bundle 是批量打包的审计记录，支持高效的批量验证和存储：\n\n```typescript\ninterface AuditBundle {\n id: string;\n records: AuditRecord[];\n merkleRoot: string;\n timestamp: number;\n signature: string;\n}\n```\n\n资料来源：[src/governance/audit.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/audit.ts)\n\n## 运行时治理 (Runtime)\n\n### 运行时决策流程\n\n运行时系统负责在操作执行期间进行实时监控和干预。\n\n```mermaid\ngraph TD\n A[操作开始] --> B[加载宪章]\n B --> C[权限检查]\n C --> D{权限验证}\n D -->|通过| E[加载策略]\n D -->|拒绝| F[抛出 PolicyViolation]\n E --> G[执行前钩子 preHook]\n G --> H{前置条件满足?}\n H -->|是| I[执行业务逻辑]\n H -->|否| J[拒绝操作]\n I --> K[执行后钩子 postHook]\n K --> L[更新审计链]\n L --> M[返回结果]\n```\n\n### 异常处理\n\n运行时支持多种异常类型：\n\n| 异常类型 | 触发条件 | 处理策略 |\n|----------|----------|----------|\n| `PolicyViolation` | 策略检查失败 | 拒绝并记录 |\n| `BudgetExceeded` | 预算超限 | 冻结操作 |\n| `PermissionDenied` | 权限不足 | 降级或拒绝 |\n| `ComplianceFailure` | 合规检查失败 | 阻断交易 |\n\n资料来源：[src/governance/runtime.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/runtime.ts)\n\n## 空间治理 (Spatial)\n\n### 概念定义\n\n空间治理定义了 Agent 的操作边界和资源隔离域。\n\n```typescript\ninterface SpatialContext {\n namespace: string; // 命名空间标识\n boundaries: Boundary[]; // 边界限制\n isolation: boolean; // 是否隔离\n}\n```\n\n### 边界类型\n\n| 类型 | 说明 | 约束 |\n|------|------|------|\n| `memory` | 记忆存储边界 | 存储量上限 |\n| `compute` | 计算资源边界 | CPU/内存配额 |\n| `network` | 网络访问边界 | 出站请求限制 |\n| `finance` | 财务操作边界 | 交易金额限制 |\n\n资料来源：[src/governance/spatial.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/spatial.ts)\n\n## 审批流程 (Approval)\n\n### 工作流状态机\n\n关键操作需要人工审批，审批流程遵循状态机模式：\n\n```mermaid\ngraph LR\n A[Pending] -->|提交| B[Awaiting Review]\n B -->|批准| C[Approved]\n B -->|拒绝| D[Rejected]\n C -->|执行| E[Completed]\n D -->|申诉| F[Under Appeal]\n F -->|重新审查| B\n E -->|失败| G[Failed]\n```\n\n### 审批配置\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `requireApproval` | true | 是否需要审批 |\n| `approvers` | string[] | 审批者列表 |\n| `timeout` | 86400 | 超时时间（秒） |\n| `autoEscalate` | false | 超时自动升级 |\n\n资料来源：[src/governance/approval.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/approval.ts)\n\n## 合规框架集成\n\n### EU AI Act 合规清单\n\n根据 Annex IV 要求，MnemoPay SDK 实现了以下技术文档要求：\n\n| 要求 | 实现状态 | 组件 |\n|------|----------|------|\n| 系统描述 | ✅ | Charter |\n| 训练数据来源 | ✅ | Memory Module |\n| 模型架构 | ✅ | Agent Core |\n| 决策逻辑 | ✅ | Runtime |\n| 人类监督措施 | ✅ | Approval |\n| 准确性评估 | ✅ | Audit |\n| 风险评估报告 | ✅ | Policy Engine |\n\n资料来源：[compliance/eu-ai-act-annex-iv.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/compliance/eu-ai-act-annex-iv.md)\n\n### Agent 信任证明 (AAIF)\n\n系统支持 Agent 身份和行为的信任证明机制：\n\n```typescript\ninterface AgentTrustAttestation {\n agentId: string;\n charterHash: string;\n auditRoot: string;\n complianceLevel: 'basic' | 'standard' | 'enhanced';\n issuedAt: number;\n expiresAt: number;\n signature: string;\n}\n```\n\n资料来源：[docs/aaif-rfc-agent-trust-attestation.md](https://github.com/mnemopay/mnemopay-sdk/blob/main/docs/aaif-rfc-agent-trust-attestation.md)\n\n## 快速开始\n\n### 初始化治理上下文\n\n```typescript\nimport { GovernanceContext } from '@mnemopay/sdk/governance';\n\nconst ctx = new GovernanceContext({\n charter: {\n scope: ['memory:remember', 'memory:recall', 'payment:charge'],\n maxBudget: 1000,\n permissions: ['read:profile', 'write:transaction']\n },\n policy: 'eu-ai-act-standard',\n requireApproval: true\n});\n```\n\n### 执行受治理的操作\n\n```typescript\nconst result = await ctx.execute('payment:charge', {\n amount: 50,\n currency: 'USD',\n recipient: 'agent-123'\n});\n\n// 审计记录自动生成\nconsole.log(result.auditId); // 审计追踪ID\n```\n\n## API 参考\n\n### GovernanceContext\n\n| 方法 | 参数 | 返回值 | 说明 |\n|------|------|--------|------|\n| `execute(action, params)` | 操作类型, 参数对象 | ExecutionResult | 执行受治理操作 |\n| `verifyPolicy(record)` | 审计记录 | boolean | 验证策略合规性 |\n| `getMerkleProof(auditId)` | 审计ID | MerkleProof | 获取默克尔证明 |\n| `exportAuditBundle()` | 无 | AuditBundle | 导出审计包 |\n\n资料来源：[src/governance/index.ts](https://github.com/mnemopay/mnemopay-sdk/blob/main/src/governance/index.ts)\n\n## 最佳实践\n\n### 1. 宪章配置\n\n- 遵循最小权限原则，仅授予必要权限\n- 设置合理的预算上限和 TTL\n- 定期审核和更新宪章版本\n\n### 2. 审计策略\n\n- 确保所有敏感操作都生成审计记录\n- 定期导出和验证审计 Bundle\n- 保留足够长度的审计历史（建议 365+ 天）\n\n### 3. 合规检查\n\n- 对高风险操作启用人工审批\n- 定期运行 EU AI Act 合规检查\n- 维护完整的信任证明链\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：mnemopay/mnemopay-sdk\n\n摘要：发现 8 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 涉及密钥、隐私或敏感领域。\n\n## 1. 安全/权限坑 · 涉及密钥、隐私或敏感领域\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。\n- 对用户的影响：金融、交易、隐私和密钥场景必须比普通工具更保守。\n- 建议检查：补敏感数据流、密钥存储和权限边界审查。\n- 防护动作：敏感领域或密钥场景必须保守推荐并要求人工复核。\n- 证据：packet_text.keyword_scan | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | matched secret / private key / privacy / trading / finance keyword\n\n## 2. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `mnemopay-sdk` 与安装入口 `@mnemopay/sdk` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npm install @mnemopay/sdk`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | repo=mnemopay-sdk; install=@mnemopay/sdk\n\n## 3. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | README/documentation is current enough for a first validation pass.\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | no_demo; severity=medium\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：mnemopay/mnemopay-sdk\n\n摘要：发现 8 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 涉及密钥、隐私或敏感领域。\n\n## 1. 安全/权限坑 · 涉及密钥、隐私或敏感领域\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。\n- 对用户的影响：金融、交易、隐私和密钥场景必须比普通工具更保守。\n- 建议检查：补敏感数据流、密钥存储和权限边界审查。\n- 防护动作：敏感领域或密钥场景必须保守推荐并要求人工复核。\n- 证据：packet_text.keyword_scan | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | matched secret / private key / privacy / trading / finance keyword\n\n## 2. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `mnemopay-sdk` 与安装入口 `@mnemopay/sdk` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npm install @mnemopay/sdk`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | repo=mnemopay-sdk; install=@mnemopay/sdk\n\n## 3. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | README/documentation is current enough for a first validation pass.\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | no_demo; severity=medium\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1197975871 | https://github.com/mnemopay/mnemopay-sdk | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# mnemopay-sdk - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mnemopay-sdk 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的数据分析与投资研究任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. getting-started：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. memory-system：内存与记忆系统。围绕“内存与记忆系统”模拟一次用户任务，不展示安装或运行结果。\n4. ledger-payments：账本与支付系统。围绕“账本与支付系统”模拟一次用户任务，不展示安装或运行结果。\n5. identity-auth：身份与认证系统。围绕“身份与认证系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. getting-started\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. memory-system\n输入：用户提供的“内存与记忆系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. ledger-payments\n输入：用户提供的“账本与支付系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. identity-auth\n输入：用户提供的“身份与认证系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / getting-started：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / quick-start：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / memory-system：Step 3 必须围绕“内存与记忆系统”形成一个小中间产物，并等待用户确认。\n- Step 4 / ledger-payments：Step 4 必须围绕“账本与支付系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / identity-auth：Step 5 必须围绕“身份与认证系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/mnemopay/mnemopay-sdk\n- https://github.com/mnemopay/mnemopay-sdk#readme\n- claude-plugin/skills/balance/SKILL.md\n- claude-plugin/skills/charge/SKILL.md\n- claude-plugin/skills/fico/SKILL.md\n- claude-plugin/skills/history/SKILL.md\n- claude-plugin/skills/recall/SKILL.md\n- claude-plugin/skills/remember/SKILL.md\n- claude-plugin/skills/settle/SKILL.md\n- claude-plugin/skills/shop/SKILL.md\n- integrations/openclaw/SKILL.md\n- README.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mnemopay-sdk 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：mnemopay/mnemopay-sdk\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install @mnemopay/sdk\n```\n\n来源：https://github.com/mnemopay/mnemopay-sdk#readme\n\n## 来源\n\n- repo: https://github.com/mnemopay/mnemopay-sdk\n- docs: https://github.com/mnemopay/mnemopay-sdk#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_f51821c637ca4c598b463bd39c40f528"
}