X02 · Studio 配置模式——基础文件

类型基础状态草案版本R0.2更新2026-09-14

Air/Key 实施范围（2026-09-10）：配置对象需按当前产品能力过滤；见 Air 指南及 Key 指南。基础 Air Hub 不因本文件含独立模式/Tag 对象就支持对应扩展；本次不改字段定义，ICD 冻结时核对当前型号、手势时序与能力。

适用范围: CORE-27、CORE-43、CORE-DO、SENSE、KEY、AIR-HUB(含独立模式)、HUB、VIEW;Air 开关与 Tag 仅作为 AIR-HUB 的 endpoints 出现
引用的基础文件: X01-ybo-can-protocol.md、X02-config-schema.md
状态: 草案 (t)
基线标识: X02@2026-09-10——Air/Key 供应商交付所引用的基线;正式修订号在 D1 由 YBO 指定
最后更新: 2026-08-28

1. 范围与归属

参与方	负责	绝不做
Studio(`P07-studio.md` §5)	唯一的 JSON 模式、bundle、校验(§9)、文档与版本链;模板、虚拟船、生产模式构建清单(`P07-studio.md` FR-21/22)。Level-1 数值只引用、不重新定义;本文件选定的每个设计值均为 (t) 并列于 §11	运行时控制;单独关闭 HD 馈电 / >25 A 决策(`P07-studio.md` §1)
Hub(`P03-mate.md` §6)	部署端点:验证签名、保存 N 个历史版本、将 bundle 拆分为各节点的 `CFG` 片段(`X01-ybo-can-protocol.md` §4)、任一节点 NACK 即原子化中止	编辑 bundle;接受未签名、重放或模式降级的 bundle(`P07-studio.md` FR-25)
节点	验证自身片段(签名、模式主版本、能力匹配、额定值与硬件型号 ID 比对——`P01-core.md` FR-19),带 CRC 存入 NVM,在无 Hub 时执行本地逻辑	通过配置提高额定值或脉冲上限(`P01-core.md` FR-13/FR-19)
独立模式 `AIR-HUB`(扩展,`P05-air-hub-design.md` §2.4)	仅对自身承担 Hub 角色:验证并保存经 BLE/Wi-Fi 从 Studio/Mate 收到的自身片段	配置任何其他节点(独立套件 = 网关 + 开关,product-plan.md §6 第 11 项)

2. 文档模型

bundle.json  = { "manifest": {...}, "vessel": {...}, "buses": [...], "nodes": [...], "channels": [...],
                 "inputs": [...], "bindings": [...], "scenes": [...], "protection_presets": [...],
                 "alarm_rules": [...], "ac_policy": {...}, "permissions": {...} }
bundle.sig   = ECDSA P-256 *(t)* over SHA-256(canonical JSON of bundle.json, RFC 8785 JCS *(t)*)
version chain: v(n).manifest.previous_version_id -> v(n-1).manifest.version_id -> ... (Hub keeps N = 10 *(t), P07 §5)

规则	定义	来源
模式版本与身份	`schema_version` = `major.minor.patch`(semver):minor 为向后兼容的新增,major 变更须附带迁移脚本,patch 仅为编辑性修改 (t);`bundle_id` 为 UUIDv7 (t),`version_id` 按船体单调递增	`P07-studio.md` §5、FR-18
逐节点哈希	`manifest.node_hashes[node_ref]` = 该节点规范化片段的 SHA-256;节点在 `STATE`/`DIAG` 中回显(`X01-ybo-can-protocol.md` §4),使 Studio、Hub、PDF 与交付包比对同一个值	`P07-studio.md` FR-17、`P02-sense.md` FR-24
签名	用户密钥对 `bundle_hash` 签名;在线时云端附加副署(`cloud_countersignature`,离线时可选);Hub 与节点用预置密钥验证;单调递增的 `version_id` 防止重放	`P07-studio.md` FR-25
不可变性	已部署版本绝不编辑;每次部署(含回滚)都产生新的 `version_id`,并设置 `previous_version_id`,适用时设置 `rollback_of`	`P07-studio.md` FR-18/FR-20
保留	Hub 保留最近 10 个版本 (t);模块保留最后一个已知良好版本加正在接收的片段(Sense:最近两个,`P02-sense.md` §9);独立模式 `AIR-HUB` 保留 3 个 (t)	`P07-studio.md` §5、§10 第 6 项
回滚与降级	回滚即通过完整流水线(§9)重新部署一个已保留版本;部分确认的部署会自动提供回滚;`version_id` 低于 Hub 当前值、或模式主版本更低且未设置 `rollback_of` 的均被拒绝(`E-MAN-03`)	`P07-studio.md` FR-20/25、`P03-mate.md` §3.3

3. 对象目录

R = 必填。*_ref 字段保存另一对象的 id,且必须可解析(E-REF-01)。未知字段见 §8。bindings/scenes 详见 §5,protection_presets 见 §4.3,alarm_rules/ac_policy 见 §6,permissions 见 §7。

对象	字段	类型	R	约束与说明
`manifest`	`schema_version`、`bundle_id`、`version_id`、`previous_version_id`、`rollback_of`	string、string、int、int、int	是/是/是/否/否	`version_id` > `previous_version_id`;首次部署无前置版本(§2)
`manifest`	`created_at`、`studio_build`、`author`	string	是	RFC 3339 UTC;Studio 构建 id;账户 id——不含其他个人数据(`P07-studio.md` §6)
`manifest`	`node_hashes`、`capability_hashes`	map	是	每个 `nodes[].id` 一条;能力哈希在设计时由 §8 的能力块计算
`manifest`	`bundle_hash`、`signature`、`cloud_countersignature`、`build_manifest_ref`	string、object、object、string	是/是/否/否	`signature = {alg, key_id, value}`,alg 为 `es256` (t);`build_manifest_ref` 仅用于生产模式(`P07-studio.md` FR-22)
`vessel`	`hull_id`、`name`、`system_voltage`	string、string、enum	是	`hull_id` 在账户内唯一;`system_voltage` ∈ {`12`, `24`} V,工作范围 9–32 V(product-plan.md §1)
`vessel`	`boat_type_template`、`template_version`	string	否	经校验的模板列表(`P07-studio.md` FR-07);用户模板在 P7-4 之前仅保存在本地
`vessel`	`destination_profile`、`install_mode`	enum	是	`eu`、`us`、…… 依 compliance-matrix.md,用于过滤无线电允许列表(§8);`install_mode` ∈ {`system`, `standalone_air`}——`standalone_air` = 恰好一个 `AIR-HUB`,无其他节点类别(G-15)
`buses`	`id`、`kind`、`bit_rate`	string、enum、object	是	`kind` ∈ {`ybo_can`, `n2k`, `rs485`};`ybo_can` 500 kbit/s (t),Classical CAN、载荷 ≤8 字节(`X01-ybo-can-protocol.md` §1);`n2k` 250 kbit/s;`rs485` 9600–115200 bit/s,每条总线一个速率(`P04-ac.md` §6)
`buses`	`termination_nodes`	array	`ybo_can`	恰好 2 个节点引用;拓扑检查依 `X01-ybo-can-protocol.md` §1
`buses`	`master_ref`、`poll_cycle_s`	string、number	`rs485`	主站仅限 `HUB`(Core 的 RS-485 角色待 P01 接口决策;`P05-key.md` §3（原 FR-15，RS-485 已移出基础范围）);`poll_cycle_s` 由 Studio 计算(G-10)
`nodes`	`id`、`class`、`uid`、`node_id`	string、enum、string、int	是/是/是/否	`class` ∈ {`CORE-27`, `CORE-43`, `CORE-DO`, `SENSE`, `KEY`, `AIR-HUB`, `HUB`, `VIEW`};64 位出厂 UID 十六进制;`node_id` 1–200,在每条 `ybo_can` 总线内唯一,0 = 未分配(`X01-ybo-can-protocol.md` §2)
`nodes`	`hw_variant`、`fw_min`、`bus_refs`	string、string、array	是	来自能力块;额定值由型号锁定(`P01-core.md` FR-19);`CORE-27`/`CORE-43` `ybo_can` + `rs485`(CAN 数量与 N2K 位置待 P01 接口决策),`AIR-HUB` `ybo_can` + `n2k` + `rs485`(product-plan.md §P1/§P5)
`nodes`	`mode`、`endpoints`	enum、array	`AIR-HUB`	`mode` ∈ {`system`, `standalone`},须显式指定、绝不自动检测(`standalone` 属扩展,`P05-air-hub-design.md` §2.4);`endpoints[] = {uid, kind, keys, profile}`,≤32 个开关 / 128 个按键(`P05-air-hub.md` §3 GW-02),≤64 个 Tag 属另行评审的扩展(同文件 §5)
`nodes`	`modbus_address`、`n2k_instance`	int	按型号	`KEY` RS-485 型号为 1–247;`SENSE` N2K 配置的 N2K 设备实例
`channels`	`id`、`node_ref`、`index`、`type`	string、string、int、enum	是	`index` < 能力块通道数;`type` 依 §4.1 且须在该通道能力 `types` 之内(G-06)
`channels`	`circuit`	object	是	`{name, zone, load_type, nominal_a, inrush_a, conductor_mm2, conductor_len_m, domain}`;`domain` ∈ {`dc`, `ac_control`}(`P07-studio.md` FR-01)
`channels`	`critical`、`default_state`	bool、enum	是	`default_state` ∈ {`on`, `off`, `hold`};关键通道默认 `on`,除非安装商覆盖并记入审计日志(`P01-core.md` FR-07;G-01)
`channels`	`protection_ref` 或 `protection`、`upstream_protection`	string 或 object、object	是	预设引用或内联的 §4.3 对象(内联需安装商覆盖,`P07-studio.md` FR-04);`{device, rating_a, declared}`——`declared=false` 时打印"UPSTREAM PROTECTION NOT DECLARED"(`P07-studio.md` FR-06;G-12)
`channels`	`pwm`、`pulse`、`half_bridge`、`coil`、`relay_out`、`readback_input_ref`	object ×5、string	按类型	§4.1 各类型专用块;`pulse` 与 `coil` 必须有 `readback_input_ref`,且解析为 `role=readback_aux` 的 `di`(G-02)
`channels`	`engineering_review`	object	50/80/120 A 通道	`{reviewer, date, envelope_verified}`;馈电与 >15 A 负载必填(G-03)
`inputs`	`id`、`node_ref`、`index`、`type`	string、string、int、enum	是	`type` ∈ {`di`, `ai`};`SENSE` 8 + 8;`CORE-27`/`CORE-43` 各 10 路可配置输入,附 `mode` ∈ {`digital`, `voltage`, `resistance`, `loop_4_20`, `loop_0_20`},每路恰一种(`P01-core.md` FR-21)(product-plan.md §P1/§P2)
`inputs`	`label`、`role`	string、enum	是	`role` ∈ {`generic`, `readback_aux`, `source_presence`, `transfer_position`, `tank`, `temperature`, `bilge`, `wake`};AC 角色仅限 `di`(G-09)
`inputs`	`di`、`ai`、`wake_source`、`sample_ms`、`alarm_rule_refs`	object、object、bool、int、array	按类型	§4.2;`wake_source` 仅限 `SENSE`/`CORE` 的 DI(`P02-sense.md` FR-17);规则在模块上 ≤100 ms (t) 内求值(`P02-sense.md` FR-08)

4. 通道与输入类型

4.1 通道类型(`channels[].type`);回读状态仅由 `STATE` 呈现:`off`、`on`、`pending`、`tripped`、`locked`、`bypassed`、`fault`

类型	允许位置	类型专用块	语义与固件限制
`level`	所有 Core 通道;50/80/120 A 通道须在已验证包络内	无	保持型 ON/OFF;`STATE` 回读 ≤5 s
`pwm`	能力 `pwm=true`(每款 Core 固定 15 路 15 A 通道,能力块 `pwm_channels`)	`pwm: {min_pct, max_pct, ramp_ms, soft_start_ms, freq_hz}`	调光与软启动(`P01-core.md` FR-11);照明分区引导至 PWM 子集(提示 `W-CH-01`)
`pulse`	任何具备能力 `pulse_max_on_ms` 的 Core 通道	`pulse: {width_ms, reactuation_s, mismatch_alarm_n, daily_limit}`	`width_ms` 50–1000 且 ≤ `pulse_max_on_ms`(`P01-core.md` FR-13);AC 模板默认最小 100 ms (t)(`P04-ac.md` §5);`reactuation_s` ≥12;`mismatch_alarm_n` = 3 (t);重试前先回读
`half_bridge`	无——2026-09-14 起 Core 不提供半桥(字段保留以便拒绝)	`half_bridge: {pair_index, travel_ms, current_limit_a}`	执行器(`P07-studio.md` FR-03);G-06
`coil`	`inductive_rated=true` 的 Core 通道	`coil: {maintained, hold_a, inrush_a, deenergised_default}`	AC 接触器 / 分励脱扣;续流二极管在 AC 板上(`P01-core.md` FR-12);`hold_a` ≤ 通道额定值的 50 % (t)(`P04-ac.md` §5)
`relay_out`	`SENSE`(1)	`relay_out: {pattern, latch, ack_timeout_s}`	`pattern` ∈ {`maintained`, `pulsed`};默认失电(`P02-sense.md` FR-11)

4.2 输入类型(`inputs[].type`)

类型 / 配置	字段	约束	来源
`di`	`contact`(`to_gnd`、`to_bat`)、`invert`、`debounce_ms`、`eol_resistor_ohm`、`pulse_count`、`wire_break_detect`	`debounce_ms` 1–1000 (t);断线检测需要 `eol_resistor_ohm`	`P02-sense.md` FR-06/07
`ai` / `sender_profile: resistive`	`r_min_ohm`、`r_max_ohm`、`curve`(≤12 点 (t))、`open_ohm`、`short_ohm`	0–190 Ω 与 10–180 Ω;240–33 Ω 与 0–310 Ω (t),待 P2 #1 决定;开路 > 1 kΩ (t),短路 < 2 Ω (t)	`P02-sense.md` FR-02/03/22
`ai` / `sender_profile: v_0_5`	`v_min`、`v_max`、`scale`、`unit`、`hysteresis`	仅限自带信号调理的变送器	`P04-ac.md` FR-13
`ai` / `sender_profile: ma_4_20`	`ma_min`、`ma_max`、`scale`、`unit`、`hysteresis`、`wire_break_ma`、`over_range_ma`	默认 3.6 mA / 21 mA(NAMUR NE 43 (t))	`P02-sense.md` FR-04
`ai` / `sender_profile: frequency`	`pulses_per_unit`、`unit`	无——Core 输入模式不含频率;频率输入由 `SENSE` 承担	product-plan.md §P1

4.3 保护字段(`protection_presets[]` 与内联 `channels[].protection`)

字段	类型	约束	说明
`id`、`name`	string	仅预设	按模板经校验的预设库
`trip_current`、`trip_curve`	number(A)、enum	≤ 能力块中的通道最大额定值且 ≤ 导线载流量(G-04);曲线 ∈ {`fast`, `standard`, `motor`, `lamp`} (t)	`P01-core.md` FR-03
`inrush_window`、`max_conduction_ms`	object、int	`{multiplier, ms}`,multiplier ≤ 硬件浪涌包络;`max_conduction_ms` 仅用于 `pulse`,≤ 固件上限、绝不提高上限	`P01-core.md` FR-13
`retry`、`overtemp_action`、`shed_priority`	object、enum、int	`{count, backoff_ms}`,硬短路时绝不连续重试;`trip` 或 `derate`;优先级低者先卸载	`P01-core.md` FR-06/FR-22

5. 绑定、场景与自动化

5.1 `bindings[]` 与 `scenes[]`

字段	类型	R	约束
`id`、`kind`	string、enum	是	`keypad_key`、`wireless_key`、`scene`、`automation`、`n2k_switch`、`modbus_target`
`source`	object	是	`keypad_key`:`{node_ref, key}`;`wireless_key`:`{gateway_ref, switch_uid, key}`;`automation`:`{task_id, origin: mate, action}`,`action` 取自白名单 `{set_level, run_scene, request_source, shed_feed, notify}` (t)(`P03-mate.md` 自动化行,G-05);`scene`:`{trigger_binding_ref}`
`gesture`	enum	是	Key:`press`、`hold`、`long_press`(≥1 s);Air:`short`、`hold`(≥500 ms)、`double`——上限三种(`P07-studio.md` FR-10)
`semantics`	enum	是	`toggle`、`momentary`、`dimmer`、`scene`、`interlock_group`、`helm_lock`;Air 仅限 `toggle`、`dimmer`、`scene`
`target`	object	是	`{channel_ref}` 或 `{scene_ref}`;`n2k_switch`:`{bank_instance, channel}`(PGN 127502 / 127501);`modbus_target`:`{bus_ref, register, readback_register}`
`options`、`nvm_target`	object、enum	否/是	`{group_id}`(互锁)、`{ramp_ms}`(调光)、`{momentary_timeout_ms}`(`P05-key.md` KEY-07);`nvm_target` ∈ {`core`, `keypad`, `gateway`},编译后的表在部署后回读(`P07-studio.md` FR-12)
`scenes[]`	object	—	`{id, name, steps: [{channel_ref, level_pct, delay_ms}], critical_off_override: {installer, date}}`;有序;将 `critical=true` 通道设为 0 % 的步骤需要该覆盖(G-01)

5.2 作为校验约束的护栏

代码	约束(除另有说明外,违反即部署失败)	来源
G-01	关键回路规则:`critical=true` 通道若其绑定仅为 `wireless_key` 或 `automation`,则需 ≥1 个 `keypad_key` 绑定或一条有文档记录的旁路路径;场景步骤设为 0 % 需要 `critical_off_override`	`P07-studio.md` FR-10/11、`P05-air-hub.md` §3 GW-01
G-02	`type=pulse` 或 `type=coil` 缺少可解析为 `role=readback_aux` 的 `di` 的 `readback_input_ref`	`P04-ac.md` §10
G-03	映射规则:`circuit.nominal_a` > 15 A 或 `load_type=feed` 在 15 A 通道上被拒绝;在 50/80/120 A 通道上要求 `engineering_review.envelope_verified=true`,否则该通道必须为驱动外部接触器的 `coil`——绝不自动分配;在 P1-4 关闭之前,`load_type` ∈ {`charger`, `bidirectional`} 在任何通道上均被拒绝	product-plan.md §P1 拓扑、`P07-studio.md` FR-02、`P01-core.md` FR-16
G-04	`trip_current` > ampacity(`conductor_mm2`, `conductor_len_m`):阻止;仅当能力块报告 `hw_max_trip_jumper=true` 时降为提示 `W-PR-01`(P1-8)	`P07-studio.md` FR-05
G-05	`automation.action` 不在白名单枚举内	`P03-mate.md` 自动化行
G-06	`type` 不在通道能力内:`pwm=false` 上使用 `pwm`/`dimmer`,`half_bridge` 在任何 Core 上,`coil` 缺少 `inductive_rated=true` 或 `deenergised_default=false`	`P07-studio.md` FR-03、`P01-core.md` FR-12
G-07	`type=pulse` 的 `width_ms` 超出 50–1000 或 > 能力 `pulse_max_on_ms`,或 `reactuation_s` < 12	`P07-studio.md` FR-08
G-08	节点无能力块,或 `schema_version.major` 超出其支持范围	`P07-studio.md` §5 发现
G-09	AC 角色(`readback_aux`、`source_presence`、`transfer_position`)用于 `ai`;`SENSE` 的 `ai` 标签为 `AC current`/`AC voltage`;裸 CT 配置	`P02-sense.md` FR-10、`P04-ac.md` FR-13
G-10	计算得到的 `rs485` `poll_cycle_s` > 2 s (t)(`P04-ac.md` FR-17;旧 `AIR-HUB` RS-485 的 2.5 s 已随 RS-485 移出基础范围,见 `P05-air-hub-design.md` §2.4)	`P07-studio.md` FR-14
G-11	`ac_policy` 将 `feed_class=safety_critical` 的馈电、无第 (c) 层 `di` 的转换路径、或 `ssr` 设备绑定到自动化	`P07-studio.md` FR-15、`P04-ac.md` FR-08/21
G-12	`upstream_protection.declared=false`:PDF 上给出警告 `W-CH-02`,允许部署	`P07-studio.md` FR-06
G-13	`install_mode=standalone_air` 缺少 ≥1 个 `n2k_switch` 或 `modbus_target` 绑定,或存在任何非 `AIR-HUB` 节点	`P07-studio.md` FR-13

6. 报警规则与 AC 策略对象

对象	字段	约束
`alarm_rules[]`	`id`、`node_ref`、`source_ref`(输入或通道)、`condition` ∈ {`gt`, `lt`, `eq`, `mismatch`, `wire_break`, `heartbeat_lost`}、`threshold`、`hysteresis`、`debounce_ms`、`severity` ∈ {`notice`, `warning`, `critical`}、`latching`、`actions`(`relay_out_ref`、`buzzer`、`bus_alarm`)、`survives_hub_loss`(计算得出:节点 ∈ {`CORE-*`, `SENSE`, `AIR-HUB`})	数量 ≤ 能力 `rule_capacity`(`E-ALM-01`);`mismatch` 将 `channel_ref` 与其 `readback_input_ref` 配对,5 s 后触发(`P02-sense.md` §10);AC 安全规则(`shore_loss`、`gen_no_output`、`contactor_mismatch`)仅绑定 `di`(`P07-studio.md` FR-09)
`ac_policy`	`source_priority`(有序,默认 `[shore, generator, inverter]`)、`transfer_delay_s`、`load_shed_order`(馈电引用)、`inverter_windows`(`{soc_min_pct, solar_w_min, hours}`)、`quiet_hours`、`feeds[]`(`{id, channel_ref, feed_class, link_loss_behaviour}`)、`modbus_map[]`(`{bus_ref, address, model, register_block, poll_s}`)、`transfer_pairs[]`(`{contactor_a_ref, contactor_b_ref, position_input_refs}`)	`feed_class` ∈ {`comfort`, `automated`, `safety_critical`};`link_loss_behaviour` ∈ {`hold`, `shore_only`},待 P4-8 决定;每个 `automated` 馈电都有一个 `readback_aux` 输入(G-02/G-11);Modbus 丢失 → 手动 + 报警属固件行为,不可配置(`P04-ac.md` FR-18)

7. 权限与角色

角色	在 bundle 中的范围	规则
`installer`	全部对象;设置 `permissions.installer_locked[]`(JSON 指针)	覆盖操作(内联保护、关键通道默认 `off`、场景关键回路关断、G-04 跳线提示)记录于 `permissions.overrides[] = {pointer, by, at, reason}` 并记入审计日志;授权模型尚未定(open-questions.md P7-1),字段形态在 `P07-studio.md` FR-23 冻结前为 (t)
`owner`	`channels[].circuit.name`、`scenes`、`pwm` 级别、非关键 `bindings`	不得触碰 `protection*`、`critical`、`default_state`、`ac_policy`、`pulse`、`coil` 或任何已锁定指针(`E-PRM-01`)
`crew`、`charter_guest`	仅运行时(`P03-mate.md`):`permissions.runtime_exposure` 列出这些角色可操作的 `comfort` 类 `channel_refs`/`scene_refs`;`charter_guest` 为只读加舒适类	执行由 Hub/Mate 与 Core 舵位锁负责(`P05-key.md` FR-07);bundle 仅声明暴露范围

8. 能力发现

node -> Hub (DIAG, X01 §4) -> Studio:
capability = { product, hw_variant, fw_version, schema_supported: {min_major, max_major},
               channels: [{index, max_a, types, pwm, half_bridge, pulse_max_on_ms, inductive_rated, hw_max_trip_jumper}],
               inputs: {di: n, ai: n, ai_modes: [...], freq: n, current_loop: n},
               binding_table_version, rule_capacity, nvm_bytes, radio_allow_list: [...] (AIR-HUB only) }
capability_hash = SHA-256(canonical capability) -> manifest.capability_hashes[node_ref]

规则	定义
协商	Studio 仅提供能力块允许的内容(`P07-studio.md` §5);部署时 Hub 重新计算每个哈希——不匹配(设计后硬件或固件已变更)即以 `E-CAP-01` 中止并提示重新校验
未知字段	同一主版本:节点忽略未知可选字段,仅在 `nvm_bytes` 允许时以不透明方式保留于 NVM,否则丢弃并报告 `W-CFG-01`;Hub 拒绝未知的顶层对象(`E-SCH-02`);Studio 绝不输出目标能力块中不存在的字段
无线电允许列表	`AIR-HUB` 发布已签名的频段/配置允许列表;Studio 不提供列表之外的频段(区域射频属扩展配置,`P05-air-hub-design.md` §2.4)
厂商固件 Core	当厂商 Core 节点仅暴露子集时(product-plan.md §6 第 1b 项),其能力块声明该子集及依 `X01-ybo-can-protocol.md` §8 的网关节点映射

9. 部署流程与校验流水线

Studio (PWA, IndexedDB) --validate--> sign --HTTPS (boat LAN) | Mate relay (mTLS MQTT)--> Hub
  Hub: verify sig + version_id + schema major -> split per node -> CFG fragments on YBO-CAN (X01 §4)
  node: verify fragment, check capability/ratings, ACK (<=100 ms), apply, echo node_hash in STATE/DIAG
  Hub: all nodes confirmed inside 5 s -> version active; any NACK/timeout -> atomic abort, last known-good
       stays active, rollback offered (P03 §3.3, P07 FR-20)
Standalone AIR-HUB: Studio/Mate --BLE | Wi-Fi (local AP / mTLS cloud)--> gateway verifies and stores its own
  fragment; bindings written to gateway NVM and read back; n2k_switch / modbus_target confirmed via
  PGN 127501 / read-back register (P05 FR-04/05)
Offline PWA: cached schema fragments + project + capability blocks; local deploy to Hub; backup, audit and
  cloud countersignature queued until a link returns; session lifetime bounded *(t)* (P7-3)

阶段	检查项	失败类别
1 模式	由本目录生成的 JSON Schema draft 2020-12 (t):类型、枚举、必填字段、引用解析	`E-SCH-`、`E-REF-`,附字段级消息(`P07-studio.md` §9)
2 语义	护栏 G-01–G-13、能力匹配、NVM/规则容量、按 `nvm_target` 编译绑定表、角色/锁定规则	`E-` 阻止;`W-` 警告
3 合理性	线径与脱扣值(G-04)、RS-485 轮询预算(G-10)、按节点数计算的 YBO-CAN 总线负载(`X01-ybo-can-protocol.md` §6)、AC 密集型船只的输入数量预算(`P04-ac.md` §6)、未分配回路 / 未使用通道清单	按各代码规定阻止或提示
4 确认与回读	展示语义差异并显式确认,随后签名;逐节点哈希回显与 `STATE` 呈现;PDF / 交付包仅从已确认版本生成并携带 `node_hashes`;虚拟船在伪造能力块与 `STATE` 的模拟器上运行同一流水线(`P07-studio.md` FR-21)	`P07-studio.md` FR-16–19

10. 示例

Core 27 通道(沙龙灯,PWM 子集)配 Key 8 切换与调光绑定:

{
  "channels": [{
    "id": "ch_saloon_lights", "node_ref": "core_27_1", "index": 7, "type": "pwm",
    "circuit": {"name": "Saloon lights", "zone": "saloon", "load_type": "lighting_led", "nominal_a": 2.5,
                "inrush_a": 6, "conductor_mm2": 1.5, "conductor_len_m": 8, "domain": "dc"},
    "critical": false, "default_state": "off", "protection_ref": "pp_lamp_5a",
    "upstream_protection": {"device": "zone_feed_fuse_F3", "rating_a": 30, "declared": true},
    "pwm": {"min_pct": 5, "max_pct": 100, "ramp_ms": 800, "soft_start_ms": 200, "freq_hz": 400}
  }],
  "protection_presets": [{
    "id": "pp_lamp_5a", "name": "LED lighting 5 A", "trip_current": 4.0, "trip_curve": "lamp",
    "inrush_window": {"multiplier": 3, "ms": 50}, "retry": {"count": 2, "backoff_ms": 2000},
    "overtemp_action": "trip", "shed_priority": 3
  }],
  "bindings": [
    {"id": "b_key8_helm_k3", "kind": "keypad_key", "source": {"node_ref": "key8_helm", "key": 3},
     "gesture": "press", "semantics": "toggle", "target": {"channel_ref": "ch_saloon_lights"}, "nvm_target": "core"},
    {"id": "b_key8_helm_k3_dim", "kind": "keypad_key", "source": {"node_ref": "key8_helm", "key": 3},
     "gesture": "hold", "semantics": "dimmer", "target": {"channel_ref": "ch_saloon_lights"},
     "options": {"ramp_ms": 1500}, "nvm_target": "core"}
  ]
}

AC 热水器回路,采用 2P 自锁继电器(脉冲),辅助触点回读接入 Sense,并配 mismatch 规则:

{
  "channels": [{
    "id": "ch_ac_water_heater", "node_ref": "core_do_1", "index": 3, "type": "pulse",
    "circuit": {"name": "AC water heater relay", "zone": "ac_board", "load_type": "latching_relay_coil",
                "nominal_a": 0.25, "inrush_a": 0.3, "conductor_mm2": 0.75, "conductor_len_m": 3, "domain": "ac_control"},
    "critical": false, "default_state": "hold", "protection_ref": "pp_coil_1a",
    "upstream_protection": {"device": "core_do_1_input_breaker", "rating_a": 80, "declared": true},
    "pulse": {"width_ms": 200, "reactuation_s": 12, "mismatch_alarm_n": 3, "daily_limit": 100},
    "readback_input_ref": "in_wh_aux"
  }],
  "inputs": [{
    "id": "in_wh_aux", "node_ref": "sense_1", "index": 2, "type": "di", "label": "Water heater aux contact",
    "role": "readback_aux", "di": {"contact": "to_gnd", "invert": false, "debounce_ms": 50,
                                   "eol_resistor_ohm": 4700, "pulse_count": false, "wire_break_detect": true}
  }],
  "alarm_rules": [{
    "id": "al_wh_mismatch", "node_ref": "sense_1", "source_ref": "in_wh_aux", "condition": "mismatch",
    "threshold": null, "hysteresis": null, "debounce_ms": 5000, "severity": "warning", "latching": true,
    "actions": {"bus_alarm": true, "buzzer": false}, "survives_hub_loss": true
  }],
  "ac_policy": {
    "feeds": [{"id": "feed_wh", "channel_ref": "ch_ac_water_heater", "feed_class": "automated",
               "link_loss_behaviour": "shore_only"}],
    "load_shed_order": ["feed_wh"]
  }
}

11. 可案头决定的事项

决策	建议	理由	冻结门槛
Semver `patch`、规范化、哈希、JSON Schema 方言、签名	`major.minor.patch`(patch 仅编辑性);RFC 8785 JCS + SHA-256;draft 2020-12;ECDSA P-256(`es256`)	保持 `P07-studio.md` §5 的 `major.minor` 规则;PWA、Hub 与节点间哈希确定一致;校验器成熟;与 MCU 安全引擎匹配	Studio 模式冻结(`P07-studio.md` §10 第 6 项);签名在 M3(product-plan.md §1 MCU 行)
`mismatch_alarm_n` 默认值;独立模式 `AIR-HUB` 保留版本数	3;3	`P07-studio.md` FR-08 写为 3 (t),`P04-ac.md` FR-11 写为 2 (t)——必须择一,并更新落选的 Level-1 文件;网关保留数受 NVM 限制,无 Hub 时仍可回滚	Studio 模式冻结;Air EVT(M6–7)
RS-485 轮询上限(G-10)	2 s	`P04-ac.md` FR-17(2 s);旧 `AIR-HUB` 的 2.5 s 随 RS-485 移出基础范围,2 s 可在 5 s 内保留一次重试	M3,随 P4-9
脱扣曲线预设 id 与自动化动作白名单	`fast`、`standard`、`motor`、`lamp`;`set_level`、`run_scene`、`request_source`、`shed_feed`、`notify`	覆盖照明、泵/电机、电子设备、P4 策略与 P8 自动化的最小枚举集	Core EVT 台架;Mate v1 范围冻结
未知字段保留	NVM 允许时不透明保留,否则丢弃 + 警告	模式 minor 新增无需固件发布即可前向兼容	Studio 模式冻结

12. 变更记录

日期	变更	参考
2026-08-28	依据 PRODUCT-PLAN §1/§P1/§P4–P8、P07 FR 列表与 §5、P01/P02/P04/P05/P06 的固件与配置章节起草初版基础文件	PLAN-029