1. 项目概述一个为aelf区块链上的DAO治理而生的AI Agent技能包如果你正在aelf区块链上构建或参与DAO去中心化自治组织并且希望将繁琐的链上治理操作——比如创建提案、投票、管理资源——无缝集成到你的AI工作流中那么tomorrowdao/agent-skills这个工具包就是你一直在找的“瑞士军刀”。简单来说它是一个专为AI Agent智能体设计的技能集合让Claude、Cursor这类AI助手能够直接与aelf链上的TomorrowDAO协议进行交互把复杂的Web3操作变成几句简单的自然语言指令。这个项目的核心价值在于“桥接”。它一头连着aelf区块链上成熟的DAO治理合约和网络治理体系另一头则通过MCP、OpenClaw、CLI和SDK四种标准接口接入了现代AI开发者和用户最熟悉的工作环境。这意味着你不再需要为了发起一个DAO提案而去翻找合约ABI、手动构造交易、处理钱包签名你只需要在你的代码里调用一个清晰的函数或者在Claude Desktop里用对话的方式告诉AI“帮我在‘Demo DAO’里创建一个关于预算调整的提案”剩下的链上交互细节这个技能包会帮你全部搞定。我花了相当一段时间去深度使用和测试这套工具发现它的设计非常“务实”。它没有试图去创造一个全新的、封闭的DAO系统而是选择成为现有强大基础设施aelf链、TomorrowDAO协议的最佳“操作员”。对于开发者而言它提供了类型安全的SDK和可脚本化的CLI对于AI原生应用的用户它通过MCP协议让治理能力直接成为AI助手的一部分。这种分层、多接口的设计使得无论是想快速写个脚本自动化治理流程还是想打造一个能理解DAO的智能客服机器人都能找到合适的切入点。2. 核心架构与设计哲学解析2.1 为什么是“技能包”而非“SDK”初看项目名agent-skills你可能会觉得它只是一个简单的函数库。但深入其架构后你会发现它的定位远比传统SDK要精准和前沿。它的核心设计哲学是“技能化”和“协议优先”。技能化意味着每个功能都被封装成一个独立的、可被AI理解和调用的“工具”。在MCP的语境下一个“技能”就是一个Tool它有明确的输入参数、输出格式和执行逻辑。例如tomorrowdao_dao_create就是一个创建DAO的技能tomorrowdao_bp_vote就是一个为节点候选人投票的技能。这种设计让AI Agent可以像人类使用工具一样根据上下文动态选择并调用这些技能完成复杂的多步骤任务。项目通过src/mcp/server.ts暴露了整整45个这样的工具覆盖了DAO、网络治理、BP选举、资源交易等所有核心场景。协议优先则体现在它对现有区块链协议的无侵入式集成上。它没有重新发明轮子去定义DAO的数据结构或治理流程而是完全遵循aelf链上TomorrowDAO智能合约的既定接口和业务逻辑。项目中的src/domains/目录清晰地按领域划分dao/、token/、network/、bp/、resource/。每个领域模块的代码本质上都是对底层合约方法的封装和友好化包装确保了行为的确定性和与链上状态的一致性。2.2 多模态消费接口适配不同场景的优雅设计这是该项目最亮眼的设计之一。它没有强迫用户只用一种方式而是提供了四种入口适配从终端脚本到AI对话的各种场景MCP Server这是面向AI协作者时代的接口。通过实现MCP协议它能让Claude Desktop、Cursor等直接加载这些技能。AI在分析你的需求后可以主动调用相应的工具。例如你问“我们DAO的AIBOUNTY代币还剩多少”AI可以自动调用tomorrowdao_dao_token_balance_view工具并返回结果。这对于构建复杂的、可行动的AI助手至关重要。CLI这是面向自动化和脚本开发的接口。所有技能都通过tomorrowdao_skill.ts这个统一的命令行入口暴露出来。你可以用Bun、Node.js写脚本定时执行提案创建、批量投票等操作。它的参数设计为JSON格式非常适合与其他系统集成。SDK这是面向传统应用开发的接口。直接从index.ts导入函数你就能在TypeScript/JavaScript项目中以编程方式使用所有功能。这对于构建自定义的管理面板、机器人或者将DAO功能嵌入现有DApp非常方便。OpenClaw Config这是针对OpenClaw这个AI Agent框架的优化适配。通过bun run build:openclaw可以生成标准的OpenClaw工具描述文件让你的技能能被OpenClaw框架识别和调度。这种设计的好处是显而易见的解耦与复用。核心的业务逻辑在src/domains/和src/core/中被所有接口共享。当底层合约升级或逻辑修复时只需要更新核心代码所有四种使用方式都能同步受益。2.3 安全与执行模式simulate与send的双重保障在区块链上操作安全是头等大事。该项目引入了一个非常实用的mode参数simulate或send这可能是新手最容易忽略但最重要的一个特性。simulate模式默认此模式下技能不会真正向区块链发送交易而是调用节点的simulate或call方法预估交易执行的结果、可能消耗的资源CPU/NET并检查交易是否会失败。它完全不会上链也不会消耗任何资源或费用。你应该在任何send操作之前都先用simulate跑一遍。这就像航天发射前的模拟测试能提前发现参数错误、权限不足、余额不够等问题。send模式此模式下技能会构造真实的交易使用配置的私钥进行签名并广播到区块链网络。交易一旦成功将永久改变链上状态并消耗资源。我强烈建议在你的工作流中固化这个步骤永远先simulate检查返回的TxReceipt中的status和error字段确认无误后再切换为send。项目文档中所有示例都遵循了这个模式这是一个非常好的实践。关于私钥管理项目采用了灵活且安全的优先级策略调用时显式传入的privateKey或signer对象最高优先级。活跃的钱包上下文如Portkey的CA钱包上下文文件。环境变量回退TMRW_PRIVATE_KEY-AELF_PRIVATE_KEY-PORTKEY_PRIVATE_KEY。特别需要注意的是对CA合约账户的处理如果技能检测到当前签名者是CA对于写操作会直接返回SIGNER_CA_DIRECT_SEND_FORBIDDEN错误。这是因为CA的写操作必须通过其Manager进行Forward转发不能直接发送。这个设计强制了更安全的CA操作流程避免了潜在的误操作风险。3. 从零开始环境配置与一键集成指南3.1 基础环境搭建与依赖安装这个项目基于Bun运行时因此第一步是确保你的系统已经安装了Bun。如果还没安装可以去Bun官网根据指引安装。用Bun的优势在于其极快的启动速度和内置的包管理、测试、脚本运行能力与这个需要快速响应AI调用的技能包场景非常匹配。# 1. 克隆仓库 git clone https://github.com/TomorrowDAOProject/tomorrowDAO-skill.git cd tomorrowDAO-skill # 2. 安装依赖 bun install这一步会安装所有必要的依赖包括aelf-sdk、各种工具库和测试框架。接下来是配置环境变量。项目提供了一个.env.example模板你需要复制它并填写自己的配置。cp .env.example .env现在打开新创建的.env文件你需要关注几个关键配置TMRW_PRIVATE_KEY你的EOA外部账户私钥。这是用于交易签名的关键。切记这个文件不要提交到版本控制系统对于生产环境应考虑使用更安全的密钥管理服务或硬件钱包集成虽然当前版本主要依赖环境变量或文件。TMRW_RPC_AELF和TMRW_RPC_TDVVaelf主网和tDVV侧链的RPC节点地址。默认提供的是公共节点对于高频或生产级应用建议使用私有节点或付费节点以获得更好的稳定性和速率限制。TMRW_CHAIN_DEFAULT_DAO和TMRW_CHAIN_DEFAULT_NETWORK分别指定DAO操作和网络治理操作的默认链。通常DAO在tDVV网络治理在AELF主网除非你有特殊需求否则保持默认即可。3.2 一键集成到你的AI工作流这是项目的“杀手级”功能。通过提供的setup脚本你可以几乎零配置地将所有技能集成到不同的AI平台。集成到Claude Desktopbun run setup claude这个命令会自动在Claude Desktop的MCP服务器配置文件中添加tomorrowdao-agent-skills的配置。完成后重启Claude Desktop你的AI助手就立刻获得了与TomorrowDAO交互的能力。你可以尝试问它“用simulate模式在tDVV上创建一个名为‘Test Club’的DAO。”集成到Cursor# 项目级集成推荐仅当前项目生效 bun run setup cursor # 全局集成对所有项目生效 bun run setup cursor --global对于使用Cursor的开发者来说这个集成意味着你可以在编写与DAO相关的代码时直接让Cursor AI帮你调用技能包函数或者查询链上状态极大提升开发效率。集成到OpenClaw# 生成OpenClaw配置并打印到控制台 bun run setup openclaw # 将配置合并到已有的OpenClaw配置文件中 bun run setup openclaw --config-path /path/to/your-openclaw-config.jsonOpenClaw是另一个流行的AI Agent框架。这个命令会生成符合OpenClaw规范的工具定义JSON你可以将其合并到你的Agent配置中。关于IronClaw集成的特别说明项目文档特别强调了与IronClaw集成的注意事项。运行bun run setup ironclaw会做两件事在IronClaw的MCP服务器列表注册并将本地的技能说明文档复制过去。这里有一个关键陷阱IronClaw默认会将安装的技能“降级”为只读工具。这意味着即使MCP服务器提供了创建提案、投票等写操作技能IronClaw也可能不会向AI暴露这些功能导致AI看起来只能查询。避坑指南如果你使用IronClaw并需要完整的写操作能力务必确保技能是通过“受信任技能”路径~/.ironclaw/skills/tomorrowdao-agent-skills/加载的而不是通过其自动安装的路径。MCP服务器已经为写操作标记了destructive注解以便IronClaw在执行前请求用户批准。目前为了兼容性注解同时提供了camelCase和snake_case两种格式。3.3 核心配置项深度解读除了基础的私钥和RPC配置.env文件中还有一些高级选项值得关注TMRW_HTTP_TIMEOUT_MS和重试相关配置当技能包与后端API或区块链节点通信时这些配置决定了网络行为的韧性。在公网环境不稳定时适当调高超时如15000ms和重试次数TMRW_HTTP_RETRY_MAX3可以增加成功率。注意TMRW_HTTP_RETRY_POST默认为0不重试POST因为POST通常是非幂等的写操作重试可能导致重复执行。TMRW_AELF_CACHE_MAX在长时间运行的进程如MCP服务器中技能包会缓存aelf客户端实例以避免重复创建。这个值设置了缓存池的大小。如果你的应用需要同时连接多个不同的链或私钥可能需要监控缓存效果。TMRW_LOG_LEVEL调试时设为debug可以打印出非常详细的请求、响应和内部状态信息对于排查问题极有帮助。在生产环境则应设为error或warn。4. 技能详解与实战操作手册4.1 DAO治理技能从创建到执行DAO技能是这套工具的核心。我们以一个完整的DAO生命周期为例看看如何用CLI其他接口同理来操作。1. 创建DAObun run tomorrowdao_skill.ts dao create --input {args:{metadata:{name:Our Creative DAO,logoUrl:https://example.com/logo.png}}} --mode simulate关键参数metadata对象包含了DAO的基本信息。name是必填的。logoUrl、description、socialMedia等都可以按需添加。模拟先行这里用了--mode simulate只会预估创建所需的资源比如RAM并返回一个模拟的交易回执不会真的创建。实操心得创建DAO通常需要一笔不小的资源抵押用于存储DAO信息。务必先用simulate模式查看预估的资源消耗确保发起账户的余额充足。如果simulate成功再换成--mode send执行。2. 创建提案假设我们的DAO ID是_OurCreativeDAO我们要创建一个“购买设计软件订阅”的提案。bun run tomorrowdao_skill.ts dao proposal-create --input { args: { daoId: _OurCreativeDAO, proposal: { title: Purchase Figma Team Plan Subscription, description: Request 500 USDT to purchase an annual Figma Team plan for our design contributors., proposalType: Transfer, transferProposal: { to: RECIPIENT_ADDRESS, symbol: USDT, amount: 500000000, // 注意精度USDT通常是8位小数 memo: Figma subscription FY2024 } } } } --mode simulate提案类型除了Transfer转账还支持ContractDeployment部署合约、ContractMethodCall调用合约方法等多种复杂类型。你需要根据proposalType来填充对应的字段如transferProposal。金额精度这是最容易出错的地方。aelf链上代币金额通常是以最小单位如1 USDT 10^8表示的整数。示例中的500000000代表5亿个最小单位即500个USDT。务必查阅对应代币的精度并在工具调用前完成转换。3. 投票提案创建成功后会返回一个proposalId。成员可以对此进行投票。bun run tomorrowdao_skill.ts dao vote --input { args: { proposalId: THE_PROPOSAL_ID_HASH, voteOption: 0, // 0 赞成1 反对 voteAmount: 100000000 // 投票的票数基于你持有的DAO治理代币数量 } } --mode sendvoteOption0表示赞成1表示反对。这是aelf链上DAO合约的标准定义。voteAmount你愿意用多少治理代币来支持你的选择。票数越多权重越大。4. 执行提案在提案达到规定的通过条件如赞成票超过阈值、投票期结束后任何人都可以触发执行。bun run tomorrowdao_skill.ts dao execute --input {args:{proposalId:THE_PROPOSAL_ID_HASH}} --mode send执行操作会真正执行提案内容比如完成转账。5. 查询与辅助功能查看我的投票信息dao proposal-my-info工具可以查询当前地址对某个提案的投票情况。查看DAO代币余额/授权dao token-balance-view和dao token-allowance-view是查询特定DAO内代币情况的快捷方式。讨论功能discussion-list和discussion-comment提供了链上讨论区的集成允许围绕提案进行公开讨论。4.2 网络治理与BP选举技能这部分技能主要针对aelf主网AELF的链上治理。网络治理提案与DAO提案类似但目标是整个aelf网络的参数调整、合约升级等。你需要指定proposalType例如Parliament议会提案、Referendum公投提案等并提供对应的参数。bun run tomorrowdao_skill.ts network proposal-create --input { chainId: AELF, proposalType: Parliament, args: { title: Adjust Block Producer Reward Ratio, description: Proposal to adjust the reward distribution ratio among BPs., contractMethodName: SetRewardRatio, toAddress: CONTRACT_ADDRESS, params: {\ratio\:\5000\} } } --mode simulateBP区块生产者选举这是aelf的DPoS共识机制的核心。任何持有足够抵押的代币持有者都可以参与投票。申请成为BP候选人bp apply需要提供团队信息、竞选宣言和抵押一定数量的ELF代币。投票与更改投票bp vote和bp change-vote允许你将票投给支持的BP候选人。你的投票权重与你抵押的ELF数量相关。领取收益当选的BP及其投票者可以定期通过bp claim-profits领取出块奖励。关键技巧BP选举是一个动态竞争过程。使用bp votes-list和bp team-desc-list工具可以实时查看候选人的得票情况和团队信息辅助你做出投票决策。注意所有BP操作都只在AELF主网有效。4.3 资源交易技能aelf网络中的智能合约执行需要消耗资源CPU、NET、RAM等。这些资源可以通过抵押ELF代币获得也可以在资源市场直接买卖。resource技能组提供了这个市场的接口。购买资源bun run tomorrowdao_skill.ts resource buy --input { symbol: CPU, amount: 50000000, payLimit: 100000000 // 愿意支付的最大ELF数量单位Satoshi, 1 ELF 10^8 Satoshi } --mode simulatesymbol资源类型如CPU、NET、RAM等。payLimit这是一个重要的保护参数。因为资源价格是实时波动的设置一个你愿意支付的最高单价上限可以避免在价格剧烈波动时以过高成本成交。查询市场记录在交易前使用resource realtime-records和resource records查询最近的市场成交价和深度可以帮助你设定一个合理的payLimit。重要安全实践对于资源买卖这种涉及实时市场价格和代币转移的操作务必遵循“模拟-检查-小额测试-正式操作”的流程。先用simulate和查询工具摸清市场情况然后用极小的数量amount进行一次真实的send操作确认整个流程符合预期后再进行大额交易。4.4 使用SDK进行集成开发对于想要将功能嵌入自己应用的开发者SDK模式提供了最大的灵活性。以下是一个在Node.js脚本中创建DAO并监控提案的示例import { daoCreate, daoProposalCreate, daoProposalMyInfo, ToolResult } from tomorrowdao/agent-skills; import { config } from dotenv; config(); // 加载.env环境变量 async function manageDAO() { // 1. 创建DAO const createResult: ToolResultany await daoCreate({ chainId: tDVV, mode: simulate, // 首次模拟 args: { metadata: { name: Dev Guild, description: A DAO for open source developers., }, }, }); if (createResult.status ! success) { console.error(DAO模拟创建失败:, createResult.error); return; } console.log(DAO模拟创建成功预估资源消耗:, createResult.receipt?.resourceFee); // 确认后切换为send模式此处需要私钥已配置 // const realCreateResult await daoCreate({...sameParams, mode: send}); // const daoId realCreateResult.receipt?.daoId; // 2. 假设我们有了DAO ID创建一个提案 const daoId _DevGuild; const proposalResult await daoProposalCreate({ chainId: tDVV, mode: simulate, args: { daoId, proposal: { title: Fund Hackathon Prize Pool, proposalType: Transfer, transferProposal: { to: RECIPIENT_ADDRESS, symbol: USDT, amount: 1000000000, // 100 USDT memo: Hackathon Q3 Prize } } } }); // 3. 定期查询我对此提案的状态例如在后台服务中 const myVoteInfo await daoProposalMyInfo({ chainId: tDVV, args: { daoId, proposalId: proposalResult.receipt?.proposalId, // 从创建结果获取 address: YOUR_WALLET_ADDRESS } }); console.log(我的投票信息:, myVoteInfo); } manageDAO().catch(console.error);SDK调用返回统一的ToolResultT类型其中包含status、data、receipt、error等字段便于进行统一的错误处理和结果解析。5. 常见问题、故障排查与进阶技巧5.1 错误代码与解决方案速查表在实际使用中你可能会遇到各种错误。以下是基于我个人踩坑经验整理的常见错误及排查思路错误信息 / 现象可能原因排查步骤与解决方案SIGNER_NOT_FOUND技能包无法找到有效的私钥进行签名。1. 检查.env文件中TMRW_PRIVATE_KEY等环境变量是否已正确设置且未过期。2. 如果使用Portkey CA钱包检查~/.portkey/skill-wallet/context.v1.json文件是否存在且包含有效的钱包上下文。3. 在CLI调用中尝试显式通过--input传入privateKey参数仅用于测试注意安全。SIGNER_CA_DIRECT_SEND_FORBIDDEN尝试使用合约账户直接发送交易。这是预期行为。CA账户的写操作必须通过其Manager账户进行Forward。你需要使用EOA账户操作或者通过Portkey SDK等工具完成CA的Forward流程。技能包本身不处理CA Forward。CHAIN_ID_NOT_SUPPORTED传入了不支持的chainId。目前只支持AELF和tDVV。确认你的操作是否在正确的链上DAO操作默认tDVV网络治理/BP/资源操作默认AELF。在调用时显式指定chainId参数。交易在simulate成功但send失败1. 账户资源不足。2. 交易过期。3. 链上状态在simulate后发生变化。1. 检查simulate返回的resourceFee确保账户有足够的CPU/NET/RAM和代币余额。2. 交易有一定有效期不要将simulate的结果搁置太久再send。3. 对于高度依赖链上状态的交易如基于特定价格的资源买卖simulate和send之间的时间差可能导致条件不再满足。MCP服务器启动失败或AI无法调用工具1. 端口冲突或命令路径错误。2. MCP配置未正确加载。3. 环境变量未传递给MCP子进程。1. 检查bun run src/mcp/server.ts是否能独立运行。2. 检查Claude Desktop或Cursor的MCP配置文件如claude_desktop_config.json确保command和args指向正确的绝对路径且env部分包含了必要的私钥等变量。3. 尝试在MCP服务器启动命令前直接设置环境变量例如TMRW_PRIVATE_KEYyour_key bun run src/mcp/server.ts。API请求超时 (HTTP_TIMEOUT)网络连接问题或RPC节点响应慢。1. 增加.env中的TMRW_HTTP_TIMEOUT_MS值例如设为30000。2. 检查TMRW_RPC_AELF和TMRW_RPC_TDVV配置的节点是否可用考虑切换到更稳定的节点。3. 启用重试机制设置TMRW_HTTP_RETRY_MAX3。5.2 性能优化与最佳实践连接池与缓存在长期运行的服务如集成了此SDK的后端服务中技能包内部会缓存aelf客户端实例。确保你的服务部署环境有足够的网络带宽并且关注TMRW_AELF_CACHE_MAX的设置。如果服务需要处理大量并发请求到不同链可能需要根据实际情况调整这个值。错误处理与重试逻辑在使用SDK时务必对每个调用进行完善的错误处理。除了检查ToolResult.status还要关注receipt中的详细错误信息。对于网络波动等可重试错误可以在业务逻辑层实现自己的重试机制尤其对于读操作。私钥安全管理重中之重绝不硬编码永远不要将私钥直接写在源代码里。环境变量与机密管理在本地开发中使用.env文件并加入.gitignore。在生产环境中使用Docker Secrets、Kubernetes Secrets、AWS Secrets Manager或类似的服务来管理环境变量。使用CA钱包对于更高安全级别的应用强烈建议使用Portkey的合约账户。虽然技能包不能直接以CA身份发送交易但你可以通过集成Portkey的Auth或SDK来管理CA的Forward操作将私钥管理的风险降到最低。测试策略项目提供了完善的测试套件。在贡献代码或深度定制前请充分利用bun run test:unit # 运行单元测试 bun run test:integration # 运行集成测试 RUN_TMRW_E2E1 bun run test:e2e # 运行真实的端到端测试只读调用公共API在编写自己的集成代码时也尽量为关键流程编写测试特别是涉及交易签名的部分可以使用simulate模式进行无风险测试。5.3 调试与日志当遇到复杂问题时开启详细日志是定位问题的关键。# 在启动命令前设置日志级别 TMRW_LOG_LEVELdebug bun run tomorrowdao_skill.ts dao ... # 或者直接修改.env文件 TMRW_LOG_LEVELdebugdebug级别会打印出详细的HTTP请求/响应、构造的交易参数、以及技能包内部的关键决策逻辑对于理解整个调用链路非常有帮助。这个技能包本质上是一个强大的“翻译器”和“执行器”它将自然语言或高级指令翻译成aelf区块链能理解的具体交易。它的稳定性和可靠性直接依赖于你对底层区块链操作如资源管理、交易构造和自身业务逻辑的理解。花时间熟悉每个技能的参数、返回值以及背后的合约原理是高效利用它的不二法门。从简单的查询开始逐步尝试模拟执行最后再进行真实的链上操作这条路径能帮你避开大多数新手会遇到的坑。