Skip to main content
Glama
README.md
# ygo-ai

**让 LLM agent 通过 MCP 和你打游戏王。** 用的是真实的 EDOPro 客户端与 ocgcore,不是规则模拟器:
卡表、脚本、判罚和你在 EDOPro 里看到的一模一样,agent 只是换了个"手"。

> Let an LLM agent play *Yu-Gi-Oh!* against you over MCP, on a real EDOPro client and the real
> ocgcore. Same cards, same scripts, same rulings — the model just plays instead of you.

```
EDOPro(你,主机)  ⇄ TCP 127.0.0.1:7911 ⇄ ygo-rs ⇄ MCP(stdio 或 --listen 7912)⇄ agent
```

- **agent 驱动**:每回合看局面、自己选动作,没有任何写死的启发式(可选的策略表只用来省往返)。
- **一次决策一次往返**:`ygo_act` 把裁决和下一条事件一起带回来;每回合 400 秒的时钟从没被打满过。
- **可复盘**:`wire.jsonl` 记原始帧,`decisions.jsonl` 记"当时有哪些选项、选了哪个、谁选的",
  两份都能离线重放,逐条比对。

## 快速开始

### 0. 你需要

- **Windows**(EDOPro 本体只有 Windows/Linux 桌面版,本项目在 Windows 上实测)
- **EDOPro 41.x**(代号 Bagooska 及以后;ocgcore 11.x)
- Rust stable(`cargo`)

### 1. 构建

```bash
git clone https://github.com/dynamder/ygo-ai.git
cd ygo-ai/ygo-rs
cargo build              # 产物 target/debug/ygo-rs(.exe)
```

(如果 cargo 在沙箱里写不了全局缓存:`CARGO_HOME=$PWD/../.cargo-home cargo build`,本项目就是这么自举的。)

### 2. 起 MCP 服务

```bash
./target/debug/ygo-rs mcp                  # stdio:给 MCP host(Claude Desktop / Codex / 自研 agent)用
./target/debug/ygo-rs mcp --listen 7912    # 环回 TCP:给 shell 脚本、调试器用,方便 curl 式手搓
```

MCP 客户端配置(stdio 形态):

```json
{
  "mcpServers": {
    "ygo": {
      "command": "D:/ygo-ai/ygo-rs/target/release/ygo-rs.exe",
      "args": ["mcp"]
    }
  }
}
```

### 3. 在 EDOPro 里开房

EDOPro → **局域网** → 建主机,端口 `7911`,房间密码随意(下文示例用 `1111`),
你当 host、deck 随便;对手的 deck 由 `.ydk` 文件指定(`decks/` 里有几套现成的)。

### 4. 让 agent 接管

```python
ygo_connect {"port": 7911, "password": "1111", "deck": "decks/agent.ydk"}
ygo_next    {"after_event": 0}          # 阻塞到轮到我方,返回事件 + 选项 + 时钟 + 变化
ygo_act     {"event_id": 3, "picks": [1]}   # 裁决,顺手把下一条事件带回来
```

你按下 EDOPro 的 Start,之后每一手都由 agent 决定。

## MCP 工具面

| 工具 | 作用 |
|---|---|
| `ygo_connect` | 加入局域网房,参数 `port/host/password/name/deck`;收到主机第一帧才算成功 |
| `ygo_next` | 长轮询到新事件:返回 `event`(`kind/format/reason/min/max/deadline_ms/options[]`),外加 `new_events`(自上次轮询以来的全部日志)与 `changes`(和上次快照的差异) |
| `ygo_act` | 按 `event_id` + `picks` 裁决,**返回下一条事件**;`cancel:true` 取放弃项;`raw_hex` 给未解码事件兜底;`code` 用于 `announce_card`;给 `steps` 则一次调用跑完一整段 |
| `ygo_scene` | 纯观测:回合/阶段/LP/场上卡号/墓地/牌组/时钟/当前事件 |
| `ygo_clock` | 双方时钟剩余(**每回合重置**) |
| `ygo_log` | 完整线性历史分页:`since` + `limit`/`n`,内存里不截断 |
| `ygo_card` | 卡号 → 名称/类型/攻守/卡文(默认给全文);也能按名字搜 |
| `ygo_policy` | 策略表:常规提示零往返(`load/show/clear/silence/restore`) |
| `ygo_rule` | 在同一调用里装策略 + 裁决;`completion:stop` 把控制权交还客户端启发式 |
| `ygo_rematch` / `ygo_surrender` / `ygo_leave` | 再战 / 投降 / 断开 |
| `ygo_say` / `ygo_events` / `ygo_wait` / `ygo_play` | 聊天、事件查询、定时等待、录像重放 |

### 为什么轮询能看懂发生了什么

日志是**只追加不截断**的,每次轮询自动带上"上次之后发生了什么"和"盘面差在哪":

```json
"new_events": [
  {"seq": 812, "line": "[move] 88453933 手牌 -> 怪兽区"},
  {"seq": 815, "line": "[damage] 我方 -2400 (LP 5600)"}
],
"changes": [
  "回合 4→5,阶段 主要1→战斗",
  "LP: 我方 8000→5600,对方 8000→8000",
  "对方怪兽 +[位2 Parlor Dragonmaid (88453933) 500/1700]",
  "手牌: 我方 6→5,对方 3→2"
]
```

同一阶段里宿主会把**同一组**可发动项反复再问(一张盖牌一回合能被问二十次),这种重复窗口会被内联放弃
(`decisions.jsonl` 里记 `by: "echo"`),不占 agent 的往返预算。

## 它是怎么工作的

三层,边界很清楚:

1. **线路层**:直接说 EDOPro 的 TCP 协议(`[len:u16][opcode:u8][body]`),跑的是官方客户端 + ocgcore。
   所以规则不是我们"实现"的,是核心给的;我们只负责读懂 `MSG_*` 和写对 `CTOS_RESPONSE`。
2. **票据层**:核心卡在哪个提示上,就把它变成一张**只能答一次**的票(长轮询等它、`event_id` 对不上就拒答),
   绝不去猜"现在大概该干什么"。
3. **决策层**:agent 通过 MCP 看局面、下决定。可选的策略表负责把"每次都想按放弃"的常规提示压成零往返。

细节见 [docs/mcp-design.md](docs/mcp-design.md);协议事实(逐条从 EDOPro 源码和真机帧核实)见
[docs/duel-log.md](docs/duel-log.md)。

## 真机验证

不是 demo 级验证:真机打过 5 局,**赢 3 输 2**。

| 局 | 对手 | 结果 |
|---|---|---|
| 1–3 | 各种 | 3 胜(其中一局 6 回合清场,`LP 7500 vs -300`) |
| 4–5 | 纯半龙女仆 | 2 负(都是第 7 回合被打穿,原因是我这边操作失误,不是协议问题) |

四、五局暴露的**工具**问题当时就修了:日志环形缓冲会丢历史(→ 改成只追加 + 轮询带差异)、
重复连锁窗口每次花一个往返(→ echo 内联放弃)、纯发动型连锁不显示卡名、`ygo_rule` 顶层 `action`
静默无效……复盘写在 [docs/duel-log.md](docs/duel-log.md)。

## 已知不足

- **只测了 Windows + EDOPro 41.0.2**;协议版本对不上会直接报错退出(这是故意的,猜版本比报错更糟)。
- 仍然有一种提示没解码:`MSG_SORT_CHAIN`(异步连锁排序)。遇到时它会带着原始字节升级成
  `unsupported` 事件,用 `ygo_act raw_hex` 兜底,不会被静默吞掉。
- 卡名/卡文依赖 EDOPro 自带的 `cards.cdb` 与 `config/strings.conf`;换卡表要指过去(`YGO_CDB`)。
- 不做自动组牌,也不内置对局策略——下棋的是模型。

## 仓库结构

```
ygo-rs/          Rust 实现(协议、票据、MCP 服务、重放)
  src/proto.rs     帧编解码、常量(相位/区域/种族/属性)
  src/msg.rs       MSG_* 解码
  src/respond.rs   提示 → 选项 → 响应字节
  src/session.rs   连接、票据、时钟、自动应答
  src/mcp.rs       MCP 工具面
  src/replay.rs    离线重放 / 回归
decks/           .ydk(agent 用的几套牌)
policies/        策略表样例
skills/          agent skill 描述(给支持 skill 的 host 用)
debug/           调试脚本与抓包(mcpcli.py、mockhost、抓帧工具)
docs/            设计文档与开发记录
src/, test/      早期 TypeScript 原型(已被 ygo-rs 取代,保留作为参考)
```

## License

MIT,见 [LICENSE](LICENSE)。