# sanguosha

**Repository Path**: TXandJL/sanguosha

## Basic Information

- **Project Name**: sanguosha
- **Description**: sanguosha -简洁版
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-19
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 三国杀 · 精简版（2~8 人在线）

与斗地主同架构的 PHP 在线三国杀：**1V1 / 2V2 对战 + 4~8 人身份局**。
PHP + 文件状态 + 轮询，零数据库、零新环境，整个文件夹丢进站点根目录就能跑。

---

## 一、模式

| 模式 | 人数 | 阵营 |
|---|---|---|
| 1V1 对战 | 2 | A 队 vs B 队 |
| 2V2 对战 | 4 | 对角同队（座位 0/2 一队，1/3 一队） |
| 身份局 4 人 | 4 | 1 主公 1 忠臣 1 反贼 1 内奸 |
| 身份局 5 人 | 5 | 1 主公 1 忠臣 2 反贼 1 内奸 |
| 身份局 6 人 | 6 | 1 主公 1 忠臣 3 反贼 1 内奸 |
| 身份局 7 人 | 7 | 1 主公 1 忠臣 3 反贼 2 内奸 |
| 身份局 8 人 | 8 | 1 主公 2 忠臣 4 反贼 1 内奸 |

- 身份随机洗牌分配，主公开局公开，其余暗置；主公先手
- 胜负：主公死 → 反贼胜（若场上只剩内奸则内奸胜）；反贼+内奸全灭 → 主忠胜；组队模式一方全灭判负
- 击杀反贼摸 3 张；主公误杀忠臣弃光手牌装备
- 阵亡亮身份，不影响对局（托管代打）

## 一点二、机器人（电脑玩家）—— 一个人也能开局

**所有 7 个模式**在等待页都能加电脑：房主点「＋ 添加电脑」加一个，或点「一键补满（+N）」直接坐满，
人数够了就能开局（1V1 加 1 个、8 人局加 7 个，机制完全一样）。**只有房主能加/删，只有开局前能动。**

| 行为 | 规则 |
|---|---|
| 加电脑 | `addbot {n}`：加 n 个，**自动截断**到坐满（要 9 个也不会多塞）；已满报「座位已满」 |
| 删电脑 | `delbot`：移除**最后一个**电脑（等待页每个电脑行尾有「移除」）；没有电脑时报错 |
| 开局后 | 加/删一律拒绝（座位表与角色/手牌按下标绑定，中途挪人整局错位） |
| 真人加入满员房 | 末尾是电脑 → **顶替**它（返回 `swapped:true`）；没有电脑可顶替才算真满 |
| 房主离开 | 房主权限交给**下一个真人**（交给电脑 = 这间房再也开不了局） |
| 再来一局 | 电脑留在原座位继续打 |

机器人是**一等座位**：与真人共用同一份座位结构（`new_seat()`），只多一个 `bot:true`。因此

- **永远代打**：机器人不轮询、没有心跳，`sgs_seat_hosted()` 对它恒为真（**先于**手动托管判断放行）
- **有「思考」节奏**：两次动作之间隔 `SGS_BOT_SEC` 秒（默认 1）——否则一次轮询就把整个回合闪完，
  玩家看不见它出牌。真人手动托管**不受**这个节奏限制（人开的托管要立刻见效）
- **不会替真人出牌**：没托管、没掉线的真人永远被等（只有掉线/手动托管才由 AI 接）
- **自动选将**：`phase=picking` 里机器人自己从候选池挑（日志写「自动选择」），真人只需要选自己那张
- **uid 不外泄也冒充不了**：`seats[i]` 不下发 uid；`seat_of()`（api.php）与 `sgs_public()`（engine.php）
  找座位时**都跳过机器人座位**——否则猜到 uid 就能读到电脑手牌、替它出牌。**两处都要跳过**：
  `sgs_public` 并不经过 `seat_of`，它自己又扫了一遍 uid → `mySeat`（漏了那条会下发电脑手牌）
- `SGS_BOT_SEC=0` 可关掉节奏（回归测试用，保证确定性）；节奏本身由 `tests/sgs-bot.php` B 组断言

> ⚠️ 「结束出牌」**不等于**回合结束：手牌超过体力上限时引擎会转进**同一个人的**弃牌阶段，
> 那时 `turnIdx` 仍是自己、`pending` 仍是 null。所以"回合有没有交出去"只能看 `turnIdx`，
> "机器人有没有真的开回合"看日志里那句 `—— 电脑·甲 的回合 ——`（`sgs_start_turn` 无条件写）。
> 写测试断言时把这两个信号搞混，会得到一条**恒真**的假断言（详见文末批次记录）。

## 一点三、电脑玩家「怎么想」—— AI 决策三层

电脑与托管共用同一套决策（`sgs_ai_*`，全在 `engine.php`）。分三层，后一层只在前一层给出的
候选里挑，**不做随机平手**：

| 层 | 函数 | 干什么 |
|---|---|---|
| ① 阵营 | `sgs_ai_side` / `sgs_ai_hostility` | 我是哪边的、他是敌是友（`0` 自己人 / `1` 中立 / `2` 明确敌人） |
| ② 价值 | `sgs_ai_threat` / `sgs_ai_card_value` | 谁最该打（残血、能斩、主公枢纽）、哪张牌最该留 |
| ③ 决策 | `sgs_ai_turn` / `sgs_ai_choice` | 出什么牌、给谁、要不要响应 |

**① 阵营 —— 反贼不再互相残杀**

- 身份局按身份分边：主公/忠臣 = `loyal`、反贼 = `fan`、内奸 = `nei`；组队模式按 `team` 比
- 内奸：**谁势大打谁**（反贼多就打反贼、忠臣多就打忠臣），主公**留到最后**——只有
  `(反贼数 + 忠臣数) === 0` 才把主公当敌人；反贼全灭后主公/忠臣必须把内奸升级为敌人，
  否则收尾变成"主公单方面挨打"，一局跑到步数上限也打不完
- ⚠️ 判"是不是主公"必须看 `role`（`=== 'zhu'`）：`sgs_ai_side()` 把主公归进 `loyal`，
  写成 `$b === 'zhu'` **永远不成立** → 内奸开局就咬主公（A4/A5/B7 就是这么抓出来的）

**② 目标 —— 有理由，且不掷骰子**

`残血 × 3` + 能斩 `+24` + 主公枢纽 `+12` + 明确敌人 `+4`；同分**按座位序取第一**。
旧版平手时 `random` 挑一个 → 一会儿打这个、一会儿打那个，观感就是"没有想法"。

**③ 出牌 —— 顺序有讲究，每步有门槛**（不值得就不出）

桃（受伤就吃）→ 无中生有/五谷（纯赚，先摸牌再决定）→ 装备（空位必填，武器按射程+技能比大小换）
→ 武将主动技（苦肉/裸衣/据守）→ 控制（乐给行动力强的、兵粮给手牌多的、拆优先拆武器、
顺手限距离 1、借刀只借敌人的刀）→ 输出（桃园只在"我方伤得更重"时开；杀优先射程内能斩的；
决斗要有第二张杀撑着或对手残血）。

**AOE（南蛮/万箭）三道门槛**：① 敌人不比队友少；② 自己手上有对应响应牌或血厚；
③ **队友没人只剩 1 血** —— 这一张的 1 点伤害对残血队友就是致命伤。③ 只看体力（明牌），
不看手牌，**不算偷看**；旧版只比人数，敌 3 友 3 时照样开，一刀下去顺手把自己人带走。

**响应的取舍**（`sgs_ai_choice`）

- 桃：自救必出；救别人只救自己人，**内奸还要保主公**（主公一死反贼就赢）；自己只剩一张桃
  且血量告急时留着
- 无懈：**三态取值** —— `-1` 生效有害就掐掉、`+1` 被掐掉的正是我们想要的结果就救回、
  `0` 与我们无关（无中生有这种小利）就省着不花。统一成一个式子：
  `$want = ($parity === 0) ? ($val < 0) : ($val > 0)`
- 五谷：从亮牌池里挑**手牌价值最高**的那张；贯石斧/青龙偃月刀/麒麟弓只在目标是敌人且
  代价划算时才发动

**暗牌不偷看**：装备区是明牌（按价值挑/拆），手牌只能随机抽 —— `sgs_ai_pick_resolve()` 里
"有装备挑装备、没装备才随机抽手牌"就是这个约束。棋子之间**只能看公开信息**（体力、手牌数、
装备、判定区），这条纪律决定了 AOE 门槛③只能看体力。

## 一点五、武将（33 名 / 37 技能，开局自选）

魏国：曹操、司马懿、夏侯惇、张辽、许褚、郭嘉、甄姬、曹仁、夏侯渊
蜀国：刘备、关羽、张飞、诸葛亮、赵云、马超、黄月英、黄忠、魏延
吴国：孙权、甘宁、吕蒙、黄盖、周瑜、大乔、陆逊、孙尚香、周泰
群雄：吕布、华佗、貂蝉、小乔、张角、于吉

**开局选将**：房主点「开始游戏」后进入 `phase=picking` 的选将阶段——

- 系统给**每名玩家随机发 5 名候选武将**（体力/势力/性别/技能都显示在选将面板里）
- **所有玩家的候选池互不重复**（洗牌后按座位切片），所以无论怎么选，**场上武将必然全局唯一**
- 每人点选 1 名 → 点「确认选择」（双击卡片可直接确认）；全房选满后自动开打，主公先手
- 别人选走的武将会实时显示在面板下方，序号进度 `已选 x/y` 可见
- 选将超时 30s（`SGS_PICK_SEC`）→ 系统自动选（挑候选里体力最高的）；
  **掉线/退出或开了托管的座位立即代选**，绝不会被一个人卡住整局
- 候选数受武将总量约束：33 名武将时 **1~6 人局每人 5 名，7~8 人局每人 4 名**（8×5=40 > 33）
- 体力在选定时定稿：按武将体力，身份局主公 +1（1v1/2v2 不加）

| 类型 | 武将（技能） |
|---|---|
| 视作类 | 关羽·武圣（红牌当杀）、赵云·龙胆（杀闪互换）、华佗·急救（红牌当桃）、甘宁·奇袭（黑牌当拆桥）、于吉·蛊惑（声明基本牌/普通锦囊，质疑真假） |
| 攻防类 | 张飞·咆哮（无限杀）、马超·铁骑（杀后判定为红锁闪）、黄忠·烈弓（目标手牌≥你体力或≤你攻击范围则不可闪）、吕布·无双（杀需 2 闪、决斗对方需 2 杀）、夏侯渊·神速（限一次弃 1 张当杀，不计次数） |
| 摸牌类 | 周瑜·英姿（摸牌+1）、张辽·突袭（摸牌改为夺两家各 1 张）、甄姬·洛神（**回合开始先问要不要发动，黑色判定牌本身到手并可继续，红色结束，上限 8**）、黄月英·集智（用普通锦囊摸 1，延时锦囊不触发）+奇才（锦囊无距离）、曹仁·据守（**结束阶段询问：摸 3 张，然后跳过自己下一个回合；摸到的牌本回合用不出去**）、黄盖·苦肉（可多次：摸 2 张失 1 体力）、许褚·裸衣（限一次弃 1 张，本回合伤害+1） |
| 回合类 | 吕蒙·克己（本回合未出杀免弃牌）、貂蝉·闭月（回合结束摸 1）、孙权·制衡（限一次弃任意张换等量）、刘备·仁德（限一次送牌，给≥2 张且已受伤回 1 点） |
| 受伤/濒死类 | 曹操·奸雄（获得造成伤害的牌）、司马懿·反馈（拿伤害来源 1 张牌）、郭嘉·遗计（每 1 点伤害摸 2）、夏侯惇·刚烈（判定非红→来源弃 2 张，不足则受 1 伤）、周泰·不屈（濒死翻牌点数不同则回到 1 点）、小乔·天香（弃红桃转移伤害给他人，该角色摸 1） |
| 响应/防御类 | 诸葛亮·空城（空手不可被杀/决斗）、陆逊·谦逊（不能被顺手牵羊/乐不思蜀指定）+连营（失去最后手牌摸 1）、大乔·流离（弃 1 张牌把杀转移给他人）、孙尚香·结姻（限一次弃 2 张，与受伤男性各回 1 点）+枭姬（失去装备摸 2）、张角·雷击（出闪判定黑桃→来源受 2 伤）+鬼道（黑牌替换判定牌，原牌归手牌）、魏延·狂骨（对距离 1 以内造成伤害后回 1 点） |

- 体力按武将（3~4），身份局主公 +1；武将与技能对所有人公开（选定时即公开）
- 视作技能前端出按钮：选中红牌出「当【杀】使用」/「当【桃】使用」/「当【过河拆桥】使用」，
  于吉·蛊惑则声明基本牌/普通锦囊（真假只看牌名，假时质疑者摸牌、真时质疑者掉血）
- 出牌阶段主动技按钮（都受服务端回合标记约束，用过即消失）：
  孙权「制衡」/ 刘备「仁德」/ 孙尚香「结姻」/ 黄盖「苦肉」；
  许褚「裸衣」与夏侯渊「神速」需先选中一张手牌
- 结束阶段询问技：曹仁「据守」——弃牌结束后弹「发动 / 不发动」，
  发动则摸 3 张并跳过自己**下一个**回合（摸到的牌本回合用不出去）
- 多选类技能统一手势：点手牌多选 → 再点目标座位 → 「确认」（制衡只需选牌；仁德要选牌+目标；
  结姻固定 2 张牌 + 一名已受伤男性角色）
- 流离：成为【杀】目标时先弹面板问「发动【流离】」——选了就点 1 张手牌 + 一名其他角色转移；
  放弃则回到正常【杀】响应（出闪或挨打）
- 目标合法性同步服务端：空城（手牌为 0 的诸葛亮不能被【杀】【决斗】指定）、
  谦逊（陆逊不能被【顺手牵羊】【乐不思蜀】指定）、结姻限男性且已受伤，不合法座位置灰并写明原因
- 受伤类技能仅存活时触发；刚烈的反制伤害不再连锁触发其他受伤技（防死锁）
- 托管 AI 会使用视作牌（武圣当杀/急救当桃/龙胆互换）与主动技（苦肉 / 裸衣 / 据守）

**技能「看得见」（服务端权威 + 前端显性反馈）**

技能判定 100% 在服务端（`sgs_skill()` / `sgs_convert()`），前端只负责展示。为了让"技能到底有没有生效"
一眼可见（而不是只能翻战斗记录数牌），牌桌上有四层反馈：

- **武将徽标 + 技能芯片**：顶栏武将名旁列出本人技能，每个座位卡下方列出该玩家的技能；
  悬停芯片显示技能说明
- **被动技能常驻提示**：出牌区上方固定一条「**被动技能（自动生效）**」，列出本人所有非主动技能
  （英姿 / 奸雄 / 遗计 / 集智 / 奇才 / 空城 / 谦逊 / 连营 / 枭姬 / 狂骨 / 鬼道 / 天香 /
   刚烈 / 反馈 / 铁骑 / 烈弓 / 无双 / 咆哮 / 克己 / 闭月 / 不屈 …）及其说明——
  这类技能没有按钮，会在对应时机自动触发
- **一问一步的「过程技能」**：洛神这类会连着做很多步的技能，**不在回合开始一次性结算**，
  而是每做一步就回到询问（按钮写清已得几张），玩家随时收手 —— 见下方「洛神为什么改成逐次询问」
- **发动飘字**：任何人触发技能时，牌桌右上角弹出「XX 发动【技能名】」气泡，对应座位卡同时高亮闪一下；
  由日志里 `发动【X】` 的单调 `seq` 增量驱动，只播**新**日志、不重播历史
- **选将面板标注**：候选武将的每个技能后面直接标 `主动` / `被动`，选人前就知道要不要手动点

> 被动提示的判定按技能表 `ACTIVE_SK` 过滤，**不按「按钮当前是否可点」判断**：
> 黄盖的【苦肉】在 1 血时按钮会隐藏，但它依然是主动技（早期版本据此把它错标成被动）。

## 二、牌库（116 张精简包）

| 类别 | 牌 |
|---|---|
| 基础 | 杀 ×30、闪 ×22、桃 ×10 |
| 锦囊 | 无中生有、决斗、过河拆桥、顺手牵羊、南蛮入侵、万箭齐发、桃园结义 |
| 锦囊·无懈 | 无懈可击 ×4（任意锦囊生效前全场依次询问；无懈也能被无懈反制） |
| 锦囊·延时 | 乐不思蜀 ×3（判定 ♥ 失效，否则跳过**出牌阶段**）、兵粮寸断 ×3（判定 ♣ 生效，跳过**摸牌阶段**）——两者均**无视距离**（2026-09-21 改，U1c 断言守住）、闪电 ×2（判定 ♠ 为 3 点雷电伤害，否则**移至下家**判定区） |
| 锦囊·其他 | 借刀杀人 ×2（两个目标：持刀者 → 被杀者；令其出【杀】，否则交出武器）、五谷丰登 ×2（亮出与人数等量的牌，每人依次挑一张） |
| 武器 | 诸葛连弩（不限杀）、青釭剑（无视八卦）、青龙偃月刀/贯石斧/方天画戟/麒麟弓（攻击范围 2~5） |
| 防具/马 | 八卦阵 ×2（放弃出闪时自动判定，红色视作闪；判定牌会亮给全场）、+1 马 ×3、-1 马 ×3 |

延时锦囊走**判定区**（`seats[i].judged`，座位卡"其他"栏画单字徽标 乐 / 兵 / ⚡，全名进 title）：
回合开始的判定阶段逐张结算，每张判定牌都广播给全场，且**每张生效前全场可问【无懈可击】**
（被抵消 = 移出判定区进弃牌堆）。
⚠️ **无懈的时机是"判定牌翻开、效果即将落实"的那一刻**（2026-09-22 修正）：
置入判定区的瞬间还没有任何效果发生，那时就问无懈 = 让全场为一件没发生的事表态。
`sgs_wuxie_offer()` 只在 `sgs_delay_step()` 里调用；置入时只写日志
「【乐不思蜀】置入 … 的判定区（回合判定时才会结算）」。
旧的两条 effect 死路径 `delay_placed` / `delay_place_end` 已删（判定阶段被抵消的收尾在 `delay_after`）。

## 三、规则实现

- 回合：**判定**（判定区的延时锦囊逐张结算；每张前全场可问【无懈可击】）→ 摸 2 张
  （【兵粮寸断】生效则跳过）→ 出牌（每回合限 1 杀，连弩不限；【乐不思蜀】生效则跳过）
  → 弃牌（手牌上限 = 当前体力，可多选一次弃完）
- 状态机：`waiting → picking（选将）→ playing → finished`；选将阶段不产生 pending / turnSub，
  只接受 `pickhero`；候选池只发给本人（别人的候选是秘密，选定后武将才公开）
- 距离：存活角色环上最短距离；-1 马进攻减距、+1 马防守加距；杀受武器攻击范围限制
- 目标合法性：前端只允许点合法目标（【顺手牵羊】距离必须为 1、【杀】须在攻击范围内），
  不合法的座位置灰并显示距离/原因，点击会提示原因而不再静默失败；座位卡上显示「距 N」
- 到手反馈：牵羊/五谷等获得的牌会弹「获得【X】」提示并在手牌区高亮 4 秒
- 响应链：杀→闪、决斗→轮流出杀、南蛮→杀、万箭→闪、濒死→从濒死者起顺位求桃
- 拆/牵羊：目标有 2 张以上可选牌时**由出牌者亲自选**（手牌面朝下、装备正面显示）；
  只有唯一一张时直接结算；开启托管时由 AI 随机选（不会卡住）
- 手动托管：顶栏「托管」按钮开关（AI 立即代打，跨回合持久；亲自操作或重连自动取消）
- 打牌特效（**全场每个人都能看清「谁 对谁 出了什么」**）：任何人出牌/响应（含闪/杀/救桃）时，
  所有玩家的屏幕上同时出现三样东西，持续约 2.8s：
  ① **顶部横幅**「<出牌者> 对 <目标> 使用【牌名】」一行大字（响应类改为「<出牌者> 打出【闪】响应 <对方>」，
     视作牌额外注明「（用【实体牌】当）」，错过牌面也不会漏看）；
  ② 牌桌中央弹出**大牌面**（牌名 + 花色点数 + 指向文字，红/黑分色）；
  ③ 出牌者 → 每个目标画**红色虚线箭头**（虚线流动），出牌者座位橙色脉动、目标座位红色脉动；
  群体锦囊（南蛮/万箭/桃园）对每个目标各画一条箭头
- 掉线托管：对局中掉线/退出（15s 无心跳）的座位自动由 AI 代打，对局不卡住
- 真人玩家不操作不会被判超时，可以无限期思考
- 八卦阵在玩家选择"放弃"时自动发动判定（青釭剑无视）；**判定牌本身会广播给全场**
  （`fx.skill='八卦阵'` + `fx.ok`，成败都发），且响应面板会提前写明「放弃=发动【八卦阵】」。

## 三点五、界面

- 战斗记录默认收起，顶栏「战斗记录」按钮点击展开左侧抽屉（新日志有未读数字提示，Esc 关闭）
- 牌桌中央改为局况卡片（牌堆剩余 / 局数 / 模式 / 当前回合）
- 对局结束 → 结算面板提供「查看战斗记录」复盘；抽屉内「返回结算」可回到结算面板
- 退出房间入口四处统一：顶栏、等待房间弹窗、结算弹窗、结算后操作区（确认后回大厅，对局中退出由托管接替）
- 手机端（≤980px）顶栏自动收纳：隐藏模式芯片/邀请按钮，按钮文案缩短（记录 / 退出），防溢出
- 技能可视化：座位卡下方的技能芯片、出牌区上方的「被动技能（自动生效）」条、
  右上角的「发动【X】」飘字（座位同步高亮），选将面板里技能带 `主动`/`被动` 标记
- 打牌可视化：顶部「谁 对谁 出了什么」横幅 + 中央大牌面 + 指向箭头 + 出牌者/目标双向高亮
- 手牌**平铺**显示（相邻只留 6px 缝），一行放不下才自动折叠（见第九节）；
  牌面文字一律不换行（4 个字的「过河拆桥」、5 个字的「青龙偃月刀」都缩字号单行）；
  提示条独占一行并可折行，浮层提示（toast / 技能飘字 / 中央牌面副标）都有最大宽度
- **对手区 = 环形三段**（顶排横排 + 左列竖排 + 右列竖排，中央单列一格留给战场，
  见第十二点五节）；座位卡按需求精简成五层信息

## 三点六、身份标记（「我判·反贼」）—— 只有自己看得见

身份局里除了主公，别人的身份都是暗的。玩家心里其实一直在猜（"这人肯定反贼"），
但猜完没地方放，过两轮就忘了。座位卡上那个 `?` 就是放判断的地方：

- 点座位卡上的 **`?`** → 弹出小浮层，选 **忠臣 / 反贼 / 内奸**（已标过的还能「清除」）
- 选完 `?` 变成 **`我判·反贼`**（**虚线**框 —— 真实身份徽标是实线，两者会同屏出现，必须一眼可分）
- **不占任何操作**：点身份徽标不会把这个人选成目标（身份不明时正是要打他的时候）。
  这条由 `sgs-ui-wiring.php` ★X6（分支顺序）与 `sgs-ui-runtime.js` U9b（点完不该出现 `picked`）双向钉住
- 身份一公开（阵亡亮身份 / 终局 / 主公本来就亮）→ 我的判断**自动收起**：
  真身份才是准的，同屏出现「真身份 + 我的猜测」会看混
- **开新局（第 N 局变化）自动作废**：身份重新洗牌，留着上一局的推断只会误导自己

### 为什么不做服务端存储

「其他人看不到」这件事，**只有本地存储能靠结构保证**。做服务端存储就得在**每一个**下发出口
加过滤（公开状态 / 旁观 / 聊天 / 日志 / 结算 / 断线重连…），漏一处就是全场标记泄露；
放 `localStorage` 则从根上不存在「别人能看到」这条路径。

- 键：`sgs_marks:<房间号>:<我的 uid>`。**uid 是必须的** —— 少了它，同一台机器换个人登录
  就能读到上一个人的推断；少了房间号会串到别的房间
- 值：`{"r": <第几局>, "m": {"2": "fan"}}`；`r` 就是上面那条「开新局作废」的判据
- 写入口**只有** `localStorage.setItem(markKey())`：标记**不产生任何请求**
  （U3c 直接数请求：标记前后 `calls` 数组必须一模一样）

**测试**：`sgs-ui-wiring.php` X 组 15 条（含 ★X11：`engine.php` / `api.php` 里**连 `marks`
这个词都不许出现**；★X12：标记没有 act/api 出口）+ `sgs-ui-runtime.js` U 组 23 条
（点 `?` 开浮层 / 只写本地 / 换 uid 读不到 / 开新局作废 / 身份公开后收掉 / 点徽标不误选目标 /
点别处收起浮层）。

**Edge 真实浏览器冒烟（19 断言，全绿）**：DOM 桩测不到 CSS 与真实点击 —— 补了一趟
headless Edge：点真实的 `?` → 断言浮层**真的弹出且贴在徽标正下方**（boundingBox 对比）、
「我判·反贼」的 `borderTopStyle === 'dashed'`（computedStyle 实测）、
**真实 HTTP 的 state 响应原文里搜不到 `marks` / `我判`**（网络层的防泄露终审）、
刷新重进房间后标记还在（localStorage 持久）、全程零控制台报错。

## 四、部署（宝塔 / IIS 通用）

1. `sgs/` 整个目录上传到站点根目录（`tests/` 可不上传）
2. `data/` 权限 777（含 .htaccess / web.config 防直读）
3. 打开 `http://你的域名/sgs/` → 选模式 → 建房 / 输房间号加入

要求：PHP 7.0+（`random_int`），无需任何扩展、无需数据库。

## 五、文件清单

```
sgs/
├── index.html        前端（大厅 + 选将面板 + 牌桌 + 聊天抽屉，含全部 CSS/JS）
├── api.php           后端路由（建房/加入/开局/选将/出牌/响应/选牌/弃牌/聊天/再来一局
│                     + 制衡/裸衣/据守/神速/仁德/结姻/苦肉/托管 + 加电脑/移除电脑）
├── engine.php        核心引擎（选将阶段 + 回合状态机 + 响应链 + 伤害/濒死/死亡 + 37 技能
│                     + AI 托管/机器人代打 + 机器人思考节奏）
├── heroes.php        武将库（33 名武将定义 + 候选池发放 + 自动选将）
├── cards.php         牌库（100 张，顺序随机）
├── data/             房间状态（需可写）
└── tests/            开发用（可不上传）
```

## 六、本地/测试

```
# 极速全托管（测试用，0 秒超时）
SGS_PLAY_SEC=0 SGS_RESP_SEC=0 php -S 127.0.0.1:8921 -t .
SGS_ORIGIN=http://127.0.0.1:8921 node tests/sgs-flow.js        # 端到端 94 断言

# 10 秒节奏服务器（交互类测试用）
SGS_PLAY_SEC=10 SGS_RESP_SEC=10 php -S 127.0.0.1:8923 -t .
node tests/sgs-ring.js       # 顶栏托管按钮稳定性    12 断言
node tests/sgs-discard.js    # 弃牌多选              10 断言
node tests/sgs-pick-ui.js    # 拆/牵羊选牌面板       11 断言
node tests/sgs-hp.js         # 血条可读性            14 断言

# 1 秒节奏服务器（对局快速打完，验证结算流程）
SGS_PLAY_SEC=1 SGS_RESP_SEC=1 php -S 127.0.0.1:8925 -t .
node tests/sgs-log.js        # 战斗记录折叠/复盘     29 断言
node tests/sgs-leave.js      # 退出房间入口          20 断言（含窄屏顶栏可见性）
node tests/sgs-duel-ui.js    # 决斗面板/掉血/回合权  18 断言（需 20s 节奏服务器）
node tests/sgs-qian-ui.js    # 牵羊目标合法性/到手反馈 25 断言（需 60s 节奏服务器）

# 引擎单测（无需服务器）
php tests/sgs-pick.php       # 拆/牵羊选牌逻辑       29 断言
php tests/sgs-dying.php      # 濒死求桃/低血弃牌/链恢复 55 断言
php tests/sgs-qian.php       # 牵羊/拆桥到手与落点/守恒/全模式压力 88 断言（含牌张守恒 + D 组判据定场景）
php tests/sgs-duel.php       # 决斗引擎逻辑          20 断言
php tests/sgs-hero.php       # 第一批 17 武将技能     70 断言（含洛神逐次询问）
php tests/sgs-hero2.php      # 第二批 16 武将技能     89 断言（含开局发牌/主公+1 严格契约、33 武将 8 人局压力）
php tests/sgs-pickhero.php   # 开局选将（候选/去重/超时/掉线）62 断言
php tests/sgs-bot.php        # 机器人（电脑玩家）36 断言
                             #   恒托管 / 思考节奏（1 秒内只动一次，真人手动托管不受限）/
                             #   全机器人 4 人局与 8 人局能自己打完且牌张守恒（116/116 唯一）/
                             #   机器人自动选将 / 混编局一定停在真人面前（日志无「超时托管」）
php tests/sgs-ai.php         # 电脑玩家「决策质量」71 断言（详见「一点三」与文末批次记录）
                             #   A 阵营（反贼不互殴/内奸维持平衡）/ B 目标排序（残血、能斩、不随机）/
                             #   C 出牌（顺序、门槛、AOE 队友残血不开、黑名单不空转）/
                             #   D 弃牌选牌（按价值升序、装备是明牌挑最好的）/
                             #   E 响应（救自己人/不救敌人/无懈三态/五谷挑最值）/
                             #   F 全机器人局宏观：**同阵营零攻击** + 动作数 ≥ 15（防空转）+
                             #     4/8 人局都能打完、不靠拖步数上限、全程牌张守恒
php tests/sgs-fx.php         # 打牌特效广播 + 八卦阵判定牌/失败仍可出闪 + 过程队列/洛神逐次判定 + **牌桌文案（动词/归属/无双）** + **五张新锦囊（U 组：延时判定/跳过阶段/闪电传递/借刀两分支/五谷亮牌池/无懈首轮不问使用者）** 227 断言
php tests/sgs-ui-wiring.php  # 前端接线契约（无需浏览器）305 断言
                             #   data-act 都有分发分支 / act() 都是真实路由 /
                             #   主动技都有入口 / canConvert 覆盖全部视作 / 回合标记约束 /
                             #   选将面板接线（候选渲染、倒计时、pickhero 路由、选将期托管）/
                             #   加电脑（房主/名额/截断/开局后拒绝）/ 前端加电脑与移除入口 /
                             #   ★seat_of 与 sgs_public 都要跳过机器人 /
                             #   ★state.n = 模式需要人数 / ★机器人恒托管先于 hostOn /
                             #   四处动作点都接了机器人节奏 / 加电脑会截断到坐满
                             #   手牌不再闪的三个前提（高亮到期、动画只播一次、滚动位置保留）/
                             #   技能可见化（ACTIVE_SK 集合与武将表一致、主动技都有入口、
                             #     被动提示按 ACTIVE_SK 过滤、飘字挂在 sync 上、#skflash 先于 <script>）
                             #   打牌特效接线（CSS 的 display:none 靠 .on 类点亮、playFx **不得**
                             #     用 style.display='' 、feedFx 水位线 act/poll 共用、
                             #     render 后重贴高亮、消失时清牌面/横幅/箭头/高亮）
node tests/sgs-hand-render.js # 手牌渲染逻辑（无需服务器/浏览器）31 断言
                             #   抽出 index.html 真实的 cardHTML 与清理片段执行：
                             #   高亮到期失效 / 入场动画每张牌只播一次 / 离手再得能重新高亮
node tests/sgs-ui-runtime.js  # **在 DOM 桩里跑真实前端逻辑**（无需浏览器）293 断言
                             #   含过程队列播放（多步/积压加速）、技能宣告 vs 亮牌两种牌面、洛神面板
                             #   等待页加电脑（行渲染/🤖/一键补满的 n/未满时开局禁用/非房主看不到）/
                             #   牌桌电脑徽标与「电脑思考中…」（不能写成"托管代打"）
                             #   从 index.html 抽出真实 <script> 体，桩掉 document/window/
                             #   localStorage/fetch/setInterval 后用 new Function 挂载，再驱动
                             #   ui.clickCard/clickAct/poll/flash/acts/hand/seats/pick/meLine：
                             #   视作类按钮 / 目标提示 / 主动技入口与用后消失 / 苦肉血限 /
                             #   弃牌类技能 / 阶段约束 / 响应阶段 / 徽标与浮窗 / 选将面板 /
                             #   技能可见化（徽标、被动提示、发动飘字、选将标注）
                             #   打牌特效（层真的可见、横幅文案、视作牌、箭头条数、双向高亮、
                             #     同 seq 不重播、进房不补播历史、~2.8s 自动消失）
                             #   加 --dump <state.json> 可对着真实房间快照跑（排查线上问题），
                             #   会把状态里带的 fx 当作新广播渲染，并打印横幅/牌面/箭头条数

# 真实 API 回归（各自独立端口）
SGS_PLAY_SEC=60 SGS_RESP_SEC=60 SGS_NO_HERO=1 php -S 127.0.0.1:8940 -t .
node tests/sgs-hero2-api.js  # 第二批武将主动技 API    54 断言
node tests/sgs-luoshen-api.js # 洛神交互全链路（pending 字段 + 每步广播 + 收手/跳过）34 断言
node tests/sgs-wording-api.js # 牌桌文案全链路（动词 verb / 自我目标 / 决斗应战 / 无双 needN / 技能归属）23 断言
node tests/sgs-bagua-api.js   # 八卦阵全链路（端口 8944）：判定失败**不扣血**、pending 活着、仍可出【闪】、再放弃才受伤、无双归还、青釭剑仍无视 21 断言
                             #   xuluo/jushou/shensu/rende/jieyin/kurou/奇袭/蛊惑/谦逊/流离
# 开局选将（**不要**加 SGS_NO_HERO，否则不进选将阶段）
SGS_PICK_SEC=6 SGS_PLAY_SEC=60 SGS_RESP_SEC=60 php -S 127.0.0.1:8950 -t .
node tests/sgs-pickhero-api.js  # 选将全链路（真实 API）38 断言
                             #   候选池去重 / 私密性 / 重选与越池拒绝 / 选满开打 /
                             #   超时自动选 / 掉线代选 / 选将期托管
# 新锦囊（端口 8947）：延时判定/跳过阶段/闪电传递/借刀两分支/五谷亮牌池/无懈首轮不排使用者
SGS_PLAY_SEC=60 SGS_RESP_SEC=60 SGS_NO_HERO=1 php -S 127.0.0.1:8947 -t .
node tests/sgs-delay-api.js  # 乐/兵/闪/借刀/五谷 全链路 47 断言
                             #   pending 约定：jidao.victim / wugu.wuguCards / seats[i].judged
                             #   守恒断言直接读房间文件（public 不下发弃牌堆 → 亮牌池漏收尾会被抓住）
# 空闲轮询（5 人同时轮询 10 秒）：版本号不该被心跳推进
SGS_PLAY_SEC=60 SGS_RESP_SEC=60 SGS_NO_HERO=1 php -S 127.0.0.1:8951 -t .
node tests/sgs-idle-api.js   # 心跳不推进版本号 / 心跳仍落盘 / 真实变化仍推进 16 断言
# 机器人（电脑玩家）
#   ⚠️ **不要**加 SGS_NO_HERO：机器人自动选将正是要测的行为，必须真进选将阶段
#   ⚠️ SGS_BOT_SEC=0 关掉 1 秒「思考」节奏，套件才是确定性的（节奏本身在离线层 sgs-bot.php B 组）
SGS_BOT_SEC=0 SGS_PLAY_SEC=60 SGS_RESP_SEC=60 SGS_PICK_SEC=60 php -S 127.0.0.1:8948 -t .
node tests/sgs-bot-api.js    # 加电脑/顶替/房主移交/uid 冒充/自动选将/自动出牌/托管打完一局 53 断言
                             #   B 组把 7 个模式逐个过一遍（建房 → 加满 → 开局）——需求原文就是这句
SGS_PLAY_SEC=20 SGS_RESP_SEC=20 SGS_NO_HERO=1 php -S 127.0.0.1:8930 -t .
node tests/sgs-duel-api.js   # 决斗全链路（真实 API）  15 断言
SGS_PLAY_SEC=8  SGS_RESP_SEC=2  SGS_AUTO_HOST=1 SGS_NO_HERO=1 php -S 127.0.0.1:8931 -t .
node tests/sgs-host.js       # 托管边界（防抢回合，AUTO 模式）15 断言
node tests/sgs-host-manual.js  # 手动托管开关（生产模式）  15 断言（服务器 SGS_PLAY_SEC=3 SGS_RESP_SEC=3 SGS_NO_HERO=1，不加 SGS_AUTO_HOST，端口 8932）
node tests/sgs-fx-ui.js      # 特效 UI（横幅+牌面+箭头+双向高亮+自动消失+八卦阵判定牌+几何不相交+洛神交互）60 断言
                             #   ⚠️ 可见性断言必须用 getComputedStyle，不能用内联 style（见下方"假断言"条）
                             #   ⚠️ rig() 里强制 phase='playing' 并清空武将技能：UI 层服务器不带 SGS_NO_HERO，
                             #      服务端开局停在「选将」30 秒，sgs_use_card 会一直报「现在不能出牌」

> 回归测试服务器需加 SGS_AUTO_HOST=1 沿用旧的「超时自动托管」推进；
> 生产部署不设该变量，托管只能由玩家手动开启（掉线座位仍自动代打）。
> 所有浏览器 UI 测试需 `SGS_CHANNEL=msedge`（走系统 Edge，免装 playwright 浏览器）。
> 旧引擎/JS 回归不包含武将技能：服务器与引擎测试加 SGS_NO_HERO=1 禁用随机武将，保证旧断言确定性
> （引擎测试文件头已内置；JS 测试启动服务器时带上即可）。**不禁用武将时开局会先进选将阶段**，
> 所以 sgs-hero.php / sgs-hero2.php 的 `mk_room()` 会先把选将走完再进入对局。
> 而「最后一人选完 → `sgs_pick_maybe_begin` → `sgs_begin_play` → `sgs_start_turn`」会**立刻开打**：
> 主公若抽到带「回合开始」技能的武将（甄姬·洛神最典型），托管会马上结算，而 `sgs_judge()` 是
> 「翻一张就从牌堆移进弃牌堆」，于是弃牌堆凭空多出 0~4 张（张数取决于随机武将）。
> 两个 rig 的 `mk_room()` 结尾都会把这份**开局噪音归位**（弃牌搬回牌堆），保证每个用例从干净牌桌起。
> 新武将测试（sgs-hero2.php / sgs-hero2-api.js）用自己的 rig 指定武将，同样带 SGS_NO_HERO=1。

# 浏览器 UI 联调（Edge，0 秒服务器）
node tests/sgs-ui.js
```

**当前回归基线（全绿）**：离线 13 套 1378 断言 + 真实 API 14 套 514 断言 = **1892 断言**
（「? 点不动」批次后：sgs-ai.php 71 / sgs-ui-wiring 305 / sgs-ui-runtime 293 /
sgs-bot.php 36 / sgs-bot-api.js 53 / sgs-fx 229 / sgs-qian 88（含 D 组定场景判据）/
sgs-weapon-api 61 / sgs-delay-api 47；flow.js 的断言在循环里生成、按旧基线口径计 94）。
一键跑：`bash tests/regress.sh`（离线层 + API 层，任何环境可用）；
`bash tests/regress.sh --all` 额外跑浏览器 UI 层。
（历史批次：无懈 1444 / 五锦囊 1560 —— 上面各自那节末尾有记录。）

> 「手牌一直闪烁」的成因与修复（**勿退回**）：
> ① 前端新牌高亮只判 `newIds[c.id]` 是否存在，而它存的是**时间戳**（恒为真）→ 高亮永不消失；
>    又因为重绘是整体重建 `#hand`，每次重建都会重播 `.card.new` 上的入场动画 →
>    牌桌上只要有人操作（sig 变化）就重绘一次，手牌就弹一次 = 肉眼看到的"一直闪"。
>    现在：高亮按 `Date.now()` 到期并清理，入场动画拆到单独的 `.card.pop` 且每张牌只挂一次。
> ② 后端心跳（刷新 `lastSeen`）也把 `v` 推进 → 所有客户端每几秒被判成"有新状态"而整块重绘。
>    现在 `room_mutate` 用「除 `lastSeen` 外内容」的指纹决定是否推进 `v`（v 仍单调递增），
>    心跳照常落盘（掉线检测不受影响）。回归：`tests/sgs-idle-api.js`。
> ③ 手牌多到要横向滚动时，重建 `innerHTML` 会把 `scrollLeft` 归零 → 手牌"跳"一下；
>    现在重建前后保留 `scrollLeft`。

> 三个断言「可观测性」坑（已修，勿退回）：
> ① **`SGS_PLAY_SEC=0` 全托管下 `start` 请求内部 AI 就已经行动过**，手牌数不再等于发牌数，
>    所以 sgs-flow.js 只做「每人手里都有牌」的冒烟断言，严格的「每人 4 张 + 首座摸 2 张 +
>    主公体力 +1」契约放在 sgs-hero2.php 的 R 段（临时 `putenv('SGS_NO_HERO=1')` 隔离变量）。
> ② **有武将时主公体力 = 武将体力 + 1，不一定是 5**（3 血武将的主公是 4），
>    sgs-flow.js 的主公断言按「有没有武将」两种模式分别校验。
> ③ **有武将时「每人 4 张」也不是有效不变量**：主公若抽到张辽，开局【突袭】会在摸牌阶段
>    各拿一名其他角色 1 张手牌（日志 `发动【突袭】…（替代摸牌阶段）`）→ 受害者 4→3、
>    张辽 4→6（拿 2 张、同时放弃摸 2 张，合计仍是 4×人数）。
>    另外 `sgs-pickhero-api.js` 的 D 段沿用 A 段那局，而全局 `SGS_PICK_SEC=6` 可能被 B/C 段的
>    多次往返吃掉 → 这局会被「选将超时自动选」推进（D1~D8 仍成立，E 段另有专门用例）。
>    所以 D6 现在断言 **每人 ≥3 且总手牌 ≥ 4×人数**，不再断言「每人 ≥4」。
>    实测原断言 40 次挂 3 次（≈7.5%），全部由「主公=张辽」触发。

> 「英雄技能都没有生效」的排查结论（2026-09-18，**不是引擎 bug**）：
> 三种独立手段（读代码 / 真 HTTP 跑完整 AI 局看到 `发动【裸衣】`·`发动【奸雄】` 日志 /
> 用 DOM 桩渲染玩家卡住的真实房间）都确认 33 武将 37 技能在服务端**全部正常生效**，
> 真正的问题是**牌桌上没有任何可见反馈**——玩家用的是周瑜（英姿，纯被动）+ 刘备（仁德），
> 日志里"摸 3 张"就是英姿生效的证据，但屏幕上看不到任何东西。
> 修复方式是上面的「技能看得见」四层反馈。**教训：服务端权威逻辑正确 ≠ 玩家认为它生效**，
> 自动触发类效果必须有显性反馈。

> 「对方出牌我看不见」的成因与修复（2026-09-18，**勿退回**）：
> 引擎一直在正确广播 `fx = {seq, seat, name, as, suit, rank, type, targets, skill, ok}`（`tests/sgs-fx.php` 47 断言全过），
> 前端 `playFx()` 也确实渲染了横幅/牌面/箭头/高亮 —— **但整层永远不可见**。
> 真凶是 `layer.style.display = ''`：`#fxLayer` 在 CSS 里是 `display:none`，
> 而 `style.display = ''` 只是**删掉内联值**，样式表里的 `none` 依然胜出 → 整层恒为 `display:none`。
> 现在可见性由 `#fxLayer.on` 这个类控制（`.on{display:block}`），隐藏时 `classList.remove('on')`。
> **配套的第二处修复**：水位线（`fxInit`）最初只在 `poll()` 里建立，而首屏进房走的是 `act('state')`，
> 导致「进房后第一次出牌」被当成历史吞掉 → 抽成 `feedFx()` 由 `act()` 与 `poll()` 共用。
> 另修：`render()` 重建 `#seats` 会抹掉座位高亮 → 渲染后调用 `applyFxMarks()` 重贴。

> 「八卦阵没有生效」的成因与修复（2026-09-20，**勿退回**）：
> **判定逻辑一直是正确的**（红视作闪免伤、黑照常掉血、青釭剑无视、铁骑锁闪），
> 引擎单测 + 场景探针 + 真实 HTTP 三条链路全过。这是**可感知性**问题，和上面那条同源：
> ① 旧实现只在判定**成功**时广播一张**合成**【闪】（`['name'=>'闪','type'=>'basic']`，
>    `suit`/`rank` 是空串、也没有"八卦阵"字样）→ 牌桌上既看不到翻出来的是哪张牌，也看不出红黑；
> ② 判定**失败**时 `fx` 完全不动（实测 `fx === null`）→ 场上**零反馈**，玩家只看到自己掉血；
> ③ 响应面板只写"否则受 1 点伤害"，玩家根本不知道「放弃」等于"发动装备"。
> 现在：判定牌（**带着真实花色点数**）无论成败都广播，负载加 `skill='八卦阵'` + `ok`；
> `sgs_public` 额外下发 `pending.canBagua` / `baguaLocked`（与 `sgs_bagua_ready()` 同源，
> 避免"面板说要发动、后端其实没发动"），面板给出提示条 + 「放弃（发动【八卦阵】）」按钮文案。
> ⚠️ `fx.skill` / `fx.ok` **恒定下发**（普通出牌是 `''` / `null`），前端才能无条件读 `fx.skill` 分支；
> `tests/sgs-fx.php` 用 `count($fx) === 11` 把键数锁死，加字段必须同步改那条断言。
> ⚠️ 判定成功与失败必须走**同一个**广播分支 —— 一旦给它加上 `&& $roll['ok']` 之类条件，
> 判定失败又会退回"场上零反馈"（`tests/sgs-ui-wiring.php` 有一条断言专门钉这个）。

> 「八卦阵触发失效直接扣血」的成因与修复（2026-09-20，**勿退回**）：
> 报障原文：「八卦阵触发有问题，如果没有生效，用户还可以打闪，现在是触发失效直接扣血」。
> 这次不是可感知性问题，是**规则实现错了**：八卦阵是「当你需要使用/打出一张【闪】时，
> 你可以进行判定，若为红色则视为你打出了【闪】」—— 判黑只是**白翻一张牌**，
> **并不消耗你打出【闪】的机会**，你仍然可以自己出【闪】。
> 旧实现在「放弃」分支里判黑后直接 `$p['answered'] = 'pass'` 然后 `sgs_advance()` →
> 立刻扣血。玩家手里明明攥着【闪】，却在看到判定翻黑之后被直接打掉 1 点体力。
>
> 修法：判黑后把这次「放弃」**退回成"尚未响应"**——`answered = null`、pending 原样留着、
> `turnAt` 重开一个响应窗口，玩家接下来可以出【闪】，也可以再点一次「放弃」。
> 三个配套细节一个都不能少：
> ① **`baguaDone` 记号**：记「本次响应已经翻过判定牌了」。再点「放弃」时它让
>    `sgs_bagua_ready()` 返回 `ok=false` → 走真放弃分支。**没有它就能反复点放弃白嫖判定**
>    （每点一次白翻一张牌）。
> ② **`sgs_rearm_pending()`**：换人（万箭齐发的下一个目标）或换第 2 张闪（吕布【无双】）
>    就是**新的一次「需要使用【闪】」**，`baguaDone` 必须跟着 `answered` 一起复位，
>    否则第二个目标会被无端剥夺八卦阵。**只清 `answered` 不清 `baguaDone` 是个隐形 bug。**
> ③ **面板必须改口**：`sgs_public` 新增 `pending.baguaTried`；前端据此把提示条换成
>    「【八卦阵】判定失败 —— 但你仍然可以打出【闪】，机会没有被用掉」，并把「放弃」按钮
>    从「放弃（发动【八卦阵】）」恢复成真「放弃（承受伤害）」。**引擎改对了但牌桌上看不出来
>    等于没改**——玩家看到翻黑还是会以为只能认命挨打。
>
> 边界（都写成断言，防止改过头）：
> · 青釭剑 / 铁骑判定为 locked → **压根不翻牌**，所以不存在"第二次机会"，一次放弃就掉血
>   （`baguaTried` 也不能乱置位）；
> · 判黑后手里那张【闪】**不能被吞掉**（有牌才谈得上"还有机会"）；
> · 第 2 次放弃**不再翻判定牌**（`fxSeq` 不前进）。
> ⚠️ 反向验证（`python3 /tmp/falsify_bagua.py`，9 个注入点）：
> 9/9「能抓住 + 能恢复」。三条值得记的：
> ① `sgs-ui-runtime.js` 的 L4 第一版断言"出【闪】按钮存在" —— 但按钮**一直都在，只是 disabled**，
>    不点选手里那张牌就断言"按钮还在"是个假断言；现在**先断言未选牌时必须 disabled**
>    （证明这条断言真的能变红），点选之后再断言可点。**"元素存在" ≠ "元素能用"。**
> ② M8（把提示条从 `bqtried` 改回 `bqoff` 灰条）首轮**没被接线契约抓住**：
>    wiring 只断言了「CSS 里定义了 `.bqbar.bqtried`」和「文案里有某句话」，
>    而"提示条到底挂的是哪个类"没人管 → 已补一条 `class="bqbar bqtried"` 的断言。
>    **"定义了样式" ≠ "用上了样式"。**
> ③ M5 首轮也判红，但那是**证人选错了**：`sgs-ui-runtime.js` 是把 pending 直接喂给前端的，
>    结构上就看不到"引擎少发一个字段"。**列证人时要先问"这个测试的输入从哪来"。**

> 「桌面牌和出牌提示有重叠部分，遮挡了」的成因与修复（2026-09-20，**勿退回**）：
> 「桌面牌」= 牌桌中央弹出的那张大牌面（`#fxCard`），「出牌提示」= 它正上方那条
> 「谁 对谁 使用什么」的横幅（`#fxBanner`）。两者是 `#fxLayer` 里的**兄弟绝对定位元素**，
> 却各自算各自的纵向位置：横幅 `top:calc(44% - 112px)`、牌面 `top:44% + translateY(-50%)`。
> 代入得牌面上沿 `44%H - 79px`、横幅下沿 `44%H - 71.5px` → **恒定重叠 7.5px**，
> 与视口高度无关；窄屏（≤980px）横幅换行成两行时重叠 22px，第二行直接被盖住。
> 牌面在 DOM 里排在横幅**之后**且两者都没有 `z-index` → 同层按文档序绘制，**被盖住的是横幅**。
> 修法（单一真值源）：几何只在 `#fxLayer` 上定义一次
> （`--fxcard-top/-h/-w` + `--fxgap`），牌面用它摆位，横幅改成
> `bottom:calc(100% - var(--fxcard-top) + var(--fxcard-h) / 2 + var(--fxgap))`
> —— **用 bottom 锚定**，横幅换行变高只会向上长，永远不会压到牌面；窄屏断点只覆盖那几个变量。
> ⚠️ 三条断言钉住这个不变量：`sgs-ui-wiring.php` N 组（不许出现 `top:` 声明、不许残留旧硬编码）、
> `sgs-ui-runtime.js` M 组（把 `calc()` 真的解出来，在 5 个视口高度 × 2 个断点上验算间距 ≥10px）、
> `sgs-fx-ui.js` E 组（`getBoundingClientRect` 实测两个矩形不相交，含 900px 换行场景）。
> 反向验证过：改回 `top:` → N/M 组红；符号写成 `100% + var(--fxcard-top)` → M6 红；
> `--fxgap:0px` → M4/M5 红。（注：把 `/ 2` 漏掉只会让横幅**更靠上**，不遮挡，M 组不报——
> 守的是「不重叠」而不是「恰好 12px」。）

> 「牌和提示条遮挡了其他用户的信息展示（1V1 没问题，其他都有遮挡）」的成因与修复（2026-09-21，**勿退回**）：
> 上面那次只解决了「横幅 vs 牌面」的互相重叠，**没解决两者对座位卡的遮挡**：
> 牌面写在 `top:44%`（屏幕正中）——那正是 6/7/8 人局**第二排座位卡**的位置。
> Playwright 实测（8 人局、残局座位卡 ~227px 高）：牌面盖住第二排座位卡 **135px（约六成）**，
> 横幅压住第一排 7px；1V1 只有一排座位卡才碰巧看不见问题。
> 修法（**用户区 / 出牌展示区 / 手牌区 三区分区**）：
> ① 新增 `.fxstage`（横幅 + 牌面的 flex 横排容器），`bottom:var(--stage-bottom)` 锚定在
>   「我的手牌区」上方的空档里 —— 座位卡一寸都不占；
> ② 几何变量全部搬到 `:root`（`--fxcard-h:132px / --fxcard-w:96px / --fxgap / --me-h`），
>   `--stage-bottom:calc(var(--me-h) + 10px)`；`#fxLayer` 退化成纯箭头层（全屏 SVG 坐标系不变）；
> ③ `--me-h` 由 JS `measureMe()` 实时写入（`#game > .me` 的 offsetHeight，render + 轮询 + resize 兜底），
>   手牌区高度随装备行/按钮换行变化时展示区自动跟随；
> ④ 横幅/牌面改 `position:static`（跟随容器排版），技能飘字 `#skflash` 从 `top:78px`
>   （正好压第一排座位卡）挪到展示区上方。
> ⚠️ 断言已重写钉死：`sgs-ui-wiring.php` N 组（`.fxstage` 存在且 bottom 锚定、横幅/牌面必须
> `position:static`、`--fxcard-top` / `top:44%` 不得复活、尺寸变量全文件只出现一次、
> `measureMe()` 必须存在）、`sgs-ui-runtime.js` M 组（同样 9 条，含 DOM 结构契约）。
> ⚠️ 反向验证过：把 `.fxcard` 改回 `position:absolute;left:50%;top:var(--fxcard-top)` → N/M 组红。
> 注：视口很矮（<~760px）且 8 人局第二排座位卡很高时，展示区与座位卡仍可能轻微相接 ——
> 那是"总高度不够"的物理约束，但已经从"盖住六成信息"降到"贴边"。

> 「洛神一口气把牌塞给我，没有任何交互」的成因与修复（2026-09-20，**勿退回**）：
> 两个独立缺陷叠在一起：
> ① **技能按"一次性结算"实现**：`sgs_start_turn()` 里洛神是一个 `for ($i=0;$i<8;$i++)`
>    循环，一直判到红为止，全程只写 `sgs_log()` —— 牌桌上没有按钮、没有翻牌过程，
>    玩家的手牌凭空从 2 张涨到 5 张。
> ② **顺带一个规则错**：原实现判黑后是**另摸一张**（`sgs_draw_cards()`），
>    而翻出来的那张判定牌进了弃牌堆 —— 玩家看到的红黑和到手的牌**永远对不上**。
> 现在洛神是「一问一步」：回合开始只挂 `pending={kind:'luoshen'}`（**不翻牌**），
> 每点一次「发动/继续」翻**一张真判定牌**并广播一步，黑色把**这张牌本身**收进手牌
> （`sgs_take_discard`）且可继续，红色结束；随时可「停止/跳过」；
> 托管与超时（用**出牌**超时，不是 15s 响应超时）等价于一路"继续"，上限 `SGS_LUOSHEN_MAX=8`。
>
> 同一次修复还解决了**所有技能**的「过程看不见」——根因是 `room['fx']` **只有一个槽位**：
> 一次引擎调用产生的多步（洛神：判定→到手→判定…；杀+铁骑：出杀→判定→锁闪）会互相覆盖，
> 前端最多只能看到最后一步。现在每一步都追加进 `room['fxq']` 队列（封顶 `SGS_FXQ_MAX=24`，
> 满则丢最早的），`sgs_public` 整条下发，前端按 `seq` 顺序**逐步重放**
> （每步停留时长按类型区分：普通出牌 2.8s / 判定 1.5s / 技能宣告 1.1s；
> 积压时压到 0.65s 加速追平，最多留 12 步）；新开一局清空队列，否则会把上一局的过程重播一遍。
> `room['fx']` 保留为"队列末条"，老前端只看单条也不会串位。
>
> ⚠️ **措辞由引擎写**：负载新增 `step` 字段（"这一步做了什么"），前端**不许自己拼句子**。
> 早期让前端合成措辞时，把判定的那一步渲染成了「乙 打出【闪】」——玩家以为对方在出闪。
> 现在前端只有两种牌面：`fx.name` 有值 = 亮**牌**（带 `ok` 判定结论徽标），
> `fx.name` 为空 = **技能宣告**（大字技能名 + `step`）。
> 26 个原本静默的技能（英姿/突袭/铁骑/烈弓/枭姬/不屈/鬼道/雷击/苦肉/裸衣/据守/神速/仁德/
> 结姻/制衡/闭月/克己/天香/狂骨/遗计/反馈/刚烈/奸雄/连营/集智/流离）现在都会发一步可见过程
> （暗牌类只报张数、不泄露牌名）。
>
> ⚠️ 反向验证（`python3 /tmp/falsify.py` 的同类做法）：逐个注入回归并确认测试会红——
> 去掉队列追加 → `sgs-fx.php` 18 红；判黑改成另摸一张 → 4 红；`step` 置空 → 6 红；
> 洛神不问了 → `sgs-fx.php` 18 红 + `sgs-hero.php` 红；前端不按 `seq` 排序 → N5 红；
> 洛神按钮改成 `{pass:true}` → `sgs-ui-runtime.js` P4 红（**这个漏洞是故意破坏验证才发现的**：
> 原来只断言"发了 respond"，没断言载荷字段，`{go:true}` 写成 `{pass:true}` 照样过）；
> 队列封顶失效 → 2 红；新局不清空 → 1 红。8/8 全部「能抓住 + 能恢复」。

> 「我给自己桃时，对方也显示自己」的成因与修复（2026-09-20，**勿退回**）：
> **牌桌文案当初是按「单机视角」写的**，而牌桌是**四个人在看同一块屏幕**，凡是相对人称
> （自己 / 我 / 我的 / 你 / 你的）都会被每个观众读成"指自己"。整体排查后发现四类缺陷：
> ① **相对人称**：自打（桃给自己）渲染成光秃秃的「（自己）」——**这就是用户报的那一条**。
>    现在打给自己写「（对自己）」，且**只在自己那台机器上**才给名字加「（我）」后缀；
>    技能步骤里的目标必须**点名**（「乙 手牌 3 张」而不是「我的手牌 3 张」）。
> ② **动词靠前端猜**：原 `fxIsResp()` 判「出牌者是不是当前回合角色」来定 使用/打出，
>    但**回合玩家也会响应**——决斗里轮流出【杀】的是当前回合玩家，借刀杀人里打【闪】的也是，
>    于是横幅写成「甲 对 乙 **使用**【杀】」，全场以为甲在主动攻击。
>    现在动词由**引擎**下发（`fx.verb` ∈ 使用 / 打出 / 装备，`sgs_fx()` 新增第 8 个参数），
>    前端只做老数据兜底。**判「响应/主动」不能看 `isTurn`。**
> ③ **技能后果挂错了人**：刚烈的惩罚步骤、天香的转移步骤，原先是以**受害者/被转者**为
>    actor 广播的 → 屏幕写「乙 发动【刚烈】」，而**乙根本没有这个技能**（刚烈是夏侯惇的）。
>    现在这类"后果步骤"一律归属于**技能持有者**（`sgs_fx_step($room, $victim, '刚烈', …)`）——
>    注意刚烈这里 owner 恰好是**被罚者本人**（夏侯惇是被打的那个），别想当然按"发动者"写。
> ④ **多张响应缺状态**：无双（吕布）一次响应要**连打 2 张**，但 `sgs_public` 没下发
>    `needN/needDone` → 第二张的提示面板跟第一张**一模一样**，玩家以为卡住了。
>    现在 `pending` 新增 `needN`（本次共需几张）与 `needDone`（已打几张）。
>    另外：装备原先写成「使用【青龙偃月刀】」（应是「装备」且**不留空格**）；
>    濒死提示原先只说「有人濒死」（现在点名）；洛神判定时座位徽标会掉进
>    「等待响应【】…」兜底（现在显示「【洛神】判定中…」）。
>
> ⚠️ 反向验证（`python3 /tmp/falsify_wording.py`，19 个注入点）：19/19 全部「能抓住 + 能恢复」。
> 过程中发现**三个假变异**（删参数仍走引擎默认值 → 语义没变，不算破坏）与
> **两处弱断言**，已分别改成"显式传错值"（M4 传 `'打出'`）、"两个分支都测"（M5 拆成
> 弃 2 张 / 手牌不足）、"连前端一起看"（M12 由 `sgs-ui-wiring.php` 做第二证人 —
> 只删后端分支时 runtime 那条断言抓得住，光看后端抓不住）；
> 无双那条（M14）runtime 抓到了但 wiring 没抓到 → wiring 断言改成钉**守卫条件本身**
> `if ((p.needN || 1) > 1) {`，而不是只钉里面的字符串；
> 出桃按钮那条（M17）`indexOf('出【桃】自救')` 被**提示文案**顶掉了 → 改成只匹配按钮元素
> `/>\s*出【桃】自救</`。

> 「武器的技能不全，例如贯石斧」的成因与修复（2026-09-20，**勿退回**）：
> **cards.php 当初只给诸葛连弩/青釭剑写了 `skill`**，青龙偃月刀/贯石斧/方天画戟/麒麟弓
> 的 skill 全是 `''` → 装备上了等于没装。修复分四层：
> ① **引擎**：`cards.php` 补齐 6 把武器的 skill 键；【杀】结算链改成**多目标感知**
>    （`sgs_sha_snap()/sgs_sha_after()/sgs_sha_rest_after_first()`，`done2/baguaDone` 每个
>    目标都要重置），新增 `pending.kind='weapon'` 询问态与 `sgs_sha_dodge_offer()`：
>    **贯石斧**＝被闪后可弃 2 张强制命中；**青龙偃月刀**＝被闪后可再出一张【杀】追击
>    （不占次数上限、铁骑/烈弓重新判定）；**麒麟弓**＝命中时、**扣血之前**（官方时机
>    「造成伤害时」）可弃目标一匹坐骑；**方天画戟**＝最后一张手牌是【杀】时可指定最多
>    3 个目标（条件必须在 `array_splice` **之前**判定，否则手牌已经不是"1 张"）。
> ② **可选≠自动**：贯石斧/青龙/麒麟弓都是「可以」——必须**询问**玩家，绝不自动执行
>    （弃 2 张/再耗一张杀/弃马都是真实代价）。
> ③ **api.php**：respond 不能钉死「必须 1 张」，否则贯石斧的 2 张永远提交不上来
>    （现在放行 1~3 张，引擎按 pending 种类各自校验数量）。
> ④ **前端**：多目标 `mtargets[]`（与单目标 `target` 并存，`clearTargets()` 双清）；
>    三种武器询问面板（贯石斧多选手牌+「弃 N 张牌，强制命中」、青龙选一张【杀】、
>    麒麟弓每匹马一个按钮 `data-act="weapon-horse" data-id=`）；询问期手牌进入多选态
>    （`inWeaponPick()` 必须进 cardHTML 选中态判断，否则玩家选不中牌）。
> 回归：`tests/sgs-fx.php` M 组（+47）、`tests/sgs-weapon-api.js`（61，新端口 8945）、
> `tests/sgs-ui-runtime.js` R 组（+35）、`tests/sgs-ui-wiring.php` W 组（+40）。
>
> ⚠️ 反向验证（`python3 /tmp/falsify_weapons.py`，13 个注入点）：13/13 全部「能抓住 + 能恢复」。
> 过程中抓出**两处弱断言**：wiring 原来只匹配「面板按钮字符串」，改成钉**守卫条件**
> （`render()` 清空守卫要放行武器询问、手牌选中态要包含 `inWeaponPick()`、
> `weapon-ok` 的 disabled 必须由 `dsel.length === n2` 控制）；以及引擎侧断言要看
> **public 字段**（`needN/needDone`）而不是内部 `need2/done2`（见 fx M 组注释）。

> 「补无懈可击」的实现与修复（2026-09-21，**勿退回**）：
> 牌堆加入无懈可击 ×4（**100 → 104 张**），任意锦囊生效前全场依次询问：
> 从出牌者**下家**起绕一整圈，只问**手里有无懈**的存活玩家；出无懈 = 抵消，
> 无懈也能被无懈反制（`pending.parity` 0↔1 翻转），全场放弃后按 parity 结算。
> 四层结构（**结算本体复用同一份代码**，放行路径与"没人无懈"完全一致）：
> ① `sgs_wuxie_offer()`——询问发起：pending.kind='wuxie' + `chain`（决斗/南蛮/万箭这类
>    "本体是 pending"的锦囊）或 `eff`（无中生有/拆桥/牵羊这类**内联结算**的锦囊）+ `next`
>    （桃园的其余目标队列）。**场上没人有无懈就直接结算，不弹询问**。
> ② `sgs_apply_respond` 的 wuxie 分支——pass 推进 oi；出无懈 → parity 翻转 +
>    从出无懈者的下家重建 askers（反制链）；无人再问 → `sgs_wuxie_resolve()`。
> ③ `sgs_wuxie_apply()`——内联效果执行（wzs/chai/qian/taoyuan 四种），文案与原实现逐字一致。
> ④ AOE 逐目标：`sgs_aoe_wait_next()` 统一推进（跳阵亡 → 问无懈 → 没人无懈才等响应），
>    **被抵消的目标要先 `oi++` 再交给下一位**（漏了这步会对同一目标问两轮）。
> 前端：`need_name` 认 wuxie → 通用响应面板直接复用；新增 `respTip` 的 wuxie 分支
> （parity 0「即将对 X 生效…将其抵消」/ parity 1「即将被抵消…使其恢复生效」）。
> AI：只为本方出手——有害锦囊指向自己/队友时抵消；被反制时若锦囊对敌人有害或本方有利就恢复。
>
> ⚠️ 反向验证（`python3 /tmp/falsify_wuxie.py`，8 个注入点）：8/8 全部「能抓住 + 能恢复」。
>
> ⚠️ **牌张守恒与 rig 换牌的教训（下次加牌必看）**：
> ① 新牌进牌堆后，离线套件里**随机发到手的牌会让旧断言撞上全场询问**——rig 必须把
>    手里的无懈**换成**牌堆里的非无懈牌。⚠️ 必须是"换"不能是"删"：删会破坏
>    「牌张守恒」（qian 的逐步守恒断言 2907 连红）和「开局每人 4 张」（hero2 R1 红）。
> ② 换牌时 `unset($room['deck'][$di])` 会在 deck 里留下**键空洞**，而各套件的
>    `take_named()` 用 `foreach` 的**键**当 `array_splice` 的**偏移**用——空洞会让它
>    错删（症状：随机「丢一张、重一张」，守恒断言逐次漂移；压测 500 次才定位到）。
>    换完必须 `$room['deck'] = array_values($room['deck']);` 归一化。
> ③ 硬编码「整副 100」的断言（dying/hero 守恒、luoshen-api 牌张守恒）要同步改成 104。
> ④ 测试 rig 手工构造的 AOE pending 没有 `dcard` → `sgs_aoe_wait_next` 必须放行
>   （`if (!empty($chain['dcard']))` 才问无懈），否则 TypeError。

> 「增加锦囊牌：乐不思蜀 / 兵粮寸断 / 闪电 / 借刀杀人 / 五谷丰登」的实现与修复（2026-09-21，**勿退回**）：
> 牌堆 **104 → 116 张**（+12：乐 3 / 兵 3 / 闪电 2 / 借刀 2 / 五谷 2）。回合结构从
> 「摸牌 → 出牌 → 弃牌」扩成「**判定** → 摸牌 → 出牌 → 弃牌」——延时锦囊才有落脚点：
> `sgs_start_turn()` 不再立即摸牌，而是把判定区的牌整体搬进 `room['delayQ']` 逐张结算
> （`sgs_delay_step()`：翻判定牌 → 广播真判定牌 → 全场问无懈 → `delay_apply`），
> 结算完统一进 `sgs_after_judge()`（摸牌 + 兵粮跳过 + 乐跳过出牌 + 洛神询问）。
> 四层结构：牌堆定义（cards.php）/ 引擎规则（engine.php）/ public 下发 / 前端可见
> （判定区 ⏳ 徽标、五谷挑牌面板、借刀两步提示）——**缺任何一层都不算实现**。
>
> ⚠️ 本批踩到的三个真 bug（**都由既有全局模拟套件当 fuzzer 抓出来**）：
> ① **五谷丰登同 id 被两个人挑到**：亮牌池曾是**值拷贝**（`$eff['cards']` / `$p['cards']`），
>    必须让 `room['wuguPool']` 成为**唯一数据源**（使用方写入，挑牌/响应/public/AI 全部读写它）。
> ② **无懈拉锯期间的守恒空洞**：延时锦囊曾在 `delayQ` 里被 `array_shift` 弹出后才走无懈询问，
>    那段窗口里它不属于任何可数区域 → 改为**只 peek `delayQ[0]`**，真的落实（`delay_apply`）
>    或被抵消（`delay_after`）时才弹出。
> ③ **被自己的闪电劈死后卡死 3000 步**：判定途中阵亡会留下 `turnSub='judge'` 而无人推进 →
>    `sgs_death` 里当前回合者要一并弃掉 `delayQ`，`sgs_tick` 加「判定续跑」兜底，
>    两条濒死结算分支补 `sgs_next_turn`。
> ④（顺带修掉的存量崩溃）拆桥/牵羊目标在无懈拉锯里打光手牌 → `random_int(0,-1)` 致命错，
>    现在先 `sgs_target_has_cards()` 判断再动手。
>
> ⚠️ **乐不思蜀 / 兵粮寸断无视距离**（2026-09-21 改，**勿退回**）：
> 引擎原本限「距离 1」（奇才除外）——已删除该校验：延时锦囊按标准规则**不限距离**，
> 前端 targetCheck 同步放开（提示语改为「可对任意距离的目标使用」），
> 机器人贴牌也不再限距离（贴前先查目标判定区防同名重复）。
> 反向验证：把距离校验注回 → sgs-fx U1c/U1c2/U1c3 红 3 条；还原回绿。
>
> ⚠️ **一个真实规则 bug：无懈可击不该问锦囊使用者本人**（本批修）：
> `sgs_wuxie_askers($room, $afterSeat)` 原本从 `$src` 的下家绕**一整圈**（含 `$src` 自己），
> 于是「使用者本回合摸到无懈」（集智/无中生有在同一 tick 里摸到）时会立刻**自问自答**，
> 整条结算被挂住 —— 症状是 `sgs-hero.php` F 组间歇性红（约 1/4 局），排查方向一度被误认为
> 是测试 rig 不稳。现在首轮传 `$src` 排除使用者本人：`sgs_wuxie_askers($room, $src, $src)`；
> 链式询问（有人打完无懈后重开一轮）**不排除**，所以「无懈反制无懈」照旧。
> `tests/sgs-fx.php` U12 专门钉这条，`sgs-ui-wiring.php` 有一条 ★ 断言守签名。
>
> ⚠️ **五谷丰登剩余亮牌必须收尾**：有人被无懈抵消 / 轮到前阵亡被跳过时，亮牌池会剩牌；
> 若不收尾，下一张【五谷丰登】的 `$room['wuguPool'] = $revealed` 会**直接覆盖**它们 = 凭空丢牌。
> 现在 while 循环结束后把剩余亮牌 `sgs_to_discard` 并清空池子（U10d / I4 各钉一条）。
>
> ⚠️ **断言的坑（本批两次踩）**：
> ① 「跳过出牌阶段」之后**回合会立刻交给下一家**，全局 `turnSub` 又被新回合重置成 `play`——
>    断言必须锚在**那个座位自己**（`turnIdx` / 「不含某条日志」），否则判定写反也照样绿
>    （破坏验证第 ① 条差点被判为「断言是摆设」）。
> ② `mk_room4()` 的座位此前没有 `judged` 字段：注入 bug 后 `count(null)` **崩溃**而不是
>    「干净地红」——rig 的座位字段要与引擎对齐（`judged` / `buqu`），
>    破坏验证要求「注入 → 一条清晰的 FAIL」。
> ③ 牵羊/拆桥的**落点白名单**要包含新增可数区域：判定区 / `delayQ` / `wuguPool`
>    （同 tick 里被牵走的牌可能立刻被置入判定区或落进亮牌池）；且目标可能在同一 tick 里
>    **先拿到这张牌再被牵走** → 目标差集为空是合法的（qian 现在有这个兜底）。
> ④ rig 里随机发到手的**新锦囊**同样要「换」成别的牌（换牌清单已扩到 6 张），
>    否则旧断言会撞上五谷挑牌 / 借刀询问这类新 pending。
>
> ⚠️ 反向验证（`python3 /tmp/falsify_delay.py`，7 个注入点：判定条件写反 ×2 / 闪电吞牌 /
> 借刀白拿武器 / 亮牌池值拷贝 / 亮牌不收尾 / 无懈又问使用者）：7/7 全部「能抓住 + 能恢复」。
>
> 本批基线：**1560 断言**（离线 1099 + API 461），全绿。

> 「所有模式创建房间后可增加机器人并开启游戏」的实现与修复（2026-09-21，**勿退回**）：
> 需求原文就一句，但它要求**7 个模式全都**能用，所以验收口径就是「建房 → 加电脑 → 补满 → 开局」
> 逐个模式过一遍（`tests/sgs-bot-api.js` B 组），单测 1v1 不算完成。
>
> 设计上机器人是**一等座位**（与真人共用 `new_seat()`，只多 `bot:true`），这样选将/手牌/装备/
> 濒死/结算全都不用分叉。四层结构（缺任何一层都会漏）：
> ① `api.php`：`addbot` / `delbot` 两个路由（房主 + waiting 双守卫）+ `join` 满员时顶替末尾电脑；
> ② `engine.php`：`sgs_is_bot()` / `sgs_bot_pace()` + `sgs_seat_hosted()` 里**先于 hostOn** 放行机器人，
>    四个动作点（自决面板/响应/弃牌/出牌）接节奏，`sgs_tick` 单次上限 40 → **80**（8 人局 = 房主 + 7 电脑）；
> ③ `sgs_public()` 下发 `seats[i].bot`；④ 前端等待页的加/删按钮与牌桌的「电脑」徽标、
>    「电脑思考中…」文案、在线点不判灰。
>
> ⚠️ **本批踩到的三个真坑**：
> ① **`state.n` 语义错了（存量 bug，被本批顺手修掉）**：原写成 `count($room['seats'])`，
>    于是 4 人房刚建好就显示「人数 1/1」、开局按钮还是可点的（点了才报「需要 4 人」）。
>    现在 `n = SGS_MODE_PLAYERS[mode]`（**这个模式需要几个人**），前端等待页的「还差几个」和
>    「一键补满（+N）」全靠它。**别把"当前坐了几个"和"需要几个"混成一个字段。**
> ② **`sgs_public()` 泄露机器人手牌**：`seat_of()`（api.php）跳过了机器人，但 `sgs_public()`
>    自己又扫了一遍 `seats` 找 `mySeat`，**并不经过 `seat_of`** → 拿机器人 uid 读 `state`
>    会得到 `mySeat>=0`，于是 `hand` 被下发（选将期还会下发候选池）。
>    "uid 是 32 位随机数猜不到"不能当成不设防的理由 —— 现在两处**都**跳过机器人。
>    两个"跳过"必须成对存在，`sgs-ui-wiring.php` 各钉一条 ★ 断言。
> ③ **`sgs-ui-wiring.php` 里两条恒绿的假断言**（破坏验证时暴露的）：
>    `/function seat_of.*?empty\(\$s\[.bot.\]\)/s` 与 `/hostUid.*?===\s*\$uid.*?empty\(\$s\[.bot.\]\)/s`
>    用的是 `.*?` + `/s`，会**一路滑出函数体**去匹配后面 `new_seat` / `last_bot_seat` 里的同一个词
>    —— 把守卫删掉照样绿。现在一律**先把函数体抠出来**再断言
>    （`if (preg_match('/function seat_of\(...\): int\s*\{.*?\n\}/s', $api, $m))`）。
>    ⚠️ 抠出函数体之后还得钉**代码行**：我第一版改成在函数体里找 `empty($s['bot'])`，
>    结果匹配到了**我自己写的那句解释性注释**（注释里也写着这个词）——照样恒绿。
>    **教训：静态断言要"先圈定范围、再钉代码本身"，别用散文里的词当锚点。**
>
> ⚠️ **一个把测试写假了的思路错误（本批最值得记的一条）**：
> 机器人套件的 C 组原本写「真人 `end` → 等回合交回真人 → 断言 seq 前进」，
> 结果**恒定失败**在 `seq 10→10`，一度以为是机器人没自动出牌，排查了半天业务代码。
> 真相是测试的**前提就错了**：`end`（结束出牌）**不等于**回合结束 —— 手牌超过体力上限时，
> 引擎会转进**同一个人的**弃牌阶段，此时 `turnIdx` 仍然是自己、`pending` 仍然是 null，
> 于是那条"等到回合交回真人"的 `waitedOnMe()` **当场成立**，`waitFor` 立刻返回，
> 比的是同一个时刻的 seq。同时 `sgs_bot_pace()` 关掉（`SGS_BOT_SEC=0`）后，
> 机器人的**整个回合会在同一个请求的 tick 里跑完** —— 想靠轮询"看到"机器人回合中间态是不可能的。
> 现在 C 组按**真实时序**重写：真人 end → 按需补弃牌 → 断言 `turnIdx` 真的不再是自己
> （C6b）→ 再用两个**可靠信号**断言机器人接管：日志里 `—— 电脑·甲 的回合 ——`
> （`sgs_start_turn` **无条件**写，是唯一可靠的"机器人开回合"信号）**且** `电脑·` 日志条数增加（C7），
> 外加「真人收尾之后一张牌都没出」（C7b）和「控制权回到真人」（C9）。
> **教训：写"等某个状态发生"的断言前，先确认这个状态**真的**会被观测到 ——
> 尤其在一次请求可能推进多步的引擎里，中间态可能根本不存在。**
>
> ⚠️ 反向验证（`python3 /tmp/falsify_bot.py`，**11 个注入点**）：11/11 全部「能抓住 + 能恢复」。
> 覆盖：不恒托管（整局卡死）/ 节奏失效 / 加电脑不限名额 / 不校验房主 / 满员不顶替 /
> 座位可被 uid 命中 / 对局中也能删电脑 / `state.n` 退回座位数 / 前端把电脑判成掉线 /
> `sgs_public` 泄手牌（①②的产物，写断言时才发现）/ 房主离开把房主让给电脑。
> 其中「房主让给电脑」这条此前**只有静态断言**，现在补了真实 HTTP 用例：
> 4 人房加 3 个电脑 → 真人顶掉末尾电脑 → 房主离开 → 断言 `isHost` 落在**真人**身上且他真能加电脑。
>
> 本批基线：**1692 断言**（离线 1178 + API 514），全绿。

> ⚠️ 顺手修掉的一个**测试侧偶发假红**（sgs-qian，2026-09-21，**勿退回**）：
> 机器人批次收尾跑全量回归时，`sgs-qian.php` 偶发 `pass=81 fail=2`（约 3%，报
> `牵羊牌进入出牌者手牌 → 目标少牌=[101] | 牵者新增手牌=[17] | 同名牌id=[…] 里没有 101`），
> 12 次重跑又全绿 —— 典型的"偶发"陷阱。定位到**两个独立缺陷叠加**：
>
> ① **前像表比守恒表少扫了三个区域**：延时锦囊批次把"牌可以停留的区域"从 4 个扩到 7 个
>    （判定区 `judged` / 判定队列 `delayQ` / 五谷亮牌池 `wuguPool`），内联守恒断言当时扩了，
>    但 `pre_name_map()` **没扩** → 一张正躺在判定区的牌在前像里没有条目，
>    `name_ids()` 查不到它 → 按牌名兜底静默失效。
>    **加新区域要同时改三处：守恒统计、前像表、落点白名单。**
>    （本文件里那个**零调用的** `piles()` 辅助函数当时**没**跟着扩，留着一份 4 区域旧清单 ——
>    死代码 + 口径分歧的双重地雷，已整段删除并留注释说明。**别再写第二份区域清单。**）
> ② **真正的假红来源：兜底条件被写成了"只在目标差集为空时才尝试"**。
>    `AUTO_HOST` 下同一次 `sgs_tick` 会连走多步：目标**摸牌拿到这张【杀】→ 转手被下家牵走**，
>    而目标自己这一 tick 里往往还丢了**别的**牌（弃牌阶段 / 被拆）→ 差集非空（[101]），
>    兜底整段被跳过 → 假红。条件跟"差集是否为空"毫无关系，要问的是
>    「牵者新增的这张同名牌，**目标前像里到底有没有**」。
>
> 修法（一并做，缺一条都还会红）：
> · 前像表补齐 `judged` / `delayQ` / `wuguPool`；
> · **落点白名单 `delayQ` / `wuguPool` 必须先取 `id` 再并入**：那两处放的是**牌对象**，
>   直接 `array_merge` 进去的话白名单里躺的是数组，`in_array($id, $zones, true)` 永远匹配不上
>   —— 牌刚好**停在判定队列 / 亮牌池**时又是偶发假红（拉长压测才现形：110 次挂 1 次，
>   报「同名牌在目标少牌里，却既不在牵者手上也不在白名单」。**这条与上一条是同一个坑的两个面**：
>   新区域只要有一处没按"id 口径"处理就会静默失效）；
> · 把判据抽成 `qian_ok()`、把落点白名单抽成 `qian_zones()`（**压测与定场景用例共用一份实现**），
>   第三条证据 = 与日志牌名一致 ∧ 目标前像里没有 ∧ 现在在牵者手上 ∧ 目标手上已经没有了；
> · 新增 **D 组定场景回归**（+6 断言，82 → 88）：D1 判绿（就是修复前报的那个形状）、
>   **D2 断言老判据在同一组输入上判红 —— 把"成因"钉成断言**、
>   D3 常规情形判绿、D4 无归属证据时仍判红（防判据被放宽成橡皮图章）、
>   **D5 白名单必须认出停在判定队列/亮牌池里的牌**、D6 白名单不是恒真集合。
> ⚠️ 反证做过两条：把兜底重新锁回 `count($lost) === 0` → **D1 立刻变红**；
> 把白名单还原成"直接并入牌对象" → **D5 立刻变红**（输出里能直接看到白名单里躺着
> `{"id":17,"name":"兵粮寸断",...}` 这种对象）。恢复都回绿（88/0）。
> ⚠️ 第三条证据是**弱证据**（只证明"牵者多了一张同名牌、且这张牌不在目标手上"，不证明它一定
> 来自目标手牌）—— 真正的强证据是文件开头的定场景用例，注释里已写明，别把它当强断言用。

> ⚠️ 一个「永远不会失败」的假断言（值得记住的教训）：
> 上面那个 bug 之所以能存活，是因为 `tests/sgs-fx-ui.js` 当时断言的是**内联样式**
> `document.getElementById('fxLayer').style.display !== 'none'` ——
> 出问题时代码写的正是 `''`，而 `'' !== 'none'` 恒真，**这个断言不可能失败**。
> 现在一律用 `getComputedStyle(el).display` 判定真实可见性；
> `tests/sgs-ui-runtime.js` 的 J 组还更进一步：从 CSS 里读出默认 `display`，
> 与类状态合成「实际生效的 display」再断言（无浏览器也能抓）。
> **凡是断言"可见/隐藏/生效"，都要断言最终生效值，不要断言你刚写进去的那个中间变量。**

> 「浏览器无法启动」时的兜底：本环境 Chromium / Edge 启动即被 SIGTRAP 杀掉
> （`thermal_state_observer_mac` + 沙箱限制），`sgs-*-ui.js` 系列跑不了。
> 此时用 `tests/sgs-ui-wiring.php` 做静态接线校验：它检查每个 `data-act` 都有分发分支、
> 每个 `act('x')` 都在 api.php 有路由、每个主动技都有入口、`canConvert` 覆盖全部视作规则、
> 主动技按钮都受对应回合标记约束——能在无浏览器条件下挡住绝大多数「按钮点了没反应 / 报未知操作」。
> **但它只是字符串/结构匹配**：条件写错、运行时抛异常把面板打空这类问题它看不出来。
> 所以再往下加一层 `tests/sgs-ui-runtime.js`：抽出 index.html 真实的 `<script>` 体，
> 桩出 `document/window/localStorage/fetch/setInterval` 后用 `new Function` 挂载，
> 再像用户一样点按钮（`ui.clickCard` / `ui.clickAct` / `ui.poll`）并断言渲染结果——
> **无浏览器也能跑真实前端逻辑**，能抓到"函数存在但条件写反 / 运行时异常"这一类 bug。
> 排查线上真实房间时用 `node tests/sgs-ui-runtime.js --dump room-state.json`。
> （夹具来源：`node tests/capture-state.js` 会建一个 1v1、选完将、把真实 state 落到
> `tests/fixtures/state-sample.json` 后退出房间。）

> 测试夹具（rig）自身踩过的四个坑（**改测试前先看这里**）：
> ① **造牌前必须把开局发的牌收回牌堆**：`sgs-duel-api.js` 直接改房间 JSON 覆盖
>    `seats[].hand`，会让开局那 8 张牌凭空消失；而整副牌只有 **3 张【决斗】**，
>    一旦它们大多正好在那 8 张里（或被后续摸牌摸走），牌堆里就再也取不到决斗 →
>    偶发 `Cannot read properties of null (reading 'id')`（实测 60 次挂 3 次，≈5%）。
>    现在造牌前先 `recycleAll(room)`：手牌 / 装备 / 弃牌堆全部退回牌堆，且取不到牌时
>    直接抛出「牌堆里没有【X】：剩余 N 张 + 全量牌名直方图」，不再抛莫名的 TypeError。
> ② **按牌名兜底必须用「房间前像」**：全局 `$DECK` 与房间牌堆都来自 `sgs_build_deck()`，
>    但各自 `shuffle()` 过，**同 id 在两边不是同一张牌**。所以"同名牌"的 id 必须取自
>    房间自己这一局的前像（`pre_name_map()`），拿 `$DECK` 反查会得到随机结果
>    （可能假通过也可能假失败）。回归：`tests/sgs-qian.php`。
> ③ **同一 tick 内弃牌堆可能被洗回牌堆**：`sgs-draw-one` 在牌堆摸完时会把弃牌堆重新洗入
>    （日志「牌堆已摸完，弃牌堆重新洗入」），此时**弃牌堆被清空、牌可能已被别人摸走**，
>    "被拆的牌落在弃牌堆"这类断言在这一 tick 内根本不可观测。
>    所以 `sgs-qian.php` 里检测到该日志就放行该 tick（牌张守恒断言仍全程生效，
>    拆桥若吞牌/复制牌必然被它抓住），**落点的强校验放在定场景用例里**
>    （目标手牌 → 弃牌堆、唯一一张直接拆掉，共 12 条断言）。
>    另外"目标在本 tick 内又摸牌补齐"会让 `pre - post` 差集为空，也要用同名牌兜底。
> ④ **不要为了修测试去改业务代码**：为让牌 id 不串局，曾给 `sgs_build_deck()` 加
>    静态 id 分段（每次调用给一段独立 id），结果反而破坏了 qian 测试依赖的
>    "两个牌堆共享 id 空间"前提——已回滚。**修 rig，不修产品**。
> ⑤ **别用「绝对上界」写断言，要么用增量、要么按 id 定位**：`M2 不屈牌不在弃牌堆`
>    原写成 `count($room['discard']) < 2`，把"牌桌上本来就有多少弃牌"也算进了不变量。
>    而 `mk_room()` 走完选将就会自动开打，主公抽到**甄姬·洛神**时托管立刻结算，
>    `sgs_judge()` 每翻一张就把判定牌移进弃牌堆 → 开局残留 0~4 张随机弃牌
>    （实测 150 次挂 3 次，≈2%；去掉归位后 120 次挂 5 次，≈4%）。
>    现在：① 两个 rig 的 `mk_room()` 都把开局噪音归位（弃牌搬回牌堆）；
>    ② M2 改成真不变量 —— **弃牌堆张数与挨打前完全一致** 且 **不屈牌的 id 不在弃牌堆里**；
>    ③ 另加 `M0 定场景后弃牌堆是干净的` 单独钉住 rig 前提，谁再往开局流程丢牌会直接红灯，
>    而不是让 M2 悄悄退化成掷骰子（已用反证验证：去掉归位后只有 M0 报 `discard=5`）。
> ⑥ **把牌塞到牌堆顶必须晚于「从牌堆里取牌」**：八卦阵那组用例先 `stack_judge()` 把一张红牌
>    `array_unshift` 到牌堆顶，再 `give($room, 0, '杀')` —— 而 100 张牌里有 30 张【杀】、
>    其花色随机，**那张红牌本身很可能就是一张【杀】**，于是 `give` 按名字搜索时把它从牌堆顶抽走了，
>    判定牌换成另一张 → `H1/H4/H5/H6` 间歇性变红（实测 5 次挂 2 次，≈40%，不是 2%）。
>    修法：**先 `give` 再 `stack_judge`**（本改已连跑 40 次全绿）。
>    教训与 ④ 一致：**先怀疑 rig 的顺序/前提，再怀疑产品**。

浏览器测试启动参数可用环境变量覆盖（本机 Edge headless 偶发 crashpad 崩溃时的兜底）：

- `SGS_HEADLESS=0`：有头模式启动（排查 headless 崩溃用）
- `SGS_CHANNEL=msedge`：切回系统 Edge（默认用 Playwright 自带 Chromium；
  需先 `PLAYWRIGHT_BROWSERS_PATH=<目录> node pw149/node_modules/playwright-core/cli.js install chromium`）
- Playwright 1.63+ 已不支持 macOS 13，仓库配套用 playwright-core@1.49.1（`PW_PATH` 指向其安装路径）

## 七、运维备注

- 轮询 700ms，8 人局约 11 请求/秒，虚拟主机够用
- 前端只在 `v`（版本号）或 sig 里的字段变化时才整块重绘；`v` 只在**真实状态变化**时推进
  （心跳刷新 `lastSeen` 不算），所以空闲时不会无意义刷新页面
- 房间 3 小时未活动自动清理
- 对局中离开不释放座位，托管代打；waiting 阶段掉线 60s 后可被顶替

## 八、行动顺序（顺位号 / 正在出牌 / 下一个）

2026-09-21 报障「出牌顺序看不懂」的修复，三端契约：

- **服务端**（`engine.php`）：`sgs_public()` 下发 `zhuSeat`（①号位=主公位）、
  每座位固定 `turnOrder`（1..n 排列，阵亡保留编号）、`nextSeat`
  （由 `sgs_next_turn_seat()` 算出，与 `sgs_next_turn()` 真实推进**同源**：
  同样跳过阵亡 +【据守】；非出牌阶段 / 活人≤1 时为 -1）。
- **前端**（`index.html`）：座位卡左上角常显顺位号（当前回合红号 + 脉冲光圈 +
  「正在出牌」红徽标；下一个橙「下一个」徽标；阵亡灰号）；我的区域同样带顺位号与
  「正在出牌 / 下一个是我」状态；`deckinfo` 加「下一个」一行。
  ⚠️ 前端**不许自算**顺序（ui-wiring O6 有负向断言）——一旦自己 % 取模，
  就跟引擎的阵亡/据守跳过逻辑漂移了。
- **测试**：`tests/sgs-turnorder.php`（37 条，B 组把 helper 预告的人与
  `sgs_next_turn` 真正交给的人逐回合交叉核对，含阵亡/据守/连杀场景）；
  ui-wiring O 组 12 条；破坏验证 5 变异全部抓到。
  ⚠️ 测试防御：helper 返回 -1 时**绝不能拿 -1 当座位下标**写 `$room['seats']`
  ——那会塞进 key=-1 的垃圾元素，后续 `sgs_public` 迭代到它直接 TypeError 崩掉，
  破坏验证显示"无效运行"而不是干净的红（本轮实测踩中）。

## 九、手牌平铺 / 牌面文字不换行 / 提示框自适应

2026-09-22 需求（一条打包三件事）：**手牌不要像斗地主一样叠起来，要平铺，超过屏幕显示区域再折叠；
牌面文字不许换行（4 个字的会折行）；提示框文字溢出，要做自适应**。

三件事同一个根因 —— **写死的几何/字号**：

| # | 旧写法（病根） | 修法 |
|---|---|---|
| ① | `.card + .card{margin-left:-18px}` 恒定负边距 = 斗地主式叠牌（放得下也照叠） | 间距改成 `calc(var(--hand-gap) - var(--hand-ov))`，`--hand-ov` 默认 `0px`（= 平铺）；只有一行超宽时由 `fitHand()` 写回"需要重叠多少像素" |
| ② | `.card .cn` 字号写死 16.5px（66px 牌面里 4 个字必折行） | 牌名按字数挂 `.len3/.len4/.len5`，字号 `calc(var(--card-w) * 系数)`，与牌宽联动（窄屏自动同缩）；`.cn/.cs/.ce` 统一 `white-space:nowrap` |
| ③ | `.acts` 里提示与按钮挤一行且不许换行 | `.acts .tip{flex:1 0 100%}` 独占一行 + `.tip{overflow-wrap:break-word}` 可折行；`.tst`/`.skb`/`.fxas`/`.fxjudge` 补 `max-width` |

**手牌平铺/折叠的实现**（`index.html`）

- 几何三个变量在 `:root` 声明（**唯一真值源**）：`--hand-gap:6px`（平铺缝）、
  `--hand-ov:0px`（重叠量，默认 0）、`--hand-min:26px`（折叠后每张牌至少露出的宽度）。
- `fitHand()`：`need = n*cardW + (n-1)*gap - 容器宽`，只有 `need > 0` 才折叠，
  `ov = min(ceil(need/(n-1)), cardW - --hand-min)` —— **最小重叠量** +
  下限兜底（40 张牌也不许压成一条线，撞下限后挂 `.hand.folded` 横向滚动并改左对齐，
  否则 flex 居中 + overflow 会把最左边的牌顶出可视区，点都点不到）。
- 数值全部用 `getComputedStyle` 从 CSS 变量读，JS 里**不抄第二份**（改了 CSS 就生效）；
  量不到几何（元素隐藏 / 桩环境）一律按平铺处理，不猜。
- 调用点：`render()` 里重建手牌 innerHTML 之后、`window resize`。

**测试**

- `tests/sgs-hand-render.js`：抽出**真实的** `cardHTML()/nameLenClass()/fitHand()` 跑数值
  （平铺 / 恰好放下 / 差 1px / 最小重叠 / 下限 / 量不到几何 / 单张 / CSS 变量缺失 / resize 接线）。
- `tests/sgs-ui-wiring.php` P 组 13 条：三处旧写法（`-18px`、`.card{width:Npx}`、
  `.card .cn{font-size:Npx}`）都做**负向**断言（先剥注释，否则修复说明里的引用会误报）。
- `tests/sgs-ui-runtime.js` T 组 9 条：把 CSS 解成**数值**算「N 个字 × 字号 + 字距 ≤ 牌宽 - 边框 - padding」，
  66px 与 56px（窄屏）两个宽度都算 —— 只查 `white-space:nowrap` 是查不出"字号没缩够"的。
- 破坏验证：9 次注入（退回 -18px / fitHand 恒定重叠 / 不挂 len 类 / 字号写死 / 提示不独占一行 /
  不许折行 / toast 无 max-width / 删 `.folded` / 删 resize 接线），每次都必须变红且还原后回绿；
  ⚠️ 注入锚点必须先 `assert count == 1`（`-18px` 在 CSS 与注释里各出现一次，不剥注释/不查唯一性就会注入错地方）。

## 十、电脑玩家决策质量（2026-09-22）

需求原话：**「电脑人不够智能，打的杂乱无章没有思考」**。逐条对着"乱"的来源改：

| # | 旧行为（病根） | 新行为 |
|---|---|---|
| ① | `sgs_is_enemy()` 只判"双方都是主公阵营才不算敌对" → **反贼 A 与反贼 B 互为敌人**，机器人互相残杀 | 统一走 `sgs_ai_hostility()` 三档（自己人 / 中立 / 敌人） |
| ② | 目标平手时 `random_int` 挑一个 → 一会儿打这个一会儿打那个 | 同分**按座位序**取第一（确定 + 可复现） |
| ③ | 内奸没有策略，开局就咬主公（`$b === 'zhu'` 恒不成立） | 谁势大打谁，主公留到最后清算 |
| ④ | 反贼死光后主公仍把内奸当中立 → **主公只挨打不还手**，一局跑到步数上限都打不完 | 反贼全灭 → 内奸升级为敌人 |
| ⑤ | 弃牌只分"桃/杀/闪/其他"四档 | 按 `sgs_ai_card_value` 升序丢（保桃保无懈，血薄时闪更值钱） |
| ⑥ | 拆/顺手从判定区 + 装备 + 手牌里**随机抽** | 装备是明牌 → 按价值挑（武器 100+射程 > 防具 80 > 坐骑 40）；手牌仍只随机 |
| ⑦ | 无懈见锦囊就出（连【无中生有】都掐） | 三态取值：有害才掐、被掐掉的是我们想要的就救回、无关就省着 |
| ⑧ | 濒死求桃谁求都救（救敌人也救） | 只救自己人；内奸保主公；自己只剩一张且血薄时留着 |
| ⑨ | 出牌"手上有就往外丢"，被引擎拒了还反复重试到上限 | 四段顺序 + 每段门槛 + `$tried` 黑名单（被拒过的牌不再重试） |
| ⑩ | AOE 只比人数（敌 3 友 3 也开）→ 顺手带走自己人 | 加第三条门槛：**队友没人只剩 1 血**（只看体力这个明牌） |

**测试**：`tests/sgs-ai.php`（71 断言，A~F 六组）+ `tests/sgs-ui-wiring.php` 3 条新契约 +
`tests/sgs-ai.php` F 组的**全机器人局宏观断言**（同阵营零攻击 / 动作数 ≥ 15 防空转 /
4 与 8 人局都能打完 / 全程牌张守恒）。

**两处非代码的坑（都写进断言了）**

1. **收尾僵局**：反贼死光后若主公仍把内奸当中立 → 主公单方面挨打，4 人局跑 1600 步打不完。
   F3/F5 就是这么抓出来的（"能打完"必须单独断言，光断言"不互殴"会漏）。
2. **flow 的旧终局断言失效**：`终局存活数 <= 一半+1` 是"这局真打起来了"的代理值，新 AI 会
   （**正确地**）集火主公 —— 8 人局反贼集火斩主时场上还站着 6~7 人，旧指标实测 **14/20 假红**。
   已 1 换 1 换成「**胜负文案 ⇔ 存活构成**自洽」（反贼获胜 ⇒ 主公已死；主公忠臣获胜 ⇒
   无反贼无内奸；内奸获胜 ⇒ 只剩内奸；队伍局 ⇒ 败方全灭且胜方有人活）。
   ⚠️ 队伍局**不能**要求胜方全员存活 —— 胜方也可能有人阵亡（同归于尽式收尾），
   写过头会在 2v2 偶发假红（注入验证时抓到的）。

**破坏验证**：本批共 3 次注入（引擎 AOE 门槛失效 → C4d 点名红；身份局两个胜负文案对调 →
flow「胜负与存活构成自洽」在 4/5/8 局点名红，1v1/2v2 保持绿；把"主公已阵亡"写成"主公体力未满"
这个 off-by-one → 该断言点名红）。每次都必须变红、还原后必须回绿，注入锚点一律先
`assert count == 1`。

## 十一、身份标记（2026-09-22）

需求原话：**「增加角色标记，当对方身份不明时可以自己标记对方身份，自己标记的身份其他人
看不到仅能自己看」**。

实现（全部在 `index.html`，**引擎与接口一行没动**）：

| 件 | 做法 |
|---|---|
| 入口 | `roleBadge()` 里那个「身份不明」的 `?` 徽标本身就是按钮（`data-mark="<座位>"`） |
| 浮层 | `#markMenu`（`position:fixed`，挂在 body 上，不被 `#seats` 重建清掉）：忠臣/反贼/内奸 + 清除 |
| 显示 | 没标过 = 虚线 `?`；标过 = `我判·X`（复用 `.badge.zhong/fan/nei` 配色 + 虚线框） |
| 存储 | `localStorage['sgs_marks:<房间号>:<uid>'] = {"r":<第几局>,"m":{座位:身份}}` |
| 收起 | 点牌桌别处 / `Esc` / 滚动 / 选完身份自动收 |

三条设计决定（每条都有断言钉着）：

1. **只存本地，不进服务端** —— 「别人看不到」靠结构保证，不靠过滤。★X11 断言
   `engine.php` / `api.php` 里**连 `marks` 这个词都不能出现**；★X12 断言标记没有 act/api 出口；
   U3c 断言标记前后请求数不变。
   *注入 G（往 `sgs_public` 塞 `'marks' => []`）→ X11 点名红；注入 H（改成 `act('mark',…)`）→
   X12 + 「act 都有路由」+ U3c 三条点名红。*
2. **键必须带 uid** —— 少了它，同一台机器换个人登录就能读到上一个人的推断。U5 复用同一份
   `localStorage`、只把 uid 换掉，断言第二个人看不到「我判·」。
   *注入 B（键去掉 uid）→ X7 + U4 + U5 点名红。*
3. **开新局作废** —— 身份重新洗牌，旧推断就是错的。
   *注入 C（去掉 round 守卫）→ X8 + U7b 点名红。*

两个容易踩的坑：

- **点徽标不能变成选目标**：`#seats` 的点击委托里 `[data-mark]` 分支必须排在
  `.seat[data-seat]` **之前** —— 身份不明时正是要打这个人的时候，点错一下目标就没了。
  *注入 A（删掉优先分支）→ X6 + U2/U4/U6/U7 等 11 条点名红*（浮层不开，点徽标直接落进选目标）。
- **身份公开后要收掉我的判断**：阵亡亮身份、终局全亮、主公本来就亮 —— 此时同屏出现
  「真身份 + 我的猜测」玩家会看混。★X9 不只数总数，还把范围钉在 `roleBadge` 第一个 `if` 里
  （在 team / 真实身份分支里再挂一个也会红）。
  *注入 D1 → X9 + U8b/U8c 红；注入 D2（入口放宽到"活着的人"）→ X10 + U1b 红。*

**破坏验证**：本批 9 次注入 —— A 优先分支 / B 键少 uid / C 去 round 守卫 / D1 身份公开仍显示 /
D2 入口放宽 / E 忘记收起（→ X15 + U3b + U10）/ F 写入后不重绘（→ U3 + U7 + U8）/
G 服务端泄露 / H 改走请求 —— **9/9 全部「点名变红 + 还原回绿」**，注入锚点一律先
`assert count == 1`。注入器 `/tmp/sgs-mk-inject.py`（snap/restore + 8 模式），
批量跑 `/tmp/sgs-mk-verify.sh`。

**基线**：1876 = 离线 1362（13 套，本批 +38：wiring X 组 +15 / ui-runtime U 组 +23）+ API 514。


## 十二、报障处理：「？标记点击没反应」（2026-09-22）

报障原话：**「？标记点击没反应」**。

第一件事是**先复现**：新版在真实浏览器里点座位卡上的 `?` 是能弹出浮层的（Edge 冒烟 19 条全绿、
浮层位置/虚线/持久化都对）。所以这不是"功能没做"，而是**某条路径没接上**或**页面不是新版**。
逐条排查出四个成因，每个都补了断言：

| # | 成因 | 现象 | 对策 |
|---|---|---|---|
| ① | 入口只在 `#seats` 里认 —— 但 `roleBadge()` **也被「我自己那一栏」(`#meLine`) 调用** | 那一栏渲染出的 `?` 和座位卡上的一模一样，点上去**毫无反应** | document 上挂兜底委托，只接「不在 `#seats` 里」的入口 |
| ② | 浮层按 `bottom+6` 直接摆 | 窄窗/手机上跑到视口外；`#game` 是 `overflow:hidden`，出去就看不见。实测 390 宽时右边界 509，**被裁掉 119px** | 横向夹进视口 + 下方放不下就翻到上方 |
| ③ | 徽标本体 20×20 | 触摸屏上点不准（点旁边一点就落到"选目标"上） | `@media (hover:none)` 把热区外扩到 38×38（伪元素不产生独立 target，桌面行为一点不变） |
| ④ | **页面根本没重新加载** | 这游戏页面是一直挂着的（700ms 长轮询）。我改完文件后旧标签页跑的还是旧 JS —— 旧版的 `?` 本来就是个**死的灰徽标**，点它当然没反应。现象与"功能没做"完全相同 | 版本自检：拿页面自身 `Content-Length` 当指纹，变了就自动重载 |

### ④ 值得单独说：为什么"用户没刷新"要写进代码

协作模式就是「我改文件 → 你在开着的页面里试」，那么"页面还是旧的"必然会反复发生。
把它交给用户记着刷新是不现实的，所以在页面里做了自检：

- **指纹用 `Content-Length`**：PHP 内置服务器 / IIS / Nginx 都会发这个头，不用改后端、
  也不用手工维护版本号常量（那种常量一定会忘记改）。
- **必须连续两次读到同一个新长度才重载**：有些代理动态 gzip，长度每次都不同 ——
  按"单次变化"就重载会变成无限刷新。这条是防御式的，`U19a` 专门钉它。
- **拿不到长度就永不重载**：桩环境、代理剥头都会拿不到 → 宁可不动，也不能误刷（`U20`）。
- **对局中不硬切**：先 toast「页面已更新，正在重连本局…」，1.2 秒后再重载。
  重载是**无损**的 —— 进房间时 URL 已经写了 `?r=<房间号>`，回来 boot 直接 join 回原座位，
  对局一直在服务端跑着。

**端到端证据**（真实浏览器，跑在 `/tmp` 的副本上、不碰真文件）：
改磁盘上的 `index.html` → **30 秒内页面自己重载** → 回来后仍在同一局（`?r=` 还在、座位卡和手牌都齐）。
7/7 全绿。

### 两个自检自纠（都是断言写错，不是产品错）

1. **`U18` 一开始是装饰性的**：第一次点开浮层后再点**同一个**座位走的是 toggle 关闭路径，
   浮层的 `left/top` 根本不会被重算 —— 断言读到的还是上一次的值，注入「取消翻转」也压不红。
   改成点**另一个座位**（`clickMark(3, …)`）才真正测到翻转。
2. **`U20` 一开始也抓不到**：从头就把长度设成"拿不到"的话，把拿不到硬算成 `1` 也永远是 `1`
   （恒定值不触发变化）→ 注入 `n = n || 1` 照样绿。改成**先给一个真实长度当基线、再让长度拿不到**，
   才抓出"代理剥头就误刷"（`reloads=1` 点名红）。

### 破坏验证（8 次，全部「点名变红 → 还原回绿」）

| 注入 | 压红的断言 |
|---|---|
| A 删掉 document 兜底分支 | ★X16 + ★X17 + U16，另带 U3/U4/U4b/U6/U7/U8（整条标记链断） |
| B 兜底不排除 `#seats`（范围放宽） | ★X17 + U3/U4/U4b/U6/U7/U8 —— **点一次"开了又被自己关掉"**，正是报障的现象 |
| C 取消横向夹紧 | ★U17（`left=320px` 溢出） |
| D 取消底部翻转 | ★X18 + ★U18（`top=769px`） |
| E 去掉「两次确认」 | ★X20 + ★U19a（`reloads=1`） |
| F 拿不到长度也当有效值 | ★X21 + ★U20（`reloads=1`） |
| G 对局中硬切 | ★U19c + ★U19d |
| H 触摸热区不放大 | ★X22 |

> B 这一条逼出了一处**桩的失真**：真实浏览器里点座位卡上的徽标，事件会**继续冒泡到 document**
> （那里挂着兜底委托和"点别处收起"）。桩只 fire 座位区那一层的话，"兜底范围写宽了"这种坏行为
> 完全测不到 —— 已让 `clickMark` 也把同一次点击冒泡到 document。

**真实浏览器复核**：视口适配 5/5（桌面/半窗/矮窗/极矮窗/手机竖屏，浮层都完整可见）、
修复复核 8/8（含 CSSOM 里确认 `@media (hover:none)` 的 `::after{inset:-9px}` **真的被解析器接受**、
徽标中心 `elementFromPoint` 就是徽标自己、浮层活过 3 秒不被重绘关掉）、
自动重载 7/7。截图 `/tmp/sgs-mark-diag-shots/`。

**基线**：1892 = 离线 1378（13 套，本批 +16：wiring X 组 +7 / ui-runtime U 组 +9）+ API 514。

---

## 2026-09-22 手机端 UI 重设计（信息分层 / 座位卡层级 / 全局状态条）

**报障**：「手机网页玩，内容显得特别拥挤，信息没有划分清晰没有辨识度，不能一眼即看清全局情况。」

### 设计（全部只动 `index.html` 的 CSS + renderSeats/render，逻辑零改动）

1. **座位卡层级**：左缘**身份色带**（`.seat.r-*` 定义唯一的 `--rc`，`::before` 画带）+
   **首字头像** `.ava`（底色同取 `--rc`，色带与头像永远同色）+
   名字行（顺位号角标 / 正在出牌 / 下一个 / 身份徽标）→ 体力+摘要行（`.srow`）→
   装备/判定行（`.seq`）→ 状态条（`.sact`，空=不占位、有内容=色块一眼可见）。
2. **`#tblInfo` 全局状态条（手机端）**：桌面由 `.center` 承担信息（手机隐藏），
   手机上 `.center` 没了 → 新增常驻条：`第 N 局 / 牌堆 M / ▶ 当前出牌者 / → 下一个`。
   render 只在对局中写内容，非对局清空。
3. **980 断点内**：牌面变量只微调 `--card-w/--card-h`（不在断点外另写第二套尺寸）、
   顺位号角标收紧到 `-5px`（`-8px` 悬出量在手机 8px 内边距下正好顶死屏幕缘，真机实测被切半）。

### 测试（新组：wiring `MB` +8 / ui-runtime `V` +9）

- **MB**（源码契约）：容器挂在 #seats 之前 / 桌面 none→断点 flex / playing 才写 / 四要素齐全 /
  色带 8 种身份类各定义 `--rc` / 头像同取 `var(--rc)` / 断点内 .tnum 覆盖唯一 /
  **★MB8 `--card-w/--card-h` 全 CSS 恰好定义两次**（基础 :root + 980 断点；
  本批踩过的坑：断点外多写一个移动端 `:root` 就是第三次定义，口径分叉，runtime 当场 3 条红）。
- **V**（渲染行为）：状态条文字逐字含服务端下发的出牌者/下一个名字 / 非对局为空 /
  色带类由数据派生（r-B→改队别→r-A；主公 r-zhu；未公开 r-mist）/ 头像 = 名字首字 /
  电脑思考状态条 sact。
- **真机截图**（Playwright + Edge，mobile 390×844 / 360×700，`/tmp/sgs-ui-redesign.js`）：
  5 人局 / 8 人局 / 1v1 三套 18/18 绿 —— 过程抓出 1v1 流程 bug（只点开始、没先补 1 个电脑，
  停在大厅）与顺位号切边，均已修。

### 破坏验证（4 次，全部「点名变红 → 还原回绿」）

| 注入 | 压红的断言 |
|---|---|
| A 桌面状态条改 display:block | MB2 |
| B 色带类恒 r-mist | V4 + V4b + V6 |
| C 状态条去掉牌堆计数 | MB4 + V1（双层同抓） |
| D 断点外第三次定义 --card-w | ★MB8 + P4（旧守卫同抓） |

**基线**：1909 = 离线 1395（13 套，本批 +17：wiring MB 组 +8 / ui-runtime V 组 +9）+ API 514。

## 十二点五、对手区环形三段 + 逆时针连续编号 + 座位卡信息精简（2026-09-22）

需求原话：「对手区：环形三段 = 顶排横排 + 左列竖排 + 右列竖排，中央留空给战场；
编号要逆时针连续编号，任何模式下不得跳号；对手信息精简展示；
其他的让竖屏玩游戏体验更加好。另有：延时判定牌要在即将判定时才提示出不出无懈可击。」

### ① 环形三段：中央那一格由**网格**保证只放战场

- `#seats` 从"一坨 flex"改成 **grid**：`grid-template-areas:"top top top" / "left center right"`，
  两列宽 `--seat-col-w`（桌面 168px / 980 断点 104px），中央单列一格 `minmax(0,1fr)`。
- **出牌展示区（`.fxstage` + `#skflash`）搬进中央那一格**，改 `position:static` 流式排版 ——
  座位卡**结构上就到不了中央**，不再需要"量我的手牌区高度、按像素躲座位"那一套：
  `--me-h` / `--stage-bottom` / `measureMe()` **整套删除**（留着就是会漂移的死代码，
  wiring 与 runtime 各有一条反证钉死"不得复活"）。
- `clearRing()` 只清三段、保住中央格（旧的两处 `$('seats').innerHTML = ''` 会把战场一起清掉）。

### ② 逆时针连续编号：从"我的下家"起取序，而不是按座位号

- 座位在环上的落位**从不按座位号排序** —— 按 `(mySeat+k)%n` 从我的下家逐个取，
  再按 **右列 → 顶排 → 左列** 依次填。按座位号排的话，"我的下家"会落在环的中间，读起来就断了。
- 屏幕方向靠 flex 反转：`.ring-top{row-reverse}`（右→左）、`.ring-right{column-reverse}`（下→上）、
  `.ring-left{column}`（上→下）。三段连起来读 = **整圈逆时针**，1v1 到 8 人局都不跳号。
- 分段表 `RING_SPLIT`（竖屏一列最多 3 张、顶排最多 3 张）+ `ringSplit()` 公式兜底：
  `1:[1,0,0] 2:[0,1,1] 3:[1,1,1] 4:[2,1,1] 5:[3,1,1] 6:[2,2,2] 7:[3,2,2]`。

### ③ 座位卡五层信息（顺序固定）

1. 昵称 + 身份 + 英雄 —— **不再展示是否电脑**（需求原话；机器人回合文案也只是「思考中…」，
   真人托管才挂「托管」徽标。等待页仍标 🤖，那里需要辨认谁可以被移除）
2. 生命 / 手牌数 / 距离
3. 英雄技能名（主动技高亮，说明进 title）
4. 武器**简称**：`EQUIP_ABBR`（青龙偃月刀→青龙、诸葛连弩→连弩、白银狮子→白银…），
   全名进 title —— 座位卡只有一列宽，5 个字会把整行撑爆。防具同口径。
   ⚠️ 引擎配套：`sgs_public()` 新增 **`equipSlots`**（weapon/armor/horse+/horse-），
   前端**不许**按牌名反推槽位 —— 真实牌堆坐骑有名字（的卢/赤兔），按名字猜必然分叉。
5. 其他：`JUDGE_MARK` 判定区单字（乐 / 兵 / ⚡，全名进 title）+ ±1 马（`+1` / `-1`）。

### 测试（wiring `RN` +9 / ui-runtime `RG` +12；改写 9 条受布局影响的旧断言）

- **RN**（源码契约）：grid 三行两列与中央格 / 三段 DOM 序与 flex 反转 / 中央格住战场 /
  `clearRing` 三段清单 / 取序三段填充顺序 / RING_SPLIT 表与兜底 / 反证旧 `.seats` 网格不得并存 /
  五层信息三件套（EQUIP_ABBR + JUDGE_MARK + ±1 马）。
- **RG**（行为，DOM 桩）：4/5/8 人局逐段落位 / **RG5 把 n=2..8 × 每个座位视角穷举**：
  环读序必须 = 从我下家起连续一圈（长度 n-1、无重复、不含我自己）/
  **RG6 顺位号沿环恒 +1（模 n 回绕）** / 反证起点=我的下家（不是座位号最小的）/
  反证换视角起点跟着换 / 装备简称 + 判定单字 + ±1 马的渲染形态。
- **真机几何**（`tests/sgs-layout-shots.js`，Edge + Playwright，8955 端口，
  1v1/4/5/8 人 × 390×844 / 1440×860 = **77 断言**）：wiring/runtime 只能钉结构与取序，
  "摆出来对不对"只有真实排版能回答 ——
  **A** 没有任何座位卡与 `.ring-center` 相交（中央留空给战场）/
  **B** 顶排整体在左右列上方、左列在中央格左侧、右列在右侧 /
  **B3** 左右两列**齐顶**（第一张卡的 y 差 ≤4px）/
  **C** 用真实 rect 验屏幕方向（右列下→上 / 顶排右→左 / 左列上→下）/
  **D** 环上顺位号相邻 +1（模 n 回绕）/ **E** 顺位号常显 /
  **F** 中央看板常驻（真实定时器）：交回合 → 等电脑出牌 → 5 秒 12 次采样
  **中央从不空着**（内容可以被新信息替换，但不许自己消失；箭头该收的时候收）。
  ⚠️ 交回合必须把**弃牌子阶段**也确认掉 ——「结束出牌」在手牌超上限时进的是
  同一个人的弃牌子阶段（end ≠ 回合结束），不弃牌电脑永远不动，F 组会跳过。
  已挂进 `regress.sh --all`。

### 破坏验证（16 次，全部「点名变红 → 还原回绿」，`tests/mutate-ring.py`）

| 注入 | 压红的断言 |
|---|---|
| 取序改回"按座位号排" | RN6 + RG2/RG5/RG6/RG7/RG8 |
| 右列改灌左列的牌（镜像环） | RG1/RG3/RG5/RG6/RG7/RG8（+目标选择/判定区等 13 条连带红） |
| 顶排取消 row-reverse（变顺时针） | RN2 |
| `clearRing` 漏掉 ringRight | RN5 |
| 座位卡加回「电脑」徽标 | 电脑标识 + Z8 |
| 托管徽标漏写 `!p.bot` | 托管徽标守卫 + Z8c |
| `JUDGE_MARK` 清空（判定区回全名） | 判定区渲染 + Y1 |
| `EQUIP_ABBR` 去掉青龙偃月刀 | RN9 + RG9 |
| CSS 复活 `--me-h` | wiring 反证 + M2 |
| JS 复活 `measureMe()` | wiring 反证 + M10 |
| 电脑回合文案回「电脑思考中…」 | 电脑标识 + Z8b + V8 |
| 右列 justify 回 flex-start（卡被推到底边） | RN2b（+真机 B3 会红，见下） |
| endFx 重新摘掉牌面/横幅的 show | JB1 + J4/JP1（runtime 5 条） |
| endFx 重新排淡出定时器 | JB2（+runtime 4 条） |
| 换局不清看板 | JB5 + JP4 |
| 离房不清看板 | JB6 + JB4 |

### 中央战场看板常驻（2026-09-23）

需求原话：「中央战场的提示信息和牌面一直保留，直到新的信息出来再替换」。

- 早先一步播完 `endFx` 就摘掉牌面/横幅的 `show`、再延迟摘整层的 `on` —— 横幅闪一下就没，
  玩家低头看一眼手牌就永久错过了。
- 现在 `endFx` **只收箭头与座位脉动**（那是"此刻"的动画，留着会让牌桌看起来还在打），
  横幅与牌面**留在中央**（`fxHasBoard` 标记看板上有内容）。
- **替换** = 下一步 `playFx` 整块重写 innerHTML（横幅/牌面两边都整块换，不会新旧混搭）。
- **清空只有两个时机**：`clearFxBoard()`，① 换局（`feedFx` 里 `round` 变了 —— 不然新局开局
  挂着上一局的牌）、② 离开房间。别处不许随手清（JB4 数了调用点）。
- 测试：wiring **JB** 组 +6（endFx 不摘 show / 不排淡出定时器 / fxHasBoard / clearFxBoard
  唯一出口 / 换局清 / 离房清）；runtime **JP** 组 +5（播完仍留 / 空轮询不清 / 整块替换 /
  换局清空）+ J4/N4 改写为"播完仍留着"；真机 **F** 组 +12（见上）。
- ⚠️ 破坏验证曾抓出 JB1 是**文本级匹配**（注入改名变量就绕过去了）—— 改成"endFx 体内
  不得出现任何 `classList.remove('show')`"这个行为级契约。

⚠️ **2026-09-23 报障「右列竖排距离顶排空白太多」**：`.ring-right` 是 `column-reverse`，
它的主轴起点在**底部** —— `justify-content:flex-start` 把座位卡推向底边，右列与顶排之间
就空出一整张卡。要贴顶必须 `flex-end`。真机 B3（左右两列齐顶）与 wiring RN2b 都是这条报障
补出来的断言 —— 原 B 组只验了"顶排在两列上方"，验不出"两列没对齐"。

⚠️ 破坏验证抓出两条**装饰性断言**，当场重写：
① 旧 Z8c `!/class="dot gray"…/` —— `.dot` 这个在线点早已删除，正则永远不匹配，注入任何 bug 都是绿的；
  换成"电脑座位不挂托管徽标"（机器人 `sgs_seat_hosted()` 也为真，漏写 `!p.bot` 就会被写成托管代打）。
② 那条断言起初还因为场景里忘了给机器人 `hosted:true` 而压不红 —— **桩的数据必须照真实服务端给**。