McArena · 麦门 AI 竞技场
基于麦当劳中国 MCP 接入方案的双 Agent 点餐决策竞技平台——两种算法策略在同一任务卡与数据集上对决，独立裁判透明评分。公开演示使用明确标注的场景数据；官方 MCP 实时联调与返回 schema 校验尚未完成。
🖼 界面展示（真实截图）
以下截图来自生产构建 + 真实 Chrome 的 16 步链路实测（2026-10-15，控制台 0 错误 / 0 警告，证据见 docs/screenshots/stage07/），非设计稿：
| 首页（深色） | 竞技场（回放中） | 结果页（五维对比） |
|---|
| | |
| 挑战设置 | 结果页（浅色） | 移动端 |
| | |
动态演示：20 帧真实会话采集帧见 docs/screenshots/gif-frames/（采集器 tools/e2e/capture-demo-frames.mjs 可一键重采）。本环境不生成视频，GIF 合成命令见「演示 GIF」。
🎮 一局比赛是什么
一张任务卡（预算 × 人数 × 场景 × 约束）+ 两名风格迥异的点餐 Agent + 一位只认规则的裁判：
- ⚡ Agent α「极速猎手」（Speed Agent）：单遍贪心构造，只评估 1 个候选方案，用最低计算成本给出一个便宜、可预测的有效解；
- 🔬 Agent β「深度优化师」（Optimizer Agent）：束搜索枚举成百上千个候选购物车，逐一修复硬约束、按当前数据源计算价格，按「约束满足率 → 营养偏差 → 价格」择优；
- ⚖️ 独立智能裁判（Judge Engine）：需求满足度 / 预算控制 / 营养均衡 / 优惠利用 / 可解释性，五维打分、公式公开、证据可查。裁判不信任 Agent 自己报告的成绩——餐品存在性、单价、优惠、营养、应付价格全部由裁判基于当前数据集独立重算；只有取得官方
calculate-price 结果时才按官方核价标记，否则明确标注 NOT_VERIFIED；出现致命违规的方案直接失去获胜资格，无效方案不能凭低价取胜；每局产出可复现的 experimentId。
两名 Agent 的算法实质不同（贪心 vs 束搜索），基准测试实测差异：平均候选数 1 vs 134、平均工具调用 1 vs 4.75 次；模拟数据下 α 更便宜、β 营养与用券更优。两者均为算法型 Agent（未配置大模型，已明确标注），不得把固定输出冒充 AI 推理。
默认演示模式使用仓内场景数据，并明确标注为模拟数据。项目已实现麦当劳 MCP 客户端与只读工具调用链，但尚未取得 Token，因此没有真实菜单、价格或营养数据的联调证据；未经成功联调与校验的数据不会标为官方数据。
✨ 特性
- 麦当劳 MCP 集成（未完成实网验证）：实现 Streamable HTTP 客户端与只读工具白名单；真实连接和工具 schema 待 Token 到位后验证；
- 可复现：固定随机种子 + 数据快照哈希，同一局比赛任何人运行结果完全一致；
- 可解释：裁判每项得分都附带公式与证据，独立验证报告逐条列出违规（severity + 数据证据引用），拒绝黑箱；
- 无 Token 也能玩：默认使用仓内场景数据集（界面明确标注「模拟数据，非麦当劳官方数据」），克隆即可完整演示；完成字段映射与校验前，演示只使用明确标注的场景模拟数据；
- 安全：只读工具白名单，默认禁止任何下单写操作；
- WorkBuddy Skill：在 WorkBuddy 对话里说「来一场麦门竞技」即可开赛（见
skill/mc-arena/INSTALL.md）。
🔀 两种数据模式
| 模式 | 数据来源 | 需要 Token | 界面标识 | 用途 |
|---|
| 演示模式（默认） | 仓内场景数据集 scenario://stage03-fixtures | ❌ 不需要 | 黄色「模拟数据」徽标 | 克隆即可完整走通全链路，适合体验、教学、CI |
| 官方数据模式（待联调） | MCP Server 实时采集；原始快照的字段映射尚未完成 | ✅ 需要 | 仅在数据成功校验后显示官方来源 | 目标是使用官方菜单 / 价格 / 优惠 / 营养数据 |
- 演示模式输出中的每一处数据均带
dataOrigin: mock，绝不冒充官方数据；
- 快照采集工具目前只保存原始响应和 sha256 manifest，尚未完成将真实响应映射为比赛快照的步骤；
- 当前状态（如实说明）：MCP 客户端协议层通过假服务器契约测试；真实 live 联调与官方 schema 验证尚未完成（BLOCKED：尚无 MCP Token），快照字段映射也待完成——详见 MCP_INTEGRATION.md。
🚀 快速开始
环境要求
- Node.js ≥ 20（开发使用 22.x）
- npm ≥ 10
一键启动（演示模式，无需 Token）
git clone https://github.com/DorianChn/McArena.git
cd McArena
npm ci
npm run dev
# 前端 http://localhost:5173 ｜ API http://localhost:8787
官方 MCP 原始响应采集（需要麦当劳 MCP Token；比赛映射尚未完成）
当前版本尚未完成真实 Token 联调、官方响应 schema 校验及快照字段映射，不能据此运行官方菜单上的完整比赛。取得 Token 后可按 MCP_INTEGRATION.md 采集只读原始响应；在映射与校验完成前，演示仍使用明确标记的场景模拟数据。
命令行竞技（无需启动服务，本地完整体验）
npm run demo # 打一局比赛，输出中文战报（任务卡/双 Agent 指标/裁判结论）
npm run bench # 跑 8 个官方测试场景，输出双 Agent 五维对比表
npm run demo -w @mcarena/arena-core -- timeout # 演示：Agent 超时 → 降级恢复（明确标注）
npm run demo -w @mcarena/arena-core -- cancel # 演示：取消执行 → CANCELLED，不产出提案
--goal 可选：balanced / protein / low-sodium / low-cal / budget / none；
--mode 可选：auto（默认；当前官方快照目录为空，运行使用场景数据集）/ mock / replay / live。
质量检查
npm run lint # ESLint（typescript-eslint 类型感知规则）
npm run typecheck # TypeScript strict 全量检查
npm test # Vitest：契约 / 协议 / 编排 / API / 前端客户端
npm run build # 生产构建（API tsup 打包 + Web Vite 构建）
WorkBuddy 中使用
node skill/mc-arena/scripts/install.mjs # 安装到 ~/.workbuddy-ai/skills/mc-arena
node skill/mc-arena/scripts/parse-request.mjs "3个人 预算60 要低卡 外带"
node skill/mc-arena/scripts/run-match.mjs --people 2 --budget 60 --goal balanced --seed 42
安装后在 WorkBuddy 对话中说「来一场麦门竞技，2 个人 60 块要均衡搭配」即可触发。
Skill 不含业务逻辑，全部调用仓库内共享引擎（与网页同源）。详见
skill/mc-arena/SKILL.md、skill/mc-arena/INSTALL.md
与 docs/archive/STAGE_06_REPORT.md。开发过程记录见 workbuddy.md。
🎯 可复现 Demo 挑战
一条命令跑一局完整的「自定义挑战 → 双 Agent 决策 → 独立裁判 → 可复现配置」闭环：
npm run challenge -w @mcarena/arena-core -- --people 2 --budget 60 --goal balanced --seed 42
真实输出（2026-10-15 实测，演示模式）：
任务卡：自定义挑战 · 2 人堂食｜预算 ¥60、人均 500 kcal、人均蛋白 20g、必含标签 burger/side/drink
数据来源：mock（scenario://stage03-fixtures）｜比赛 ID match_mv9660tm_42
⚠ 阶段03 场景测试数据集（模拟数据，非麦当劳官方数据）
【α 极速猎手】[email protected]｜总分 78.5/100
自述应付 ¥22.00｜裁决成本 ¥22.00｜核价 not-verified｜资格 通过
实测 7ms｜候选 1｜工具调用 1
【β 深度优化师】[email protected]｜总分 79.6/100
自述应付 ¥25.00｜裁决成本 ¥25.00｜核价 not-verified｜资格 通过
实测 3ms｜候选 248｜工具调用 6
裁判结论：极速猎手胜出（五维总分 78.5 : 79.6 / 100）——双方均无官方核价记录（NOT_VERIFIED），按裁判重算成本比较，α更低（¥22.00 : ¥25.00）
规则 judge-rules/1.1.0｜实验 exp_bcc724febf31e0b8｜成本依据 claimed-unverified
同一 seed 重复运行得到同一 experimentId（该 ID 已在 2026-10-14 的阶段06 实测中复现）。输出末尾会给出 reproducibleConfig——粘贴到网页「挑战设置」或同种子重跑即可复现同一局。
📖 使用案例
- 多人聚餐预算分配：3 个人、¥60、要高蛋白——看 β 如何在 248 个候选里找出满足硬约束且营养偏差最小的组合，而 α 用 1 个候选闪电给出便宜解；
- 「省钱 vs 吃好」的量化对比：同一任务卡下，用裁判五维图表直接比较两种策略的预算控制 / 营养均衡 / 优惠利用得分；
- MCP 决策类应用的工程范本：把「快照录制 + 规则裁判 + 证据链」三件套迁移到任何基于 MCP 的决策场景，用于回归测试与公平评测；
- 可解释 AI 教学演示：雷达图 + 决策时间轴 + 逐项公式，让「Agent 如何点餐、裁判如何打分」肉眼可见；
- WorkBuddy 对话内开赛：自然语言「来一场麦门竞技，2 个人 60 块要均衡搭配」即可触发完整比赛并返回可分享战报。
This is the beginning of the README. Read the rest at the original. Read the full README ↗
