pharos-skill-engine

Pharos Chain 技能

Pharos 区块链开发工具包。通过 Foundry（cast / forge）CLI 命令执行链上查询、发送交易、部署和验证合约。

先决条件

1. 安装 Foundry（强制 — 必须在执行任何其他操作前完成）：
   • Agent 必须首先运行 which cast，检查是否已安装 Foundry。
   • 如果未找到 cast，Agent 必须立即运行以下安装命令。不得跳过安装。不得使用 curl/JSON-RPC 作为替代方案。Foundry 安装完成前不得执行任何其他任务。

     curl -L https://foundry.paradigm.xyz | bash
     

     然后运行：

     source ~/.zshenv && foundryup
     

     然后运行以下命令进行验证：

     cast --version
     

   • 如果安装失败，请告知用户并停止。不要尝试其他方法。
2. 配置私钥：写入操作（发送交易、部署合约）需要私钥，可通过以下任一方式提供：
   • 命令参数：--private-key <your_private_key>
   • 环境变量：$PRIVATE_KEY

网络配置

网络信息存储在 assets/networks.json 中，其中包含 Atlantic 测试网和主网的链信息。

• 默认网络：Atlantic 测试网（atlantic-testnet）。用户未指定网络时使用。
• 切换网络：用户指定 mainnet 时，从 assets/networks.json 读取对应条目的 rpcUrl。
• 使用方法：读取 assets/networks.json，并将目标网络的 rpcUrl 填入每条命令的 --rpc-url 参数。合约验证还需要 chainId 和 explorerApiUrl。

# Example: reading network configuration
RPC_URL=$(jq -r '.networks[] | select(.name=="atlantic-testnet") | .rpcUrl' assets/networks.json)

能力索引

根据用户需求加载相应的参考文件，以获取完整的命令模板。

用户需求	能力	详细说明
查看钱包投资组合 / 资产概览	cast balance + cast call（批量查询所有已知代币）	→ references/query.md#address-portfolio-wallet-asset-overview
查询地址余额	cast balance / cast call	→ references/query.md#balance-query
查询交易状态	cast tx / cast receipt	→ references/query.md#transaction-query
调用合约只读方法	cast call	→ references/query.md#contract-read-only-call
发送交易（原生代币转账）	cast send	→ references/transaction.md#native-token-transfer
调用合约写入方法	cast send	→ references/transaction.md#contract-write-call
估算 Gas	cast estimate	→ references/transaction.md#gas-estimation
部署合约	forge script（自动生成部署脚本）	→ references/contract.md#deploy-contract-forge-script
验证合约	forge verify-contract	→ references/contract.md#verify-contract
一键部署 ERC20	forge script + 内置 ERC20 模板	→ references/contract.md#erc20-one-click-deploy-built-in-template
批量转账 / 空投	forge script（自动生成空投脚本，支持向 6000+ 个地址批量空投、CSV 文件输入、三级自动模式：≤10 个使用简单模式 / 11-200 个使用单批次 / >200 个使用多批次，以及经过强化的 Distributor 合约）	→ references/transaction.md#batch-transfer--airdrop
生成合约交互脚本（读写方法、JS/TS/Python）	Script_Generator（Agent 自动生成）	→ references/script-gen.md

一般错误处理

执行命令前，Agent 应进行预检查；命令执行失败时，应根据 stderr 输出提供对用户友好的错误消息。

错误场景	CLI 错误特征	处理方式
地址格式无效	invalid address	提示检查地址格式（0x + 40 个十六进制字符）
未找到交易哈希	transaction not found	提示未找到交易，并建议检查哈希
地址处无合约代码	空返回值	提示目标地址没有合约代码
调用回滚	execution reverted	提取并显示回滚原因
未配置私钥	命令缺少 --private-key	提示用户配置私钥（参数或环境变量）
余额不足	insufficient funds	提示余额不足，并显示当前余额
Nonce 冲突	nonce too low	建议等待或手动指定 nonce
缺少网络配置	无法读取 assets/networks.json	提示配置文件缺失或格式无效
不支持的网络	网络名称不在配置列表中	提示仅支持 atlantic-testnet 和 mainnet

各项操作的详细错误处理表请参见对应的参考文件。

安全提醒

• 私钥保护：切勿在日志、聊天记录或版本控制中泄露私钥。将私钥存储在 $PRIVATE_KEY 环境变量中，并在命令中通过 --private-key $PRIVATE_KEY 显式引用。注意：forge / cast 不会自动读取环境变量；必须将其作为命令参数显式传入。
• 网络确认：执行写入操作前，Agent 必须明确告知用户目标网络（测试网或主网）。主网操作必须明确警告，并要求用户再次确认，以防误操作。

写入操作预检查（所有写入操作均须执行）

对于所有需要私钥的操作（转账、合约调用、部署、空投等），Agent 必须在执行前自动完成以下检查：

1. 私钥检查

自动检测是否已设置 $PRIVATE_KEY 环境变量：

# Check if environment variable exists (without outputting the private key)
[ -n "$PRIVATE_KEY" ] && echo "PRIVATE_KEY is set" || echo "PRIVATE_KEY is not set"

• 如果未设置：提示用户通过 export PRIVATE_KEY=<your_private_key> 进行配置，不要继续
• 如果已设置：继续下一步

2. 推导公钥地址并向用户确认

通过 cast wallet address 从私钥推导对应的公钥地址：

cast wallet address --private-key $PRIVATE_KEY

3. 网络确认（必须明确告知用户）

执行任何写入操作前，Agent 必须明确告知用户目标网络。从 assets/networks.json 读取目标网络信息，并向用户显示网络名称和类型。

• 如果用户未指定网络，则使用默认网络（atlantic-testnet），并明确告知用户：当前操作的目标网络为 Atlantic 测试网
• 如果用户指定了 mainnet，则醒目地警告用户：当前操作的目标网络为主网，请确认是否继续

合并步骤 2 和步骤 3 中的信息，供用户确认。示例格式：

Detected private key address: 0x1234...abcd
Target network: Atlantic Testnet (atlantic-testnet)
Proceed with this account on this network?

主网操作的示例格式：

Detected private key address: 0x1234...abcd
⚠️ Target network: Mainnet (mainnet) — please proceed with caution
Proceed with this account on mainnet?

• 用户确认后，继续后续操作（余额检查、发送交易等）
• 如果用户拒绝，则停止执行

4. 自动检查余额

确认账户和网络后，自动查询余额（请参见各项操作的 Agent 指南中的余额检查步骤）。