aelfscan-skill：为AI智能体打造的AELF区块链数据查询工具包

1. 项目概述：为AI智能体打造的区块链数据工具箱

如果你正在开发一个需要查询AELF区块链数据的AI助手，或者想为你的Claude、Cursor、OpenClaw等AI工具增加一个“区块链专家”技能，那么你找对地方了。今天要聊的这个aelfscan-skill项目，就是一个专门为AI智能体（Agent）设计的、功能齐全的AELF区块链数据查询工具包。简单来说，它把AELF区块链浏览器（AelfScan）的绝大部分查询能力，打包成了AI能直接理解和调用的“技能”。

这个工具包最核心的价值在于它的“多接口统一”。它不像传统SDK那样只给开发者用，而是同时提供了SDK、MCP（Model Context Protocol）、CLI命令行工具和OpenClaw配置这四种接入方式。这意味着，无论你是想写代码集成，还是想让Claude Desktop直接调用，抑或是通过命令行快速测试，甚至是为OpenClaw这样的开源AI平台添加技能，aelfscan-skill都能一站式搞定。它背后是一套“元数据驱动”的架构，所有工具的描述只定义一次，就能自动生成适配不同接口的代码，保证了功能的一致性和维护的便捷性。

2. 核心架构与设计哲学

2.1 元数据驱动：一处定义，四处生成

aelfscan-skill项目最精妙的设计在于其“元数据驱动”的工具注册机制。在传统的开发模式里，如果你要为同一个功能（比如“查询区块列表”）提供SDK、CLI和MCP接口，很可能需要在三个不同的地方写三遍类似的参数定义、描述和调用逻辑。这不仅容易出错，一旦API有变动，维护起来更是噩梦。

这个项目彻底解决了这个问题。它在src/tooling/目录下，用一套统一的元数据（metadata）来定义每一个工具。这份元数据清晰地描述了：

• 工具名称：如blockchain_blocks
• 功能描述：AI可读的自然语言说明，例如“获取指定链上的区块列表”。
• 输入参数：每个参数的名称、类型、是否必需、描述及示例值。
• 输出结构：返回数据的类型定义。

基于这份唯一的“真相源”（Single Source of Truth），项目在构建时，会自动生成：

1. TypeScript SDK：供开发者直接在Node.js或Bun项目中导入使用。
2. CLI命令：生成对应的命令行参数解析和调用逻辑。
3. MCP工具定义：生成符合MCP协议的工具描述，供Claude Desktop等客户端加载。
4. OpenClaw配置：生成openclaw.json配置文件。

这样做的好处是显而易见的：功能一致性和维护效率极大提升。你只需要修改一处元数据，所有接口的功能就同步更新了。

2.2 统一的输出治理与结构

让AI稳定、可靠地处理区块链数据，另一个关键是控制输出的“形状”和“规模”。区块链查询动辄返回成千上万条交易记录，如果一股脑全塞给AI，很容易导致其上下文窗口爆炸，或者解析出错。

aelfscan-skill在src/mcp/模块中实现了一套MCP输出治理策略，主要包括：

• 数组截断：当返回结果是列表（如交易列表、Token持有者列表）时，会默认只返回前N条（数量可配置），并在结果中明确提示总数和已截断的信息。
• 最大字符数限制：对整个工具输出的文本内容长度设定了上限，防止超长响应。
• 原始负载可控：提供一个配置项（AELFSCAN_MCP_INCLUDE_RAW），允许高级用户选择是否在返回结果中包含原始的、未加工的API响应数据。对于大多数AI交互场景，关闭此选项，返回结构化的摘要信息更佳。

更重要的是，所有接口的返回都包裹在一个名为ToolResult<T>的统一结构里。这个结构包含：

• data: T: 核心的业务数据。
• traceId: string: 本次请求的唯一追踪ID，用于后续调试和日志排查。
• error?: object: 标准化的错误信息（如果发生错误）。
• raw?: any: 可选的原始API响应数据。

这种设计让AI在处理结果时有了固定的模式可循，大大降低了工具调用的不确定性。

2.3 项目目录结构解析

看一眼项目的目录树，就能对它的模块化设计心领神会：

aelfscan-skill/ ├── index.ts # 主入口，导出所有SDK功能 ├── aelfscan_skill.ts # CLI适配器入口 ├── src/ │ ├── core/ # 核心领域逻辑层 │ │ ├── search/ # 搜索相关逻辑 │ │ ├── blockchain/ # 区块、交易、日志事件 │ │ ├── address/ # 地址详情、资产、转账 │ │ ├── token/ # Token列表、详情、持有者 │ │ ├── nft/ # NFT合集、物品、活动 │ │ └── statistics/ # 统计指标、图表数据 │ ├── tooling/ # 【核心】工具元数据定义 │ └── mcp/ # MCP服务器适配器与输出策略 ├── lib/ # 共享库：配置、HTTP客户端、错误、追踪、类型 ├── bin/setup.ts # 一键安装脚本（Claude/Cursor/OpenClaw） ├── openclaw.json # 自动生成的OpenClaw配置 ├── mcp-config.example.json # MCP服务器配置示例 └── tests/ # 单元、集成、端到端测试

核心层（core/）按区块链数据的领域进行划分，职责清晰。工具层（tooling/）是中枢神经。适配层（mcp/和CLI）负责对外沟通。这种分层使得项目既保持了核心逻辑的纯净，又能灵活扩展新的接入方式。

3. 功能模块深度解析与实操

3.1 搜索模块：多维度的区块链实体检索

搜索是用户最常用的入口。aelfscan-skill的搜索功能支持多实体类型混合检索，并可通过过滤器精确定位。

核心搜索参数解析：

• chainId: 链标识，如主网”AELF“、侧链”tDVV“。
• keyword: 搜索关键词。这可以是一个交易哈希、区块高度、合约地址、账户地址、Token符号（如”ELF“）或NFT名称。
• filterType: 过滤器类型，用于限定搜索的实体范围。例如，你可以指定只搜索Token或只搜索NFT。
• searchType: 搜索类型，进一步细化，比如在Token中搜索是按符号还是按名称。

实操示例：查找ELF Token假设我们想在主网上搜索ELF Token的相关信息，可以通过CLI快速验证：

bun run aelfscan_skill.ts search query --input '{"chainId":"AELF","keyword":"ELF","filterType":0,"searchType":0}'

这里filterType: 0和searchType: 0通常代表“无特定过滤”和“默认搜索”。执行后，返回的data里会包含与“ELF”相关的Token合约、可能的重名账户等列表。

注意：搜索的模糊性与精确性区块链搜索往往是模糊匹配。输入“ELF”可能返回ELF Token合约，也可能返回地址中包含“ELF”字符的普通账户。对于精确查询（如已知完整地址），直接使用address detail接口效率更高。

3.2 区块链数据模块：从宏观到微观的洞察

这个模块提供了区块链的骨架信息，是进行链上分析的基础。

3.2.1 区块与交易列表查询获取最新区块或交易列表是监控链上活动的常用手段。

# 获取最新2个区块 bun run aelfscan_skill.ts blockchain blocks --input '{"chainId":"AELF","maxResultCount":2,"skipCount":0}'

• maxResultCount: 控制单次返回的数量，务必合理设置，尤其是在MCP模式下，避免返回数据过大。默认值200，但建议在AI交互场景下调小，如10或20。
• skipCount: 用于分页，实现“加载更多”的功能。

3.2.2 链上概览与图表数据blockchain overview接口返回的是链的实时“健康仪表盘”，包括当前高度、TPS、账户总数、市值等关键摘要信息。这对于AI快速了解链的当前状态极为有用。

3.2.3 日志事件查询这是与智能合约交互调试的利器。当合约触发事件（Event）时，日志会被记录在链上。

bun run aelfscan_skill.ts blockchain log-events --input '{"chainId":"AELF","contractAddress":"256MtWxt3dvxBUdh1XHjQeeSDm2SMR98gDQxLL4UXjwFDhzcAM","maxResultCount":1,"skipCount":0}'

通过指定contractAddress，可以抓取特定合约发出的所有事件日志，用于分析合约的历史行为，比如一个DEX完成了多少笔交易，一个NFT合约发生了多少次转账。

3.3 地址模块：链上身份的完整档案

在区块链世界，地址就是身份。这个模块让你能深入探查任何一个地址的方方面面。

地址详情（address detail）：这是最全面的查询。输入一个地址，返回的信息包括其类型（外部账户还是合约）、创建时的交易哈希、当前余额、以及关联的Token和NFT资产概览。对于合约地址，还会包含合约名称、符号和创建者等信息。

实操心得：区分账户与合约在分析地址时，首先看isContract字段。如果是true，那么这个地址很可能是一个Token合约、DEX路由或NFT合集。接下来可以：

1. 使用token list或nft collections接口，传入该合约地址，获取其发行的具体资产信息。
2. 使用blockchain log-events接口，监听该合约的活动。 如果是外部账户（isContract: false），分析重点则在其持有的资产（token assets,nft inventory）和资金流向（transfers）。

3.4 Token与NFT模块：资产管理的专业化查询

虽然地址详情里包含了资产概览，但Token和NFT模块提供了更专业、更深入的数据视角。

Token模块：

• token list: 获取链上所有Token的列表，支持分页和排序（如按市值）。
• token detail: 获取某个Token的详细信息，包括总供应量、流通量、持有者数量、价格（如果已上价格预言机）等。
• token holders:重要查询某个Token的持有者分布。返回的数据包括每个地址的余额和占比，是分析Token集中度、寻找巨鲸的关键。
• token transfers: 查看该Token的所有转账记录。

NFT模块： NFT的数据结构更复杂，分为“合集”（Collection）和“物品”（Item）两层。

• nft collections: 获取链上的NFT合集列表。
• nft detail: 查看某个NFT合集的元数据，如名称、符号、总发行量。
• nft inventory: 查询某个地址持有的所有NFT物品列表。
• nft item detail: 查看单个NFT物品的详细信息，包括它的唯一ID（Token ID）、元数据URL、当前所有者等。
• nft item activity: 追踪单个NFT物品的生命周期，包括铸造、转账、销售等所有历史活动。

3.5 统计模块：趋势分析与宏观指标

统计模块是为数据分析和仪表盘准备的。它提供了一系列时间序列数据和聚合指标。

核心接口：

• daily-transactions: 获取最近一段时间（默认7天）的每日交易数图表数据。这是观察链上活跃度的最直观指标。
• daily-transaction-info: 需要指定startDate和endDate，获取更精确时间范围内的每日交易详情，包括交易次数和唯一地址数。
• metric: 这是一个多功能接口，通过传入metric参数，可以获取各种核心指标，如：
  • dailyTransactions: 日交易数
  • dailyActiveAddresses: 日活跃地址数
  • totalSupply: Token总供应量
  • stakingTVL: 质押总锁仓价值
  • nodeCount: 节点数量

使用场景：你可以让AI定期调用这些接口，将数据存入数据库，然后生成链上活动周报、分析市场情绪（通过交易活跃度）、或监控生态发展（通过地址增长和TVL）。

4. 多环境部署与集成实战

4.1 作为SDK在Node.js/Bun项目中使用

这是最灵活的集成方式。首先安装依赖：

# 假设你已初始化了一个Node.js/Bun项目 bun add @aelfscan/skill # 注意：包名可能需要根据实际发布情况调整，这里仅为示例

然后在你的代码中导入并使用：

import { AelfScanClient } from '@aelfscan/skill'; // 初始化客户端，可以传入自定义配置 const client = new AelfScanClient({ baseUrl: process.env.AELFSCAN_API_BASE_URL, timeoutMs: 15000, }); async function analyzeAddress(address: string) { try { // 查询地址详情 const result = await client.address.detail({ chainId: 'AELF', address }); console.log(`地址 ${address} 类型: ${result.data.isContract ? '合约' : '外部账户'}`); console.log(`余额: ${result.data.balance} ELF`); // 查询该地址的NFT库存 const nftResult = await client.nft.inventory({ chainId: 'AELF', address }); console.log(`持有NFT数量: ${nftResult.data.items?.length || 0}`); // 统一的结果结构包含traceId，便于链路追踪 console.log(`追踪ID: ${result.traceId}`); } catch (error) { console.error('查询失败:', error); } }

SDK使用心得：充分利用TypeScript的类型提示。所有工具函数的输入参数和返回类型都有严格定义，这能极大减少编码错误。另外，SDK内部实现了请求重试、缓存和并发控制（通过环境变量配置），在生产环境中非常稳定。

4.2 配置MCP服务器与Claude Desktop集成

这是让AI助手获得区块链查询能力的“魔法”步骤。MCP（Model Context Protocol）是Anthropic推出的一个协议，允许像Claude Desktop这样的客户端动态加载外部工具。

4.2.1 配置与启动MCP服务器首先，复制示例配置文件并根据需要修改：

cp mcp-config.example.json mcp-config.json

在mcp-config.json中，你可以调整MCP特有的参数，比如maxItems（返回列表的最大条数）和maxChars（输出最大字符数）。通常不需要修改工具列表，因为它们是从元数据自动生成的。

然后，启动MCP服务器：

bun run mcp

服务器启动后，会在标准输出（stdout）上以MCP协议（通常是JSON-RPC over stdio）提供服务。关键点：MCP服务器本身不监听网络端口，它通过标准输入输出与父进程（如Claude Desktop）通信。

4.2.2 集成到Claude Desktop

1. 找到你的Claude Desktop配置目录。通常在~/.config/Claude/(Linux/macOS) 或%APPDATA%\Claude\(Windows)。
2. 在该目录下创建或编辑claude_desktop_config.json文件。
3. 添加以下配置，将command路径替换为你本地aelfscan-skill项目中bun可执行文件和脚本的实际路径：

{ "mcpServers": { "aelfscan": { "command": "/path/to/your/bun", "args": ["run", "/absolute/path/to/aelfscan-skill/project/mcp"], "env": { "AELFSCAN_DEFAULT_CHAIN_ID": "AELF", "AELFSCAN_MCP_MAX_ITEMS": "10" } } } }

4. 重启Claude Desktop。现在，当你与Claude对话时，它就能自动调用“查询区块”、“查看地址详情”等工具了。你可以直接说：“帮我查一下AELF主网最新的5个区块”，或者“分析一下地址JRmBduh4nXWi1aXgdUsj5gJrzeZb2LxmrAbf7W99faZSvoAaE的资产情况”。

重要提示：环境变量优先级在MCP配置中通过env设置的环境变量，会覆盖项目根目录.env文件中的同名变量。这为你提供了按客户端配置的灵活性，例如为不同的AI助手设置不同的默认链或返回数据量限制。

4.3 一键安装脚本的妙用

项目提供的bin/setup.ts脚本极大地简化了集成工作。它不仅能生成配置，还能进行环境检查。

# 为Claude Desktop生成配置片段并复制到剪贴板 bun run setup claude # 为Cursor编辑器生成配置（支持全局或项目级） bun run setup cursor bun run setup cursor --global # 全局配置，对所有项目生效 # 为OpenClaw生成配置文件 bun run setup openclaw # 列出所有可用的技能工具 bun run setup list

实操技巧：在集成到Claude Desktop前，先用bun run setup list查看所有可用的工具名称和描述，这能帮助你了解AI具体能调用哪些功能。setup claude命令生成的配置片段非常准确，直接粘贴到Claude配置文件中即可，避免了手动编写JSON容易出错的麻烦。

4.4 OpenClaw集成

OpenClaw是一个开源的AI工具平台。集成aelfscan-skill同样简单：

1. 运行构建命令，生成OpenClaw所需的配置文件：

   bun run build:openclaw

2. 运行检查命令，验证生成的配置是否有效：

   bun run build:openclaw:check

3. 将生成的openclaw.json文件放置到OpenClaw的技能目录下，或者在OpenClaw的配置中指向这个文件路径即可。

5. 高级配置、性能优化与安全实践

5.1 环境变量详解与调优

.env.example文件里列出了一系列环境变量，理解它们对生产部署至关重要：

• AELFSCAN_API_BASE_URL: 指向AelfScan API的基础URL。除非你部署了私有节点或测试网浏览器，否则一般不需要修改。
• AELFSCAN_DEFAULT_CHAIN_ID: 设置默认链ID。如果大部分查询都针对同一条链（如主网AELF），设置这个可以避免在每个请求中都传入chainId。
• AELFSCAN_TIMEOUT_MS: 请求超时时间。对于不稳定的网络环境，可以适当调高（如15000毫秒）。
• AELFSCAN_RETRY与退避策略: 默认失败重试1次。RETRY_BASE_MS和RETRY_MAX_MS控制了指数退避的时间间隔。对于查询类服务，重试可以有效应对网络的瞬时抖动。
• AELFSCAN_MAX_CONCURRENT_REQUESTS: 并发请求数限制。默认5个，防止对API服务器造成过大压力。如果你的应用需要高频查询，可以谨慎调高，但要注意目标服务器的承受能力。
• AELFSCAN_CACHE_TTL_MS与CACHE_MAX_ENTRIES:性能关键配置。对于不常变的数据（如Token详情、合约信息、历史统计图表），启用缓存能极大提升响应速度和降低API调用次数。TTL设置缓存存活时间（如60000毫秒即1分钟），MAX_ENTRIES限制缓存条目数量防止内存溢出。
• AELFSCAN_MCP_*系列: 专门控制MCP服务器的输出行为。MCP_MAX_ITEMS=10和MCP_MAX_CHARS=60000能确保返回给AI的数据量是可控的、高效的。

5.2 钱包上下文兼容性说明

这是一个非常贴心的设计。aelfscan-skill是一个只读技能，它不需要也不处理私钥或签名。但是，在复杂的AI工作流中，一个任务可能需要先查询（读）再执行（写，如转账）。为了与其他需要钱包上下文的“写”技能（例如一个DeFi交易技能）协同工作，它遵循了共享的钱包上下文协议。

具体来说，它会检查~/.portkey/skill-wallet/context.v1.json这个文件（如果存在）。这个文件可能包含当前会话选择的网络、默认地址等信息。aelfscan-skill会读取其中的chainId等信息，用于填充查询请求，从而与其他技能保持上下文一致。你可以通过运行bun run deps:check来验证本地钱包上下文文件的模式版本是否兼容。

5.3 安全最佳实践

项目README中的安全提醒至关重要，这里再强调并扩展几点：

1. 密钥绝不入代码：任何API Token、私钥、助记词都必须通过环境变量（.env文件）或安全的配置管理系统来传递。绝对不要硬编码在源码中，也不要提交到版本控制系统（确保.env在.gitignore中）。
2. 最小权限原则：aelfscan-skill只需要读取权限。在为其配置任何关联服务（假设未来API需要密钥）时，只授予它查询所需的最小权限。
3. 输出净化：虽然工具本身做了输出治理（截断、限长），但在将结果展示给最终用户（尤其是通过Web界面）时，仍需警惕潜在的数据注入风险。确保对返回数据中的动态内容进行适当的转义或过滤。
4. 依赖安全：定期运行bun audit或类似命令，检查项目依赖是否存在已知的安全漏洞。

6. 测试策略与质量保障

一个健壮的工具包离不开完善的测试。aelfscan-skill提供了多层测试套件，确保了代码质量和功能可靠性。

6.1 单元测试：保障核心逻辑

单元测试专注于src/core/目录下的每一个领域函数，模拟各种输入，验证其逻辑是否正确，不依赖外部网络。

bun run test:unit

运行单元测试并生成覆盖率报告：

bun run test:unit:coverage

生成的覆盖率报告能清晰显示哪些代码分支没有被测试到，是提高代码健壮性的重要指标。你还可以运行bun run coverage:badge来生成一个显示覆盖率百分比的徽章，通常用在README中展示项目质量。

6.2 集成测试：验证模块协作

集成测试关注模块之间的交互，例如工具描述符是否正确加载、配置系统是否正常工作等。这些测试可能涉及部分内部模块的集成，但依然不调用真实API。

6.3 端到端（E2E）测试：对接真实环境

这是最重量级的测试，会实际调用AelfScan的线上或测试网API。

bun run test:e2e

重要提示：E2E测试受网络环境影响，且会对真实API产生调用。项目通常默认使用模拟（mock）数据或指向测试网来运行。如果你想针对主网API运行“冒烟测试”，需要显式设置环境变量：

RUN_LIVE_TESTS=1 bun run test:e2e

实操建议：在CI/CD流水线中，通常只运行单元和集成测试。E2E测试，特别是Live Test，应作为手动发布前的最终验证步骤，或配置在低频的定时任务中，以避免对生产API造成不必要的负载。

6.4 测试中的环境隔离

注意，测试套件可能会读取项目根目录的.env文件。为了测试的纯净性，最好在.env.test或类似文件中为测试环境配置专门的变量（如指向测试网API的URL），并在运行测试时通过环境变量NODE_ENV=test来让代码加载对应的配置。

7. 常见问题排查与调试技巧

在实际开发和集成过程中，你可能会遇到一些问题。以下是一些常见场景的排查思路。

7.1 MCP服务器启动失败或Claude无法识别工具

症状：Claude Desktop重启后，没有出现预期的区块链查询工具。排查步骤：

1. 检查MCP服务器日志：在终端直接运行bun run mcp，观察是否有错误输出。常见的错误包括：
   • Error: Cannot find module...：依赖未安装。运行bun install。
   • 端口冲突或权限错误：确保配置文件中command的路径是正确的，且bun有可执行权限。
2. 验证Claude配置：检查claude_desktop_config.json的JSON格式是否正确，路径是否是绝对路径。可以尝试将command改为"bun"，并在args中提供项目的绝对路径。
3. 查看Claude Desktop日志：Claude Desktop通常有应用日志，可以在其设置中或系统日志里查找MCP加载相关的错误信息。
4. 使用setup脚本：最稳妥的方法是使用bun run setup claude重新生成配置并手动核对。

7.2 查询返回空数据或错误

症状：调用工具后，返回的data为空或包含错误信息。排查步骤：

1. 检查输入参数：确认chainId是否正确（如”AELF“是主网）。确认地址格式是否正确（AELF地址通常是Base58或Bech32编码）。
2. 查看traceId：每个返回结果都包含一个traceId。在开发阶段，可以将这个ID记录下来。如果项目开启了更详细的日志（需要自行在代码中或通过环境变量配置），可以用这个ID去搜索对应的请求和响应日志。
3. 检查网络和API状态：直接使用curl或浏览器访问AelfScan官网，确认对应功能是否正常。例如，检查https://aelfscan.io/block/blocks是否能访问。
4. 环境变量覆盖：确认当前生效的环境变量。记住，MCP配置中的env会覆盖.env文件。使用console.log或调试工具输出实际发送请求的URL和参数。

7.3 性能问题：响应缓慢

症状：查询工具调用很慢。优化方向：

1. 启用缓存：确保AELFSCAN_CACHE_TTL_MS设置了一个合理的值（如30000毫秒以上）。对于不常变的数据，缓存效果显著。
2. 调整超时和重试：如果是因为网络不稳定导致的超时重试变慢，可以适当增加AELFSCAN_TIMEOUT_MS，或减少AELFSCAN_RETRY次数。
3. 减少数据量：在MCP模式下，确保AELFSCAN_MCP_MAX_ITEMS设置得较小（如10）。避免一次性请求过多数据。
4. 并发控制：如果自定义代码中并发调用多个工具，注意整体的并发量，避免触达AELFSCAN_MAX_CONCURRENT_REQUESTS限制导致排队。

7.4 类型错误或编译问题

症状：在TypeScript项目中导入SDK时出现类型错误，或者bun run build失败。解决方案：

1. 确保依赖安装：运行bun install --frozen-lockfile确保依赖版本完全一致。
2. 检查TypeScript配置：确保你的tsconfig.json中的moduleResolution等设置与aelfscan-skill项目兼容。通常”bundler“或”node16“是安全的选择。
3. 清理并重建：有时构建缓存会导致问题。可以删除node_modules和bun.lockb，然后重新安装，并运行bun run build。

这个工具包的设计充分考虑了开发者与AI集成时的各种实际需求，从统一抽象的元数据驱动，到细致入微的输出治理和安全考量，都体现出了工程上的成熟度。无论是将其作为后端服务的数据源组件，还是赋予AI助手链上洞察力，aelfscan-skill都提供了一个坚实、优雅的解决方案。