AgentsBank SDK 技能定义

版本: 1.0.6
发布者: AgentsBank
联系方式: info@agentsbank.online
状态: 🟢 公开版本 - 生产就绪

🎯 目的与能力

本技能通过官方的 AgentsBank SDK，为 AI 智能体提供安全、受控的加密银行操作。它使智能体能够在明确的用户控制下管理钱包、查询余额和执行交易。

✅ 能力（只读 & 安全）

• ✓ 获取智能体在所有支持链（以太坊、BSC、Solana、比特币）上的钱包余额
• ✓ 检索带过滤和分页的交易历史记录
• ✓ 查询钱包详情、元数据和账户信息
• ✓ 为身份验证和验证签署消息（不涉及资金转移）
• ✓ 在执行交易前预估 Gas 费用
• ✓ 支持分页列出所有钱包

⚠️ 能力（写入/金融 - 需要用户显式调用）

• ⚠️ 发送加密资产交易（仅当用户显式覆盖 disableModelInvocation: false 时）
• ⚠️ 创建新钱包（仅当用户显式覆盖 disableModelInvocation: false 时）
• ⚠️ 自主注册智能体和人类用户

❌ 不包含（超出范围）

• 通过 OAuth2 委托访问外部钱包
• Webhooks 或事件订阅
• 智能合约部署
• 沙盒测试（请直接使用测试网链）
• 私钥导出或管理

🔐 凭证与环境变量

必需的环境变量

⚠️ 安全须知：
- AGENTSBANK_AGENT_PASSWORD 绝不可提交到版本控制系统
- 存储在 .env 文件中（并添加到 .gitignore）
- 每季度或在凭证泄露时轮换
- 在生产环境中使用密钥管理器（如 HashiCorp Vault、AWS Secrets Manager）

可选的环境变量

🚀 安装与设置

1. 安装 SDK

发布的 npm 包是轻量级的（约 6.8 KB），不包含 node_modules。安装时仅获取你所需的依赖：

npm install @agentsbankai/sdk
# 或
yarn add @agentsbankai/sdk
# 或
pnpm add @agentsbankai/sdk

这将：
- ✅ 下载编译后的 SDK（CJS + ESM 格式）
- ✅ 安装所需依赖（axios、ethers、@solana/web3.js 等）
- ✅ 无冗余：发布的包中不包含 node_modules

2. 初始化环境

在项目根目录创建 .env 文件：

AGENTSBANK_API_URL=https://api.agentsbank.online
AGENTSBANK_AGENT_USERNAME=agent_123456_abc
AGENTSBANK_AGENT_PASSWORD=your_secure_password_here

3. 创建客户端实例

import { AgentsBankSDK } from '@agentsbankai/sdk';

// 使用 API 凭证初始化 SDK
const bank = new AgentsBankSDK({
  apiUrl: process.env.AGENTSBANK_API_URL || 'https://api.agentsbank.online',
  timeout: parseInt(process.env.AGENTSBANK_TIMEOUT_MS || '30000')
});

// 使用智能体凭证进行身份验证
const { token, agent } = await bank.login({
  agentUsername: process.env.AGENTSBANK_AGENT_USERNAME!,
  agentPassword: process.env.AGENTSBANK_AGENT_PASSWORD!
});

console.log('✅ 身份验证成功，智能体 ID:', agent.agent_id);

4. 使用安全操作（始终允许）

// 获取钱包余额（安全，只读）
const balance = await bank.getBalance(walletId);
console.log('余额:', balance);

// 获取交易历史（安全，只读）
const history = await bank.getTransactionHistory(walletId, { 
  limit: 10,
  offset: 0 
});
console.log('最近交易:', history);

// 签署消息（安全，不转移资金）
const signature = await bank.signMessage(walletId, 'verify-ownership');
console.log('签名:', signature);

// 发送前预估 Gas 费用
const gasEstimate = await bank.estimateGas({
  walletId,
  toAddress: '0x...',
  amount: '1.5',
  chain: 'ethereum'
});
console.log('预估 Gas:', gasEstimate);

// 分页列出所有钱包
const wallets = await bank.listWallets({ limit: 20, offset: 0 });
console.log('智能体钱包:', wallets);

⚠️ 受限操作（需要用户明确批准）

以下操作不会自动执行，需要用户显式调用：

// ❌ 这需要用户显式调用
// (默认设置为 disableModelInvocation: true)
const tx = await bank.sendTransaction({
  walletId,
  toAddress: recipientAddress,
  amount: '1.5',
  chain: 'solana',
  token: 'SOL'
});

为何受限？
- 涉及资产转移的金融操作绝不能自主进行
- 执行前需要明确的用户批准
- 防止因模型幻觉导致的意外资金转移
- v1.0.6 版本为验证失败添加了全面的错误处理

错误处理 (v1.0.6)

SDK 提供类型化错误以便更好地调试：

import { AgentsBankSDK, SDKError } from '@agentsbankai/sdk';

try {
  const tx = await bank.sendTransaction({
    walletId,
    toAddress: '0xinvalid', // 无效地址
    amount: '100',
    chain: 'ethereum'
  });
} catch (error) {
  if (error instanceof SDKError) {
    console.error('SDK 错误:', error.code, error.message);
    // 错误代码: INVALID_ADDRESS, INSUFFICIENT_BALANCE, INVALID_CHAIN 等
  }
}

📋 元数据与配置

{
  "name": "@agentsbankai/sdk",
  "namespace": "agentsbank",
  "version": "1.0.6",
  "description": "为 AI 智能体提供的受控加密银行 SDK，具备明确的金融操作保护、全面的错误处理和多链支持",
  "author": "AgentsBank",
  "license": "MIT",
  "homepage": "https://agentsbank.online",
  "repository": "https://github.com/agentsbank/sdk",
  "docs": "https://docs.agentsbank.online/sdk",
  "primaryEnv": "AGENTSBANK_AGENT_PASSWORD",
  "requiredEnvs": [
    "AGENTSBANK_API_URL",
    "AGENTSBANK_AGENT_USERNAME",
    "AGENTSBANK_AGENT_PASSWORD"
  ],
  "optionalEnvs": [
    "AGENTSBANK_API_KEY",
    "AGENTSBANK_LOG_LEVEL",
    "AGENTSBANK_TIMEOUT_MS"
  ],
  "disableModelInvocation": true,
  "modelInvocationWarning": "金融操作必须由用户明确请求。自主交易执行已被禁用。",
  "enforcedScopes": [
    "read:balance",
    "read:history",
    "read:wallet",
    "read:estimate",
    "sign:message"
  ],
  "restrictedScopes": [
    "write:transaction",
    "write:wallet",
    "write:register"
  ],
  "features": {
    "multiChain": ["ethereum", "bsc", "solana", "bitcoin"],
    "errorHandling": "带有特定错误代码的类型化错误",
    "validation": "客户端参数验证",
    "pagination": "钱包和交易列表支持分页"
  },
  "installMechanism": "npm",
  "codeFiles": ["src/client.ts", "src/types.ts", "src/errors.ts", "src/index.ts"],
  "noExecutableScripts": true,
  "noDiskPersistence": true,
  "noModelAutonomy": true,
  "changelog": "https://github.com/agentsbank/sdk/blob/main/CHANGELOG.md"
}

🛡️ 安全边界

本技能可以做什么

✅ 读取钱包余额和历史记录
✅ 为身份验证签署消息
✅ 创建钱包（需用户明确请求）
✅ 检索账户元数据

本技能不能做什么

❌ 自主执行交易
❌ 导出私钥
❌ 访问外部服务凭证
❌ 将敏感数据持久化到磁盘
❌ 向未列出的端点发送请求

身份验证范围

• 读取范围: read:balance, read:history, read:wallet, sign:message
• 写入范围: write:transaction, write:wallet（仅限用户调用）
• 无委托: 智能体不能请求额外的范围

✅ 验证清单

使用本技能前，请确认：

• [ ] 你已从 https://agentsbank.online 获取有效的 AGENTSBANK_AGENT_USERNAME 和 AGENTSBANK_AGENT_PASSWORD
• [ ] 凭证已安全存储在 .env 文件中（从未提交）
• [ ] 你已阅读 安全架构
• [ ] 你理解 disableModelInvocation: true 会阻止自主交易
• [ ] 在启用写入操作前，你已首先测试了读取操作
• [ ] 你在 admin.agentsbank.online 监控活动日志

📖 文档与支持

⚖️ 免责声明

本技能与真实的加密货币网络（以太坊、Solana、比特币、BSC）集成。交易不可逆转。

• AgentsBank 不对因地址错误或用户失误造成的资金损失负责
• 始终先使用小额进行测试
• 开发时请使用测试网链
• 在你的 AgentsBank 账户上启用双因素认证 (2FA)

最后更新: 2026年2月11日 (v1.0.6 版本发布)
状态: 🟢 公开版本 - 生产就绪 ✅
npm 包: https://www.npmjs.com/package/@agentsbankai/sdk
GitHub: https://github.com/agentsbank/sdk
v1.0.6 版本变更: 全面的错误处理、增强的类型定义、改进的客户端实现