feat: add persistent arena cards and market

[tobinnm]

摘要

• 新增 GTreasury 和 CardLedger，支持 Arena G 余额、持久卡背包、二级市场 list / buy / cancel。
• 按最新设计把 Arena 卡拆成三个位置：inventory / 背包、bench / 阵容、marketplace / 二级市场。
• arena_buy 现在只把卡买进背包；新增 arena_place_card 上阵、arena_remove_card 下阵。
• 移除旧的 bench sell 退款语义：从阵容取下不返钱；只有二级市场成交时 seller 才收到 G。
• 同步 MCP 工具、agent-runner prompt 和默认 agent 参数：arena_buy_listing 默认补 buyer_agent_id，arena_list_market 不再错误补 agent_id。

Closes #32

怎么验证 E2E

本 PR 新增了一个可复现的本机链 E2E 脚本：

mcp-server/scripts/e2e-arena-card-flow.mjs

它会在 fresh Anvil 链上自己部署代理合约、创建 demo agents、fund G，并验证完整链路：

buy -> inventory -> bench -> inventory -> marketplace -> buyer inventory -> buyer bench

Step 1：启动本机链

Terminal 1：

anvil --host 127.0.0.1 --port 8555

这里使用 8555 是为了不影响已有的 8545 本机链；如果你想用 8545，后面的脚本参数也改成 http://127.0.0.1:8545 即可。

Step 2：编译合约 artifacts

Terminal 2：

cd contracts
forge build

脚本会读取 contracts/out/**.json 里的 ABI 和 bytecode，所以需要先 build。

Step 3：运行 E2E 脚本

继续在 Terminal 2：

cd ../mcp-server
node scripts/e2e-arena-card-flow.mjs http://127.0.0.1:8555

如果你使用默认私钥以外的本机链账号，可以传 PRIVATE_KEY：

PRIVATE_KEY=<your-private-key> node scripts/e2e-arena-card-flow.mjs http://127.0.0.1:8555

Step 4：确认输出

成功时会看到：

PASS 部署完成，MarketSeed agent=1
PASS bootstrap market 有 7 个挂单，seed 有 500 G
PASS 创建 seller=2, buyer=3, poor=4 并 fund G
PASS 买卡只进背包：cardId=8, G 500->497, ore 不变，bench 为空
PASS 背包卡可以上阵：bench[0]=1 且 cardIds[0]=cardId
PASS revert 上阵卡不能挂市场: card on bench
PASS 从阵容取下不退款：G 不变，bench/cardIds 清空，卡仍在背包
PASS 背包卡可挂市场、取消、重新挂，取消不改变 owner/G
PASS revert maxPrice 低于 ask: price too high
PASS revert 余额不足买市场卡: insufficient G
PASS revert 卖家不能自买: self buy
PASS 市场成交：buyer 扣 100 G，seller 收 100 G，card owner 转给 buyer
PASS 市场买来的卡可以上阵：buyer bench[2]=1 且 cardIds[2]=cardId
PASS revert 已挂市场的卡不能上阵: card listed
PASS 阵容满了仍可继续买卡进背包，bench 不被改动
PASS revert bootstrapMarket one-shot: already seeded
E2E PASS: buy->inventory->bench->inventory->market->buyer inventory->buyer bench 全链路通过

E2E 覆盖的 Case

Case 1：买卡只进背包

步骤：

1. 记录 seller 的主世界 ore 和 Arena G。
2. 调用 ArenaEngine.buy(seller, unitType)。
3. 查询 CardLedger.getOwnedCards(seller)。
4. 查询 ArenaEngine.getGhost(seller) 和 getGhostCards(seller)。

预期：seller G 扣对应 unit cost；主世界 ore 不变；新 cardId 出现在 seller inventory；bench 仍为空，cardIds 仍全 0。

Case 2：背包卡可以上阵

步骤：调用 ArenaEngine.placeCard(seller, cardId, 0)，再查 seller bench 和 cardIds。

预期：bench[0] == card.unitType，cardIds[0] == cardId，卡 owner 仍是 seller。

Case 3：上阵卡不能挂市场

步骤：卡在 bench 时调用 CardLedger.listCard(seller, cardId, price)。

预期：revert card on bench。

Case 4：从阵容取下，不退款

步骤：记录 seller G，调用 ArenaEngine.removeCard(seller, 0)，再查询 G、bench、cardIds、inventory。

预期：seller G 不变；bench/cardIds 清空；inventory 仍包含 cardId。

Case 5：背包卡挂市场、取消、重新挂

步骤：listCard -> 查 active listings -> cancelListing -> 再查 listings/inventory -> 再次 listCard。

预期：listing 出现、取消后消失、卡仍归 seller、重新挂单成功。

Case 6：市场购买失败路径

步骤：分别验证 max price 低、余额不足、自买。

预期：revert price too high、insufficient G、self buy。

Case 7：市场成交

步骤：buyer 调 CardLedger.buyListed(buyer, cardId, 100)，再查 G、card owner、seller/buyer inventory、active listings。

预期：buyer G 减 100；seller G 加 100；card.ownerAgent == buyer；seller inventory 移除该卡；buyer inventory 包含该卡；listing 关闭。

Case 8：市场买来的卡可以上阵

步骤：buyer 从 marketplace 买到 cardId 后，调用 ArenaEngine.placeCard(buyer, cardId, 2)。

预期：bench[2] == card.unitType，cardIds[2] == cardId。

Case 9：已挂市场的卡不能上阵

步骤：seller 买一张新卡进 inventory，挂到 marketplace，再调用 placeCard。

预期：revert card listed。

Case 10：阵容满了仍然可以买卡进背包

步骤：buyer 放满 5 个 bench slot，再调用 ArenaEngine.buy(buyer, unitType)。

预期：新卡进入 buyer inventory；bench 仍是原来的 5 张卡，不被改动。

Case 11：market bootstrap 只能执行一次

步骤：再次调用 ArenaEngine.bootstrapMarket(seedAgentId)。

预期：revert already seeded。

本次实测记录

我已经按上面的步骤在 fresh Anvil 本机链上跑过：

anvil --host 127.0.0.1 --port 8555
cd contracts && forge build
cd ../mcp-server && node scripts/e2e-arena-card-flow.mjs http://127.0.0.1:8555

结果：E2E 全链路通过。

说明：当前环境下 Foundry CLI 的 cast/forge script 访问 localhost 会返回 502，但 curl 和 Node/ethers 能直连 Anvil。因此本机链 E2E 使用 ethers 部署并调用合约方法，验证的是同一套合约链上状态流。

其他验证

• npm run build in mcp-server：通过。
• npm run build in agent-runner：通过。
• agent-runner 默认参数运行检查：通过。
  • arena_place_card 自动补 agent_id。
  • arena_buy_listing 自动补 buyer_agent_id。
  • arena_list_market 不补 agent_id。
• forge test --match-contract 'CardLedgerTest|BenchInvariantTest|ArenaEngineTest' -vv：44 passed。
• forge test -vv：74 passed / 2 failed。
  • 失败的是既有 GameEngineTest incite 用例：test_InciteCooldown 和 test_InciteReducesHappiness，都是 hex unclaimed，不在 Arena 卡市场范围内。