Courtship

---

1. 问题与论点

LOVE 模型上下文协议（MCP）生态系统功能齐全，却缺乏治理。原始桥接会在每次交互时输出单体游戏状态对象、冗长的文档转储以及数百个未经筛选的键，导致上下文膨胀和 Token 成本飙升。

Courtship 充当测量与优化层，验证三项基础论断：

论断	目标	实测结果	状态
1. 常驻上下文开销	将常驻架构上下文减少 >=70%	减少 76.5%（340 对比 1,450 个 Token）	已证实
2. 响应整形开销	将每项任务的 Token 开销减少 >=40%	平均减少 53.4%	已证实
3. 统一路由器效率	混合任务中优于独立 MCP 服务	借助本地 FTS5，延迟降低 40%，调用次数减少 33%	已证实

---

2. 架构

+-----------------+       MCP (stdio/HTTP)       +--------------------------------+
|   AI Client     |<---------------------------->|  court proxy                   |
| (Claude Code,   |   ~340 token                 |  +- meta-tools (5 standing)    |
|  Cursor, IDE)   |   standing surface           |  +- heuristic router           |
+-----------------+                              |  +- response shaper & cursors  |
                                                 |  +- session token ledger       |
                                                 |  +- upstream pool manager      |
                                                 +---------------+----------------+
                                                                 | MCP
                                       +-------------------------+--------------------------+
                                       |                         |                          |
                                       v                         v                          v
                                   LovePilot               LOVE 12 Docs            Custom Game Servers
                                       |                   (SQLite FTS5)
                                       v
                                   LOVE Game
                                  (TCP 12345)

代理以带内部注册表的守护进程运行，而非简单的直通代理。工具架构会保留在守护进程端，直到按需加载；闲置 N 个轮次后过期。

---

3. GitHub MCP 注册表与客户端设置

Courtship 已发布至官方模型上下文协议（MCP）注册表，并使用经过验证的命名空间：

io.github.grimmdev/courtship

在 VS Code / Cursor / Claude Desktop 中安装

选项 A：原生二进制文件（最快）

从 Releases 下载二进制文件，或通过 cargo build --release --bin court 构建。

将其添加到 MCP 客户端配置（mcp.json 或 claude_desktop_config.json）中：

{
  "mcpServers": {
    "courtship": {
      "command": "court",
      "args": ["proxy"]
    }
  }
}

选项 B：通过 Docker / GitHub Packages 容器化运行

无需安装本地依赖即可运行：

{
  "mcpServers": {
    "courtship": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/grimmdev/courtship:latest"
      ]
    }
  }
}

---

4. 核心功能

4.1 常驻接口（少于 500 个 Token）

常驻上下文中仅永久公开 5 个精简元工具（约 340 个 Token），保持上下文清爽，同时让 Agent 能按需发现或调用任意游戏工具：

• discover_tools(query, limit)：模糊发现工具，无需加载架构。
• load_tool_schema(name)：按需加载完整 JSON 架构。
• call_tool(name, args)：通过压缩过滤器执行工具。
• love_task(goal, context)：智能意图路由器（文档、检查或执行）。
• report_usage()：统计会话 Token 数、调用次数和延迟。

4.2 内置游戏功能（通过 call_tool 和 discover_tools 使用）

• simulate_input(sequence)：Agent Joypad：分派定时键盘输入（press、keydown、keyup）。
• step_frames(count, dt)：确定性帧步进：以固定的 dt 将物理模拟推进 N 个刻度。
• get_last_crash()：安全崩溃诊断：恢复非致命堆栈跟踪和局部变量。
• clear_crash()：热修补后恢复游戏循环。
• visual_diff(image_a, image_b)：视觉回归：比较两张截图并返回边界框。
• get_objects()：以精简格式返回活动实体的坐标和类型。
• get_screenshot()：返回缩小并裁剪后的 PNG 帧缓冲区。
• run_lua(code)：在游戏循环中执行任意 Lua 代码。

4.3 安全崩溃拦截（覆盖 love.errhand）

当 Agent 引入错误时，防止臭名昭著的 LOVE “蓝屏死机” 导致进程崩溃或 MCP 桥接中断：

• 替换 love.errhand，暂停执行并显示游戏内诊断 HUD，而不是终止程序。
• 提取出错的源文件、行号、debug.traceback() 和活动局部变量。
• 保持 TCP 套接字监听器处于活动状态，以便 Agent 通过 get_last_crash() 检查故障、编写修复并热重载。

4.4 Agent Joypad 和确定性物理验证

让 Agent 能够测试需要时间和移动的游戏机制：

• 输入序列：分派定时操作序列（例如，按住 D 1.2s，按下 Space，然后释放）。
• 帧步进：以固定增量时间（默认 1/60）按精确帧数推进 love.update(dt)，在验证平台游戏物理和碰撞时消除墙上时钟抖动。

4.5 8 条规则的响应整形器

每个工具返回值和通知都会经过确定性整形：

1. 字段投影：将实体图精简为 {id, type, name, x, y}。
2. 剔除空值和空内容：移除空数组、对象和空字符串。
3. 深度上限：将超过 3 层的深层对象图折叠为 "<table: N keys>"。
4. 数组切片和游标：对超过 50 项的数组进行切片，并将游标提示存储在内存中。
5. 令牌上限：自动截断并控制超出 max_tokens 的载荷。
6. 截图压缩：通过区域裁剪和双线性缩小（默认 0.5）防止视觉令牌激增。
7. 增量模式：连续流（watch_game_state）会抑制相同的刻度，令牌数降至 0。
8. 精简文档：移除 Wiki 导航界面并对代码示例去重。

4.6 零插桩启动器（court run）

动态包装任何现有 LOVE 游戏：

court run ./mygame --mcp-port 12345

自动挂载源文件并挂接 love.update、love.draw 和桥接，无需修改你的代码库。若要手动集成，court init 会生成 5 行的内联挂接代码。

---

5. 基准测试结果

在参考套件上运行 court bench --compare lovepilot,courtship：

task                     tokens   calls   p95ms  turns  success
--------------------------------------------------------------
fix-double-jump             316       2     110      2     PASS
spawn-coin                  307       2     110      2     PASS
--------------------------------------------------------------
TOTAL (per task)            311       2     110      2      2/2
vs lovepilot          -54.3%   -33%    -40%     -         -

参考套件细分

• platformer（物理模拟 + 跳跃逻辑）：令牌减少 54.3%
• ui_heavy（绘制调用压力测试 + 小地图 + HUD）：令牌减少 52.1%
• menu_nested（6 层深的 UI 实体树）：令牌减少 53.9%

---

6. CLI 参考

运行 MCP 代理

court proxy --port 12345
court proxy --eager # Fallback exposing full upstream tools

运行基准测试和 CI 回归门禁

# Compare candidate against raw baseline
court bench --suite ./suites/platformer.yaml --compare lovepilot,courtship

# Enforce CI gate (fails if regression exceeds threshold)
court bench --suite ./suites/platformer.yaml --ci --max-regression 10.0

# Submit signed benchmark to community leaderboard
court bench --suite ./suites/platformer.yaml --compare lovepilot,courtship --submit

启动 LOVE 游戏

court run ./fixtures/platformer
court run ./fixtures/platformer --shim-only

离线文档索引

court docs search "rectangle"
court docs search "love.physics.newWorld"

环境和令牌开销审计

court doctor
court doctor --ci

---

7. 配置（courtship.toml）

[proxy]
port = 12345
max_response_tokens = 1500
evict_after_turns = 6
delta_notifications = true
eager = false

[upstream.lovepilot]
transport = "stdio"
command = "uvx"
args = ["--from", "./love-mcp", "love-mcp-server"]
shape = { get_objects = "lean", get_screenshot = "scaled" }

[upstream.docs]
transport = "builtin"
index = "./lua54-love12.sqlite"

[bench]
suite_dir = "./suites"
baseline = ".courtship/baseline.json"
max_regression = "10%"

---

8. 许可证

采用双重许可，可任选其一：

• MIT License（LICENSE-MIT）
• Apache License，Version 2.0（LICENSE-APACHE）