snowy-yang
a7725f8812
在引入 uv 依赖管理、ruff 静态检查与格式化、pyright 类型检查之前， 先把当前可正常运行的状态固定下来，作为后续大规模自动改动的回滚点。 此时状态：97 项测试全绿，HTTP + WebSocket 多牧场服务器可用。
50 lines
3.9 KiB
Markdown
50 lines
3.9 KiB
Markdown
# 2026-09-18 · SimpleFarm 从单机 TUI 改造为小型多人游戏服务器
|
||
|
||
## 需求
|
||
用户先要求"CLI/TUI 农场游戏 + HTTP/gRPC 接口让 AI 参与"；中途改方向：
|
||
**放弃 gRPC，改用 FastAPI/aiohttp**，要求：守护进程可后台运行、SSE 或 WS 二选一、
|
||
TUI 只在用户玩时作为客户端、用户也能用 HTTP 调用、支持多用户（小型游戏服务器）。
|
||
|
||
## 最终架构（v2.0）
|
||
- 服务端 `farm/server/`：`app.py`(FastAPI REST+WS) / `actions.py`(动作表) /
|
||
`session.py`(多牧场会话 + 单一 FarmClock 统一时钟) / `hub.py`(WS 连接池 + 250ms 节流推送) /
|
||
`daemon.py`(守护进程) / `webui.py`(内嵌网页客户端)。
|
||
- 客户端 `farm/client.py` 的 `RemoteFarm`：与 `FarmEngine` **接口同构**，
|
||
所以 `tui.py` 不用改渲染逻辑就能从"本地引擎"切到"远程服务器"。
|
||
写操作优先走 WS（带 id 回执），通道类错误自动退回 HTTP；读数靠 WS 推送。
|
||
- `farm/bot.py` 规则机器人 + `ai_player.py` 外挂机器人：只调接口，不 import 游戏规则。
|
||
- 统一入口 `main.py`：serve/stop/status/logs/play/solo/do/batch/actions/state/log/watch/bot/farms/help。
|
||
|
||
## 关键决策
|
||
- **选 WebSocket 而非 SSE**：这个游戏动作上行和状态下行是同一件业务的两半，
|
||
SSE 只能下行，等于要维护两套鉴权/重连。
|
||
- **删掉 gRPC**（`farm/api.py` 旧 stdlib HTTP 层、`farm/grpc_server.py`、`proto/`、`tools/gen_proto.py`）：
|
||
接口主要喂 LLM/脚本，它们只会捏 HTTP+JSON。
|
||
- 多牧场模型：一个牧场 = 一个玩家 = 一份存档 + 一个引擎；空闲 30 分钟先落盘再移出内存。
|
||
- 动作表 `server/actions.py` 是所有入口（HTTP / WS / CLI / 机器人）的唯一执行通道，参数校验只写一次。
|
||
|
||
## 踩过的坑（重要，可复用）
|
||
1. **本地请求被系统代理截走**：机器上设了 `HTTP_PROXY` 但没有 `no_proxy`，
|
||
`urllib` 把发给 127.0.0.1 的请求也交给代理，本机服务器报 `502 upstream connect failed`。
|
||
解决：`farm/net.py` 的 `open_url()`，回环地址走 `ProxyHandler({})` 直连。
|
||
2. **pid 归属**：起初父进程把 `Popen().pid` 写进 pid 文件，但 Windows 上 venv 的
|
||
`python.exe` 可能是转发器，`os.getpid()`（40564）≠ 父进程看到的 pid（20244），`stop` 会杀错进程。
|
||
解决：`--pid-file` 传给子进程，子进程在 lifespan 启动（端口已绑定）后写自己的 pid，退出时删除；
|
||
`stop` 优先走 HTTP `/api/admin/shutdown` 优雅停机（能落盘），拿不到 pid 也能停。
|
||
3. **精简状态会清空视图**：动作回执里的 `state` 是精简版（无 `plots`/`animals`），
|
||
客户端若整体替换就会把农田格子清空。解决：`StateView.apply()` 按"含 plots 即整体替换，
|
||
否则合并字段"，并且 HTTP 动作带 `full=1` / WS 回执带 `snapshot` 让客户端立刻刷新。
|
||
4. **`save` 动作必须由会话处理**：`engine.save()` 会写默认路径，多牧场下会互相覆盖；
|
||
在 `app.execute_action()` 里把 save/reset 拦截为会话级操作。
|
||
5. 本机 Bash 的 coreutils 坏了（`ls`/`head`/`tail`/`grep` 都不存在），
|
||
所有查看/清理动作改用 Python 脚本完成；管道会直接让命令失败，**不要用管道**。
|
||
|
||
## 验证
|
||
- 97 项测试全绿（引擎 45 + 服务器 52），含真 uvicorn + 真客户端 + 真 WebSocket 端到端。
|
||
- 实测：daemon 启动 → status 正确 pid → actions/do/batch → 两牧场隔离与排行榜 →
|
||
WS 收到 welcome/state/result/day → 机器人 120→197 金币 → stop 优雅停机落盘。
|
||
- TUI 远程渲染验证：`tools/preview_tui.py --url http://127.0.0.1:8793 --farm alice`
|
||
（112 列 / 76 列都正常，头部显示 `牧场名 @ 服务器`）。
|
||
- 依赖装在隔离 venv：`C:/Users/Administrator/.workbuddy/binaries/python/envs/default/Scripts/python.exe`
|
||
（fastapi 0.141.1 / uvicorn 0.53 / websockets 17.1 / httpx 0.28）。
|