AI Agent与区块链交互：aelf钱包技能包架构设计与实战指南-平芜编程栈

1. 项目概述：为AI Agent赋能的aelf区块链钱包技能包

如果你正在开发一个需要与aelf区块链交互的AI Agent，或者你希望让Claude、Cursor这类AI工具能帮你管理数字资产、查询链上数据，那么你很可能需要一套标准化的“技能”。@portkey/eoa-agent-skills正是为此而生。它是一个专为Portkey EOA钱包设计的AI Agent技能库，提供了MCP、CLI和SDK三种标准接口，让AI能够安全、便捷地执行钱包创建、资产查询、代币转账、合约调用等一系列链上操作。

简单来说，这个项目把复杂的区块链交互封装成了AI能直接理解和调用的“工具”。开发者无需从零开始编写与aelf节点通信、处理交易签名、解析合约ABI的底层代码，直接引入这个技能包，你的AI助手就立刻获得了管理aelf链上资产的能力。这对于构建自动化交易机器人、链上数据分析助手、或是用户友好的资产管理AI界面来说，是一个强大的基础设施。

2. 核心架构与设计思路拆解

2.1 为什么选择“技能包”模式？

在AI Agent领域，一个核心挑战是如何让大语言模型（LLM）安全、可靠地执行外部操作。直接让模型生成并执行任意代码是危险且不可控的。@portkey/eoa-agent-skills采用了“技能”或“工具”模式，其设计哲学可以概括为“定义边界，提供接口”。

定义边界：所有可能的链上操作被预先定义为一组有限的、经过严格测试的“技能”（如portkey_transfer,portkey_call_view_method）。AI Agent只能调用这些明确定义的技能，而不能执行范围之外的任意操作，这极大地提升了安全性。
提供接口：每个技能都有清晰的输入参数、输出格式和错误处理。对于MCP模式，这符合Model Context Protocol标准；对于CLI，它是一组命令行参数；对于SDK，它是一系列TypeScript函数。这种一致性使得技能可以在不同运行时（如Claude Desktop、自定义Node.js后端、终端脚本）中无缝切换。

这种设计将区块链交互的复杂性从AI的“推理逻辑”中剥离出来，AI只需要学会“在什么情况下调用哪个技能并传递什么参数”，而具体的加密签名、RPC调用、交易构造等细节则由技能包可靠地处理。

2.2 三层适配器与统一核心：杜绝逻辑重复

项目的架构清晰地体现了“关注点分离”的原则。从README中我们可以看到其核心目录结构：

index.ts (SDK) ─┐ server.ts (MCP) ─┼─> src/core/ ──> lib/ portkey_eoa_skill.ts (CLI) ─┘ (纯业务逻辑) (基础设施)

src/core/：这是项目的心脏。所有与aelf区块链交互的核心业务逻辑都集中在这里，例如：如何生成一个钱包密钥对、如何构造一笔转账交易、如何查询某个地址的Token余额。这些函数是“纯净”的，它们只关心业务逻辑，不关心自己被谁调用。
适配器层（MCP, CLI, SDK）：这三个入口文件是核心逻辑的三种不同“外壳”。
- server.ts将核心功能包装成符合MCP标准的工具，供Claude等AI工具调用。
- portkey_eoa_skill.ts将核心功能映射为命令行参数，方便在终端或脚本中使用。
- index.ts将核心功能导出为干净的JavaScript/TypeScript API，供开发者直接集成到自己的应用或Agent框架（如LangChain）中。

这种架构的最大优势是维护性。当你需要修复一个转账逻辑的bug时，你只需要修改src/core/里的一个函数，MCP、CLI、SDK三种使用方式都会自动获得修复，彻底避免了同一段逻辑在三个地方重复编写可能带来的不一致性。

2.3 钱包安全与状态管理设计

处理私钥是区块链应用中最敏感的部分。该项目采用了分层的安全策略：

本地加密存储：通过PORTKEY_WALLET_PASSWORD环境变量设置的密码，对钱包的私钥进行AES加密后存储在本地文件系统（默认在~/.portkey/eoa/wallets/）。这确保了私钥不会以明文形式持久化。
运行时隔离：私钥仅在执行需要签名的操作（如转账）时，在内存中被短暂解密使用，操作完成后立即从内存中清除。
跨技能签名上下文：这是一个非常实用的设计。当用户通过portkey_create_wallet创建一个钱包后，该钱包的地址信息（不包含私钥！）会被写入一个共享的上下文文件（~/.portkey/skill-wallet/context.v1.json）。这样，其他需要知道“当前活跃钱包是哪个”的技能（可能来自不同项目）可以读取这个文件，而执行签名时，则通过“显式提供私钥 -> 读取上下文找到钱包地址再结合环境变量密码解密 -> 直接使用环境变量私钥”的优先级来获取签名权限。这既方便了多技能协作，又保证了私钥不出安全边界。

3. 三种消费模式详解与选型指南

3.1 MCP模式：与AI工具深度集成

MCP是当前让AI安全使用外部工具最热门的协议。@portkey/eoa-agent-skills的MCP服务器让Claude Desktop、Cursor等工具能直接“拥有”区块链能力。

配置与激活：配置MCP服务器通常需要编辑AI客户端的配置文件。以Claude Desktop为例，你需要在其配置目录（如~/Library/Application Support/Claude/claude_desktop_config.json）中添加如下片段：

{ "mcpServers": { "portkey-eoa-agent-skills": { "command": "bun", "args": ["run", "/ABSOLUTE/PATH/TO/eoa-agent-skills/src/mcp/server.ts"], "env": { "PORTKEY_NETWORK": "mainnet", "PORTKEY_WALLET_PASSWORD": "你的加密密码" } } } }

配置完成后，重启Claude Desktop，你就可以在对话中直接要求AI：“用我的aelf钱包查一下ELF余额”，或者“向这个地址转0.1个ELF”。AI会自动识别可用的portkey_get_token_balance或portkey_transfer工具，并引导你提供必要的参数（如地址、金额），最终执行操作。

实操心得：在配置args路径时，务必使用绝对路径。相对路径在MCP服务器启动时可能会因工作目录不同而导致找不到模块。另外，PORTKEY_WALLET_PASSWORD是加密本地钱包文件用的，如果只是查询操作，可以不设置，但转账等写操作就必须有了。

3.2 CLI模式：自动化脚本与快速测试利器

CLI模式非常适合编写自动化脚本或进行快速的功能测试。所有功能都通过一个统一的入口脚本portkey_eoa_skill.ts来调用。

典型使用场景：

批量操作：你需要给100个空投地址分发代币。可以写一个Shell脚本，循环读取地址列表，并调用bun run portkey_eoa_skill.ts transfer ...。
监控警报：结合Cron任务，定期运行bun run portkey_eoa_skill.ts query balance ...，当余额低于某个阈值时发送通知。
CI/CD流程：在部署智能合约后，自动运行CLI命令调用一个视图方法来验证合约状态。

命令结构解析：CLI采用了“资源-操作”的结构，非常清晰。

bun run portkey_eoa_skill.ts <资源> <操作> [选项]

例如：

wallet create：创建钱包资源。
query balance：对“查询”资源执行“余额”操作。
contract send：对“合约”资源执行“发送”（写）操作。

一个复杂的合约调用示例：假设你要调用一个共振合约的JoinPairQueue方法，这是一个需要支付Gas的写操作。

bun run portkey_eoa_skill.ts contract send \ --contract-address 28Lot71VrWm1WxrEjuDqaepywi7gYyZwHysUcztjkHGFsPPrZy \ --method JoinPairQueue \ --params '{}' \ # 该方法无需参数，但需传递空对象 --chain-id tDVV \ # 侧链ID --address YOUR_AELF_ADDRESS \ # 调用者地址 --password YOUR_WALLET_PASSWORD # 解密私钥进行签名

注意事项：--params参数要求是JSON字符串。对于空参数，必须传递'{}'，而不是留空。留空会导致解析错误。对于字符串类型的参数，需要额外转义，如'"your_string_value"'（外层单引号是Shell引用，内层双引号是JSON字符串标识）。

3.3 SDK模式：自定义AI Agent与后端服务的基石

对于想要深度定制或将功能嵌入自己Node.js/TypeScript应用的开发者，SDK模式提供了最大的灵活性。你可以在LangChain Agent、LlamaIndex的Tool中直接导入这些函数。

基础集成示例：

import { getConfig, getTokenList, transfer } from '@portkey/eoa-agent-skills'; import { ChatOpenAI } from "@langchain/openai"; import { DynamicStructuredTool } from "@langchain/core/tools"; // 1. 初始化配置 const config = getConfig('testnet'); // 使用测试网 // 2. 将技能包装成LangChain Tool const tools = [ new DynamicStructuredTool({ name: "get_aelf_token_balance", description: "获取指定aelf地址的代币余额列表", schema: z.object({ address: z.string().describe("要查询的aelf区块链地址") }), func: async ({ address }) => { const result = await getTokenList(config, { address }); return JSON.stringify(result.data, null, 2); }, }), new DynamicStructuredTool({ name: "transfer_aelf_token", description: "在aelf链上进行代币转账", schema: z.object({ privateKey: z.string().describe("发送者钱包的私钥（确保在安全环境中）"), to: z.string().describe("接收者地址"), symbol: z.string().describe("代币符号，如ELF"), amount: z.string().describe("转账金额（以最小单位表示，例如1 ELF = 100000000）"), chainId: z.string().describe("链ID，如AELF代表主链") }), func: async ({ privateKey, to, symbol, amount, chainId }) => { const result = await transfer(config, { privateKey, to, symbol, amount, chainId }); return `转账成功！交易ID: ${result.transactionId}`; }, }) ]; // 3. 创建Agent并运行 const model = new ChatOpenAI({}); const agent = await createReactAgent({ llm: model, tools }); const result = await agent.invoke({ input: "帮我查一下地址'2g...'有哪些代币，然后给地址'3x...'转0.5个ELF" }); console.log(result);

SDK模式的优势：

类型安全：项目使用TypeScript开发，提供了完整的类型定义，在编码时就能获得参数提示和错误检查。
组合自由：你可以自由组合多个技能调用，处理中间结果，实现复杂的业务流。
错误处理：SDK函数返回Promise，你可以使用try...catch进行精细的错误处理和重试逻辑。

4. 核心功能实操与避坑指南

4.1 钱包生命周期管理：从创建到备份

钱包管理是一切操作的起点。技能包提供了完整的生命周期支持。

创建钱包：

bun run portkey_eoa_skill.ts wallet create --password YourStrongPassword123

执行后会生成一个助记词（12或24个单词）和一个aelf地址。请立即、安全地备份助记词！这是恢复钱包的唯一方式。密码用于加密存储本地钱包文件，不会上传到任何服务器。

导入钱包：如果你已有助记词，可以导入：

bun run portkey_eoa_skill.ts wallet import --mnemonic "your twelve or twenty four words here" --password YourNewPassword

重要安全警告：切勿在共享环境、不安全的终端历史记录或日志中留下助记词或私钥。--password参数在脚本中最好通过环境变量或安全输入方式传递，避免在命令行中明文显示。

备份与恢复：portkey_backup_wallet工具提供了两种输出：

明文字段：包含address,mnemonic,privateKey。这仅用于一次性查看或导入到其他不支持加密备份的钱包。备份后应从任何不安全介质中删除。
加密的walletExport字段：这是一个经过加密的字符串，可以与密码一起，通过portkey_import_wallet工具安全地恢复整个钱包（包括本地加密存储的元数据）。这是推荐的、更安全的备份方式。

4.2 资产查询：获取链上数据全景

查询功能丰富且高效，是构建数据看板或监控系统的基础。

查询代币列表与余额：portkey_get_token_list是最高效的接口，它一次RPC调用就能返回指定地址在所有aelf链（主链、侧链）上的所有代币及其余额。这对于展示用户资产总览非常有用。

查询交易历史：portkey_get_transaction_history返回的是交易列表。要获取某笔交易的详细信息（如输入输出、日志、状态），需要使用portkey_get_transaction_detail并传入交易ID。

实操心得：aelf的链ID是一个重要概念。主链是AELF，不同的侧链有各自的ID（如tDVV,tDVW）。在进行任何链特定操作（查询余额、转账）时，都必须指定正确的chainId。你可以通过bun run portkey_eoa_skill.ts query chains命令获取所有可用链的信息。

4.3 代币转账与跨链操作

同链转账：使用portkey_transfer。关键参数是amount，它需要传入代币的最小单位。例如，ELF代币有8位小数，所以转账1个ELF，amount需要传入100000000。

aelf生态内跨链转账：使用portkey_cross_chain_transfer。这用于将资产从aelf主链转移到某个侧链，或者反之。这个过程涉及跨链桥合约，通常需要支付少量ELF作为跨链手续费，并且会有一定的确认时间（若干个主链区块）。

通过eBridge进行跨生态转账：这是更强大的功能，允许资产在aelf链和外部EVM链（如以太坊、BSC）之间转移。使用portkey_ebridge_transfer。在操作前，务必先用portkey_ebridge_info查询目标链的可用性、最小/最大转账金额、以及预估手续费。

避坑指南：跨链操作（无论是aelf内部还是通过eBridge）都不是即时到账的。务必在操作后保存好返回的交易ID，并使用区块链浏览器或查询工具跟踪状态。eBridge转账通常需要先在源链上授权并锁定资产，然后在目标链上领取，这是一个两步过程。

4.4 智能合约交互：视图调用与发送调用

这是与DeFi、NFT等去中心化应用交互的核心。技能包将其清晰地分为两类：

视图调用：使用portkey_call_view_method或CLI的contract view。用于读取合约状态，不消耗Gas，不需要签名。

方法识别：通常合约中Get开头的方法都是视图方法。
参数传递：params必须是JSON字符串，且其结构必须与合约方法的参数列表完全匹配。例如，调用GetBalance方法，它需要{“symbol”: “ELF”, “owner”: “address”}，那么params就应该是'{"symbol":"ELF","owner":"2g..."}'。

发送调用：使用portkey_call_send_method或CLI的contract send。用于修改合约状态，需要消耗Gas，必须由拥有私钥的地址签名。

典型场景：授权代币（Approve）、质押（Stake）、交易（Swap）。
费用估算：在发送交易前，强烈建议使用portkey_estimate_fee工具预估所需的Gas费用，避免因Gas不足导致交易失败。

一个常见的交互流程示例（参与共振）：

查询队列状态（视图调用）：确认当前是否可以加入。

bun run portkey_eoa_skill.ts contract view \ --contract-address [共振合约地址] \ --method GetPairQueueStatus \ --params '"你的地址"' \ --chain-id tDVV

估算费用：查看加入队列需要多少Gas。

bun run portkey_eoa_skill.ts contract estimate-fee \ --contract-address [共振合约地址] \ --method JoinPairQueue \ --params '{}' \ --chain-id tDVV \ --address 你的地址

执行加入（发送调用）：

bun run portkey_eoa_skill.ts contract send \ --contract-address [共振合约地址] \ --method JoinPairQueue \ --params '{}' \ --chain-id tDVV \ --address 你的地址 \ --password 你的钱包密码

5. 环境配置、依赖管理与进阶部署

5.1 环境变量详解

项目通过环境变量来管理配置，提供了灵活性和安全性。.env.example文件是模板。

变量名	作用与建议	默认值
`PORTKEY_NETWORK`	指定连接的区块链网络。开发时用`testnet`，生产环境用`mainnet`。	`mainnet`
`PORTKEY_API_URL`	高级选项。覆盖默认的RPC节点URL。如果你有自己的节点或需要连接特定网关，可以在这里设置。	根据`NETWORK`自动选择
`PORTKEY_PRIVATE_KEY`	慎用。以明文形式设置私钥。这虽然方便（尤其对于脚本），但存在安全风险。更推荐使用加密的本地钱包文件。	空
`PORTKEY_WALLET_DIR`	自定义本地加密钱包文件的存储目录。	`~/.portkey/eoa/wallets/`
`PORTKEY_WALLET_PASSWORD`	核心安全变量。用于加密/解密本地钱包文件的密码。在MCP服务器或需要访问本地钱包的CLI脚本中必须设置。	空
`PORTKEY_SKILL_WALLET_CONTEXT_PATH`	覆盖共享的活跃钱包上下文文件路径。用于多技能、多项目共享“当前钱包”状态。	`~/.portkey/skill-wallet/context.v1.json`

安全最佳实践：永远不要将.env文件或其中包含密码、私钥的内容提交到版本控制系统（如Git）。应该将.env添加到.gitignore中。在生产服务器上，通过Docker secrets、云服务商的环境变量管理或专门的密钥管理服务来设置这些变量。

5.2 依赖管理与构建工具

项目使用Bun作为主要的运行时和包管理器。Bun以其快速的启动速度和与Node.js良好的兼容性，非常适合这类工具类项目。

初始化与安装：

git clone [项目仓库地址] cd eoa-agent-skills bun install # 安装所有依赖

运行测试：

bun test # 运行所有单元测试和集成测试 bun test tests/unit/ # 仅运行单元测试 bun run tests/e2e/mcp-verify.ts # 验证MCP服务器功能是否正常

关于上游依赖漏洞：README中提到了一个已知问题，aelf-sdk依赖的elliptic库存在一个低危漏洞。这是一个上游依赖问题。对于大多数非金融核心应用，这个风险是可控的。你可以通过bun audit命令查看详情，并关注项目仓库的更新，等待上游aelf-sdk升级其依赖后，本项目也会随之更新。

5.3 IronClaw WASM原生工具部署

这是为追求极致性能和无依赖部署的进阶场景准备的。它将核心逻辑用Rust编写并编译为WebAssembly，可以直接在IronClaw运行时中执行。

本地构建与测试流程：

构建WASM模块：bun run ironclaw:wasm:build。这个命令会调用Rust工具链，编译位于ironclaw-wasm/目录下的原生代码。
打包发布包：bun run ironclaw:wasm:bundle。将编译好的.wasm文件和能力描述文件打包成IronClaw可识别的格式。
本地安装：ironclaw tool install ./artifacts/ironclaw/portkey-eoa-ironclaw.wasm。将工具安装到你的本地IronClaw环境中。

关键注意事项：

状态隔离：当前IronClaw WASM版本的钱包存储状态与Bun/Node.js版本的MCP/CLI/SDK是隔离的。这意味着你在MCP中创建的钱包，在IronClaw工具中无法直接使用，需要重新导入或创建。
能力对等：WASM版本实现了全部23个工具，功能上是完备的。
部署路径：生产环境部署时，应从GitHub Releases下载版本化的.tar.gz包进行安装，而不是直接从源码构建。ClawHub主要作为发现和安装引导入口。

6. 常见问题排查与实战技巧

6.1 交易失败问题排查

交易失败是开发中最常遇到的问题，可以按以下步骤排查：

检查网络和地址：确认PORTKEY_NETWORK设置正确，发送和接收地址都是有效的aelf地址，且位于正确的链上（主链/侧链）。
确认余额和精度：使用portkey_get_token_balance确认发送地址有足够的代币余额。特别注意金额单位，确保传入的amount是正确的最小单位（例如1 ELF = 100000000）。
检查Gas费用：使用portkey_estimate_fee预估Gas。确保发送地址有足够的ELF来支付这笔Gas费。aelf上的交易需要消耗ELF作为资源。
验证合约调用：对于合约调用，仔细检查--method名称是否正确，--params的JSON格式是否完全匹配合约方法的参数签名。一个常见的错误是参数类型不匹配，比如合约需要int，你却传了字符串。
查看交易回执：交易发送后，会返回一个transactionId。使用portkey_get_transaction_detail或前往aelf区块链浏览器（如explorer.aelf.io）输入该ID，查看交易详情。回执中的Status字段会明确显示Failed，并且Error字段会给出失败原因（例如Insufficient balance）。

6.2 MCP服务器连接或工具不可用

如果在Claude Desktop中看不到Portkey的工具，请检查：

配置文件路径与语法：确保MCP服务器配置的路径是绝对路径，且JSON格式正确，没有缺少逗号或括号。
环境变量：确保在MCP配置中正确设置了必要的环境变量，特别是PORTKEY_WALLET_PASSWORD（如果使用本地钱包）。
服务器进程：检查Bun进程是否正常运行。可以在终端手动运行bun run src/mcp/server.ts，看是否有错误输出。
客户端重启：修改MCP配置后，必须完全重启Claude Desktop或Cursor，新的MCP服务器才会被加载。

6.3 CLI命令参数格式错误

CLI参数，特别是JSON格式的--params，是常见的错误源。

空参数：必须传'{}'。
字符串参数：需要双层引号。例如，参数是一个地址字符串，应该写为'"2g..."'。
复杂对象：参数是一个嵌套对象，确保整个JSON字符串是有效的。可以先用一个在线JSON验证器校验，再粘贴到命令行中。在Shell中，使用单引号包裹整个JSON字符串可以避免很多转义问题。

6.4 性能与优化建议

批量查询：尽量避免在循环中频繁调用portkey_get_token_balance查询单个代币。优先使用portkey_get_token_list一次性获取所有余额。
连接池与超时：如果你基于SDK构建高并发服务，考虑对底层的HTTP客户端（如axios）配置连接池和合理的超时时间，以应对网络波动。
错误重试：网络请求和区块链RPC调用可能因临时网络问题失败。在SDK集成中，为关键操作（如转账）实现简单的指数退避重试机制。
本地缓存：对于不经常变化的数据，如代币价格列表、链信息，可以在应用层实现短期缓存，减少不必要的RPC调用。

6.5 安全红线

私钥与助记词：这是最高机密。永远不要硬编码在源码中，不要提交到Git，不要通过不安全的信道传输。使用加密的本地钱包文件（配合密码）是最佳实践。
环境隔离：开发、测试、生产环境使用不同的钱包和区块链网络（testnet vs mainnet）。切勿将测试网的私钥误用于主网。
权限最小化：在给AI Agent或自动化脚本授权时，遵循最小权限原则。如果只是查询，就不要提供签名能力。如果只是需要转账，可以单独创建一个仅存有少量资金的热钱包，而不是使用主钱包。
依赖安全：定期运行bun audit检查依赖漏洞，并及时更新项目版本。

这个技能包将aelf区块链的复杂性封装成了一组对AI友好的标准化接口。无论是想快速搭建一个链上查询机器人，还是为你的DeFi策略构建一个自动执行Agent，它都提供了一个坚实、安全且高效的起点。在实际集成中，多花时间理解交易失败的回执信息，善用费用估算功能，并严格遵守安全规范，就能让AI真正成为你在区块链世界中的得力助手。