Agent 想打的角度
    │
    ▼
┌─────────────────────────────┐
│  angle_sigma     球杆抖动    │  ← 随机噪声：只能靠概率硬扛
│  systematic_bias 习惯性偏左  │  ← 系统偏差：可以通过反馈学习补偿 ★
│  power_sigma     力度误差    │
│  bias_drift      手感漂移    │  ← 昨天练的加塞今天还在，但今天手有点不顺
└─────────────────────────────┘
    │
    ▼
确定性物理引擎（Ground Truth，永远精确）

┌────────────────────────────────────────────┐
│           LLM Agent（任何 MCP 客户端）        │
│        观察 → 推理 → 预测 → 出杆 → 校准       │
└──────┬────────────────────────▲────────────┘
  observation                action
       │  定性描述（默认）        │  angle / power / spin
┌──────▼────────────────────────┴────────────┐
│        感知降级 + Hand Model 噪声注入         │
└──────┬─────────────────────────────────────┘
       │ 精确物理
┌──────▼─────────────────────────────────────┐
│        无头物理引擎（确定性、可回放）           │
└─────────────────────────────────────────────┘

observe_table()        观察球桌（按感知分级输出）
take_shot(angle, power, spin)   出杆（噪声在此注入）
get_shot_history()     回顾自己最近的杆（校准的原料）
get_score()            当前得分

poolhall/
├── engine/         无头物理核（确定性模拟、种子回放）
├── mcp-server/     台球厅 MCP 封装（工具面 + 噪声注入层）
├── godot/          Godot 4 前端（渲染回放、观战、可视化调试）
├── experiments/    校准实验、模型对比脚本（知行曲线出图）
└── docs/           设计文档

pnpm install     # 唯一前置
make help        # 看全部 target 与可覆盖变量
make demo        # 零配置冒烟：纯物理打一杆（不联网、不读 .env）

make dev         # 常驻大厅 → http://localhost:8800（多桌·动态认座·选桌观战）
make table       # 单桌实时对局 → WS :8800 + 前端页 :8801
make stop        # 清理遗留服务进程

node packages/cli/src/main.ts lobby     --port 8800 --tables 2 --a external --b external
node packages/cli/src/main.ts web-match --port 8800 --a external --b external

# 方式一：pnpm exec（本地仓库内）
pnpm exec poolhall mcp --agent claude-4 --trials 20 --seed 42

# 方式二：直接 node（等效，适用于不支持 pnpm 的客户端配置）
node packages/cli/src/main.ts mcp --agent claude-4 --trials 20 --seed 42

{
  "mcpServers": {
    "poolhall": {
      "command": "pnpm",
      "args": ["exec", "poolhall", "mcp", "--agent", "claude-4", "--seed", "42"],
      "cwd": "/path/to/poolhall"
    }
  }
}

# 启动一桌实时对局，同时保存不含隐藏手感参数的公开事件日志
pnpm exec poolhall web-match \
  --a synthetic:oracle --b synthetic:oracle \
  --event-out experiments/results/live-match.jsonl

# 生成无需服务器、可直接分享的单文件 HTML
pnpm exec poolhall replay-match \
  --in experiments/results/live-match.jsonl \
  --out replay.html

pnpm exec poolhall web-match --a external --b external \
  --name-a claude --name-b codex --port 8899
# 两个 Agent 各自的 MCP 配置（stdio；注意 HTTP 在 port+1，即 8900）：
pnpm exec poolhall-mcp --match --remote http://host:8900 --agent claude
pnpm exec poolhall-mcp --match --remote http://host:8900 --agent codex

pnpm exec poolhall lobby --port 8830 --tables 2 \
  --a external --b external --event-out-dir experiments/results/lobby
# 任何 Agent 入座（自动分配空桌；同一身份跨局手感不变——肌肉记忆）：
pnpm exec poolhall-mcp --match --remote http://host:8830 --agent <身份名>

{
  "mcpServers": {
    "poolhall": {
      "command": "node",
      "args": ["/abs/path/to/poolhall/packages/mcp/src/main.ts",
               "--match", "--remote", "http://host:8830", "--agent", "claude"]
    }
  }
}