MARL Cop & Thief - 基于 MCP 的双 AI 智能体

一个去中心化、部分可观测的追捕游戏，由两个自主 AI 智能体——警察和小偷——通过 MCP 服务器以自由自然语言交流，使用博弈论极小极大 + 自对弈强化学习引擎决定移动，在网页控制面板中实时渲染，并通过 Gmail API 发送双方同意的 JSON 比赛报告。

University of Haifa · AI 智能体编排 (ex06) · Dr. Yoram Segal. 一条命令启动一切；一个浏览器标签页运行整场比赛。

亮点

• 一键节点 - python -m cop_thief.app 同时启动两个 MCP 服务器、公共 Cloudflare 隧道以及浏览器控制面板（无孤立隧道，无端口冲突）。

• 网页控制面板 - 实时节点状态、可复制的公共 URL/令牌、对手挑战表单、一键镜像自测，以及实时 5×5 游戏电视 - 全部位于 http://127.0.0.1:8800。

• 真实策略 - 天使–魔鬼极小极大引擎（零和马尔可夫博弈，alpha-beta）配合 Conway 阻挡游戏（警察 = 魔鬼墙 §4.3）和自对弈强化学习权重学习，远超作业基线的表格 Q。参见 docs/STRATEGY.md。

• 去中心化且防作弊 - 无裁判；双方对结果进行哈希（SHA-256），任何分歧均计 0/0。入站文本被视为敌意：提示注入/胁迫被筛查、记录为证据，且无法改变结果（不存在弃权动作）。

• 单一 SDK 边界 + API 门卫 - 所有逻辑位于 CopThiefSDK 之后；每个外部调用（LLM、Gmail）都通过 FIFO 背压门卫，并具有 DeepSeek→Anthropic 故障转移。

• 质量门 - pytest ≥ 85% 覆盖率、零违规 ruff、每文件 ≤ 150 行、仅 uv。

Related MCP server: Police MCP Server

快速开始

uv sync                                   # install (uv is the ONLY package manager)
cp .env-example .env                      # fill in real values (see "Secrets")
uv run ruff check .                       # zero-violation lint gate
uv run pytest                             # full suite (>=85% coverage gate)
uv run python -m cop_thief.app            # launch the control panel + servers + tunnels

然后打开 http://127.0.0.1:8800。

进行比赛（控制面板）

1. uv run python -m cop_thief.app → 面板打开；等待 Servers ● 和 Tunnels ● 变绿。

2. 状态卡片显示你的两个公共 …/mcp/ URL + 每个角色的令牌（复制按钮）。将这些发送给你的对手，连同 docs/INTER_GROUP_TREATY_SPEC.md。使用 match_setup/ 中的填写表单（RULES.txt、OUR_DETAILS、OPPONENT_DETAILS）。

3. 将对手的两个 …/mcp/ URL（以及令牌，如果有）粘贴到挑战表单中，然后开始挑战 - 6 个子游戏在电视上跨主机进行，报告通过电子邮件发送。

4. 还没有伙伴？点击 MIRROR SELF-TEST ⟳ - 它会填充你自己的 localhost 端点和令牌，并让你与自己比赛（非常适合策略测试）。

一场游戏 = 6 个子游戏（根据 §4.1）：我们扮演 3 次警察（主场）和 3 次小偷（客场），小偷先手，每局最多 25 步。得分不可更改：警察捕获 → 20 / 5；小偷存活 → 5 / 10。

截图

控制面板 - 节点状态（Servers/Tunnels/Game）、我们可共享的 …/mcp/ URL + 带复制按钮的令牌、对手挑战表单以及实时游戏。这里正在运行镜像自测；注意 [INTENT: BARRIER] 行（警察封锁相邻单元格并保持不动，§4.3）、绿色 B 屏障和 ! 捕获。

实时棋盘 - 5×5 网格，警察 C（蓝色）和小偷 T（红色），旁边是通信拦截源，显示自然语言 [INTENT: MOVE] 传输以及 HOME LEG / Sub-game 分隔符。

回合转换 - 跑步者进入 AWAY LEG（我们扮演小偷）在第 4/6 个子游戏，棋盘上仍有 B 屏障和 ! 捕获。

启动节点会将可共享端点打印到终端（一个进程：服务器 + 隧道 + 面板）：

Control panel  >  http://127.0.0.1:8800   (open in a browser)
╔══════════════════════════════════════════════════════════════════╗
║ LIVE PUBLIC MATRIX (Team Alpha)                                   ║
╠══════════════════════════════════════════════════════════════════╣
║ COP   (:8001)  https://acting-tomorrow-yard-raid.trycloudflare.com/mcp/   ║
║ THIEF (:8002)  https://dial-mean-courses-tramadol.trycloudflare.com/mcp/  ║
╚══════════════════════════════════════════════════════════════════╝
Tunnels live and written to config/setup.json. Share these /mcp/ URLs. Ctrl+C to stop.

架构

入口点

策略简述

每个 request_move 都由深度受限的 alpha-beta 极小极大算法在零和马尔可夫博弈中回答（警察最大化，小偷最小化，最优对手假设）。进度形状的终局得分（±WIN ∓ turns）使策略追求捕获/生存，因此结构上避免了平局。警察的动作集包括封锁相邻单元格（Conway "魔鬼" 移动，§4.3）；评估的遏制特征是小偷的泛洪填充逃生区域，因此规划器自行发现合法的驱赶至陷阱的路线。线性评估权重可通过自对弈 TD（selfplay.train_weights）调整。三种变体配置（激进 / 平衡 / 防守）满足所需的 3 智能体阵容。完整设计：docs/STRATEGY.md。

形式化模型 - Dec-POMDP

追捕被建模为去中心化、部分可观测的马尔可夫决策过程，元组 ⟨ n, S, {Aᵢ}, P, R, {Ωᵢ}, O, γ ⟩（ex06 §11）：

编排挑战（难点）

根据 ex06 §14，作业的价值在于编排，而非胜利。难题及我们的解决方案：

• 自由自然语言，无预定义协议。 智能体以散文形式对话。我们叠加一层薄确定性契约——每条消息以恰好一个路标 [INTENT: MOVE|BARRIER|HOLD] 开头，后接一个罗盘词——因此动作可被机器解析，而正文保持自由自然语言。这使得两个独立构建的引擎无需共享代码库即可保持同步。

• 语言歧义与不可信输入。 入站散文被确定性解析（最长匹配方向词、仅限括号的意图，因此修饰性文本无法伪造它），并带有可选的 LLM 解析以处理非结构化对手文本；低置信度 → 安全的探索性回退（绝不崩溃，绝不伪造吃子）。每个字段都被视为敌意输入——例如，非数字的 variant 会被强制转换，绝不信任。

• 确保相互理解。 双方对等节点共享确定性动作语言（编码/解析无需 LLM），因此对局可逐字节复现。结束时双方对规范化的 sub_games 进行哈希（SHA-256, K3）；任何不匹配 ⇒ 双方均记 0/0——一致性是被强制执行的，而非假设的。

• 在不可靠网络上的活性。 跨主机动作带重连重试；持续中断或冻结的对等节点（每步 20 秒超时）判负该子对局，因此系列赛始终完成全部 6 局，报告仍会发送邮件——死掉的对手永远无法拖延比赛。

可视化与结论性证明（§11）

• GUI——上方 截图 展示了实时 5×5 棋盘、[INTENT: …] 通信截获流、屏障（B）、吃子（!）以及回合过渡。

• 云端 MCP 通信——上方启动块打印了实时公共 Cloudflare /mcp/ URL，面板的通信流实时传输与云服务器交换的真实 [INTENT:] 传输；每一步也会追加到 data/game_audit.jsonl，并封存到防篡改的每局归档中（data/archive/，报告内含捆绑 SHA-256）。

• 学习——策略权重通过自对弈 TD（selfplay.train_weights）调优；保留表格型 Q-learning 基线以供对比。设计与曲线：docs/STRATEGY.md。

安全与公平竞赛

• 令牌——每次 MCP 工具调用都需要按角色可撤销的 bearer 令牌；带外交换，可轮换以撤销。服务器默认失败关闭。

• 防注入——入站传输不可信；注入/强制转换/冒充/伪造均被筛查，在 data/game_audit.jsonl 中标记为 hostile:true，计入报告，且对引擎决定的结果无任何影响。在条约（§F）中为对手明文规定。

• 相互一致——双方对规范化的 sub_games 进行哈希；任何不匹配 ⇒ 0/0（both_lose）。

• 报告——通过 OAuth2 Desktop 使用 Gmail API（范围 gmail.modify，零密码）；组名同时出现在主题行和 JSON 正文中；安全防护默认使用一次性收件箱。

令牌预算与成本

每次外部调用都通过 API Gatekeeper → TokenTracker 计量，实时流式写入 data/token_usage.json（原子写入；排除在 K3 一致性哈希之外，因此成本永远不会影响结果）。所有数字均为配置驱动（config/setup.json → token_budget / economics）。

实际上整个项目在 LLM 上花费 ≈ $0.01。 动作来自本地 minimax 引擎，动作语言是确定性的 [INTENT: …] 编码/解析——无需 LLM 即可对弈或发送报告（Gmail API，而非 LLM）。微小的预算 + DeepSeek 优先的故障转移是可选 LLM 辅助自然语言解析的护栏；上限设为 $0.50，留有充足余量。

密钥与配置

• 复制 .env-example → .env 并填写：DEEPSEEK_API_KEY、ANTHROPIC_API_KEY、COP_MCP_TOKEN、 THIEF_MCP_TOKEN、GMAIL_CREDENTIALS_PATH。零依赖自动加载器在启动时注入 .env——无需 export/source；已有的 shell 导出始终优先。

• 所有可调参数位于版本化的 config/*.json 中（无硬编码）。密钥（.env、credentials.json、 token.json）被 git 忽略，绝不进入源代码管理。

文档

PRD · PLAN · TODO · STRATEGY · RULES_AND_AGREEMENTS · INTER_GROUP_TREATY_SPEC

许可证

MIT。