grimoire

Grimoire CLI 技能

此技能是 Grimoire 的基础操作手册。

适用场景

在任务涉及以下内容时使用此技能：

• 安装/设置 Grimoire 工具
• 创建或编辑 .spell 文件
• 询问 DSL 功能的语法问题
• 撰写、调试和重放 advisory (advise) 工作流
• 设置/编译/验证/模拟/施放/恢复工作流
• 调试 spell 编译/运行时故障

必须遵守的加载规则

以下所有 references/ 和 docs/ 路径均相对于此技能目录（skills/grimoire/）。这些规则必须遵守——它们用于弥补语法覆盖缺口，以免编写内容时出错。

**停止——请先阅读此处：**不要搜索代码库、grep 语法模式，也不要依赖记忆编写 DSL 语法。此技能附带的参考文件是唯一可信来源。在编写或编辑任何 spell 内容之前，立即使用 Read 工具读取以下文件。

1. 对于任何 .spell 编写/编辑任务——在进行其他操作之前，立即使用 Read 工具读取以下文件：
   • references/syntax-capabilities.md
   • references/authoring-workflow.md
2. 对于 CLI 标志详情——立即使用 Read 工具读取：
   • references/cli-quick-reference.md
3. 对于任何 advisory 任务（advise、advisors、重放）——立即使用 Read 工具读取：
   • docs/how-to/use-advisory-decisions.md
   • docs/explanation/advisory-decision-flow.md
4. 对于本地 fork 预览工作流——立即使用 Read 工具读取：
   • references/anvil-cheatsheet.md
   • docs/how-to/simulate-on-anvil-fork.md
5. 对于钱包设置和执行密钥工作流——立即使用 Read 工具读取：
   • docs/how-to/use-wallet-commands-end-to-end.md
6. 对于 RPC/签名者/交易诊断——立即使用 Read 工具读取：
   • references/cast-cheatsheet.md

安装方式判定

选择第一个可用的调用方式，并在整个会话中继续使用。

1. 全局安装：
   • npm i -g @grimoirelabs/cli
   • 命令前缀：grimoire
2. 无需安装：
   • 命令前缀：npx -y @grimoirelabs/cli
3. 仓库本地：
   • 命令前缀：bun run packages/cli/src/index.ts --

如果一种方式失败，则自动尝试下一种方式。

如果 grimoire venue doctor ... 因 Unknown venue adapter "doctor" 而失败，优先使用仓库本地调用方式（bun run packages/cli/src/index.ts），或升级全局 CLI。

使用仓库本地 Bun 执行时，务必保留末尾的 --，以便 Bun 将标志传递给 Grimoire，而不是自行处理。

快速开始（立即成功路径）

编写自定义 spell 之前，按顺序执行：

1. <grimoire-cmd> --help
2. <grimoire-cmd> setup（引导式交互执行设置）
3. <grimoire-cmd> validate spells/compute-only.spell
4. <grimoire-cmd> simulate spells/compute-only.spell --chain 1

如果以上四项全部通过，即可开始编写 spell。

设置过程中的安全性/运行时预期：

• setup 会提示输入隐藏密码，且绝不会回显输入内容
• RPC 输入留空时，将回退到链的默认公共 RPC
• 除非使用 --no-save-password-env，否则 setup 可能会写入 .grimoire/setup.env
• CLI 启动时会自动加载最近的 .grimoire/setup.env，且不会覆盖现有环境变量

编写和执行策略

1. 首先阅读语法参考（上文的强制规则）。
2. 编写或更新 spell。
3. 验证前运行 format，规范化布局。
4. 运行 validate（对于建议较多的 spell，使用 --strict）。
5. 修复错误和警告，然后重新运行，直到验证通过。
6. 运行 simulate。
7. 在查询场地元数据或执行涉及资金变动的运行之前，针对目标适配器/链执行 venue doctor。
   • 示例：<grimoire-cmd> venue doctor --adapter uniswap --chain 1 --rpc-url <rpc> --json
8. 在 EVM 场地执行涉及资金变动的运行之前，使用 Foundry Cast 快速检查（chain-id、block-number、balance、nonce）验证端点和签名者状态。
   • 不要对 hyperliquid 等链下场地执行 Anvil/Cast 检查。
9. 对于旨在确定性执行的建议步骤，记录运行 ID，然后在 dry-run/live cast 中使用 --advisory-replay <runId>。
10. 如果 spell 包含不可逆操作，则必须先执行 cast --dry-run，然后才能执行任何 live cast。
11. 执行涉及资金变动的 live cast 前，必须征求用户的明确确认。
12. 对于跨链模式，必须明确指定每条链的 RPC 映射：

• --rpc-url <sourceChainId>=<url>
• --rpc-url <destinationChainId>=<url>

13. 对于跨链 Morpho 操作，必须通过以下方式明确指定市场映射：

• --morpho-market-id <actionRef>=<marketId>（可重复），或
• --morpho-market-map <path>

14. 对于仅供给的 Morpho 策略，优先使用 vault_deposit / vault_withdraw（明确指定金库地址）。

• 如果缺少金库地址，请列出候选金库并要求用户选择；绝不自动选择。

15. 对于 Morpho 市场策略（借款/抵押/借出），必须明确指定 market_id 并使用明确的操作：

• morpho_blue.supply_collateral(asset, amount, market_id)
• morpho_blue.withdraw_collateral(asset, amount, market_id)

16. 在操作的 token 字段中使用裸 0x... 地址字面量；带引号的类似地址字符串会触发 QUOTED_ADDRESS_LITERAL。
17. 对于 Morpho doctor 就绪检查，请明确设置钱包环境变量（优先使用 GRIMOIRE_WALLET_ADDRESS，备用为 WALLET_ADDRESS）。
18. 如果跨链运行处于等待状态，请使用 resume <runId> 继续（使用 --watch 轮询结算状态）。
19. 切勿将密码/私钥放入 Agent 提示词或内联命令赋值中。
20. 对于 dry-run/live cast，优先使用 keystore + --password-env，而不是 --private-key。
21. 将 .grimoire/setup.env 视为明文机密材料：仅保存在本地，并在不再需要时轮换或移除。
22. 在项目目录树之外运行命令时，如有需要，请设置 GRIMOIRE_SETUP_ENV_FILE=/abs/path/to/.grimoire/setup.env。

命令概览（核心）

• init
• setup
• format
• compile
• compile-all
• validate
• triggers
• simulate
• cast
• venues
• venue
• venue doctor
• history
• log
• resume
• wallet（generate、address、balance、import、wrap、unwrap）

请使用 references/cli-quick-reference.md 查阅简明的命令签名和关键安全标志。

运行时行为模型

• 统一的运行时语义：先预览，仅在执行路径中提交。
• simulate 和 cast --dry-run 仅用于预览。
• 在策略和运行时检查通过后，live cast 可以提交不可逆操作。
• simulate 支持显式使用 --rpc-url，优先级为：--rpc-url -> RPC_URL_<chainId> -> RPC_URL。
• 第 1 阶段的跨链执行使用双 spell 编排（--destination-spell），共享一个逻辑运行 ID，并支持恢复执行。
• 使用 triggers <spell> 原生发现稳定的处理器 ID，然后再执行指定目标。
• simulate 和 cast 支持通过 --trigger-id、--trigger-index 和旧版 --trigger 执行选定的触发器。
• 对于包含多个处理器的 spell，优先使用 --trigger-id；--trigger 基于标签，可能存在歧义。
• 跨链 simulate / cast 必须将同一选定触发器传递给每条链的执行。
• 在 --json 模式下，仅解析 stdout；stderr 中仍可能出现进度和加载动画输出。

查询函数（price / balance / apy / metric）

获取结构化数据时，始终优先使用查询函数，而不是 advisory。 这些函数具有确定性、速度快，且不需要调用大模型。

• price(BASE, QUOTE[, SOURCE]) — 通过查询提供方获取实时代币价格（需要 Alchemy RPC URL）
• balance(ASSET[, ADDRESS]) — 通过 RPC 查询链上代币余额（任意 RPC URL）
• apy(VENUE, ASSET[, SELECTOR]) — 由场所提供的 APY 查询接口（例如 Aave 和 Morpho）
• metric(SURFACE, VENUE[, ASSET[, SELECTOR]]) — 通用协议指标查询接口
• 选择器使用指南：
• 市场 / 金库 ID 选择器：apy(morpho, USDC, "wbtc-usdc-86")
• 金库选择器（Morpho）：metric("vault_net_apy", morpho, USDC, "vault=0xVaultAddress")
• Morpho 的 vault_apy / vault_net_apy 需要显式选择器；不要依赖隐式默认值。
• 键值选择器：metric("quote_out", uni_v3, USDC, "asset_out=WETH,amount=1000000,fee_tier=3000")
• 切勿仅为获取价格、余额、APY 或其他结构化指标而使用 advisory（advise）

仅当任务需要大模型判断、推理或解读时才使用 advisory。

Advisory 操作规则

• Advisory 必须采用显式语句形式：x = advise advisor: "prompt" { ... }。
• 将 advisory 输出视为类型化契约；使用 output 强制执行架构。
• 每个 advisory 块都必须包含 timeout 和 fallback。
• 当 advisory 逻辑会影响资金转移操作时，优先使用 validate --strict。
• 从预览 / dry-run 转为实时执行时，使用 replay 确保确定性。
• 调试运行时问题时，使用 --advisory-trace-verbose（非 JSON 模式）流式输出详细的 advisory 跟踪信息。

场所元数据和快照

使用场所技能获取快照参数和市场元数据：

• grimoire-aave
• grimoire-uniswap
• grimoire-morpho-blue
• grimoire-hyperliquid
• grimoire-pendle
• grimoire-polymarket

场所 CLI 输出格式策略：

• 自动化处理或嵌套负载时，优先使用 --format json
• 面向用户的摘要使用 --format table

参考资料

• references/syntax-capabilities.md
• references/authoring-workflow.md
• references/anvil-cheatsheet.md
• references/cast-cheatsheet.md
• references/cli-quick-reference.md
• docs/how-to/simulate-on-anvil-fork.md
• docs/how-to/use-wallet-commands-end-to-end.md
• docs/how-to/use-advisory-decisions.md
• docs/how-to/compare-protocol-metrics.md
• docs/explanation/advisory-decision-flow.md
• docs/reference/cli.md
• docs/reference/spell-syntax.md
• docs/reference/grimoire-dsl-spec.md
• docs/reference/compiler-runtime.md