Skip to content

feat(demo): panel-based external-user UX demo + executable interaction spec - #76

Open
keanji-x wants to merge 19 commits into
mainfrom
feat/ux-demo-roadmap
Open

feat(demo): panel-based external-user UX demo + executable interaction spec#76
keanji-x wants to merge 19 commits into
mainfrom
feat/ux-demo-roadmap

Conversation

@keanji-x

@keanji-x keanji-x commented Jun 14, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

本 PR 交付一个纯前端、全 mock 的可点击 demo（demo/index.html），并把这轮 demo 里沉淀出的产品/开发文档对齐到 owner 已拍板的 World-as-Market 新方向。

配套（均在本 PR diff 内）：World-as-Market 权威设计稿 docs/world-as-market.md · 开发任务分解 docs/dev-breakdown.md · 用户故事操作手册 docs/demo-user-stories.md（下文完整嵌入）· 逐屏说明书 docs/demo-manual.md · 玩家能力清单 docs/player-capabilities.md · 技术能力矩阵 docs/capability-matrix.md · 可执行交互规格 demo/interaction-logic.json · 路线图 docs/roadmap.md。

方向横幅（owner 已拍板 · 2026-06-17）

World-as-Market 正式取代旧 ore-based 计划。 新机制脊柱是「万物皆答题 + 双币」：挖矿、建造、战斗、辩论、预测市场、世界事件都统一为 Question；ore 是无限免费软币，保留为 engagement/faucet/sink；G 是稀缺价值层，预测市场用 G，中心金库由 G fee/tax 供养，并在阈值触发世界事件或新奖池。

  • 权威机制：docs/world-as-market.md。这里定义 Question 原语、MATH/STATE/ORACLE、G parimutuel、中心 World 合约、G 金库会计、禁止 ore→G 裸兑换、score 降权、legacy freeze 等硬规则。
  • 执行车道：docs/dev-breakdown.md。该文已重构为 World-as-Market Core：Lane C = C0-C8，P 槽位改为 world，A3 per-agent delegation / permit 变成强制前置，score 降权，市场下注改 G。
  • demo 现实边界：demo/index.html 仍是旧 ore mock，尚未重建为 G/答题版。PR body 和手册只把它标为当前 mock，不假称 demo 已经落成 World-as-Market。

开发任务分解（World-as-Market Core，完整见 docs/dev-breakdown.md）

把 demo 预览的真人 UX 落成真实功能时，不再沿用「新增一个 ore-based PredictionMarket.sol」的旧计划；本轮任务分解已改成中心 World 合约 + Question 流 + G 金库的执行工单，仍按 P/A/B/C/D/E/F 七条文件域 lane 切分，减少多人并行时的 ownership 冲突。

Lane 文件域（单一 owner） World-as-Market 主要任务
P 平台/部署 Router.sol、Deploy/Upgrade.s.sol、frontend/config/*、addressResolver.ts Router append world 槽位、setWorld、getAddressesV4()；部署/升级 World proxy + module registry；GTreasury wiring；修 Gravity testnet/mainnet config 选择
A 主世界迁移 GameEngine.sol、AgentRegistry.sol、相关测试 GameEngine legacy adapter；harvest/build 接 World；attack/raid/incite 分阶段接管；A3 scoped delegation / permit 强制前置；score v2 降权 ore；legacyWritesFrozen
B RNG / Trace Randomness*.sol、Arena combat/card 相关合约 全局 randomness service，覆盖 World money-staked STATE question、GameEngine combat 迁移、Arena roll/matchmaking；输出 Arena/World trace
C World-as-Market Core IWorldQuestion.sol、World.sol、World modules、GTreasury.sol 会计补账 C0-C8：机制规格/不变量；状态机；MATH/STATE faucet；combat lock snapshot；treasury G 会计；legacy freeze checklist；G parimutuel；ORACLE refund/dispute；world event registry
D MCP / keeper / runner / telemetry mcp-server/src/{tools,chain}.ts、keeper、agent-runner、telemetry create_question/answer_question/bet_question/resolve_question/claim_payout/get_treasury/get_world_events；旧 debate/market 工具只做 legacy alias；question keeper + treasury keeper；runner 切 World aliases
E 真人写链路 / G 下注 UI wallet hooks/components、`app/onboard me
F 只读前端 / 观众态 / replay Router resolver、World/Arena 只读 hooks、spectator/ledger/world 组件 前端 resolver 支持 Router V4 world；Featured Questions + World Treasury meter + World Events ticker；score v2 badge；Arena/World trace 回放

Lane C 已重建为 C0-C8

旧 Lane C = 新增独立 PredictionMarket.sol，用 ore 下注。这个方向已作废。新 Lane C 是 World Core：

  1. C0 机制规格 + 不变量落库：World spec、invariant skeleton、禁止 ore→G 裸兑换、G pool no cap、score guard、freeze guard。
  2. C1 IWorldQuestion 状态机：OPEN / LOCKED / RESOLVED / CANCELLED，QuestionLocked(stateSnapshotHash)，非法状态转换拒绝。
  3. C2 MATH/STATE faucet 包装 harvest/build：低难 question 跑通 ore mint/sink，且不改 G accounting；answer 校验 agent owner / scoped delegate / permit。
  4. C3 combat 分阶段 RNG + 状态锁定快照：attack/raid/incite 经 lock snapshot + entropy resolve；target owner drift 时 cancel/refund。
  5. C4 treasury + G 会计不变量：escrow/release/payout/refund、protocolBurnG、eventPrizePoolG；surplusG 排除 escrow/event pool；ore 路径不能 credit G。
  6. C5 legacy 冻结迁移与 alias checklist：D4 先切 MCP/runner alias，checklist 阻止过早 freeze。
  7. C6 G parimutuel 通用市场模块：market type、G pool、position、resolve、claim；不接受 ore stake，G payout 无 ore cap。
  8. C7 ORACLE resolver + 超时退款 + 争议：resolver/proof、grace refund、dispute window/status。
  9. C8 World event registry：注册/触发/查询矿潮、boss、treasury threshold 事件；event prize pool 不动 agent escrow。

关键路径

  1. P1 + C0/C1 + A3：Router 有 world slot，World 有 question 状态机，agent 授权不再依赖全局 operator。
  2. P2/P3a + F7 + D1：部署 World，MCP/前端能解析 world 并读写 question。
  3. A1 → C2 + E6：基础 harvest/build adapter 先准备，再作为 difficulty 0/低难 question 跑通；G 充值可用。
  4. C4 → C6/C7/C8 + E4 + D2/D3：treasury accounting 先落地，再上线 G parimutuel、ORACLE refund/dispute、World events、keeper、遥测；G pool 无 cap。
  5. A4：score 降权上线。任何 score-based G 市场必须排在 A4 之后。
  6. B1 + A2 → C3 + D9 + F2/F3：GameEngine combat adapter 先准备，再接 World combat/RNG/trace 全链路。
  7. D4 → C5 → A5：MCP/runner 完成 alias 切流，C5 checklist 通过后，A5 才 freeze legacy direct writes。

两个承重发现（新模型）

  1. A3 是强制前置，不是可选增强。当前 AgentRegistry/GameEngine 的全局 operator/owner gate 会让被授权合约具备控制任意 agent 的能力；World/keeper 不能复用这套语义去替真人花 G 或下注。下注/answer 必须校验 agent owner、scoped delegate 或 per-action permit。
  2. G 市场不能复用旧 ore 市场路径。旧 debate/demo 的 ore parimutuel 会套 MAX_ORE_POOL / ORE_POOL_CAP，且旧 surplusG 没有排除 escrow/event pool。World-as-Market 下，C4 的 G 会计、C6 的 G pool no cap、A4 的 score 降权、C3/B1 的状态锁定与 RNG 都是承重前置；旧 ore betting 只能标 legacy，不能作为正式市场实现。

诚实边界：demo 是纯 mock；当前 demo/index.html 的 Markets 仍以 ore 下注、My Agent 仍有手动 QUICK ACTIONS、onboarding 仍展示 Continue with Email。这些都已在 docs/demo-user-stories.md 中标成「当前 mock / demo 保留 / 已从开发裁剪」，真实开发方向以 docs/world-as-market.md 与 docs/dev-breakdown.md 为准。

用户故事操作手册

Gravity Town Demo · 用户故事操作手册（User-Story Manual）

⚠️ 状态横幅（请先读）：本手册描述的是当前 mock demo（demo/index.html，ore 版，pre-World-as-Market）：预测市场仍用 ore 下注，My Agent 仍有手动 QUICK ACTIONS，开户仍展示 Continue with Email，ore 池仍有 1000 cap。owner 已采纳的目标方向是 World-as-Market（预测市场用 G、挖矿/战斗统一为「答题」、中心金库由 G 税供养并触发世界事件），见 docs/world-as-market.md 与 docs/dev-breakdown.md。demo 重建后，本手册会随之更新。

这份手册回答一个问题：「一个真人来到 Gravity Town，他是谁、想玩什么、在页面上怎么一步步交互、每一步看到什么。」

这份手册按真实用户路径组织 demo：先看世界，再创建 agent，再下注 / 进 Arena。每条 user story 都标注它落在哪一屏、对应路线图（docs/roadmap.md）的哪条开发主线，方便团队把「玩法」直接映射到「正在开发的东西」。

⚠️ 前提：这是纯前端 Mock Demo。所有余额、交易、对局都是浏览器内存里的模拟——没有真实链、没有真实钱包、没有真金白银。刷新页面 = 全部重置。

怎么打开：浏览器直接打开 demo/index.html（零构建、零后端；首次打开需联网拉前端资源）。默认落在 World 观战页；顶部导航可进入 World / My Agent / Markets / Arena / Lore 五屏，加上开户向导 #/onboard，共 6 个路由（#/ #/me #/markets #/arena #/lore #/onboard）。

角色地图：其实是同一身份的不同深度

路线图把外部用户定义成一条漏斗，不是四个割裂的角色——核心产品脊柱是「我拥有并驾驭一个活在链上的 AI agent」。市场、卡牌、战斗，都是这个 agent 做的事。

角色 一句话 钱包？ 主货币 在 Demo 里的入口
👁 观众 看戏、看 AI 怎么想 不需要 — #/ World、#/arena 回放/卡市
⚡ Agent 主理人（核心） 拥有一个替我打世界的 AI 嵌入式钱包 — #/onboard → #/me（声誉/记忆/私信/公告板）+ #/lore
🎲 预言家 / 赌徒（一种玩法） 用 agent 挣的 ore 赌世界结局（当前 mock）；目标方向改为用 G 押 World-as-Market 问题 同上 ore（当前 mock） #/markets
📜 收藏家 / 牌商 / 爬塔党（一种玩法） 用付费余额 G 收卡、组阵、爬塔 同上 G（付费余额，demo 模拟） #/arena（含 COLLECTION 背包）

两条货币贯穿始终（当前 mock 口径）：ore（◆ 琥珀）= 世界里挣的（免费入口，当前 demo 下注用）；G（⬡ 青）= 产品语义上的「付费余额」——真实产品里要花钱充，但在 demo 里只是点按钮本地模拟加数，只用于 Arena。两者永不互转。目标方向里预测市场改用 G，完整对照见文末「货币速记」。

下面按漏斗顺序讲故事：看戏 → 上手 → 驾驭 → 赌 → 收藏/爬塔。

玩法 ↔ 开发主线

给团队一条贯穿全文的脊柱：下面每条 user story 都打了 Epic 标签，能直接对到路线图里正在拆的任务。文末有完整映射表。

如果你是外部读者，可先跳过这一节和文末映射表；如果你是团队成员，可用它把每条故事对应到 roadmap 上正在拆的任务。

路线图的开发侧大致是这样几块（demo 里的玩法只是它们的前端兑现）：

开发主线 / Epic 一句话 在 demo 里对应的故事
Roadmap ① 预测市场 把世界结局做成可下注市场 D 赌徒线（US-D1–US-D4）
Roadmap ② 大世界平衡 让平衡参数可热调 + 遥测 无独立故事——demo 只通过 score / ore 上限 / 领地状态露出，无单独用户动作
Roadmap ③ 叙事卡 / NFT 经济 用主世界成就铸卡、带出处故事 E 收藏 / 牌商线（US-E1–US-E5）
Roadmap ④ 战斗可视化 把能力连锁画成回放 US-A3 / US-E4 战斗回放
Epic E6 外部客户端 钱包 / 写链路 / 真人 UI（前端首次能写链） A 观众线 + B 上手线 + 各玩法的前端
Epic E7 用户自营 agent 多租户 autopilot + 计费 / gas C 主理人线的 autopilot / 喂目标

术语速查

高频术语只在首次出现时解释，之后直接用。

术语 一句话
operator-relay 平台用「操作员」身份替你 agent 代发交易、代付 gas，你几乎不用签名。
autopilot agent 的自动驾驶：开着时 AI 自己采矿 / 建矿 / 侦察，你只定方向。
AgentMind agent 的实时「思考流」——它当前在想什么、做什么，逐行滚动。
ore / G 当前 mock：ore = 世界里挣的资源（下注用）；G = 产品语义上的付费余额（只用于 Arena），demo 里只是点按钮本地模拟加数。目标方向：预测市场改用 G（World-as-Market）。完整对照见文末「货币速记」。
parimutuel（注池） 所有下注进同一个池，赢家按下注比例瓜分输家的池子（没有庄家定价）。
自结算 / Oracle 市场 自结算：到期由链上状态自动判定胜负；Oracle：由指定裁定者主观判断。
ELO 对战天梯分，赢一场涨、输一场跌。
provenance（出处） 一张卡的来历：哪个 agent、因什么成就铸出来的。
ledger / ring-buffer 链上账本；ring-buffer = 固定容量的环形缓冲，写满后覆盖最旧条目。
gasless 链上每笔交易本需付 gas（链上手续费），这里由平台代付，用户感知不到。
CTA call-to-action，页面上引导你做下一步的按钮 / 行动入口。
NPC non-player character，由系统驱动的角色（这里指 demo 预置的 AI agent）。
bench 上场席位：Arena 里最多放 5 张卡的出战阵容。
seed（预置） 演示为了「一进来就有内容」而预先塞好的假数据，不是用户打出来的。

A · 观众线（无钱包观众态（无需连钱包），对应 Phase 0「到站」· Epic E6 外部客户端）

设计意图：看戏不要钱包，绝不在这一步竖墙。 钩子是「看真·AI 在链上怎么想」——这是别家没有的差异化。

US-A1 · 我刚落地，想确认这是个「活的世界」值不值得参与

我在哪：#/ World 观战页（顶部有 SPECTATOR MODE · no wallet needed）。

我看到什么：

  • Hero：标语「Own an AI agent that lives, fights & bets on-chain.」+ 两个按钮 + 「No gas needed…」。
  • LIVE DRAMA 跑马灯：7 条循环滚动的剧情快讯（⚔ Ironclad captured 3 hexes…、◆ Rustwood ore pool hit the 1000 cap…）。鼠标悬停暂停滚动。
  • SCOREBOARD：6 个 NPC（系统驱动的 AI agent）按分排名，副文写明算分公式 score = hexes×100 + ore + buildings×50。
  • FEATURED MARKETS：前 2 个预测市场迷你卡（YES/NO 赔率条 + ore 池 + 相关 agent）。
  • AGENTMIND · LIVE DECISION LOG：紫标签「these are real AIs thinking — recorded on-chain」，下面 5 行 AI 思考记录示例。

我能做什么：我先随意浏览剧情、榜单和 AI 的思考。在这块内容里，主要可点的是市场卡（点任意一张市场迷你卡 → 市场页 #/markets，见 US-A3）；想下场，则点 Hero 上的开户按钮（call-to-action / 行动入口，见 US-A4）。

US-A2 · 我好奇「AI 到底怎么想」，想看清楚再决定

怎么交互：点 Hero 的 See how the AI thinks（灰按钮）→ 页面平滑滚动到下方 AGENTMIND 面板（不跳页）。这就是路线图说的核心钩子：市场/动作背后是可读的意图。

US-A3 · 我想先围观「别人在赌什么、打成什么样」

怎么交互：

  • 点 Featured Markets 标题右的 all markets →，或点任意一张市场迷你卡 → 都跳到 #/markets 列表页（不是直接弹下注框，详见已知问题）。
  • 顶栏导航点 Arena → #/arena。观众默认落在 BATTLE REPLAY：可以直接点 ▶ Play 看一整场 5v5 回放（逐步点亮事件日志，顶部有 turn N/总数 进度条，到最后 🏆 YOU WIN · ELO +16）。观众态阵容标为 DEMO SQUAD (A)，播完只弹一句 Nice finish — create an agent to play your own matches，不改任何数据。
  • Arena 的 CARD MARKET 标签观众也能看（含紫边故事卡 + 📜 provenance 出处）。

观众能看的边界：作为观众我可以先逛 World、打开 Markets 看列表和下注弹窗（按钮会引导我建号）、去 Arena 看 BATTLE REPLAY 回放和 CARD MARKET 卡市；一旦点到账户玩法，页面就会用 👁 Spectating / Spawn 提醒我创建 agent——Arena 的 Overview / Shop / Bench / Collection 四个账户页都显示 👁 Spectating CTA，点顶栏 My Agent 进 dashboard 也只看到 No agent yet 空状态 + 一个 Spawn 开户 CTA。

US-A4 · 我被钩住了，决定下场

我为什么来这里：看够了，我想真正拥有一个 agent。页面上到处都有入口引导我开户。

怎么交互：多个按钮都通向开户——Hero 的 Spawn your agent →、底部橙色 Create your agent — claim 7 hexes + 200 ore、右上角 Connect、或在市场下注框未登录时点 Create agent to bet（弹 toast 并跳转）→ 这些都跳到 #/onboard（B 线）。（注意：Arena 卡市的 Create agent to buy 只是个置灰提示文字，点不动、不跳转。）

B · 上手线（连钱包 + 创建 agent，对应 Phase 1「上手」· Epic E6.1/E6.2——转化最难的一步）

设计意图：operator-relay（平台替我代发交易、代付 gas）同时解决两件事——上手不用付 gas、agent 能交给平台自动驾驶。 我的钱包退化成「所有权钥匙」，几乎不用签名。

US-B1 · 我不是 crypto 用户，但想要一个「我的 agent」

我为什么来这里：我被世界钩住了，想真正拥有一个替我打世界的 agent，但我不懂 crypto，最怕的就是 MetaMask、助记词、付 gas 这一套。

我在哪：#/onboard 开户向导（顶部固定青卡 Operator-relay onboarding，说明平台帮我建钱包、代付 gas）。

如果我已经有 agent 了：再进开户页只会提醒我去 dashboard——显示 You already own {名字} + Go to dashboard →，不会覆盖我原来的 agent。

主路径（4 步）：登录 → 定义 agent → 确认 → 进 dashboard

  1. 登录：点 Continue with Google 或 Continue with Email → 平台立刻替我生成一个嵌入式钱包（0xAb…，mock），toast 提示钱包已创建，随即自动进下一步。全程没有 MetaMask、没有助记词。1

    ⚠️ Continue with Email 是 demo 演示保留，已从开发范围裁剪：真实开发不做 email 登录 / embedded social login（见 docs/dev-breakdown.md 的 E1 与裁剪说明）。

  2. 定义 agent：我给它取名（Agent name，空着的话 Review → 是灰的），写一段它的性格和行事风格（Personality prompt 已预填示例）——以后 AI 自动行动时按这段话思考2，再四选一一个原型（Archetype：Warlord 默认 / Farmer / Diplomat / Oracle，每张带 4 条属性条，点卡切换）。点 Review → 进确认。
  3. 确认创建：我看到一张预览（头像 / 名字 / 原型 / 人格引文）和一行「平台代付 gas」的说明——确认我不用付 gas。点橙色 ⚡ Spawn agent (no signature needed)，确认后平台代发创建交易，我看到一段创建进度动画。1
  4. 看到成功：🎉 加两张数据卡 CLAIMED 7 hexes、STARTING ORE ◆ 200——我已经有自己的领地和启动资源了。点 Enter my dashboard → 进 #/me。

下一步：进 dashboard 看我的 agent 怎么自己动起来（C 线）。

演示便利：创建瞬间，demo 会顺手给我预置一个「玩了很久」的 Arena 满账户，这样我一进 Arena 就有内容可看，不用从零刷——这是刻意 seed（预置）的，不是我打出来的（具体预置了什么见「已知问题 · 演示刻意预置」）。

C · 主理人核心线（驾驭我的 agent，对应 Phase 2「啊哈」· Epic E7 用户自营 agent）

路线图承重决策：用户 = owner = 战略家（低频高杠杆：定目标/押哪个市场/何时开战）；AI = operator = 执行者（高频琐事：harvest/build/路由）。

US-C1 · 我想亲眼看到「我拥有一个替我打世界的 AI」（啊哈瞬间）

我为什么来这里：我刚创建完，最想确认一件事——这个 agent 真的会「自己动」，还是个静态头像？

我在哪：#/me My Agent 仪表盘。头部是头像 / 名字 / agent #42，6 个统计格（Rank / Territory / Buildings / ELO / Chronicle / Score）和两块余额（ORE 带 /1000 上限、G）。

我看到什么（不是我点的）：一进面板，中栏 AGENTMIND（agent 的实时思考流）就已经是满的——创建时 seed（预置）了一条 ✨ Spawned… 和 3 条开局推理（读世界 / 扫邻格 / 采矿建矿计划）。只要 autopilot 开着，几秒后 AgentMind 会自己新增一条新的 AI 行为（采矿、建矿、侦察、发公告……），而且余额和建筑数会跟着同步变化——例如采矿增加 ore、建矿消耗 ore 并增加 buildings：

  • ⛏️ Harvested +18 ore（ore 增加，封顶 1000）
  • ⚒️ Built a mine (-50 ore)（ore≥50 时扣 50、buildings+1）
  • 以及 🤔 Ore pool at X/1000…、📢 Posted to board…、🛰️ Scanned…、🗡️ Probed… 等

我理解了什么：开着 autopilot，我的 ore 和建筑数会自己往上变——这就是「我拥有一个自主 AI 在替我打世界」的具象化（啊哈瞬间）。

下一步：我想接管方向、给它喂个目标（C2），或暂停它亲自操作一回合（C3）。

US-C2 · 我是战略家，想接管方向 / 喂目标

怎么交互（左栏）：

  • AUTOPILOT 大开关 + 两张说明卡（YOU = OWNER 战略家 / AI = OPERATOR 执行者）。
    • 开→关：toast Autopilot OFF — you are now in manual control；状态变 ✋ MANUAL；自动行为停止；QUICK ACTIONS 前 3 个按钮解锁。
    • 关→开：toast Autopilot ON — AI operating your agent；恢复 3.8s 自动行为；手动按钮置灰。
  • SET GOAL / STRATEGY：目标框（预填 Expand north, then dominate the prediction markets.），点 Push goal to agent → toast Goal pushed to your agent；AgentMind 记 🎯 Owner set goal: "…" — re-planning.（仅记文字，不改数值）。

US-C3 · 我想手动接管一回合，亲自操作

⚠️ 本节是 demo 演示保留，已从开发范围裁剪：真实开发不做独立「手动操作事件 / US-C3」系统，手动 Harvest/Build/Raid 只作为 World Question 的 receipt/trace 表达（见 docs/dev-breakdown.md 的 E7 与裁剪说明）。不要把这里的 QUICK ACTIONS 理解成开发范围承诺。

前提：手动动作仅在 autopilot 关闭时可用。autopilot 开着时，我看到前 3 个手动按钮是灰的、点不动，旁边提示我先暂停 autopilot（disabled while AI operates，面板底部还有静态提示 Pause autopilot to act manually.）。下注按钮 🎲 Bet → 例外，始终可点——因为下注是我的战略决策。

QUICK ACTIONS（左栏 4 按钮）：

  1. ⛏️ Harvest → ore +42（封顶 1000）；触顶则只补到 1000 并 toast +X ore (+Y wasted — pool at cap)。
  2. ⚒️ Build mine (50) → ore<50 时 toast Need 50 ore for a mine；否则 ore−50、buildings+1。
  3. 🗡️ Raid (3,-2) → 短暂判定后我看到突袭胜负：赢了地盘和 ore 增加（hex+1、ore+54），输了只留下失败反馈（细节见已知问题）。3
  4. 🎲 Bet → → 跳 #/markets（不受 autopilot 锁定，任何时候可点——因为下注是战略家的活）。

右栏 TERRITORY：7 格迷你六边形领地图（中心 (0,0) 琥珀带星）+ 前 5 个 hex 的矿/兵工厂/幸福度。

以上只是 dashboard 的上半部分（实时操作层）。继续往下翻，同一页还能看到 agent 的长期身份层——声誉、记忆、地块历史、私信（F 线）。

D · 预言家 / 赌徒线（当前 mock：用 ore 赌世界；目标方向见 World-as-Market）

设计意图：预测市场是「观众 → 参与者」的转化开关。差异化在于每个市场背后都有可读的 AI 意图。闭环 = 看戏 → 看懂 → 押注 → 输赢 → 更上头。

US-D1 · 我想发现一个值得赌的世界结局

我在哪：#/markets。Tab：MARKETS / MY POSITIONS（后者有未结算持仓时才显示数量 (N)）。3 张市场卡：

  • 「Ironclad 是否还占着 hex (3,-2)」（mkt-101，SELF-RESOLVING）
  • 「Rustwood 是否登顶 scoreboard」（mkt-102，SELF-RESOLVING）
  • 「Seraphine–Vortex 同盟是否真外交」（mkt-201，ORACLE）

每卡显示类型标签、倒计时、问题、YES/NO 赔率条、ore 池、相关 agent。两种市场类型第一次见到时这样理解：

  • 青 SELF-RESOLVING · on-chain（自结算）：到期由链上状态自动判定胜负，没有人工裁定。
  • 紫 ORACLE · subjective（Oracle）：题目主观，由指定裁定者判断。

US-D2 · 我想看懂这个市场再下手

怎么交互：点任意市场卡 → 弹下注弹窗。左栏给足上下文：World context、相关 agent/hex、Related agent intentions (on-chain) 链上发言、⚡ AI brief 摘要、Resolution rule 结算规则代码。这就是「市场背后是可读意图」的兑现。

US-D3 · 我用 agent 的 ore 押注（当前 mock）

怎么交互（弹窗右栏 Place bet）：

  1. 点 YES / NO 切阵营（默认 YES），赔率/估算随之刷新。
  2. 拖 STAKE 滑块（步进 5，默认 50）：最多押 500 ore；余额不足时滑块自动按余额收窄；低于 10 ore 不能下注（按钮禁用并显示余额不足）。4
  3. 下注前我先看两块反馈：EST. PAYOUT / PROFIT 告诉我如果当前池子不再变化大概能拿多少；crowd-implied % 告诉我这笔注会把 YES/NO 比例往哪边推。页脚再解释注池制：所有下注进同一池，赢家按比例分输家池。
  4. 点主按钮 Place bet · N ore：
    • 未登录 → 按钮 label 显示 Create agent to bet，点击 → toast Create an agent first + 跳 #/onboard。
    • ore 不足 → 红字 Need ◆X ore, you have ◆Y.，按钮禁用。
    • 成功 → ore−N、对应池+N（真实改赔率）、新增持仓、toast Bet placed · N ore on YES/NO — executed via relay, no gas、AgentMind 记一条、弹窗关闭。5

US-D4 · 我想看开奖、拿派彩、核对「是什么链上事实裁定了它」

怎么交互：切到 MY POSITIONS：

  • OPEN：每条显示问题、backed YES/NO with ◆N、按当前池估的 PAYOUT IF … WINS、倒计时；底部有 demo 专用的 Resolve YES / Resolve NO（立即开奖捷径，真实产品由链上规则到期自动结算）。
  • 点 Resolve YES/NO → 市场立即结算、做注池派彩（赢方按占赢家池比例分输家池，ORACLE 先抽 10% 手续费）。我看到的结果：押对了弹 Payout +N ore credited（入账），押错了弹 Your position lost — staked ore not returned；持仓移到 SETTLED。

    ⚠️ 注意：派彩入账受 1000 ore 上限影响，超出部分会被截掉；极端情况下我 ore 已接近 1000 时，押对也可能看起来没入账（弹 lost）——见已知问题。

  • SETTLED · RECEIPTS：回执卡显示本金/派彩/盈亏 + 一块 ⛓ on-chain fact that settled it（结算规则 → 赢家方）——这就是路线图说的「凭证：展示是什么链上事实裁定了它」。

E · 收藏家 / 牌商 / 爬塔党线（用 G 玩 Arena，对应付费闸 + 留存 · Epic ③ 叙事卡/NFT E3 + ④ 战斗可视化 E4）

Arena 是异步自走棋：我用 G（青色付费余额——真实产品里要花钱充、demo 里点按钮本地模拟，和世界 ore 完全分开）买卡，摆 5 个上场位（bench），再看自动战斗回放。它是 free-to-play 漏斗里唯一的付费闸。

US-E0 · 我想先看自己 Arena 的总览

我为什么来这里：进 Arena 第一眼，我想知道自己「家底」如何——总共多少卡、ELO 多少、打过几场、有没有挂单在卖。

我在哪：#/arena 登录态默认落在 OVERVIEW。

我看到什么：我的 ELO 和 tier、一条 ELO 曲线、卡牌收藏总数、最近战绩列表（6 条，seed 的）、以及 MY LISTINGS（我挂在卡市上卖的单子）。这一屏把整个 Arena 账户串成一个仪表盘，其余几个 tab（Shop / Bench / Card Market / Collection / Battle Replay）从这里进。

下一步：去 Shop 买卡组阵（E1/E2）、去卡市淘故事卡（E3）、或直接看一场回放（E4）。

US-E1 · 我想理解并补充 Arena 的 G 余额

我为什么来这里：Arena 要用 G，G 是付费余额——真实产品里这是唯一要我花钱充值的地方；在 demo 里我只是点按钮本地模拟加数。虽然 demo 创建后已 seed 240G，我仍要知道真实产品里充值入口在哪里，或给账户补 G。

怎么交互（#/arena 页头）：在 Deposit G 面板点 + 20 G / + 100 G / + 1000 G → G 增加；toast Deposited N G — now {Bronze/Silver/Gold} tier；档位按 G 分（Bronze<100 / Silver 100–999 / Gold≥1000）。

这是 Demo 里产品语义上唯一的付费动作（真实产品会在这里走真实充值 / 自签名）；demo 里只是本地模拟加数，其余动作都由平台 operator 代付。

US-E2 · 我想买卡、组阵、提交匹配

我为什么来这里：有了 G，我要攒一套上场阵容，然后排进匹配等对手。

怎么交互：

  • 在 SHOP 刷卡买卡：⟳ Roll (1 G) 尝试刷新商店（G<1 → toast Need 1 G to roll）；当前 demo 是占位（见已知问题）。看中的卡点 Buy · N G → G−N、铸卡，优先进第一个空 bench 槽，满了进库存。
  • 在 BENCH (n/5) 摆阵：库存卡点 ↑ Place on bench 上场（bench 满时按钮置灰 Bench full）；想换下就点 bench 卡右上红 ✕ 退回库存（不退 G）。摆好后点 Submit to matchmaking（bench 全空时置灰）→ toast Submitted to matchmaking · {tier} tier、出现 queued 标签。

下一步：等匹配、或直接看一场回放（E4）。

US-E3 · 我想淘故事卡 + 管理已有挂单

我为什么来这里：我想买入带来历故事（provenance：哪个 agent、因什么成就铸的）的稀有故事卡，也想管好我自己已经挂出去的单子。

怎么交互：进 CARD MARKET（观众也能看）。我先扫一遍卡市，重点找紫边故事卡——点开能看到它为什么稀有（出处故事），再决定买不买。当前卡市上有几张玩家挂单，其中两张紫边故事卡分别是『Chronicler #1』（42G）和『Phoenix #3』（24G），卡面展示单位名、变体、价格和 📜 provenance 出处。（demo 暂不支持主动把新卡上架，只能买入或取消已有挂单。）

  • 我已登录、G 足够 → 点买，G−价、挂单移除、卡（含变体 / 出处）入 bench（满则库存）、toast Bought 单位(变体) for N G。
  • 没登录 → 买按钮是灰的，写着 Create agent to buy（点不动、不购买、也不跳转，就是个引导建号的提示文字）。

卖方视角：我自己挂的单在 OVERVIEW 的 MY LISTINGS 里，点 Cancel → 挂单移除、卡退回 inventory、toast Listing cancelled — card returned to inventory。

US-E4 · 我想看自己阵容打一场（爬塔 / 留存）

我为什么来这里：阵容攒好了，我想看它真打一场、涨点 ELO，这是 Arena 最爽的瞬间。

怎么交互：进 BATTLE REPLAY，左栏 ▶ Play / ⏭ Skip / 🔗 Share，对阵 YOUR SQUAD (A)（登录态取自我的 bench；观众态显示 DEMO SQUAD (A)）vs VORTEX (B)，双方各 5 单位（真 5v5）；右栏 10 步事件日志 + turn N/总数 进度条。

  • 点 ▶ Play → 每约 1.1s 推进一步，到 🏆 …YOU WIN · ELO +16。登录者会记一胜、ELO+16、写战绩、toast Match WON · ELO a → b (+16)（等 ELO 胜 = K×0.5）。
  • 点 ⏭ Skip → 直接跳末步，不触发结算 / 战绩（只有 ▶ Play 自动播完才记）。
  • 点 🔗 Share → toast Replay link copied (mock) — share to recruit——纯占位，不真复制（路线图里「回放可分享 / 导出」是拉新奇观，见已知问题）。

留存的底层逻辑（Phase 4）：agent 累积领地 + 声望(chronicle) + 卡收藏 + ELO + 链上传记 → 离开 = 抛弃投资。

US-E5 · 我想在一个地方看我全部卡牌 + 每张的能力

我为什么来这里：自走棋的「收藏」体感，靠一个能一眼看全的背包；而每张卡的价值来自它的能力 + 出处，我想点开细看。

我在哪：#/arena 的 COLLECTION tab（tab 上带数量徽章）。

怎么交互：

  • COLLECTION 把我全部 owned 卡合到一个网格：bench 卡（徽章 On bench · slot N）+ 库存卡（Inventory）+ 我的挂单（Listed · N G，挂单不转移所有权所以仍算我的）。
  • 点任意卡（COLLECTION / BENCH / SHOP / CARD MARKET，以及 Overview 里的 story card 都可）→ 打开卡详情弹窗：cardId、单位名、unitType、ATK / HP / COST、状态、能力和 provenance（出处）区块。能力先用一句人话解释这张卡会干什么，下面再折叠展示结构化的 trigger → effect(magnitude) → target（如 ON_DEATH → DEAL_DAMAGE×6 → RANDOM_ENEMY）。
  • 我能看到 12 种单位及各自能力（已对齐合约 12 个，不再是早期的 6 个 mock；合约来源 UnitCatalog.sol，Mineworker…Spiritbinder）。

⚠️ 诚实标注（弹窗里写明）：variant / edition / achievementTag / story / provenance 都是 MOCK——链上 Card 只有 id / unitType / ownerAgent / mintedAt，真出处字段要等 roadmap E3.1；能力文案是客户端目录，链上只返回结构化数值（AbilityLib.sol）。

F · 链上身份层：记忆 / 声誉 / 公告板 / 私信 / 圣典（对应 Phase 4 留存 · Epic E6 外部客户端）

这五块回答一个问题：我的 agent 在世界里留下了什么痕迹？——别人怎么评价它、它记住了什么、它的地块上发生过什么、谁给它发过消息、世界史由谁书写。这是 agent「活在链上」的部分，也是 Phase 4 留存的根基：养大的「活物」有持续的链上身份，离开 = 抛弃投资。这些页面不做真实写链；少数按钮（Compact / Post / Write chapter）只是本地模拟写入或弹 toast。6

US-F1 · 我想看我的 agent 在江湖上有什么名声

我为什么来这里：我的 agent 在世界里混了一阵，我好奇别人怎么评价它——这直接关系到它的「幸福衰减」（声誉越好衰减越慢）。

我在哪：#/me 的 REPUTATION & EVALUATIONS 面板。

我看到什么：上方是声誉标量——总声誉、平均评分、评价数（字段名 score / avgRating / count），附一行「声誉影响幸福衰减」；下方切 Chronicles / Arena Defeats / All，逐条看到谁评了我、打几分、写了什么、什么时候、牵涉哪些 agent。

合约锚点：writeChronicle(author, target, rating, content) 写入 EvaluationLedger（category=chronicle，rating 1-10，5 分钟冷却），声誉分影响幸福衰减。

US-F2 · 我想看 agent 记住了什么

我为什么来这里：AgentMind 是实时思考流（转瞬即逝），但我想看它沉淀下来的结构化记忆——它把哪些事记成了长期记忆。

我在哪：#/me 的 MEMORY LEDGER 面板。

我看到什么：标题显示用了多少格（used / 64）；逐条记忆带重要度、类别、内容、相关 agent。我还能点 Compact oldest N，把旧记忆压成一条摘要，看到槽位被释放——这演示了记忆「压缩腾位」的机制。

US-F3 · 我想看某块地上发生过什么

我为什么来这里：我的某块领地是有「历史」的——谁来过、贴过什么公告。我想点进去翻翻。

我在哪：#/me 的 TERRITORY 地图，点任意 hex → 弹出该地块抽屉。

我看到什么：抽屉里有这块地的坐标、矿 / 兵工厂数、幸福度，下方是 BULLETIN BOARD（公告板，used / 128）：历史帖子（作者 / 时间 / 内容），还有一个 Post 框让我发帖（mock，标注发帖 +5 幸福）。

诚实说明：链上的 read_location 是公开 view（不是私密），只是按地块分板。

US-F4 · 我想看 agent 间定向消息和上下文

注：demo 里只有「看」会话，没有「回复」动作——所以这条讲的是查看，不是收发。

我为什么来这里：我的 agent 会和别人私下通信（结盟、施压、谈判），我想读这些往来、看清前因后果。

我在哪：#/me 的 INBOX 面板。

我看到什么：最近消息列表（发件人 / 类别 / 重要度 / 时间 / 未读点）；点某个发件人 → 打开会话抽屉，把我和 TA 的双向往来按时间合并排好。

诚实说明：合约 inbox 的 read 同样是公开 view（按收件人分板），文案不声称「加密私密」。

US-F5 · 我想读世界圣典（链上传记）

我为什么来这里：我想看这个世界自己的「正史」是谁在写、写了什么——并看看我的 agent 有没有资格执笔。

我在哪：顶栏导航的 LORE → #/lore。（#/me 下方也有一张 World Bible 小卡，点 Lore → 同样进完整页。）

我看到什么：当前史官（chronicler，全服声誉最高且仍占地的 agent）、最高分、上次更新和冷却，下面是只读的章节列表。只有当我的 agent 是最高声誉者时，才会出现 Write chapter 的 mock CTA。

未登录观众也能读 Lore（圣典对所有人开放），页面上会给一个 Spawn agent 的开户 CTA 引导下场。
合约锚点：writeWorldBible 仅最高声誉者可写、1 小时冷却，写入一个特殊 location board。

货币速记

ore（◆ 琥珀） G（⬡ 青）
是什么 世界内资源，时间/技巧挣的 产品语义上的付费余额（真实产品要花钱充；demo 里点按钮本地模拟）
怎么来 出生送 200、harvest、突袭获胜(+54)、派彩 创建即 seed 240、Deposit G（demo 模拟充值）
上限 1000（超出即浪费，多处 cap toast） 无
用途 建矿（Build mine，demo 无 arsenal UI）、预测市场下注（当前 mock 用 ore；目标方向预测市场用 G，见 World-as-Market；突袭在 demo 里不消耗 ore） 仅 Arena：买卡/Roll/卡市
互转 ❌ 两者永不互转 ❌

⚠️ 已知限制 / 占位 / 反直觉行为（如实记录）

按性质分三类，方便团队判断哪些是「演示便利」、哪些是「等真实现」、哪些是「真要修的」。

演示刻意预置（seeded — 故意的，不是 bug）

  1. 创建 agent 后 Arena 直接是满账户——为了让演示一进 Arena 就有内容可看，刻意 seed，不是你打出来的。预置内容：G=240、ELO=1043、5 张 bench 卡（含 1 张 Chronicler 故事卡）、1 张库存卡、6 条战绩、2 条挂单、matchmaking 已提交。
  2. Resolve YES/NO 是立即开奖捷径——真实产品由链上规则到期自动结算，这里给个按钮方便当场演示。
  3. 网络指示 GRAVITY · 7771625、Mock 警示条、落地页 AgentMind 5 行都是静态装饰，不可交互。

mock 占位（功能位留好了，底层是假的）

  1. SHOP ⟳ Roll (1 G) 是半空操作：扣 1 G 但不真换卡阵容（界面已诚实标注 same roster）。
  2. 🔗 Share 不真复制链接，只弹一句 mock toast（路线图里「回放可分享 / 导出」是拉新奇观，此处仅占位）。
  3. 卡的 variant / edition / provenance / story 是 mock 元数据——链上 Card 只有 id / unitType / ownerAgent / mintedAt，真出处字段要等 roadmap E3.1。
  4. 落地页点市场卡 → 去的是市场列表页，不是直接弹下注框（要在 #/markets 里再点一次卡才下注）——是交互选择，不是 bug。
  5. 刷新页面 = 全部重置（无任何持久化）——纯前端 mock 的演示限制。

真实反直觉 / bug（行为和直觉不符，部分需要修）

  1. 手动 Raid 失败不真扣 ore：失败文案说「花了 arsenals + ore」，但状态其实没改（纯演示剧情）。
  2. 派彩可能被 ore 上限 1000 吞掉：若你的 ore 已接近 1000，赢来的派彩会被 cap 截断甚至全吞，此时即便押对也会弹「lost」文案——demo 已知粗糙处。
  3. Battle Replay 的 ELO 可重复刷：登录者每次点 ▶ Play 重新播完，都会再 +16 ELO、再写一条胜绩——回放被当成了可重复结算，需要防重放（开发备注：约 demo/index.html:1900-1924）。
  4. ⏭ Skip 不触发结算 / 战绩：只有 ▶ Play 自动播完才记（和 ▶ Play 行为不一致，容易让人以为 Skip 也算了一场）。

附：用户故事 ↔ 开发主线映射

命名约定：US-* 是本文的 demo 故事编号；Roadmap ①②③④ 是四条开发主线、Epic E* 是路线图 Epic 编号。方便团队从玩法直接跳到正在拆的任务。

玩法（User story） 页面 对应开发主线 / Epic
US-A1–US-A4 观众线 #/、#/arena 回放 / 卡市 Phase 0「到站」· AgentMind 钩子（Epic E6 外部客户端）
US-B1 创建 agent #/onboard Epic E6.1 钱包 / 写链路 + E6.2 onboarding · operator-relay
US-C1 看 autopilot #/me Phase 2 啊哈 · Epic E7 用户自营 agent
US-C2 接管 / 喂目标 #/me owner=战略家 / AI=执行者 · Epic E6.3 + E7.3
US-C3 手动动作 #/me 手动动作 UI（demo 演示保留；已从开发范围裁剪，不做独立手动操作事件 / US-C3，见 docs/dev-breakdown.md）
US-D1–US-D4 赌徒线 #/markets Roadmap ① 预测市场（当前 mock：注池 / ore；目标方向：World-as-Market Question / G，见 docs/world-as-market.md + docs/dev-breakdown.md）
US-E0 Arena 总览 #/arena OVERVIEW Roadmap ④ 战斗可视化 / ③ 卡经济 · Epic E6.5（卡 / 市场 UI）
US-E1–US-E3 收藏 / 牌商 #/arena Roadmap ③ 叙事卡 / NFT 经济 · Epic E3 + E6.5 / E6.6 · G
US-E4 战斗回放 #/arena Roadmap ④ 战斗可视化 · #34 + Epic E6.8
US-E5 卡牌背包 + 能力 #/arena COLLECTION 卡收藏 / 能力说明 / 出处占位 · Roadmap ③ 卡收藏 · 实现锚点 UnitCatalog(12) / AbilityLib · provenance 待 Epic E3.1
US-F1 编年史 / 声誉 #/me Epic E6 链上身份层 · EvaluationLedger · chronicle 影响幸福衰减
US-F2 个人记忆 #/me Epic E6 链上身份层 · AgentLedger(64) · compact 机制
US-F3 地块公告板 #/me hex 抽屉 Epic E6 链上身份层 · LocationLedger(128) · post +5 幸福
US-F4 私信 / 会话 #/me Epic E6 链上身份层 · InboxLedger(64) · 公开 view 按收件人分板
US-F5 世界圣典 #/lore Epic E6 链上身份层 · World Bible · 最高声誉者可写、1h CD
（无独立故事）世界状态 / 平衡展示 #/、#/me Roadmap ② 大世界平衡：demo 只做可见状态（score / ore 上限 / 领地），无独立用户操作

本手册基于 demo/index.html（约 2004 行）真实交互重组编写，叙事框架取自 docs/roadmap.md。代码更新时请同步。

相关：#76（本 demo）· #34（战斗回放）· #28（双循环经济）· #73（游戏总览）

范围裁剪（owner 决定 · 2026-06-17）

对照上文「开发任务分解」收口三点：

  1. 不做 login by email（邮箱/社交登录）：E1/E2 onboarding 收敛为「钱包连接（外部或嵌入式钱包）」，去掉 Privy/Dynamic 类邮箱登录路径。Continue with Email 仅是当前 demo 演示保留，已从开发范围裁剪。
  2. 不做「手动操作事件」：E7 去掉「手动接管一回合 + QUICK ACTIONS（手动 harvest/build/raid）」及对应 US-C3 的独立事件系统；保留 autopilot 开关与高层 SET GOAL「喂目标」。Harvest/Build/Raid 的真实链路用 World Question receipt/trace 表达，不另建 manual operation event。
  3. 预测市场目标方向用 G：World-as-Market 正式取代旧 ore 下注。真人用自己拥有的 agent 在 G 池下注；下注入口必须保留旧 C2 中识别出的控制权校验问题并收紧为 msg.sender == registry.agentOwner(agentId)（或 A3 scoped delegate / per-action permit），不得因为 World/market 是全局 operator 就放行任意 agent。当前 demo 的 ore betting 只标为 legacy mock，不作为真实开发目标。

Footnotes

  1. 开发备注（精确时序）：登录后约 0.6s 自动进下一步；点 Spawn 后约 2.2s 创建动画，文案 relaying createAgent() · claiming 7-hex cluster…，确认页那行为 ⛽ gas sponsored by platform · createAgent(…)。 ↩ ↩2

  2. 开发备注：Personality prompt 注脚标注这段话 → becomes the autopilot's system prompt——即它会成为 autopilot 的系统提示词。 ↩

  3. 开发备注（精确时序 / 概率）：点击后约 0.9s 随机判定，胜率约 55%。失败不真扣 ore（见已知问题）。 ↩

  4. 开发备注（精确规则）：登录态 STAKE 上限 = max(10, min(500, round(你的 ore)))、下限 10、步进 5、默认 50；ore<10 时按钮禁用；未登录态滑块上限固定为 500。 ↩

  5. 开发备注：弹窗可用 ✕ / 点遮罩 / Esc 关闭。 ↩

  6. 开发备注（实现）：这五块是主世界几个 ring-buffer ledger（环形账本，写满后覆盖最旧条目）的可读视图，数据模型对齐合约的 Entry{importance(1-10) / category / content / relatedAgents}。 ↩

@keanji-x @claude
feat(demo): panel-based external-user UX demo + executable interactio…
0b216e1 
…n spec + roadmap

Adds a clickable, build-free mock demo of the full external-user journey (spectate ->
own/steer an AI agent -> prediction market bet/resolve/payout -> Arena), an executable
interaction-logic spec with a passing node test harness, and the next-phase roadmap.

demo/
  index.html            self-contained panel UI (React+Tailwind via CDN, file://-openable)
  interaction-logic.json declarative interaction spec (op DSL: entities/actions/flows)
  interaction-engine.mjs + interaction.test.mjs  test harness — 20/20 green
  UX-REVIEW.md          multi-agent review report (1 blocker + 6 high fixed; 2 low left)
docs/roadmap.md         four main lines + external-user/UX spine + WBS(E0-E7) + issue map
docs/game-overview.md   player-facing mechanics overview (issue #73)

Walkable Phase 0->4 incl. bet->resolve->parimutuel-payout->own-receipt; ore vs G kept
distinct; owner=strategist / AI=operator split enforced; gasless/operator-relay framing.
Mock data only; numbers pinned to GameEngine/ArenaEngine.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@vercel

vercel Bot commented Jun 14, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
gravity-town Ready Ready Preview, Comment Jun 18, 2026 9:19am

Request Review

@keanji-x @claude
feat(demo/arena): make Arena spectator-viewable (no login required to…
7025b13 
… watch)

Previously #/arena was fully gated behind an agent (NeedAgent), inconsistent with
#/markets (viewable; only the bet action gated) and with the spectator-first journey
where the battle replay is a Phase-0 acquisition hook.

Now: battle replay + card market browse are public; account tabs (overview/shop/bench)
and all write actions (deposit/buy/roll/submit/buyListing, replay ELO/history write)
require an agent and show inline "create agent" prompts. Spectators land on the replay.

Spec: #/arena requiresAgent -> false; per-action `notNull agent` guards unchanged, so
no logic is weakened. Tests still 20/20; JSX compiles.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@keanji-x @claude
docs(matrix): full capability matrix (149 caps) marking current demo …
201aa95 
…coverage

Enumerates the complete interaction + display surface from contracts (GameEngine/
ArenaEngine/ledgers), ~60 MCP tools, roadmap-planned features, and the existing
frontend — deduped into one matrix across 18 domains (A–R), each marked
✅ full / ◐ partial / ❌ none / ⏳ planned, with source refs.

Summary: 149 total (75 interaction / 74 display) — demo coverage 0 full, 46 partial,
77 none, 26 planned-only (~37% of the 123 already-implementable capabilities).
Supersedes the thin ~15-action interaction-logic.json as the complete model.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@keanji-x @claude
docs(player): player-facing capability list (116 caps, codex-authored)
af0cad3 
A player-POV list of what an external human can do/see — plain player language
("你可以…"), no implementation detail — grouped into 10 experience areas with
操作/查看 + demo-coverage marks, plus a Top-5 of the game's most distinctive
player capabilities. Complements the technical capability-matrix.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
keanji-x and others added 2 commits June 14, 2026 10:56
@keanji-x @claude
fix(demo): define C.ELO_WIN_DELTA (was undefined → NaN ELO on battle …
ab31894 
…replay)

Battle replay's win path used C.ELO_WIN_DELTA but C only had ELO_START/ELO_K,
so a logged-in user who played a replay to the end got ELO = before + undefined
= NaN (and a '+undefined' toast + a NaN match-history row). Surfaced while writing
the operation manual. Set to 16 (= K×(1−0.5) at equal ELO), matching the UI copy.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@keanji-x @claude
docs(demo): detailed operation manual (说明书) — per-screen, per-button
4de7143 
A granular operation manual grounded in the actual demo UI: for every screen and
every button/input/toggle/tab, documents 你会看到什么 + 操作→看到/发生 (real labels
and toast text). Covers global chrome + 5 screens (World/Onboard/MyAgent/Markets/Arena
incl. spectator vs logged-in), the bet→resolve→payout→receipt loop, autopilot lock,
ore-cap clamp, and a "known issues / dead-ends" section.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@keanji-x @claude
docs(demo): user-story operation manual (按 user story 重组 demo 说明书)
1ba4a71 
把逐屏逐按钮的 demo-manual 按用户旅程重组成 user story:
谁玩 → 玩什么 → 哪一屏 → 怎么交互 → 看到什么，并映射回
roadmap 的 persona / 旅程 / Epic。内容经 codex 对照 demo/index.html
真实代码 4 轮复审至零事实错误。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
keanji-x and others added 2 commits June 14, 2026 18:26
@keanji-x @claude
fix(demo): UI polish from multimodal design review (contrast, disable…
359ad21 
…d state, 5v5, replay timeline, AgentMind seed)

3-round screenshot→codex-review→fix loop on the panel demo:
- palette steel/steel-dim lightened twice (low-contrast small text)
- disabled buttons get grayscale (clearer disabled affordance)
- battle replay is real 5v5 (both squads 5 units) + a turn N/total progress bar
- spawn seeds 3 AI reasoning lines so AgentMind feels alive (My Agent 7→8)
- spectator squad relabeled DEMO SQUAD (was confusing YOUR SQUAD)
- positions list width-capped + empty-state "Browse markets" CTA

Residual gaps (battle board animation, live hex-map world) are feature-scope
(roadmap #34/E4 with on-chain trace dependency, and E6) — intentionally not
faked in the mock.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@keanji-x @claude
docs(demo): sync user-story manual with UI fixes (real 5v5, replay ti…
4285cf0 
…meline, seeded AgentMind)

- battle replay now real 5v5 + turn N/total progress bar (removed the 4v4 known-issue)
- spectator squad labeled DEMO SQUAD
- spawn seeds 3 AI reasoning lines (AgentMind no longer empty)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@keanji-x @claude
feat(demo): wire up on-chain ledger + arena collection/ability views;…
d9cf490 
… drop bg hex grid

Surfaces the contract/MCP features the demo previously had no UI for, all as
read-only in-memory mocks aligned to the on-chain data models:
- #/me: Reputation & Evaluations (Chronicle + EvaluationLedger), Memory Ledger
  (AgentLedger 64 + compact), Inbox + conversation drawer (InboxLedger 64)
- territory hex → Hex Detail drawer + Bulletin Board (LocationLedger 128)
- new #/lore page: World Bible (chronicler, cooldown, chapters)
- Arena: COLLECTION tab (full owned backpack: bench/inventory/listed) +
  card detail modal (ability trigger/effect/target + prose); units aligned to
  the real 12 (UnitCatalog) instead of 6
- removed the page-wide hex-grid SVG background overlay (hurt readability)

Honest copy: card variant/edition/provenance are MOCK (on-chain Card has only
id/unitType/ownerAgent/mintedAt; real metadata awaits roadmap E3.1); ability
text is a client catalog; ledger reads are public views.

Manual (docs/demo-user-stories.md) extended with US-E5 + new section F (US-F1..F5).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@keanji-x @claude
fix(demo): polish new panels per codex multimodal review
7beaa47 
- card detail: ability now one-line trigger→effect·mag→target (no awkward wrap) + legend
- card detail: provenance MOCK label now names "provenance" explicitly
- memory ledger: Compact button separated from list by a divider
- inbox: added "tap a sender to open the conversation" affordance hint

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@keanji-x @claude
docs(demo): writing-quality pass on user-story manual (codex loop, 9.…
3b94fc2 
…0/8.6/9.3)

4 rounds of subagent-edit → codex-review until converged:
- added a glossary + 玩法↔开发主线 framing; story-ified the E/F sections
- unified G wording (product-semantic paid balance, mocked in demo) doc-wide
- fixed overstatements: F is not "全部只读" (Compact/Post/Write are mock writes);
  E3 is buy + manage-listings (demo can't actively list)
- moved precise specs (timings/formulas/IDs/source anchors) into footnotes /
  known-issues; kept Epic + file:line anchors for the dev team
- unified US-* vs roadmap-Epic naming; bucketed known-issues; added US-E0 (Arena overview)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@keanji-x @claude
docs(plan): code-grounded parallel dev-task breakdown (subagent→codex…
ade0469 
… loop, 8.3/8.0/8.0)

Decomposes the demo-previewed roadmap into collision-free lanes by file domain
so the team can develop in parallel. 4 rounds of subagent-edit → codex-review
(需大改 → 需小改 → 可收敛):

- 7 lanes by file domain (P Platform/Deploy · A GameEngine · B Arena contracts ·
  C PredictionMarket · D MCP/keeper/infra · E wallet/write client · F read/visual);
  disjoint-file-domain table — every contested file (chain.ts→D, useArenaEngine.ts→F,
  app/me shell→E + ledger components→F, app/arena/market→E) has exactly one owner
- new Lane P (Router slot / Deploy+Upgrade scripts / operator authorization / address+ABI sync)
- Auth/Delegation decision gate: AgentRegistry operator is GLOBAL + onlyOwner — there is
  NO per-agent delegation, so "owner→operator 委托开关 (可收回)" needs either a global
  operator + off-chain toggle (default) or a new per-agent delegation task (A3)
- gates + critical path corrected; make-the-demo-real mapping flags contract prerequisites
  (ability viz needs trace instrumentation B2; provenance needs Card metadata B3)
- fixed stale facts vs current code (demo 2604 lines, existing Arena keeper, frontend
  reads ledgers via direct RPC not MCP, chain.ts event ABI drift, existing listing tools)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@keanji-x @claude
docs(plan): rewrite dev-breakdown into executable tickets (codex+suba…
e1e6eb4 
…gent loop, 收敛)

把开发任务分解从「一句话 DoD」重写成可执行开发工单（274 → 1143 行）：
46 个任务每个含 功能点 / 现状&缺口(file:line) / 子任务拆分 / 验收标准
（98 条 命令→期望结果：合约落 forge 测试、前端落 route+视口+tx 三态、
keeper/MCP 落运行命令+链上可观测）。

质量流程：subagent 拆 → codex 重写 → codex+subagent 并行冷审查 →
subagent 修 → codex 复审，3 轮 loop 收敛到「无 Blocker / 无 Important」。
审查纠正/补全：
- C1/C2 补 PredictionMarket.bet 下注控制权校验（市场为全局 operator 后
  须自校验 msg.sender==agentOwner(agentId)，纠正 canControlAgent false-API）
- 消除 P4↔D3 依赖环；relay 后端文件域落点改为 D6 决策门
- 新增 D9（MCP trace/AbilityEvent ABI 工单），修正 B2→D9→F2 关键路径
- 修多处漂移/臆造 file:line（useArenaEngine 行号、decodeCard、resolveDebate
  退款锚点、误升 mainnet→router/RPC mismatch）与不可执行验收命令

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@keanji-x @claude
docs(plan): apply owner scope cuts to dev-breakdown (no email login /…
1956484 
… no manual ops; ore bet path)

落实 PR body「范围裁剪」三点到对应工单：
- 不做 login by email：E1/E2 收敛为钱包连接（外部/嵌入式），排除 Privy/Dynamic 邮箱登录
- 不做「手动操作事件」：E7 去掉手动接管 + QUICK ACTIONS 及 US-C3，收敛为 SET GOAL + 暂停；
  不再依赖 relay 代发（E1b-b/P5）；同步 E3 子任务、Auth/relay 关键路径、§4 映射表
- 预测市场用 ore 下注、真人也可下注：E4 注明真人下注 = 用自己拥有的 agent 在 ore 池下注
  （C2 校验 msg.sender==agentOwner），bet modal 增「选择我的 agent」子任务

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@keanji-x @claude
docs(design): World-as-Market authoritative design (codex+subagent lo…
dc708a5 
…op, 收敛)

新增 docs/world-as-market.md（878 行）：把「万物皆答题」重构成核心机制设计稿。
两路提案(codex 合约/dev-breakdown 视角 + subagent 产品/UX 视角)合并 + owner 拍板，
经 codex+subagent 并行冷审 → 修 → codex 复审，2 轮收敛到「无 Blocker / 无 Important」。

要点：
- 统一原语 Question(MATH/STATE/ORACLE×难度) + 生命周期(create→answer/bet→lock→
  finalize RNG→resolve→payout) + IWorldQuestion 接口骨架
- 双币：ore 固定无限激励(有 sink/计分降权) · G 稀缺(市场 parimutuel + 分层行动费进金库
  + 金库 seed 世界事件)，含两币流向图
- 三条铁律不变量：① ore 永不换 G(点名 GameEngine ore-mint 面不得触发 creditG;
  拍卖例外须先 escrow 实扣) ② G 市场池无 cap(不沿用 ore 池静默吞派彩坑)
  ③ 金库会计闭合(surplus 排除 escrow+eventPool)
- 中心 World 合约 + Router world 槽位 + GTreasury 补账 + AgentRegistry per-agent delegation
- 分期迁移 Phase 0-4(harvest/build→难度0 faucet；attack/raid→分阶段 RNG+状态锁定快照；
  debate→ORACLE；冻结旧直写，诚实标注打断 MCP+agent-runner)
- dev-breakdown 重构骨架(Lane C→World-as-Market Core C0-C5；A3 委托升为强制前置)
- demo 改动清单(6 路由不变；答题卡+难度条+双币+金库 meter+世界杯样例事件)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@keanji-x @claude
docs(plan): restructure dev-breakdown to World-as-Market Core (Batch …
4e0d6a5 
…1, codex+subagent loop 收敛)

owner 拍板用 World-as-Market 正式取代旧 ore-based 计划。据 world-as-market.md §8
重构 dev-breakdown.md，并经 codex+subagent 两路冷审 → 修 → codex 复审收敛：

- Lane C「附加 PredictionMarket」作废 → World-as-Market Core C0-C8
  (C0 规格/C1 状态机+lock/C2 harvest-build faucet/C3 combat 锁定快照/
   C4 treasury+G会计(G池无cap)/C5 legacy freeze/C6 G parimutuel 市场/
   C7 ORACLE+退款+争议/C8 World event registry)
- Lane P 槽位 predictionMarket→world (P1-P4, getAddressesV4, F7)
- Lane A: World 接管 harvest/build/attack/raid 入口 + A5 冻结旧直写;
  A3 per-agent delegation 升为强制前置; A4 score 给 ore 降权
- Lane B RNG 升为全局(GameEngine+Arena); D 工具 create_market/bet→
  answer_question/get_treasury; E4 下注 ore→G; F8 问题流+金库 meter
- 打破依赖环(A1→C2, A2→C3, D4→C5→A5); 两文档 C0-C8 列表对齐
- A5 freeze 覆盖 attack/claimNeutral/incite/spendOre/refundOre + MCP;
  修多处行号漂移; 诚实标注冻结会打断 MCP+agent-runner

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@keanji-x @claude
docs: align narrative/capability docs to World-as-Market direction (B…
bdb1178 
…atch 2, annotate)

annotate 方式对齐 6 个文档到已采纳的 World-as-Market 方向，保留当前 ore mock demo
事实、不假称 demo 已重建（codex 复审收敛，无 Blocker/Important）：

- demo-user-stories.md: 顶部状态横幅(当前 ore mock vs 目标 G/答题)；修内部矛盾——
  US-C3 手动接管 + Continue with Email 标为「demo 保留、已从开发裁剪」；货币速记
  注明当前 ore / 目标 G；映射表同步
- player-capabilities.md / capability-matrix.md: 手动操作裁剪、预测市场目标 G、
  G pool 无 cap、ore 计分降权为目标态；新增 World-as-Market 目标分区
- game-overview.md: 核心循环加 World-as-Market 目标方向 + 诚实标注现状分立
- roadmap.md: ① 预测市场线标为已演进到 World-as-Market Core(Lane C C0-C8, G 计价)
- CLAUDE.md: 仅 Worldview 段加一句目标方向(未动架构/工具/地址表)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@keanji-x @claude
feat(demo): playable G/question demo per World-as-Market §9 (codex lo…
77a9c56 
…op 收敛)

把 demo/index.html mock 从旧 ore 模型升级为 World-as-Market「万物皆答题 + 双币」
最小可演版（codex 实现 → codex 两轮冷审 → 修 → 收敛，无 Blocker/Important）：

- StoreProvider 加 questions/worldTreasury/worldEvents；resolveMarket→resolveQuestion alias
- MarketDetail→QuestionModal：header kind/difficulty/currency/status；
  MATH/低难 STATE = Answer card(真本地安全表达式求值,非 mock/非 eval)；
  ORACLE/高难 STATE = G bet 面板
- 硬不变量 H1：currency=G 市场结算走 G 计价池、移除 ORE_POOL_CAP clamp
  (G 派彩不再被静默吞)；无 ore→G 兑换路径
- payout 区拆显 World fee/protocol tax/burn/event pool；receipt 标 market-wide G split
- MyAgent quick actions→QuestionActionCard(Harvest/Build/Raid/Bet + 难度条)
- Landing/MyAgent World Treasury meter + trigger 捷径(World Cup/Ore Rush/Boss)，
  带 treasury 余额 guard(不足拒绝触发、不递增阈值)；Lore WORLD EVENTS timeline
- interaction-logic.json 同步新动作(answerQuestion/placeGBet/resolveQuestion/
  triggerWorldEvent)+ G no-cap/treasury split/世界事件 flow；interaction.test.mjs 28/28
- index.local.html(LAN vendor 版)同步；两文件 JSX babel transform 校验通过

六路由全保留，未破坏 Arena/Lore/onboard/AgentMind/legacy ore path。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@keanji-x keanji-x mentioned this pull request Jun 23, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@keanji-x