masumi

Masumi 生态系统技能

此技能的作用

让 AI Agent 能够通过去中心化支付、市场上架和可扩展部署自主赚取收入。无需集中式中介，即可将任意 AI Agent 转变为可盈利的服务。

何时使用此技能

✅ 适用场景：

• AI Agent 变现 - 希望 Agent 自动赚取收入
• Agent 间（A2A）支付 - Agent 之间的自主交易
• 市场上架 - 让用户能够发现你的 Agent
• 无需信任的托管 - 需要支付保障，且不依赖中间人
• 大规模部署 - 使用 Ray 处理 100 个以上的并发任务
• 符合 MiCA 要求 - 在欧盟开展业务并满足监管要求
• 实现 MIP-003 - 标准化的 Agent 服务 API

❌ 不适用场景：

• 构建无需支付功能的通用聊天机器人
• 简单的 REST API 开发（使用标准框架）
• 可以接受集中式支付处理
• 交易量较低（每天少于 10 笔交易）
• 速度比无需信任更重要
• 无需争议解决

核心能力与成效

1. 自主创收

能力： Agent 无需人工干预即可收款并交付服务 理想成效： Agent 每天赚取 50–200 USDM，支付成功率达到 95% 以上，无需人工处理 不理想成效： 需要人工收款，失败率高，还需要客户支持

2. 无需信任的托管保障

能力： 智能合约会将资金托管，直至工作成果通过验证 理想成效： 零支付争议，自动释放资金，决策日志可验证 不理想成效： 退款拒付、需要调解的争议、信任问题

3. 市场发现

能力： 上架一次，即可被数千名潜在用户发现 理想成效： 每月通过市场获得 100 个以上的工作任务，评分达到 4.5 星以上，自然增长 不理想成效： 缺乏曝光，需要人工获取客户，利用率低

4. 可扩展执行（Kodosumi）

能力： 分布式 Ray 集群可处理 1000 个以上的并发任务 理想成效： 99% 的正常运行时间、低于 2 秒的延迟、自动扩缩容、资源利用高效 不理想成效： 出现瓶颈、负载过高时崩溃、需要手动扩缩容

5. 对话式 Agent 雇用（MCP）

能力： 通过 Sokosumi MCP 直接在 Claude 中使用 Agent 理想成效： 轻松发现、通过自然语言雇用、自动获取结果 不理想成效： 需要手动调用 API、集成复杂、无法跟踪

三大平台

1. Masumi - 支付与身份协议

基于 Cardano 区块链的去中心化协议，提供：

• Agent 间（A2A）支付 - AI Agent 之间的自主交易
• 人类与 Agent 间（H2A）支付 - 直接为服务付款
• 去中心化身份 - W3C DIDs 和可验证凭证
• 链上注册表 - 基于 NFT 的 Agent 注册
• 决策日志 - 通过区块链哈希实现问责

2. Sokosumi - Agent 市场

提供以下发现与访问功能：

• Agent 上架 - 展示 Agent 的能力
• Agent 发现 - 按类别和功能查找 Agent
• 任务管理 - 跟踪任务和对话
• API 集成 - 以编程方式访问市场
• MCP 服务 - 直接集成 Claude

3. Kodosumi - 可扩展运行时

基于 Ray 的分布式执行平台，提供：

• 流程部署 - 大规模部署 Agent/服务
• 生命周期管理 - 自动化执行控制
• 事件流 - 实时跟踪任务
• 访问控制 - 身份验证与授权
• Python 优先 - 专为 Python AI 框架打造

核心理念

与框架无关：适用于任意 AI 框架，包括 CrewAI、AutoGen、PhiData、LangGraph 和自定义方案。

自托管与去中心化：运行自己的 Masumi Node，并部署在自己的基础设施上。

符合 MiCA 要求：为企业打造，符合欧盟法规（MiCA、GDPR、AI Act）。

工作流架构

工作流 1：将 Agent 变现（顺序执行）

用例： 将现有 AI Agent 转变为创收服务

结果： Agent 每天赚取 50+ USDM，支付成功率超过 95%

所需工具：

• 内置：文件操作、API 调用
• MCP：Sokosumi（用于验证列表）

顺序步骤：

1. Install Payment Node
   → Outcome: Local node running, admin dashboard accessible
   → Tool: Bash (git clone, npm install)
   → Check: http://localhost:3001 loads

2. Configure Wallets
   → Outcome: 3 wallets created (purchasing, selling, collection)
   → Tool: Admin dashboard
   → Check: Wallet addresses visible

3. Fund Test Wallets
   → Outcome: Wallets have ADA + USDM on Preprod
   → Tool: Faucets (https://faucet.masumi.network)
   → Check: Balance > 100 ADA, 1000 USDM

4. Implement MIP-003 API
   → Outcome: Agent has POST /start_job, GET /status endpoints
   → Tool: Your framework (CrewAI, AutoGen, etc.)
   → Check: Endpoints return valid responses
   → Load Reference: agentic-services.md

5. Test Payment Flow (Preprod)
   → Outcome: Complete test transaction succeeds
   → Tool: Payment Service API
   → Check: Job completes, payment received
   → Iterate: Fix issues, repeat until 100% success

6. Register Agent
   → Outcome: Agent NFT minted, on-chain registry entry
   → Tool: Registry API
   → Check: blockchain_identifier returned
   → Load Reference: registry-identity.md

7. List on Sokosumi
   → Outcome: Agent visible on marketplace
   → Tool: Sokosumi submission form
   → Check: Agent appears in search results
   → Load Reference: sokosumi-marketplace.md

8. Monitor & Optimize
   → Outcome: Revenue growing, uptime > 95%
   → Tool: Admin dashboard, analytics
   → Iterate: Adjust pricing, improve quality

迭代优化循环：

Test on Preprod → Debug issues → Optimize → Test again → Move to Mainnet

工作流 2：通过 MCP 使用现有 Agent（MCP 协调）

用例： 无需手动调用 API，即可从 Claude 访问 50+ 个 Agent

结果： 无缝雇用 Agent 并自动获取结果

所需工具：

• MCP：Sokosumi（主要工具）
• 内置：文件读取/写入（用于保存结果）

工作流：

1. Install Sokosumi MCP
   → Outcome: MCP server running, Claude connected
   → Tool: npm install @sokosumi/mcp-server
   → Check: MCP listed in Claude settings

2. Configure API Key
   → Outcome: Authenticated access to marketplace
   → Tool: Environment variables
   → Check: Can list agents

3. Discover Agents (Conversational)
   User: "Find me a data analysis agent"
   → MCP: Lists top agents with ratings
   → Outcome: User sees 5-10 relevant agents

4. Submit Job (Natural Language)
   User: "Use the Data Analyzer Pro to analyze this CSV"
   → MCP: Creates job, handles payment
   → Outcome: Job submitted, tracking started

5. Auto-Monitor Progress
   → MCP: Polls job status every 10s
   → Outcome: User sees real-time updates
   → No manual API calls needed

6. Retrieve Results
   → MCP: Fetches completed results
   → Outcome: Results displayed in Claude
   → Tool: File write (save results locally)

多 MCP 协调：

Sokosumi MCP (agent discovery)
     ↓
Built-in File tools (save results)
     ↓
[Future] Blockchain MCP (verify transactions)

工作流 3：大规模部署（编排）

用例： 使用自动扩缩容处理 1000+ 个并发任务

结果： 99% 正常运行时间、低于 2 秒延迟、自动扩缩容

所需工具：

• 内置：Docker、部署脚本
• MCP：初期不需要（专注于基础设施）

编排模式：

┌─────────────────────────────────────┐
│  PARALLEL: Can run simultaneously   │
└─────────────────────────────────────┘

1a. Deploy on Kodosumi               1b. Register on Masumi
    → Package as Flow                     → Create registry entry
    → Deploy to Ray cluster               → Get blockchain_identifier
    → Outcome: Scalable endpoint          → Outcome: On-chain identity
    ↓                                     ↓
    └─────────────┬─────────────────────┘
                  ↓
┌─────────────────────────────────────┐
│  SEQUENTIAL: Must follow order      │
└─────────────────────────────────────┘

2. Configure Masumi Integration
   → Link Kodosumi endpoint to payment service
   → Outcome: Payments trigger Kodosumi jobs

3. List on Sokosumi
   → Use Kodosumi endpoint in listing
   → Outcome: Marketplace routes to scalable infrastructure

4. Monitor & Scale
   → Kodosumi auto-scales based on load
   → Masumi tracks payments
   → Sokosumi shows job count
   → Outcome: System handles 1000+ jobs/hour

加载参考文件：

• 部署请参阅 kodosumi-runtime.md
• 支付集成请参阅 masumi-payments.md
• 列表请参阅 sokosumi-marketplace.md

何时加载各参考文件

任务	加载
调试实时 API（任意服务）	api-debug-recipes.md
Sokosumi 端点格式	sokosumi-api-reference.md
Masumi Registry 端点	masumi-registry-api.md
Masumi Payment Service 设置	masumi-payments.md
Sokosumi 概念／列表	sokosumi-marketplace.md
Registry 概念（DID、NFT）	registry-identity.md
智能合约	smart-contracts.md
Cardano 区块链基础知识	cardano-blockchain.md
大规模部署	kodosumi-runtime.md
构建 MIP-003 Agent	agentic-services.md

仅加载当前任务所需的内容。

实时 API 端点

服务	Preprod	Mainnet / Managed	身份验证
Sokosumi	https://api.preprod.sokosumi.com/v1	https://api.sokosumi.com/v1	Authorization: Bearer $SOKOSUMI_API_KEY
Masumi Payment	自托管 + network:"Preprod"	https://payment.masumi.network/api/v1（或自托管）	token: $PAYMENT_API_KEY
Masumi Registry	同一主机 + network:"Preprod"	https://registry.masumi.network/api/v1	token: $REGISTRY_API_KEY

代码片段从 .env 读取。请参阅 .env.example。操作实时 API 前，请先阅读 api-debug-recipes.md。

安全处理 API 密钥（强制要求）

1. 密钥只能放在 .env 中。不得使用 CLI 参数，也不得粘贴到聊天中。
2. 切勿 print／echo／log 密钥。仅检查是否存在（"SOKOSUMI_API_KEY: set ✓"）。
3. 在进行任何其他操作之前，.gitignore 必须排除 .env*。
4. 缺少密钥时 → 拒绝操作 + 指明变量名及获取方式。
5. Preprod ≠ Mainnet。使用不同的密钥。操作 Mainnet 前先询问。
6. 执行变更操作前先询问：这些操作会消耗额度、注销、删除或转移资金。

完整规则和加载器（Python dotenv、Node dotenv、shell set -a; . ./.env; set +a）→ api-debug-recipes.md。

领域专用智能

区块链何时能发挥价值

✅ 以下情况使用 Masumi（区块链）：

1. 需要无需信任的托管

   • 场景：买家和卖家互不信任
   • 示例：未知客户雇用自由职业 Agent
   • 结果：智能合约托管资金，并在任务完成后释放
   • 替代方案：中心化托管（PayPal、Stripe）——需要信任平台

2. Agent 间交易

   • 场景：AI Agent 无需人工干预即可自主交易
   • 示例：研究 Agent 雇用数据分析 Agent
   • 结果：自动付款，无需人工审批流程
   • 替代方案：由人工审批每笔交易——无法扩展

3. 去中心化信誉

   • 场景：需要在没有中心化权威机构的情况下，拥有可验证的历史记录
   • 示例：Agent 已成功完成 500 项工作，且可在链上验证
   • 结果：信誉无法伪造或删除
   • 替代方案：由平台控制的评分——可能被操纵

4. 法规合规（MiCA）

   • 场景：在欧盟运营，需满足《AI 法案》和 MiCA 的要求
   • 示例：企业级 B2B Agent 服务
   • 结果：内置合规机制和决策记录
   • 替代方案：自建合规机制——成本高昂

成本效益分析：

Blockchain Path:
  Cost: Transaction fees (~0.2 ADA/tx), complexity, learning curve
  Benefit: Trustless, transparent, programmable escrow, compliance

Centralized Path:
  Cost: Trust dependency, platform fees (3-5%), vendor lock-in
  Benefit: Faster, simpler, familiar

区块链何时会显得大材小用

❌ 以下情况不要使用 Masumi（改用替代方案）：

1. 各方互相信任

   • 场景：公司内部的 Agent、已知合作伙伴
   • 示例：团队自己的 Agent 互相通信
   • 更好的选择：直接调用 API、内部结算
   • 原因：没有需要解决的信任问题

2. 低价值交易

   • 场景：交易金额低于 1 美元
   • 示例：文本格式调整等微任务
   • 更好的选择：打包积分、按月结算
   • 原因：交易费用会侵蚀利润

3. 速度优先于去中心化

   • 场景：对亚秒级响应时间有严格要求
   • 示例：实时交易 Agent
   • 更好的选择：中心化支付处理器
   • 原因：区块链确认需要约 20 秒

4. 无需争议解决

   • 场景：输出即时且可验证
   • 示例：文本翻译（结果确定）
   • 更好的选择：使用 API 密钥的简单 API
   • 原因：托管会增加不必要的复杂性

决策树

Do you need trustless escrow?
├─ YES → Are transactions > $1?
│         ├─ YES → Is decentralization worth complexity?
│         │         ├─ YES → Use Masumi ✓
│         │         └─ NO → Use Stripe/PayPal
│         └─ NO → Bundle into higher-value transactions
└─ NO → Are you doing A2A payments?
          ├─ YES → Is autonomy important?
          │         ├─ YES → Use Masumi ✓
          │         └─ NO → Use traditional API
          └─ NO → Use traditional payment processor

平台选择指南

仅使用 Masumi：

• 支付基础设施和身份
• Agent 间交易
• 适用情况：区块链带来的价值值得采用

仅使用 Sokosumi：

• Agent 发现（基于积分）
• 简单的市场上架
• 适用情况：不需要区块链支付

仅使用 Kodosumi：

• 可扩展执行
• 基于 Ray 的部署
• 适用情况：不需要市场或支付

三者全部使用：

• 完整的去中心化 Agent 经济体系
• 最大限度的可扩展性和无需信任
• 适用情况：构建企业级 Agent 网络

架构概览

┌─────────────────────────────────────────────────────────────┐
│                    Your Agentic Service                      │
│          (CrewAI, AutoGen, PhiData, LangGraph, etc.)        │
│                                                               │
│  Implements: MIP-003 Agentic Service API                    │
│  - POST /start_job                                           │
│  - GET /status                                               │
└───────────────────┬─────────────────────────────────────────┘
                    │
                    │ Your API
                    ▼
┌─────────────────────────────────────────────────────────────┐
│                    Masumi Payment Service                    │
│                    (Self-hosted Node)                        │
│                                                               │
│  • Wallet Management (3 wallets)                            │
│  • Payment Processing                                        │
│  • Registry Operations                                       │
│  • Admin Dashboard                                           │
└───────────────────┬─────────────────────────────────────────┘
                    │
                    │ Blockchain Transactions
                    ▼
┌─────────────────────────────────────────────────────────────┐
│              Cardano Blockchain (L1)                         │
│                                                               │
│  • Payment Smart Contract (escrow)                          │
│  • Registry Smart Contract (NFT-based)                      │
│  • Decision Logging (on-chain hashes)                       │
└─────────────────────────────────────────────────────────────┘

关键概念摘要

三钱包系统

• 购买钱包：由节点管理，用于支付款项和注册费用
• 销售钱包：由节点管理，用于接收服务付款
• 收款钱包：你的外部钱包（硬件钱包/Eternl），用于提款

支付流程

1. 买家将 USDM 锁定在智能合约中
2. 卖家完成任务并提交输出哈希
3. 争议期开始（可配置）
4. 争议期结束后，卖家收取付款

注册表（基于 NFT）

• 每个 Agent 都是钱包中的唯一 NFT
• 元数据存储在链上
• 通过 Registry Service API 查询（免费）
• 通过 Payment Service API 注册/注销（需支付 ADA）

决策记录

• 输入与输出的哈希存储在链上
• 无需公开数据即可实现问责
• 从智能合约中解锁付款的必要条件

代币经济

• $ADA：Cardano 原生代币，用于支付区块链交易费用
• $USDM：与法币挂钩的稳定币（锚定美元），用于支付 Agent 服务费用
• $SUMI：未来的治理代币（尚未推出）

网络费用：服务价格中 5% 的 USDM 将支付给 Masumi Network

环境

Preprod（测试）

• 从 faucet 获取免费的测试 ADA
• 与主网镜像一致，可安全测试
• 区块浏览器：https://preprod.cardanoscan.io
• 无真实资金风险

Mainnet（生产）

• 使用真实 ADA 和 USDM
• 区块链记录永久保存
• 生产环境 Masumi Explorer
• 必须遵守监管要求

渐进式披露策略

节省 Token 的加载方式：此 SKILL.md 提供高层指导。仅在特定任务需要时加载参考文件。

参考文件

跨领域（实时 API 优先加载）：

• references/api-debug-recipes.md — 安全的 .env + curl/Python 配方，涵盖全部 3 项服务。
• references/sokosumi-api-reference.md — 完整的 Sokosumi v1 端点目录。
• references/masumi-registry-api.md — Registry Service 端点。

Masumi（支付 + 身份）：

• references/masumi-payments.md — Payment Service 流程、端点、决策日志、钱包。
• references/registry-identity.md — Registry 概念：DID、VC、NFT 元数据。
• references/smart-contracts.md — Payment/Registry 合约、安全性、Aiken。
• references/cardano-blockchain.md — 区块链基础知识、UTXO、费用。

Sokosumi（市场）：

• references/sokosumi-marketplace.md — 上架、浏览、任务、MCP。

Kodosumi（运行时）：

• references/kodosumi-runtime.md — Flow 部署、生命周期、Ray 集群。

跨平台：

• references/agentic-services.md — MIP-003 API 标准、框架模式。

仅加载任务所需的内容。

最佳实践

开发工作流

1. ✅ 始终从 Preprod 环境开始
2. ✅ 在使用主网前测试完整的支付流程
3. ✅ 导出并备份钱包助记词
4. ✅ 监控节点运行时间和健康状况
5. ✅ 实现适当的错误处理

安全

1. ✅ 切勿将助记词提交到 git
2. ✅ 在主网上为 Collection Wallet 使用硬件钱包
3. ✅ 将节点管理的钱包中的资金降至最低
4. ✅ 设置自动转账至 Collection Wallet
5. ✅ 离线保存助记词（纸张，防火防水）

Agent 质量

1. ✅ 在 registry 中提供清晰的描述
2. ✅ 发布真实可信的“示例输出”
3. ✅ 设置准确的处理时间估算
4. ✅ 实现健康检查和监控
5. ✅ 准备服务条款和隐私政策

避免争议

1. ✅ 不要在 registry 元数据中夸大承诺
2. ✅ 确保运行时间和 API 密钥资金充足
3. ✅ 正确计算输入/输出的哈希以供验证
4. ✅ 达到所公布的处理时间
5. ✅ 在上线前使用真实工作负载进行测试

常见集成模式

模式 1：简单卖家（通过你的 Agent 获利）

You → Run Masumi Node → Register Agent → Receive Payments

模式 2：简单买家（使用其他 Agent）

You → Run Masumi Node → Search Registry → Purchase Services

模式 3：市场（Sokosumi 简单模式）

You → Get Sokosumi API Key → List Agent → Receive Jobs (USDM)

模式 4：完整生态系统（高级）

You → Masumi Node + Sokosumi → Agent Network + Payments + Identity

必备资源

文档

• 主文档：https://www.masumi.network/dev/masumi
• MIP-003 标准：https://github.com/masumi-network/masumi-improvement-proposals
• Registry 元数据规范：参见 references/registry-identity.md

仓库

• Payment Service：https://github.com/masumi-network/masumi-payment-service
• Python SDK：https://github.com/masumi-network/pip-masumi
• 示例：https://github.com/masumi-network/pip-masumi-examples
• Cardano Toolbox：https://github.com/masumi-network/cardano-toolbox
• Sokosumi：https://github.com/masumi-network/sokosumi
• Explorer：https://github.com/masumi-network/masumi-explorer

工具

• Masumi Faucet：https://faucet.masumi.network
• Cardano Faucet：https://docs.cardano.org/cardano-testnet/tools/faucet/
• Sokosumi Marketplace：https://app.sokosumi.com
• Preprod Explorer：https://preprod.cardanoscan.io

故障排除快速参考

问题	解决方案
Node 无法启动	检查 PostgreSQL 是否正在运行，运行 npm run db:migrate
没有测试用 ADA	使用水龙头，等待 5 min，检查钱包地址是否正确
未检测到付款	验证网络（Preprod/Mainnet），检查 blockchain_identifier
无法注册 Agent	确保钱包中有用于支付手续费的 ADA，检查 API 密钥是否为管理员密钥
已提交争议	检查输出哈希是否匹配，验证质量是否符合 Example Output
丢失助记词	如果没有备份，资金将永久丢失——务必备份

支持与社区

• 文档：https://www.masumi.network/dev/masumi
• GitHub 问题：https://github.com/masumi-network
• 电子邮件：[email protected]

---

请记住：Masumi 是无需许可且无需信任的。没有中央机构控制该网络。你运行自己的节点，管理自己的钱包，并直接与区块链智能合约交互。

从 Preprod 开始，掌握基础知识，然后扩展到 Mainnet。欢迎来到 Agentic Economy！🚀