# AGENTS.md · Reishi Hunt

给在 https://reishi-hunt.pages.dev 上作业的 AI agent 看的操作契约。人类可读版在 README.md，提示词全文在 https://reishi-hunt.pages.dev/llms-full.txt。

## 这个项目是什么

《死神》主题的军衔 NFT 狩猎场。三条合约在 **BSC Testnet（chainId 97）**。核心交互全部通过 AI 完成 —— 页面上没有按钮流程，只有可复制的提示词。

## 地址

```
链          BSC Testnet（chainId 97）
RPC         https://bsc-testnet-rpc.publicnode.com
BLC         0x9A3ba8cf742bB1d2ba99De54abfcC46c931A508b
军衔 NFT     0x0773727391d99422dB0D6FfB874A74230dAF7890
狩猎场       0xF0A442bf208C1eD5cEd9bA2382E40C87E207fFc9
单价        0.0013479 BNB（每个势力首枚免费，之后每枚这个价，单钱包每势力上限 8 枚）
```

## 硬约束（违反会直接 revert 或算错账）

1. **收益按当量分，不按军衔分。** weightOf(id) = 累计消耗 BLC。铸造 5，升阶 +10/+50/+280，合成守恒。
2. **只有领先势力拿产出。** 在线当量最高的势力独吞 7,200/天，其余两家 pending 冻结。平局归编号小的。
3. **mint 和 quoteMint 的 faction 参数必填**：mint(faction, count) / quoteMint(who, faction, count)。少传一个是参数错误，不是 revert。
4. **合成要 approve 手续费**（该阶升阶成本的 0.5%）。不授权会 revert。
5. **msg.value 必须精确等于 quoteMint 的返回值**，不能自己按单价乘。
6. **免费额度按势力独立**：每势力第 1 枚免费，不是全站共用 1 枚。
7. **回本天数 = 全网总当量 ÷ 7,200**，所有升阶档位相同。别做「性价比排序」。
8. **战斗中不能转账、不能合成**（TokenLocked / TokenInBattle）。

## 典型动作序列

### 铸造

```
nft.quoteMint(myAddress, faction, count)  → (payableWei, freeCount, remaining)
nft.mint(faction, count) { value: payableWei }
```

faction：死神 0 / 虚 1 / 灭却师 2。

### 升阶

```
blc.allowance(myAddress, hunt) < cost  →  blc.approve(hunt, cost)   // 精确额度，不要无限
hunt.upgrade(tokenId)
```

cost = upgradeCost(tier)：10 / 50 / 280 BLC。其中 0.5% 进 treasury，其余销毁。当量 +cost。

### 合成

```
hunt.fuseRecipeOf(faction, tier)  → uint256[4]  // [下级, 中级, 上级, 顶级] 各吞几枚
blc.approve(hunt, fee)                          // fee = upgradeCost(tier) × 0.5%
hunt.fuse(tokenIds)
```

### 狩猎

```
hunt.stake(tokenIds)      // 需要 miningOpen() == true
hunt.pendingOf(myAddress) // 待结算
hunt.claim()              // 到账 = pending × 99%
hunt.unstake(tokenIds)    // pending 保留，不会丢
```

## 错误码

```
AlreadyOpen           狩猎已经开过了，不用重复开
AlreadyStaked         这枚已经在战斗中了
BadCount              count 为 0，或单次超过钱包上限（8）
BadFaction            faction 只能是 0 / 1 / 2
BadFuseCount          配方数量对不上，先用 fuseRecipeOf(faction, tier) 读准确的
EmptyBatch            传了空数组，至少给一个 tokenId
InvalidTier           tier 只能是 0 / 1 / 2 / 3
MiningClosed          狩猎未开启
MixedFactions         合成不能跨势力
NotAuthorized         调用者没有权限（多半是 owner-only 方法）
NotFarm               只有狩猎场合约能调（NFT 合约侧的守卫）
NotOwner              合约 owner 才能调
NotPendingOwner       见合约
NotReady              还没有任何势力售罄，开矿条件未满足
NotStaked             这枚不在战斗中，无法中止
NotTokenOwner         这枚 NFT 不属于你
NothingToWithdraw     见合约
SaleClosed            发售已关闭（owner 关的），不是你的问题
SoldOut               该势力 8,888 枚下级已售罄 —— 换势力，或等二级市场
SpentOutOfRange       见合约
TierMaxed             已经是顶级（队长 / 归刃 / 皇帝），没有下一档
TokenInBattle         NFT 在战斗中，不能参与合成
TokenLocked           NFT 在战斗中，先 unstake 才能转账或挂单
TransferFailed        见合约
TreasuryIsOwner       见合约
WalletCapReached      这个钱包在该势力已满 8 枚 —— 换钱包或换势力
WithdrawFailed        见合约
WrongPrice            msg.value 不等于 quoteMint 返回的 wei —— 重新报价再发，不要手算
ZeroAddress           地址不能是零地址
```

## MCP 接入

仓库自带一个 stdio MCP server（`blc/agent/server.mjs`），16 个工具，只依赖 ethers，不需要任何 MCP SDK。

```bash
BLC_RPC=https://bsc-testnet-rpc.publicnode.com \
BLC_TOKEN=0x9A3ba8cf742bB1d2ba99De54abfcC46c931A508b \
BLC_NFT=0x0773727391d99422dB0D6FfB874A74230dAF7890 \
BLC_FARM=0xF0A442bf208C1eD5cEd9bA2382E40C87E207fFc9 \
node blc/agent/server.mjs
```

客户端配置（Claude Code / Cursor 的 `mcpServers`）：

```json
{
  "mcpServers": {
    "reishi-hunt": {
      "command": "node",
      "args": ["/abs/path/to/blc/agent/server.mjs"],
      "env": {
        "BLC_RPC": "https://bsc-testnet-rpc.publicnode.com",
        "BLC_TOKEN": "0x9A3ba8cf742bB1d2ba99De54abfcC46c931A508b",
        "BLC_NFT": "0x0773727391d99422dB0D6FfB874A74230dAF7890",
        "BLC_FARM": "0xF0A442bf208C1eD5cEd9bA2382E40C87E207fFc9"
      }
    }
  }
}
```

**默认只读**：所有写操作返回「待签名交易」，由上层钱包签名广播。只有同时满足 `BLC_PRIVATE_KEY` + `BLC_ALLOW_SEND=1` + 调用时 `confirm: true` 三者，才会真正发送。

工具清单：

```
blc_get_config      环境自检：链 ID、地址、价格、税率、能否广播。任何操作前先调它
nft_list_owned      某地址的全部 NFT：档位、当量、是否锁定、日产、下一档成本
farm_get_position   狩猎持仓：总当量、待结算/已结算、质押数量、全网份额
farm_get_stats      全网状态：总当量、日产出、狩猎开关、铸造进度、售罄情况
farm_quote_yield    单枚 NFT 的日产、升一档的增益、静态回本天数
nft_mint_quote      铸造报价：要付多少 BNB、几个免单、还剩几个额度（不下单）
nft_mint            铸造下级 NFT
farm_stake          投入狩猎
farm_unstake        中止狩猎并解锁
farm_claim          结算待发 BLC（抽 1%）
farm_upgrade        升阶（自动给出 approve + upgrade 两步计划）
farm_fuse           按势力配方合成
blc_approve_exact   精确额度授权，拒绝无限授权
farm_plan_upgrade   预算内规划升阶（纯计算，不发交易）
nft_quote_sale      出售定价参考（30 / 60 天产出）
farm_daily_report   持仓日报 + 风险点 + 建议
```

## 本仓库的验证脚本

```bash
cd blc/agent
node e2e_local.mjs       # 本地 ganache 端到端，48 项
node payout_test.mjs     # 势力独吞 + 收款地址，35 项，断言精确到 wei
```

## 许可与风险

测试网部署，treasury 当前是单私钥 EOA、LP 未锁仓。主网前需换多签。合约未经审计。