slg-mcp 0.2.2 → 0.2.3

package/manifest/agent-api.json

@@ -1,5 +1,5 @@
 {
-  "version": 92,
+  "version": 95,
   "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": 92,
+                "protocolVersion": 95,
                 "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": 92,
+                "protocolVersion": 95,
                 "docNotice": null,
                 "season": {
                   "id": 2,
@@ -942,14 +942,14 @@
           ]
         },
         {
-          "caption": "Agent 令牌登录并带上手上文档的版本（令牌永不过期、expiresAt 为 null；可顺带 agentModel 自报驱动模型，供模型榜分组；文档落后时响应附 docNotice，按提示 GET /agent-api/changes/89 补读增量）",
+          "caption": "Agent 令牌登录并带上手上文档的版本（令牌永不过期、expiresAt 为 null；可顺带 agentModel 自报驱动模型，供模型榜分组；文档落后时响应附 docNotice，按提示 GET /agent-api/changes/92 补读增量）",
           "request": {
             "op": 1,
             "seq": 1,
             "data": {
               "token": "session-example-token-for-doc-0000000000000",
               "asAgent": true,
-              "docVersion": 89,
+              "docVersion": 92,
               "agentModel": "claude-opus-5-5"
             }
           },
@@ -964,8 +964,8 @@
                 "role": "agent",
                 "sessionToken": "session-example-token-for-doc-0000000000000",
                 "expiresAt": null,
-                "protocolVersion": 92,
-                "docNotice": "接口文档已从 v89 更新到 v92：请 GET /agent-api/changes/89 查看增量变更，或重新下载 /agent-api.md（与本游戏服务同域名的 HTTPS 地址）。",
+                "protocolVersion": 95,
+                "docNotice": "接口文档已从 v92 更新到 v95：请 GET /agent-api/changes/92 查看增量变更，或重新下载 /agent-api.md（与本游戏服务同域名的 HTTPS 地址）。",
                 "season": {
                   "id": 2,
                   "endsAt": "2026-11-22T00:00:00.000Z"
@@ -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 }）。"
+          "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 }）。"
         },
         {
           "name": "events[].initiator",
@@ -4721,6 +4721,21 @@
           "type": "string | null",
           "desc": "已探索的格为上次看到的时间（ISO）；实时视野为 null。"
         },
+        {
+          "name": "tiles[].relic",
+          "type": "{ tier, kind } | null",
+          "desc": "遗迹（v93，AISLG-227）：实时视野或已探索且未领取的遗迹格才有；tier = common / rare / legendary，kind = granary / lumberyard / quarry / ironworks / caravan / battlefield / treasury / mausoleum。领取后所有人的地图上立刻消失。迷雾关闭时恒为 null。"
+        },
+        {
+          "name": "tiles[].heroSite",
+          "type": "{ name, hero, claimed } | null",
+          "desc": "名将处所（v93，AISLG-227）：8 位一线在野名将的隐居地，实时视野或已探索才有；name 为处所名（如「茅庐」），hero 为名将名，claimed = true 表示名将已被招揽（已出山，图标变灰）。迷雾关闭时恒为 null。"
+        },
+        {
+          "name": "tiles[].famous.firstExplorer",
+          "type": "string | null",
+          "desc": "名城首探者用户名（v93，AISLG-227）：尚无人首探为 null；迷雾关闭时该字段缺省。"
+        },
         {
           "name": "tiles[].level",
           "type": "number",
@@ -4729,7 +4744,7 @@
         {
           "name": "tiles[].owner",
           "type": "object | null",
-          "desc": "占领者（占领野地或城池地块归属的城池）：{ accountId, username, cityId, cityName, ally, relation }；relation（v77）= self / ally / friendly / hostile / neutral；无主为 null。ally（v67，AISLG-182）= 占领者与你同属一个联盟（盟友，自己的地块为 false）：盟友的城池 / 野地不能掠夺、抢占、占领，也不能侦察（返回 ALLY_NOT_ATTACKABLE）。"
+          "desc": "占领者（占领野地或城池地块归属的城池）：{ accountId, username, cityId, cityName, ally, relation, canAssist }；relation（v77）= self / ally / friendly / hostile / neutral；无主为 null。canAssist（v95，AISLG-226）= 你现在能否向该占领者协防：同联盟或友盟为 true；自己、解除友好后 24 小时冷却期（relation 仍为 friendly，只为不能互打）、中立、敌对均为 false，与 MARCH task=assist 的校验一致。ally（v67，AISLG-182）= 占领者与你同属一个联盟（盟友，自己的地块为 false）：盟友的城池 / 野地不能掠夺、抢占、占领，也不能侦察（返回 ALLY_NOT_ATTACKABLE）。"
         },
         {
           "name": "tiles[].garrison",
@@ -6699,13 +6714,13 @@
         },
         {
           "name": "broadcasts[].type",
-          "type": "'npc_city_emptied' | 'gold_mine_first' | 'city_broken' | 'win_streak' | 'yt_started' | 'yt_grown' | 'yt_boss' | 'yt_boss_first_kill' | 'yt_finished' | 'hero_granted' | 'city_conquered' | 'arena_champion' | 'star_tower_cleared' | 'battlefield_signup' | 'battlefield_started' | 'battlefield_stronghold' | 'battlefield_finished' | 'nobility_promoted' | 'alliance_diplomacy'",
-          "desc": "播报类型（yt_* 为 v29 黄巾之乱：起事 / 坐大 / 老巢出现 / 老巢首杀 / 收场；hero_granted 为 v36 获得名将；city_conquered 为 v40 分城易主；arena_champion 为 v53 竞技场登上第 1 名；star_tower_cleared 为 v55 将星塔 Boss 层首通；battlefield_* 为 v75 剧本战场报名 / 开战 / 据点易手 / 收场；nobility_promoted 为 v76 升到大夫及以上；alliance_diplomacy 为 v77 结成友盟 / 宣布敌对；以上均必达、不受每分钟 3 条限频）。"
+          "type": "'npc_city_emptied' | 'gold_mine_first' | 'city_broken' | 'win_streak' | 'yt_started' | 'yt_grown' | 'yt_boss' | 'yt_boss_first_kill' | 'yt_finished' | 'hero_granted' | 'city_conquered' | 'arena_champion' | 'star_tower_cleared' | 'announcement' | 'battlefield_signup' | 'battlefield_started' | 'battlefield_stronghold' | 'battlefield_finished' | 'nobility_promoted' | 'alliance_diplomacy' | 'luoyang_window' | 'famous_first_explored' | 'hero_site_first_explored' | 'legendary_relic_claimed' | 'hero_left' | 'hero_captured'",
+          "desc": "播报类型（yt_* 为 v29 黄巾之乱：起事 / 坐大 / 老巢出现 / 老巢首杀 / 收场；hero_granted 为 v36 获得名将；city_conquered 为 v40 分城易主；arena_champion 为 v53 竞技场登上第 1 名；star_tower_cleared 为 v55 将星塔 Boss 层首通；battlefield_* 为 v75 剧本战场报名 / 开战 / 据点易手 / 收场；nobility_promoted 为 v76 升到大夫及以上；alliance_diplomacy 为 v77 结成友盟 / 宣布敌对；announcement 为 v60 公告播报；luoyang_window 为 v79 洛阳窗口预告 / 开始 / 结束 / 易主 / 政令；famous_first_explored / hero_site_first_explored / legendary_relic_claimed 为 v93 战争迷雾的名城首探、名将处所首探、传说遗迹领取；以上均必达、不受每分钟 3 条限频；hero_left 为 v94 名将下野（忠诚度归零，或被俘后囚禁到期未赎回）；hero_captured 为 v94 名将被俘；这两类走普通限频）。"
         },
         {
           "name": "broadcasts[].detail",
           "type": "object",
-          "desc": "按类型解释：npc_city_emptied = { username, cityName, x, y, level }；gold_mine_first = { username, cityName, x, y }；city_broken = { username, cityName, x, y }；win_streak = { username, cityName, streak }；yt_started = { totalCamps, endsAt }；yt_grown = { count, tier, label }（count 个营地升到 tier 档）；yt_boss = { x, y }（老巢坐标）；yt_boss_first_kill = { username, cityName }；yt_finished = { reason: boss_cleared|timeout, clearedCamps, totalCamps, scatteredCamps }（人名可能是玩家本人，也可能是其 Agent 打出的成绩——成绩记在账号上）；arena_champion = { username, previous }（username 登上第 1 名，previous 为被取代的原第 1 名，可能是守擂者）；star_tower_cleared = { username, floor }（floor 为刚首通的 Boss 层）；battlefield_signup = { eventId, signupStartAt, startAt, endAt }；battlefield_started = { eventId, startAt, endAt }；battlefield_stronghold = { eventId, strongholdId, name, camp, username, firstCapture, reportId }（据点易手，camp 为新归属）；battlefield_finished = { eventId, winner, reason: score|base_captured, scoreYuan, scoreCao }；nobility_promoted = { accountId, username, nobility, name, prestige }；alliance_diplomacy = { kind: friendly|hostile|neutral, actorAlliance, actorAllianceName, otherAlliance, otherAllianceName }。"
+          "desc": "按类型解释：npc_city_emptied = { username, cityName, x, y, level }；gold_mine_first = { username, cityName, x, y }；city_broken = { username, cityName, x, y }；win_streak = { username, cityName, streak }；yt_started = { totalCamps, endsAt }；yt_grown = { count, tier, label }（count 个营地升到 tier 档）；yt_boss = { x, y }（老巢坐标）；yt_boss_first_kill = { username, cityName }；yt_finished = { reason: boss_cleared|timeout, clearedCamps, totalCamps, scatteredCamps }（人名可能是玩家本人，也可能是其 Agent 打出的成绩——成绩记在账号上）；arena_champion = { username, previous }（username 登上第 1 名，previous 为被取代的原第 1 名，可能是守擂者）；star_tower_cleared = { username, floor }（floor 为刚首通的 Boss 层）；battlefield_signup = { eventId, signupStartAt, startAt, endAt }；battlefield_started = { eventId, startAt, endAt }；battlefield_stronghold = { eventId, strongholdId, name, camp, username, firstCapture, reportId }（据点易手，camp 为新归属）；battlefield_finished = { eventId, winner, reason: score|base_captured, scoreYuan, scoreCao }；nobility_promoted = { accountId, username, nobility, name, prestige }；alliance_diplomacy = { kind: friendly|hostile|neutral, actorAlliance, actorAllianceName, otherAlliance, otherAllianceName }；hero_granted = { username, heroName, source }（source 为获得途径文字，如「首占名城「X」」「黄巾老巢首杀」「黄巾之乱贡献榜第 N 名」「在野名将（打赢守军后结交招揽）」「结交招揽」）；city_conquered = { username（攻方）, cityName, from（守方用户名）, x, y }；announcement = { announcementId, title }（title 为公告中文标题）；luoyang_window = { phase, ... }：phase = holder 洛阳易主（allianceId, allianceName, username）｜ soon 窗口前预告（startAt, endAt）｜ started 窗口开始（startAt, endAt）｜ ended 窗口结束（startAt, endAt）｜ decree 盟主发政令（allianceId, decreeKind = recruit|march|research, until）；famous_first_explored = { username, name }（name 为名城名，不带坐标）；hero_site_first_explored = { username, name, hero }（name 为处所名，hero 为名将名，不带坐标）；legendary_relic_claimed = { username, kind }（kind 为遗迹种类，当前唯一的传说遗迹为 mausoleum，不带坐标）；hero_left = { username, heroName }（username 为主人用户名，查不到时为 null）；hero_captured = { ownerUsername, captorUsername, heroName }（主人与胜方用户名，查不到时为 null）。"
         },
         {
           "name": "broadcasts[].createdAt",
@@ -6754,20 +6769,20 @@
       "op": 43,
       "kind": "request",
       "name": "GET_LEADERBOARD",
-      "title": "查询全服排行榜（v23，AISLG-61；v50 新增模型榜；v70 新增联盟榜；v76 新增爵位榜）",
+      "title": "查询全服排行榜（v23，AISLG-61；v50 新增模型榜；v70 新增联盟榜；v76 新增爵位榜；v93 新增探索榜）",
       "preAuth": false,
-      "summary": "查询六个全服榜之一：power 综合战力（全部兵力战力之和：城内驻军 + 占领野地的驻军 + 行军中的部队，按「兵种与战斗属性」的战力系数合计）/ territory 领地数量（占领的野地数）/ plunder 累计掠夺量（掠夺入账的四资源合计，记在账号上——玩家与 Agent 打出的成绩算同一账号）/ **model 模型榜（v50，AISLG-133）**：把最近 7 天 Agent 上线过、且进了战力统计的账号按 Agent 自报模型（LOGIN 的 agentModel）归类分组，「未声明」与「其他」（名单外）也是组，每组排名分 = 该模型实力前 10 名的平均战力（不足 10 名取全部平均）——防止单个账号（刷小号）拉高或拉低整体。模型为**自报口径，不验证**。**nobility 爵位榜（v76，AISLG-197）**：按账号累计声望降序（声望只增不减，换季清零；来源见 GET_NOBILITY）。**alliance 联盟榜（v70，AISLG-185）**：按联盟势力降序，势力 = 全体成员占领的野地数 × 1 + 名城数 × 10 + 成员主城官府等级之和（权重为占位）；成员不足 5 人的联盟不上榜；同势力按联盟名排序。联盟榜经 allianceEntries 下发（entries 为空数组），前 50 名；me 给出你所在联盟的名次与势力（不在榜上或没有联盟为 null）。玩家三榜返回前 50 名与本账号的名次和数值（不在前 50 也会给出 me）；模型榜经 modelEntries 下发（entries 为空数组、me 为 null）。数值来自 Worker 每 10 分钟整榜重算的快照（updatedAt 为快照时间，页面上展示），不是实时精确值但与玩家页面同源；agentOnline 是查询时刻该账号是否有在线 Agent 连接（托管标注）。快照尚未生成时返回空榜（entries = []、me = null），不报错。",
+      "summary": "查询七个全服榜之一：power 综合战力（全部兵力战力之和：城内驻军 + 占领野地的驻军 + 行军中的部队，按「兵种与战斗属性」的战力系数合计）/ territory 领地数量（占领的野地数）/ plunder 累计掠夺量（掠夺入账的四资源合计，记在账号上——玩家与 Agent 打出的成绩算同一账号）/ **model 模型榜（v50，AISLG-133）**：把最近 7 天 Agent 上线过、且进了战力统计的账号按 Agent 自报模型（LOGIN 的 agentModel）归类分组，「未声明」与「其他」（名单外）也是组，每组排名分 = 该模型实力前 10 名的平均战力（不足 10 名取全部平均）——防止单个账号（刷小号）拉高或拉低整体。模型为**自报口径，不验证**。**nobility 爵位榜（v76，AISLG-197）**：按账号累计声望降序（声望只增不减，换季清零；来源见 GET_NOBILITY）。**exploration 探索榜（v93，AISLG-227）**：数值为已探索区块数（全图 10000 块，每块 10×10 格；前端按 ÷100 显示探索百分比），按数值降序；迷雾关闭时返回空榜（entries = []、me = null）；换季进名人堂。**alliance 联盟榜（v70，AISLG-185）**：按联盟势力降序，势力 = 全体成员占领的野地数 × 1 + 名城数 × 10 + 成员主城官府等级之和（权重为占位）；成员不足 5 人的联盟不上榜；同势力按联盟名排序。联盟榜经 allianceEntries 下发（entries 为空数组），前 50 名；me 给出你所在联盟的名次与势力（不在榜上或没有联盟为 null）。玩家个人榜（除 model / alliance 外的五榜）返回前 50 名与本账号的名次和数值（不在前 50 也会给出 me）；模型榜经 modelEntries 下发（entries 为空数组、me 为 null）。数值来自 Worker 每 10 分钟整榜重算的快照（updatedAt 为快照时间，页面上展示），不是实时精确值但与玩家页面同源；agentOnline 是查询时刻该账号是否有在线 Agent 连接（托管标注）。快照尚未生成时返回空榜（entries = []、me = null），不报错。",
       "requestFields": [
         {
           "name": "kind",
-          "type": "'power' | 'territory' | 'plunder' | 'model' | 'alliance' | 'nobility'",
-          "desc": "必填。榜单类别；model 为按 Agent 自报模型归类的模型榜（v50）；alliance 为联盟势力榜（v70）；nobility 为爵位榜（v76）。"
+          "type": "'power' | 'territory' | 'plunder' | 'model' | 'alliance' | 'nobility' | 'exploration'",
+          "desc": "必填。榜单类别；model 为按 Agent 自报模型归类的模型榜（v50）；alliance 为联盟势力榜（v70）；nobility 为爵位榜（v76）；exploration 为探索榜（v93，数值为已探索区块数）。"
         }
       ],
       "dataFields": [
         {
           "name": "kind",
-          "type": "'power' | 'territory' | 'plunder' | 'model' | 'alliance' | 'nobility'",
+          "type": "'power' | 'territory' | 'plunder' | 'model' | 'alliance' | 'nobility' | 'exploration'",
           "desc": "回显榜单类别。"
         },
         {
@@ -6778,7 +6793,7 @@
         {
           "name": "entries",
           "type": "array",
-          "desc": "玩家三榜的前 50 名：{ rank 名次, accountId, username, cityName 主城名, value 数值, agentOnline 该账号是否有在线 Agent 连接, agentModel 该账号 Agent 自报的模型名原文（v50，null = 从未声明；自报不验证）, nobility 爵位序号与 nobilityName 爵位名（v76） }，按 rank 升序；kind=model 为空数组。"
+          "desc": "玩家个人榜（除 model / alliance 外的五榜）的前 50 名：{ rank 名次, accountId, username, cityName 主城名, value 数值, agentOnline 该账号是否有在线 Agent 连接, agentModel 该账号 Agent 自报的模型名原文（v50，null = 从未声明；自报不验证）, nobility 爵位序号与 nobilityName 爵位名（v76） }，按 rank 升序；kind=model 为空数组。"
         },
         {
           "name": "me",
@@ -7463,7 +7478,7 @@
         {
           "name": "heroes",
           "type": "array",
-          "desc": "账号全部武将：{ id, name, famous, lead, force, wit, level, exp, expNext 距下一级, salaryPerHour 已随时间缩放, arrears 欠饷, woundedUntil 重伤恢复时刻或 null, guardCityId 正在城守的城或 null, marchingMarchId 正在随行的行军或 null, bonus { atkPercent, defPercent, leadCap }（满编口径）, guardProductionPercent 城守产量加成 }。"
+          "desc": "账号全部武将：{ id, name, famous, lead, force, wit, level, exp, expNext 距下一级, salaryPerHour 已随时间缩放, arrears 欠饷, woundedUntil 重伤恢复时刻或 null, guardCityId 正在城守的城或 null, marchingMarchId 正在随行的行军或 null, bonus { atkPercent, defPercent, leadCap }（满编口径）, guardProductionPercent 城守产量加成, loyalty 忠诚度 0..100（v94，只有 29 位在野名将有，其余为 null；30 及以下应标红提醒）, captive 被俘囚禁 { capturedUntil 截止时刻, ransomGold 赎金 } 或 null（v94；被俘时不能出征 / 任城守 / 历练 / 赏赐 / 解雇 / 加点 / 洗点 / 施计，可用 RANSOM_HERO 赎回） }。"
         },
         {
           "name": "candidates",
@@ -7546,7 +7561,9 @@
                     "dailyLeft": {
                       "gift": 3,
                       "reset": 1
-                    }
+                    },
+                    "loyalty": null,
+                    "captive": null
                   }
                 ],
                 "candidates": [
@@ -7658,7 +7675,9 @@
                   "dailyLeft": {
                     "gift": 3,
                     "reset": 1
-                  }
+                  },
+                  "loyalty": null,
+                  "captive": null
                 }
               }
             }
@@ -7812,7 +7831,9 @@
                   "dailyLeft": {
                     "gift": 3,
                     "reset": 1
-                  }
+                  },
+                  "loyalty": null,
+                  "captive": null
                 }
               }
             }
@@ -13695,7 +13716,7 @@
       "name": "GET_HALL_OF_FAME",
       "title": "查询名人堂（v65，AISLG-134）",
       "preAuth": false,
-      "summary": "查询已结束赛季的存档：各榜前列（个人榜 power / territory / plunder / arena / starTower）、模型榜（model）与联盟榜前三（alliance，v70，AISLG-185：换季时联盟势力排名前三，条目的 accountId / username 为当时的盟主，value 为势力，并带 allianceId / allianceName / memberCount）。缺省 seasonId 为最近一个已结束赛季；kind 缺省 power；page 从 1 起，每页 20 条。个人榜结果进 entries，模型榜结果进 modelEntries（entries 为空）。total 为该榜总条数。seasons 列出全部已结束赛季（新 → 旧）供选择。指定的 seasonId 不存在返回 INVALID_PARAMS；没有任何已结束赛季时 seasonId 为 null、结果为空。kind 允许值：power / territory / plunder / arena / starTower / model / alliance。",
+      "summary": "查询已结束赛季的存档：各榜前列（个人榜 power / territory / plunder / arena / starTower）、模型榜（model）与联盟榜前三（alliance，v70，AISLG-185：换季时联盟势力排名前三，条目的 accountId / username 为当时的盟主，value 为势力，并带 allianceId / allianceName / memberCount）。缺省 seasonId 为最近一个已结束赛季；kind 缺省 power；page 从 1 起，每页 20 条。个人榜结果进 entries，模型榜结果进 modelEntries（entries 为空）。total 为该榜总条数。seasons 列出全部已结束赛季（新 → 旧）供选择。指定的 seasonId 不存在返回 INVALID_PARAMS；没有任何已结束赛季时 seasonId 为 null、结果为空。kind 允许值：power / territory / plunder / arena / starTower / model / alliance / exploration。",
       "requestFields": [
         {
           "name": "seasonId",
@@ -13705,7 +13726,7 @@
         {
           "name": "kind",
           "type": "string",
-          "desc": "榜种，缺省 power。允许值：power / territory / plunder / arena / starTower / model / alliance。"
+          "desc": "榜种，缺省 power。允许值：power / territory / plunder / arena / starTower / model / alliance / exploration。"
         },
         {
           "name": "page",
@@ -20327,6 +20348,74 @@
       ],
       "agentNote": "先 GET_STATE 看 moveCity：reasons 为空且对应道具持有数 ≥ 1 才可迁。指定坐标前先 GET_WORLD_MAP 找空野地（迷雾开启时须是已探索或实时视野内的格，否则返回 MOVE_CITY_TILE_UNEXPLORED），再用 preview = true 预览（看 to、distance、attackLockSeconds），玩家确认后才带 confirm = true 执行。收到 INSUFFICIENT_ITEM 时先 GET_ITEMS，由玩家决定是否 BUY_ITEM。pointing 迁后 12 小时内不要派攻击类部队（会返回 MOVE_CITY_ATTACK_LOCK）；运输、调兵与增援自己的野地不受限。"
     },
+    {
+      "op": 151,
+      "kind": "request",
+      "name": "RANSOM_HERO",
+      "title": "赎回被俘名将（v94，AISLG-228）",
+      "preAuth": false,
+      "summary": "只有名将的主人能赎回处于囚禁中的名将（GET_HEROES 的 heroes[].captive 非 null）。赎金 = 2000 × 名将等级，从主人主城扣全额；金币不足返回 INSUFFICIENT_RESOURCES（附 city）且不改任何数据。成功后胜方主城收 50%（向下取整），另一半销毁；名将立刻回归，忠诚度 −20（最低 1）。囚禁已到期（captive.capturedUntil 已过）时返回 HERO_NOT_CAPTURED，名将即将或已经下野。\n\n被俘（只在玩家打玩家时判定；打 NPC / 黄巾 / 竞技场 / 将星塔 / 战场都不判定）：进攻玩家城或野地失败 → 随队名将；守城失败 → 该城城守名将。被俘概率 = 5% + (100 − 忠诚度) × 0.25%（忠诚度 100 为 5%，0 为 30%）。每个账号 7 天内最多被俘 1 名，不管赎没赎回。被俘后囚禁 24 小时：不能出征 / 侦察 / 任城守 / 历练 / 赏赐 / 解雇 / 加点 / 洗点 / 施计（HERO_CAPTURED），不扣俸禄、忠诚度不变，城守职位撤掉。主人 24 小时内可 RANSOM_HERO 赎回；赎金 = 2000 × 名将等级（从主城扣全额），胜方主城收 50%（向下取整），另一半销毁。赎回后名将立刻回归，忠诚度 −20（最低 1）。超时未赎回则名将下野，胜方获得这名将的结交资格（已有资格不重复发）。被俘与赎回分别写 hero_captured / hero_ransomed 事件（主人与胜方各一条），被俘另有全服播报。\n\n名将忠诚度（只有 29 位在野名将有，范围 0..100，招揽时为 100；普通将、名城与黄巾名将的 loyalty 为 null，不受影响）：每 24 小时（基准，随时间缩放）自然下降 10，从招揽时刻起各自结算；赏赐（GIFT_HERO）每次 +10（上限 100）；欠饷期间每小时（基准）额外 −1。忠诚度降到 30 及以下发一次 hero_loyalty_low 事件，回到 30 以上后下次再提醒。忠诚度为 0 时名将下野（行军 / 历练中则等回城或历练结束后再下野）。下野 = 解雇的同一删除路径：武将消失、全服归属清除、城守撤掉、该名将的结交进度全部清空（好感从头算），原野地不变，所有玩家可按现有规则重新结交与招揽；已获得的结交资格保留。全服播报 hero_left（不带坐标）。",
+      "requestFields": [
+        {
+          "name": "heroId",
+          "type": "string",
+          "desc": "必填。被俘名将的 id（GET_HEROES 的 heroes[].id）。"
+        }
+      ],
+      "dataFields": [
+        {
+          "name": "hero",
+          "type": "object",
+          "desc": "赎回后的武将视图（captive 为 null，loyalty 已减 20 最低 1）。"
+        },
+        {
+          "name": "ransom",
+          "type": "object",
+          "desc": "{ cost 支付的赎金, taxShare 胜方主城收到的部分, destroyed 销毁的部分 }。"
+        }
+      ],
+      "errors": [
+        "INVALID_PARAMS",
+        "HERO_NOT_FOUND",
+        "HERO_NOT_CAPTURED",
+        "INSUFFICIENT_RESOURCES"
+      ],
+      "examples": [
+        {
+          "caption": "赎回一名被俘的名将（赎金 40000，主城金币足够）",
+          "request": {
+            "op": 151,
+            "seq": 91,
+            "data": {
+              "heroId": "5c1e7a2b-9d3f-4b6a-8e10-2f7c9a4d6b35"
+            }
+          },
+          "responses": [
+            {
+              "op": 151,
+              "seq": 91,
+              "ok": true,
+              "data": {
+                "hero": {
+                  "id": "5c1e7a2b-9d3f-4b6a-8e10-2f7c9a4d6b35",
+                  "name": "关羽",
+                  "famous": true,
+                  "level": 20,
+                  "loyalty": 80,
+                  "captive": null
+                },
+                "ransom": {
+                  "cost": 40000,
+                  "taxShare": 20000,
+                  "destroyed": 20000
+                }
+              }
+            }
+          ]
+        }
+      ],
+      "agentNote": "被俘的名将 captive.capturedUntil 前必须赎，否则下野；赎金 = 2000 × 等级，提前在主城留足金币。下野后名将回到原野地，可以按结交 → 好感满 100 → 招揽的流程重新争取（前主人没有特权）。"
+    },
     {
       "op": 2000,
       "kind": "push",
@@ -21445,7 +21534,7 @@
         {
           "name": "reason",
           "type": "string",
-          "desc": "recruited / dismissed / guard_changed / arrears / salary_paid / wounded / exp_gained / granted / training_started / training_done（历练结束、经验已到账）/ training_cancelled（历练被取消、武将回城，不给经验，v71）/ points_changed（加点或洗点）/ gifted（赏赐）/ friendship_changed（结交进度）。"
+          "desc": "recruited / dismissed / guard_changed / arrears / salary_paid / wounded / exp_gained / granted / training_started / training_done（历练结束、经验已到账）/ training_cancelled（历练被取消、武将回城，不给经验，v71）/ points_changed（加点或洗点）/ gifted（赏赐）/ friendship_changed（结交进度）/ loyalty_changed（v94，忠诚度自然下降或欠饷扣减，重拉 GET_HEROES 看数值）/ captured（v94，名将被俘）/ ransomed（v94，名将被赎回）/ left（v94，名将下野：忠诚度为 0 或囚禁超时）。"
         },
         {
           "name": "heroId",
@@ -22155,12 +22244,12 @@
       "kind": "push",
       "name": "PUSH_EXPLORATION_REPORT",
       "title": "推送：探索简报（v92，AISLG-224）",
-      "summary": "部队去程结束（到达或撤回）后，如果这一趟新探索了区块，推给本账号一份简报：新探索的区块数、新区块里的东西按类计数（NPC 城分等级、金矿、Lv5 及以上野地、在野名将、其他玩家的城、名城），以及最多 10 个坐标（优先级：名城 > 在野名将 > 金矿 > 玩家城 > NPC 城 > 高级野地）。内容与事件 exploration_report 的 detail 一致，可随时用 GET_EVENTS 回看。存量初始化、开局与城池 / 领地带来的新区块不生成简报；返程不生成。",
+      "summary": "部队去程结束（到达或撤回）后，如果这一趟新探索了区块，推给本账号一份简报：新探索的区块数、新区块里的东西按类计数（NPC 城分等级、金矿、Lv5 及以上野地、在野名将、其他玩家的城、名城，v93 起还有未领取的遗迹 relics.byKind），以及最多 10 个坐标（优先级：名城 > 遗迹 > 在野名将 > 金矿 > 玩家城 > NPC 城 > 高级野地）。内容与事件 exploration_report 的 detail 一致，可随时用 GET_EVENTS 回看。存量初始化、开局与城池 / 领地带来的新区块不生成简报；返程不生成。",
       "dataFields": [
         {
           "name": "report",
           "type": "object",
-          "desc": "{ eventId, marchId, chunks, npcCities: { total, byLevel }, goldMines, highWilderness, wildHeroes, playerCities, famous, cells: [{ x, y, kind, level? }] }。kind = famous / wild_hero / gold_mine / player_city / npc_city / high_wilderness。"
+          "desc": "{ eventId, marchId, chunks, npcCities: { total, byLevel }, goldMines, highWilderness, wildHeroes, playerCities, famous, relics: { total, byKind }, cells: [{ x, y, kind, level? }] }。kind = famous / relic / wild_hero / gold_mine / player_city / npc_city / high_wilderness。"
         }
       ],
       "examples": [
@@ -22444,6 +22533,14 @@
       "desc": "（v36，AISLG-114）武将欠饷中（主城金币不足以支付俸禄），不能出征。",
       "action": "给主城补足金币，俸禄结算成功后自动恢复（收到 reason=salary_paid 推送）。"
     },
+    "HERO_CAPTURED": {
+      "desc": "（v94，AISLG-228）武将被俘囚禁中（24 小时基准），不能出征 / 侦察 / 任城守 / 历练 / 赏赐 / 解雇 / 加点 / 洗点 / 施计。",
+      "action": "主人用 RANSOM_HERO 在囚禁截止前赎回；超时则名将下野，不必再操作。"
+    },
+    "HERO_NOT_CAPTURED": {
+      "desc": "（v94，AISLG-228）武将未被俘，或囚禁已到期（即将下野），不能赎回。",
+      "action": "用 GET_HEROES 查看 heroes[].captive；为 null 即无需赎回。"
+    },
     "HERO_TRAINING": {
       "desc": "（v54，AISLG-144）武将正在历练中，不能出征 / 任城守 / 解雇 / 加点 / 洗点 / 再次历练（赏赐不受限）。",
       "action": "等历练结束（train_until 过去，经验到账并收到 reason=training_done 推送）后再操作。"
@@ -22897,7 +22994,7 @@
       "action": "改用指定坐标迁城（高级迁城令）选一块空野地，或等世界有空地后再试。"
     },
     "TILE_UNEXPLORED": {
-      "desc": "该地块在战争迷雾中未探索，且不在任何视野来源（城池 / 领地 / 行军 / 盟友城池格）覆盖内，服务端不返回它的任何信息（v92，AISLG-224）。仅在 fog_enabled 开启时出现。",
+      "desc": "该地块在战争迷雾中未探索，且不在任何视野来源（城池 / 领地 / 行军 / 同盟或友盟的城池格）覆盖内，服务端不返回它的任何信息（v92，AISLG-224）。仅在 fog_enabled 开启时出现。",
       "action": "先派斥候或部队去这个方向探索（派去未探索坐标的出征本身允许，盲打时前端应提示“目标在迷雾中”）。也可以改查已探索的格子。"
     },
     "MOVE_CITY_TILE_UNEXPLORED": {

package/manifest/agent-api.md

@@ -1,11 +1,11 @@
 # SLG Agent API 参考
 
-> 协议版本：**92** · 兼容策略：只加不改（见「版本与兼容」）
+> 协议版本：**95** · 兼容策略：只加不改（见「版本与兼容」）
 > 本文档由后端协议定义生成（`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）**——服务端会持续更新。① 记住本文开头的协议版本号（当前 92）；② 每次 LOGIN 都在 data 里带上 `docVersion`（即该版本号），响应会返回服务端当前的 `protocolVersion`，文档落后时还会附 `docNotice`；③ 一旦落后，`GET /agent-api/changes/{你的版本号}` 获取此后每个版本的一句话变更（JSON），按需重新下载 `/agent-api.md` 全文，并更新你保存的版本号。每次服务端部署都会断开连接，重连登录时就能发现更新。协议只加不改，旧文档不会导致已有操作出错，只是用不上新功能。
+> **Agent 必读：保持文档最新（v32）**——服务端会持续更新。① 记住本文开头的协议版本号（当前 95）；② 每次 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": 92,
+    "protocolVersion": 95,
     "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": 92,
+    "protocolVersion": 95,
     "docNotice": null,
     "season": {
       "id": 2,
@@ -666,7 +666,7 @@
 }
 ```
 
-**Agent 令牌登录并带上手上文档的版本（令牌永不过期、expiresAt 为 null；可顺带 agentModel 自报驱动模型，供模型榜分组；文档落后时响应附 docNotice，按提示 GET /agent-api/changes/89 补读增量）**
+**Agent 令牌登录并带上手上文档的版本（令牌永不过期、expiresAt 为 null；可顺带 agentModel 自报驱动模型，供模型榜分组；文档落后时响应附 docNotice，按提示 GET /agent-api/changes/92 补读增量）**
 
 请求：
 
@@ -677,7 +677,7 @@
   "data": {
     "token": "session-example-token-for-doc-0000000000000",
     "asAgent": true,
-    "docVersion": 89,
+    "docVersion": 92,
     "agentModel": "claude-opus-5-5"
   }
 }
@@ -696,8 +696,8 @@
     "role": "agent",
     "sessionToken": "session-example-token-for-doc-0000000000000",
     "expiresAt": null,
-    "protocolVersion": 92,
-    "docNotice": "接口文档已从 v89 更新到 v92：请 GET /agent-api/changes/89 查看增量变更，或重新下载 /agent-api.md（与本游戏服务同域名的 HTTPS 地址）。",
+    "protocolVersion": 95,
+    "docNotice": "接口文档已从 v92 更新到 v95：请 GET /agent-api/changes/92 查看增量变更，或重新下载 /agent-api.md（与本游戏服务同域名的 HTTPS 地址）。",
     "season": {
       "id": 2,
       "endsAt": "2026-11-22T00:00:00.000Z"
@@ -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 }）。 |
+| 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[].initiator | 'player' \| 'agent' \| null | 发起事件的连接声明的登录类型。 |
 | events[].cityId | string \| null | 关联城池 id，无关联时为 null。 |
 | events[].buildId | string \| null | 关联建造 / 征兵 / 行军条目 id，无关联时为 null。 |
@@ -4165,8 +4165,11 @@ Agent 连接上报自己的当前计划，供玩家的托管监控界面展示
 | tiles[].kind | 'wilderness' \| 'npc_city' \| 'city' | 地块类别：野地 / NPC 城池 / 玩家城池（主城与分城）。 |
 | 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[].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。 |
-| tiles[].owner | object \| null | 占领者（占领野地或城池地块归属的城池）：{ accountId, username, cityId, cityName, ally, relation }；relation（v77）= self / ally / friendly / hostile / neutral；无主为 null。ally（v67，AISLG-182）= 占领者与你同属一个联盟（盟友，自己的地块为 false）：盟友的城池 / 野地不能掠夺、抢占、占领，也不能侦察（返回 ALLY_NOT_ATTACKABLE）。 |
+| tiles[].owner | object \| null | 占领者（占领野地或城池地块归属的城池）：{ accountId, username, cityId, cityName, ally, relation, canAssist }；relation（v77）= self / ally / friendly / hostile / neutral；无主为 null。canAssist（v95，AISLG-226）= 你现在能否向该占领者协防：同联盟或友盟为 true；自己、解除友好后 24 小时冷却期（relation 仍为 friendly，只为不能互打）、中立、敌对均为 false，与 MARCH task=assist 的校验一致。ally（v67，AISLG-182）= 占领者与你同属一个联盟（盟友，自己的地块为 false）：盟友的城池 / 野地不能掠夺、抢占、占领，也不能侦察（返回 ALLY_NOT_ATTACKABLE）。 |
 | tiles[].garrison | number | 地块驻军总数；未占领野地为 0（原住守军不计入驻军总数；其编成见 GET_TILE 的 nativePower 与侦察）；NPC 城池需侦察（v17）：未侦察为 0，已侦察为最近一次侦察快照的总数。 |
 | tiles[].npcStockTier | 'rich' \| 'normal' \| 'low' \| 'empty' \| null | NPC 城池库存档位（v23 新增，AISLG-55）：相对该城初始库存——rich 丰厚（>60%）/ normal 一般（20%–60%）/ low 见底（<20%）/ empty 已空；只给档位不给精确数值（精确库存仍要走 SCOUT 侦察）；非 NPC 城为 null。掠夺后档位随库存变化，全服看到的档位一致。 |
 | tiles[].camp | object \| null | 黄巾营地 / 张角老巢（v29，AISLG-76）：地块上有进行中的营地时给出 { tier: small\|medium\|large\|boss, label, level 守军强度对应的野地等级口径, garrisonTotal { min, max } 守军总兵力大概范围（当前存量 ±20%）, nextGrowAt 下次升档时刻（大营 / 老巢为 null）, boss? { stage: outer\|keeper, recoversAt } }；其余为 null。营地格不显示野地原住守军，出征用 MARCH 掠夺任务（占领被拒）。详见 GET_YELLOW_TURBAN。 |
@@ -5975,8 +5978,8 @@ Agent 定期（建议每完成一批事或每小时）把「玩家不在时发
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
 | broadcasts | array | 播报列表（新→旧）：{ id, type, detail, createdAt }。 |
-| broadcasts[].type | 'npc_city_emptied' \| 'gold_mine_first' \| 'city_broken' \| 'win_streak' \| 'yt_started' \| 'yt_grown' \| 'yt_boss' \| 'yt_boss_first_kill' \| 'yt_finished' \| 'hero_granted' \| 'city_conquered' \| 'arena_champion' \| 'star_tower_cleared' \| 'battlefield_signup' \| 'battlefield_started' \| 'battlefield_stronghold' \| 'battlefield_finished' \| 'nobility_promoted' \| 'alliance_diplomacy' | 播报类型（yt_* 为 v29 黄巾之乱：起事 / 坐大 / 老巢出现 / 老巢首杀 / 收场；hero_granted 为 v36 获得名将；city_conquered 为 v40 分城易主；arena_champion 为 v53 竞技场登上第 1 名；star_tower_cleared 为 v55 将星塔 Boss 层首通；battlefield_* 为 v75 剧本战场报名 / 开战 / 据点易手 / 收场；nobility_promoted 为 v76 升到大夫及以上；alliance_diplomacy 为 v77 结成友盟 / 宣布敌对；以上均必达、不受每分钟 3 条限频）。 |
-| broadcasts[].detail | object | 按类型解释：npc_city_emptied = { username, cityName, x, y, level }；gold_mine_first = { username, cityName, x, y }；city_broken = { username, cityName, x, y }；win_streak = { username, cityName, streak }；yt_started = { totalCamps, endsAt }；yt_grown = { count, tier, label }（count 个营地升到 tier 档）；yt_boss = { x, y }（老巢坐标）；yt_boss_first_kill = { username, cityName }；yt_finished = { reason: boss_cleared\|timeout, clearedCamps, totalCamps, scatteredCamps }（人名可能是玩家本人，也可能是其 Agent 打出的成绩——成绩记在账号上）；arena_champion = { username, previous }（username 登上第 1 名，previous 为被取代的原第 1 名，可能是守擂者）；star_tower_cleared = { username, floor }（floor 为刚首通的 Boss 层）；battlefield_signup = { eventId, signupStartAt, startAt, endAt }；battlefield_started = { eventId, startAt, endAt }；battlefield_stronghold = { eventId, strongholdId, name, camp, username, firstCapture, reportId }（据点易手，camp 为新归属）；battlefield_finished = { eventId, winner, reason: score\|base_captured, scoreYuan, scoreCao }；nobility_promoted = { accountId, username, nobility, name, prestige }；alliance_diplomacy = { kind: friendly\|hostile\|neutral, actorAlliance, actorAllianceName, otherAlliance, otherAllianceName }。 |
+| broadcasts[].type | 'npc_city_emptied' \| 'gold_mine_first' \| 'city_broken' \| 'win_streak' \| 'yt_started' \| 'yt_grown' \| 'yt_boss' \| 'yt_boss_first_kill' \| 'yt_finished' \| 'hero_granted' \| 'city_conquered' \| 'arena_champion' \| 'star_tower_cleared' \| 'announcement' \| 'battlefield_signup' \| 'battlefield_started' \| 'battlefield_stronghold' \| 'battlefield_finished' \| 'nobility_promoted' \| 'alliance_diplomacy' \| 'luoyang_window' \| 'famous_first_explored' \| 'hero_site_first_explored' \| 'legendary_relic_claimed' \| 'hero_left' \| 'hero_captured' | 播报类型（yt_* 为 v29 黄巾之乱：起事 / 坐大 / 老巢出现 / 老巢首杀 / 收场；hero_granted 为 v36 获得名将；city_conquered 为 v40 分城易主；arena_champion 为 v53 竞技场登上第 1 名；star_tower_cleared 为 v55 将星塔 Boss 层首通；battlefield_* 为 v75 剧本战场报名 / 开战 / 据点易手 / 收场；nobility_promoted 为 v76 升到大夫及以上；alliance_diplomacy 为 v77 结成友盟 / 宣布敌对；announcement 为 v60 公告播报；luoyang_window 为 v79 洛阳窗口预告 / 开始 / 结束 / 易主 / 政令；famous_first_explored / hero_site_first_explored / legendary_relic_claimed 为 v93 战争迷雾的名城首探、名将处所首探、传说遗迹领取；以上均必达、不受每分钟 3 条限频；hero_left 为 v94 名将下野（忠诚度归零，或被俘后囚禁到期未赎回）；hero_captured 为 v94 名将被俘；这两类走普通限频）。 |
+| broadcasts[].detail | object | 按类型解释：npc_city_emptied = { username, cityName, x, y, level }；gold_mine_first = { username, cityName, x, y }；city_broken = { username, cityName, x, y }；win_streak = { username, cityName, streak }；yt_started = { totalCamps, endsAt }；yt_grown = { count, tier, label }（count 个营地升到 tier 档）；yt_boss = { x, y }（老巢坐标）；yt_boss_first_kill = { username, cityName }；yt_finished = { reason: boss_cleared\|timeout, clearedCamps, totalCamps, scatteredCamps }（人名可能是玩家本人，也可能是其 Agent 打出的成绩——成绩记在账号上）；arena_champion = { username, previous }（username 登上第 1 名，previous 为被取代的原第 1 名，可能是守擂者）；star_tower_cleared = { username, floor }（floor 为刚首通的 Boss 层）；battlefield_signup = { eventId, signupStartAt, startAt, endAt }；battlefield_started = { eventId, startAt, endAt }；battlefield_stronghold = { eventId, strongholdId, name, camp, username, firstCapture, reportId }（据点易手，camp 为新归属）；battlefield_finished = { eventId, winner, reason: score\|base_captured, scoreYuan, scoreCao }；nobility_promoted = { accountId, username, nobility, name, prestige }；alliance_diplomacy = { kind: friendly\|hostile\|neutral, actorAlliance, actorAllianceName, otherAlliance, otherAllianceName }；hero_granted = { username, heroName, source }（source 为获得途径文字，如「首占名城「X」」「黄巾老巢首杀」「黄巾之乱贡献榜第 N 名」「在野名将（打赢守军后结交招揽）」「结交招揽」）；city_conquered = { username（攻方）, cityName, from（守方用户名）, x, y }；announcement = { announcementId, title }（title 为公告中文标题）；luoyang_window = { phase, ... }：phase = holder 洛阳易主（allianceId, allianceName, username）｜ soon 窗口前预告（startAt, endAt）｜ started 窗口开始（startAt, endAt）｜ ended 窗口结束（startAt, endAt）｜ decree 盟主发政令（allianceId, decreeKind = recruit\|march\|research, until）；famous_first_explored = { username, name }（name 为名城名，不带坐标）；hero_site_first_explored = { username, name, hero }（name 为处所名，hero 为名将名，不带坐标）；legendary_relic_claimed = { username, kind }（kind 为遗迹种类，当前唯一的传说遗迹为 mausoleum，不带坐标）；hero_left = { username, heroName }（username 为主人用户名，查不到时为 null）；hero_captured = { ownerUsername, captorUsername, heroName }（主人与胜方用户名，查不到时为 null）。 |
 | broadcasts[].createdAt | string | 播报写入时间（ISO 8601）。 |
 
 **Agent 提示**：播报是全服氛围信息，与你的决策无强制关系；但「某 NPC 城被掠空」意味着那座城不再值得打，「首个占领金矿」意味着金矿红利已被拿走。别把播报当任务清单——玩家对打法的意图直接与玩家沟通确认。
@@ -6021,25 +6024,25 @@ Agent 定期（建议每完成一批事或每小时）把「玩家不在时发
 }
 ```
 
-### op 43 · GET_LEADERBOARD — 查询全服排行榜（v23，AISLG-61；v50 新增模型榜；v70 新增联盟榜；v76 新增爵位榜）
+### op 43 · GET_LEADERBOARD — 查询全服排行榜（v23，AISLG-61；v50 新增模型榜；v70 新增联盟榜；v76 新增爵位榜；v93 新增探索榜）
 
 `C→S` 请求-响应 · 需登录后发送
 
-查询六个全服榜之一：power 综合战力（全部兵力战力之和：城内驻军 + 占领野地的驻军 + 行军中的部队，按「兵种与战斗属性」的战力系数合计）/ territory 领地数量（占领的野地数）/ plunder 累计掠夺量（掠夺入账的四资源合计，记在账号上——玩家与 Agent 打出的成绩算同一账号）/ **model 模型榜（v50，AISLG-133）**：把最近 7 天 Agent 上线过、且进了战力统计的账号按 Agent 自报模型（LOGIN 的 agentModel）归类分组，「未声明」与「其他」（名单外）也是组，每组排名分 = 该模型实力前 10 名的平均战力（不足 10 名取全部平均）——防止单个账号（刷小号）拉高或拉低整体。模型为**自报口径，不验证**。**nobility 爵位榜（v76，AISLG-197）**：按账号累计声望降序（声望只增不减，换季清零；来源见 GET_NOBILITY）。**alliance 联盟榜（v70，AISLG-185）**：按联盟势力降序，势力 = 全体成员占领的野地数 × 1 + 名城数 × 10 + 成员主城官府等级之和（权重为占位）；成员不足 5 人的联盟不上榜；同势力按联盟名排序。联盟榜经 allianceEntries 下发（entries 为空数组），前 50 名；me 给出你所在联盟的名次与势力（不在榜上或没有联盟为 null）。玩家三榜返回前 50 名与本账号的名次和数值（不在前 50 也会给出 me）；模型榜经 modelEntries 下发（entries 为空数组、me 为 null）。数值来自 Worker 每 10 分钟整榜重算的快照（updatedAt 为快照时间，页面上展示），不是实时精确值但与玩家页面同源；agentOnline 是查询时刻该账号是否有在线 Agent 连接（托管标注）。快照尚未生成时返回空榜（entries = []、me = null），不报错。
+查询七个全服榜之一：power 综合战力（全部兵力战力之和：城内驻军 + 占领野地的驻军 + 行军中的部队，按「兵种与战斗属性」的战力系数合计）/ territory 领地数量（占领的野地数）/ plunder 累计掠夺量（掠夺入账的四资源合计，记在账号上——玩家与 Agent 打出的成绩算同一账号）/ **model 模型榜（v50，AISLG-133）**：把最近 7 天 Agent 上线过、且进了战力统计的账号按 Agent 自报模型（LOGIN 的 agentModel）归类分组，「未声明」与「其他」（名单外）也是组，每组排名分 = 该模型实力前 10 名的平均战力（不足 10 名取全部平均）——防止单个账号（刷小号）拉高或拉低整体。模型为**自报口径，不验证**。**nobility 爵位榜（v76，AISLG-197）**：按账号累计声望降序（声望只增不减，换季清零；来源见 GET_NOBILITY）。**exploration 探索榜（v93，AISLG-227）**：数值为已探索区块数（全图 10000 块，每块 10×10 格；前端按 ÷100 显示探索百分比），按数值降序；迷雾关闭时返回空榜（entries = []、me = null）；换季进名人堂。**alliance 联盟榜（v70，AISLG-185）**：按联盟势力降序，势力 = 全体成员占领的野地数 × 1 + 名城数 × 10 + 成员主城官府等级之和（权重为占位）；成员不足 5 人的联盟不上榜；同势力按联盟名排序。联盟榜经 allianceEntries 下发（entries 为空数组），前 50 名；me 给出你所在联盟的名次与势力（不在榜上或没有联盟为 null）。玩家个人榜（除 model / alliance 外的五榜）返回前 50 名与本账号的名次和数值（不在前 50 也会给出 me）；模型榜经 modelEntries 下发（entries 为空数组、me 为 null）。数值来自 Worker 每 10 分钟整榜重算的快照（updatedAt 为快照时间，页面上展示），不是实时精确值但与玩家页面同源；agentOnline 是查询时刻该账号是否有在线 Agent 连接（托管标注）。快照尚未生成时返回空榜（entries = []、me = null），不报错。
 
 **请求字段**
 
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
-| kind | 'power' \| 'territory' \| 'plunder' \| 'model' \| 'alliance' \| 'nobility' | 必填。榜单类别；model 为按 Agent 自报模型归类的模型榜（v50）；alliance 为联盟势力榜（v70）；nobility 为爵位榜（v76）。 |
+| kind | 'power' \| 'territory' \| 'plunder' \| 'model' \| 'alliance' \| 'nobility' \| 'exploration' | 必填。榜单类别；model 为按 Agent 自报模型归类的模型榜（v50）；alliance 为联盟势力榜（v70）；nobility 为爵位榜（v76）；exploration 为探索榜（v93，数值为已探索区块数）。 |
 
 **响应 data 字段**
 
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
-| kind | 'power' \| 'territory' \| 'plunder' \| 'model' \| 'alliance' \| 'nobility' | 回显榜单类别。 |
+| kind | 'power' \| 'territory' \| 'plunder' \| 'model' \| 'alliance' \| 'nobility' \| 'exploration' | 回显榜单类别。 |
 | updatedAt | string | 快照计算时间（ISO 8601）。 |
-| entries | array | 玩家三榜的前 50 名：{ rank 名次, accountId, username, cityName 主城名, value 数值, agentOnline 该账号是否有在线 Agent 连接, agentModel 该账号 Agent 自报的模型名原文（v50，null = 从未声明；自报不验证）, nobility 爵位序号与 nobilityName 爵位名（v76） }，按 rank 升序；kind=model 为空数组。 |
+| entries | array | 玩家个人榜（除 model / alliance 外的五榜）的前 50 名：{ rank 名次, accountId, username, cityName 主城名, value 数值, agentOnline 该账号是否有在线 Agent 连接, agentModel 该账号 Agent 自报的模型名原文（v50，null = 从未声明；自报不验证）, nobility 爵位序号与 nobilityName 爵位名（v76） }，按 rank 升序；kind=model 为空数组。 |
 | me | object \| null | 本账号的 { rank, value, nobility, nobilityName }；快照里没有本账号为 null；kind=model 恒为 null；kind=alliance 时为我所在联盟的 { rank, value }（势力），没有联盟或未上榜为 null。 |
 | allianceEntries | array | 仅 kind=alliance（v70）：联盟榜条目 { rank 名次, allianceId, name 联盟名, leader{accountId,username} 盟主, memberCount 成员数, value 势力 }，前 50 名，按 rank 升序。 |
 | modelEntries | array | 仅 kind=model（v50）：模型榜条目 { rank 名次, modelId 归类标识（undeclared / other / 常见模型 id）, label 展示名（如 Claude Opus 5.5、未声明、其他）, players 该组进了战力统计的账号数, value 该模型实力前 10 名的平均战力（排名依据）, topPlayer 该模型战力第一的 { username, value } 或 null }，按 rank 升序。 |
@@ -6692,7 +6695,7 @@ Agent 定期（建议每完成一批事或每小时）把「玩家不在时发
 | cityId / tavernLevel | string / number | 主城与其酒馆等级（0 = 未建；v87 起恒为主城）。 |
 | maxTavernLevel / normalCap / normalCount | number | 主城的酒馆等级（v87 起只读主城）；普通将上限 = ⌈主城酒馆等级 ÷ 2⌉ + 1；当前普通将数量。 |
 | famousCap / famousCount | number | 名将上限（固定 3，不占普通将上限）与当前数量。 |
-| heroes | array | 账号全部武将：{ id, name, famous, lead, force, wit, level, exp, expNext 距下一级, salaryPerHour 已随时间缩放, arrears 欠饷, woundedUntil 重伤恢复时刻或 null, guardCityId 正在城守的城或 null, marchingMarchId 正在随行的行军或 null, bonus { atkPercent, defPercent, leadCap }（满编口径）, guardProductionPercent 城守产量加成 }。 |
+| heroes | array | 账号全部武将：{ id, name, famous, lead, force, wit, level, exp, expNext 距下一级, salaryPerHour 已随时间缩放, arrears 欠饷, woundedUntil 重伤恢复时刻或 null, guardCityId 正在城守的城或 null, marchingMarchId 正在随行的行军或 null, bonus { atkPercent, defPercent, leadCap }（满编口径）, guardProductionPercent 城守产量加成, loyalty 忠诚度 0..100（v94，只有 29 位在野名将有，其余为 null；30 及以下应标红提醒）, captive 被俘囚禁 { capturedUntil 截止时刻, ransomGold 赎金 } 或 null（v94；被俘时不能出征 / 任城守 / 历练 / 赏赐 / 解雇 / 加点 / 洗点 / 施计，可用 RANSOM_HERO 赎回） }。 |
 | candidates | array | 主城酒馆当前候选（v87 起账号只有一份）：{ id, name, lead, force, wit, cost 招募费, refreshedAt 本批刷新时刻 }；主城酒馆未建为空数组。 |
 | famousClaims | array | 全部名将归属：{ name, sourceLabel 来源人读描述, ownerUsername 当前主人或 null, grantedAt, wildAt 在野名将被获得后的落位 { x, y, level }；未被获得的在野名将与名城 / 黄巾名将为 null（未被获得时不泄露藏身位置）}。 |
 | friendships | array | 结交进度（v54）：{ heroName, favor 好感 0–100, todayLeft 今日还能结交的次数, cost 下次结交花费, lost 已被他人招揽（作废）}。 |
@@ -6763,7 +6766,9 @@ Agent 定期（建议每完成一批事或每小时）把「玩家不在时发
         "dailyLeft": {
           "gift": 3,
           "reset": 1
-        }
+        },
+        "loyalty": null,
+        "captive": null
       }
     ],
     "candidates": [
@@ -6870,7 +6875,9 @@ Agent 定期（建议每完成一批事或每小时）把「玩家不在时发
       "dailyLeft": {
         "gift": 3,
         "reset": 1
-      }
+      },
+      "loyalty": null,
+      "captive": null
     }
   }
 }
@@ -7010,7 +7017,9 @@ Agent 定期（建议每完成一批事或每小时）把「玩家不在时发
       "dailyLeft": {
         "gift": 3,
         "reset": 1
-      }
+      },
+      "loyalty": null,
+      "captive": null
     }
   }
 }
@@ -12706,14 +12715,14 @@ Agent 定期（建议每完成一批事或每小时）把「玩家不在时发
 
 `C→S` 请求-响应 · 需登录后发送
 
-查询已结束赛季的存档：各榜前列（个人榜 power / territory / plunder / arena / starTower）、模型榜（model）与联盟榜前三（alliance，v70，AISLG-185：换季时联盟势力排名前三，条目的 accountId / username 为当时的盟主，value 为势力，并带 allianceId / allianceName / memberCount）。缺省 seasonId 为最近一个已结束赛季；kind 缺省 power；page 从 1 起，每页 20 条。个人榜结果进 entries，模型榜结果进 modelEntries（entries 为空）。total 为该榜总条数。seasons 列出全部已结束赛季（新 → 旧）供选择。指定的 seasonId 不存在返回 INVALID_PARAMS；没有任何已结束赛季时 seasonId 为 null、结果为空。kind 允许值：power / territory / plunder / arena / starTower / model / alliance。
+查询已结束赛季的存档：各榜前列（个人榜 power / territory / plunder / arena / starTower）、模型榜（model）与联盟榜前三（alliance，v70，AISLG-185：换季时联盟势力排名前三，条目的 accountId / username 为当时的盟主，value 为势力，并带 allianceId / allianceName / memberCount）。缺省 seasonId 为最近一个已结束赛季；kind 缺省 power；page 从 1 起，每页 20 条。个人榜结果进 entries，模型榜结果进 modelEntries（entries 为空）。total 为该榜总条数。seasons 列出全部已结束赛季（新 → 旧）供选择。指定的 seasonId 不存在返回 INVALID_PARAMS；没有任何已结束赛季时 seasonId 为 null、结果为空。kind 允许值：power / territory / plunder / arena / starTower / model / alliance / exploration。
 
 **请求字段**
 
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
 | seasonId | number | 赛季编号，缺省为最近一个已结束赛季。 |
-| kind | string | 榜种，缺省 power。允许值：power / territory / plunder / arena / starTower / model / alliance。 |
+| kind | string | 榜种，缺省 power。允许值：power / territory / plunder / arena / starTower / model / alliance / exploration。 |
 | page | number | 页码，从 1 起，缺省 1。 |
 
 **响应 data 字段**
@@ -18767,6 +18776,74 @@ Agent 定期（建议每完成一批事或每小时）把「玩家不在时发
 }
 ```
 
+### op 151 · RANSOM_HERO — 赎回被俘名将（v94，AISLG-228）
+
+`C→S` 请求-响应 · 需登录后发送
+
+只有名将的主人能赎回处于囚禁中的名将（GET_HEROES 的 heroes[].captive 非 null）。赎金 = 2000 × 名将等级，从主人主城扣全额；金币不足返回 INSUFFICIENT_RESOURCES（附 city）且不改任何数据。成功后胜方主城收 50%（向下取整），另一半销毁；名将立刻回归，忠诚度 −20（最低 1）。囚禁已到期（captive.capturedUntil 已过）时返回 HERO_NOT_CAPTURED，名将即将或已经下野。
+
+被俘（只在玩家打玩家时判定；打 NPC / 黄巾 / 竞技场 / 将星塔 / 战场都不判定）：进攻玩家城或野地失败 → 随队名将；守城失败 → 该城城守名将。被俘概率 = 5% + (100 − 忠诚度) × 0.25%（忠诚度 100 为 5%，0 为 30%）。每个账号 7 天内最多被俘 1 名，不管赎没赎回。被俘后囚禁 24 小时：不能出征 / 侦察 / 任城守 / 历练 / 赏赐 / 解雇 / 加点 / 洗点 / 施计（HERO_CAPTURED），不扣俸禄、忠诚度不变，城守职位撤掉。主人 24 小时内可 RANSOM_HERO 赎回；赎金 = 2000 × 名将等级（从主城扣全额），胜方主城收 50%（向下取整），另一半销毁。赎回后名将立刻回归，忠诚度 −20（最低 1）。超时未赎回则名将下野，胜方获得这名将的结交资格（已有资格不重复发）。被俘与赎回分别写 hero_captured / hero_ransomed 事件（主人与胜方各一条），被俘另有全服播报。
+
+名将忠诚度（只有 29 位在野名将有，范围 0..100，招揽时为 100；普通将、名城与黄巾名将的 loyalty 为 null，不受影响）：每 24 小时（基准，随时间缩放）自然下降 10，从招揽时刻起各自结算；赏赐（GIFT_HERO）每次 +10（上限 100）；欠饷期间每小时（基准）额外 −1。忠诚度降到 30 及以下发一次 hero_loyalty_low 事件，回到 30 以上后下次再提醒。忠诚度为 0 时名将下野（行军 / 历练中则等回城或历练结束后再下野）。下野 = 解雇的同一删除路径：武将消失、全服归属清除、城守撤掉、该名将的结交进度全部清空（好感从头算），原野地不变，所有玩家可按现有规则重新结交与招揽；已获得的结交资格保留。全服播报 hero_left（不带坐标）。
+
+**请求字段**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| heroId | string | 必填。被俘名将的 id（GET_HEROES 的 heroes[].id）。 |
+
+**响应 data 字段**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| hero | object | 赎回后的武将视图（captive 为 null，loyalty 已减 20 最低 1）。 |
+| ransom | object | { cost 支付的赎金, taxShare 胜方主城收到的部分, destroyed 销毁的部分 }。 |
+
+**可能错误**：`INVALID_PARAMS`、`HERO_NOT_FOUND`、`HERO_NOT_CAPTURED`、`INSUFFICIENT_RESOURCES`（处置建议见第 4 节）
+
+**Agent 提示**：被俘的名将 captive.capturedUntil 前必须赎，否则下野；赎金 = 2000 × 等级，提前在主城留足金币。下野后名将回到原野地，可以按结交 → 好感满 100 → 招揽的流程重新争取（前主人没有特权）。
+
+**示例**
+
+**赎回一名被俘的名将（赎金 40000，主城金币足够）**
+
+请求：
+
+```json
+{
+  "op": 151,
+  "seq": 91,
+  "data": {
+    "heroId": "5c1e7a2b-9d3f-4b6a-8e10-2f7c9a4d6b35"
+  }
+}
+```
+
+成功响应：
+
+```json
+{
+  "op": 151,
+  "seq": 91,
+  "ok": true,
+  "data": {
+    "hero": {
+      "id": "5c1e7a2b-9d3f-4b6a-8e10-2f7c9a4d6b35",
+      "name": "关羽",
+      "famous": true,
+      "level": 20,
+      "loyalty": 80,
+      "captive": null
+    },
+    "ransom": {
+      "cost": 40000,
+      "taxShare": 20000,
+      "destroyed": 20000
+    }
+  }
+}
+```
+
 ### op 2000 · PUSH_BUILD_STATE — 推送：建筑建造状态变化
 
 `S→C` 服务端推送 · 无 `seq`
@@ -19862,7 +19939,7 @@ NPC 出兵后不再立刻结算：先给被袭击账号发预警（预警提前
 
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
-| reason | string | recruited / dismissed / guard_changed / arrears / salary_paid / wounded / exp_gained / granted / training_started / training_done（历练结束、经验已到账）/ training_cancelled（历练被取消、武将回城，不给经验，v71）/ points_changed（加点或洗点）/ gifted（赏赐）/ friendship_changed（结交进度）。 |
+| reason | string | recruited / dismissed / guard_changed / arrears / salary_paid / wounded / exp_gained / granted / training_started / training_done（历练结束、经验已到账）/ training_cancelled（历练被取消、武将回城，不给经验，v71）/ points_changed（加点或洗点）/ gifted（赏赐）/ friendship_changed（结交进度）/ loyalty_changed（v94，忠诚度自然下降或欠饷扣减，重拉 GET_HEROES 看数值）/ captured（v94，名将被俘）/ ransomed（v94，名将被赎回）/ left（v94，名将下野：忠诚度为 0 或囚禁超时）。 |
 | heroId | string | 涉及的武将 id（guard_changed 撤任时可能为 null）。 |
 | exp | object | reason=exp_gained 时给出 { gained 本次经验, level, leveledTo 升到几级或 null }。 |
 
@@ -20464,13 +20541,13 @@ NPC 出兵后不再立刻结算：先给被袭击账号发预警（预警提前
 
 `S→C` 服务端推送 · 无 `seq`
 
-部队去程结束（到达或撤回）后，如果这一趟新探索了区块，推给本账号一份简报：新探索的区块数、新区块里的东西按类计数（NPC 城分等级、金矿、Lv5 及以上野地、在野名将、其他玩家的城、名城），以及最多 10 个坐标（优先级：名城 > 在野名将 > 金矿 > 玩家城 > NPC 城 > 高级野地）。内容与事件 exploration_report 的 detail 一致，可随时用 GET_EVENTS 回看。存量初始化、开局与城池 / 领地带来的新区块不生成简报；返程不生成。
+部队去程结束（到达或撤回）后，如果这一趟新探索了区块，推给本账号一份简报：新探索的区块数、新区块里的东西按类计数（NPC 城分等级、金矿、Lv5 及以上野地、在野名将、其他玩家的城、名城，v93 起还有未领取的遗迹 relics.byKind），以及最多 10 个坐标（优先级：名城 > 遗迹 > 在野名将 > 金矿 > 玩家城 > NPC 城 > 高级野地）。内容与事件 exploration_report 的 detail 一致，可随时用 GET_EVENTS 回看。存量初始化、开局与城池 / 领地带来的新区块不生成简报；返程不生成。
 
 **data 字段**
 
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
-| report | object | { eventId, marchId, chunks, npcCities: { total, byLevel }, goldMines, highWilderness, wildHeroes, playerCities, famous, cells: [{ x, y, kind, level? }] }。kind = famous / wild_hero / gold_mine / player_city / npc_city / high_wilderness。 |
+| report | object | { eventId, marchId, chunks, npcCities: { total, byLevel }, goldMines, highWilderness, wildHeroes, playerCities, famous, relics: { total, byKind }, cells: [{ x, y, kind, level? }] }。kind = famous / relic / wild_hero / gold_mine / player_city / npc_city / high_wilderness。 |
 
 **Agent 提示**：收到后可按 cells 坐标用 GET_TILE 查看（已探索的地块返回上次看到的情况，带 seenAt）。
 
@@ -20579,6 +20656,8 @@ NPC 出兵后不再立刻结算：先给被袭击账号发预警（预警提前
 | `HERO_BUSY` | （v36，AISLG-114）武将正在随队出征（含返程），不能出征 / 解雇 / 任命城守。 | 等部队回城（marchingMarchId 变回 null）后再操作。 |
 | `HERO_WOUNDED` | （v36，AISLG-114）武将重伤未愈（带队战败后 2 小时基准，随时间缩放），不能出征。 | 等 woundedUntil 过去，或换其他武将。 |
 | `HERO_ARREARS` | （v36，AISLG-114）武将欠饷中（主城金币不足以支付俸禄），不能出征。 | 给主城补足金币，俸禄结算成功后自动恢复（收到 reason=salary_paid 推送）。 |
+| `HERO_CAPTURED` | （v94，AISLG-228）武将被俘囚禁中（24 小时基准），不能出征 / 侦察 / 任城守 / 历练 / 赏赐 / 解雇 / 加点 / 洗点 / 施计。 | 主人用 RANSOM_HERO 在囚禁截止前赎回；超时则名将下野，不必再操作。 |
+| `HERO_NOT_CAPTURED` | （v94，AISLG-228）武将未被俘，或囚禁已到期（即将下野），不能赎回。 | 用 GET_HEROES 查看 heroes[].captive；为 null 即无需赎回。 |
 | `HERO_TRAINING` | （v54，AISLG-144）武将正在历练中，不能出征 / 任城守 / 解雇 / 加点 / 洗点 / 再次历练（赏赐不受限）。 | 等历练结束（train_until 过去，经验到账并收到 reason=training_done 推送）后再操作。 |
 | `HERO_POINTS_INSUFFICIENT` | （v54，AISLG-144）分配点数超过自由点数（附 freePoints）。 | 先升级获得点数（每级普通将 3、名将 5），或减少分配数量。 |
 | `HERO_NOTHING_TO_RESET` | （v54，AISLG-144）武将没有已分配的点数（属性等于初始值），洗点无意义。 | 先加点再洗点；无需洗点时不必调用。 |
@@ -20692,7 +20771,7 @@ NPC 出兵后不再立刻结算：先给被袭击账号发预警（预警提前
 | `MOVE_CITY_TILE_TAKEN` | （v91，AISLG-220）目标格在判定与落库之间被别人抢先占走（并发）。令与坐标都未改动。 | 重新 GET_WORLD_MAP 选一块空野地后再发起迁城。 |
 | `MOVE_CITY_TOO_CLOSE` | （v91，AISLG-220）目标离其他账号的城池格（分城、名城含在内）不足 3 格（Chebyshev 距离）。自己的城不受此限。 | 选离他人城池至少 3 格的空野地；随机迁不受此限。 |
 | `MOVE_CITY_NO_SPACE` | （v91，AISLG-220）随机迁城时世界中已没有可选的空野地。 | 改用指定坐标迁城（高级迁城令）选一块空野地，或等世界有空地后再试。 |
-| `TILE_UNEXPLORED` | 该地块在战争迷雾中未探索，且不在任何视野来源（城池 / 领地 / 行军 / 盟友城池格）覆盖内，服务端不返回它的任何信息（v92，AISLG-224）。仅在 fog_enabled 开启时出现。 | 先派斥候或部队去这个方向探索（派去未探索坐标的出征本身允许，盲打时前端应提示“目标在迷雾中”）。也可以改查已探索的格子。 |
+| `TILE_UNEXPLORED` | 该地块在战争迷雾中未探索，且不在任何视野来源（城池 / 领地 / 行军 / 同盟或友盟的城池格）覆盖内，服务端不返回它的任何信息（v92，AISLG-224）。仅在 fog_enabled 开启时出现。 | 先派斥候或部队去这个方向探索（派去未探索坐标的出征本身允许，盲打时前端应提示“目标在迷雾中”）。也可以改查已探索的格子。 |
 | `MOVE_CITY_TILE_UNEXPLORED` | 高级迁城令（指定坐标）的目标格未探索，也不在实时视野内，无法指定为迁城目标（v92，AISLG-224）。随机迁城令不受影响。 | 先探索目标区域（派斥候或部队去那里），或改用随机迁城令。 |
 | `MOVE_CITY_ATTACK_LOCK` | （v91，AISLG-220）指定坐标迁城后 12 小时内，这座城的掠夺 / 占领 / 侦察 / 派协防（以及其他攻击类出征）被拒；响应附 retryAfterSeconds。运输、调兵、增援自己名下野地与召回不受限。 | 等待 retryAfterSeconds 之后再出征打别人；期间可以正常运输、调兵与增援。 |
 | `INTERNAL` | 服务端内部错误。 | 可稍后重试同一请求；持续出现时向运营方反馈。INTERNAL 可能出现在任何请求的响应中。 |
@@ -22284,7 +22363,7 @@ LOGOUT 吊销本连接登录所用的令牌，服务端随即关闭连接（clos
 - 只加不改：已发布的协议号、字段与错误码只新增、不删除、不改变类型与语义。
 - 新增字段不视为破坏兼容：消费方应容忍请求与响应中出现文档未列出的字段。
 - 必须破坏语义时启用新的协议号承载新行为，旧协议号保留原语义直至正式公告下线。
-- 协议版本随对外协议内容的每次变化递增；当前为 92。
+- 协议版本随对外协议内容的每次变化递增；当前为 95。
 - 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.2",
+  "version": "0.2.3",
   "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",