snowy-yang
bc3ae96a38
`saves/farm.db` 一张 farms 表，farm_id 主键，**一个牧场一行**。 接口签名不变（save_state / load_state / delete_save 只多了 farm_id 参数）， 调用方只改了路径语义。 设计取舍：标量列 + 整份 payload。 * day/gold/level/ap/weather/forecast/net_worth 单独成列——外部工具或 AI 一条 SELECT 就能排榜、画曲线，不必先把每份存档读进内存； * 完整状态仍整份存 payload JSON：游戏数据隔三差五长新字段，规范化成 几十张表意味着每加字段写一次迁移，而存档只做整体读、整体写， 所以结构化列管可查询，完整性交给 JSON——加字段不用改表结构。 崩溃安全升级：写入包在事务里。原来的"临时文件 + os.replace"能挡进程 崩溃，挡不住写到一半掉电；SQLite 的日志能。读取失败照旧降级开新档。 向后兼容：SAVE_VERSION=2 / MIN_SAVE_VERSION=1 不变。老 JSON 存档由 migrate_json_saves() 在服务器启动时自动导入：同名已存在就跳过（宁可不 迁不覆盖），导入成功原文件改名 *.json.migrated 留底，先写库再改名 保证幂等；坏档一律跳过——迁移不许有能力阻止服务器启动。 异常边界：StorageError = sqlite3.Error，刻意不是 OSError 子类—— 调用方原来的 except OSError 全部跟着改，否则写盘失败会穿透出去。 性能实测：PRAGMA journal_mode=WAL 是持久属性，建库时设一次就够， 每次连接重设白花 2.2ms；save_state 约 6.9ms/次，大头是 synchronous=FULL 的 fsync——不省，存档的价值就是不丢档。bench 热路径无回归。 顺手修一个真 bug：connect() 建表失败时连接会泄漏，Windows 上句柄没关 就删不掉文件，而调用方正是靠"读失败→开新档"容错的。补 close。 测试：StorageTestCase 重写（往返/版本/损坏降级/多牧场隔离/迁移）， test_server 断言 *.json 的用例改查库。513 项全过，ruff/pyright 全绿。 端到端：预置 v1/v2 老档起真服务器验 22 项——自动迁移、字段还原、 list_farms() 排榜、重启后进度分毫不差，全过。
17 KiB
17 KiB
SimpleFarm 项目长期约定
是什么
终端农场经营游戏 + 小型多人游戏服务器（v2.0）。游戏跑在服务端进程里， TUI 是纯客户端，同时开放 HTTP + SSE 接口给 AI/脚本调用（服务端不内置 AI）。
运行方式（v2.0 起由 uv 统一管理）
- 单一可信来源是
pyproject.toml，.venv/由 uv 创建；uv.lock要提交（可复现构建依据）。 加/删依赖走uv add/uv remove，不要手工编辑依赖表，也不要再列pip install。 - 所有命令带
uv run前缀：uv run main.py serve --daemon，网页 http://127.0.0.1:8765/，文档 /docs - 玩：
uv run main.py play --farm 名字；单机：uv run main.py solo - AI/脚本入口：
main.py actions | do <动作> '<JSON>' | batch | state --json | watch | bot - 测试套件已重建（2026-09-19）：
uv run python -m unittest discover -s tests，500 项。 但 pyproject 里不认它（用户明确选择「只写测试文件」）：tests不进 ruffsrc、 不进 pyrightinclude、没有per-file-ignores，httpx也保持已移除状态 —— 于是TestClient/ 真机LiveServer那 35 项靠 skip-guard 自动跳过。 代价是：ruff check .仍会扫tests/（命令行给了.），测试文件必须自己保持 lint 干净。 覆盖：test_engine(110) /test_actions(35) /test_server(131, skip 35) /test_tui_keys(75) /test_bot(36) /test_client(113)。 - 质量门禁（改动后都应跑一遍）：
uv run ruff format . && uv run ruff check . && uv run pyright && uv run python -m unittest discover -s tests（2026-09-19 起把测试并入标准动作；想复核性能再跑uv run python tools/bench.py --repeat 5） - 不用 uv 的人：
requirements.txt是uv export的产物，只读、不要手工改。 README 与 main.py 顶部保留了一段"没装 uv？把uv run去掉即可"的兜底说明，别删。
玩法节奏（2026-09-19 起）
- 一天 40 分钟：
config.DEFAULT_TICK_SECONDS = 2400，MAX_TICK_SECONDS = 86400（旧上限 600 秒会把 40 分钟悄悄夹回去，已放宽）。--tick可调，调试用--tick 3。 - 没有「手动推进一天」：
engine.sleep()/SLEEP_COOLDOWN//api/sleep/ TUI 的[N]休息/ 网页版按钮全部移除，时间只能自然流动。 机器人改为RuleBot.wait_for_next_day(timeout)，CLIbot --wait控制等多久（0 = 直接收工）。 再加任何“快进一天”的入口前先想清楚：它会让慢时钟彻底失效。 - 时长显示统一走
farm.models.format_duration()（2400 秒 →40:00）， TUI 头部倒计时 /main.py state/ 网页版（JS 里同名函数）都用它，别再写{x}s。 - 新建牧场时
FarmSession会立刻设好next_tick_at，否则到时钟线程下一轮（≤0.2s） 之间倒计时是 None，客户端会误显示成“已暂停/手动模式”。
三大系统：天气 / 谷仓 / 建筑（2026-09-19 起）
- 天气：
config.WEATHER5 种（晴 30 / 多云 27 / 雨 24 / 干旱 12 / 暴风雨 7，合计 100）， 同种不连出（WEATHER_REROLLS重掷）。state.weather＝今天、state.forecast＝明天且 提前可见，于是「今晚浇不浇」成了可计算的决策。水分消耗改由天气决定 （晴 1 / 多云 0 / 干旱 2），雨天反补 3；建成温室后蒸发减半。 - 谷仓：收获 / 收取不再直接给钱，进
state.inventory（键与market同构：wheat/animal:chicken），靠sell换金币——市场波动因此从纯装饰变成真决策。 仓满时_store()抛granary_full且不改状态（作物原地不动，卖了再来）。 - 建筑：
config.BUILDINGS，第 n 座价int(cost * 1.6**owned)；每天在advance_day里先于生长执行（水井救的正是今天要断水那块地）。喂食器只吃库存饲料、绝不自动花钱。 - 存档：SQLite（
saves/farm.db，一张farms表，一牧场一行）。 标量列（day/gold/level/ap/weather/forecast/net_worth）管可查询， 完整状态整份存payloadJSON——加字段不用改表结构，改_raw_state()就行。SAVE_VERSION=2配MIN_SAVE_VERSION=1，旧档缺的新字段走默认值、不作废玩家档； 老 JSON 由migrate_json_saves()启动时自动导入（原文件改名*.json.migrated留底）。StorageError = sqlite3.Error（不是 OSError 子类），吞异常别再写except OSError。 WAL 是持久属性，建库时设一次就够；每次连接重设白花 2ms。 - 测试钩子：
advance_day(weather="sunny")可钉死当天天气（不传就随机，测试会飘）； 这条链的入口是_resolve_weather/_evaporation/_run_buildings/_storm_damage。 - 动作表新增
sell与build，都是 0 AP；bot在 AP=0 时仍会走一次step()， 正是为了执行这些免费动作。
架构约定（改动时必须遵守）
- 分层：
farm.engine只管规则，不认识网络/终端；farm.tui不认识 socket；farm/server/*不认识终端。新增玩法动作只改farm/server/actions.py一张表。 - 接口同构：
farm.client.RemoteFarm必须与FarmEngine同名同语义， 这样tui.py不需要区分本地/远程。加动作时两边都要补。两条容易踩的：StateView.apply()里"带plots= 完整快照（整体替换）、不带 = 精简状态（只合并字段）"—— 搞反了播一次种就清空整片农田；RemoteFarm._normalize()必须先补 scheme 再削尾部斜杠， 顺序反了"http://"会被削成"http:"，地址没有主机名 → 请求溜到系统代理 → 报一个 和真实原因无关的 502。空视图（StateView()）也要预置plots/animals为空列表， 否则连不上服务器时读state.plots直接 AttributeError。 - 按键名统一小写：
farm/keys.py是按键名的唯一来源，具名键全小写 （UP/SPACE/TAB/ESC/CTRL_C… 常量值即小写字符串），Windows 与 POSIX 两条路径必须返回完全一样的名字。tui.py一律用keys.XXX引用，不要手写 字符串字面量：历史 bug 就是 Windows 侧产大写"UP"、TUI 里写小写"up"， 方向键/空格/Tab/ESC 全部静默失效（字母键正常，所以很难注意到）。 动farm/keys.py时，farm/tui.py里所有具名键引用都要跟着核一遍。 读不到键盘时（管道 / 非 Win32 控制台）TUI 会用reader.reason在底部明示原因。 - 多牧场：一个 farm = 一个玩家 = 库里一行（
saves/farm.db）+ 一个引擎 + 独立时钟； 时钟由一个FarmClock线程统一驱动，不要给每个牧场开线程。 - 存档类动作：
save/reset必须由会话（FarmSession）处理， 不能直接落到engine.save()（会写默认路径、覆盖别人的档）。 - 实时通道（v2.1 起为 SSE）：
GET /api/stream是唯一实时通道，单向推送 （welcome/state/day/notice/bye），节流 250ms，消息带自增seq，空闲每 15s 发: keep-alive注释心跳。写操作一律走 HTTP POST /api/actions，不再有 WS 回执。 停机必须hub.close_all()（否则长连接拖住 ASGI 服务器的优雅退出）+ 配置timeout_graceful_shutdown兜底；客户端 stop() 要 shutdown 底层 socket， 光 close() 会等读线程的锁（最长等到下一次心跳）。 - ASGI 服务器（v2.3 起为 uvicorn + zttp 的 HTTP/2）：
farm/server/__main__.py用uvicorn.Config(http="zttp", http2=True)+uvicorn.Server。 同一端口同时说 HTTP/1.1 与 HTTP/2（TLS 走 ALPN；明文走 h2c prior-knowledge； 分流由AutoZttpProtocol完成；浏览器只在 https 下用 h2）。 关键：uvicorn 0.53 自己不再内置 h2，HTTP/2 必须装zttp并显式选http="zttp"， 否则Config.load()直接 raise（错误信息里就写着 pip install zttp）。 两条停机路径汇到同一处：POST /api/admin/shutdown与 Ctrl+C / SIGTERM / SIGBREAK 都调handle.request_stop()。信号接管靠子类覆盖Server.handle_exit（0.53 的机制是capture_signals()+handle_exit，没有 install_signal_handlers 可覆盖）； 覆盖后不调 super()、也不写_captured_signals，退出时就不会重放信号。第二次信号 = 强制退出。farm/server/app.py的as_asgi()是给 pyright 的类型桥：uvicorn 的uvicorn._types.Scope与starlette.types.Scope两个 TypedDict 互不兼容。 另：uvicorn 的启动顺序也是先 lifespan、后 bind 端口（旧注释曾写成"相反"，已更正）。 - 端口自检：uvicorn 会设
SO_REUSEADDR，Windows 上第二个实例能 "绑上"已被监听的端口并抢走新连接，所以入口启动前用daemon.port_busy()（判断"能不能连上"，而不是"能不能 bind"）自检，被占用就退 3 并提示换端口。
序列化与性能约定（2026-09-19 优化后固化）
- 轻量路径不许做完整序列化：只要标量时（动作回执 /
session.summary()/app.brief()/ 排行榜单行）一律走engine.brief_source()，不要调engine.snapshot()或state.to_dict()再挑字段——那是整局序列化（16 地 + 8 牲畜约 45µs，轻量路径只需 15µs）。 完整快照只在GET /api/state、SSEstate消息、POST /api/actions?full=1用。app.py的BRIEF_KEYS/BRIEF_TODO_KEYS是这两类字段的白名单，加字段要同步。 GameState.to_dict()里net_worth只算一次再复用（net_worth/goal_index/next_goal三处都靠它）；net_worth是每次访问都重算的属性（约 5µs），别在循环里反复读。 「下一个目标」用模块级models.next_goal_after(index)，不要再加next_goalproperty。tools/bench.py是性能守卫，不只是一次性脚本：它给to_dict/snapshot/brief_source/net_worth装了调用计数器，谁把轻量路径改回snapshot()会立刻计数变红。 它用 ASGI 直调（不走 httpx），不跑 FastAPI lifespan —— 动了 lifespan 要用tests/test_server.py::LiveServerTestCase（真 in-process uvicorn）复验。farm/server/app.py的结构：create_app()只做「建_Services+ 依次调_register_*」，所有路由/生命周期都住在模块级_register_*函数里（曾经是一个 475 行的 内嵌闭包大函数）。加路由就加/改对应的_register_*，别把逻辑塞回create_app。- 函数长度参考：>60 行的函数应视为信号（重构前 15 个，现在 8 个，最长
__main__._run_foreground131 行，其中大半是"必须内嵌的 uvicorn 停机子类"）。 - 重复的等级门槛统一走
engine._is_locked/_require_level/_newly_unlocked， 不要在catalog/available_actions/plant/buy_animal/_gain_exp各写一份。
环境禁忌（本机特有）
-
os.makedirs(os.path.dirname(path), exist_ok=True)在 path 只有文件名时 （--pid-file pid.txt）dirname是空串，会以 FileNotFoundError 崩掉。 已抽farm/server/daemon.py的ensure_parent_dir()兜底，新代码用它，别再手写。 -
RemoteFarm.snapshot()是本地缓存、不发请求。关掉实时通道（realtime=False）的 脚本必须自己调refresh()，否则轮询永远读到同一份旧数据——服务器在推进却看起来像卡死。 TUI / 网页走 SSE 所以没这个问题；bot走available_actions()（会顺手带回最新状态）。 -
Windows 上文件句柄还开着就
os.remove()会失败（PermissionError / WinError 32）； 若被except OSError吞掉就是静默不生效（clear_pid_file曾因此永远删不掉 pid 文件）。 一律"先读完 → 关掉句柄 → 再删"。 -
Bash 的 coreutils 残缺（
ls/head/tail/grep/cat/rm缺失），不要用管道，会整条命令失败； 查看/删除文件一律写 Python 脚本（pathlib.unlink()/shutil.rmtree()）——连删临时脚本都别用 shell 的rm（safe-bin shim 依赖 dirname，直接 127）。跑测试也一样：cd /d/SimpleFarm && uv run python -m unittest ... 2>&1必须整条无管道（| tail -40会让命令直接 127 退出，看起来像"没输出"）。 PowerShell 跑原生命令的*>重定向会写成 UTF-16 + 中文乱码，别用它读输出。 -
写多行 git commit message 不要用
git commit -m "$(cat <<'EOF' ... EOF)"：本机没有cat， 会报cat: command not found然后 git 以为消息为空直接Aborting commit due to empty commit message（此时git add -A已经成功，暂存区是好的）。正确做法：把消息写进一个文件 （用 Write 工具，再read_bytes().replace(b"\r\n", b"\n")归一化成 LF，避免 CRLF 混进消息）， 然后git commit -F <文件>，最后删掉它。注意顺序：先git add -A再建消息文件， 这样消息文件不会进暂存区（而且见下条，它本来也会被忽略）。 -
.gitignore里有/_*（根目录下划线开头的文件全部忽略）：好处是临时补丁脚本 （_splice_app.py、_commit_msg.txt之类）默认就不会污染git status，跑完删不删都不碍事； 代价是放在根目录、以_开头的正经文件也会被静默忽略，要提交就换名字或放子目录。 -
环境设了
HTTP_PROXY但没有no_proxy：任何本机 HTTP 访问都要走farm/net.py的open_url()（回环直连），否则会拿到 502 并误判为"服务器没起来"。 -
Windows 下守护进程的 pid 必须由服务进程自己写（见
farm/server/__main__.py）， 父进程的Popen().pid不可信。 -
写文件必须指定行尾：Windows 上
pathlib.write_text()会把\n转成\r\n， 破坏本仓库"统一 LF"的约定（.gitattributes已声明eol=lf）。 用脚本改文件时一律read_bytes()/write_bytes()，或write_text(..., newline="\n")。 -
同一文件在一条消息里多次 Edit 会被静默覆盖（只落地一部分，随后报出"幽灵"错误）。 批量改同一文件时改用幂等 Python 补丁脚本：整文件读入 → 精确匹配替换 → 逐条打印
ALREADY/APPLIED/MISS，跑完即删。判断"已应用"要if new in text， 不要比对两行文本（会出现 new 是 old 子串的假阳性）。 -
git status报 M 但git diff为空，是索引 stat 缓存过期，不是真差异；git add -A（内容相同时等于无操作）即恢复干净。
代码风格约定（ruff / pyright 已固化在 pyproject.toml）
- 行宽 100；字符串统一双引号；
isort把farm视为第一方。 - 类型标注用 PEP 585/604 写法（
dict[str, int]/X | None），不要Dict/Optional。 - 吞异常要显式：
contextlib.suppress(...)优先于try/except/pass。 - 异常链：转换后重抛用
raise ... from exc；有意隐藏原始上下文用from None（不要省略，会触发 B904）。 - 路径保持
str（不要为了 lint 而转Path）；farm/__init__.py的惰性__all__导出是刻意设计。 - 改完代码的标准动作：
uv run ruff format . && uv run ruff check . && uv run pyright
远端仓库与推送（gitea.4i.hk）
- 远端：https://gitea.4i.hk/hhhge/SimpleFarm（public，默认分支
main，ownerhhhge）， 本地origin已指向https://gitea.4i.hk/hhhge/SimpleFarm.git并设好 upstream。 - 推送认证走 GCM 的 generic provider（
credential.https://gitea.4i.hk.provider=generic写在~/.gitconfig里）。关键：非交互 shell 里必须带GCM_INTERACTIVE=always， 否则 GCM 直接Cannot prompt because user interactivity has been disabled， 接着 git 报could not read Username / Failed to authenticate user，看起来像认证配置坏了。 加上这个环境变量后 GCM 会静默用已有的 OAuth 凭据续期，不需要弹窗也不需要手输：GCM_INTERACTIVE=always git push -u origin main teaCLI（0.16.0）已用 OAuth 登录该实例，配置在%LOCALAPPDATA%\tea\config.yml（token 存在系统 keyring，不在配置文件里）。可用来建仓与调 API：tea repos create --name X --login gitea.4i.hk（没有--public参数，默认就是公开）、tea api <path> -l gitea.4i.hk [-X POST -d '<json>']。 限制：OAuth token 不能签发访问令牌（POST /users/{u}/tokens需要 basic auth， 会返回 401auth required，这是 Gitea 防提权的设计）；但可以用它加 SSH 公钥 （POST /user/keys），所以将来若要免密推送，加一把密钥是可行的。- 本机 git 走
http.proxy / https.proxy = http://127.0.0.1:7890（写在~/.gitconfig）。 - 沙箱怪癖：
.git/refs/remotes/**里"新建目录"的写入跨命令调用会被丢弃， 于是git status -sb一直显示## main...origin/main [gone]（远端其实好着呢）。 修法是在同一个命令里先mkdir -p .git/refs/remotes/origin+ 写入 ref 文件， 紧接着跑git status——分开两条命令就又看不到。真实终端里直接git fetch即可。
相关文档
- 项目入口文档：
README.md（接口表、SSE 协议、边界处理、设计取舍全在里面） - 当天工作记录：
.workbuddy/memory/2026-09-19.md