chore: 工程化改造前的基线快照

在引入 uv 依赖管理、ruff 静态检查与格式化、pyright 类型检查之前，
先把当前可正常运行的状态固定下来，作为后续大规模自动改动的回滚点。

此时状态：97 项测试全绿，HTTP + WebSocket 多牧场服务器可用。

farm/server/app.py

@@ -0,0 +1,688 @@
+"""FastAPI 应用：REST + WebSocket + 网页客户端。
+
+接口设计原则
+------------
+1. **一切皆 JSON**：每个响应都带 ``ok`` 字段，出错时带机器可读的 ``error``
+   与人类可读的 ``message``，AI 可以直接拿 ``error`` 分支决策。
+2. **状态紧随结果**：每个写操作都会在响应里附一份精简状态（``state``），
+   这样 AI 一次请求就能同时"做动作 + 看结果"，省一半往返。
+3. **多牧场隔离**：用 ``farm`` 参数（或 ``X-Farm-Id`` 头）区分玩家，
+   每个牧场有自己的引擎、时钟与存档；互不影响。
+4. **实时通道**：``/ws`` 推送状态，人和 AI 都能订阅；HTTP 与 WS 改的是
+   同一个引擎，所以「网页里点一下，AI 那边立刻看到」。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+from fastapi import FastAPI, Request, WebSocket, WebSocketDisconnect
+from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse
+
+from .. import config
+from ..engine import GameError
+from . import actions as actions_mod
+from .hub import Client, ConnectionHub, Publisher, next_seq
+from .session import DEFAULT_FARM, FarmClock, FarmSession, SessionManager, validate_farm_id
+from .webui import DASHBOARD_HTML, dashboard_text
+
+API_VERSION = "2.0"
+SERVER_NAME = "SimpleFarm"
+
+
+@dataclass
+class ServerConfig:
+    """服务器配置（由命令行解析而来）。"""
+
+    host: str = "127.0.0.1"
+    port: int = 8765
+    token: Optional[str] = None
+    tick_seconds: float = config.DEFAULT_TICK_SECONDS
+    save_dir: str = "saves"
+    max_sessions: int = 64
+    idle_timeout: float = 1800.0
+    autosave_interval: float = 60.0
+    allow_remote_control: bool = True
+    world_name: str = "SimpleFarm 公共农场"
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+
+class ServerHandle:
+    """让 HTTP 接口能够优雅地要求本进程退出，并暴露进程生命周期的钩子。
+
+    * ``on_start``：监听端口成功后触发（用于写 pid 文件等）；
+    * ``on_stop``：请求关闭时触发（uvicorn 用它设置 ``should_exit``）。
+    """
+
+    def __init__(self) -> None:
+        self._start_callbacks: List[Callable[[], None]] = []
+        self._stop_callbacks: List[Callable[[], None]] = []
+        self.stopping = False
+
+    def on_start(self, callback: Callable[[], None]) -> None:
+        self._start_callbacks.append(callback)
+
+    def on_stop(self, callback: Callable[[], None]) -> None:
+        self._stop_callbacks.append(callback)
+
+    def notify_start(self) -> None:
+        for callback in list(self._start_callbacks):
+            try:
+                callback()
+            except Exception:
+                pass
+
+    def request_stop(self) -> bool:
+        if self.stopping:
+            return False
+        self.stopping = True
+        for callback in list(self._stop_callbacks):
+            try:
+                callback()
+            except Exception:
+                pass
+        return True
+
+
+# ---------------------------------------------------------------------- 工具
+def brief(session: FarmSession, hub: ConnectionHub) -> Dict[str, Any]:
+    """操作后回给调用者的精简状态：够做下一步决策，又不至于太吵。"""
+    snap = session.snapshot()
+    return {
+        "farm": session.farm_id,
+        "day": snap["day"],
+        "gold": snap["gold"],
+        "level": snap["level"],
+        "exp": snap["exp"],
+        "exp_needed": snap["exp_needed"],
+        "ap": snap["ap"],
+        "max_ap": snap["max_ap"],
+        "feed": snap["feed"],
+        "plot_count": snap["plot_count"],
+        "max_plots": snap["max_plots"],
+        "next_plot_price": snap["next_plot_price"],
+        "animal_count": snap["animal_count"],
+        "max_animals": snap["max_animals"],
+        "ripe_plots": [p["position"] for p in snap["plots"] if p["is_ripe"]],
+        "hungry_animals": [a["id"] for a in snap["animals"] if not a["fed"]],
+        "collectable_animals": [a["id"] for a in snap["animals"] if a["pending"] > 0],
+        "net_worth": snap["net_worth"],
+        "goal_index": snap["goal_index"],
+        "seconds_to_tick": snap["seconds_to_tick"],
+        "paused": snap["paused"],
+        "online": hub.online(session.farm_id),
+    }
+
+
+def rules_text() -> str:
+    return (
+        f"{SERVER_NAME} 规则速览（给 AI 玩家的上下文）\n"
+        "==========================================\n"
+        f"1. 时间：每个牧场每 {config.DEFAULT_TICK_SECONDS:.0f} 秒自动推进一天（可配置）。"
+        f"每天开始时行动点恢复为 {config.START_AP} 点，作物生长、牲畜产出、市场价格都在此刻结算。\n"
+        f"2. 行动点：播种/浇水/喂食各消耗 1 点，收获与收取产出免费。行动点用完只能等第二天"
+        "（POST /api/actions {\"action\":\"sleep\"} 可主动推进一天，有 2 秒冷却）。\n"
+        f"3. 水分：作物每天消耗 1 点水分（上限 {config.WATER_CAPACITY}），水分为 0 时停止生长。"
+        f"播种时自带 {config.PLANT_INITIAL_MOISTURE} 点水分。\n"
+        f"4. 收获：成熟后 harvest 获得金币与经验，有 {config.LUCKY_CHANCE:.0%} 概率丰收翻倍。\n"
+        "5. 牲畜：每天必须喂食才会累计产出周期；连续 3 天未进食会永久离开农场。\n"
+        f"6. 市场：作物与畜产品价格每天在基础价 ±{config.PRICE_VOLATILITY:.0%} 内波动，"
+        "高价卖出收益更高。\n"
+        f"7. 土地：初始 {config.BASE_PLOTS} 块，每升 1 级多 {config.PLOTS_PER_LEVEL} 块，"
+        f"上限 {config.MAX_PLOTS} 块；购地价格每次递增。\n"
+        "8. 目标：把净资产（金币 + 土地 + 牲畜 + 库存 + 地里作物）做到 10000 金币。\n"
+        "9. 多人：每个 farm 是一个独立牧场，用 ?farm=名字 区分，互不影响；"
+        "排行榜见 GET /api/world。\n"
+        "\n推荐决策循环（AI 最短路径）：\n"
+        "  GET  /api/actions?farm=me   → 拿到当前所有**合法**动作（含开销与理由）\n"
+        "  POST /api/actions           → {\"action\":\"<上一步里的 action>\","
+        "\"params\":{...}} 直接执行\n"
+        "  响应里的 state 就是执行后的最新状态，无需再查一次。\n"
+        "\n实时通道：ws://host/ws?farm=me ，服务器在状态变化时推送 state 消息；"
+        "也可以直接在 WS 上发送 {\"type\":\"action\",\"action\":\"plant\","
+        "\"params\":{\"plot\":1,\"crop\":\"wheat\"},\"id\":1} 并等待 result 回执。\n"
+    )
+
+
+# ---------------------------------------------------------------------- 应用
+def create_app(cfg: Optional[ServerConfig] = None) -> FastAPI:
+    cfg = cfg or ServerConfig()
+    manager = SessionManager(
+        save_dir=cfg.save_dir,
+        tick_seconds=cfg.tick_seconds,
+        max_sessions=cfg.max_sessions,
+        idle_timeout=cfg.idle_timeout,
+    )
+    hub = ConnectionHub()
+    publisher = Publisher(manager, hub, autosave_interval=cfg.autosave_interval)
+    clock = FarmClock(manager)
+    handle = ServerHandle()
+    started_at = time.time()
+    counters = {"requests": 0, "actions": 0, "ws_messages": 0, "errors": 0}
+
+    async def lifespan(_app: FastAPI) -> Any:
+        clock.start()
+        publisher.start()
+        # 端口已经绑定成功（uvicorn 先 bind 再跑 lifespan），可以对外宣告"我在了"
+        handle.notify_start()
+        try:
+            yield
+        finally:
+            publisher.stop()
+            clock.stop()
+            manager.shutdown()
+
+    app = FastAPI(
+        title=f"{SERVER_NAME} 游戏服务器",
+        version=API_VERSION,
+        description="命令行农场游戏的服务端：HTTP 给 AI 用，WebSocket 给实时界面用。",
+        lifespan=lifespan,
+    )
+    app.state.cfg = cfg
+    app.state.manager = manager
+    app.state.hub = hub
+    app.state.publisher = publisher
+    app.state.clock = clock
+    app.state.handle = handle
+    app.state.started_at = started_at
+    app.state.counters = counters
+
+    # ------------------------------------------------------------ 异常处理
+    @app.exception_handler(GameError)
+    async def _game_error(_request: Request, exc: GameError) -> JSONResponse:
+        counters["errors"] += 1
+        return JSONResponse(exc.to_dict(), status_code=exc.status)
+
+    @app.exception_handler(json.JSONDecodeError)
+    async def _bad_json(_request: Request, exc: json.JSONDecodeError) -> JSONResponse:
+        counters["errors"] += 1
+        return JSONResponse(
+            {"ok": False, "error": "bad_json", "message": f"请求体不是合法 JSON：{exc}"},
+            status_code=400,
+        )
+
+    # ------------------------------------------------------------ 鉴权与取牧场
+    def authorized(supplied: Optional[str]) -> bool:
+        if not cfg.token:
+            return True
+        return supplied == cfg.token
+
+    def token_of(request: Request) -> Optional[str]:
+        return request.headers.get("x-api-token") or request.query_params.get("token")
+
+    def guard(request: Request) -> None:
+        counters["requests"] += 1
+        if not authorized(token_of(request)):
+            raise GameError("unauthorized", "缺少或错误的 API Token", status=401)
+
+    def session_of(request: Request, owner: str = "") -> FarmSession:
+        farm = request.headers.get("x-farm-id") or request.query_params.get("farm") or DEFAULT_FARM
+        return manager.get(farm, create=True, owner=owner)
+
+    def full_requested(request: Request) -> bool:
+        raw = (request.query_params.get("full") or "").lower()
+        return raw in ("1", "true", "yes", "on")
+
+    async def body_of(request: Request) -> Dict[str, Any]:
+        raw = await request.body()
+        if not raw:
+            return {}
+        try:
+            data = json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise GameError("bad_json", f"请求体不是合法 JSON：{exc}")
+        if not isinstance(data, dict):
+            raise GameError("bad_json", "请求体必须是 JSON 对象")
+        return data
+
+    def execute_action(session: FarmSession, name: Any, params: Any) -> Dict[str, Any]:
+        """执行一个动作，返回引擎/会话级的结果字典。
+
+        ``save`` 与 ``reset`` 必须由**牧场会话**处理而不是引擎：
+        ``engine.save()`` 只会写到默认存档路径，多牧场环境下会把别人的存档覆盖掉。
+        这两个动作单独拦截，其余全部走统一的动作表。
+        """
+        key = name.strip().lower() if isinstance(name, str) else ""
+        if key == "save":
+            path = session.save()
+            session.engine.add_log(f"已存档到 {path}", "info")
+            return {"ok": True, "action": "save", "path": path,
+                    "message": f"已存档到 {path}"}
+        if key == "reset":
+            session.reset()
+            return {"ok": True, "action": "reset",
+                    "message": f"牧场「{session.farm_id}」已重置，重新开始经营"}
+        return actions_mod.run_action(session.engine, name, params)
+
+    def run_and_wrap(session: FarmSession, name: Any, params: Any,
+                     full: bool = False) -> Dict[str, Any]:
+        """执行动作并拼装统一响应。HTTP 与 WS 共用。"""
+        result = execute_action(session, name, params)
+        counters["actions"] += 1
+        session.touch(count_action=True)
+        payload: Dict[str, Any] = dict(result)
+        payload["ok"] = True
+        payload["farm"] = session.farm_id
+        payload["seq"] = next_seq()
+        payload["state"] = brief(session, hub)
+        payload["log"] = session.engine.recent_log(limit=3)
+        if full:
+            payload["snapshot"] = session.snapshot()
+        return payload
+
+    # ================================================================ 页面
+    @app.get("/", response_class=HTMLResponse, include_in_schema=False)
+    async def index() -> HTMLResponse:
+        return HTMLResponse(DASHBOARD_HTML)
+
+    @app.get("/text", response_class=PlainTextResponse, include_in_schema=False)
+    async def text_index() -> PlainTextResponse:
+        return PlainTextResponse(dashboard_text(cfg.host, cfg.port))
+
+    # ================================================================ 元信息
+    @app.get("/api/health", tags=["元信息"], summary="健康检查（无需鉴权）")
+    async def health() -> Dict[str, Any]:
+        return {
+            "ok": True,
+            "service": SERVER_NAME,
+            "version": API_VERSION,
+            "uptime": round(time.time() - started_at, 1),
+            "farms": manager.count(),
+            "clients": hub.total(),
+            "clock_ticks": clock.ticks,
+            "saves_since_start": publisher.pushes,
+        }
+
+    @app.get("/api/help", tags=["元信息"], summary="玩法规则与接口说明（给 AI 的说明书）")
+    async def help_page(request: Request) -> Dict[str, Any]:
+        guard(request)
+        return {
+            "ok": True,
+            "service": SERVER_NAME,
+            "version": API_VERSION,
+            "rules": rules_text(),
+            "actions": actions_mod.describe_actions(),
+            "crops": config.CROPS,
+            "animals": config.ANIMALS,
+            "endpoints": {
+                "state": "GET /api/state?farm=NAME",
+                "catalog": "GET /api/catalog?farm=NAME",
+                "actions": "GET /api/actions?farm=NAME",
+                "log": "GET /api/log?farm=NAME&limit=20&since=0",
+                "execute": "POST /api/actions  {\"action\":\"plant\",\"params\":{\"plot\":1,\"crop\":\"wheat\"}}",
+                "farms": "GET /api/farms | POST /api/farms {\"farm\":\"NAME\"}",
+                "realtime": "WS /ws?farm=NAME",
+            },
+        }
+
+    @app.get("/api/world", tags=["世界"], summary="世界概览：排行榜 + 在线连接 + 时钟")
+    async def world(request: Request) -> Dict[str, Any]:
+        guard(request)
+        return {
+            "ok": True,
+            "world": cfg.world_name,
+            "uptime": round(time.time() - started_at, 1),
+            "farms": manager.count(),
+            "clients": hub.total(),
+            "connections": hub.snapshot(),
+            "leaderboard": manager.leaderboard(hub.online_map()),
+            "tick_seconds": cfg.tick_seconds,
+            "started_at": started_at,
+        }
+
+    # ================================================================ 牧场
+    @app.get("/api/farms", tags=["世界"], summary="牧场排行榜")
+    async def list_farms(request: Request) -> Dict[str, Any]:
+        guard(request)
+        rows = manager.leaderboard(hub.online_map())
+        return {"ok": True, "count": len(rows), "farms": rows}
+
+    @app.post("/api/farms", tags=["世界"], summary="创建或进入一个牧场")
+    async def create_farm(request: Request) -> Dict[str, Any]:
+        guard(request)
+        body = await body_of(request)
+        farm = validate_farm_id(body.get("farm") or body.get("name"))
+        owner = str(body.get("owner") or "")
+        existed = manager.find(farm) is not None
+        session = manager.get(farm, create=True, owner=owner)
+        tick = body.get("tick")
+        if tick is not None:
+            try:
+                tick_value = float(tick)
+            except (TypeError, ValueError):
+                raise GameError("bad_param", "tick 必须是数字")
+            session.engine.tick_seconds = max(
+                config.MIN_TICK_SECONDS, min(config.MAX_TICK_SECONDS, tick_value)
+            )
+            session.engine.next_tick_at = time.time() + session.engine.tick_seconds
+        return {
+            "ok": True,
+            "created": not existed,
+            "message": ("牧场已创建" if not existed else "牧场已在运行") + f"：{farm}",
+            "farm": farm,
+            "summary": session.summary(hub.online(farm)),
+            "state": brief(session, hub),
+        }
+
+    # ================================================================ 单牧场只读
+    @app.get("/api/state", tags=["牧场"], summary="完整状态快照")
+    async def get_state(request: Request) -> Dict[str, Any]:
+        guard(request)
+        session = session_of(request)
+        return {
+            "ok": True,
+            "farm": session.farm_id,
+            "state": session.snapshot(),
+            "online": hub.online(session.farm_id),
+        }
+
+    @app.get("/api/catalog", tags=["牧场"], summary="作物/牲畜目录与实时价格")
+    async def get_catalog(request: Request) -> Dict[str, Any]:
+        guard(request)
+        session = session_of(request)
+        return {"ok": True, "farm": session.farm_id, "catalog": session.engine.catalog()}
+
+    @app.get("/api/actions", tags=["牧场"], summary="当前所有合法动作（AI 推荐入口）")
+    async def get_actions(request: Request) -> Dict[str, Any]:
+        guard(request)
+        session = session_of(request)
+        items = session.engine.available_actions()
+        return {
+            "ok": True,
+            "farm": session.farm_id,
+            "count": len(items),
+            "actions": items,
+            "state": brief(session, hub),
+        }
+
+    @app.get("/api/log", tags=["牧场"], summary="最近事件")
+    async def get_log(request: Request) -> Dict[str, Any]:
+        guard(request)
+        session = session_of(request)
+        limit = _int(request.query_params.get("limit"), 20, 1, 200)
+        since = _int(request.query_params.get("since"), 0, 0, 10 ** 9)
+        entries = session.engine.recent_log(limit=limit, since=since)
+        return {
+            "ok": True,
+            "farm": session.farm_id,
+            "count": len(entries),
+            "entries": entries,
+            "last_seq": entries[-1]["seq"] if entries else since,
+        }
+
+    # ================================================================ 写操作
+    @app.post("/api/actions", tags=["动作"], summary="通用动作入口（推荐 AI 使用）")
+    async def post_action(request: Request) -> Dict[str, Any]:
+        guard(request)
+        body = await body_of(request)
+        session = session_of(request)
+        name = body.get("action") or body.get("name")
+        params = body.get("params")
+        if params is None:
+            # 允许把参数平铺在顶层：{"action":"plant","plot":1,"crop":"wheat"}
+            params = {k: v for k, v in body.items() if k not in ("action", "name", "params")}
+        return run_and_wrap(session, name, params, full_requested(request))
+
+    @app.post("/api/batch", tags=["动作"], summary="批量执行动作（一个请求干多件事）")
+    async def post_batch(request: Request) -> Dict[str, Any]:
+        """给 AI 的省流入口：一次提交多个动作，按顺序执行。
+
+        每个动作独立成败，失败的只记错误不中断后续动作。
+        """
+        guard(request)
+        body = await body_of(request)
+        session = session_of(request)
+        items = body.get("actions")
+        if not isinstance(items, list) or not items:
+            raise GameError("bad_param", "actions 必须是至少含一个元素的数组")
+        if len(items) > 50:
+            raise GameError("too_many", "单次批量最多 50 个动作")
+        results: List[Dict[str, Any]] = []
+        for item in items:
+            if not isinstance(item, dict):
+                results.append({"ok": False, "error": "bad_param", "message": "每个动作必须是对象"})
+                continue
+            try:
+                payload = run_and_wrap(
+                    session, item.get("action"), item.get("params") or {}, full=False
+                )
+                results.append({k: v for k, v in payload.items() if k != "state"})
+            except GameError as exc:
+                counters["errors"] += 1
+                results.append({**exc.to_dict(), "action": item.get("action")})
+        ok_count = sum(1 for r in results if r.get("ok"))
+        payload: Dict[str, Any] = {
+            "ok": True,
+            "farm": session.farm_id,
+            "done": ok_count,
+            "failed": len(results) - ok_count,
+            "results": results,
+            "state": brief(session, hub),
+        }
+        if full_requested(request):
+            payload["snapshot"] = session.snapshot()
+        return payload
+
+    def make_action_route(action_name: str) -> Callable[[Request], Any]:
+        async def route(request: Request) -> Dict[str, Any]:
+            guard(request)
+            body = await body_of(request)
+            session = session_of(request)
+            return run_and_wrap(session, action_name, body, full_requested(request))
+
+        route.__name__ = f"post_{action_name}"
+        return route
+
+    for _name, _spec in actions_mod.ACTIONS.items():
+        app.add_api_route(
+            f"/api/{_name}",
+            make_action_route(_name),
+            methods=["POST"],
+            name=f"action_{_name}",
+            tags=["动作"],
+            summary=f"{_spec.summary}（等价于 POST /api/actions）",
+        )
+
+    # ================================================================ 管理
+    @app.post("/api/admin/save", tags=["管理"], summary="把所有牧场写入存档")
+    async def admin_save(request: Request) -> Dict[str, Any]:
+        guard(request)
+        saved: List[str] = []
+        for session in manager.all():
+            try:
+                session.save()
+                saved.append(session.farm_id)
+            except OSError as exc:
+                raise GameError("save_failed", f"{session.farm_id} 存档失败：{exc}", status=500)
+        return {"ok": True, "message": f"已保存 {len(saved)} 个牧场", "farms": saved}
+
+    @app.post("/api/admin/shutdown", tags=["管理"], summary="优雅停机（守护进程 stop 使用）")
+    async def admin_shutdown(request: Request) -> Dict[str, Any]:
+        guard(request)
+        if not cfg.allow_remote_control:
+            raise GameError("forbidden", "服务器未开放远程停机", status=403)
+        manager.shutdown()
+        accepted = handle.request_stop()
+        return {
+            "ok": True,
+            "message": "服务器正在优雅停机，存档已写入" if accepted else "停机请求已受理（重复）",
+        }
+
+    # ================================================================ WebSocket
+    @app.websocket("/ws")
+    async def ws_endpoint(websocket: WebSocket) -> None:
+        params = websocket.query_params
+        supplied = websocket.headers.get("x-api-token") or params.get("token")
+        if not authorized(supplied):
+            # 4401 是自定义关闭码，客户端据此提示"令牌不对"而不是"网络断了"
+            await websocket.close(code=4401, reason="unauthorized")
+            return
+
+        try:
+            farm = validate_farm_id(params.get("farm") or DEFAULT_FARM)
+        except GameError as exc:
+            await websocket.close(code=4400, reason=exc.message[:120])
+            return
+
+        await websocket.accept()
+        loop = asyncio.get_running_loop()
+        client = Client(farm, loop, name=(params.get("name") or "")[:32])
+        try:
+            session = manager.get(farm, create=True)
+        except GameError as exc:
+            # 例如牧场数量达到上限：说清楚原因再关，别让客户端以为是网络问题
+            await websocket.send_json({"type": "error", "error": exc.code,
+                                       "message": exc.message})
+            await websocket.close(code=1013, reason=exc.message[:100])
+            return
+        hub.register(client)
+        session.touch()
+
+        await websocket.send_json({
+            "type": "welcome",
+            "client_id": client.cid,
+            "farm": farm,
+            "server": {
+                "name": SERVER_NAME,
+                "version": API_VERSION,
+                "world": cfg.world_name,
+                "tick_seconds": session.engine.tick_seconds,
+            },
+            "state": session.snapshot(),
+            "catalog": session.engine.catalog(),
+            "actions": session.engine.available_actions(),
+            "log": session.engine.recent_log(limit=12),
+            "online": hub.online(farm),
+        })
+        hub.broadcast(
+            farm,
+            {"type": "notice", "farm": farm,
+             "text": f"{client.name or client.cid} 来到了牧场（在线 {hub.online(farm)}）"},
+            exclude=client,
+        )
+
+        async def writer() -> None:
+            while True:
+                message = await client.next_message()
+                await websocket.send_json(message)
+
+        async def reader() -> None:
+            while True:
+                raw = await websocket.receive_text()
+                counters["ws_messages"] += 1
+                await handle_ws_message(raw)
+
+        async def handle_ws_message(raw: str) -> None:
+            """处理一条客户端消息。
+
+            注意：这里只做「解析 + 派发」，真正的引擎调用丢给线程池，
+            因此一条慢查询不会让同一个连接的心跳/推送卡住。
+            """
+            try:
+                data = json.loads(raw)
+            except json.JSONDecodeError as exc:
+                await websocket.send_json({"type": "error", "error": "bad_json",
+                                           "message": f"不是合法 JSON：{exc}"})
+                return
+            if not isinstance(data, dict):
+                await websocket.send_json({"type": "error", "error": "bad_json",
+                                           "message": "消息必须是 JSON 对象"})
+                return
+
+            kind = str(data.get("type") or "").lower()
+            rid = data.get("id")
+
+            if kind == "ping":
+                await websocket.send_json({"type": "pong", "id": rid, "t": time.time()})
+                return
+
+            if kind in ("sync", "refresh", "state"):
+                await websocket.send_json({
+                    "type": "sync",
+                    "id": rid,
+                    "seq": next_seq(),
+                    "farm": session.farm_id,
+                    "state": session.snapshot(),
+                    "actions": session.engine.available_actions(),
+                    "log": session.engine.recent_log(limit=20),
+                })
+                return
+
+            if kind == "help":
+                await websocket.send_json({"type": "help", "id": rid, "rules": rules_text(),
+                                           "actions": actions_mod.describe_actions()})
+                return
+
+            if kind == "action":
+                try:
+                    # 引擎是同步的，丢到线程池里跑，别堵住事件循环
+                    result = await asyncio.to_thread(
+                        execute_action, session, data.get("action"),
+                        data.get("params") or {},
+                    )
+                except GameError as exc:
+                    counters["errors"] += 1
+                    await websocket.send_json({"type": "result", "id": rid, "ok": False,
+                                               "error": exc.code, "message": exc.message,
+                                               "farm": session.farm_id})
+                    return
+                counters["actions"] += 1
+                session.touch(count_action=True)
+                await websocket.send_json({
+                    "type": "result",
+                    "id": rid,
+                    "ok": True,
+                    "farm": session.farm_id,
+                    "message": result.get("message", "完成"),
+                    "result": result,
+                    "state": brief(session, hub),
+                    # 回执里带上完整快照：客户端可以立刻刷新画面，不必等下一次推送
+                    "snapshot": session.snapshot(),
+                    "log": session.engine.recent_log(limit=3),
+                    "seq": next_seq(),
+                })
+                return
+
+            await websocket.send_json({"type": "error", "error": "unknown_message",
+                                       "message": f"不认识的消息类型 {kind!r}",
+                                       "hint": "可用：action / ping / sync / help"})
+
+        writer_task = asyncio.create_task(writer())
+        reader_task = asyncio.create_task(reader())
+        try:
+            await asyncio.wait({writer_task, reader_task}, return_when=asyncio.FIRST_COMPLETED)
+        except WebSocketDisconnect:
+            pass
+        except Exception:
+            counters["errors"] += 1
+        finally:
+            for task in (writer_task, reader_task):
+                task.cancel()
+            hub.unregister(client)
+            session.touch()
+            hub.broadcast(
+                session.farm_id,
+                {"type": "notice", "farm": session.farm_id,
+                 "text": f"{client.name or client.cid} 离开了牧场（在线 {hub.online(session.farm_id)}）"},
+            )
+
+    return app
+
+
+def _int(raw: Optional[str], default: int, low: int, high: int) -> int:
+    if raw is None or raw == "":
+        return default
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        raise GameError("bad_param", f"参数必须是整数，收到 {raw!r}")
+    return max(low, min(high, value))
+
+
+def build_app(host: str = "127.0.0.1", port: int = 8765, **kwargs: Any) -> FastAPI:
+    """给外部（测试、嵌入式调用）用的便捷工厂。"""
+    return create_app(ServerConfig(host=host, port=port, **kwargs))