驾驶舱交互层重做方案：稳定状态接口（Stable Cockpit Interface, SCI）

2026-10-31 更新： 产品中已删除 LU737 Host、WebSocket 链路和 XPanel gauge（逻辑与仪表改为 MSFS WASM + HTML 显示单元重写，见 REWRITE_PLAN.md）。本文中 Host/gauge 的实现部分只作历史参考；SCI 契约（data/sci/contract）、Zibo profile 与模型行为保持不变，是重写版要实现的接口；Host 作为测试基准（oracle）保留，--sci-test 脚本继续可用。

状态日期：2026-10-31。适用：LU737 (737-800) MSFS 2024 ↔ xphost ↔ Zibo 2.S1.50（xlua 脚本 + zibomod.xpl）。

实施进度：全部控件与驾驶舱状态已迁移（P0–P6，旧路径已删除），通过离线测试。实现与本设计的差异（事件按名称发送、名称表代替契约哈希、写回 X-Plane 的电气量取自合成模型等）及实测结论见 docs/SCI_IMPLEMENTATION.md。

本文是可直接落地的重做方案，取代当前"MSFS 直接读写 laminar/B738/*"的做法。 前 4 节定义接口与实现，第 5–7 节是验证、分期与 Zibo 2.S1.50 兼容策略。

0. 现状诊断（以本仓库代码为依据）#

结论：问题不在单个按钮，而在缺少一层语义稳定、带闭环确认的状态模型。

1. 新架构（文字架构图）#

┌──────────────────────────── MSFS 2024 ────────────────────────────┐
│                                                                    │
│  3D 模型 (LU738_INTERIOR.xml，由 SCI 契约生成)                      │
│   MouseRect ──► (>H:LU737_<CTL>_<ACT>)        只发稳定 H: 事件      │
│   Animation  ◄── (L:LU737_<CTL>_POS / _GRD / _BTN)                  │
│   Emissive   ◄── (L:LU737_ANN_* / L:LU737_LT_* / L:LU737_DU_*_PWR)  │
│   Visibility ◄── 同上（只读 SCI L:）                                │
│                                                                    │
│  XPanel Gauge（瘦中继，不含任何 laminar/B738 名称）                 │
│   onInteractionEvent(H:LU737_*) ─► 编码为 CTL_EVENT(id, act, arg)  │
│   收到 STATE_DELTA ─► SimVar.SetSimVarValue(L:LU737_*)             │
│   面板渲染：按 L:LU737_DU_<n>_PWR 决定是否绘制该 DU 的内容          │
│   (现有 SimBridge：MSFS 物理 SimVar ↔ sim/* 保持不变)               │
└──────────────────────────────┬─────────────────────────────────────┘
                               │ ws://127.0.0.1:52737（现有链路，新增 0x1x/0x9x 帧）
┌──────────────────────────────▼─────────────────────────────────────┐
│ LU737Host (xphost)                                                  │
│                                                                     │
│  ┌─ SCI 层（新，版本无关）──────────────────────────────────────┐   │
│  │ ControlRegistry   控件定义：id、类型、位置枚举、护盖关系      │   │
│  │ StateTable        稳定状态：值 + 质量(OK/ALIAS/SYNTH/SHADOW/   │   │
│  │                   MISSING) + 来源 + 最后变化时间              │   │
│  │ EventRouter       事件 → 意图(intent)：SET pos / PRESS / ...  │   │
│  │ ClosedLoop        每个意图的期望状态、超时、结果、日志         │   │
│  │ ElecModel         合成电气状态机（总线/供电/DU/灯），与 Zibo   │   │
│  │                   自身状态交叉校验                             │   │
│  └───────────────────────────┬──────────────────────────────────┘   │
│  ┌─ Zibo 适配层（随 Zibo 版本替换）▼────────────────────────────┐   │
│  │ profiles/zibo_2S1_50/*.json  绑定：命令(begin/end/once)、     │   │
│  │                              DataRef(含别名链)、合成表达式     │   │
│  │ ProfileLoader + Probe        启动时解析每个绑定 → 解析报告     │   │
│  └───────────────────────────┬──────────────────────────────────┘   │
│  ┌─ 现有 XPLM 仿真（缩减为插件运行所需的最小集）▼───────────────┐   │
│  │ core / xplm_api / xpsim：DataRef、Command、FlightLoop         │   │
│  │ xpsim 的电气合成改为从 ElecModel 输出 sim/cockpit2/electrical/*│   │
│  └───────────────────────────┬──────────────────────────────────┘   │
│                  xlua.xpl + Zibo Lua ▼  zibomod.xpl（不修改）        │
└─────────────────────────────────────────────────────────────────────┘

单一事实来源（仓库内）：
  data/sci/contract/*.json   ← 稳定契约：控件、状态、事件（版本无关）
  data/sci/profiles/zibo_2S1_50/*.json ← Zibo 绑定（版本相关，只有 Host 读）
生成物：
  tools/msfs/generate_behaviors.py --sci   → 模型行为 XML（只引用契约）
  avionics/generated/sci_ids.json          → gauge 用的 id ↔ L: 名称表
  xphost 运行时加载 profile（换 Zibo 版本无需重新编译、无需重新生成 MSFS 包）

1.1 职责划分（硬性规则）#

1.2 为什么由 Host（而不是 gauge）做适配#

• Host 与插件在同一进程、同一帧内：发命令、跑一帧、读 DataRef 是原子的，闭环确认不受 WebSocket 延迟影响。
• 适配表换版本只改 Host 读取的 JSON，MSFS 包（glTF + XML + JS）不需重建。
• Gauge 只做中继：H: 事件是 MSFS 中只有 gauge 能接收的东西（onInteractionEvent），L: 写入也只有 gauge 能做，所以 gauge 必须保留，但不含逻辑。

2. 稳定状态表#

2.1 数据模型#

每个稳定状态（State）：

所有值统一为 f64，编码规则：

• pos：整数下标 0..n-1，与 Zibo 的取值无关（例如 Zibo 的 -1/0/1 由 profile 映射为 0/1/2）。
• guard：0 闭合，1 打开；Host 可输出中间值用于动画（0..1）。
• btn：0 未按下，1 按下（按钮的机械行程，不是逻辑状态）。
• ann：0..1 亮度，已包含供电、灯测试（LIGHTS TEST）与 DIM/BRT 的结果——模型只做 EmissiveFactor = (L:LU737_ANN_x)。
• bus/pwr：0 无电 / 1 有电（合成量）。
• 角度类旋钮：输出 0..1 的归一化角度，模型动画长度固定按契约中的 anim 映射。

2.2 最小必要集合（Phase 1–2 必须实现，约 140 项）#

A. 电气总线与供电（全部合成量，kind=bus/pwr）#

B. 仪表 / 屏幕供电（kind=pwr，gauge 与模型据此决定渲染/发光）#

规则：主来源可用且自洽时用主来源；主来源缺失 → 用合成；二者不一致 → 用主来源并记 MISMATCH 日志。 这样 Zibo 自己的逻辑（例如电瓶下 FO DU 为空白）被完整保留，Zibo 缺量时又不会整片黑屏。

C. 开关/旋钮/护盖位置（以 Phase 1 电气面板为例，其他面板同模式）#

D. 关键指示灯（kind=ann，值已含供电与灯测试）#

电气面板：ANN_BAT_DISCHARGE、ANN_TR_UNIT、ANN_ELEC、ANN_STBY_PWR_OFF、ANN_GRD_PWR_AVAIL、ANN_DRIVE1/2、ANN_TRANS_BUS_OFF1/2、ANN_SOURCE_OFF1/2、ANN_GEN_OFF_BUS1/2、ANN_APU_GEN_OFF_BUS、ANN_APU_MAINT/LOW_OIL/FAULT/OVERSPEED。 全局：ANN_MASTER_CAUTION_CPT/FO、ANN_FIRE_WARN_CPT/FO、六组 Six-Pack（ANN_SIXPACK_<ELEC|APU|FUEL|...>）。 MCP：ANN_MCP_<BTN>（每个 MCP 按钮的绿条）。

合成通用式（Host 内）：

ann = clamp01( (logic ∨ (lights_test ∧ bus(ann.bus))) ∧ bus(ann.bus) ) × dim(ann.dim_group)

logic 的主来源是 Zibo laminar/B738/annunciator/*（Zibo 已在其中处理测试与亮度时，profile 声明 includes_test=true / includes_dim=true，Host 不重复处理）。

E. 照明（kind=lt）#

LT_PANEL_CPT、LT_PANEL_FO、LT_PANEL_OVHD、LT_PANEL_PED、LT_FLOOD_*、LT_DOME、LT_BACKLIGHT_<group>：值 = 旋钮位置 × 对应总线有电。现有 L:LU737_default_lit 迁移为 LT_*。

2.3 扩展集合（Phase 3–5）#

按面板分组，名称前缀即分组：

数量预估：控件约 420 个（现有 991 个点击区按控件合并后），稳定状态约 900 项（位置+护盖+按钮约 520，指示灯约 210，供电/总线约 50，数值约 120）。

3. 命名规范#

3.1 通用规则#

• 前缀固定 LU737_；其余全大写，下划线分隔：LU737_<PANEL>_<CONTROL>[_<SUB>]_<SUFFIX>。
• PANEL 取 §2.3 表中的前缀（ELEC、FUEL、MCP、EFIS_CPT…）。
• 双侧控件以 _CPT/_FO（人员侧）或 1/2、_L/_R（系统侧）区分，不用 Zibo 的 capt/cpt/pilot 混用写法。
• 名称一经发布不得改名；废弃名保留到下一大版本，并在契约中标 deprecated。

3.2 L: 变量（Host → MSFS，只读给模型）#

MSFS 侧唯一可写的 L:：LU737_IN_*（输入暂存，见 3.3 拖动）与用户偏好（LU737_DU_GAIN）。模型绝不写 _POS/_GRD/_BTN/_KNOB。

3.3 H: 事件（MSFS → Host）#

格式：H:LU737_<PANEL>_<CONTROL>_<ACTION>

示例：H:LU737_ELEC_BAT_TOGGLE、H:LU737_ELEC_GEN1_SET_0、H:LU737_ELEC_GEN1_RELEASE、H:LU737_ELEC_BAT_GUARD_TOGGLE、H:LU737_EFIS_CPT_RANGE_INC、H:LU737_MCP_HDG_INC_FAST、H:LU737_PED_FLAP_LEVER_DRAG。

3.4 鼠标与事件的标准映射（生成器统一套用）#

4. Host 适配层：核心逻辑#

4.1 契约文件（版本无关）data/sci/contract/elec.json 片段#

{
  "controls": [
    {"id": "ELEC_BAT", "type": "switch2", "enum": ["OFF", "ON"],
     "guard": "ELEC_BAT_GRD", "guard_blocks": true},
    {"id": "ELEC_GEN1", "type": "switch3_spring", "enum": ["OFF", "NEUTRAL", "ON"],
     "rest": "NEUTRAL"},
    {"id": "ELEC_STBY_PWR", "type": "switch3", "enum": ["BAT", "OFF", "AUTO"],
     "guard": "ELEC_STBY_PWR_GRD", "guard_blocks": true},
    {"id": "APU_SW", "type": "switch3_spring_end", "enum": ["OFF", "ON", "START"],
     "spring": {"from": "START", "to": "ON"}}
  ],
  "states": [
    {"name": "ELEC_BAT_POS", "kind": "pos", "enum": ["OFF", "ON"], "default": 0},
    {"name": "ELEC_BAT_GRD", "kind": "guard", "default": 0},
    {"name": "BUS_XFR1", "kind": "bus", "default": 0},
    {"name": "DU_FO_OUTBD_PWR", "kind": "pwr", "default": 0},
    {"name": "ANN_SOURCE_OFF1", "kind": "ann", "bus": "BUS_DC1", "test": true, "dim": "ANN"}
  ]
}

4.2 Zibo 绑定文件（版本相关）data/sci/profiles/zibo_2S1_50/elec.json 片段#

{
  "profile": "zibo_2S1_50",
  "bindings": {
    "ELEC_BAT": {
      "read": [{"dref": "laminar/B738/electric/battery_pos", "map": {"0": 0, "1": 1}}],
      "drive": {"mode": "step_pair",
                "inc": "laminar/B738/switch/battery_up",
                "dec": "laminar/B738/switch/battery_dn"}
    },
    "ELEC_BAT_GRD": {
      "read": [{"dref": "laminar/B738/button_switch/cover_position[?]", "probe": "cover_index"}],
      "drive": {"mode": "toggle", "cmd": "laminar/B738/button_switch_cover??"},
      "fallback": "shadow"
    },
    "ELEC_GEN1": {
      "read": [{"dref": "laminar/B738/electrical/gen1_pos", "map": {"-1": 0, "0": 1, "1": 2}}],
      "drive": {"mode": "spring_hold",
                "to": {"OFF": "laminar/B738/toggle_switch/gen1_dn",
                       "ON":  "laminar/B738/toggle_switch/gen1_up"}}
    },
    "APU_SW": {
      "read": [{"dref": "laminar/B738/spring_toggle_switch/APU_start_pos"}],
      "drive": {"mode": "step_pair",
                "inc": "laminar/B738/spring_toggle_switch/APU_start_pos_up",
                "dec": "laminar/B738/spring_toggle_switch/APU_start_pos_dn",
                "hold_last_step": "START"},
      "effects": [{"when": "START held", "expect": "SRC_APU_RUNNING", "within_s": 5,
                   "else": "x_apu_start"}]
    },
    "BUS_XFR1": {
      "read": [{"dref": "laminar/B738/electric/ac_tnsbus1_status", "gt": 0.5}],
      "synth": "elec.xfr1"
    },
    "DU_FO_OUTBD_PWR": {
      "read": [{"dref": "laminar/B738/display_units/odu_fo", "ge": 0}],
      "synth": "elec.load('DU_FO_OUTBD')"
    },
    "ANN_SOURCE_OFF1": {
      "read": [{"dref": "laminar/B738/annunciator/source_off1", "includes_test": true}],
      "synth": "!elec.xfr1_from_side1 && bus('BUS_DC1')"
    }
  }
}

read 是别名链：按顺序尝试，第一个能解析的生效（OK/ALIAS），全部失败再走 synth（SYNTH）或 shadow（SHADOW），都没有则 MISSING + 契约默认值。

4.3 驱动模式（把“意图”翻译成正确的 begin/end/once）#

护盖联动（guard_blocks=true）：护盖闭合时对开关的任何意图先转为 GUARD_OPEN，不直接下发开关命令（真实行为，也避免 Zibo 因护盖闭合忽略命令导致“点了没反应”）。

begin/end 不变量（Host 强制）：

1. 同一命令同一时刻最多一个持有者；重复 begin 被合并（计数，不重复调用插件）。
2. 每个 begin 必有一个 end：来源可以是 RELEASE、once 的下一帧、超时、链路断开（releaseCommands()）。
3. once 至少跨一个插件帧（begin → frame → end），因为 Zibo 很多命令在 phase==1（continue）或 flight loop 中才处理。

4.4 核心伪代码#

// ---------- 启动 ----------
Contract C = loadContract("data/sci/contract/*.json");      // 版本无关
Profile  P = loadProfile(ini.profile /* "zibo_2S1_50" */);   // 版本相关
for (State &s : C.states) {
    Binding *b = P.find(s.name);
    s.reader = resolveReadChain(b);          // 依次 Host::find(dref)；记录哪个别名命中
    s.quality = s.reader ? (s.reader->isPrimary ? OK : ALIAS)
              : b && b->synth ? SYNTH
              : b && b->fallback == "shadow" ? SHADOW : MISSING;
}
for (Control &c : C.controls) c.driver = makeDriver(P.find(c.id));  // 解析命令；缺失 → UNBOUND
writeResolutionReport("LU737Host_sci_report.txt");  // 每项：名称 / 质量 / 命中的 DataRef / 命令

// ---------- 每帧（gauge 的 FRAME 到达时） ----------
void Sci::frame(double dt) {
    for (Event &e : inbox) router.dispatch(e);  // 事件 → 意图（Intent），打 seq
    for (Intent &i : active) i.driver->step(i); // 下发 begin/once/end
    host.frame(dt);                             // 插件跑一帧（现有）
    for (Intent &i : active) i.driver->settle(i);  // 结束本帧的 once
    elec.update(stateTable, dt);                // 合成电气（读开关、源、MSFS 物理量）
    for (State &s : C.states) {
        double v = s.reader ? s.map(s.reader->get())
                 : s.quality == SYNTH  ? eval(s.synth)
                 : s.quality == SHADOW ? shadow[s.name]
                 : s.def;
        if (s.reader && s.synthCheck) crossCheck(s, v, eval(s.synth)); // MISMATCH 日志（限频）
        if (v != s.value) { s.value = v; s.t_change = now; delta.push(s.id, v); }
    }
    for (Intent &i : active) closedLoop.check(i);  // §4.5
    send(STATE_DELTA{seq, delta}, ACKS{...});
}

// ---------- 意图驱动（step_pair 例） ----------
void StepPair::step(Intent &i) {
    int cur = state(i.ctl.posState);
    if (cur == i.target) { i.done = true; return; }
    if (i.steps++ >= i.maxSteps) { i.fail("STUCK", cur); return; }
    Command *c = (i.target > cur) ? inc : dec;
    host.commandBegin(c); endAfterFrame.push(c);      // once = 跨一帧
}

// ---------- 影子状态（SHADOW） ----------
// 位置 DataRef 缺失但命令存在：Host 以“已执行且未被拒绝的意图”更新影子值，
// 并在启动/冷暗复位时置契约默认值。

4.5 闭环判定与日志#

每个意图（Intent）都有结果，写入日志并通过 ACK 帧回传：

日志格式（一行一事件，便于 grep 与自动比对）：

[sci] t=123.456 seq=812 EV  ELEC_BAT TOGGLE
[sci] t=123.456 seq=812 CMD laminar/B738/switch/battery_up once
[sci] t=123.489 seq=812 ST  ELEC_BAT_POS 0->1 (OK dref laminar/B738/electric/battery_pos)
[sci] t=123.489 seq=812 ST  BUS_BAT 0->1 (SYNTH elec) ; BUS_AC_STBY 0->1 ; DU_CPT_OUTBD_PWR 0->1 (OK)
[sci] t=123.489 seq=812 RES OK 1 frame

lu737host.ini 新增：sci_log = off|events|states|all、sci_profile = zibo_2S1_50、sci_trace = ELEC_*,APU_*（通配过滤）。

4.6 电气状态机（ElecModel，合成，不依赖易变 DataRef）#

输入（全部是稳定状态或 MSFS 物理量）：开关位置（BAT、STBY PWR、GPU、GEN1/2、APU GEN1/2、BUS TRANS、DRIVE DISC、CAB UTIL、IFE）、SRC_GPU_AVAIL、APU N%（MSFS APU PCT RPM 或 Zibo APU 量）、发动机 N2（MSFS）、电瓶电量（Host 积分）。

锁存状态（737NG 的 GEN/GPU/APU GEN 是瞬时开关，“谁在供电”是锁存的）：

src_xfr1, src_xfr2 ∈ {NONE, GPU, APU, IDG1, IDG2}
on GPU_SW→ON   : if GPU_AVAIL { src_xfr1 = src_xfr2 = GPU }
on APUGEN1→ON  : if APU_GEN_RDY { src_xfr1 = APU; if src_xfr2 == GPU: src_xfr2 = APU }
on APUGEN2→ON  : 对称
on GEN1→ON     : if IDG1_RDY { src_xfr1 = IDG1 }      (GEN2 对称)
on *→OFF       : 对应侧断开 → 若 BUS_TRANS=AUTO 且另一侧有 IDG/APU，经 BTB 由另一侧供电
on 源失效       : (GPU 撤除 / APU 停车 / 发动机停车 / IDG 脱开) 对应 src = NONE
on BAT→OFF 且无 AC : 全部 NONE

总线方程：

XFR1 = src_xfr1 != NONE || (BUS_TRANS==AUTO && src_xfr2 in {APU,IDG2})
XFR2 = 对称
TRU1 = XFR1, TRU2 = XFR2, TRU3 = XFR2 || (BUS_TRANS==AUTO && XFR1)
DC1  = TRU1 || (TRU3 && BUS_TRANS==AUTO)       DC2 = TRU2 || TRU3
BAT  = BAT_SW && (bat_charge>0 || DC1 || DC2)
HOT_BAT = bat_charge > 0                        SW_HOT_BAT = HOT_BAT && BAT_SW
DC_STBY = DC1 || (BAT && STBY_PWR != OFF && (STBY_PWR==BAT || !DC1))
AC_STBY = XFR1 || (BAT && STBY_PWR != OFF && (STBY_PWR==BAT || !XFR1))   // 静变流机
MAINx   = XFRx && !CAB_UTIL_OFF

状态 ELEC_STATE：COLD_DARK(无任何总线) → BAT_ONLY(仅 BAT/STBY) → GPU / APU / ENG / MIXED（按 src_xfr1/2 组合）。状态切换都写 [sci] ELEC 日志，便于对照冷暗启动流程。

负载表（设备 → 总线，作为 _PWR 的合成回退；主来源仍是 Zibo 量）：

向下兼容 X-Plane 自带量：现有 xpsim.cpp 中按开关位置推 bus_volts 的代码删除，改为由 ElecModel 写：

sim/cockpit2/electrical/bus_volts[0..3]   = 28 × {DC1, DC2, DC_STBY, BAT}
sim/cockpit2/electrical/battery_on[0]     = BAT_SW
sim/cockpit/electrical/avionics_on        = DC1 || DC2 || DC_STBY
sim/cockpit2/electrical/generator_on[i]   = src 中含 IDGi
sim/cockpit2/electrical/APU_generator_on  = src 中含 APU
sim/cockpit/electrical/gpu_on             = src 中含 GPU

插件（Zibo）自己读取这些 X-Plane 量时得到的是物理一致的结果，而不是“开关拨过了”。

4.7 与 MSFS 物理的边界#

不变：飞行物理、推力、燃油量、起落架/襟翼实际位置仍由 MSFS 计算（现有 SimBridge）。SCI 只负责驾驶舱控件与驾驶舱显示状态。 油门杆/驾驶盘/方向舵：位置来自 MSFS 硬件轴（A:），SCI 仅输出其上的按钮（TOGA、A/T DISC、AP DISC、配平电门）。

4.8 线协议（在现有 WebSocket 帧格式上扩展）#

沿用 bridge.h 的小端二进制格式，新增类型，不影响现有 0x01–0x06 / 0x80–0x85：

MSFS → Host

0x10 SCI_HELLO   u32 contract_hash, u16 n_states, u16 n_controls   // 契约版本校验
0x11 SCI_EVENT   u32 seq, u16 control_id, u8 action, f32 arg       // arg: SET 的 n、DRAG 的值、INC 的倍数
0x12 SCI_RESYNC  —                                                 // 请求全量快照（gauge 重载/切换飞机/暂停恢复）

action：1 PRESS, 2 RELEASE, 3 TOGGLE, 4 INC, 5 DEC, 6 INC_FAST, 7 DEC_FAST, 8 SET, 9 GUARD_OPEN, 10 GUARD_CLOSE, 11 GUARD_TOGGLE, 12 PUSH, 13 DRAG。 多个 SCI_EVENT 可在同一 WebSocket 消息中拼接，并随下一 FRAME 一起处理（Host 在 h.frame(dt) 之前分派）。

Host → MSFS（作为 0x80 FRAME 回复中的新 section）

0x90 SCI_SNAPSHOT u32 frame, u16 n, n × (u16 state_id, f64 value)            // HELLO/RESYNC 后
0x91 SCI_DELTA    u32 frame, u16 n, n × (u16 state_id, f64 value)            // 每帧只发变化
0x92 SCI_ACK      u16 n, n × (u32 seq, u8 result, u16 frames)                // §4.5 结果
0x93 SCI_QUALITY  u16 n, n × (u16 state_id, u8 quality)                      // 启动时一次 + 变化时

频率：与现有 FRAME 同步（每个 MSFS 帧一次，30–60 Hz），一帧往返；DELTA 平均 < 20 项。 contract_hash 不一致时 Host 拒绝 SCI（只记日志），gauge 显示 LU737 SCI CONTRACT MISMATCH，避免新旧包混用造成错位。

4.9 Gauge 改动（avionics/src/instruments/xpanel/index.ts）#

• 删除 model_io.json 的 lvars/writes/hevents 路径与 H:LU737_W<n> 机制。
• onInteractionEvent：解析 LU737_<CTL>_<ACT> → 查 sci_ids.json → 发送 0x11。不认识的事件记一次控制台警告。
• 收到 0x90/0x91：SimVar.SetSimVarValue('L:LU737_' + name, 'number', v)（只写变化值）。
• 链路断开时：L:LU737_SYS_LINK=0，所有 _PWR/ANN_*/BUS_* 置 0（防止断线后假亮），位置类保持最后值。
• 面板渲染：每个 DU 的绘制区域在 L:LU737_DU_<n>_PWR == 0 时清为黑色并跳过该区域的指令（同时减少负载）；DU 材质 EmissiveFactor = PWR × 亮度 × DU_GAIN。

4.10 模型行为生成（tools/msfs/generate_behaviors.py --sci）#

新增一张点击区 → 控件的映射表 data/sci/clickspots.json（由现有 991 个点击区自动初分组，再人工校对）：

{"node": "switch_battery", "control": "ELEC_BAT", "region": "full"},
{"node": "cover_battery",  "control": "ELEC_BAT_GRD", "region": "full"},
{"node": "knob_dc_power",  "control": "ELEC_DC_METER", "region": "left_right"}

以及动画 → 稳定状态映射 data/sci/animations.json（OBJ 中驱动动画的 Zibo DataRef → 稳定状态 + 值映射），生成器据此输出：

<Animation Name="laminar_B738_electric_battery_pos" Length="100" Type="Sim" TypeParam="AutoPlay">
  <Parameter><Code>(L:LU737_ELEC_BAT_POS) 100 *</Code><Lag>400</Lag></Parameter>
</Animation>
<MouseRect>
  <Cursor>Hand</Cursor><MouseFlags>LeftSingle+RightSingle+WheelUp+WheelDown</MouseFlags>
  <CallbackCode>
    (M:Event) 'WheelUp' scmp 0 == if{ (>H:LU737_ELEC_BAT_SET_1) quit }
    (M:Event) 'WheelDown' scmp 0 == if{ (>H:LU737_ELEC_BAT_SET_0) quit }
    (>H:LU737_ELEC_BAT_TOGGLE)
  </CallbackCode>
</MouseRect>

生成器的静态检查（构建失败条件）：

1. 任何行为代码中出现 laminar/、LU737_ 后跟小写字母的旧名 → 失败。
2. 每个可点击节点必须映射到一个控件；每个控件至少有一个可见的 _POS/_GRD/_BTN/_KNOB 动画或明确标注 no_anim。
3. 每个 ANN_* 至少驱动一个发光节点；每个带发光的指示灯节点必须由 ANN_*/LT_* 驱动。
4. 未映射的 OBJ 动画 DataRef 列表输出到 build/sci_unmapped.txt（应为空或全部 ignore）。

5. 闭环验证清单#

5.1 自动化（无 MSFS，CI 可跑）#

xphost 增加 --sci-selftest（Linux 版 + lin_x64 插件，现有测试方式）：

1. 解析报告：所有状态 quality != MISSING；ALIAS/SYNTH/SHADOW 列表与 profile 预期一致（快照比对文件 xphost/test/sci_expected_quality.txt）。
2. 逐控件扫遍：对契约中每个控件、每个位置执行 SET n，断言：
   • RES OK（或 OK_SHADOW）在 ≤ 3 帧内；
   • _POS 等于 n；
   • profile 声明的 effects 在时限内出现。
3. 护盖：护盖闭合时 SET → BLOCKED_GUARD 且护盖打开；开盖后 SET 生效。
4. 按住语义：PRESS 后保持 N 帧，断言命令 held>0 持续 N 帧，RELEASE 后为 0；丢失 RELEASE 时 20 s 超时释放。
5. 冷暗上电脚本（断言每一步的总线与 _PWR）：

6. 缺量注入：用 --sci-hide-dref <pattern> 在 Host 中隐藏 DataRef（模拟 Zibo 改名/缺失），重跑 2 和 5：结果必须仍然通过（质量降为 ALIAS/SYNTH/SHADOW），不得出现大面积 _PWR=0。
7. 契约一致性：生成器静态检查（§4.10）。

5.2 Gauge 侧（avionics 的 vitest + 现有 harness）#

• 事件编码：每个契约 H: 名 → 正确的 (control_id, action, arg)。
• DELTA 应用：只写变化值；断线时 _PWR/ANN/BUS 清零。
• 渲染门控：_PWR=0 的 DU 区域为黑（截图比对现有 harness 输出）。

5.3 机上（MSFS 2024）逐面板验收表#

每个控件一行，测试员只需看三列（日志自动给出前两列）：

辅助：

• Host 控制台 sci_trace=* 时，每次点击打印完整闭环一行汇总：[sci] ELEC_BAT TOGGLE → OK 1f | POS 0→1 | BUS_BAT 0→1 | DU_CPT_OUTBD_PWR 0→1。
• Gauge 调试覆盖层（L:LU737_SYS_DEBUG=1）：在 Panel 角落显示最近 8 个 ACK 与非 OK 结果。
• 判定规则：任何点击若 ACK 不是 OK*/BLOCKED_GUARD，或 ST 变了但无视觉变化（模型映射错）→ 记缺陷，附日志行。

6. 分阶段实施计划#

每阶段完成标准：§5.1 自动化全绿 + §5.3 该阶段面板机上验收通过。旧路径（model_io.json）在过渡期仍可工作：生成器按控件逐个切换，已迁移控件的点击区只发 SCI 事件，未迁移的保持旧事件。

优先打通的 12 个“验证样板”控件（P1 第一天）：BAT（含护盖）、STBY PWR（含护盖）、GPU、APU GEN1、GEN1、BUS TRANS、DC/AC 表选择钮、APU 开关、LIGHTS TEST、MCP CMD A、EFIS CPT RANGE、襟翼手柄。它们覆盖全部驱动模式（toggle、step_pair、spring_hold、hold、once、护盖、多位、杆），模式打通后其余控件只是填表。

7. Zibo 2.S1.50 已知缺失/改名 DataRef 的处理策略#

7.1 先测量，不靠猜：Probe#

Host 启动（或 --sci-probe）时，在插件加载完、跑 N 帧之后输出：

• profile 中每个 DataRef/命令：FOUND / NOT_FOUND / FOUND_BUT_STATIC（N 帧内从未变化且等于 0，疑似“定义了但不再更新”）。
• 插件实际注册的、名称与缺失项相似（编辑距离/同目录）的候选，供人工补别名。
• 对点击区扫遍时“命令执行了但没有任何 DataRef 变化”的命令列表（疑似废弃命令）。

输出 LU737Host_sci_probe.txt，作为 profile 更新的依据。每个 Zibo 版本一个 profile 目录，可以继承："extends": "zibo_2S1_40"，只写差异。

7.2 分级策略#

7.3 隔离原则（保证“单个 DataRef 缺失不导致大面积失效”）#

1. 逐项解析、逐项降级：一个绑定失败只影响该状态；其余状态照常更新（不再出现一个 find() 失败导致整块逻辑跳过）。
2. 供电门控永不依赖单一 DataRef：每个 _PWR 都有 ElecModel 合成回退；BUS_* 本身就是合成量。
3. 默认值偏向“可用”而非“全黑”的仅限显示：_PWR 在主来源缺失时取合成值（物理一致），而不是取 0；指示灯缺失时取 0（不假亮）。
4. 不一致时信 Zibo，但记录：主来源与合成不一致只记日志（限频，每状态每 10 s 一次），不覆盖 Zibo 的逻辑结果——Zibo 的特殊逻辑（例如电瓶下 FO DU 空白、DU 自检）得以保留。
5. 契约哈希 + profile 版本写入日志头：任何用户日志都能看出所用 Zibo profile 与解析质量。

7.4 Zibo 升级流程（目标：MSFS 资源零改动）#

1. 新 Zibo 放入 plugins/，运行 LU737Host --sci-probe --sci-profile zibo_<new>（新目录 extends 旧 profile）。
2. 按探测报告补别名/合成/影子；运行 --sci-selftest 至全绿。
3. 只发布 Host 与 profile；MSFS 包无需重建（契约哈希不变）。
4. 只有当 Zibo 新增了真实存在的新控件时才扩展契约（追加 id，不重排），此时才需要重新生成模型行为。

附：与现有代码的对照#