Marico's space

最近折腾 AI 编程助手调试 Solidity 回滚交易、编写 Foundry 不变量测试，发现这套路子基本都会翻车：

1. 把错误信息或者原始交易哈希丢给 AI。
2. AI 先道歉，然后瞎猜三种可能原因，顺手建议重写一个本来没问题的辅助合约。
3. 如果让它生成不变量测试，它要么造一个脱离链上存储的"无状态"属性断言，要么搞个幽灵变量，测试通过但根本没碰真实合约状态。

问题不在于现在的 LLM（大型语言模型）不懂 Solidity。问题在于通用编程助手缺少一套可重复的、证据优先的 Web3 系统工作流。

在 Web3 领域，一个错误的建议不只是构建失败的语法错误。它可能意味着未处理的链重组、未授权的外部调用，或者配错的滑点参数。

为了解决这个问题，我们梳理并开源了 Spellbook Skills：五个可测试、确定性的工作流包，专为 Claude Code、Cursor 这类 AI 编程助手设计。

这篇说清楚 AI 编程助手为什么在 EVM（以太坊虚拟机）任务上翻车，结构化 Skills 怎么改变它的行为，以及怎么现在就能装上。

核心问题：没有证据的推理

人类智能合约工程师调查回滚时，会遵循一套系统性流程：

获取交易回执 → 解码自定义错误选择器 → 通过 `cast run` 拉取调用栈 → 检查存储槽/状态 → 形成假设 → 写可复现的测试

当一个没有引导的 AI 代理试图做同样的任务时，它直接从原始错误跳到提议代码修改。它依赖对训练数据的模式匹配，而不是验证链上的实际状态。

要让 AI 代理可靠运行，你不需要更大的提示词。你需要用四个操作边界来约束 AI：

1. 结论先于证据：AI 必须在建议代码修改之前先拉取回滚原因或 cast run 调用栈。
2. 严格角色分离：搭建测试和验证漏洞是两件不同的事。
3. 零秘密处理：AI 绝对不能询问、记录或接受私钥、助记词或实时签名者凭证。
4. 默认拒绝执行：任何链上操作或交易提案必须通过明确的策略门才能执行。

我们打包的 5 个 Skills

我们没有构建一个"全功能 Web3 AI"的庞然大物，而是做了五个专注的 Skills。每个 Skill 包含 SKILL.md 操作规范、参考检查清单、测试固件和可运行的辅助脚本。

1. evm-tx-failure-diagnoser

针对问题：神秘回滚、自定义错误选择器、gas 耗尽、nonce 冲突。

工作流：它阻止 AI 瞎猜。强制 AI 先解码 4 字节错误选择器，通过 cast run <TX_HASH> 或本地 RPC 获取调用栈，隔离失败的调用帧，在碰合约文件之前先记录根本原因。

2. foundry-invariant-scaffold

针对问题：脆弱的单元测试，漏掉边缘情况的多步骤攻击。

工作流：引导 AI 完成 Foundry 中真正的有状态模糊测试。搭建专用的 handler 合约、定义 actor 代理、用现实的幽灵变量约束输入，构建跨调用序列检查系统级不变量的断言结构。

3. web3-agent-tx-safety

针对问题：自主 AI 代理提议或广播交易。

工作流：实现严格的、默认拒绝的交易策略门。每个交易载荷必须通过参数边界（目标白名单、最大值、calldata 选择器检查）和模拟干跑，才能构建任何签名载荷。

4. slither-finding-verifier

针对问题：静态分析分类疲劳和误报。

工作流：接收原始 Slither JSON 输出并规范化为分类工作表。它要求 AI 在生成针对性的、可复现的测试用例之前，先对照实际源代码 AST 验证发现结果，确认漏洞是否可利用还是误报。

5. rpc-event-reliability

针对问题：事件监听器在网络拥堵或链重组期间丢失日志。

工作流：强化日志摄入后端。构建持久的事件去重键（chain + blockHash + txHash + logIndex），配置 Viem 后备传输，构建能优雅处理链重组的重组协调例程。

如何安装和使用

五个 Skills 都在 MIT 协议下开源。

如果你使用 skills CLI，可以直接把任意 Skill 安装到 AI 的工作区：

# 安装 EVM 诊断器到 Claude Code
npx skills add theweb3wizard/spellbook-skills --skill evm-tx-failure-diagnoser -a claude-code # 安装 Foundry 不变量脚手架
npx skills add theweb3wizard/spellbook-skills --skill foundry-invariant-scaffold -a claude-code # 或者一次性安装全部 5 个 Skills
npx skills add theweb3wizard/spellbook-skills --skill '*' -a claude-code

手动安装

你也可以克隆仓库，把 Skill 目录直接丢进工作区：

• Claude Code：.claude/skills/<skill-name>/
• Cursor / Codex：.agents/skills/<skill-name>/

git clone https://github.com/theweb3wizard/spellbook-skills.git

示例：有防护的 AI 运行长什么样

当你用 evm-tx-failure-diagnoser 装备 AI 后，提示它会得到这样的结果：

提示词：

"我们的存款交易在 Base 上回滚了：0x7a8b...3f1c。找出原因，告诉我需要修什么。"

没有 Skill 时：
AI 通常瞎猜："看起来你没有先授权 ERC20 代币，或者合约被暂停了。"

有 Skill 时：
AI 执行诊断工作流：

1. 查询交易回执，提取回滚数据：0x118cdaa7。
2. 对着项目 ABI 解码选择器：InsufficientCollateral(uint256 current, uint256 required)。
3. 注明所需抵押门槛是用比协议容忍延迟（maxOracleDelay = 3600）更旧的价格预言机时间戳计算的。
4. 输出基于证据的分诊报告，并建议一个回归测试固件，而不是盲目修改合约代码。

开源与社区反馈

这些 Skills 是我们在 Spellbook 工作的一部分，我们为 Web3 协议设计和部署生产级 AI 代理。

Skills 完全免费，可离线测试。你可以在这里查看完整代码、测试套件和工作流：

• 🐙 GitHub 仓库：github.com/theweb3wizard/spellbook-skills
• 📖 交互式 Skills 目录：spellbook.theweb3wizard.xyz/skills

如果你在智能合约项目中测试了这些 Skills，在评论区留下反应或者告诉我你的 AI 代理在其他哪些常见 Web3 工作流上还翻车！