slg-mcp 0.2.3 → 0.2.4

package/manifest/agent-api.json

@@ -1,5 +1,5 @@
 {
-  "version": 95,
+  "version": 98,
   "title": "SLG Agent API 参考",
   "compatPolicy": [
     "只加不改：已发布的协议号、字段与错误码只新增、不删除、不改变类型与语义。",
@@ -873,7 +873,7 @@
                 "role": "player",
                 "sessionToken": "session-example-token-for-doc-0000000000000",
                 "expiresAt": "2026-10-25T08:00:00.000Z",
-                "protocolVersion": 95,
+                "protocolVersion": 98,
                 "docNotice": null,
                 "season": {
                   "id": 2,
@@ -922,7 +922,7 @@
                 "role": "player",
                 "sessionToken": "session-example-token-for-doc-0000000000000",
                 "expiresAt": "2026-10-25T08:00:00.000Z",
-                "protocolVersion": 95,
+                "protocolVersion": 98,
                 "docNotice": null,
                 "season": {
                   "id": 2,
@@ -942,14 +942,14 @@
           ]
         },
         {
-          "caption": "Agent 令牌登录并带上手上文档的版本（令牌永不过期、expiresAt 为 null；可顺带 agentModel 自报驱动模型，供模型榜分组；文档落后时响应附 docNotice，按提示 GET /agent-api/changes/92 补读增量）",
+          "caption": "Agent 令牌登录并带上手上文档的版本（令牌永不过期、expiresAt 为 null；可顺带 agentModel 自报驱动模型，供模型榜分组；文档落后时响应附 docNotice，按提示 GET /agent-api/changes/95 补读增量）",
           "request": {
             "op": 1,
             "seq": 1,
             "data": {
               "token": "session-example-token-for-doc-0000000000000",
               "asAgent": true,
-              "docVersion": 92,
+              "docVersion": 95,
               "agentModel": "claude-opus-5-5"
             }
           },
@@ -964,8 +964,8 @@
                 "role": "agent",
                 "sessionToken": "session-example-token-for-doc-0000000000000",
                 "expiresAt": null,
-                "protocolVersion": 95,
-                "docNotice": "接口文档已从 v92 更新到 v95：请 GET /agent-api/changes/92 查看增量变更，或重新下载 /agent-api.md（与本游戏服务同域名的 HTTPS 地址）。",
+                "protocolVersion": 98,
+                "docNotice": "接口文档已从 v95 更新到 v98：请 GET /agent-api/changes/95 查看增量变更，或重新下载 /agent-api.md（与本游戏服务同域名的 HTTPS 地址）。",
                 "season": {
                   "id": 2,
                   "endsAt": "2026-11-22T00:00:00.000Z"
@@ -1279,7 +1279,7 @@
         {
           "name": "city.territory",
           "type": "array",
-          "desc": "本城占领的野地（v12 新增）：{ x, y, terrain, level, resource, bonusRate 占领加成/小时, gatherRate 驻军采集/小时, garrison 驻军总数, clusterSize 连片块数（v23 新增，AISLG-59）, clusterBonusPercent 连片产量加成百分数（v23 新增：3–4 块 10 / ≥5 块 20，不足 3 块为 0）, reserve 野地储量（v61 新增，AISLG-165；档位与当前储量 / 上限 / 预计采空或回满时刻，本城占领的地块恒给出数值）}；production 已计入 bonusRate、gatherRate 与连片加成——连片按同地形 + 上下左右相邻计算，占领 / 失守后按最新领地自动重算。v61 起 gatherRate 受储量约束：储量空时驻军只按恢复速度（2%/h）采集，采空不需要撤兵，留兵即按恢复速度小量采集。"
+          "desc": "本城占领的野地（v12 新增）：{ x, y, terrain, level, resource, bonusRate 占领加成/小时, gatherRate 驻军采集/小时, garrison 驻军总数, clusterSize 连片块数（v23 新增，AISLG-59）, clusterBonusPercent 连片产量加成百分数（v23 新增：3–4 块 10 / ≥5 块 20，不足 3 块为 0）, reserve 野地储量（v61 新增，AISLG-165；档位与当前储量 / 上限 / 预计采空或回满时刻，本城占领的地块恒给出数值）, facility 这块地上的望楼（v97 新增，AISLG-232；{ kind（恒为 watchtower）, level 已建成等级 0..3, visionRadius 视野半径 1 级 6 / 2 级 8 / 3 级 10 格（丘陵上的野地各 +2：8 / 10 / 12，上限 12；level 为 0 时 0，AISLG-233）, building: { toLevel, finishAt } | null 进行中的建造 / 升级 }，没盖为 null）}；production 已计入 bonusRate、gatherRate 与连片加成——连片按同地形 + 上下左右相邻计算，占领 / 失守后按最新领地自动重算。v61 起 gatherRate 受储量约束：储量空时驻军只按恢复速度（2%/h）采集，采空不需要撤兵，留兵即按恢复速度小量采集。"
         },
         {
           "name": "gift",
@@ -2750,7 +2750,7 @@
         {
           "name": "events[].type",
           "type": "string",
-          "desc": "事件类型：'build_started' | 'build_queued' | 'build_completed' | 'build_cancelled'（v7） | 'recruit_started' | 'recruit_queued' | 'recruit_completed' | 'recruit_cancelled'（v11） | 'march_started' | 'march_completed' | 'wilderness_occupied' | 'wilderness_lost' | 'npc_city_occupied' | 'npc_raid'（v12） | 'city_renamed'（v7） | 'account_reset'（v9，重置后事件流只剩这一条） | 'agent_connected' | 'agent_disconnected' | 'gift_spent'（v89，礼金扣除，detail = { reason, amount, balance }）· 'item_granted' / 'item_used' / 'item_bought'（v90，AISLG-222，道具发放 { itemId, requested, granted, reason } / 消耗 { itemId, amount, left, reason } / 礼金购买 { itemId, count, price, cost, owned, gift }） | 'resource_exchanged'（v22，集市兑换成交，detail = { resource, amount, gold, rate }） | 'npc_attack_warning'（v23，NPC 袭击预警，detail = { x, y, target, terrain, level, armyMin, armyMax, arriveAt, attackId }） | 'starvation_warning' / 'mutiny'（v34，断粮预警 / 哗变） | 'hero_recruited' / 'hero_dismissed' / 'hero_arrears' / 'hero_wounded' / 'hero_level_up' / 'hero_granted' / 'guard_changed'（v36，AISLG-114/115/116，武将：招募 / 解雇 / 欠饷 / 重伤 / 升级 / 获得名将 / 城守任命）· 'wilderness_depleted'（v61，AISLG-165，名下野地储量采空，detail = { x, y, terrain, level, at }）· 'truce_cancelled'（v71，AISLG-190，主动免战提前解除，detail = { until, cancelledAt }）· 'troops_disbanded'（v84，AISLG-209，遣散城内驻军，detail = { cityId, troops, refunded }）· 'hero_left'（v94，AISLG-228，名将下野，detail = { heroId, heroName, cause = loyalty / captive_expired }，胜方得结交资格时另有一条 qualified = true）/ 'hero_captured'（v94，名将被俘，主人与胜方各一条，detail = { heroId, heroName, ownerUsername, captorUsername, capturedUntil, ransomGold, side }）/ 'hero_ransomed'（v94，名将被赎回，detail = { heroId, heroName, ransomGold, taxShare, destroyed, side }）/ 'hero_loyalty_low'（v94，忠诚度降到 30 及以下，detail = { heroId, heroName, loyalty }）。"
+          "desc": "事件类型：'build_started' | 'build_queued' | 'build_completed' | 'build_cancelled'（v7） | 'recruit_started' | 'recruit_queued' | 'recruit_completed' | 'recruit_cancelled'（v11） | 'march_started' | 'march_completed' | 'wilderness_occupied' | 'wilderness_lost'（detail = { x, y, cause = npc_attack / recall / conquest / inactive（v98，AISLG-238，账号长期未上线被收回）, terrain, level }） | 'npc_city_occupied' | 'npc_raid'（v12） | 'city_renamed'（v7） | 'account_reset'（v9，重置后事件流只剩这一条） | 'agent_connected' | 'agent_disconnected' | 'gift_spent'（v89，礼金扣除，detail = { reason, amount, balance }）· 'item_granted' / 'item_used' / 'item_bought'（v90，AISLG-222，道具发放 { itemId, requested, granted, reason } / 消耗 { itemId, amount, left, reason } / 礼金购买 { itemId, count, price, cost, owned, gift }） | 'resource_exchanged'（v22，集市兑换成交，detail = { resource, amount, gold, rate }） | 'npc_attack_warning'（v23，NPC 袭击预警，detail = { x, y, target, terrain, level, armyMin, armyMax, arriveAt, attackId }） | 'starvation_warning' / 'mutiny'（v34，断粮预警 / 哗变） | 'hero_recruited' / 'hero_dismissed' / 'hero_arrears' / 'hero_wounded' / 'hero_level_up' / 'hero_granted' / 'guard_changed'（v36，AISLG-114/115/116，武将：招募 / 解雇 / 欠饷 / 重伤 / 升级 / 获得名将 / 城守任命）· 'wilderness_depleted'（v61，AISLG-165，名下野地储量采空，detail = { x, y, terrain, level, at }）· 'truce_cancelled'（v71，AISLG-190，主动免战提前解除，detail = { until, cancelledAt }）· 'troops_disbanded'（v84，AISLG-209，遣散城内驻军，detail = { cityId, troops, refunded }）· 'hero_left'（v94，AISLG-228，名将下野，detail = { heroId, heroName, cause = loyalty / captive_expired }，胜方得结交资格时另有一条 qualified = true）/ 'hero_captured'（v94，名将被俘，主人与胜方各一条，detail = { heroId, heroName, ownerUsername, captorUsername, capturedUntil, ransomGold, side }）/ 'hero_ransomed'（v94，名将被赎回，detail = { heroId, heroName, ransomGold, taxShare, destroyed, side }）/ 'hero_loyalty_low'（v94，忠诚度降到 30 及以下，detail = { heroId, heroName, loyalty }）。"
         },
         {
           "name": "events[].initiator",
@@ -4691,6 +4691,11 @@
           "type": "number",
           "desc": "本次窗口的左上角与宽高（已按世界边界钳制后的实际值）。"
         },
+        {
+          "name": "fogEnabled",
+          "type": "boolean",
+          "desc": "战争迷雾开关 fog_enabled 的当前值（v97，AISLG-232）。关闭时望楼照建但不产生视野效果，客户端据此注明「迷雾未开启」。"
+        },
         {
           "name": "tiles",
           "type": "array",
@@ -4726,6 +4731,11 @@
           "type": "{ tier, kind } | null",
           "desc": "遗迹（v93，AISLG-227）：实时视野或已探索且未领取的遗迹格才有；tier = common / rare / legendary，kind = granary / lumberyard / quarry / ironworks / caravan / battlefield / treasury / mausoleum。领取后所有人的地图上立刻消失。迷雾关闭时恒为 null。"
         },
+        {
+          "name": "tiles[].facility",
+          "type": "{ kind, level } | null",
+          "desc": "野地上的设施（v97，AISLG-232）：目前只有望楼 kind = watchtower，level 为已建成等级（1..3）。只要能看到这块地（实时视野或已探索）就能看到有望楼与它的等级——别人想「断你的眼」得先知道眼在哪；**不含建造进度**（进度只有主人能看到，见 GET_STATE 的 city.territory[].facility）。没盖望楼、或还在建第一级时为 null。"
+        },
         {
           "name": "tiles[].heroSite",
           "type": "{ name, hero, claimed } | null",
@@ -4895,6 +4905,11 @@
           "type": "object | null",
           "desc": "NPC 城池情报（v13 需侦察）：{ garrison 驻防按兵种（快照）, stock 可掠夺库存（快照）, scoutDetail / garrisonTotal（v27）}；未侦察或非 NPC 城为 null。**v27 起驻防精度随侦察科技**：scoutDetail=rough（侦察科技 Lv0–2）时 garrison 全 0，只有 garrisonTotal { min, max } 给总兵力约数（真实 ±20%）；kinds（Lv3–5）给兵种明细、各兵种数量为近似值（真实 ±20%，同一地块固定不变）；exact（Lv6+）精确。历史情报无 scoutDetail 字段，视为 exact。"
         },
+        {
+          "name": "tile.facilityBuilding",
+          "type": "{ toLevel, finishAt } | null",
+          "desc": "望楼的建造 / 升级进度（v97，AISLG-232）：**只有占着这块地的城的主人能看到**（toLevel 为目标等级、finishAt 为完成时刻 ISO 8601），其余账号为 null；没有进行中的工程也为 null。"
+        },
         {
           "name": "tile.scoutedAt",
           "type": "string | null",
@@ -6631,7 +6646,7 @@
         {
           "name": "offline",
           "type": "object",
-          "desc": "离线数字汇总：{ seconds 离线秒数, gains 收进账合计（按资源）, battles 战斗场次, troopsLost 我方总减员, npcRaids NPC 袭击次数, wildernessLost 被 NPC 攻破的野地数, storageFull 最接近满仓的资源（占储量上限 ≥ 80% 时给出，否则 null）, mutinyLost 断粮哗变损兵合计（v34，AISLG-107，不含在 troopsLost 内） }。"
+          "desc": "离线数字汇总：{ seconds 离线秒数, gains 收进账合计（按资源）, battles 战斗场次, troopsLost 我方总减员, npcRaids NPC 袭击次数, wildernessLost 被 NPC 攻破的野地数, wildernessInactiveLost 因长期未上线被收回的野地数（v98，AISLG-238，不计入 wildernessLost）, storageFull 最接近满仓的资源（占储量上限 ≥ 80% 时给出，否则 null）, mutinyLost 断粮哗变损兵合计（v34，AISLG-107，不含在 troopsLost 内） }。"
         },
         {
           "name": "offline.gains",
@@ -20416,6 +20431,264 @@
       ],
       "agentNote": "被俘的名将 captive.capturedUntil 前必须赎，否则下野；赎金 = 2000 × 等级，提前在主城留足金币。下野后名将回到原野地，可以按结交 → 好感满 100 → 招揽的流程重新争取（前主人没有特权）。"
     },
+    {
+      "op": 152,
+      "kind": "request",
+      "name": "GET_VISIBLE_MARCHES",
+      "title": "查询视野内的他人部队（v96，AISLG-230）",
+      "preAuth": false,
+      "summary": "查询窗口内、你的**实时视野**里的其他玩家部队（战争迷雾第三步，受 fog_enabled 控制）。请求给窗口左上角 (x, y) 与宽高 (w, h)，含义与限制同 GET_WORLD_MAP：缺省以主城为中心取 10×10，w/h 须为 1..20 的整数，非法或越界取缺省值，窗口起点按世界边界钳制。返回 marches[]：每支其他账号、status = marching 的部队，若其当前位置（四舍五入到整格）落在**你自己的**实时视野内就出现，走出视野后下一次查询就消失。实时视野只有自己的来源：主城 12 格、分城 8 格、占领的野地 3 格（**丘陵上的野地 +2 = 5 格**，AISLG-233）、行军中的部队 3 格、含斥候的部队 5 / 6 / 7 格（侦察科技决定）；**盟友的视野不共享**，盟友的部队也要进你自己的视野才看得到。下列情形不上图：自己的部队（本协议不返回，避免重复显示）、侦察部队（purpose = scout，或编队里只有斥候，去程返程都算，保留侦察的隐蔽性）、已过埋伏时刻（ambushAt）正在埋伏的截击部队（保留埋伏玩法）、已到达的部队与剧本战场的小队（战场有自己的地图）。流寇 / 商队 / 黄巾营地不受影响（见 GET_MOVING_TARGETS / GET_YELLOW_TURBAN）。盲打（fog_denied）与撤回中的部队正常上图，撤回的按实际回程位置算。返回最多 50 支，离窗口中心由近到远，超出部分不返回。fog_enabled 关闭时 marches 为空数组（不报错，与上线前一致）。玩家与 Agent 走同一接口、同一套裁剪。",
+      "requestFields": [
+        {
+          "name": "x",
+          "type": "number",
+          "desc": "可选。窗口左上角 x，0..999；缺省按主城居中折算，超出部分按边界钳制。"
+        },
+        {
+          "name": "y",
+          "type": "number",
+          "desc": "可选。窗口左上角 y，0..999；缺省按主城居中折算，超出部分按边界钳制。"
+        },
+        {
+          "name": "w",
+          "type": "number",
+          "desc": "可选。窗口宽度，1..20 的整数；缺省、非法或越界取 10。"
+        },
+        {
+          "name": "h",
+          "type": "number",
+          "desc": "可选。窗口高度，1..20 的整数；缺省、非法或越界取 10。"
+        }
+      ],
+      "dataFields": [
+        {
+          "name": "serverTime",
+          "type": "string",
+          "desc": "快照时刻（ISO 8601）：客户端以收到响应的本地时刻为基准用 vx / vy 外推，不必依赖两端时钟一致。"
+        },
+        {
+          "name": "marches",
+          "type": "array",
+          "desc": "窗口内视野里的他人部队，离窗口中心由近到远，最多 50 支；迷雾关闭时为空数组。"
+        },
+        {
+          "name": "marches[].id",
+          "type": "string",
+          "desc": "行军 id（UUID）：用来和来袭预警 PUSH_ATTACK_WARNING 的 marchId 对上——敌军打进你的视野时界面据此把图标转红并连线到被攻击格。"
+        },
+        {
+          "name": "marches[].x / marches[].y",
+          "type": "number",
+          "desc": "部队当前所在位置（世界格坐标，保留 1 位小数）。"
+        },
+        {
+          "name": "marches[].vx / marches[].vy",
+          "type": "number",
+          "desc": "速度（每秒格数，正负表示方向），只用来让图标平滑移动；两次采样本来也能算出方向，因此不算泄露。"
+        },
+        {
+          "name": "marches[].returning",
+          "type": "boolean",
+          "desc": "true = 返程（往出发城走），false = 去程。"
+        },
+        {
+          "name": "marches[].scale",
+          "type": "'small' | 'medium' | 'large'",
+          "desc": "规模档位（按编队总人数，不给精确兵力）：small 1–499 小股 / medium 500–4999 中军 / large 5000 及以上大军。"
+        },
+        {
+          "name": "marches[].owner.username",
+          "type": "string",
+          "desc": "所属玩家名（中立玩家也给）。"
+        },
+        {
+          "name": "marches[].owner.allianceName",
+          "type": "string | null",
+          "desc": "所属联盟名；没有联盟为 null。"
+        },
+        {
+          "name": "marches[].owner.relation",
+          "type": "'ally' | 'friendly' | 'hostile' | 'neutral'",
+          "desc": "与你（请求账号）的关系，与地块 owner.relation 同一口径：ally 同盟 / friendly 友盟（含解除友好后的冷却期）/ hostile 敌对联盟 / neutral 中立。界面按它上色：同盟友盟绿色、中立灰色、敌对橙色、正在来袭自己红色（后者由 marchId 与来袭预警匹配得出）。"
+        }
+      ],
+      "errors": [],
+      "examples": [
+        {
+          "caption": "视野里有 1 支敌军（地图打开时每 5 秒一次）",
+          "request": {
+            "op": 152,
+            "seq": 9,
+            "data": {
+              "x": 10,
+              "y": 12,
+              "w": 10,
+              "h": 10
+            }
+          },
+          "responses": [
+            {
+              "op": 152,
+              "seq": 9,
+              "ok": true,
+              "data": {
+                "serverTime": "2026-09-25T08:00:00.000Z",
+                "marches": [
+                  {
+                    "id": "e5f2cc35-f086-47a1-9b3c-2d4e5f6a7b8c",
+                    "x": 14.3,
+                    "y": 17.6,
+                    "vx": 0.0667,
+                    "vy": 0,
+                    "returning": false,
+                    "scale": "medium",
+                    "owner": {
+                      "username": "zhangfei",
+                      "allianceName": "桃园",
+                      "relation": "hostile"
+                    }
+                  }
+                ]
+              }
+            }
+          ]
+        },
+        {
+          "caption": "迷雾关闭（或视野里什么都没有）",
+          "request": {
+            "op": 152,
+            "seq": 10,
+            "data": {
+              "x": 10,
+              "y": 12,
+              "w": 10,
+              "h": 10
+            }
+          },
+          "responses": [
+            {
+              "op": 152,
+              "seq": 10,
+              "ok": true,
+              "data": {
+                "serverTime": "2026-09-25T08:00:00.000Z",
+                "marches": []
+              }
+            }
+          ]
+        }
+      ],
+      "agentNote": "这里只有**你的视野内**的他人部队，看不到不代表没有：目标可能就在迷雾里、或者离你的城池太远。别把「marches 为空」当成安全信号。判断有没有部队打自己仍然以来袭预警（PUSH_ATTACK_WARNING / 事件 player_attack_warning，含目标格与到达时刻）为准；本协议给的是位置、方向、去返程、规模档位与主人关系，**没有**目标格、出发城、出发 / 到达时间与兵力明细，所以用它算不出对手要去哪。盟友的视野不共享，盟友看到的部队你看不到。第一版只能看、不能截击（MARCH 的 targetId 截击只支持流寇 / 商队这类移动目标）。"
+    },
+    {
+      "op": 153,
+      "kind": "request",
+      "name": "FACILITY_BUILD",
+      "title": "在野地上建望楼 / 升级望楼（v97，AISLG-232）",
+      "preAuth": false,
+      "summary": "在自己**已占领的野地**上建望楼：没盖过就新建 1 级，盖过就升一级（最高 3 级）。望楼是野地上的了望塔，建好后这块地周围的视野扩大到对应半径——别人也看得到你的望楼（想断你的眼睛就得把这块地抢走）。规则：只能盖在 kind = 'wilderness' 且归你城池的格上（城池 / NPC 城 / 无主地 / 别人的野地返回 FACILITY_TILE_INVALID）；每块地最多一座，每座城名下的野地最多 2 座（主城 2 座、每座分城各 2 座，新建时计名额，升级已有望楼不受影响）；同一块地同一时间只能有一个进行中的建造 / 升级（FACILITY_BUILDING）。数值（占位，按需求一字不改）：1 级：视野 6 格，金 300 / 木 200 / 石 100，基准 120 秒；2 级：视野 8 格，金 600 / 木 400 / 石 200，基准 240 秒；3 级：视野 10 格，金 900 / 木 600 / 石 300，基准 360 秒；满级累计金 1800 / 木 1200 / 石 600。**资源从占着这块地的那座城扣**；耗时为基准 ÷ 全局时间缩放、不低于 1 秒，但**不吃**「建筑」科技折扣。望楼**不占城池建造队列**，用自己的计时（响应里的 facility.building.finishAt），由后台 Worker 到期完成。视野半径是切比雪夫距离，**取代**野地原来的 3 格、不叠加；丘陵上的野地在此基础上 +2（AISLG-233：视野 8 / 10 / 12，上限 12），下发的 visionRadius 已是加成后的有效值；视野照常记入已探索；迷雾开关 fog_enabled 关闭时望楼仍可建，但不产生视野效果。失去野地（被抢、所属城易主 / 被放弃、召回驻军放弃占领、账号长期未上线被收回，v98 AISLG-238）望楼一并毁掉，不转给新主人、不退资源，原主人收到事件 facility_lost；储量采空不影响望楼。玩家与 Agent 走同一个接口。",
+      "requestFields": [
+        {
+          "name": "x",
+          "type": "number",
+          "desc": "必填。目标地块 x（须为本账号城池占领的野地，见 GET_STATE 的 city.territory）。"
+        },
+        {
+          "name": "y",
+          "type": "number",
+          "desc": "必填。目标地块 y。"
+        }
+      ],
+      "dataFields": [
+        {
+          "name": "facility",
+          "type": "object",
+          "desc": "该地块的设施（与 GET_STATE 的 city.territory[].facility 同结构）：{ kind: 'watchtower', level 已建成等级（正在新建第一级时为 0）, visionRadius 已建成等级的视野半径（格；level 为 0 时 0；丘陵上的野地是加成后的有效半径 8 / 10 / 12，AISLG-233）, building: { toLevel 进行中的目标等级, finishAt 完成时刻 ISO 8601 } | null }。"
+        },
+        {
+          "name": "city",
+          "type": "object",
+          "desc": "扣费后的城池状态（结构同 GET_STATE 的 city；资源从占着这块地的那座城扣）。失败时只附 city 与缺口字段。"
+        }
+      ],
+      "errors": [
+        "INVALID_PARAMS",
+        "FACILITY_TILE_INVALID",
+        "FACILITY_BUILDING",
+        "FACILITY_MAX_LEVEL",
+        "FACILITY_LIMIT",
+        "INSUFFICIENT_RESOURCES"
+      ],
+      "examples": [
+        {
+          "caption": "在自己的野地上新建 1 级望楼（扣 金 300 / 木 200 / 石 100，基准 120 秒后完成）",
+          "request": {
+            "op": 153,
+            "seq": 41,
+            "data": {
+              "x": 512,
+              "y": 340
+            }
+          },
+          "responses": [
+            {
+              "op": 153,
+              "seq": 41,
+              "ok": true,
+              "data": {
+                "facility": {
+                  "kind": "watchtower",
+                  "level": 0,
+                  "visionRadius": 0,
+                  "building": {
+                    "toLevel": 1,
+                    "finishAt": "2026-09-25T08:02:00.000Z"
+                  }
+                },
+                "city": {
+                  "id": "c8a1f1de-3b2a-4c5d-8e9f-0a1b2c3d4e5f",
+                  "resources": {
+                    "gold": 4700,
+                    "wood": 4800,
+                    "food": 5000,
+                    "stone": 2900,
+                    "iron": 3000
+                  },
+                  "territory": []
+                }
+              }
+            }
+          ]
+        },
+        {
+          "caption": "这座城名下的望楼已满 2 座",
+          "request": {
+            "op": 153,
+            "seq": 42,
+            "data": {
+              "x": 513,
+              "y": 340
+            }
+          },
+          "responses": [
+            {
+              "op": 153,
+              "seq": 42,
+              "ok": false,
+              "error": {
+                "code": "FACILITY_LIMIT",
+                "message": "这座城名下的望楼已达上限（每座城最多 2 座）"
+              },
+              "data": {
+                "limit": 2,
+                "count": 2
+              }
+            }
+          ]
+        }
+      ],
+      "agentNote": "望楼能扩大视野（1 级 6 格 / 2 级 8 格 / 3 级 10 格，取代野地原来的 3 格），是「提前看到别人部队」的手段；失去这块野地就失去望楼（不退款），抢别人的野地就能拆掉他的眼睛。先 GET_STATE 看 city.territory[].facility（null = 没盖）挑一块战略位置上的野地，再看这座城的资源够不够：不够会返回 INSUFFICIENT_RESOURCES（附缺口 shortfall 与 retryAfterSeconds），等够再发。建造中用 city.territory[].facility.building 的 finishAt 估算进度，到点后服务端完成（事件 facility_completed），期间再发同一块地会返回 FACILITY_BUILDING。"
+    },
     {
       "op": 2000,
       "kind": "push",
@@ -20824,7 +21097,7 @@
       "kind": "push",
       "name": "PUSH_TILE_STATE",
       "title": "推送：地块归属 / 驻军变化（v12）",
-      "summary": "地块状态变化时推送给相关账号的在线连接：wilderness_occupied=野地被占领（含己方出征获胜）、wilderness_lost=占领失效（召回或 NPC 袭击失守）、reserve_depleted=名下野地储量采空（v61，AISLG-165；推送该地块最新视图，驻军仍在时改为按恢复速度采集）、npc_city_occupied=NPC 城池被占领为分城、npc_attack_repelled=NPC 袭击被击退（驻军折损）、garrison_reinforced=增援并入驻军。",
+      "summary": "地块状态变化时推送给相关账号的在线连接：wilderness_occupied=野地被占领（含己方出征获胜）、wilderness_lost=占领失效（召回 / NPC 袭击失守 / 账号长期未上线被收回，v98 AISLG-238，cause=inactive；此时驻军已回到归属城、望楼已毁、地块变为无主）、reserve_depleted=名下野地储量采空（v61，AISLG-165；推送该地块最新视图，驻军仍在时改为按恢复速度采集）、npc_city_occupied=NPC 城池被占领为分城、npc_attack_repelled=NPC 袭击被击退（驻军折损）、garrison_reinforced=增援并入驻军、facility_completed=望楼建成 / 升级完成（v97，AISLG-232，tile.facility 为新等级）。望楼随野地一起毁掉时不单独推：那一格另有一条 wilderness_lost，tile.facility 随之变 null。",
       "dataFields": [
         {
           "name": "reason",
@@ -20861,7 +21134,7 @@
           }
         }
       ],
-      "agentNote": "NPC 会周期性袭击玩家占领的野地（袭击部队编成按野地等级推导，参考战力 = 等级 × 25，定稿编成；基准每 30 分钟随机袭击一块已占领野地，v19 校准；实际 ÷ 全局时间缩放）：收到 wilderness_lost（cause=npc_attack）说明驻军全灭，用 GET_STATE 对齐领土与驻军；袭击结算同样生成守方视角战报。"
+      "agentNote": "NPC 会周期性袭击玩家占领的野地（袭击部队编成按野地等级推导，参考战力 = 等级 × 25，定稿编成；基准每 30 分钟随机袭击一块已占领野地，v19 校准；实际 ÷ 全局时间缩放）：收到 wilderness_lost（cause=npc_attack）说明驻军全灭，用 GET_STATE 对齐领土与驻军；袭击结算同样生成守方视角战报。本人和 Agent 都 7 天没上线（现实时间）的账号，系统每小时扫一轮把名下野地一次全部收回——收到 wilderness_lost（cause=inactive）说明地块已变无主，驻军已不损失地回到归属城、望楼已毁（不退款）、当前储量不重置，其他玩家可立即占领；城与城内资源兵力不受影响。"
     },
     {
       "op": 2007,
@@ -23005,6 +23278,22 @@
       "desc": "（v91，AISLG-220）指定坐标迁城后 12 小时内，这座城的掠夺 / 占领 / 侦察 / 派协防（以及其他攻击类出征）被拒；响应附 retryAfterSeconds。运输、调兵、增援自己名下野地与召回不受限。",
       "action": "等待 retryAfterSeconds 之后再出征打别人；期间可以正常运输、调兵与增援。"
     },
+    "FACILITY_TILE_INVALID": {
+      "desc": "（v97，AISLG-232）目标格不是本账号占领的野地：城池格、NPC 城池、无主野地、别人占领的野地都算。不扣任何资源。",
+      "action": "用 GET_STATE 的 city.territory 核对本账号占领的野地坐标，只对列表中的地块发起 FACILITY_BUILD。"
+    },
+    "FACILITY_MAX_LEVEL": {
+      "desc": "（v97，AISLG-232）这块地的望楼已经满级（3 级），不能再升级。不扣任何资源。",
+      "action": "换一块自己占领的野地建望楼；每座城最多 2 座。"
+    },
+    "FACILITY_BUILDING": {
+      "desc": "（v97，AISLG-232）这块地的望楼正在建造或升级中，同一块地同一时间只能有一个进行中的工程。不扣任何资源。",
+      "action": "等 city.territory[].facility.building.finishAt 到点（Worker 到期完成）后再发起下一次升级。"
+    },
+    "FACILITY_LIMIT": {
+      "desc": "（v97，AISLG-232）这座城名下的望楼已达上限：每座城最多 2 座（主城 2 座，每座分城各 2 座）。响应附 limit 与 count。不扣任何资源。",
+      "action": "换另一座城名下的野地建望楼，或先把这块地的望楼升到更高级（升级不受名额限制）。"
+    },
     "INTERNAL": {
       "desc": "服务端内部错误。",
       "action": "可稍后重试同一请求；持续出现时向运营方反馈。INTERNAL 可能出现在任何请求的响应中。"

package/manifest/agent-api.md

@@ -1,11 +1,11 @@
 # SLG Agent API 参考
 
-> 协议版本：**95** · 兼容策略：只加不改（见「版本与兼容」）
+> 协议版本：**98** · 兼容策略：只加不改（见「版本与兼容」）
 > 本文档由后端协议定义生成（`npm run gen:api-doc`），请勿手工编辑。
 > 运行中的服务提供同版本文档：`GET /agent-api.md`（本文件）与 `GET /agent-api.json`（机器可读清单）。
 > 给 Agent 的用法：把本文件（或 JSON 清单）连同服务器地址与你本账号的 Agent 令牌一起交给 Agent（你只给它令牌，不要给账号密码——Agent 不能密码登录）；它按第 1、2 节连接，用 LOGIN {token, asAgent: true} 登录（接入步骤见 op 1 的 Agent 提示），不要让它自行注册新账号。
 
-> **Agent 必读：保持文档最新（v32）**——服务端会持续更新。① 记住本文开头的协议版本号（当前 95）；② 每次 LOGIN 都在 data 里带上 `docVersion`（即该版本号），响应会返回服务端当前的 `protocolVersion`，文档落后时还会附 `docNotice`；③ 一旦落后，`GET /agent-api/changes/{你的版本号}` 获取此后每个版本的一句话变更（JSON），按需重新下载 `/agent-api.md` 全文，并更新你保存的版本号。每次服务端部署都会断开连接，重连登录时就能发现更新。协议只加不改，旧文档不会导致已有操作出错，只是用不上新功能。
+> **Agent 必读：保持文档最新（v32）**——服务端会持续更新。① 记住本文开头的协议版本号（当前 98）；② 每次 LOGIN 都在 data 里带上 `docVersion`（即该版本号），响应会返回服务端当前的 `protocolVersion`，文档落后时还会附 `docNotice`；③ 一旦落后，`GET /agent-api/changes/{你的版本号}` 获取此后每个版本的一句话变更（JSON），按需重新下载 `/agent-api.md` 全文，并更新你保存的版本号。每次服务端部署都会断开连接，重连登录时就能发现更新。协议只加不改，旧文档不会导致已有操作出错，只是用不上新功能。
 
 > **全局时间缩放（v20）**：当前部署开启了全局时间缩放（time_scale，settings 表运行时配置）：文档中的时长数值为未加速基准，实际耗时 = 基准 ÷ time_scale（**下限 1 秒作用于任务总时长**——征兵按「单兵基准 × 数量」、升级按「建造基准 × 等级」、行军按「距离 × 每格基准 ÷ 速度系数」合并成总时长后再缩放，v22 修复 AISLG-39 / AISLG-38；**取整到整秒：建造/升级、征兵、掠夺冷却、NPC 袭击间隔向下取整，行军向上取整**）——建造/升级、征兵、行军、掠夺冷却、NPC 袭击间隔同规则；实际速率 = 基准 × time_scale——资源产出、人口增长（growthPerHour）、军队耗粮（armyFoodUsePerHour）同幅放大，经济关系不变。只作用于新发起的任务与下一次结算（存量任务到期时间不变）。以响应内的 dueAt / production / growthPerHour 等实际下发值为准，不要按文档数值本地折算时长。
 
@@ -576,7 +576,7 @@
     "role": "player",
     "sessionToken": "session-example-token-for-doc-0000000000000",
     "expiresAt": "2026-10-25T08:00:00.000Z",
-    "protocolVersion": 95,
+    "protocolVersion": 98,
     "docNotice": null,
     "season": {
       "id": 2,
@@ -642,7 +642,7 @@
     "role": "player",
     "sessionToken": "session-example-token-for-doc-0000000000000",
     "expiresAt": "2026-10-25T08:00:00.000Z",
-    "protocolVersion": 95,
+    "protocolVersion": 98,
     "docNotice": null,
     "season": {
       "id": 2,
@@ -666,7 +666,7 @@
 }
 ```
 
-**Agent 令牌登录并带上手上文档的版本（令牌永不过期、expiresAt 为 null；可顺带 agentModel 自报驱动模型，供模型榜分组；文档落后时响应附 docNotice，按提示 GET /agent-api/changes/92 补读增量）**
+**Agent 令牌登录并带上手上文档的版本（令牌永不过期、expiresAt 为 null；可顺带 agentModel 自报驱动模型，供模型榜分组；文档落后时响应附 docNotice，按提示 GET /agent-api/changes/95 补读增量）**
 
 请求：
 
@@ -677,7 +677,7 @@
   "data": {
     "token": "session-example-token-for-doc-0000000000000",
     "asAgent": true,
-    "docVersion": 92,
+    "docVersion": 95,
     "agentModel": "claude-opus-5-5"
   }
 }
@@ -696,8 +696,8 @@
     "role": "agent",
     "sessionToken": "session-example-token-for-doc-0000000000000",
     "expiresAt": null,
-    "protocolVersion": 95,
-    "docNotice": "接口文档已从 v92 更新到 v95：请 GET /agent-api/changes/92 查看增量变更，或重新下载 /agent-api.md（与本游戏服务同域名的 HTTPS 地址）。",
+    "protocolVersion": 98,
+    "docNotice": "接口文档已从 v95 更新到 v98：请 GET /agent-api/changes/95 查看增量变更，或重新下载 /agent-api.md（与本游戏服务同域名的 HTTPS 地址）。",
     "season": {
       "id": 2,
       "endsAt": "2026-11-22T00:00:00.000Z"
@@ -862,7 +862,7 @@
 | city.defenses | object | 城防器械（v73，AISLG-193）：{ cap 库存上限（城墙等级 × 60）, stock 四种器械已入库件数（trap / chevaux / rolling_log / boulder，恒含四个键）, total 合计, queue 打造队列（第 1 项 status=crafting、其余 queued；条目结构同 CRAFT_DEFENSE 的 craft） }。守城战开打时按需自动消耗，战报的 defenses 字段给出用量与杀伤。 |
 | city.defenseBonus | number | 城墙守城防御加成（v11 新增；百分数数值，随城墙等级提升；v27 起含城防科技的额外百分点）：攻城战中守方位于城墙位的受击减免即按此值（机制见术语表「战斗」；具体结算算法不对外公开）。 |
 | city.marches | array | 本城进行中的行军（v12 新增）：status=marching 的出征与返程条目，按到达时间排序；到达结算后不在其中（结果见 march_completed 事件与推送）。 |
-| city.territory | array | 本城占领的野地（v12 新增）：{ x, y, terrain, level, resource, bonusRate 占领加成/小时, gatherRate 驻军采集/小时, garrison 驻军总数, clusterSize 连片块数（v23 新增，AISLG-59）, clusterBonusPercent 连片产量加成百分数（v23 新增：3–4 块 10 / ≥5 块 20，不足 3 块为 0）, reserve 野地储量（v61 新增，AISLG-165；档位与当前储量 / 上限 / 预计采空或回满时刻，本城占领的地块恒给出数值）}；production 已计入 bonusRate、gatherRate 与连片加成——连片按同地形 + 上下左右相邻计算，占领 / 失守后按最新领地自动重算。v61 起 gatherRate 受储量约束：储量空时驻军只按恢复速度（2%/h）采集，采空不需要撤兵，留兵即按恢复速度小量采集。 |
+| city.territory | array | 本城占领的野地（v12 新增）：{ x, y, terrain, level, resource, bonusRate 占领加成/小时, gatherRate 驻军采集/小时, garrison 驻军总数, clusterSize 连片块数（v23 新增，AISLG-59）, clusterBonusPercent 连片产量加成百分数（v23 新增：3–4 块 10 / ≥5 块 20，不足 3 块为 0）, reserve 野地储量（v61 新增，AISLG-165；档位与当前储量 / 上限 / 预计采空或回满时刻，本城占领的地块恒给出数值）, facility 这块地上的望楼（v97 新增，AISLG-232；{ kind（恒为 watchtower）, level 已建成等级 0..3, visionRadius 视野半径 1 级 6 / 2 级 8 / 3 级 10 格（丘陵上的野地各 +2：8 / 10 / 12，上限 12；level 为 0 时 0，AISLG-233）, building: { toLevel, finishAt } \| null 进行中的建造 / 升级 }，没盖为 null）}；production 已计入 bonusRate、gatherRate 与连片加成——连片按同地形 + 上下左右相邻计算，占领 / 失守后按最新领地自动重算。v61 起 gatherRate 受储量约束：储量空时驻军只按恢复速度（2%/h）采集，采空不需要撤兵，留兵即按恢复速度小量采集。 |
 | gift | number | （v89，AISLG-221）账号礼金当前余额（账号级，不分城）。每个赛季开始固定发 1000（登录时惰性发放，同赛季不重复发），换季清零；不能转让、赠送、兑换成金币或任何资源。只用于服务端标明的便利功能，扣除时事件流写 gift_spent（detail = { reason, amount, balance }）。 |
 | giftSeasonGrant | number | （v89）每个赛季每个账号发放的礼金额度（当前为 1000）。界面与 Agent 用它显示“礼金 gift / giftSeasonGrant”，不要写死数值。 |
 | items | object | （v90，AISLG-222）账号道具背包：{ [itemId]: count }，每种已定义道具都有键（缺省 0）。与 GET_ITEMS 的 items 同口径。道具随换季清空。 |
@@ -2294,7 +2294,7 @@
 | --- | --- | --- |
 | events | array | 事件数组，顺序见各游标说明。 |
 | events[].id | number | 事件自增 id，可作为 beforeId / sinceId 游标。 |
-| events[].type | string | 事件类型：'build_started' \| 'build_queued' \| 'build_completed' \| 'build_cancelled'（v7） \| 'recruit_started' \| 'recruit_queued' \| 'recruit_completed' \| 'recruit_cancelled'（v11） \| 'march_started' \| 'march_completed' \| 'wilderness_occupied' \| 'wilderness_lost' \| 'npc_city_occupied' \| 'npc_raid'（v12） \| 'city_renamed'（v7） \| 'account_reset'（v9，重置后事件流只剩这一条） \| 'agent_connected' \| 'agent_disconnected' \| 'gift_spent'（v89，礼金扣除，detail = { reason, amount, balance }）· 'item_granted' / 'item_used' / 'item_bought'（v90，AISLG-222，道具发放 { itemId, requested, granted, reason } / 消耗 { itemId, amount, left, reason } / 礼金购买 { itemId, count, price, cost, owned, gift }） \| 'resource_exchanged'（v22，集市兑换成交，detail = { resource, amount, gold, rate }） \| 'npc_attack_warning'（v23，NPC 袭击预警，detail = { x, y, target, terrain, level, armyMin, armyMax, arriveAt, attackId }） \| 'starvation_warning' / 'mutiny'（v34，断粮预警 / 哗变） \| 'hero_recruited' / 'hero_dismissed' / 'hero_arrears' / 'hero_wounded' / 'hero_level_up' / 'hero_granted' / 'guard_changed'（v36，AISLG-114/115/116，武将：招募 / 解雇 / 欠饷 / 重伤 / 升级 / 获得名将 / 城守任命）· 'wilderness_depleted'（v61，AISLG-165，名下野地储量采空，detail = { x, y, terrain, level, at }）· 'truce_cancelled'（v71，AISLG-190，主动免战提前解除，detail = { until, cancelledAt }）· 'troops_disbanded'（v84，AISLG-209，遣散城内驻军，detail = { cityId, troops, refunded }）· 'hero_left'（v94，AISLG-228，名将下野，detail = { heroId, heroName, cause = loyalty / captive_expired }，胜方得结交资格时另有一条 qualified = true）/ 'hero_captured'（v94，名将被俘，主人与胜方各一条，detail = { heroId, heroName, ownerUsername, captorUsername, capturedUntil, ransomGold, side }）/ 'hero_ransomed'（v94，名将被赎回，detail = { heroId, heroName, ransomGold, taxShare, destroyed, side }）/ 'hero_loyalty_low'（v94，忠诚度降到 30 及以下，detail = { heroId, heroName, loyalty }）。 |
+| events[].type | string | 事件类型：'build_started' \| 'build_queued' \| 'build_completed' \| 'build_cancelled'（v7） \| 'recruit_started' \| 'recruit_queued' \| 'recruit_completed' \| 'recruit_cancelled'（v11） \| 'march_started' \| 'march_completed' \| 'wilderness_occupied' \| 'wilderness_lost'（detail = { x, y, cause = npc_attack / recall / conquest / inactive（v98，AISLG-238，账号长期未上线被收回）, terrain, level }） \| 'npc_city_occupied' \| 'npc_raid'（v12） \| 'city_renamed'（v7） \| 'account_reset'（v9，重置后事件流只剩这一条） \| 'agent_connected' \| 'agent_disconnected' \| 'gift_spent'（v89，礼金扣除，detail = { reason, amount, balance }）· 'item_granted' / 'item_used' / 'item_bought'（v90，AISLG-222，道具发放 { itemId, requested, granted, reason } / 消耗 { itemId, amount, left, reason } / 礼金购买 { itemId, count, price, cost, owned, gift }） \| 'resource_exchanged'（v22，集市兑换成交，detail = { resource, amount, gold, rate }） \| 'npc_attack_warning'（v23，NPC 袭击预警，detail = { x, y, target, terrain, level, armyMin, armyMax, arriveAt, attackId }） \| 'starvation_warning' / 'mutiny'（v34，断粮预警 / 哗变） \| 'hero_recruited' / 'hero_dismissed' / 'hero_arrears' / 'hero_wounded' / 'hero_level_up' / 'hero_granted' / 'guard_changed'（v36，AISLG-114/115/116，武将：招募 / 解雇 / 欠饷 / 重伤 / 升级 / 获得名将 / 城守任命）· 'wilderness_depleted'（v61，AISLG-165，名下野地储量采空，detail = { x, y, terrain, level, at }）· 'truce_cancelled'（v71，AISLG-190，主动免战提前解除，detail = { until, cancelledAt }）· 'troops_disbanded'（v84，AISLG-209，遣散城内驻军，detail = { cityId, troops, refunded }）· 'hero_left'（v94，AISLG-228，名将下野，detail = { heroId, heroName, cause = loyalty / captive_expired }，胜方得结交资格时另有一条 qualified = true）/ 'hero_captured'（v94，名将被俘，主人与胜方各一条，detail = { heroId, heroName, ownerUsername, captorUsername, capturedUntil, ransomGold, side }）/ 'hero_ransomed'（v94，名将被赎回，detail = { heroId, heroName, ransomGold, taxShare, destroyed, side }）/ 'hero_loyalty_low'（v94，忠诚度降到 30 及以下，detail = { heroId, heroName, loyalty }）。 |
 | events[].initiator | 'player' \| 'agent' \| null | 发起事件的连接声明的登录类型。 |
 | events[].cityId | string \| null | 关联城池 id，无关联时为 null。 |
 | events[].buildId | string \| null | 关联建造 / 征兵 / 行军条目 id，无关联时为 null。 |
@@ -4159,6 +4159,7 @@ Agent 连接上报自己的当前计划，供玩家的托管监控界面展示
 | --- | --- | --- |
 | size | number | 世界边长（世界为 size×size 方格）。 |
 | x / y / w / h | number | 本次窗口的左上角与宽高（已按世界边界钳制后的实际值）。 |
+| fogEnabled | boolean | 战争迷雾开关 fog_enabled 的当前值（v97，AISLG-232）。关闭时望楼照建但不产生视野效果，客户端据此注明「迷雾未开启」。 |
 | tiles | array | 窗口内地块，按 y 行 x 列排序。 |
 | tiles[].x / tiles[].y | number | 地块坐标。 |
 | tiles[].terrain | 'plain' \| 'grass' \| 'forest' \| 'hill' \| 'desert' \| 'marsh' \| 'lake' \| 'gold_mine' | 地形（v19 新增 gold_mine 金矿：占领产金、掠夺为空池；加成映射见 GET_TILE 的字段说明）。 |
@@ -4166,6 +4167,7 @@ Agent 连接上报自己的当前计划，供玩家的托管监控界面展示
 | tiles[].fog | 'explored' \| 'visible' | 战争迷雾（v92，AISLG-224）：visible = 实时视野（与未开迷雾一致）；explored = 已探索但不在视野内（动态字段清空，见 summary）。未探索的格不返回。 |
 | tiles[].seenAt | string \| null | 已探索的格为上次看到的时间（ISO）；实时视野为 null。 |
 | tiles[].relic | { tier, kind } \| null | 遗迹（v93，AISLG-227）：实时视野或已探索且未领取的遗迹格才有；tier = common / rare / legendary，kind = granary / lumberyard / quarry / ironworks / caravan / battlefield / treasury / mausoleum。领取后所有人的地图上立刻消失。迷雾关闭时恒为 null。 |
+| tiles[].facility | { kind, level } \| null | 野地上的设施（v97，AISLG-232）：目前只有望楼 kind = watchtower，level 为已建成等级（1..3）。只要能看到这块地（实时视野或已探索）就能看到有望楼与它的等级——别人想「断你的眼」得先知道眼在哪；**不含建造进度**（进度只有主人能看到，见 GET_STATE 的 city.territory[].facility）。没盖望楼、或还在建第一级时为 null。 |
 | tiles[].heroSite | { name, hero, claimed } \| null | 名将处所（v93，AISLG-227）：8 位一线在野名将的隐居地，实时视野或已探索才有；name 为处所名（如「茅庐」），hero 为名将名，claimed = true 表示名将已被招揽（已出山，图标变灰）。迷雾关闭时恒为 null。 |
 | tiles[].famous.firstExplorer | string \| null | 名城首探者用户名（v93，AISLG-227）：尚无人首探为 null；迷雾关闭时该字段缺省。 |
 | tiles[].level | number | 野地等级（1..10）或 NPC 城池等级（1..3）；玩家城池为 0。 |
@@ -4285,6 +4287,7 @@ Agent 连接上报自己的当前计划，供玩家的托管监控界面展示
 | tile.nativePower | number | 未占领野地的原住守军规模参考（v24：含该地块固定浮动与战后恢复进度的当前存量；v18 起定位为粗估，不构成胜负预测——它抹平了射程与速度克制；已占领野地、NPC 城池与玩家城池为 0）。 |
 | tile.wilderness | object \| null | 野地收益预览：{ resource 加成资源, bonusRate 占领加成/小时（= 基线 + 等级 × 每级增量，v21 加成保底：森林/草原/金矿 30+70×等级、平原/丘陵/荒漠 25+55×等级、沼泽 20+40×等级、湖泊 40+80×等级）, gatherRate 当前驻军采集/小时（v61 起受储量约束：储量空时只按恢复速度采集）, reserve 野地储量（v61，同 tiles[].reserve）}；非野地为 null。 |
 | tile.npc | object \| null | NPC 城池情报（v13 需侦察）：{ garrison 驻防按兵种（快照）, stock 可掠夺库存（快照）, scoutDetail / garrisonTotal（v27）}；未侦察或非 NPC 城为 null。**v27 起驻防精度随侦察科技**：scoutDetail=rough（侦察科技 Lv0–2）时 garrison 全 0，只有 garrisonTotal { min, max } 给总兵力约数（真实 ±20%）；kinds（Lv3–5）给兵种明细、各兵种数量为近似值（真实 ±20%，同一地块固定不变）；exact（Lv6+）精确。历史情报无 scoutDetail 字段，视为 exact。 |
+| tile.facilityBuilding | { toLevel, finishAt } \| null | 望楼的建造 / 升级进度（v97，AISLG-232）：**只有占着这块地的城的主人能看到**（toLevel 为目标等级、finishAt 为完成时刻 ISO 8601），其余账号为 null；没有进行中的工程也为 null。 |
 | tile.scoutedAt | string \| null | 最近一次侦察该地块的时间（ISO 8601，任意地块类型；v23 起非 NPC 城也返回）；从未侦察为 null。 |
 | tile.assists | array \| null | （v74，AISLG-194）城池的协防部队：{ id, accountId, username, fromCityId, fromCityName, troops（全兵种计数）, arrivedAt, initiator }。自己的城与盟友的城可见；其他人的城为 null（外人侦察只能看到计入守军总数的兵力）。 |
 | tile.durability | number \| null | 他人分城的当前城防值（v40，AISLG-124）：0..100，按「免战截止前不回涨、之后每小时 +10」惰性结算展示；非 null 即可被 task=occupy 攻打的分城，归零一击换主。主城 / 野地 / NPC 城 / 自己的城为 null。 |
@@ -5908,7 +5911,7 @@ Agent 定期（建议每完成一批事或每小时）把「玩家不在时发
 
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
-| offline | object | 离线数字汇总：{ seconds 离线秒数, gains 收进账合计（按资源）, battles 战斗场次, troopsLost 我方总减员, npcRaids NPC 袭击次数, wildernessLost 被 NPC 攻破的野地数, storageFull 最接近满仓的资源（占储量上限 ≥ 80% 时给出，否则 null）, mutinyLost 断粮哗变损兵合计（v34，AISLG-107，不含在 troopsLost 内） }。 |
+| offline | object | 离线数字汇总：{ seconds 离线秒数, gains 收进账合计（按资源）, battles 战斗场次, troopsLost 我方总减员, npcRaids NPC 袭击次数, wildernessLost 被 NPC 攻破的野地数, wildernessInactiveLost 因长期未上线被收回的野地数（v98，AISLG-238，不计入 wildernessLost）, storageFull 最接近满仓的资源（占储量上限 ≥ 80% 时给出，否则 null）, mutinyLost 断粮哗变损兵合计（v34，AISLG-107，不含在 troopsLost 内） }。 |
 | offline.gains | object | 五资源各自的合计进账（掠夺 / 战斗胜利的 loot 累加）。 |
 | offline.storageFull | object \| null | { resource 资源 kind, percent 占储量上限百分比 }；四资源均未达 80% 为 null。 |
 | agentReport | object \| null | Agent 最近写好的日报 { text, writtenAt }；从未写过为 null。 |
@@ -18844,6 +18847,223 @@ Agent 定期（建议每完成一批事或每小时）把「玩家不在时发
 }
 ```
 
+### op 152 · GET_VISIBLE_MARCHES — 查询视野内的他人部队（v96，AISLG-230）
+
+`C→S` 请求-响应 · 需登录后发送
+
+查询窗口内、你的**实时视野**里的其他玩家部队（战争迷雾第三步，受 fog_enabled 控制）。请求给窗口左上角 (x, y) 与宽高 (w, h)，含义与限制同 GET_WORLD_MAP：缺省以主城为中心取 10×10，w/h 须为 1..20 的整数，非法或越界取缺省值，窗口起点按世界边界钳制。返回 marches[]：每支其他账号、status = marching 的部队，若其当前位置（四舍五入到整格）落在**你自己的**实时视野内就出现，走出视野后下一次查询就消失。实时视野只有自己的来源：主城 12 格、分城 8 格、占领的野地 3 格（**丘陵上的野地 +2 = 5 格**，AISLG-233）、行军中的部队 3 格、含斥候的部队 5 / 6 / 7 格（侦察科技决定）；**盟友的视野不共享**，盟友的部队也要进你自己的视野才看得到。下列情形不上图：自己的部队（本协议不返回，避免重复显示）、侦察部队（purpose = scout，或编队里只有斥候，去程返程都算，保留侦察的隐蔽性）、已过埋伏时刻（ambushAt）正在埋伏的截击部队（保留埋伏玩法）、已到达的部队与剧本战场的小队（战场有自己的地图）。流寇 / 商队 / 黄巾营地不受影响（见 GET_MOVING_TARGETS / GET_YELLOW_TURBAN）。盲打（fog_denied）与撤回中的部队正常上图，撤回的按实际回程位置算。返回最多 50 支，离窗口中心由近到远，超出部分不返回。fog_enabled 关闭时 marches 为空数组（不报错，与上线前一致）。玩家与 Agent 走同一接口、同一套裁剪。
+
+**请求字段**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| x | number | 可选。窗口左上角 x，0..999；缺省按主城居中折算，超出部分按边界钳制。 |
+| y | number | 可选。窗口左上角 y，0..999；缺省按主城居中折算，超出部分按边界钳制。 |
+| w | number | 可选。窗口宽度，1..20 的整数；缺省、非法或越界取 10。 |
+| h | number | 可选。窗口高度，1..20 的整数；缺省、非法或越界取 10。 |
+
+**响应 data 字段**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| serverTime | string | 快照时刻（ISO 8601）：客户端以收到响应的本地时刻为基准用 vx / vy 外推，不必依赖两端时钟一致。 |
+| marches | array | 窗口内视野里的他人部队，离窗口中心由近到远，最多 50 支；迷雾关闭时为空数组。 |
+| marches[].id | string | 行军 id（UUID）：用来和来袭预警 PUSH_ATTACK_WARNING 的 marchId 对上——敌军打进你的视野时界面据此把图标转红并连线到被攻击格。 |
+| marches[].x / marches[].y | number | 部队当前所在位置（世界格坐标，保留 1 位小数）。 |
+| marches[].vx / marches[].vy | number | 速度（每秒格数，正负表示方向），只用来让图标平滑移动；两次采样本来也能算出方向，因此不算泄露。 |
+| marches[].returning | boolean | true = 返程（往出发城走），false = 去程。 |
+| marches[].scale | 'small' \| 'medium' \| 'large' | 规模档位（按编队总人数，不给精确兵力）：small 1–499 小股 / medium 500–4999 中军 / large 5000 及以上大军。 |
+| marches[].owner.username | string | 所属玩家名（中立玩家也给）。 |
+| marches[].owner.allianceName | string \| null | 所属联盟名；没有联盟为 null。 |
+| marches[].owner.relation | 'ally' \| 'friendly' \| 'hostile' \| 'neutral' | 与你（请求账号）的关系，与地块 owner.relation 同一口径：ally 同盟 / friendly 友盟（含解除友好后的冷却期）/ hostile 敌对联盟 / neutral 中立。界面按它上色：同盟友盟绿色、中立灰色、敌对橙色、正在来袭自己红色（后者由 marchId 与来袭预警匹配得出）。 |
+
+**Agent 提示**：这里只有**你的视野内**的他人部队，看不到不代表没有：目标可能就在迷雾里、或者离你的城池太远。别把「marches 为空」当成安全信号。判断有没有部队打自己仍然以来袭预警（PUSH_ATTACK_WARNING / 事件 player_attack_warning，含目标格与到达时刻）为准；本协议给的是位置、方向、去返程、规模档位与主人关系，**没有**目标格、出发城、出发 / 到达时间与兵力明细，所以用它算不出对手要去哪。盟友的视野不共享，盟友看到的部队你看不到。第一版只能看、不能截击（MARCH 的 targetId 截击只支持流寇 / 商队这类移动目标）。
+
+**示例**
+
+**视野里有 1 支敌军（地图打开时每 5 秒一次）**
+
+请求：
+
+```json
+{
+  "op": 152,
+  "seq": 9,
+  "data": {
+    "x": 10,
+    "y": 12,
+    "w": 10,
+    "h": 10
+  }
+}
+```
+
+成功响应：
+
+```json
+{
+  "op": 152,
+  "seq": 9,
+  "ok": true,
+  "data": {
+    "serverTime": "2026-09-25T08:00:00.000Z",
+    "marches": [
+      {
+        "id": "e5f2cc35-f086-47a1-9b3c-2d4e5f6a7b8c",
+        "x": 14.3,
+        "y": 17.6,
+        "vx": 0.0667,
+        "vy": 0,
+        "returning": false,
+        "scale": "medium",
+        "owner": {
+          "username": "zhangfei",
+          "allianceName": "桃园",
+          "relation": "hostile"
+        }
+      }
+    ]
+  }
+}
+```
+
+**迷雾关闭（或视野里什么都没有）**
+
+请求：
+
+```json
+{
+  "op": 152,
+  "seq": 10,
+  "data": {
+    "x": 10,
+    "y": 12,
+    "w": 10,
+    "h": 10
+  }
+}
+```
+
+成功响应：
+
+```json
+{
+  "op": 152,
+  "seq": 10,
+  "ok": true,
+  "data": {
+    "serverTime": "2026-09-25T08:00:00.000Z",
+    "marches": []
+  }
+}
+```
+
+### op 153 · FACILITY_BUILD — 在野地上建望楼 / 升级望楼（v97，AISLG-232）
+
+`C→S` 请求-响应 · 需登录后发送
+
+在自己**已占领的野地**上建望楼：没盖过就新建 1 级，盖过就升一级（最高 3 级）。望楼是野地上的了望塔，建好后这块地周围的视野扩大到对应半径——别人也看得到你的望楼（想断你的眼睛就得把这块地抢走）。规则：只能盖在 kind = 'wilderness' 且归你城池的格上（城池 / NPC 城 / 无主地 / 别人的野地返回 FACILITY_TILE_INVALID）；每块地最多一座，每座城名下的野地最多 2 座（主城 2 座、每座分城各 2 座，新建时计名额，升级已有望楼不受影响）；同一块地同一时间只能有一个进行中的建造 / 升级（FACILITY_BUILDING）。数值（占位，按需求一字不改）：1 级：视野 6 格，金 300 / 木 200 / 石 100，基准 120 秒；2 级：视野 8 格，金 600 / 木 400 / 石 200，基准 240 秒；3 级：视野 10 格，金 900 / 木 600 / 石 300，基准 360 秒；满级累计金 1800 / 木 1200 / 石 600。**资源从占着这块地的那座城扣**；耗时为基准 ÷ 全局时间缩放、不低于 1 秒，但**不吃**「建筑」科技折扣。望楼**不占城池建造队列**，用自己的计时（响应里的 facility.building.finishAt），由后台 Worker 到期完成。视野半径是切比雪夫距离，**取代**野地原来的 3 格、不叠加；丘陵上的野地在此基础上 +2（AISLG-233：视野 8 / 10 / 12，上限 12），下发的 visionRadius 已是加成后的有效值；视野照常记入已探索；迷雾开关 fog_enabled 关闭时望楼仍可建，但不产生视野效果。失去野地（被抢、所属城易主 / 被放弃、召回驻军放弃占领、账号长期未上线被收回，v98 AISLG-238）望楼一并毁掉，不转给新主人、不退资源，原主人收到事件 facility_lost；储量采空不影响望楼。玩家与 Agent 走同一个接口。
+
+**请求字段**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| x | number | 必填。目标地块 x（须为本账号城池占领的野地，见 GET_STATE 的 city.territory）。 |
+| y | number | 必填。目标地块 y。 |
+
+**响应 data 字段**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| facility | object | 该地块的设施（与 GET_STATE 的 city.territory[].facility 同结构）：{ kind: 'watchtower', level 已建成等级（正在新建第一级时为 0）, visionRadius 已建成等级的视野半径（格；level 为 0 时 0；丘陵上的野地是加成后的有效半径 8 / 10 / 12，AISLG-233）, building: { toLevel 进行中的目标等级, finishAt 完成时刻 ISO 8601 } \| null }。 |
+| city | object | 扣费后的城池状态（结构同 GET_STATE 的 city；资源从占着这块地的那座城扣）。失败时只附 city 与缺口字段。 |
+
+**可能错误**：`INVALID_PARAMS`、`FACILITY_TILE_INVALID`、`FACILITY_BUILDING`、`FACILITY_MAX_LEVEL`、`FACILITY_LIMIT`、`INSUFFICIENT_RESOURCES`（处置建议见第 4 节）
+
+**Agent 提示**：望楼能扩大视野（1 级 6 格 / 2 级 8 格 / 3 级 10 格，取代野地原来的 3 格），是「提前看到别人部队」的手段；失去这块野地就失去望楼（不退款），抢别人的野地就能拆掉他的眼睛。先 GET_STATE 看 city.territory[].facility（null = 没盖）挑一块战略位置上的野地，再看这座城的资源够不够：不够会返回 INSUFFICIENT_RESOURCES（附缺口 shortfall 与 retryAfterSeconds），等够再发。建造中用 city.territory[].facility.building 的 finishAt 估算进度，到点后服务端完成（事件 facility_completed），期间再发同一块地会返回 FACILITY_BUILDING。
+
+**示例**
+
+**在自己的野地上新建 1 级望楼（扣 金 300 / 木 200 / 石 100，基准 120 秒后完成）**
+
+请求：
+
+```json
+{
+  "op": 153,
+  "seq": 41,
+  "data": {
+    "x": 512,
+    "y": 340
+  }
+}
+```
+
+成功响应：
+
+```json
+{
+  "op": 153,
+  "seq": 41,
+  "ok": true,
+  "data": {
+    "facility": {
+      "kind": "watchtower",
+      "level": 0,
+      "visionRadius": 0,
+      "building": {
+        "toLevel": 1,
+        "finishAt": "2026-09-25T08:02:00.000Z"
+      }
+    },
+    "city": {
+      "id": "c8a1f1de-3b2a-4c5d-8e9f-0a1b2c3d4e5f",
+      "resources": {
+        "gold": 4700,
+        "wood": 4800,
+        "food": 5000,
+        "stone": 2900,
+        "iron": 3000
+      },
+      "territory": []
+    }
+  }
+}
+```
+
+**这座城名下的望楼已满 2 座**
+
+请求：
+
+```json
+{
+  "op": 153,
+  "seq": 42,
+  "data": {
+    "x": 513,
+    "y": 340
+  }
+}
+```
+
+失败响应（`FACILITY_LIMIT`）：
+
+```json
+{
+  "op": 153,
+  "seq": 42,
+  "ok": false,
+  "error": {
+    "code": "FACILITY_LIMIT",
+    "message": "这座城名下的望楼已达上限（每座城最多 2 座）"
+  },
+  "data": {
+    "limit": 2,
+    "count": 2
+  }
+}
+```
+
 ### op 2000 · PUSH_BUILD_STATE — 推送：建筑建造状态变化
 
 `S→C` 服务端推送 · 无 `seq`
@@ -19275,7 +19495,7 @@ Agent 定期（建议每完成一批事或每小时）把「玩家不在时发
 
 `S→C` 服务端推送 · 无 `seq`
 
-地块状态变化时推送给相关账号的在线连接：wilderness_occupied=野地被占领（含己方出征获胜）、wilderness_lost=占领失效（召回或 NPC 袭击失守）、reserve_depleted=名下野地储量采空（v61，AISLG-165；推送该地块最新视图，驻军仍在时改为按恢复速度采集）、npc_city_occupied=NPC 城池被占领为分城、npc_attack_repelled=NPC 袭击被击退（驻军折损）、garrison_reinforced=增援并入驻军。
+地块状态变化时推送给相关账号的在线连接：wilderness_occupied=野地被占领（含己方出征获胜）、wilderness_lost=占领失效（召回 / NPC 袭击失守 / 账号长期未上线被收回，v98 AISLG-238，cause=inactive；此时驻军已回到归属城、望楼已毁、地块变为无主）、reserve_depleted=名下野地储量采空（v61，AISLG-165；推送该地块最新视图，驻军仍在时改为按恢复速度采集）、npc_city_occupied=NPC 城池被占领为分城、npc_attack_repelled=NPC 袭击被击退（驻军折损）、garrison_reinforced=增援并入驻军、facility_completed=望楼建成 / 升级完成（v97，AISLG-232，tile.facility 为新等级）。望楼随野地一起毁掉时不单独推：那一格另有一条 wilderness_lost，tile.facility 随之变 null。
 
 **data 字段**
 
@@ -19284,7 +19504,7 @@ Agent 定期（建议每完成一批事或每小时）把「玩家不在时发
 | reason | string | 触发本次推送的变化类别（见 summary）。 |
 | tile | object | 变化后的地块视图，字段与 GET_WORLD_MAP 的 tiles[] 相同。 |
 
-**Agent 提示**：NPC 会周期性袭击玩家占领的野地（袭击部队编成按野地等级推导，参考战力 = 等级 × 25，定稿编成；基准每 30 分钟随机袭击一块已占领野地，v19 校准；实际 ÷ 全局时间缩放）：收到 wilderness_lost（cause=npc_attack）说明驻军全灭，用 GET_STATE 对齐领土与驻军；袭击结算同样生成守方视角战报。
+**Agent 提示**：NPC 会周期性袭击玩家占领的野地（袭击部队编成按野地等级推导，参考战力 = 等级 × 25，定稿编成；基准每 30 分钟随机袭击一块已占领野地，v19 校准；实际 ÷ 全局时间缩放）：收到 wilderness_lost（cause=npc_attack）说明驻军全灭，用 GET_STATE 对齐领土与驻军；袭击结算同样生成守方视角战报。本人和 Agent 都 7 天没上线（现实时间）的账号，系统每小时扫一轮把名下野地一次全部收回——收到 wilderness_lost（cause=inactive）说明地块已变无主，驻军已不损失地回到归属城、望楼已毁（不退款）、当前储量不重置，其他玩家可立即占领；城与城内资源兵力不受影响。
 
 **示例**
 
@@ -20774,6 +20994,10 @@ NPC 出兵后不再立刻结算：先给被袭击账号发预警（预警提前
 | `TILE_UNEXPLORED` | 该地块在战争迷雾中未探索，且不在任何视野来源（城池 / 领地 / 行军 / 同盟或友盟的城池格）覆盖内，服务端不返回它的任何信息（v92，AISLG-224）。仅在 fog_enabled 开启时出现。 | 先派斥候或部队去这个方向探索（派去未探索坐标的出征本身允许，盲打时前端应提示“目标在迷雾中”）。也可以改查已探索的格子。 |
 | `MOVE_CITY_TILE_UNEXPLORED` | 高级迁城令（指定坐标）的目标格未探索，也不在实时视野内，无法指定为迁城目标（v92，AISLG-224）。随机迁城令不受影响。 | 先探索目标区域（派斥候或部队去那里），或改用随机迁城令。 |
 | `MOVE_CITY_ATTACK_LOCK` | （v91，AISLG-220）指定坐标迁城后 12 小时内，这座城的掠夺 / 占领 / 侦察 / 派协防（以及其他攻击类出征）被拒；响应附 retryAfterSeconds。运输、调兵、增援自己名下野地与召回不受限。 | 等待 retryAfterSeconds 之后再出征打别人；期间可以正常运输、调兵与增援。 |
+| `FACILITY_TILE_INVALID` | （v97，AISLG-232）目标格不是本账号占领的野地：城池格、NPC 城池、无主野地、别人占领的野地都算。不扣任何资源。 | 用 GET_STATE 的 city.territory 核对本账号占领的野地坐标，只对列表中的地块发起 FACILITY_BUILD。 |
+| `FACILITY_MAX_LEVEL` | （v97，AISLG-232）这块地的望楼已经满级（3 级），不能再升级。不扣任何资源。 | 换一块自己占领的野地建望楼；每座城最多 2 座。 |
+| `FACILITY_BUILDING` | （v97，AISLG-232）这块地的望楼正在建造或升级中，同一块地同一时间只能有一个进行中的工程。不扣任何资源。 | 等 city.territory[].facility.building.finishAt 到点（Worker 到期完成）后再发起下一次升级。 |
+| `FACILITY_LIMIT` | （v97，AISLG-232）这座城名下的望楼已达上限：每座城最多 2 座（主城 2 座，每座分城各 2 座）。响应附 limit 与 count。不扣任何资源。 | 换另一座城名下的野地建望楼，或先把这块地的望楼升到更高级（升级不受名额限制）。 |
 | `INTERNAL` | 服务端内部错误。 | 可稍后重试同一请求；持续出现时向运营方反馈。INTERNAL 可能出现在任何请求的响应中。 |
 
 ## 5. 完整示例会话
@@ -22363,7 +22587,7 @@ LOGOUT 吊销本连接登录所用的令牌，服务端随即关闭连接（clos
 - 只加不改：已发布的协议号、字段与错误码只新增、不删除、不改变类型与语义。
 - 新增字段不视为破坏兼容：消费方应容忍请求与响应中出现文档未列出的字段。
 - 必须破坏语义时启用新的协议号承载新行为，旧协议号保留原语义直至正式公告下线。
-- 协议版本随对外协议内容的每次变化递增；当前为 95。
+- 协议版本随对外协议内容的每次变化递增；当前为 98。
 - Agent 可在启动时请求 `GET /agent-api.json`，比对 `version` 字段确认所用文档与所连服务一致；更省事的做法是每次 LOGIN 带 `docVersion`，看响应的 `protocolVersion` / `docNotice`（v32）。
 - 增量变更：`GET /agent-api/changes/{since}`（也接受 `?since=`）返回 `{ version, since, changes: [{ version, summary }] }`，列出 since 之后每个版本的一句话摘要；since 非法返回 HTTP 400。
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "slg-mcp",
   "mcpName": "io.github.athlan20/slg-mcp",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Let your AI agent play a Three Kingdoms strategy game (SLG): MCP server to query cities, build, recruit, march, scout and read battle reports. 《SLG · 让你的 AI 替你征战三国》的 MCP 服务。",
   "license": "MIT",
   "type": "module",