snowy-yang
a7725f8812
在引入 uv 依赖管理、ruff 静态检查与格式化、pyright 类型检查之前， 先把当前可正常运行的状态固定下来，作为后续大规模自动改动的回滚点。 此时状态：97 项测试全绿，HTTP + WebSocket 多牧场服务器可用。
2.6 KiB
2.6 KiB
SimpleFarm 项目长期约定
是什么
终端农场经营游戏 + 小型多人游戏服务器（v2.0）。游戏跑在服务端进程里， TUI 是纯客户端，同时开放 HTTP + WebSocket 接口给 AI/脚本调用（服务端不内置 AI）。
运行方式
- 依赖放隔离 venv：
C:/Users/Administrator/.workbuddy/binaries/python/envs/default/Scripts/python.exe（服务端需要 fastapi + uvicorn[standard] + websockets；客户端与 TUI 只用标准库） - 服务端：
python main.py serve --daemon，网页 http://127.0.0.1:8765/，文档 /docs - 玩：
python main.py play --farm 名字；单机：python main.py solo - AI/脚本入口：
main.py actions | do <动作> '<JSON>' | batch | state --json | watch | bot - 测试：
python -m unittest discover -s tests（97 项；不需要 FastAPI 时只跑 test_engine.py）
架构约定（改动时必须遵守）
- 分层：
farm.engine只管规则，不认识网络/终端；farm.tui不认识 socket；farm/server/*不认识终端。新增玩法动作只改farm/server/actions.py一张表。 - 接口同构：
farm.client.RemoteFarm必须与FarmEngine同名同语义， 这样tui.py不需要区分本地/远程。加动作时两边都要补。 - 多牧场：一个 farm = 一个玩家 = 一份
saves/<名字>.json+ 一个引擎 + 独立时钟； 时钟由一个FarmClock线程统一驱动，不要给每个牧场开线程。 - 存档类动作：
save/reset必须由会话（FarmSession）处理， 不能直接落到engine.save()（会写默认路径、覆盖别人的档）。 - 实时通道：WebSocket（
/ws）是唯一实时通道，推送节流 250ms，消息带自增seq。 写操作优先走 WS（带id回执与snapshot），只有 ws_closed/timeout/network 才退回 HTTP 重试；业务错误必须原样抛出，不能重试。
环境禁忌（本机特有）
- Bash 的 coreutils 残缺（
ls/head/tail/grep缺失），不要用管道，会整条命令失败； 查看/删除文件一律写 Python 脚本。 - 环境设了
HTTP_PROXY但没有no_proxy：任何本机 HTTP 访问都要走farm/net.py的open_url()（回环直连），否则会拿到 502 并误判为"服务器没起来"。 - Windows 下守护进程的 pid 必须由服务进程自己写（见
farm/server/__main__.py）， 父进程的Popen().pid不可信。
相关文档
- 项目入口文档：
README.md（接口表、WS 协议、边界处理、设计取舍全在里面） - 当天工作记录：
.workbuddy/memory/2026-09-18.md