feat: game pause/speed control API with AI pause protocol

- POST /api/action/pause - pause game (AI must call before operations)
- POST /api/action/unpause - resume game at desired speed
- POST /api/action/speed - set game speed (1x/2x/3x)
- Game state now includes isPaused and gameSpeed
- AI pause protocol documented in SKILL.md: pause before every operation
- Introduces cell.isDiggable flag that filters neutronium properly
- pause/unpause/speed CLI commands added to oni_api.py
This commit is contained in:
root
2026-05-22 09:04:04 +08:00
parent a4f2062c1a
commit 48a70e4928
4 changed files with 183 additions and 1 deletions

View File

@ -234,6 +234,62 @@ python3 tools/oni_builder.py build spom 42 42
---
## AI 暂停协议(关键规则)
AI **必须**在每次操作序列前暂停游戏,操作完成后恢复。这防止推理延迟期间游戏状态变化导致操作失效。
### 规则
```
1. 收到事件 / 决定操作 → 立即 PAUSE
2. 查询状态、分析、决策(可耗时,游戏已暂停)
3. 执行操作(dig / build / batch)
4. 检查操作反馈
5. 所有操作完成后 → UNPAUSE
```
### 示例
```bash
# 1. 暂停
python3 tools/oni_api.py pause "Building SPOM"
# 2. 查询状态(游戏已冻结,不会变化)
python3 tools/oni_api.py explore 40 40 30 20
python3 tools/oni_api.py cell 45 42
# 3. 执行操作
python3 tools/oni_api.py dig 40 40 8 6
python3 tools/oni_api.py build Electrolyzer 45 42
# 4. 恢复
python3 tools/oni_api.py unpause 1
```
### 当前游戏速度
通过 `status` 命令查看:
```
isPaused: true ← 游戏是否暂停
gameSpeed: 0 ← 0=暂停, 1=1x, 2=2x, 3=3x
```
### 总是暂停的场景
| 场景 | 原因 |
|------|------|
| 收到 critical 事件 | 可能需要紧急操作 |
| 执行 dig / build / deconstruct | 坐标必须精确,不能偏移 |
| 执行 batch | 多个相关操作需原子性 |
| 查询状态后做决策 | 避免推理时状态变化 |
### 不需要暂停的场景
| 场景 | 原因 |
|------|------|
| 仅查看 status / resources | 只读操作,无副作用 |
| 轮询 events | 事件本身是增量变化的 |
## AI 事件驱动工作流
AI 应持续运行事件守护进程,形成"事件 → 分析 → 操作 → 反馈"的闭环: