MetaMask Agent Wallet 技能

控制一个沙箱化的 MetaMask 钱包，以实现自主区块链交易，并支持可配置的权限防护机制。

概述

该技能允许 AI 代理通过专用 MetaMask 钱包与 dapp 交互并执行交易。所有操作均受用户定义的约束限制（如支出限额、协议白名单、审批阈值等）。

安全模型： 代理在隔离的浏览器配置文件中控制一个独立的钱包。请勿使用您的主钱包。

设置

1. 安装依赖项

cd metamask-agent-skill
npm install
npx playwright install chromium

2. 创建代理钱包配置文件

npm run setup

该命令将执行以下操作：

• 在 ~/.agent-wallet/chrome-profile 创建全新的 Chrome 配置文件
• 安装 MetaMask 扩展程序
• 引导您完成钱包创建流程（请使用一个全新的助记词）

3. 为钱包充值

向您的代理钱包转入少量资产：

• ETH（用于支付 Gas 费，建议 0.01–0.05 ETH）
• 代币（用于执行操作，建议从小额开始，例如 $50 USDC）

4. 配置权限

编辑 permissions.json 文件以设定您的约束条件：

{
  "constraints": {
    "spendLimit": {
      "daily": "50000000",    // $50，采用六位小数格式
      "perTx": "10000000"     // 单笔交易最高 $10
    },
    "allowedChains": [1, 137, 42161],
    "allowedProtocols": ["0x...uniswap", "0x...1inch"]
  }
}

可用操作

连接至 Dapp

connect 

导航至指定 dapp 并连接代理钱包。

示例： connect https://app.uniswap.org

执行兑换（Swap）

swap   for  [on ]

在允许的 DEX 上执行代币兑换。

示例： swap 0.01 ETH for USDC on uniswap

发送代币

send   to 

向指定地址发送代币（须在支出限额范围内）。

示例： send 10 USDC to 0x1234...

签名消息

sign 

对任意消息进行签名。请谨慎使用。

查询余额

balance [token]

返回钱包余额信息。

查看交易历史

history [count]

显示最近的代理交易及其结果。

约束条件

所有操作在执行前均会校验 permissions.json 中的配置：

审批流程

当某笔交易超出 requireApproval.above 设定的阈值时：

1. 代理暂停执行
2. 交易详情被记录到日志中
3. 代理报告：“Transaction requires approval: [details]”（该交易需人工审批：[详情]）
4. 用户必须明确批准后，代理方可继续执行

安全性

• 隔离配置文件： 代理使用独立的 Chrome 配置文件，绝不会影响您的主浏览器
• 独立钱包： 代理钱包与您的主钱包完全隔离
• 支出上限： 硬性限额可防止意外超额支出
• 协议白名单： 仅允许调用白名单中的合约
• 完整日志记录： 每一笔交易意图及最终结果均被记录
• 权限撤销： 在 permissions.json 中设置 "revoked": true 可禁用全部操作

日志记录

所有交易均记录至 ~/.agent-wallet/logs/ 目录下：

{
  "timestamp": 1706900000000,
  "action": "swap",
  "intent": { "to": "0x...", "value": "0", "data": "0x..." },
  "guardResult": { "allowed": true },
  "outcome": "confirmed",
  "txHash": "0x..."
}

可使用 history 命令查看近期交易。

故障排查

“Protocol not allowed”（协议未被允许）

请将对应合约地址添加至 permissions.json 中的 allowedProtocols 字段。

“Exceeds daily limit”（超出日限额）

请等待 24 小时，或提高 spendLimit.daily 的数值。

未检测到 MetaMask 弹窗

请确认浏览器配置文件路径正确，且 MetaMask 已成功安装。

交易模拟失败

dapp 可能尝试调用了被阻止的方法，或目标链不受支持。

架构

src/
├── index.ts          # 主入口文件
├── browser.ts        # Playwright 浏览器管理模块
├── wallet.ts         # MetaMask 交互基础能力
├── guard.ts          # 权限强制执行逻辑
├── logger.ts         # 交易日志记录模块
├── price.ts          # USD 价格估算模块
├── types.ts          # TypeScript 类型定义
└── config.ts         # 配置加载模块

与 Gator 的集成

当 Gator 账户功能上线后，permissions.json 可替换为链上权限证明（on-chain permission attestations）。此时权限守卫（guard）将依据 Gator 的权限注册表（permission registry）进行校验，而非本地配置文件。