aelf-skills：构建AI智能体区块链技能生态的中央注册表与自动化部署指南

1. 项目概述：aelf-skills，一个为AI智能体打造的区块链技能中心

如果你正在探索如何让AI智能体（比如Claude Code、Cursor、OpenClaw）真正“上手”操作区块链，比如查询AElf节点状态、执行智能合约、分析链上数据，那么你很可能已经遇到了一个核心难题：技能发现与集成。每个技能（Skill）都是一个独立的GitHub仓库或npm包，它们分散各处，安装方式各异，文档格式不一。对于一个需要快速调用多种能力的AI助手或开发者来说，手动去每个仓库翻找、配置、测试，无疑是一场效率噩梦。

aelf-skills项目就是为了终结这场噩梦而生的。你可以把它理解为一个专为AI智能体设计的“区块链技能应用商店”或“中央注册表”。它的核心使命非常明确：提供统一的技能发现、一键式引导安装和标准化的能力索引。它本身不替代任何具体技能的实现逻辑，而是扮演一个“总控台”和“接线员”的角色，让AI智能体或开发者能够以一致、可靠的方式，找到、安装并激活所需的区块链操作能力。

简单来说，它解决了三个关键问题：

1. 发现难：技能散落在各处，没有统一目录。
2. 安装烦：每个技能安装步骤不同，环境依赖复杂。
3. 集成乱：不同AI客户端（Claude Desktop, Cursor, IronClaw等）的集成方式五花八门，配置令人头疼。

aelf-skills通过一个机器可读的skills-catalog.json目录文件，为所有技能定义了标准的元数据格式和“安装契约”。无论是人类开发者还是AI智能体，都可以通过这个目录，配合项目提供的bootstrap.sh脚本和一系列健康检查工具，实现技能的自动化部署与验证。这对于构建基于AElf区块链的自动化工作流、AI辅助开发或链上数据分析任务来说，是一个至关重要的基础设施。

2. 核心设计理念：分离“发现”与“激活”，定义清晰的机器契约

要理解aelf-skills的价值，必须深入其核心设计哲学。它严格区分了技能的“发现”和“激活”两个阶段，并为AI智能体的操作定义了明确的“游戏规则”。

2.1 发现与激活的二分法

这是项目设计中最为精妙且实用的一点。很多工具混淆了“哪里找到代码”和“如何安装运行”。

• 发现阶段：目标是定位技能。aelf-skills支持多种发现源：

  • GitHub仓库URL：如https://github.com/AElfProject/aelf-node-skill
  • npm包名：如@blockchain-forever/aelf-node-skill
  • ClawHub标识符：一个技能分发平台（如果配置了distributionSources.clawhubId） 在这个阶段，目录（skills-catalog.json）提供的就是这些定位信息。AI智能体或脚本需要理解，一个GitHub的treeURL（指向某个提交的代码快照）或仓库主页，仅仅是一个代码来源，而不是最终的、可执行的安装包。

• 激活阶段：目标是让技能在目标环境中运行起来。这是通过执行“安装契约”完成的。契约定义在skills-catalog.json每个技能的clientInstall字段中。

  • 对于OpenClaw，优先使用distributionSources.clawhubId指向的托管安装源。如果没有，则执行clientInstall.openclaw.installCommand中定义的命令。
  • 对于IronClaw，则必须执行clientInstall.ironclaw.installCommand中定义的本地安装命令。项目明确禁止将GitHub代码树URL直接作为IronClaw的安装输入，因为这涉及到安全边界和依赖管理问题。

为什么这么设计？这源于对安全和可靠性的深度考量。直接执行来自GitHub的代码存在版本不确定性、依赖缺失、环境不兼容等风险。而installCommand是一个经过技能作者定义和测试的、标准的安装流程（通常是npm install或bun install加上一些初始化步骤），能确保技能被正确地安装到本地环境中，处理好所有依赖。这为AI智能体的自动化操作划定了一条安全、可预测的路径。

2.2 机器可读的目录与AI导航系统

skills-catalog.json是这个项目的基石。它不是一个给人看的简单列表，而是一个结构化的、版本化的数据契约。对于AI智能体而言，这就是它的“技能地图”。

这个目录文件包含了每个技能的丰富元数据：

• 身份与描述：id,displayName,description,capabilities（技能能力列表）。
• 分发源：distributionSources，明确指向代码所在。
• 产出物：artifacts，指明技能安装后会生成什么，比如mcpServer（Model Context Protocol 服务器）的路径，这对于与支持MCP的客户端（如Claude Desktop）集成至关重要。
• 客户端支持矩阵：clientSupport，清晰地列出该技能支持哪些AI客户端（Claude Desktop, Cursor, IronClaw, Codex）。
• 安装契约：clientInstall，如前所述，是激活技能的核心指令。
• 依赖关系：dependsOn（从schema 1.3.0开始），可以声明技能之间的依赖，这对于管理复杂技能组合非常重要。

为了让AI智能体（尤其是大型语言模型）能更好地理解和使用这个目录，项目提供了完整的“导航文档”：

• SKILL_ROUTING_MATRIX.md：可以理解为“意图路由表”。当AI接收到一个用户请求（如“查询AElf主网最新区块”），它可以查阅此矩阵，判断应该调用哪个技能（例如aelf-node-skill），以及如何调用。
• AI_E2E_SCENARIOS.md：提供了端到端的执行场景示例和通用的错误恢复模板。这是极其宝贵的实操指南，告诉AI在遇到安装失败、命令出错等常见问题时，应该按照什么步骤进行排查和重试。
• TYPE_SAFETY_MATRIX.md：记录了各个技能TypeScript类型定义的完善程度，帮助AI在提供代码补全或类型检查时心中有数。

这套组合拳，使得aelf-skills不仅仅是一个代码仓库，更是一个为AI智能体与区块链技能交互而精心设计的操作系统接口。

3. 上手实操：从零开始搭建你的技能环境

理论说得再多，不如动手一试。下面我将带你完整走一遍使用aelf-skills的流程，并穿插我实践中积累的关键要点。

3.1 环境准备与项目初始化

首先，确保你的系统满足硬性要求：

• Bun >= 1.1.0: 这是项目的核心运行时，比Node.js更快，内置了包管理、测试和脚本运行功能。如果还没安装，去 bun.sh 官网一键安装。
• npm >= 10和git >= 2.39: 通常现代系统都已满足。
• tar: 用于解压包，Linux/macOS通常自带，Windows用户可能需要通过Git Bash或WSL获得。

# 1. 克隆 aelf-skills 仓库（如果你需要贡献或深度定制） git clone https://github.com/AElfProject/aelf-skills.git cd aelf-skills # 2. 安装项目依赖（使用 bun 或 npm） bun install # 或 npm install # 3. （关键步骤）设置 SKILLS_BASE 环境变量 # 这个变量定义了所有技能将被下载和安装的根目录。强烈建议设置，保持路径一致性。 export SKILLS_BASE=$HOME/workspace/aelf-skills-root mkdir -p $SKILLS_BASE

注意：workspace.json文件内部使用了${SKILLS_BASE}这样的占位符。这个文件主要是给Codex这类本地工作区管理的AI工具使用的。对于大多数通过脚本或命令行交互的用户和AI来说，skills-catalog.json才是主要的数据源。设置SKILLS_BASE主要是为了与可能存在的workspace.json配置保持兼容，并统一技能存放位置。

3.2 生成与理解技能目录

项目的核心数据skills-catalog.json并不是手动维护的，而是通过脚本生成的。这保证了数据的准确性和一致性。

# 生成公开目录（用于发布和一般查看） bun run catalog:generate # 此命令会读取 workspace.json，拉取各个技能仓库的最新信息，更新 skills-catalog.json 和 README 中的技能表格。 # 生成本地目录（包含本地路径信息，用于引导和健康检查） bun run catalog:generate:local # 这个命令生成的目录会包含 `sourcePath` 字段，指向技能在本地的实际路径，对于后续的 `bootstrap.sh` 和 `health:check` 是必需的。

实操心得：

• 在贡献新技能或更新现有技能信息后，必须运行catalog:generate来更新中央目录。项目CI也会检查这一点。
• catalog:generate:local依赖于workspace.json和正确的SKILLS_BASE环境变量。如果运行失败，首先检查这两项。
• 生成的skills-catalog.json文件就是你的“技能圣经”。在让AI执行任何操作前，最好自己先浏览一下这个文件的结构，理解每个字段的含义。

3.3 使用 Bootstrap 脚本一键获取技能

这是aelf-skills最核心的用户功能。bootstrap.sh脚本封装了从发现、下载到安装（可选）的全过程。

# 最基本的使用方式：使用默认目录，从自动源（优先npm）下载并安装所有技能到当前目录下的 `downloaded-skills` 文件夹 ./bootstrap.sh # 更常见的、推荐的使用方式：指定目标目录，并跳过立即安装（先下载，后按需安装） ./bootstrap.sh --dest $SKILLS_BASE --skip-install # 只下载特定的技能（例如，我只想要节点查询和扫描技能） ./bootstrap.sh --only aelf-node-skill,aelfscan-skill --dest $SKILLS_BASE # 指定下载源为 GitHub（例如，npm包尚未发布最新版本时） ./bootstrap.sh --source github --dest $SKILLS_BASE # 下载后跳过健康检查（用于快速下载，但后续需手动检查） ./bootstrap.sh --skip-health --dest $SKILLS_BASE

参数解析与避坑指南：

• --dest：务必指定。否则技能会下载到脚本所在目录，容易造成混乱。我习惯设为$SKILLS_BASE。
• --skip-install：强烈建议在首次探索时加上。这样脚本只下载代码仓库，不执行npm install等命令。你可以先查看代码结构，再手动进入目录安装。这给了你更多的控制权，也避免了因网络或权限问题导致的安装中断影响下载过程。
• --only：当你只需要一两个技能时非常有用，可以节省时间和磁盘空间。
• --source：auto模式是默认且最智能的。它会先尝试从npm下载（更快、更稳定），失败则回退到GitHub克隆。除非你明确需要GitHub上的开发分支，否则不用管它。

脚本做了什么？

1. 解析目录：读取skills-catalog.json。
2. 选择技能：根据--only参数过滤。
3. 下载：根据--source策略，从npm下载tarball或从GitHub克隆仓库到--dest指定的目录下。
4. 安装（如果未跳过）：进入每个技能目录，执行其package.json中定义的依赖安装。
5. 健康检查（如果未跳过）：对下载的技能运行bun run health:check。

3.4 运行健康检查与安全审计

下载或安装完成后，验证技能是否“健康”至关重要。

# 检查本地 workspace.json 中定义的技能源 bun run health:check # 检查通过 bootstrap 下载到特定目录的技能 bun run health:check -- --skills-root ./downloaded-skills # 或 bun run health:check -- --skills-root $SKILLS_BASE

健康检查的内容：

• 目录存在性：技能文件夹是否存在。
• 关键文件检查：如package.json、skill.md（技能描述文件）、mcp.server.js（如果声明了MCP服务）等是否存在。
• 基础构建检查：可能会尝试运行bun install或npm install以及bun run build（如果定义了）来验证项目结构基本正常。

安全审计： 这是一个独立但重要的步骤，用于检测技能安装命令中可能存在的风险模式。

bun run security:audit

它会扫描skills-catalog.json中所有clientInstall里的命令，标记出那些直接执行远程脚本（如curl | bash）或具有潜在风险的操作。作为技能使用者，定期运行此命令是一个好习惯。

4. 为AI智能体配置技能：以Claude Desktop和Cursor为例

作为开发者，我们最终目标是让AI智能体能无缝使用这些技能。这里以两个流行的AI编码助手为例，说明如何将aelf-skills管理的技能集成进去。

4.1 集成到 Claude Desktop (通过 MCP)

Claude Desktop 支持 Model Context Protocol (MCP)，这是一种让AI模型安全访问工具和数据的协议。许多aelf-skills中的技能都提供了 MCP 服务器。

步骤：

1. 使用bootstrap下载技能：如前所述，将技能下载到本地，例如$SKILLS_BASE。
2. 安装并构建技能：进入技能目录，安装依赖并构建（如果需要）。通常技能README会有说明。

   cd $SKILLS_BASE/aelf-node-skill bun install bun run build # 如果 package.json 里有 build 脚本

3. 配置 Claude Desktop 的 MCP 设置：
   • 打开 Claude Desktop。
   • 进入设置 -> 开发者 -> 编辑 MCP 配置。
   • 编辑claude_desktop_config.json文件（通常位于~/Library/Application Support/Claude或%APPDATA%\Claude）。
4. 添加MCP服务器配置：参考技能文档（通常是skill.md或 README）中的MCP配置部分。例如，aelf-node-skill的配置可能如下：

   { "mcpServers": { "aelf-node": { "command": "node", "args": [ "/ABSOLUTE/PATH/TO/YOUR/SKILLS_BASE/aelf-node-skill/build/mcp-server.js" ], "env": { "AELF_NETWORK": "mainnet" // 或其他环境变量 } } } }

   关键点：args中的路径必须是绝对路径。这就是为什么之前要设置并统一SKILLS_BASE的原因，它让配置变得可预测和可管理。

5. 重启 Claude Desktop：保存配置后重启客户端，Claude 就应该能识别并使用该技能提供的工具了。

4.2 集成到 Cursor

Cursor 同样支持MCP，配置方式与Claude Desktop类似，但配置文件的位置和格式可能略有不同。通常需要查看Cursor的官方文档或技能仓库中关于Cursor集成的特别说明。一些技能可能会在skills-catalog.json的setupCommands.cursor字段中提供具体的配置命令或指引。

通用流程：

1. 找到 Cursor 的 MCP 配置位置（可能是~/.cursor/mcp.json或工作区内的.cursor/mcp.json）。
2. 按照类似上述的格式，添加MCP服务器配置。
3. 重启 Cursor。

4.3 对于 OpenClaw / IronClaw / Codex

对于这些更专注于AI智能体工作流的客户端，集成方式通常由clientInstall契约直接定义。

• OpenClaw：如果技能在distributionSources.clawhubId有值，OpenClaw可能会从其托管平台直接安装。否则，它会执行clientInstall.openclaw.installCommand。
• IronClaw：它会忠实地执行clientInstall.ironclaw.installCommand。这就是为什么这个命令必须是一个完整的、能在本地环境中成功运行的安装脚本。
• Codex：作为本地工作区工具，它可能直接读取workspace.json和本地技能路径来提供上下文和工具。

给技能开发者的建议：在编写技能的clientInstall.installCommand时，务必确保它在干净的、符合前置条件的环境中是可执行的。最好提供一个本地测试脚本，验证安装命令能正确运行。

5. 常见问题排查与实战经验分享

在实际使用和集成aelf-skills的过程中，我遇到并总结了一些典型问题和解决方案。

5.1 Bootstrap 脚本执行失败

问题现象：运行./bootstrap.sh时卡住、报错权限不足或下载失败。

排查步骤：

1. 检查网络和代理：特别是从GitHub克隆或npm下载时。可以尝试手动git clone或npm view一个技能包来测试。
2. 检查 Bun 版本：运行bun --version，确保是 1.1.0 或更高。版本不符是很多奇怪错误的根源。
3. 检查目录权限：确保对--dest指定的目录有写权限。
4. 使用--skip-install和--skip-health：先仅下载代码，排除安装和检查步骤的影响。
5. 查看详细日志：脚本本身输出可能有限。可以手动执行它内部的关键步骤，例如查看skills-catalog.json中某个技能的repository.https字段，然后手动git clone试试。

我的经验：在CI/CD环境或一些限制较多的服务器上运行bootstrap时，总是先加上--skip-install。先确保代码能拉下来，再在一个更可控的环境里（比如容器内）执行安装和构建，这样更容易隔离问题。

5.2 健康检查 (health:check) 不通过

问题现象：bun run health:check报告某些技能缺失文件或构建失败。

排查步骤：

1. 确认技能目录存在且路径正确：检查--skills-root参数是否指向了正确的、包含技能子文件夹的目录。
2. 检查技能完整性：进入报错的技能目录，查看文件是否完整。bootstrap.sh下载失败可能会留下不完整的文件夹。
3. 手动运行技能的自检脚本：许多技能在package.json中定义了test或health脚本。尝试手动运行bun test或npm test。
4. 查看依赖是否安装：如果健康检查包含构建步骤，确保已经在该技能目录下运行过bun install。
5. 查阅技能的独立文档：回到该技能的原始GitHub仓库，查看是否有特殊的环境要求或构建步骤。

5.3 AI智能体无法识别或调用技能

问题现象：在Claude Desktop或Cursor中配置了MCP，但AI助手说找不到工具或调用失败。

排查步骤：

1. 验证MCP服务器是否在运行：在配置MCP时，可以尝试在终端手动运行你配置的命令。例如：

   node /path/to/skill/build/mcp-server.js

   如果服务器启动失败，会有错误信息输出，这通常是问题所在（如缺少环境变量、端口冲突、依赖错误）。
2. 检查Claude Desktop/Cursor的日志：这些客户端通常有开发者控制台或日志文件，里面会记录MCP服务器连接和通信的详细信息，是排查问题的金矿。
3. 确认技能与客户端的兼容性：查看skills-catalog.json中该技能的clientSupport字段，确认它明确支持你正在使用的客户端（如claude_desktop）。
4. 环境变量配置：许多区块链技能需要配置RPC端点、私钥（或助记词）等环境变量。确保在MCP服务器配置的env字段中，或在启动AI客户端的终端环境里，正确设置了这些变量。
5. 路径问题：再次确认MCP配置中的路径是绝对路径，并且指向的是构建后的输出文件（如mcp-server.js），而不是源代码文件。

5.4 更新管理与版本漂移

aelf-skills项目自身和它收录的技能都在不断更新。

问题：如何知道我的本地技能目录或技能版本已经过时了？

解决方案：使用项目内置的更新检查工具。

# 检查是否有更新（非阻塞，有缓存，默认24小时内只提醒一次） bun run update:check # 强制立即检查更新 bun run update:check -- --force # 以JSON格式输出更新信息，便于脚本处理 bun run update:check:json

这个功能通过缓存上次检查的时间戳来实现免打扰提醒。你可以通过环境变量AELF_SKILLS_UPDATE_TTL_HOURS来调整提醒频率。

我的工作流：我会将bun run update:check加入到我的日常开发环境启动脚本中，或者定期手动执行。如果发现核心技能（如aelf-node-skill）有重大更新，我会：

1. 使用./bootstrap.sh --only <skill-id> --source auto重新下载该技能。
2. 仔细阅读该技能仓库的 Changelog 或 Release Notes。
3. 在测试环境中重新集成和测试，确认无误后再更新生产或常用环境的配置。

5.5 贡献新技能时遇到的坑

如果你想将自己的技能添加到aelf-skills生态中，项目提供了非常详细的贡献指南和模板。但仍有几点需要特别注意：

1. workspace.json是入口：你的技能首先要被添加到workspace.json文件中，catalog:generate脚本才会发现它。确保路径和id正确。
2. 完整的元数据：你的技能仓库根目录需要有一个skill.md文件，其中包含符合skill-frontmatter.schema.json的YAML头信息。这是生成skills-catalog.json的关键。
3. 定义清晰的clientInstall契约：这是AI智能体激活你技能的关键。命令必须独立可执行，处理好所有前置条件（如检查环境变量、创建必要目录等）。最好在仓库里提供一个scripts/install-local.sh进行本地测试。
4. 通过所有CI门禁：提交PR前，务必在本地运行bun run health:check、bun run readme:check和bun run security:audit，确保不会破坏现有流程。项目CI非常严格，这些检查失败会导致PR被拒绝。

aelf-skills项目代表了一种面向未来的基础设施构建思路：通过严格的契约、机器可读的目录和清晰的执行边界，为AI智能体与复杂系统（如区块链）的交互搭建了一座坚固、可靠的桥梁。它降低的不是单一技能的使用门槛，而是整个技能生态的集成和运维成本。随着收录的技能越来越多，这套机制的价值会愈发凸显。对于任何想要构建或使用基于AElf区块链的AI智能体应用的开发者来说，深入理解并熟练运用aelf-skills，无疑是提升效率、保证稳定性的最佳实践。