内容
# 智能钱包（区块链技能）
一套工具包，允许任何AI代理直接在区块链上操作钱包：创建钱包、接收、发送、交换、跨链桥接、签名、部署和验证Solidity合约，并学习已部署合约的工作原理。密钥在本地机器上生成和存储（加密的keystore v3），交易直接发送到公共RPC端点。无需MetaMask，无需交易所，无需托管。
该工具包提供了三种接口：一个CLI（`agent-wallet <verb>`）、一个MCP服务器（stdio）和Claude代码技能。相同的动词，相同的JSON信封在所有接口中通用。
## 安装
- CLI：`npx agent-wallet help`
- 技能：`npx skills add hec-ovi/blockchain-skill`
- 插件：`/plugin marketplace add hec-ovi/blockchain-skill`
- MCP：在`.mcp.json`中注册服务器（`node bin/agent-wallet.ts mcp`）
需要Node >= 22.18（直接运行TypeScript）。将密钥放在.gitignore的`.env`中（参见`.env.example`）；CLI和MCP服务器会自动加载它。至少设置`AGENT_WALLET_PASSPHRASE`（加密keystore）。
## 功能
| 领域 | 动词 | 网络 |
|---|---|---|
| 钱包 | wallet-create, wallet-import, wallet-list, wallet-addresses | EVM + Bitcoin |
| 读取 | balance, utxos, fees, tx | EVM + Bitcoin |
| 发送 | send (native, ERC-20, BTC, sweep) | EVM + Bitcoin |
| 交换 | swap-quote, swap (CoW, Kyber, Uniswap) | EVM |
| 跨链桥接 | bridge-quote, bridge, bridge-status (LI.FI) | EVM to EVM |
| 合约 | contract-compile, contract-deploy, contract-call, contract-write, contract-learn | EVM |
| 资助 | faucet (自助测试网燃料) | Base Sepolia, Ethereum Sepolia |
每个默认后端都是无密钥的。可选密钥（Etherscan, LI.FI）仅提高限制。
## 资助（自助燃料）
代理可以使用`faucet`动词无头加载自己的测试网燃料，无需验证码或浏览器：
```
agent-wallet faucet --network base-sepolia --token eth
```
它使用Coinbase CDP faucet，需要在`.env`或`~/.agent-wallet/config.json`中设置免费的API密钥（`CDP_API_KEY_ID`，`CDP_API_KEY_SECRET`）。在portal.cdp.coinbase.com上获取。支持Base Sepolia和Ethereum Sepolia，支持eth、usdc、eurc和cbbtc。比特币测试网仍需要人类参与，因此使用EVM测试网进行自动资助。
## 安全
在`~/.agent-wallet/config.json`中允许主网（`{"gate":{"allowMainnet":true}}`或每个链的允许列表，以及可选的每个交易上限）。每个状态更改操作在签名之前都会经过一个确定性的门控。读取操作永远不会被门控。
## 验证内容
该工具包在三个级别进行了验证：自动化套件、针对真实公共网络的实时调用，以及由单独的AI代理驱动的完整运行，作为首次使用者的模拟。
**自动化套件。** `npm test`运行95个测试，无需外部网络：每个层的模式和合约测试，密钥派生检查与官方BIP-86和BIP-84向量，比特币币选择，信封验证，以及真实CLI和MCP服务器的端到端运行。
**实时公共网络检查** （使用`RUN_LIVE=1`选择加入）：在Ethereum Sepolia和Bitcoin signet上读取余额和区块头，无密钥Sourcify ABI获取WETH，以及来自CoW、KyberSwap和LI.FI的实时交换和桥接报价。
**代理驱动，端到端。** 一个单独的模型（Claude Haiku），仅给定技能和CLI，被要求用自然语言创建一个钱包，传递一个地址，检查余额，并发送资金。它产生的每个命令都是正确且格式良好的，发送的资金到达了链上，安全门控拒绝了主网发送，原因明确。出现了一个歧义（它在没有指定网络时假设了一个网络），因此技能现在告诉代理询问。
**在Base Sepolia（真实，可点击）。** 在一次运行中，代理资助了一个新的钱包，发送了一个转账，部署了`Counter`合约，并调用了`increment()`（计数从41增加到42，通过直接链调用确认）。它首先通过CDP faucet资助自己，无需人类干预：
- 钱包：https://sepolia.basescan.org/address/0xE5f6d3E30259EC65CB373de402647DA3D6Bd7E84
- Faucet资助：https://sepolia.basescan.org/tx/0x34adadc142150cbd51bf5c8f44766c5fcd0cc7ae4aeb53ec52247a6af25f6ff5
- 转账：https://sepolia.basescan.org/tx/0x1e1a51bea96eb6e8b727a0dfcc4a978b2b6ad236ac199f2224d4b48992ad7f97
- 合约：https://sepolia.basescan.org/address/0xbeaf85138e51c30fe3511f78e7bf868356ec7373
- 部署交易：https://sepolia.basescan.org/tx/0x924108df1061ddd917e0785127512a67027d69f3af326c5952488bcce54d5d10
- increment(): https://sepolia.basescan.org/tx/0xd5e42c9da194487ba261cb6c481cda6a19b7a18c42105a87007c7496ba7236ec
## 架构
在`layers/`下隔离合约层，通过一个JSON信封耦合。每个层拥有自己的`CONTRACT.md`、`schema/`、`src/`和`tests/`。`docs/INDEX.md`映射了您想要更改的内容到要打开的文件夹。参见`docs/ARCHITECTURE.md`和`docs/RESEARCH.md`了解设计和2026年堆栈选择。
层顺序，从易到难：核心、密钥、链、读取、签名、门控、发送、学习、合约、交换、桥接、资助、agentio（CLI + MCP表面）。
