1. 项目概述构建自主、安全且可组合的Starknet智能体基础设施如果你正在探索如何让AI智能体Agent在Starknet区块链上自主、安全地执行任务比如自动进行DeFi交易、管理链上身份或审计智能合约那么你很可能已经遇到了一个核心难题如何将智能体的“大脑”与一个安全、可控且具备链上执行策略的“钱包”无缝结合。大多数现有的智能体框架只是把钱包当作一个简单的插件或外部服务这带来了巨大的安全隐患和操作限制。starknet-agentic这个开源项目正是为了解决这个问题而生。它不是一个简单的工具库而是一套完整的、将钱包、链上身份和执行策略视为一等公民的基础设施框架。简单来说starknet-agentic为开发者提供了在Starknet上构建“政策驱动型”自主智能体所需的一切。它包含智能合约、运行时集成包和可复用的技能模块使得智能体不仅能调用链上功能还能在链上拥有可验证的身份ERC-8004标准其每一次操作都受到预先定义好的策略如单次交易限额、可调用合约白名单的约束。这意味着你可以构建一个智能体让它帮你自动进行DCA美元成本平均法投资但你完全不用担心它会突然把全部资产转到一个可疑地址——因为链上的账户合约会直接拒绝这笔不符合策略的交易。这套框架非常适合两类人一是希望为现有AI智能体如在Claude Code、OpenClaw等环境中运行的智能体添加强大且安全的Starknet区块链能力的开发者二是希望从零开始构建一个真正去中心化、自主运行的链上AI应用的团队。无论你是想快速集成一个Cairo合约审计技能还是想设计一个复杂的多智能体DeFi策略集群starknet-agentic都提供了模块化的组件和清晰的路径。2. 核心设计理念为什么钱包和策略必须是“一等公民”在深入技术细节之前理解starknet-agentic的设计哲学至关重要。这决定了它与其他智能体框架的根本区别。2.1 传统智能体框架的局限性当前主流的AI智能体运行时如基于OpenAI API构建的框架通常遵循一个简单的模式智能体逻辑LLM工具调用在中心化服务器或本地运行当需要与区块链交互时它通过一个简单的SDK如ethers.js、starknet.js调用RPC而私钥往往以环境变量或配置文件的形式存在。这种模式有几个致命缺陷私钥暴露风险私钥直接存储在运行智能体的环境中一旦该环境被入侵所有资产面临风险。策略执行滞后任何执行策略如“单日转账不超过100U”都只能在智能体的应用层代码中实现。如果智能体逻辑出现bug或被恶意提示词注入Prompt Injection策略可能被绕过。身份模糊智能体的行为无法与一个持久的、可验证的链上身份绑定。它的每一次操作都是匿名的难以建立信誉或进行责任追溯。2.2 Starknet-agentic的解决方案链上策略执行边界starknet-agentic颠覆了上述模式其核心思想是将执行策略和身份验证下放到区块链层由智能合约来充当智能体的“安全守门人”。它通过一套精心设计的账户抽象合约来实现这一点。具体来说智能体专属账户合约每个智能体不再直接使用一个普通的EOA外部拥有账户私钥而是部署一个专属的智能合约账户。这个合约账户的拥有者Owner是你用户而智能体运行时则持有一个或多个由该账户合约授权的“会话密钥”。会话密钥与策略会话密钥的权限是受限的。你在部署账户合约时可以定义精细的策略例如这个会话密钥只能向地址A、B、C发送代币单笔交易价值不得超过X每天累计交易额不得超过Y只能调用特定的DeFi合约等。链上强制执行当智能体使用会话密钥发起交易时交易会先提交到其所属的账户合约。账户合约的__validate__和__execute__函数会首先校验该交易是否符合预设策略。只有完全符合策略的交易才会被签名并广播到网络。策略的校验是在Starknet虚拟机中完成的具有确定性和不可篡改性。ERC-8004链上身份除了资产控制智能体还可以在链上注册一个符合ERC-8004标准的身份标识。这个标识可以关联信誉分数、能力声明Capabilities和验证记录。其他合约或智能体可以通过查询这个身份来决定是否与之交互实现了链上可信协作的基础。这种架构带来了几个关键优势安全即使智能体运行时的服务器被完全攻破攻击者也只能在预设的策略范围内进行操作无法转移核心资产或进行破坏性操作。确定性与合规所有策略公开透明且在链上强制执行为自动化金融操作提供了可审计的合规基础。可组合性具备链上身份的智能体可以像DeFi乐高一样被其他合约或智能体发现和调用开启真正的多智能体协作经济。3. 核心组件深度解析与实操要点starknet-agentic项目结构清晰模块化程度高。理解每个组件的职责是正确使用和扩展它的前提。3.1 合约层安全的基石合约位于contracts/目录下是整个系统的安全核心全部用Cairo编写。agent-account(智能体账户合约)这是最重要的合约。它实现了支持会话密钥的账户抽象逻辑。你可以把它理解为一个多签钱包的升级版但权限管理更加灵活。其核心函数包括添加/移除会话密钥、更新会话密钥策略、执行交易等。在部署时你需要初始化一个主管理员密钥通常由用户自己冷存储保管然后由这个管理员来授权给智能体运行时使用的会话密钥。注意会话密钥的私钥仍然需要被智能体运行时访问。为了生产环境安全starknet-agentic强烈建议使用“代理签名者”模式即会话密钥的签名操作在一个隔离的安全服务如HSM或特制硬件中完成而不是在运行智能体应用的同一进程中。erc8004-cairo(链上身份注册表)这是ERC-8004标准的Starknet实现。它包含三个核心注册表身份注册表记录智能体的唯一标识符通常是账户合约地址和元数据名称、描述、链接。信誉注册表允许其他实体可以是合约或链下预言机为某个身份提交信誉评分。例如一个DeFi协议可以在智能体成功完成一次无损套利后为其增加“盈利能力”信誉分。验证注册表用于记录对某个身份或声明的验证结果。例如一个“KYC提供商”合约可以验证某个智能体背后关联的实体是否通过了合规检查。 这套系统为“去中心化信誉”和“可验证声明”提供了底层基础设施是构建复杂协作生态的关键。session-account(会话账户原语)提供了一些更低级别的模块用于构建自定义策略的账户合约。如果你对agent-account的默认策略模型不满意例如想实现基于时间的策略、基于预言机价格的策略可以基于这里的模块进行二次开发。3.2 运行时集成层MCP与A2A桥梁为了让智能体运行时能方便地调用上述合约功能项目提供了packages/下的集成包。starknet-mcp-server(MCP服务器)这是最常用的集成方式。MCPModel Context Protocol是Anthropic提出的一个协议用于标准化AI模型与外部工具之间的通信。这个包实现了一个MCP服务器将Starknet的各种操作查询余额、发送交易、与DeFi协议交互等暴露为一系列工具Tools。你的智能体运行时如Claude Code、OpenClaw只需连接这个MCP服务器就能像调用普通函数一样进行链上操作无需关心底层的RPC调用和交易构造细节。实操要点在开发环境中MCP服务器可以配置为直接使用会话密钥的私钥进行签名。但在生产环境务必通过环境变量或配置项启用proxy_signer_url将签名请求转发到你部署的代理签名服务确保私钥不泄露。starknet-a2a(A2A适配器)A2AAgent-to-Agent协议专注于智能体间的通信与工作流编排。这个包提供了将Starknet能力和事件接入A2A工作流的能力。例如你可以设置一个监控特定合约事件的智能体当事件触发时通过A2A协议通知另一个负责交易的智能体执行操作。create-starknet-agent(脚手架工具)这是最快的入门方式。运行npx create-starknet-agentlatest会启动一个交互式命令行工具自动检测你当前使用的智能体开发环境如Claude Code、Cursor等并为你初始化一个预配置好的项目包含了必要的依赖、MCP服务器配置示例和基础技能。3.3 技能库开箱即用的能力模块skills/目录下存放着“技能包”。一个技能就是一组预定义好的、用于完成特定任务的工具集合和提示词模板。它们是构建功能型智能体的高效积木。cairo-auditor(Cairo合约审计技能)这是一个非常实用的技能。它允许智能体如Claude对Cairo智能合约代码进行安全检查。你只需将合约代码或文件路径提供给智能体它就能调用这个技能来分析潜在的重入漏洞、整数溢出、访问控制缺陷等。其亮点在于集成了“确定性预检”和“误报过滤”能提供更精准的报告。安装与使用在Claude Code中你可以通过/plugin marketplace add keep-starknet-strange/starknet-agentic添加市场然后安装starknet-agentic-skills插件来获取所有技能。之后在聊天中直接输入/starknet-agentic-skills:cairo-auditor并附上合约代码即可。starknet-wallet(钱包操作技能)提供了基础的链上操作能力如查询余额、发送STRK或ETH转账、管理会话密钥、与付费主Paymaster交互以使用ERC-20代币支付Gas费等。starknet-defi(去中心化金融技能)封装了与Starknet上主流DeFi协议如JediSwap、10kSwap、AVNU聚合器交互的逻辑。智能体可以利用这个技能执行代币兑换、限价单、提供流动性等复杂操作。内部通常集成了价格滑点保护、最优路径计算等逻辑。starknet-identity(链上身份技能)专门用于管理ERC-8004身份包括注册身份、更新元数据、查询信誉分数、发起或响应验证请求等。每个技能都独立封装可以通过npx skills add命令单独安装到兼容的智能体运行时中。技能的设计遵循“单一职责”原则方便组合使用。例如一个DeFi套利智能体可能会同时调用starknet-defi和starknet-wallet技能。4. 从零开始的完整实操流程构建一个自主DeFi智能体理论讲完了我们动手搭建一个实际的智能体。假设我们的目标是构建一个在Starknet测试网Sepolia上运行的智能体它能够监控两个DEX间的价格差并在有利可图时自动执行套利交易同时所有交易受到严格的链上策略限制。4.1 第一步环境准备与项目初始化首先确保你的开发环境符合要求。你需要Node.js18和pnpm。然后使用脚手架快速创建项目。# 使用脚手架创建项目它会自动适配你的开发环境 npx create-starknet-agentlatest my-arbitrage-agent cd my-arbitrage-agent脚手架会询问几个问题例如智能体运行时选择你使用的平台例如Claude Code。目标网络选择Starknet Sepolia测试网。是否初始化示例技能选择Yes并勾选starknet-defi和starknet-wallet。是否设置链上策略选择Yes并设置一个简单的策略例如“单笔交易价值不超过10 STRK”。完成问答后脚手架会生成一个项目结构大致如下my-arbitrage-agent/ ├── .env.example # 环境变量示例文件 ├── package.json # 项目依赖 ├── mcp-server.config.js # MCP服务器配置文件 ├── agent/ # 智能体主逻辑目录可能包含提示词、工作流定义 └── skills/ # 本地技能目录链接或复制了所选技能接下来复制环境变量文件并填写你的配置cp .env.example .env编辑.env文件填入关键信息# 网络配置 STARKNET_RPC_URLhttps://starknet-sepolia.infura.io/v3/YOUR_INFURA_KEY STARKNET_CHAIN_IDSN_SEPOLIA # 智能体账户配置后续部署后填写 AGENT_ACCOUNT_ADDRESS AGENT_ACCOUNT_SESSION_PRIVATE_KEY # 代理签名者URL生产环境使用开发可暂留空 PROXY_SIGNER_URL # 付费主合约地址可选用于ERC-20支付Gas STARKNET_PAYMASTER_ADDRESS4.2 第二步部署智能体账户合约并配置策略这是最关键的安全步骤。我们需要在链上部署一个属于该智能体的账户合约并为其配置会话密钥和策略。项目通常提供了一个部署脚本。查看生成的scripts/目录或package.json中的脚本命令。假设有一个deploy-agent-account脚本。准备部署者私钥你需要一个拥有测试网ETH用于支付Gas的账户私钥。将其导出为环境变量仅用于临时部署切勿提交。export DEPLOYER_PRIVATE_KEY0x你的部署者私钥运行部署脚本pnpm run deploy-agent-account脚本会执行以下操作使用部署者账户发起交易部署一个新的智能体账户合约。将你或一个管理多签设置为主管理员Owner。生成一对新的会话密钥公钥和私钥并将其添加到账户合约中同时附带上一步在脚手架中定义的策略如交易限额。输出部署结果包括AGENT_ACCOUNT_ADDRESS和AGENT_ACCOUNT_SESSION_PRIVATE_KEY。更新环境变量将脚本输出的地址和会话私钥填入.env文件的对应位置。重要安全警告AGENT_ACCOUNT_SESSION_PRIVATE_KEY是智能体运行时用来签名的密钥。在本地开发中我们可以将其放在.env中但必须确保.env文件不被上传至Git。在生产环境中绝对不要将此私钥放在应用环境中。必须使用前面提到的代理签名者模式将PROXY_SIGNER_URL指向一个安全的签名服务并从.env中移除私钥。为账户充值向新部署的AGENT_ACCOUNT_ADDRESS转入少量测试网STRK或ETH作为智能体未来的交易Gas费和操作资金。4.3 第三步开发智能体逻辑与集成MCP服务器现在智能体的“安全钱包”已经就绪。接下来是开发其“大脑”——决策逻辑。启动MCP服务器在项目根目录下运行MCP服务器。它会读取.env配置并将会话密钥和策略封装成安全的工具接口。pnpm run start-mcp-server服务器启动后会输出一个连接地址如ws://localhost:3000或Stdio通信配置。你的智能体运行时需要连接到这里。在Claude Code中连接以Claude Code为例在Claude Code中打开设置找到“MCP服务器”或“工具连接”配置。添加一个新的服务器连接类型选择stdio或sse根据mcp-server.config.js的配置。命令填写为node参数填写为path/to/your/project/mcp-server.config.js的绝对路径。保存后Claude Code会重启并连接到你的MCP服务器。连接成功后你可以在聊天中尝试让Claude调用工具例如“查询我的智能体账户余额”。编写套利策略逻辑智能体的核心逻辑可以用自然语言描述在提示词Prompt中也可以结合更结构化的编程。在agent/目录下你可以创建一个工作流文件例如arbitrage_workflow.json或提示词文件。核心逻辑伪代码提示词你是一个DeFi套利智能体连接了我的Starknet MCP工具。你的任务是 1. 每5分钟监控一次JediSwap和10kSwap上STRK/ETH交易对的价格。 2. 计算价格差异率。如果发现10kSwap上的STRK价格比JediSwap低超过0.5%则执行以下套利 a. 使用starknet-defi技能的swap工具在10kSwap上用X个ETH购买STRK。X由账户可用资金和策略决定例如不超过资金的20% b. 等待第一笔交易确认后立即使用swap工具在JediSwap上将刚买到的STRK全部卖出换回ETH。 3. 每次执行前后记录利润估算。如果单次预估利润低于Gas成本则放弃交易。 4. 所有操作必须通过我的MCP工具进行不得自行构造交易。 我的智能体账户地址是{{AGENT_ACCOUNT_ADDRESS}}。请开始执行监控。将这个提示词提供给Claude它就会开始利用MCP工具自动执行监控和交易。由于底层交易需要经过账户合约的策略校验如单笔交易限额所以即使提示词被恶意修改为“转走所有资金”链上合约也会拒绝该非法交易。4.4 第四步测试与运行本地测试在测试网环境下先用极小的金额如0.001 STRK运行智能体观察其日志和链上交易确保逻辑正确策略生效。监控与日志确保MCP服务器和智能体运行时都有完善的日志输出记录每笔交易的哈希、状态和利润计算结果。策略调优根据测试结果你可能需要调整链上策略如提高限额或优化智能体的决策参数如价差阈值、资金分配比例。调整策略需要主管理员发起合约交易来更新会话密钥的权限。5. 进阶架构多智能体协作与生产环境部署当你掌握了单个智能体的构建后可以探索更复杂的架构starknet-agentic的示例库提供了很好的蓝图。5.1 多智能体Swarm示例 (full-stack-swarm)这个示例展示了如何协调多个具有不同专长的智能体共同工作。例如侦察员智能体负责监控链上事件和价格数据发现机会后通过A2A协议发布“任务”。执行员智能体订阅特定类型的任务如套利、清算接收到任务后使用自己的专属账户和策略去执行。审计员智能体在执行员提交交易前对交易进行模拟和审查通过A2A协议反馈风险提示。这种架构的关键在于A2A协议作为智能体间的通信总线。ERC-8004身份每个智能体都有身份和信誉。执行员智能体可能需要一定的“可靠性”信誉分才能接收高价值任务。独立的账户与策略每个智能体有独立的账户合约策略各不相同。侦察员可能只有查询权限而执行员拥有受限的交易权限。5.2 生产环境安全部署要点将实验性的智能体推向生产环境必须高度重视安全。必须使用代理签名者绝不在应用程序进程内存放会话私钥。部署一个独立的签名服务可以使用packages/starknet-mcp-server中提供的代理模式参考实现该服务运行在高度安全的环境中如硬件安全模块HSM、机密计算环境。MCP服务器配置proxy_signer_url指向该服务。签名服务只做一件事验证请求来源然后用其安全存储的私钥签名。精细化策略设计生产环境的策略应极其保守。考虑以下维度支出限额单笔、每日、每周。合约白名单只允许与经过严格审计的知名协议如JediSwap, Nostra交互。时间锁对于重大操作如更改策略、更换会话密钥设置24小时的时间锁给管理员应急反应时间。紧急暂停在账户合约中实现一个由主管理员触发的紧急暂停开关。监控与告警建立链下监控监听智能体账户的所有交易。对异常交易如超出常规金额、调用陌生合约实时告警。渐进式部署先在小额、隔离的环境中长时间运行观察其行为稳定性再逐步增加资金和权限。6. 常见问题与排查技巧实录在实际开发和运行中你肯定会遇到各种问题。以下是我在实践过程中总结的一些典型问题和解决方法。6.1 MCP服务器连接失败症状智能体运行时如Claude Code提示无法连接到MCP服务器或工具列表为空。排查步骤检查服务器进程首先确认pnpm run start-mcp-server是否成功运行并无报错退出。查看服务器日志确认它正在监听指定端口或已准备好Stdio通信。检查连接配置在Claude Code的设置中仔细核对MCP服务器的连接配置。如果是Stdio模式确保“命令”和“参数”的路径完全正确。可以尝试在终端手动运行配置中的命令看是否能启动服务器。检查环境变量确保.env文件中的STARKNET_RPC_URL有效且网络可达。可以尝试用curl或starknet.js手动调用一下RPC。检查私钥格式确保AGENT_ACCOUNT_SESSION_PRIVATE_KEY是有效的十六进制字符串以0x开头。一个常见错误是复制了助记词而非私钥。6.2 交易被账户合约拒绝症状智能体发起交易后交易在钱包账户合约层面被拒绝错误信息可能包含Transaction execution reverted或Error in the called contract。排查步骤查询会话密钥策略使用Starkscan或类似区块浏览器调用你的智能体账户合约的get_session_key_policy视图函数传入会话密钥的公钥。检查返回的策略是否允许你正在尝试的操作目标合约、代币、金额上限。模拟交易在发送真实交易前先使用starknet.js的account.estimateFee或account.simulateTransaction方法进行模拟。模拟失败的错误信息通常会更清晰地指出违反了什么策略。检查Nonce确保智能体正确地获取和使用了当前账户的Nonce。如果多个进程共用同一个会话密钥可能导致Nonce冲突。建议在MCP服务器层实现一个简单的Nonce管理锁。检查付费主如果使用了付费主Paymaster用ERC-20代币支付Gas请确保付费主合约已批准足够的代币额度给账户合约且付费主服务运行正常。6.3 智能体逻辑“失控”或做出非预期行为症状智能体没有按预期执行套利或者做出了明显不合理的交易决策。排查步骤审查提示词这是最常见的原因。检查你的提示词是否足够清晰、无歧义。是否明确限制了操作条件价差X%和资金用量不超过Y%。尝试在提示词中加入“逐步思考”的指令让智能体输出其推理过程。检查工具输出解析智能体依赖于MCP工具返回的数据如价格。确认工具返回的数据格式是智能体能够正确解析的。有时价格查询可能返回多个路径智能体可能错误地选择了第一个。可以在工具描述或提示词中指定更精确的数据解析方式。引入“二次确认”步骤对于高价值操作不要让它完全自主执行。修改工作流在最终交易发送前增加一个“人工确认”或“模拟报告”步骤。让智能体先输出它计划执行的交易详情和预期结果经过程序化或人工检查后再放行。启用详细日志在MCP服务器和智能体逻辑中增加详细日志记录每一个决策点的输入获取到的价格和输出决定的操作。这有助于事后复盘问题根源。6.4 性能与延迟问题症状套利机会转瞬即逝但智能体从发现到执行完成耗时过长错过机会。优化方向RPC节点选择使用低延迟、高可用性的私人RPC节点而非免费的公共节点。Infura、Alchemy等提供商通常有更优的性能。并行化与异步监控价格和发送交易可以使用异步并行处理。例如使用Promise.all同时查询多个DEX的价格。本地缓存与预测对于Gas价格、基础代币价格等相对变化较慢的数据可以进行短期缓存减少不必要的RPC调用。交易模拟优化simulateTransaction调用本身有开销。对于高度重复的交易模式如相同的交易路径可以缓存模拟结果或在策略允许的情况下对小额交易跳过模拟接受一定的失败风险。调整监控频率权衡监控频率与RPC调用成本、机会捕获率之间的关系。对于高频套利可能需要订阅链上事件流如WebSocket而非轮询。构建一个健壮的链上自主智能体是一个持续迭代的过程。starknet-agentic提供了强大的基础设施将最复杂的安全和策略问题抽象化让你能更专注于智能体本身的策略逻辑。从一个小型的、策略严格的测试网智能体开始逐步积累经验和信心是通向成功最稳妥的路径。记住在区块链世界代码即法律而starknet-agentic帮助你为你的智能体编写了第一套也是最关键的一套法律。