@international-iot-association/plugin-contracts 3.0.0-rc.1

package/dist/index.d.cts

@@ -0,0 +1,1931 @@
+declare const FIXTURE_LOGICAL = "serial.fixture";
+declare const DUT_LOGICAL = "serial.dut";
+declare const CURRENT_METER_LOGICAL = "instrument.current-meter";
+declare const FIXTURE_BOARD_ADDRESS = 250;
+declare const FIXTURE_BAUD_RATE = 115200;
+declare const T9W_DUT_BAUD_RATE = 460800;
+declare const KNOWN_T9W_FIXTURE_ENDPOINT = "58b20024743";
+declare const KNOWN_T9W_DUT_ENDPOINT = "58b20024741";
+interface FixturePortSelection {
+    fixture?: SerialPortInfo;
+    dut?: SerialPortInfo;
+    reasons: string[];
+}
+interface OperatorSignals {
+    keys: string[];
+    encoderForward: boolean;
+    encoderReverse: boolean;
+}
+declare function isFixtureReadyEvent(event: Record<string, unknown>): boolean;
+declare function preferredSerialPortPath(path: string): string;
+declare function allSerialPortPaths(port: SerialPortInfo): string[];
+declare function serialEndpointId(path: string): string | null;
+declare function serialPortHasEndpoint(port: SerialPortInfo, endpoint: string): boolean;
+declare function preferredSerialPathFromPort(port: SerialPortInfo): string;
+/**
+ * 粗筛「可能是 USB 转串口」的候选。
+ * - macOS：cu/tty.wchusbserial* / usbmodem*
+ * - Windows：COM* + CH340/CP210/FTDI 等元数据（path 本身没有 wch 字样）
+ * 协议已命中的口不应再被本函数否决——见 chooseFixtureAndDutPortPairs。
+ */
+declare function looksLikeUsbSerialPort(port: SerialPortInfo): boolean;
+interface FixtureDutPair {
+    fixture: SerialPortInfo;
+    dut: SerialPortInfo;
+}
+interface FixturePortPairSelection {
+    pairs: FixtureDutPair[];
+    reasons: string[];
+}
+interface ChooseFixtureDutOptions {
+    /**
+     * 需要的夹具+DUT 对数（多席位）。默认 1。
+     * 协议探测优先；不足时才考虑已知端点兜底。
+     */
+    count?: number;
+    /** 已占用路径（含别名），不再分配。 */
+    excludePaths?: string[];
+    /**
+     * 可选：已知夹具 USB 端点（仅作协议探测失败时的兜底，不区分产品型号）。
+     * 不传则不使用端点硬编码；传空字符串可显式关闭默认兜底。
+     */
+    fixtureEndpoint?: string | null;
+    /** 可选：已知 DUT 转发端点兜底。 */
+    dutEndpoint?: string | null;
+    /**
+     * @deprecated 逻辑名不再参与筛选；夹具以 `kind=fixture-modbus`（协议握手成功）为准。
+     * 保留字段以免旧调用方类型报错。
+     */
+    fixtureLogicalName?: string;
+    /** @deprecated 见 fixtureLogicalName。 */
+    dutLogicalName?: string;
+    /**
+     * true 时在协议结果之后仍尝试 KNOWN_T9W_* 端点兜底（默认 true，兼容旧实验室固定线序）。
+     * 跨机/跨 Windows 部署应依赖协议探测，不依赖该兜底。
+     */
+    allowKnownEndpointFallback?: boolean;
+}
+/**
+ * 选择夹具控制板 + DUT 转发口。
+ *
+ * **优先级（不区分 T9W/TRV 等产品型号）**：
+ * 1. Agent `detectDevices` 中 `kind=fixture-modbus`（0xFA Modbus 握手成功）→ 协议可用即夹具；
+ * 2. 同建议的 `pairedWith` / `role=dut` / 同族 USB 兄弟口 → DUT 转发；
+ * 3. 可选：已知 USB 端点硬编码（仅实验室线序兜底，默认开启以兼容旧台架）。
+ *
+ * 物理路径因 macOS/Windows/重插而变；跨机部署必须走 1+2，勿写死 path。
+ */
+declare function chooseFixtureAndDutPorts(ports: SerialPortInfo[], suggestions?: SerialDeviceSuggestion[], options?: ChooseFixtureDutOptions): FixturePortSelection;
+/**
+ * 多席位版本：按协议探测结果依次分配互不重叠的 fixture+DUT 对。
+ */
+declare function chooseFixtureAndDutPortPairs(ports: SerialPortInfo[], suggestions?: SerialDeviceSuggestion[], options?: ChooseFixtureDutOptions): FixturePortPairSelection;
+declare function buildFixtureSerialConfig(port: SerialPortInfo | undefined, options?: {
+    logicalName?: string;
+    boardAddress?: number;
+}): SerialChannelConfig;
+declare function buildDutRawTextSerialConfig(port: SerialPortInfo | undefined, options?: {
+    logicalName?: string;
+    baudRate?: number;
+}): SerialChannelConfig;
+declare function parseOperatorSignals(text: string): OperatorSignals;
+
+/**
+ * ctx.channels.control() 是宿主进程返回给插件运行时的受控边界。
+ *
+ * 这些 helper 只做“运行时值 -> 契约类型”的窄化，不参与业务判断：业务代码仍然需要
+ * 检查数组是否为空、通道是否打开、端口是否满足设备策略。这样可以让示例插件少写重复
+ * 的类型断言，同时避免把具体工站流程塞进公共包。
+ */
+declare function asSerialPorts(value: unknown): SerialPortInfo[];
+declare function asSerialDeviceSuggestions(value: unknown): SerialDeviceSuggestion[];
+declare function asChannelStatus(value: unknown): ChannelStatus;
+/**
+ * writeRead() 的 response 在插件契约中故意保持 unknown：不同 provider/codec 会返回不同
+ * 结构。需要检查字段的示例插件先收敛成普通对象，再由业务逻辑读取具体字段。
+ */
+declare function asResponseObject(value: unknown): Record<string, unknown>;
+
+interface PluginStepDef {
+    key: string;
+    label: string;
+    description?: string;
+}
+/**
+ * 插件类别（详见 docs/global-plugins.md）：
+ * - `station`（缺省）：工位插件，由操作员按需启动。
+ * - `global`：全局能力插件（如日志、登录）。是否有 UI 与 kind 正交——
+ *   `uiEntry` 省略即无界面后台插件。
+ */
+type PluginKind = 'station' | 'global';
+/**
+ * 插件 storage 作用域（W3-6，P0-06）：
+ * - `version`（缺省）：数据放在 `data/<pluginId>/versions/<version>/`，版本私有，
+ *   版本切换/回滚互不影响。
+ * - `shared`：数据放在 `data/<pluginId>/shared/`，跨版本共享。只有 manifest 显式
+ *   声明才使用；shared 数据的 schema 不得做破坏旧版本的不可逆迁移。
+ */
+type PluginStorageScope = 'version' | 'shared';
+/**
+ * manifest 的 storage 声明（W3-6）。缺省等价于
+ * `{ scope: 'version', migrateLegacy: true }`。
+ */
+interface PluginStorageDeclaration {
+    scope?: PluginStorageScope;
+    /**
+     * false 时不把 W3-6 之前的平铺数据复制/移动进当前活动目录；旧文件原地保留，
+     * 适用于新版本不得继承历史敏感数据的迁移边界。缺省 true。
+     */
+    migrateLegacy?: boolean;
+}
+/** 插件的 manifest.json（即打包进插件 zip 内的清单）。 */
+interface PluginManifest {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    /** 缺省视为 'station'。 */
+    kind?: PluginKind;
+    stationTypes: string[];
+    /**
+     * 仅为展示用元数据：外壳把它渲染成插件详情的「适用机型」/ 介绍页的「适配型号」，
+     * **不参与插件分发、准入或工位匹配判断**——那由 MES 侧 workOrder + stationType +
+     * skuId 解析出的 packages 清单决定。可省略（安装器归一化为 `[]`）。
+     */
+    models?: string[];
+    agentApi: string;
+    /**
+     * 插件 UI 入口。`kind: 'station'` 必填；`kind: 'global'` 可省略（无界面，
+     * 外壳不创建 iframe）。
+     */
+    uiEntry?: string;
+    runtimeEntry: string;
+    permissions: string[];
+    /** true 时外壳启动后自动拉起该插件（连同其依赖闭包，按拓扑序）。 */
+    autoStart?: boolean;
+    /**
+     * 插件依赖：被依赖插件 id -> 版本范围（支持 `*`、精确 `1.2.3`、`^1.2.3`、`1.x`）。
+     * 启动时依赖先于依赖者启动；同时它也是服务总线（轴 D）的调用授权 ACL。
+     */
+    dependencies?: Record<string, string>;
+    resultSchema?: string;
+    /**
+     * 仅为可选元数据。由于外壳通过 API-Bridge（而非通用的 runStep）驱动插件，
+     * `steps` 不再用于渲染外壳侧的按钮；保留它只是为了文档 / 注册表展示。
+     */
+    steps?: PluginStepDef[];
+    checksum?: string;
+    /**
+     * W3-6（P0-06）：插件本地存储作用域声明。缺省为 version scope
+     * （`data/<pluginId>/versions/<version>/`）。注意外壳安装器归一化后的
+     * InstalledPlugin.manifest 可能不携带该字段——外壳按包内 manifest.json 原文解析。
+     */
+    storage?: PluginStorageDeclaration;
+    /**
+     * W3-4（P0-06）：readiness（activate）等待超时（毫秒）。版本切换事务缺省 8000ms，
+     * 超时按失败处理并恢复原版本。readiness 必须是无副作用检查：activate 只允许
+     * 模块加载/配置解析/本地依赖检查，不允许写 SN、切继电器、烧录等硬件动作。
+     */
+    readinessTimeoutMs?: number;
+}
+/** 注册表服务器对外公布的一个安装包。 */
+interface RemotePlugin {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    kind?: PluginKind;
+    stationTypes: string[];
+    /**
+     * 展示用元数据，语义同 {@link PluginManifest.models}。注册表侧仍为必填
+     * （后端登记记录始终携带该键，解析时 fail-closed 校验），外壳只用于渲染。
+     */
+    models: string[];
+    agentApi: string;
+    permissions: string[];
+    autoStart?: boolean;
+    dependencies?: Record<string, string>;
+    /** 后端历史 JSON 登记记录可能未知；安装时仍以实际下载字节执行上限与验签。 */
+    sizeBytes: number | null;
+    sha256: string;
+    /**
+     * Ed25519 分离签名（base64）：对 {agentApi,id,sha256,sizeBytes,version}
+     * 规范化 JSON（键排序）的签名，由内部发布链 root key 或被 root 背书的
+     * publisher key 签出。生产 MES 上传可为空串；development 未配置信任根时也可为空。
+     */
+    signature: string;
+    downloadUrl: string;
+}
+/** 签名 registry 中被 root key 背书的 publisher 公钥（支持 key rotation）。 */
+interface RegistryPublisherKey {
+    /** 公钥指纹：sha256(SPKI DER) 前 16 个 hex 字符。 */
+    keyId: string;
+    publicKeyPem: string;
+    /** root key 对 {keyId, publicKeyPem} 规范化 JSON 的 Ed25519 签名（base64）。 */
+    signature: string;
+}
+/** registry.json 顶层的签名快照（对整个发布集合的完整性签名）。 */
+interface RegistrySnapshot {
+    /** root key 对快照签名内容（含全部包签名内容、撤销列表等）的签名（base64）。 */
+    signature: string;
+    rootKeyId: string;
+}
+/**
+ * registry 文档（demo/生产 registry 服务对外壳提供的完整形态）。
+ * 新增字段全部可选，向后兼容旧的「纯数组」响应。
+ */
+interface PluginRegistryDocument {
+    generatedAt: string;
+    plugins: RemotePlugin[];
+    snapshot?: RegistrySnapshot;
+    /** 已确认供应链/安全事故的包 sha256 集合：安装与启动一律拒绝，但不自动删除。 */
+    revokedDigests?: string[];
+    /** pluginId -> 允许安装的最低版本（strict SemVer）。 */
+    minVersions?: Record<string, string>;
+    publisherKeys?: RegistryPublisherKey[];
+}
+/** 包签名状态（外壳安装器判定）。 */
+type PluginSignatureState = 'verified' | 'unsigned-dev' | 'local-dev'
+/** Shell 安装包 extraResources 白名单底座插件，经清单 sha256 证明后落盘。 */
+ | 'bundled-attested'
+/** 经认证 MES 精确版本 download-url 安装的已发布包。 */
+ | 'mes-attested'
+/** 经认证 MES 下载的 draft；启动前需用户允许。 */
+ | 'mes-draft';
+/** 已通过校验、解压并在本地登记的插件。 */
+interface InstalledPlugin {
+    id: string;
+    version: string;
+    manifest: PluginManifest;
+    installedAt: string;
+    installDir: string;
+    sha256: string;
+    /**
+     * 签名判定结果：`verified` = 已按信任根验签通过；`mes-attested` =
+     * 经生产 MES 官方渠道安装的 released 包；`mes-draft` = MES draft；
+     * `unsigned-dev` = development 未验签；`local-dev` = 本地目录开发安装；
+     * `bundled-attested` = 安装包白名单底座。缺省视为签名机制之前的历史安装。
+     * production 对非官方包改为启动前提示后允许，不再直接拒绝。
+     */
+    signatureState?: PluginSignatureState;
+}
+/** 本地保留的某个插件历史版本目录。 */
+interface PluginVersionHistoryEntry {
+    id: string;
+    version: string;
+    installDir: string;
+    active: boolean;
+    installedAt?: string;
+    sha256?: string;
+    /** W3-4：安装目录占用字节数（供版本下拉/清理 UI 展示；计算失败时缺省）。 */
+    sizeBytes?: number;
+    /** W3-4：该版本落盘时的验签判定（缺省 = 引入签名机制之前的历史安装）。 */
+    signatureState?: PluginSignatureState;
+}
+/** 清理非活动历史版本后的结果。 */
+interface PluginVersionCleanupResult {
+    pluginId: string;
+    activeVersion?: string;
+    keptVersions: string[];
+    removedVersions: string[];
+    /**
+     * W3-6：随被删版本一并删除的 version-local storage
+     * （`data/<pluginId>/versions/<version>/`）字节数合计。清理确认文案属 UI 层，
+     * 本层只提供数据。
+     */
+    removedDataBytes?: number;
+}
+/** 版本下拉里的一个本地版本选项（15 章第 10 节的数据面）。 */
+interface PluginVersionOption {
+    version: string;
+    sha256?: string;
+    installedAt?: string;
+    sizeBytes?: number;
+    signatureState?: PluginSignatureState;
+    /** installed-registry 当前登记的 active 版本（与 selected 保持同步的落盘态）。 */
+    active: boolean;
+    /** 该版本 runtime 正在运行。 */
+    running: boolean;
+    /** 持久化 pin（下次启动/当前期望运行的版本）。 */
+    selected: boolean;
+    /** 最近一次通过 readiness 且被明确维护确认的版本。 */
+    lastKnownGood: boolean;
+    /**
+     * 非空 = 该版本不可被切换启用，并给出明确原因（agentApi 不兼容 / revoked
+     * digest / 未验签等）。UI 应展示为 disabled 并在 tooltip 中说明。
+     */
+    disabledReasons: string[];
+}
+/** 最近一次 registry 刷新后可见的远端版本（供详情页逐版本下载）。 */
+interface RemotePluginVersionOption {
+    version: string;
+    sha256: string;
+    sizeBytes: number | null;
+    description?: string;
+    status: 'draft' | 'released' | 'offline' | 'rolled_back';
+    /** 后端返回的下载授权；Shell 不得从生命周期自行推导。 */
+    downloadable: boolean;
+    /** 不可下载时供可信 Shell UI 展示的固定原因；可下载时为 null。 */
+    downloadDisabledReason: string | null;
+    publishedAt?: string | null;
+    availableLocally: boolean;
+    selected: boolean;
+    running: boolean;
+    latest: boolean;
+}
+/**
+ * 单个插件的聚合版本状态（P0-06 状态模型）。五个字段语义分离，
+ * 不再用一个 `installed.version` 同时表示「磁盘上有 / 已选择 / 正在运行」。
+ */
+interface PluginVersionState {
+    pluginId: string;
+    /** 本地已验签保留的版本集合（按版本降序）。 */
+    availableVersions: PluginVersionOption[];
+    /** 最近一次 registry 刷新后缓存的远端版本集合（按版本降序）。 */
+    remoteVersions: RemotePluginVersionOption[];
+    /** 远端查询失败时保留本地版本，并由 UI 展示刷新失败。 */
+    remoteStatus: 'ready' | 'unavailable';
+    /** 持久化 pin；缺省 = 当前 active 版本。 */
+    selectedVersion: string | null;
+    /** 当前 runtime 实际运行的版本；停止时为 null（运行期派生，不落盘）。 */
+    runningVersion: string | null;
+    /** 最近通过 readiness 且被明确确认的版本（confirmVersionGood）。 */
+    lastKnownGoodVersion: string | null;
+    /** registry 中可下载的更高版本（listRemote 后缓存；不自动下载/启用）。 */
+    registryCandidate: string | null;
+}
+type RuntimeState = 'stopped' | 'starting' | 'running' | 'error';
+interface RuntimeStatus {
+    pluginId: string;
+    state: RuntimeState;
+    startedAt?: string;
+    lastError?: string;
+}
+interface RuntimeLogEntry {
+    ts: string;
+    level: 'info' | 'warn' | 'error' | 'debug';
+    pluginId: string;
+    message: string;
+    /** 可选模块标签（统一日志门面 tag）。 */
+    tag?: string;
+    /** 可选结构化字段（ADR-0002）。 */
+    data?: Record<string, unknown>;
+}
+/** 单个测试步骤的结果，与 schemas/result.schema.json 对应。 */
+interface StepResult {
+    ok: boolean;
+    stepKey: string;
+    measurements?: Record<string, unknown>;
+    raw?: string;
+    error?: string;
+    startedAt: string;
+    finishedAt: string;
+}
+/** 运行时上报的中间进度事件。 */
+interface StepEvent {
+    pluginId: string;
+    stepKey: string;
+    phase?: string;
+    message: string;
+    ts: string;
+}
+interface StationPaths {
+    root: string;
+    packages: string;
+    installed: string;
+    /** 插件私有数据根目录（ctx.storage 的宿主侧根，按 pluginId 分目录）。 */
+    data: string;
+}
+/** 标准 IPC 信封，使渲染进程无需捕获原始抛出的异常。 */
+interface UnofficialPluginRunPrompt {
+    pluginId: string;
+    pluginName: string;
+    version: string;
+    sha256: string;
+    kind: 'unofficial' | 'draft';
+}
+type IpcResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+    code?: string;
+    unofficialRun?: UnofficialPluginRunPrompt;
+};
+interface SerialPortInfo {
+    path: string;
+    aliases?: string[];
+    manufacturer?: string;
+    serialNumber?: string;
+    vendorId?: string;
+    productId?: string;
+    pnpId?: string;
+    locationId?: string;
+    friendlyName?: string;
+    /**
+     * 该口是外壳虚拟串口能力铸出的 PTY（ADR-0031 D6 选项 A），不是物理设备。
+     *
+     * 只在外壳「设置 → 开发者 → 虚拟串口」开着时出现，且只会是客户端那一端。
+     * 它是**枚举**结果：外壳不做自动绑定，路径仍要人工选中 / 抄写。
+     * 缺省 undefined = 真实口。
+     *
+     * 插件可据此加角标或拒绝用于放行；`manufacturer` / `friendlyName` 里也带着
+     * 中文标记，两处一致。
+     */
+    virtual?: boolean;
+    /**
+     * **同一块板上的多个串口共享的板级标识**；判不出同板归属时缺省 undefined。
+     *
+     * 真实 USB 双串口板靠**设备级** `serialNumber` 表达「这两个口是一块板」
+     * （同一 `IOUSBHostDevice` 下的两个接口读到同一个值，见
+     * `trv-wifi-combined/runtime/rf/station/fixture-candidates.ts` 的 `serialBoardKey`）。
+     * 虚拟 PTY 没有 USB 描述符，这条路走不通——于是改由**铸口方显式声明**：
+     * 仿真插件铸一席的夹具口与 DUT 口时传同一个 `boardId`，外壳原样投影。
+     *
+     * 这不是自动发现（ADR-0031 D6 删掉的是「描述符一活、真实端口整份被顶替」
+     * 那套机制）：声明的是**设备自己的身份**，不是「这条口属于第几席」。
+     * 席位归属仍然只由夹具下压产生（`serial-seat-binding.ts`）。
+     */
+    boardId?: string;
+}
+type SerialProbeKind = 'fixture-modbus' | 'esp32-json' | 'unknown' | 'ignored';
+type SerialPortRole = 'fixture' | 'dut' | 'simulator' | 'unknown' | 'ignored';
+type SerialPortCapability = 'modbus-rtu' | 'fixture-ready-event' | 'fixture-power-control' | 'raw-text' | 'json-lines';
+interface SerialProbeAttempt {
+    kind: SerialProbeKind;
+    ok: boolean;
+    message: string;
+    latencyMs?: number;
+    response?: unknown;
+}
+interface SerialDeviceSuggestion {
+    port: SerialPortInfo;
+    kind: SerialProbeKind;
+    role: SerialPortRole;
+    capabilities: SerialPortCapability[];
+    logicalName?: string;
+    baudRate?: number;
+    pairedWith?: string;
+    confidence: number;
+    reasons: string[];
+    attempts: SerialProbeAttempt[];
+}
+interface JsonLinesCodecConfig {
+    type: 'json-lines';
+    delimiter: '\n';
+    maxFrameBytes: number;
+    ignoreUntilJson?: boolean;
+}
+interface ModbusRtuCodecConfig {
+    type: 'modbus-rtu';
+    deviceAddress?: number;
+    maxFrameBytes: number;
+}
+interface RawTextCodecConfig {
+    type: 'raw-text';
+    delimiter?: '\n' | '\r\n' | '\r';
+    maxFrameBytes: number;
+    encoding?: 'utf8' | 'latin1';
+    appendDelimiter?: boolean;
+}
+type SerialCodecConfig = JsonLinesCodecConfig | ModbusRtuCodecConfig | RawTextCodecConfig;
+interface ScpiTextCodecConfig {
+    type: 'scpi-text';
+    delimiter?: '\n' | '\r\n' | '\r';
+    maxFrameBytes: number;
+    encoding?: 'utf8' | 'latin1';
+    appendDelimiter?: boolean;
+}
+interface SerialChannelConfig {
+    logicalName: string;
+    provider: 'serial';
+    /** 可显式引用连接 profile；配置 channelBindings 后通常无需由插件传入。 */
+    profileRef?: string;
+    /** 兼容本地 bring-up；生产应由 Shell station profile 的 channelBindings 注入。 */
+    port?: string;
+    baudRate: number;
+    dataBits?: 7 | 8;
+    stopBits?: 1 | 2;
+    parity?: 'none' | 'even' | 'odd';
+    codec: SerialCodecConfig;
+    timeouts: {
+        openMs: number;
+        responseMs: number;
+        idleFrameMs?: number;
+    };
+    signals?: {
+        dtr?: boolean;
+        rts?: boolean;
+    };
+    openStabilizeMs?: number;
+}
+interface TcpChannelConfig {
+    logicalName: string;
+    provider: 'tcp';
+    /**
+     * W3-2：受保护 station profile 的引用。仪表的 host/port 由外壳按 profileRef
+     * 从 station-profile.json 注入——非回环 endpoint 不得内联（外壳 fail-closed
+     * 拒绝），除非声明 `endpointSource: 'mes-machine-instruments'`。
+     * 插件只提供非敏感业务字段（codec/timeouts/keepAlive 等）。
+     */
+    profileRef?: string;
+    /**
+     * 仪表地址。允许来源：
+     * - 回环（127.x/localhost/::1）本地 mock；
+     * - `endpointSource: 'mes-machine-instruments'` 时 MES 下发的产线 IP；
+     * - 其它非回环一律走 profileRef（内联会被外壳拒绝）。
+     */
+    host?: string;
+    /** TCP 端口。走 profileRef 时由 station profile 注入，可省略。 */
+    port?: number;
+    /**
+     * 端点权威声明。取值 `'mes-machine-instruments'` 时，instrument.* tcp 通道
+     * 可内联非回环 host/port（须先经 platform.mes 拉取 machine-instruments）。
+     * 外壳解析后剥离，不透传 Agent provider。
+     */
+    endpointSource?: 'mes-machine-instruments';
+    codec: ScpiTextCodecConfig;
+    timeouts: {
+        connectMs: number;
+        responseMs: number;
+        idleFrameMs?: number;
+    };
+    keepAlive?: boolean;
+    openStabilizeMs?: number;
+}
+/**
+ * 逻辑 MQTT broker 通道的物理映射。writeRead 的 payload 是 MQTT 操作：
+ * `{ op: 'subscribe' | 'unsubscribe', topics }` / `{ op: 'publish', topic,
+ * payload, qos?, retain? }`；broker 推送的 PUBLISH 以 unsolicited channelEvent
+ * 形式上抛（`{ event: 'mqtt-message', topic, payload }`），用 ctx.channels.subscribe 接收。
+ */
+interface MqttChannelConfig {
+    logicalName: string;
+    provider: 'mqtt';
+    /**
+     * W2-7：受保护 station profile 的引用。broker 的 host/port/username/password
+     * 由外壳按 profileRef 从 station-profile.json 注入——插件源码/插件包内不得携带
+     * 这些字段（外壳 fail-closed 拒绝内联 endpoint/凭据）。插件只提供非敏感业务
+     * 字段（clientId / keepaliveSec / timeouts）。
+     */
+    profileRef?: string;
+    /** broker 地址。仅本地调试直连可用；生产一律走 profileRef（内联会被外壳拒绝）。 */
+    host?: string;
+    port?: number;
+    clientId: string;
+    /** 已废弃的内联凭据入口：外壳一律拒绝，凭据只能来自 station profile。 */
+    username?: string;
+    password?: string;
+    /** MQTT keepalive 心跳间隔（秒，默认 30）。 */
+    keepaliveSec?: number;
+    timeouts: {
+        connectMs: number;
+        responseMs: number;
+    };
+}
+interface MockChannelConfig {
+    logicalName: string;
+    provider: 'mock';
+}
+/**
+ * S3 兼容对象存储上传通道（如阿里云 OSS）。writeRead 的 payload 是一次性操作：
+ * `{ op: 'putObject', key, contentBase64, contentType? }` → `{ ok, url, md5, size, key }`。
+ * 真正的 HTTP PUT 由宿主进程执行（宿主可出网），md5/size 也由宿主计算；沙箱内的
+ * 插件不直接触网。
+ *
+ * W2-7：endpoint/bucket/凭据一律来自受保护 station profile（profileRef 引用），
+ * 插件不得内联——外壳 fail-closed 拒绝携带这些字段的 configure 请求。
+ */
+interface OssChannelConfig {
+    logicalName: string;
+    provider: 'oss';
+    /** 受保护 station profile 的引用（endpoint/region/bucket/baseUrl/凭据由外壳注入）。 */
+    profileRef?: string;
+    /** 以下字段仅保留给本地调试直连；生产一律走 profileRef（内联会被外壳拒绝）。 */
+    endpoint?: string;
+    region?: string;
+    bucket?: string;
+    /** 拼接返回 URL 用的公开基址，如 https://<bucket>.<region>.aliyuncs.com */
+    baseUrl?: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+}
+type DeviceChannelConfig = SerialChannelConfig | TcpChannelConfig | MqttChannelConfig | OssChannelConfig | MockChannelConfig;
+type ChannelState = 'unconfigured' | 'closed' | 'opening' | 'open' | 'error';
+interface ChannelMetrics {
+    bytesRx: number;
+    bytesTx: number;
+    requestCount: number;
+    successCount: number;
+    timeoutCount: number;
+    parseErrorCount: number;
+    reopenCount: number;
+    queueDepth: number;
+    latencyMsP50: number;
+    latencyMsP95: number;
+    latencyMsMax: number;
+}
+interface ChannelStatus {
+    logicalName: string;
+    provider: 'serial' | 'tcp' | 'mqtt' | 'oss' | 'mock';
+    state: ChannelState;
+    /** serial provider 的规范化物理资源 ID；共享 binding 的 metrics 均按该资源累计。 */
+    resourceId?: string;
+    port?: string;
+    baudRate?: number;
+    host?: string;
+    tcpPort?: number;
+    lastError?: string;
+    metrics: ChannelMetrics;
+}
+type SerialUsageState = 'intent' | 'open' | 'open-failed';
+/** 一条使用记录：某插件 runtime 通过某 logical name 使用某物理资源。 */
+interface SerialUsageUser {
+    pluginId: string;
+    /** 该插件 runtime 实例的 ID（外壳每次启动 runtime 生成，插件不可伪造）。 */
+    runtimeInstanceId: string;
+    logicalName: string;
+    /**
+     * intent = configure 成功（使用意图）；open = 打开成功的 owner；
+     * open-failed = configure 冲突或 open 失败的 contender（持续保留显示冲突原因）。
+     */
+    state: SerialUsageState;
+    /** 规范化连接配置（剔除凭据字段）的 sha256——profile 不同即 hash 不同。 */
+    connectionProfileHash: string;
+    openedAt?: string;
+    errorCode?: string;
+}
+/**
+ * 一个物理资源的使用快照（15 章 P0-05 数据模型）。resourceId 为规范化物理资源
+ * key（serial 别名已合并，如 `serial:endpoint:58b20024743`）；conflict 只对
+ * serial 类资源判定：去重后的非 shell-debug pluginId 数量 > 1。平台只观测告警，
+ * 不自动停止、不抢占、不策略性拒绝（B3/D02）。
+ */
+interface SerialUsageSnapshot {
+    resourceId: string;
+    provider: 'serial' | 'tcp' | 'mqtt' | 'oss';
+    users: SerialUsageUser[];
+    conflict: boolean;
+}
+/**
+ * 通过单一通道将事件从主进程推送到渲染进程。
+ *
+ * `uiMessage` 携带一个 OPAQUE（不透明）的 api-bridge 信封，从插件运行时回传到
+ * 插件 UI 的 iframe（轴 A）。外壳从不检查 `envelope`。
+ */
+type RuntimeEvent = {
+    kind: 'status';
+    status: RuntimeStatus;
+} | {
+    kind: 'log';
+    log: RuntimeLogEntry;
+} | {
+    kind: 'stepEvent';
+    event: StepEvent;
+} | {
+    kind: 'stepResult';
+    pluginId: string;
+    result: StepResult;
+    /**
+     * W4-4（P0-07 第 10 条）：production 模式下，1.x（legacy）插件的 report
+     * 结果若其 exact digest 未通过 legacy verdict allowlist 审核，外壳标注
+     * legacy-unverified。该结果仍进 UI 记录面板，但绝不进入正式 outbox
+     * ——1.x 结果本就没有 run 生命周期，进入正式 MES 的唯一途径是未来经
+     * legacy adapter 显式桥接 + allowlist 审核（当前不桥接）。
+     */
+    legacyUnverified?: true;
+} | {
+    kind: 'uiMessage';
+    pluginId: string;
+    envelope: unknown;
+}
+/** 主进程请求 renderer 聚焦某个插件（例如后台一键就绪完成后）。 */
+ | {
+    kind: 'focusPlugin';
+    requestId: string;
+    pluginId: string;
+    version?: string;
+    source: 'machine-ready';
+}
+/** Auth runtime 只请求 Shell 打开可信凭据对话框；token 不进入插件进程。 */
+ | {
+    kind: 'credentialConfigurationRequested';
+    pluginId: string;
+}
+/** 安装确认只在 Shell renderer 的可信 UI 展示；插件 iframe 不能代替操作员确认。 */
+ | {
+    kind: 'pluginInstallConfirmationRequested';
+    request: PluginInstallConfirmationRequest;
+} | {
+    kind: 'unofficialRunConfirmationRequested';
+    prompt: UnofficialPluginRunPrompt;
+}
+/**
+ * 开发闭环（development profile）：local-dev 插件的来源目录构建产物
+ * （runtime-dist / ui-dist / manifest.json）发生变化。调试页据此提示
+ * "产物已更新，点击重载生效"——刻意不自动重启（runtime 可能正持有串口/夹具）。
+ */
+ | {
+    kind: 'localDevSourceChanged';
+    pluginId: string;
+};
+
+/**
+ * 轴 A（插件 UI <-> 插件运行时）的传输层。外壳负责传递不透明信封；
+ * @international-iot-association/plugin-sdk 在其之上叠加一个 API-Bridge 服务端。
+ */
+interface PluginUiTransport {
+    /** 向插件 UI 的 iframe 发送一个不透明信封。 */
+    postMessage(envelope: unknown): void;
+    /** 注册一个处理器，用于接收来自插件 UI iframe 的不透明信封。 */
+    onMessage(handler: (envelope: unknown) => void): void;
+}
+/**
+ * 轴 D（插件 runtime <-> 插件 runtime）的服务总线。与轴 A 同构：外壳只按
+ * from/to 路由不透明信封，永不解析内容。路由授权规则（外壳强制）：
+ * A -> B 允许当且仅当 B ∈ A.dependencies 或 A ∈ B.dependencies。
+ * 请使用 @international-iot-association/plugin-sdk 的 createServiceClient / createServiceServer，
+ * 不要直接操作本传输层。详见 docs/global-plugins.md。
+ */
+interface PluginServiceBus {
+    /** 向目标插件 runtime 发送一个不透明信封（外壳校验路由权限，违规丢弃并记日志）。 */
+    postMessage(targetPluginId: string, envelope: unknown): void;
+    /** 接收来自其他插件的信封；`from` 为对端 pluginId，由外壳注入、不可伪造。 */
+    onMessage(handler: (from: string, envelope: unknown) => void): void;
+}
+/**
+ * 插件私有本地存储（需在 manifest.permissions 声明 `"storage"`，否则
+ * ctx.storage 为 undefined）。相对路径不得逃逸（宿主强制包含检查）。缺省根目录为
+ * `<data>/<pluginId>/versions/<version>/`；只有显式 `storage.scope: "shared"` 才使用
+ * `<data>/<pluginId>/shared/` 跨版本保留数据。
+ */
+interface PluginStorage {
+    /** 数据目录绝对路径（仅供展示/日志，读写请走下面的 API）。 */
+    readonly dir: string;
+    /** 读取文本文件；不存在返回 null。 */
+    read(relPath: string): Promise<string | null>;
+    /** 写入（覆盖）文本文件；自动创建父目录。 */
+    write(relPath: string, content: string): Promise<void>;
+    /** 追加文本；文件/父目录不存在时自动创建。 */
+    append(relPath: string, content: string): Promise<void>;
+    /** 列出目录下的文件名（不含子目录内容）；目录不存在返回 []。 */
+    list(relDir?: string): Promise<string[]>;
+    /** 删除文件；不存在时静默成功。 */
+    remove(relPath: string): Promise<void>;
+}
+/** durable receipt：平台落盘（fsync）成功后才返回（{runId, sequence, persistedAt}）。 */
+interface PlatformDurableReceipt {
+    runId: string;
+    /** begin=0；每条 step 为其 sequence；terminal 记录复用最后 sequence。 */
+    sequence: number;
+    persistedAt: string;
+}
+/** 一次产测 run 的被测对象（SN/工单/机型，均可选）。 */
+interface PlatformRunSubject {
+    sn?: string;
+    workOrderId?: string;
+    model?: string;
+}
+/** ctx.platform.appendStep 的入参（sequence 由平台分配，插件不提供）。 */
+interface PlatformRunStep {
+    stepKey: string;
+    /** 同一步骤的第几次尝试（缺省 1）。 */
+    attempt?: number;
+    ok: boolean;
+    measurements?: Record<string, unknown>;
+    raw?: string;
+    error?: string;
+    startedAt: string;
+    finishedAt: string;
+}
+/**
+ * 平台盖章后的 run 归属模式：只有纯 production 平台模式才产生 production run；
+ * maintenance-simulated / development 一律 simulated。
+ * completeRun 仅本地 journal，不上传 MES envelope。
+ */
+type PlatformRunResultMode = 'production' | 'simulated';
+/**
+ * MES 代发 HTTP 方法（agentApi 3.0 + manifest `mes:api`）。
+ * 插件只传相对 path；token/指纹由 Shell 附加，绝不回传插件。
+ */
+type MesHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/** query 参数值：Shell 转为字符串并 encode；禁止嵌套对象/数组。 */
+type MesParamValue = string | number | boolean;
+/** 单次 MES 代发选项。默认 delivery=live。 */
+interface MesRequestOptions {
+    /** query 键值；不得写在 path 字符串内。 */
+    params?: Record<string, MesParamValue>;
+    /**
+     * live：立即代发 MES。
+     * outbox：落盘入队（仅写方法）；await 只表示已入队。
+     */
+    delivery?: 'live' | 'outbox';
+    /**
+     * 目标平台 Run id。
+     * - 无 active run 时：普通 live 可省略；显式 runId 因无法命中 active set 而拒绝；
+     *   outbox 仍要求显式且有效的 runId。
+     * - 单 active run 时：live/outbox 均可省略以兼容旧代码。
+     * - 多 active run 时：outbox 必须显式提供且命中当前 active set；
+     *   live 可省略（不归属任何 Run，用工位当前 mode），显式 runId 仍必须命中 active set。
+     */
+    runId?: string;
+    /**
+     * 本次 live 代发的单次超时（毫秒）。省略时用 Shell 全局默认（60s）。
+     *
+     * 为什么需要它：插件若想在应用层做「失败重试 N 次」，单次超时就必须由插件
+     * 定；否则 N × 全局 60s 会把一次操作卡上好几分钟。有了它，超时只有一个闸
+     * （Shell 侧），插件不必再叠一层 `Promise.race`——那样 Shell 的 fetch 不会被
+     * 取消，只会留一串悬挂请求占住代发并发槽。
+     *
+     * 约束：
+     * - Shell 钳制到 `[1s, 60s]`，**只能调小不能调大**；非法值（0/负数/NaN/
+     *   非 number）一律回落全局默认，不报错。
+     * - **只作用于 `delivery:'live'`**。outbox 排水是 Shell 后台自己的节奏，
+     *   入队记录也不持久化本字段，排水一律用全局默认。
+     * - 旧 Shell（不认识本字段）会在逐字段透传时**静默丢弃**它，超时退回 60s。
+     *   本字段不参与 agentApi 能力协商，插件无法探测对端是否支持。
+     */
+    timeoutMs?: number;
+}
+/** live 代发结果：HTTP 已结束；4xx/5xx 不抛。 */
+interface MesLiveResult {
+    kind: 'live';
+    status: number;
+    data: unknown;
+}
+/** outbox 入队结果：已落盘；不等于 MES 已过站。 */
+interface MesQueuedResult {
+    kind: 'queued';
+    receiptId: string;
+    runId: string;
+    enqueuedAt: string;
+}
+type MesResult = MesLiveResult | MesQueuedResult;
+/**
+ * agentApi 3.0 + `mes:api`：path 形态 MES 客户端（挂在 ctx.platform.mes）。
+ * get/delete 禁止 body；post/put/patch body 可省略，若传则 JSON 序列化。
+ */
+interface PluginPlatformMes {
+    get(path: string, options?: MesRequestOptions): Promise<MesResult>;
+    post(path: string, body?: unknown, options?: MesRequestOptions): Promise<MesResult>;
+    put(path: string, body?: unknown, options?: MesRequestOptions): Promise<MesResult>;
+    patch(path: string, body?: unknown, options?: MesRequestOptions): Promise<MesResult>;
+    delete(path: string, options?: MesRequestOptions): Promise<MesResult>;
+}
+/**
+ * @deprecated agentApi 2.x 具名 operation 面；3.0 已删除，勿在新代码使用。
+ * 保留类型名仅避免历史文档引用炸类型搜索；运行时不再注入。
+ */
+interface PluginPlatformHttp {
+    invokeOperation(operation: string, params?: Record<string, string>, body?: unknown): Promise<{
+        status: number;
+        body: unknown;
+    }>;
+}
+/** agentApi 2.1.0 向插件公开的最小机器凭据状态；不包含 token 或 token 尾号。 */
+interface PluginCredentialStatus {
+    state: PlatformCredentialStatus['state'];
+    environmentTag?: string;
+    verifiedAt?: string;
+}
+/**
+ * agentApi 2.1.0 的机器凭据窄接口。配置请求只让 Shell renderer 打开可信
+ * 对话框，token 输入值绝不经过 iframe/runtime。
+ */
+interface PluginPlatformCredential {
+    getStatus(): Promise<PluginCredentialStatus>;
+    requestConfiguration(): Promise<void>;
+}
+/** agentApi 2.2.0：插件只能请求安装的包标识；安全元数据由 Shell 重新取得。 */
+interface PluginInstallPackageRequest {
+    packageId: string;
+    version: string;
+}
+interface PluginInstallRequestInput {
+    /** 工单加载器必须携带；Shell 会重新解析工单并校验 packageId/version 子集。 */
+    workOrder?: string;
+    packages: PluginInstallPackageRequest[];
+}
+type PluginInstallProgressStatus = 'pending' | 'confirmed' | 'rejected' | 'downloading' | 'installed' | 'failed';
+/** 单包安装状态；reason 必须是脱敏文案，不得包含 token 或预签名下载地址。 */
+interface PluginInstallProgress {
+    requestId: string;
+    packageId: string;
+    version: string;
+    status: PluginInstallProgressStatus;
+    reason?: string;
+    /** 已安装同版本时为 true；此时不会重新下载。 */
+    skipped?: boolean;
+}
+interface PluginInstallRequestResult {
+    requestId: string;
+    packages: PluginInstallProgress[];
+}
+/** Shell 可信确认对话框使用的安全摘要；不包含 token、下载 URL 或签名原文。 */
+interface PluginInstallConfirmationPackage {
+    packageId: string;
+    name: string;
+    version: string;
+    releaseStatus: 'released' | 'draft';
+    sizeBytes: number | null;
+    signatureState: 'signed' | 'unsigned';
+    installedVersion: string | null;
+}
+interface PluginInstallConfirmationRequest {
+    requestId: string;
+    pluginId: string;
+    workOrder?: string;
+    packages: PluginInstallConfirmationPackage[];
+}
+/**
+ * agentApi 2.2.0 的受控安装请求面。请求会立即返回逐包快照；可信确认、下载与
+ * 安装结果通过 onProgress 推送。进度事件与 request Promise 响应没有先后保证：
+ * 调用方必须先订阅，再按响应中的 requestId 和原始包集合缓冲、约束并合并事件。
+ */
+interface PluginPlatformInstall {
+    getInstalledVersions(packageIds: string[]): Promise<Record<string, string | null>>;
+    request(input: PluginInstallRequestInput): Promise<PluginInstallRequestResult>;
+    onProgress(handler: (event: PluginInstallProgress) => void): () => void;
+}
+/**
+ * 全局结构化日志（Shell 内部 StationLogService；原 rti.global.logger 插件下沉）。
+ *
+ * **业务写入面（ADR-0002）**：插件应使用 `ctx.logger` 或 `@international-iot-association/plugin-logger` 门面。
+ * `ctx.platform.log` 仅保留兼容/查询；新业务代码不要再 `platform.log.write`。
+ * agentApi 3 的 ctx.platform 仍恒带 `log`（查询/stats/迁移期写入）。
+ * `source` 由宿主按 pluginId 盖章，调用方无法伪造。
+ */
+type PlatformLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** 插件 runtime 日志句柄（唯一业务写入面；可带结构化 data）。 */
+interface PluginLogger {
+    debug(msg: string, data?: Record<string, unknown>): void;
+    info(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    error(msg: string, data?: Record<string, unknown>): void;
+}
+interface PlatformLogEntryInput {
+    level: PlatformLogLevel;
+    message: string;
+    tags?: string[];
+    data?: Record<string, unknown>;
+    /** ISO 时间戳；缺省由 Shell 按接收时刻填充。 */
+    ts?: string;
+}
+interface PlatformLogEntry extends PlatformLogEntryInput {
+    ts: string;
+    /** 来源 pluginId（宿主填充）。 */
+    source: string;
+}
+interface PlatformLogWriteAck {
+    ok: boolean;
+    accepted: number;
+    error?: string;
+}
+interface PlatformLogQuery {
+    limit?: number;
+    levels?: PlatformLogLevel[];
+    sources?: string[];
+    tags?: string[];
+}
+interface PlatformLogQueryResult {
+    ok: boolean;
+    entries: PlatformLogEntry[];
+    error?: string;
+}
+interface PlatformLogStats {
+    ok: boolean;
+    currentFile: string;
+    writtenTotal: number;
+    pending: number;
+    files: string[];
+}
+interface PluginPlatformLog {
+    write(entry: PlatformLogEntryInput): Promise<PlatformLogWriteAck>;
+    writeBatch(entries: PlatformLogEntryInput[]): Promise<PlatformLogWriteAck>;
+    query(q?: PlatformLogQuery): Promise<PlatformLogQueryResult>;
+    stats(): Promise<PlatformLogStats>;
+}
+interface PluginPlatformRfStationAssetSnapshot {
+    stationProfile: unknown;
+}
+interface PluginPlatformRfSecureMaterialRequest {
+    kind: "string" | "auth" | "triple";
+    ref: string;
+    params?: Record<string, string | number | boolean>;
+}
+interface PluginPlatformRfSecureMaterialPreflightRequest {
+    entries: Array<{
+        kind: "string" | "auth" | "triple";
+        ref: string;
+    }>;
+}
+interface PluginPlatformRfSecureMaterialStringResponse {
+    kind: "string";
+    value: string;
+}
+interface PluginPlatformRfSecureMaterialAuthResponse {
+    kind: "auth";
+    cipher: string;
+    source: "local-md5" | "certificate" | "simulated";
+}
+interface PluginPlatformRfSecureMaterialTripleResponse {
+    kind: "triple";
+    productId: string;
+    deviceId: string;
+    secret: string;
+    source: "mes-lease" | "simulated";
+}
+type PluginPlatformRfSecureMaterialResponse = PluginPlatformRfSecureMaterialStringResponse | PluginPlatformRfSecureMaterialAuthResponse | PluginPlatformRfSecureMaterialTripleResponse;
+interface PluginPlatformRf {
+    getStationAssetSnapshot(): Promise<PluginPlatformRfStationAssetSnapshot>;
+    /** 只核对当前插件 scope 内的 ref 与类型，不读取或返回秘密。 */
+    preflightSecureMaterials(request: PluginPlatformRfSecureMaterialPreflightRequest): Promise<{
+        ok: true;
+    }>;
+    resolveSecureMaterial(request: PluginPlatformRfSecureMaterialRequest): Promise<PluginPlatformRfSecureMaterialResponse>;
+}
+/**
+ * agentApi 3.0 的 ctx.platform：本地 run 生命周期 + 全局日志 + 可选 MES 代发。
+ * 语义要点：
+ * - begin/append/complete/interrupt 返回 durable receipt（本地 journal fsync）；
+ *   complete/interrupt **不**触发 MES envelope 上报；
+ * - plugin stamp 由外壳按 installed 登记盖章，绝不采信 runtime 自报身份；
+ * - beginRun 默认仍是单 active run 语义；只有 `{ concurrent: true }` 才允许在
+ *   同一 runtime 内并发开启第二个及以上 run；
+ * - append/complete/interrupt 在单 active run 时可省略 runId 以兼容旧代码；
+ *   若当前存在多个 active run，则省略 runId 会被宿主明确拒绝；
+ * - `log` 恒注入（agentApi 3）：NDJSON 由 Shell Main 落盘，无独立 logger 插件进程；
+ * - `mes` 仅当 manifest 声明 `mes:api` 时注入；细权在机器 token 后端 scope；
+ * - 无具名 invokeOperation 插件面（ADR-0001）。
+ */
+interface PlatformBeginRunOptions {
+    concurrent?: boolean;
+}
+interface PlatformRunTargetOptions {
+    runId?: string;
+}
+/** 原生扫码结构化错误码（ADR-0009）。字符串错误只作诊断，业务必须看 code。 */
+type ScannerErrorCode = 'SCANNER_UNAVAILABLE' | 'CAMERA_NOT_FOUND' | 'CAMERA_OPEN_FAILED' | 'CAMERA_DISCONNECTED' | 'NO_CODE' | 'MULTIPLE_CODES' | 'TIMEOUT' | 'CANCELLED' | 'DUPLICATE_TRIGGER' | 'INVALID_REQUEST' | 'PERMISSION_DENIED';
+interface ScannerCameraInfo {
+    cameraId: string;
+    label: string;
+    backend: 'mf' | 'avf' | 'fake';
+}
+interface ScannerRoi {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface ScannerScanRequest {
+    scanId: string;
+    sessionId: string;
+    seatIndex: number;
+    cameraId: string;
+    triggerSource: 'fixture-press' | 'manual-rescan';
+    triggeredAt: string;
+    deadlineMs: number;
+    settleMs?: number;
+    frameCount?: number;
+    roi?: ScannerRoi;
+}
+interface ScannerCandidate {
+    rawText: string;
+    format: string;
+}
+interface ScannerSeatResult {
+    cameraId: string;
+    imageId: string;
+    frameTs: string;
+    ok: boolean;
+    rawText?: string;
+    candidates: ScannerCandidate[];
+    captureMs: number;
+    roiMs: number;
+    decodeMs: number;
+    width?: number;
+    height?: number;
+    roi?: ScannerRoi;
+    errorCode?: ScannerErrorCode;
+    errorMessage?: string;
+}
+interface NativeScanResult {
+    scanId: string;
+    sessionId: string;
+    seatIndex: number;
+    ok: boolean;
+    result: ScannerSeatResult;
+    totalMs: number;
+    decoderVersion: string;
+    cameraConfigVersion: string;
+}
+interface ScannerHealth {
+    available: boolean;
+    decoderVersion: string;
+    cameras: Array<{
+        cameraId: string;
+        ready: boolean;
+        errorCode?: ScannerErrorCode;
+    }>;
+}
+/**
+ * agentApi 3 + `platform:scanner`：按席触发式原生扫码（ADR-0009）。
+ * 插件不得自己打开摄像头或解码。
+ */
+interface PluginPlatformScanner {
+    listCameras(): Promise<ScannerCameraInfo[]>;
+    healthCheck(): Promise<ScannerHealth>;
+    configure(cameras: Array<{
+        cameraId: string;
+        seatIndex: number;
+        roi?: ScannerRoi;
+    }>): Promise<{
+        ok: true;
+    }>;
+    scan(request: ScannerScanRequest): Promise<NativeScanResult>;
+    cancel(scanId: string): Promise<{
+        ok: true;
+    }>;
+}
+/**
+ * 机台上传对象：把失败现场（过程日志、整窗截图）传到 MES 绑定的对象库。
+ *
+ * 插件只声明「传哪个 storage 相对路径」「要不要一张整窗截图」——STS 凭证、机器
+ * token、bucket/endpoint 与文件字节全部收敛在 Shell 主进程，插件一概拿不到，
+ * 通讯面上也只走路径字符串，不搬字节。
+ *
+ * **失败走返回值联合，不走 reject**：宿主把 rejection 压成 `err.message` 字符串
+ * 转发，自定义字段会全部丢失，而产线 UI 规范要求故障代码必须能到操作员眼前。
+ * 只有传输层问题（宿主未接线 / runtime 掉线）才会 reject。
+ */
+type PluginUploadSource = {
+    kind: 'storage-file';
+    /** ctx.storage 相对路径，如 `runs/20260823T031500Z_s0_SN123_run-1.log`。 */
+    path: string;
+    /** 对象相对名的基名；缺省取 path 的 basename。宿主一律清洗，不采信原样。 */
+    label?: string;
+    contentType?: string;
+} | {
+    kind: 'window-screenshot';
+    /** 对象相对名的基名，缺省 `screen`。 */
+    label?: string;
+} | {
+    kind: 'dialog-file';
+    /**
+     * `ctx.dialog.openFile()` 返回的文件 handle（需 `ui:file-dialog` 权限）。
+     *
+     * 为什么是 handle 而不是路径：沙箱 UI 与插件 runtime 都拿不到用户选中文件的
+     * 绝对路径（W1-7），宿主只发一个不透明 handle。上传时宿主用自己的登记表把它
+     * 兑换回路径、自己读盘直传对象库——**字节与路径全程不进插件进程**，
+     * 与 storage-file / window-screenshot 是同一条口径。
+     *
+     * 与设备通道兑换的差别：上传兑换**不消耗使用次数**，只受 handle 自身的
+     * 有效期约束。理由是上传失败要能让操作员原地点「重试」，而不是把刚选的
+     * 一二十个文件重选一遍；读文件本身是幂等的，与「同一份固件被重放进设备」
+     * 不是一类风险。handle 过期或 runtime 停止后照常失效。
+     */
+    handle: string;
+    /** 对象相对名的基名；缺省取宿主侧的文件名。宿主一律清洗，不采信原样。 */
+    label?: string;
+    contentType?: string;
+};
+interface PluginUploadRequest {
+    /** 1..20 个来源，顺序即登记顺序。 */
+    sources: PluginUploadSource[];
+    /** 对象名分组段，如 `pcba/SN123`；宿主逐段清洗。缺省不分组。 */
+    group?: string;
+    /**
+     * 归属测试记录，**必须成对**（宿主在任何网络调用之前就校验，单传其一直接
+     * invalid-request）。`testKind` 只认 `'pcba'` / `'product'`，大小写敏感；
+     * `testId` 必须是正整数。
+     *
+     * PCBA 站的取法：MES result-submit 的 live 2xx 回包带 `data.testRecordId`。
+     * 回落 outbox（还没落库）、无写通道、只读模式都拿不到 id——那时两个字段**都**
+     * 不要带，对象照样传得上去，只是在 Admin 测试详情页挂不出来，得去机台上传
+     * 会话列表里翻。
+     */
+    testKind?: string;
+    testId?: number;
+    /** 本地 runId，仅进宿主日志用于串联，不上送后端。 */
+    runId?: string;
+}
+interface PluginUploadedObject {
+    objectId: string;
+    relativeKey: string;
+    sizeBytes: number;
+    /** 对应 request.sources 的下标，便于插件回填自己的 UI。 */
+    sourceIndex: number;
+}
+type PluginUploadFailureCode = 
+/** token 缺 object-upload:write scope —— 找管理员开权限。 */
+'permission-denied'
+/** 机台被后台锁定 —— 与缺 scope 同为 403，但要做的是解锁机台，不是开权限。 */
+ | 'machine-locked'
+/** 机器令牌失效/被吊销（401）—— 要重新配对机台，重试无用。 */
+ | 'unauthorized'
+/** 对象库拒绝（STS 票过期或策略不匹配）。重传会开新会话拿新票，故可重传。 */
+ | 'store-denied' | 'invalid-request' | 'not-found' | 'conflict' | 'service-unavailable' | 'network' | 'source-missing' | 'source-too-large' | 'screenshot-unavailable'
+/** 机台本地上传通道暂时排满（并发或内存配额）—— 稍后重试即可。 */
+ | 'busy' | 'internal';
+type PluginUploadOutcome = {
+    ok: true;
+    sessionId: string;
+    objects: PluginUploadedObject[];
+    totalBytes: number;
+    durationMs: number;
+} | {
+    ok: false;
+    code: PluginUploadFailureCode;
+    /** 稳定故障代码，直接进 UI「故障代码」栏，如 `UP-AUTH-403`。 */
+    faultCode: string;
+    /** 是否值得让操作员点「重新上传」。 */
+    retryable: boolean;
+    /** 技术细节（可能是后端英文原文），只进日志；禁止单独当操作员文案。 */
+    detail: string;
+    /** 后端 requestId（有则带），供跨系统追溯。 */
+    requestId?: string;
+    attempts: number;
+    /** 失败前已成功传上去的对象数，用于「部分上传」提示。 */
+    uploadedBeforeFailure: number;
+};
+interface PluginPlatformUpload {
+    /**
+     * 一次调用 = 一个上传会话，内含有限次退避重试；最终失败返回 `ok:false`，
+     * **不落持久化队列**。将来若加队列，会新增 `{ ok:true, queued:true }` 分支，
+     * 现有 `if (outcome.ok)` 判断不受影响。
+     */
+    submit(request: PluginUploadRequest): Promise<PluginUploadOutcome>;
+}
+/**
+ * 一对已铸造的虚拟串口（socat PTY 对）。
+ *
+ * 两端是同一条管道的两头：往 `simulatorPath` 写的字节，从 `clientPath` 读得到，
+ * 反之亦然。
+ */
+interface VirtualSerialPairInfo {
+    /** 释放时用的句柄。 */
+    pairId: string;
+    /**
+     * **仿真器自己那一端。** 仿真插件用 `node:fs` / `serialport` 打开它，
+     * 扮演被测设备读写字节。
+     */
+    simulatorPath: string;
+    /**
+     * **客户端那一端——只读文本，给人看的。**
+     *
+     * 把它显示出来供操作者复制，然后由**人**去工位插件的通道配置里填上。
+     * Shell 不会、也没有能力替谁把它绑进任何通道（ADR-0031 D6）：真机上没有谁会
+     * 把串口自动绑进插件，仿真台跳过这一步，等于把「产线准备流程」这段最容易出错的
+     * 部分从演练里删掉，到了真机上第一次做就是在产线上做。
+     */
+    clientPath: string;
+    /** 铸造时传入的人类标签（如「夹具」「DUT」），未传为 null。 */
+    label: string | null;
+    /**
+     * 铸造时传入的板级标识，未传为 null。
+     *
+     * 同一块**虚拟板**的多条 PTY 传同一个值——外壳会把它投影到
+     * `SerialPortInfo.boardId`，让「哪两条口是同一块板」这件事有明确答案，
+     * 而不是靠路径号相邻去猜（那正是 ADR-0031 D6 删掉的自动发现）。
+     * 仿真台一席铸「夹具 + DUT」两条口时必须传同一个值，否则向导只能看到
+     * 两条互不相干的口，配不成一套夹具。
+     */
+    boardId: string | null;
+    createdAt: number;
+}
+/**
+ * 虚拟串口能力（ADR-0031 D2）。可用需要**同时**满足两个条件，但两个条件
+ * 各管一件事，**不要把它们混成一个判断**：
+ *
+ * 1. **manifest.permissions 含 `devtools:virtual-serial` → 决定这些方法在不在。**
+ *    没声明权限时 `ctx.platform.virtualSerial` 为 `undefined`。
+ * 2. **Shell 设置里的「虚拟串口」开关 → 决定调用成不成。**
+ *    开关默认关闭；关着时方法**存在但调用抛错**，错误里带开启路径。
+ *
+ * 分工的原因是开关运行期可变（用户随时能关），而 ctx 只在 activate 时构一次；
+ * 把开关冻进 ctx 会让「界面说关了、插件还以为开着」。所以：
+ * **`undefined` 一律读作「这个插件没申请这项权限」，不是「开关没开」。**
+ *
+ * 两条路径都**绝不静默降级**——静默降级会让人以为仿真台在跑。调用方应当把
+ * 抛出的原因原样显示给用户（含开启路径），而不是吞掉改走假数据。
+ *
+ * 仅 macOS 与 Linux 支持（依赖 socat 铸造 PTY 对），Windows 明确不支持。
+ * **产线形态只验证过 macOS**——Linux 是为 CI 回归开放的，不要据此认为 Linux 工位可用。
+ */
+interface PluginPlatformVirtualSerial {
+    /**
+     * 铸造一对 PTY。socat 缺失 / 平台不支持 / 开关关闭时抛错，**绝不静默成功**。
+     *
+     * `boardId`：同一块虚拟板的多条 PTY 传同一个值（见 `VirtualSerialPairInfo.boardId`）。
+     */
+    create(options?: {
+        label?: string;
+        boardId?: string;
+    }): Promise<VirtualSerialPairInfo>;
+    /** 释放一对 PTY（引用计数减一，归零时 Shell 杀掉 socat）。未知 pairId 幂等成功。 */
+    release(pairId: string): Promise<{
+        ok: true;
+    }>;
+    /** 本插件当前持有的 PTY 对。 */
+    list(): Promise<VirtualSerialPairInfo[]>;
+}
+interface PluginPlatformApi {
+    /** 当前平台运行模式（activate 下发初始值 + platformMode 推送即时更新）。 */
+    readonly mode: PlatformRunMode;
+    beginRun(subject: PlatformRunSubject, configRefs?: Record<string, string>, options?: PlatformBeginRunOptions): Promise<{
+        receipt: PlatformDurableReceipt;
+        mode: PlatformRunResultMode;
+    }>;
+    appendStep(step: PlatformRunStep, options?: PlatformRunTargetOptions): Promise<PlatformDurableReceipt>;
+    completeRun(verdict: 'pass' | 'fail', options?: PlatformRunTargetOptions): Promise<PlatformDurableReceipt>;
+    interruptRun(reason: string, options?: PlatformRunTargetOptions): Promise<PlatformDurableReceipt>;
+    /** 全局结构化日志（Shell 常驻；source 由宿主盖章）。 */
+    log: PluginPlatformLog;
+    /**
+     * MES path 客户端。仅 manifest.permissions 含 `mes:api` 时提供；
+     * 否则为 undefined（与缺权限区分于「无凭据」——无凭据时 mes 仍在但调用抛错）。
+     */
+    mes?: PluginPlatformMes;
+    /** manifest 声明 `platform:credential` 时提供。 */
+    credential?: PluginPlatformCredential;
+    /** manifest 声明 `platform:plugin-install` 时提供。 */
+    pluginInstall?: PluginPlatformInstall;
+    /**
+     * 受保护 RF 工位资产与敏感材料能力。
+     * 仅对声明 `platform:rf-station` 权限的 RF 插件提供。
+     */
+    rf?: PluginPlatformRf;
+    /** manifest 声明 `platform:scanner` 时提供（ADR-0009）。 */
+    scanner?: PluginPlatformScanner;
+    /** manifest 声明 `platform:object-upload` 时提供（机台上传对象）。 */
+    upload?: PluginPlatformUpload;
+    /**
+     * manifest 声明 `devtools:virtual-serial` 时提供（ADR-0031 D2/D3）。
+     * **`undefined` = 没申请这项权限**；Shell 设置开关是否打开不影响这里在不在，
+     * 它决定的是 `create()` 调用成不成（关着时抛错）。
+     */
+    virtualSerial?: PluginPlatformVirtualSerial;
+}
+/**
+ * 在宿主进程内交给插件运行时的受控上下文
+ *（构造于 electron-station-shell 的 plugin-host/runner.ts）。插件除此之外
+ * 什么都拿不到——没有 fs、没有 db、没有真实串口、没有后端 token。
+ */
+interface PluginRuntimeContext {
+    /** 唯一业务日志写入面（ADR-0002）；可选第二参为结构化 data。 */
+    logger: PluginLogger;
+    channels: {
+        writeReadMock(logicalName: string, payload: string): Promise<{
+            logicalName: string;
+            request: string;
+            response: string;
+            latencyMs: number;
+        }>;
+        /**
+         * 真实设备通道。路由路径为 runner -> host -> Agent Device Broker -> provider。
+         * 插件永远看不到原始端口。需要在 manifest.permissions 中声明该通道。
+         *
+         * 电流表 qt-burst 连采：payload 为 `{ kind: "scpi-qt-burst", count, intervalMs, ... }`
+         * 时，新外壳在 Agent 内循环 INITiate+READ?，一次返回 `acceptedSamplesA`。
+         * 不是通用 TCP 剧本。老外壳会拒识该 payload，插件应回退逐枪 writeRead。
+         */
+        writeRead(logicalName: string, payload: unknown, options?: {
+            timeoutMs?: number;
+            codec?: 'json-lines' | 'modbus-rtu' | 'raw-text' | 'scpi-text';
+            expectResponse?: boolean;
+            /**
+             * raw-text 专用：本次调用的「回包结束标记」。收到它之后只再等一小段
+             * 静默就返回，不等满 timeoutMs。缺省 `CLI_OK`（工厂 CLI 的完成字样）。
+             *
+             * 为什么要按次传而不是写死通道级常量：回包里没有 `CLI_OK` 的命令
+             * （不同固件/非 tct 指令）会一路等满超时，整条产测被拖长；调用方最清楚
+             * 自己这条命令的结束标记是什么。匹配不区分大小写。
+             */
+            expectToken?: string;
+        }): Promise<{
+            logicalName: string;
+            request: unknown;
+            response: unknown;
+            latencyMs: number;
+        }>;
+        /**
+         * 订阅某个逻辑通道上的非请求触发（unsolicited）设备事件。需要在
+         * manifest.permissions 中声明该通道。运行时停止时处理器会被丢弃。
+         * serial 订阅本身不 open/独占物理串口；资源事件会扇出到 active logical consumer。
+         * 返回反注册函数：移除本次注册的 handler（重复调用幂等）。宿主级订阅
+         * 保持存在，由运行时停止统一回收（协议面无 unsubscribe 消息）。
+         */
+        subscribe(logicalName: string, handler: (event: Record<string, unknown>) => void): () => void;
+        /**
+         * 受控通道生命周期操作。插件仍然看不到真实串口句柄；宿主会按 manifest.permissions
+         * 校验 logicalName。`configure/open/close/status/updateBaudRate` 必须声明对应通道的 `.control`
+         * 权限，例如 `serial.dut.control` 或 `channel.serial.dut.control`；只声明
+         * `serial.dut` / `serial.dut.writeRead` 只能读写/订阅，不能控制生命周期。
+         * serial 的 open/close 是 caller-scoped attachment/detachment；同一 caller 必须
+         * 先 open 才能 writeRead，最后一个 attachment 释放后才关闭物理串口。
+         * `updateBaudRate` 只改已打开串口的波特率，不关口；非串口通道或不在 open 态会拒绝。
+         * 未调用该动作的插件行为与以前完全相同。
+         * `listPorts`/`detectDevices` 需要显式 `serial.discovery`（或粗粒度 `serial`）
+         * 权限。`listPorts` 只返回 Agent 已合并过的端口元数据；`detectDevices` 返回
+         * Agent 协议探测建议，但不授予任何额外通道访问权。
+         */
+        control(request: {
+            action: 'listPorts';
+        } | {
+            action: 'detectDevices';
+        } | {
+            action: 'configure';
+            config: DeviceChannelConfig;
+        } | {
+            action: 'open';
+            logicalName: string;
+        } | {
+            action: 'close';
+            logicalName: string;
+        } | {
+            action: 'status';
+            logicalName: string;
+        } | {
+            action: 'updateBaudRate';
+            logicalName: string;
+            baudRate: number;
+        }): Promise<SerialPortInfo[] | SerialDeviceSuggestion[] | ChannelStatus>;
+    };
+    /** 轴 B：向外壳上报进度/结果（日志 + 记录面板）。 */
+    report: {
+        stepEvent(event: {
+            stepKey: string;
+            phase?: string;
+            message: string;
+        }): void;
+        result(result: StepResult): void;
+    };
+    /** 轴 A：通往插件 UI iframe 的传输层（由 @international-iot-association/plugin-sdk 使用）。 */
+    ui: PluginUiTransport;
+    /** 轴 D：插件间服务总线（由 @international-iot-association/plugin-sdk 的 service client/server 使用）。 */
+    bus: PluginServiceBus;
+    /** 插件私有本地存储；仅当 manifest.permissions 含 `"storage"` 时提供。 */
+    storage?: PluginStorage;
+    /**
+     * 原生文件对话框（主进程执行）；仅当 manifest.permissions 含 `"ui:file-dialog"`
+     * 时提供，否则为 undefined。用于让操作员选择本机文件（如 OTA 固件）。宿主不返回
+     * 绝对路径，只返回一次性 opaque handle（W1-7）——插件在设备通道 payload 里以
+     * `fileHandle` 字段回传，宿主校验归属/有效期/次数后替换为真实路径读盘
+     * （避免把大文件字节搬进沙箱，同时插件无法上传任意本地文件）。
+     */
+    dialog?: PluginDialog;
+    /**
+     * agentApi 2.0.0：平台 run 生命周期 + operation broker 通道。仅当
+     * manifest.agentApi 主版本 >= 2 时注入；1.x 插件为 undefined（K3 adapter
+     * 的 capability gate，见外壳 agent-api-adapters/）。`platform.credential`
+     * 是 2.1.0 的独立可选能力，并额外受 `platform:credential` 权限约束。
+     */
+    platform?: PluginPlatformApi;
+}
+/** 原生「打开文件」对话框选项（子集，映射到 Electron dialog.showOpenDialog）。 */
+interface DialogOpenFileOptions {
+    title?: string;
+    buttonLabel?: string;
+    /** 文件类型过滤，如 `[{ name: '固件', extensions: ['bin'] }]`。 */
+    filters?: {
+        name: string;
+        extensions: string[];
+    }[];
+    /** 允许多选（默认单选）。 */
+    multiSelections?: boolean;
+    /**
+     * 扩展名 allowlist（如 `[".bin"]`，大小写不敏感，可省略前导点）。
+     * 宿主在对话框选择后强制校验，不匹配则整个请求以明确错误拒绝。
+     */
+    accept?: string[];
+    /** 单文件大小上限（字节）；任一选中文件超限则整个请求以明确错误拒绝。 */
+    maxSizeBytes?: number;
+    /**
+     * 让宿主把选中文件的内容以 UTF-8 文本随结果直接回传（`contentUtf8`）。
+     * 面向"读一份小配置/模板"的场景：插件不经 handle 兑换即可拿到内容，
+     * 但仍拿不到绝对路径（W1-7 的口径不变）。
+     * 必须同时给出 `maxSizeBytes` 且不得超过 `DIALOG_READ_CONTENT_MAX_BYTES`，
+     * 否则整个请求以明确错误拒绝——内容走 IPC，尺寸必须有硬上限。
+     * 与 `readContentBase64` 互斥。
+     */
+    readContent?: boolean;
+    /**
+     * 让宿主把选中文件的**原始字节**以 Base64 随结果回传（`contentBase64`）。
+     * 面向 JPEG/PNG 等二进制：不能走 UTF-8。同样必须给 `maxSizeBytes` 且不超过硬顶。
+     * 与 `readContent` 互斥。
+     */
+    readContentBase64?: boolean;
+}
+/** `readContent: true` 时单文件内容上限（字节）。超限拒绝而不是截断。 */
+declare const DIALOG_READ_CONTENT_MAX_BYTES: number;
+/** 用户选中的单个文件（W1-7：不暴露绝对路径，只给一次性 opaque handle）。 */
+interface DialogOpenFileEntry {
+    /**
+     * 一次性 opaque handle：由宿主登记（默认 10 分钟有效、可使用 1 次）。
+     * 插件在通道 payload 的 `fileHandle` 字段回传，由宿主兑换为真实路径。
+     */
+    handle: string;
+    /** 文件名（basename，不含目录）。 */
+    name: string;
+    /** 文件大小（字节）。 */
+    sizeBytes: number;
+    /** 仅 `readContent: true` 时存在：文件内容（UTF-8 文本）。 */
+    contentUtf8?: string;
+    /** 仅 `readContentBase64: true` 时存在：文件原始字节的 Base64。 */
+    contentBase64?: string;
+}
+interface DialogOpenFileResult {
+    canceled: boolean;
+    /** 用户选择的文件（canceled 时为空数组）。 */
+    files: DialogOpenFileEntry[];
+}
+/** 原生「另存为」对话框选项（映射到 Electron dialog.showSaveDialog）。 */
+interface DialogSaveFileOptions {
+    title?: string;
+    buttonLabel?: string;
+    /** 文件类型过滤；Electron 会按选中的过滤器自动补扩展名。 */
+    filters?: {
+        name: string;
+        extensions: string[];
+    }[];
+    /** 另存为默认文件名（不含目录）。 */
+    defaultFileName?: string;
+    /**
+     * 要写入的内容（UTF-8 文本）。**由宿主代写**：插件把内容推给宿主，
+     * 宿主在用户选定的位置写文件——插件全程拿不到绝对路径（与 openFile 同一口径）。
+     * 上限 `DIALOG_SAVE_CONTENT_MAX_BYTES`，超限以明确错误拒绝。
+     */
+    contentUtf8: string;
+}
+/** saveFile 内容上限（字节）。超限拒绝而不是截断。 */
+declare const DIALOG_SAVE_CONTENT_MAX_BYTES: number;
+interface DialogSaveFileResult {
+    canceled: boolean;
+    /** 实际写入的文件名（basename；canceled 时不存在）。 */
+    name?: string;
+    /** 实际写入的字节数（canceled 时不存在）。 */
+    sizeBytes?: number;
+}
+/** 原生文件对话框能力（需 `"ui:file-dialog"` 权限）。 */
+interface PluginDialog {
+    /** 弹出「打开文件」对话框，返回一次性文件 handle（不返回绝对路径）。 */
+    openFile(options?: DialogOpenFileOptions): Promise<DialogOpenFileResult>;
+    /** 弹出「另存为」对话框并由宿主把 contentUtf8 写到用户选定的位置。 */
+    saveFile(options: DialogSaveFileOptions): Promise<DialogSaveFileResult>;
+}
+/** 插件运行时的 activate() 允许返回的内容。 */
+interface ActivatedRuntime {
+    deactivate?(): void | Promise<void>;
+}
+/** 插件运行时模块必须导出的内容。 */
+type PluginActivate = (ctx: PluginRuntimeContext) => ActivatedRuntime | void | Promise<ActivatedRuntime | void>;
+/** 由 preload 桥接层暴露在 window.stationPlugins 上的带类型 API。 */
+interface StationPluginsApi {
+    listRemote(registryUrl: string): Promise<IpcResult<RemotePlugin[]>>;
+    installPlugin(pluginId: string): Promise<IpcResult<InstalledPlugin>>;
+    updatePlugin(pluginId: string): Promise<IpcResult<InstalledPlugin>>;
+    listPluginVersions(pluginId: string): Promise<IpcResult<PluginVersionHistoryEntry[]>>;
+    rollbackPlugin(pluginId: string, version: string): Promise<IpcResult<InstalledPlugin>>;
+    cleanupPluginVersions(pluginId: string, keepLatest?: number): Promise<IpcResult<PluginVersionCleanupResult>>;
+    /** W3-4：聚合版本状态查询（版本下拉的数据入口）。 */
+    getVersionState(pluginId: string): Promise<IpcResult<PluginVersionState>>;
+    /** 下载指定远端版本；已安装插件不会因此自动切为当前运行版本。 */
+    downloadPluginVersion(pluginId: string, targetVersion: string): Promise<IpcResult<PluginVersionState>>;
+    /** renderer 完成一键就绪画面切换后的可信回执。 */
+    acknowledgeMachineReadyFocus(requestId: string): Promise<IpcResult<null>>;
+    /**
+     * W3-4：维护切换事务——目标版本必须已在本地；停止受影响 runtime、启动目标
+     * 版本并等待 readiness；成功才原子提交 selectedVersion，失败恢复原版本。
+     */
+    switchVersion(pluginId: string, targetVersion: string): Promise<IpcResult<PluginVersionState>>;
+    /** W3-4：明确维护确认——把当前运行版本记为 lastKnownGoodVersion。 */
+    confirmVersionGood(pluginId: string): Promise<IpcResult<PluginVersionState>>;
+    uninstallPlugin(pluginId: string): Promise<IpcResult<{
+        pluginId: string;
+    }>>;
+    listInstalled(): Promise<IpcResult<InstalledPlugin[]>>;
+    startRuntime(pluginId: string): Promise<IpcResult<RuntimeStatus>>;
+    allowUnofficialPluginAndStart(prompt: UnofficialPluginRunPrompt): Promise<IpcResult<RuntimeStatus>>;
+    stopRuntime(pluginId: string): Promise<IpcResult<RuntimeStatus>>;
+    /** 轴 A：将来自 UI iframe 的不透明 api-bridge 信封转发给运行时。 */
+    pluginMessage(pluginId: string, envelope: unknown): Promise<IpcResult<void>>;
+    getPluginUiUrl(pluginId: string): Promise<IpcResult<string>>;
+    getRuntimeLogs(pluginId: string): Promise<IpcResult<RuntimeLogEntry[]>>;
+    getPaths(): Promise<IpcResult<StationPaths>>;
+    /** 消费一次 Auth 请求的可信凭据配置入口；用于 renderer 重载后的可靠补投。 */
+    consumeCredentialConfigurationRequest(): Promise<IpcResult<{
+        requested: boolean;
+    }>>;
+    /** 消费待确认的插件安装请求；用于 renderer 重载后的可靠补投。 */
+    consumePluginInstallConfirmationRequest(): Promise<IpcResult<PluginInstallConfirmationRequest | null>>;
+    /** 对待确认请求作一次可信确认或拒绝；重复/未知 requestId fail-closed。 */
+    respondPluginInstallRequest(requestId: string, confirmed: boolean): Promise<IpcResult<void>>;
+    /**
+     * 开发闭环（development profile 专用，production fail-closed）：弹出目录选择框，
+     * 从本地插件目录（构建产物：manifest.json + runtime-dist (+ ui-dist)）安装为
+     * local-dev 插件。用户取消返回 null。
+     */
+    selectAndInstallLocalPlugin(): Promise<IpcResult<{
+        installed: InstalledPlugin;
+        sourceDir: string;
+    } | null>>;
+    /**
+     * 开发闭环:用本会话记录的来源目录重装该 local-dev 插件(运行中则先停后启)。
+     * 缺省先在来源目录代跑插件自己的构建(`pnpm build`,可经
+     * STATION_SHELL_LOCAL_BUILD_COMMAND 覆盖;输出进 runtime 日志),构建失败则
+     * 不重装;`options.build: false` 跳过构建(已手动构建/构建环境异常时的逃生口)。
+     */
+    reloadLocalPlugin(pluginId: string, options?: {
+        build?: boolean;
+    }): Promise<IpcResult<InstalledPlugin>>;
+    /** 订阅实时运行时事件；返回一个取消订阅的函数。 */
+    onRuntimeEvent(cb: (event: RuntimeEvent) => void): () => void;
+}
+/**
+ * 平台运行模式（W2-6，P0-04）：
+ * - `production`：正式生产。runner / Agent / 调试面板一律拒绝 Mock 通道。
+ * - `maintenance-simulated`：受保护维护入口开启；所有 run 一律 simulated。
+ * - `development`：开发 profile；所有 run 一律 simulated（不进正式 MES）。
+ */
+type PlatformRunMode = 'production' | 'maintenance-simulated' | 'development';
+/** 机器凭据状态（脱敏；绝不含 token 明文或可恢复片段）。 */
+interface PlatformCredentialStatus {
+    state: 'unconfigured' | 'configured' | 'reauth-required' | 'cipher-unavailable' | 'identity-mismatch';
+    environmentTag?: string;
+    verifiedAt?: string;
+    /** 脱敏展示：仅 '••••' + 末 4 位。 */
+    maskedToken?: string;
+}
+/** Shell 可信配置窗口中的 MES 服务选择；不会进入插件 iframe/runtime。 */
+type PlatformCredentialEndpointChoice = {
+    kind: 'default';
+} | {
+    kind: 'custom';
+    baseOrigin: string;
+};
+/** token 与服务选择必须作为一次配置事务提交并共同验证。 */
+interface PlatformCredentialConfigureInput {
+    token: string;
+    endpoint: PlatformCredentialEndpointChoice;
+}
+/** 仅供 Shell renderer 的连接配置视图；默认服务地址本身永不返回。 */
+interface PlatformCredentialConfiguration {
+    defaultAvailable: boolean;
+    activeKind: 'none' | PlatformCredentialEndpointChoice['kind'];
+    /** 当前 MES 服务 origin，仅供 Shell 可信设置/registry UI 展示。 */
+    activeBaseOrigin?: string;
+    /** 仅 activeKind=custom 时返回；插件状态投影不包含该字段。 */
+    customBaseOrigin?: string;
+}
+/** 正式结果 outbox 概览。 */
+interface PlatformOutboxStats {
+    pending: number;
+    deadLetter: number;
+    synced: number;
+    oldestPendingAt: string | null;
+}
+interface PlatformFatalRecord {
+    at: string;
+    message: string;
+}
+/** 平台健康快照（P1-3；Agent 面板 / 诊断导出的数据面）。 */
+interface PlatformHealthSnapshot {
+    at: string;
+    /** runtime 重启次数（pluginId -> 次数；含 watchdog 自动重启）。 */
+    runtimeRestarts: Record<string, number>;
+    /** 每插件最近一次 fatal（fail-stop）。 */
+    lastFatal: Record<string, PlatformFatalRecord>;
+    agentRestarts: number;
+    agentLastExit: PlatformFatalRecord | null;
+    channelTimeouts: number;
+    channelParseErrors: number;
+    serialConflicts: number;
+    outbox: PlatformOutboxStats | null;
+    diskFreeBytes: number | null;
+    activeDigests: Record<string, string>;
+    diagnosticsDropped: number;
+}
+/**
+ * 设备指纹身份（脱敏投影：只含最终指纹与来源构成布尔，绝不含任何原始
+ * 硬件序列号/机器 GUID）。指纹由 Shell 主进程启动时解析：env 覆盖优先，
+ * 否则自动派生 `v1:<sha256hex>`（OS 机器 ID + SMBIOS UUID + 首装随机 installId）。
+ */
+interface PlatformDeviceIdentity {
+    /** env 覆盖原文，或自动派生的 `v1:<sha256hex>`（67 字符）。 */
+    fingerprint: string;
+    source: 'env-override' | 'derived';
+    /** 各分量是否参与了本次派生（env-override 时全 false）。 */
+    components: {
+        osMachineId: boolean;
+        hardwareUuid: boolean;
+        installId: boolean;
+    };
+}
+/** MES 标准错误信封（{error:{code,message,requestId}}）；requestId 用于对账报障。 */
+interface MesApiError {
+    code: string;
+    message: string;
+    requestId?: string;
+}
+interface ManufacturingContextSku {
+    skuId: string;
+    skuName: string;
+    /** 其余 *Params 等字段为 JSON 字符串或标量，Shell 原样透传不解析。 */
+    [key: string]: unknown;
+}
+/** 机台制造上下文（GET /api/v1/manufacturing-context 的 data）。 */
+interface ManufacturingContext {
+    machineId: string;
+    assignmentId: string;
+    /** 工位类型编码；展示字典见 Shell @shared/manufacturingContext（未知 → `工序 #n`）。 */
+    stationType: number;
+    workOrder: {
+        workOrderId: string;
+    } | null;
+    sku: ManufacturingContextSku | null;
+}
+/** manufacturing-context 拉取结果（renderer 安全投影；不透传 token/URL）。 */
+type ManufacturingContextResult = {
+    kind: 'ok';
+    context: ManufacturingContext;
+    fetchedAt: string;
+}
+/** HTTP 409：机台无生效工位分配——禁止开测语义，UI 呈警告态。 */
+ | {
+    kind: 'no-active-assignment';
+    error: MesApiError | null;
+    fetchedAt: string;
+}
+/** 机器凭据未配置/需重新验证：先配置凭据再拉取。 */
+ | {
+    kind: 'credential-unavailable';
+    message: string;
+    fetchedAt: string;
+} | {
+    kind: 'error';
+    /** null = 网络层失败（未取得 HTTP 状态）。 */
+    httpStatus: number | null;
+    error: MesApiError | null;
+    message: string;
+    fetchedAt: string;
+};
+/**
+ * 屏幕物理校准记录（每工位/每显示器一份，落盘 display-calibration.json）。
+ * 由 Shell 校准 Mask 产出：操作员用实体直尺在 10mm 校准线档位中选最接近的一档。
+ */
+interface DisplayCalibration {
+    /** 档位百分比（50–400），同时是插件 UI 的默认根字号基准。 */
+    scalePercent: number;
+    /** 派生冗余值：CSS px / 物理 mm = (96/25.4) × scalePercent/100；主进程按 scalePercent 重算。 */
+    pxPerMm: number;
+    /** ISO 8601 保存时间。 */
+    updatedAt: string;
+}
+/**
+ * Shell → 插件 iframe 的显示缩放消息：握手应答与校准变更广播共用。
+ * 插件 SDK 的 useDisplayScale 监听该消息；与 type:'api' 的 API-Bridge 信封互不干扰。
+ */
+interface ShellDisplayScaleMessage {
+    source: 'station-shell';
+    type: 'display-scale';
+    scalePercent: number;
+}
+/** 插件 iframe → Shell 的显示缩放握手请求（SDK 挂载时发送，Shell 仅应答已注册 frame）。 */
+interface PluginUiDisplayScaleRequestMessage {
+    source: 'station-plugin-ui';
+    type: 'display-scale:request';
+}
+/**
+ * 由 preload 桥接层暴露在 window.stationPlatform 上的平台 API（第四个具名 API）。
+ * 安全边界：token 字符串只经 credentialConfigure 单向进入主进程，绝无任何
+ * 回读通道；credentialStatus 只返回脱敏状态。
+ */
+interface StationPlatformApi {
+    platformGetMode(): Promise<IpcResult<PlatformRunMode>>;
+    /**
+     * 进入/退出 maintenance-simulated（二次确认由 UI 层执行）。
+     * development profile 下拒绝（本就全 simulated，无维护开关）。
+     */
+    platformSetMaintenance(on: boolean): Promise<IpcResult<PlatformRunMode>>;
+    credentialStatus(): Promise<IpcResult<PlatformCredentialStatus>>;
+    /** 读取可信配置窗口所需的最小连接信息；不返回默认 URL。 */
+    credentialConfiguration(): Promise<IpcResult<PlatformCredentialConfiguration>>;
+    /** 配置/轮换机器凭据与服务选择。token 单向进入主进程，绝不回读。 */
+    credentialConfigure(input: PlatformCredentialConfigureInput): Promise<IpcResult<void>>;
+    outboxStats(): Promise<IpcResult<PlatformOutboxStats>>;
+    /** 人工重试 dead-letter 中的一条结果。 */
+    outboxRetry(runId: string): Promise<IpcResult<void>>;
+    /** 导出 dead-letter 中的一条结果到 <userData>/exports/，返回导出路径。 */
+    outboxExport(runId: string): Promise<IpcResult<string>>;
+    healthSnapshot(): Promise<IpcResult<PlatformHealthSnapshot>>;
+    /** 一键导出诊断包（spool + 平台审计）到 <userData>/exports/，返回 zip 路径。 */
+    diagnosticExport(): Promise<IpcResult<string>>;
+    /** 隔离调试区中的 simulated run 结果文件列表（绝不上传正式 MES）。 */
+    debugResultsList(): Promise<IpcResult<string[]>>;
+    /** 读取屏幕校准记录；null 表示未校准（视同 100%）。 */
+    displayCalibrationGet(): Promise<IpcResult<DisplayCalibration | null>>;
+    /** 保存校准档位（50–400）；pxPerMm 由主进程重算，不信任渲染进程派生值。 */
+    displayCalibrationSet(scalePercent: number): Promise<IpcResult<DisplayCalibration>>;
+    /** 读取设备指纹身份（供管理员到后台 Admin → 工位管理 → 机台 登记设备指纹）。 */
+    deviceIdentityGet(): Promise<IpcResult<PlatformDeviceIdentity>>;
+    /** 拉取机台制造上下文（机台/工序/工单/型号）；错误含 requestId 供报障对账。 */
+    manufacturingContextGet(): Promise<IpcResult<ManufacturingContextResult>>;
+    /**
+     * MES 代发请求日志（Shell 侧栏；Main 内存环形缓冲，默认不落盘）。
+     * 条目永不含 token / Authorization；插件 iframe 无此 API。
+     */
+    mesRequestLogList(): Promise<IpcResult<MesRequestLogListItemView[]>>;
+    /** 单条 MES 请求详情（按需读取；大 body 不随列表轮询传输）。 */
+    mesRequestLogGet(id: string): Promise<IpcResult<MesRequestLogDetailView | null>>;
+    /** MES path outbox 队列快照（pending + dead-letter）。 */
+    mesOutboxList(): Promise<IpcResult<MesOutboxListView>>;
+    /** 机台配对展示态（无 session_secret / token）。 */
+    pairingStatus(): Promise<IpcResult<MachinePairingStatusView>>;
+    /** 安装包预置的 MES Base URL 列表。 */
+    pairingPresets(): Promise<IpcResult<string[]>>;
+    /**
+     * Main 实际配对通道策略（与 MachinePairingOrchestrator 选项一致）。
+     * Renderer 必须用此值做 HTTPS 预检，勿自行按 profile 另推一套。
+     */
+    pairingPolicy(): Promise<IpcResult<MachinePairingChannelPolicy>>;
+    /** 开始/继续配对轮询（baseUrl 为 origin）。 */
+    pairingStart(baseUrl: string): Promise<IpcResult<MachinePairingStatusView>>;
+    pairingStop(): Promise<IpcResult<void>>;
+    /**
+     * 高级「重新配对」：清除本地凭据后进入配对。
+     * UI 须先强警告。
+     */
+    pairingStartRepair(baseUrl: string): Promise<IpcResult<MachinePairingStatusView>>;
+}
+/** Main 下发的配对通道策略（默认预置是否含 development loopback HTTP）。 */
+interface MachinePairingChannelPolicy {
+    allowInsecureLoopbackHttp: boolean;
+}
+/** Shell 可信配对页状态投影（永不含 session_secret / token）。 */
+interface MachinePairingStatusView {
+    phase: 'idle' | 'selecting_endpoint' | 'waiting_approval' | 'claiming' | 'verifying' | 'configured' | 'rejected' | 'error';
+    baseUrl: string | null;
+    pairingCode: string | null;
+    pairingCodeDisplay: string | null;
+    qrPayload: string | null;
+    codeExpiresAt: string | null;
+    claimExpiresAt: string | null;
+    rejectReason: string | null;
+    message: string | null;
+    hostname: string | null;
+    installId: string | null;
+    allowManualToken: boolean;
+}
+/** Shell 侧栏轮询的轻量 MES 请求条目；仅含列表渲染所需字段。 */
+interface MesRequestLogListItemView {
+    id: string;
+    at: string;
+    method: MesHttpMethod;
+    path: string;
+    status: number | null;
+}
+/** Shell 按需读取的 MES 请求元数据（脱敏投影；与 Main 日志摘要字段对齐）。 */
+interface MesRequestLogEntryView extends MesRequestLogListItemView {
+    pluginId: string;
+    params?: Record<string, string>;
+    durationMs: number | null;
+    delivery: 'live' | 'outbox';
+    runId?: string;
+    receiptId?: string;
+    requestBodySummary?: string | null;
+    responseBodySummary?: string | null;
+    error?: string | null;
+    phase: 'live' | 'enqueue' | 'drain' | 'reject';
+}
+/** MES 请求详情（点击列表项后按需获取；仍为脱敏投影，不含 token / Authorization）。 */
+interface MesRequestLogDetailView extends MesRequestLogEntryView {
+    requestBodyText?: string | null;
+    responseBodyText?: string | null;
+    requestBodyTruncated?: boolean;
+    responseBodyTruncated?: boolean;
+}
+/** Shell 侧栏可见的 MES outbox 单条记录（不含 Authorization）。 */
+interface MesOutboxRecordView {
+    receiptId: string;
+    pluginId: string;
+    runId: string;
+    method: MesHttpMethod;
+    path: string;
+    params?: Record<string, string>;
+    status: 'pending' | 'dead-letter' | 'done';
+    attempts: number;
+    maxAttempts: number;
+    nextAttemptAt: string | null;
+    lastError: string | null;
+    lastHttpStatus: number | null;
+    enqueuedAt: string;
+    updatedAt: string;
+    pausedForReauth?: boolean;
+}
+interface MesOutboxListView {
+    pending: MesOutboxRecordView[];
+    deadLetter: MesOutboxRecordView[];
+}
+
+export { type ActivatedRuntime, CURRENT_METER_LOGICAL, type ChannelMetrics, type ChannelState, type ChannelStatus, type ChooseFixtureDutOptions, DIALOG_READ_CONTENT_MAX_BYTES, DIALOG_SAVE_CONTENT_MAX_BYTES, DUT_LOGICAL, type DeviceChannelConfig, type DialogOpenFileEntry, type DialogOpenFileOptions, type DialogOpenFileResult, type DialogSaveFileOptions, type DialogSaveFileResult, type DisplayCalibration, FIXTURE_BAUD_RATE, FIXTURE_BOARD_ADDRESS, FIXTURE_LOGICAL, type FixtureDutPair, type FixturePortPairSelection, type FixturePortSelection, type InstalledPlugin, type IpcResult, type JsonLinesCodecConfig, KNOWN_T9W_DUT_ENDPOINT, KNOWN_T9W_FIXTURE_ENDPOINT, type MachinePairingChannelPolicy, type MachinePairingStatusView, type ManufacturingContext, type ManufacturingContextResult, type ManufacturingContextSku, type MesApiError, type MesHttpMethod, type MesLiveResult, type MesOutboxListView, type MesOutboxRecordView, type MesParamValue, type MesQueuedResult, type MesRequestLogDetailView, type MesRequestLogEntryView, type MesRequestLogListItemView, type MesRequestOptions, type MesResult, type MockChannelConfig, type ModbusRtuCodecConfig, type MqttChannelConfig, type NativeScanResult, type OperatorSignals, type OssChannelConfig, type PlatformBeginRunOptions, type PlatformCredentialConfiguration, type PlatformCredentialConfigureInput, type PlatformCredentialEndpointChoice, type PlatformCredentialStatus, type PlatformDeviceIdentity, type PlatformDurableReceipt, type PlatformFatalRecord, type PlatformHealthSnapshot, type PlatformLogEntry, type PlatformLogEntryInput, type PlatformLogLevel, type PlatformLogQuery, type PlatformLogQueryResult, type PlatformLogStats, type PlatformLogWriteAck, type PlatformOutboxStats, type PlatformRunMode, type PlatformRunResultMode, type PlatformRunStep, type PlatformRunSubject, type PlatformRunTargetOptions, type PluginActivate, type PluginCredentialStatus, type PluginDialog, type PluginInstallConfirmationPackage, type PluginInstallConfirmationRequest, type PluginInstallPackageRequest, type PluginInstallProgress, type PluginInstallProgressStatus, type PluginInstallRequestInput, type PluginInstallRequestResult, type PluginKind, type PluginLogger, type PluginManifest, type PluginPlatformApi, type PluginPlatformCredential, type PluginPlatformHttp, type PluginPlatformInstall, type PluginPlatformLog, type PluginPlatformMes, type PluginPlatformRf, type PluginPlatformRfSecureMaterialAuthResponse, type PluginPlatformRfSecureMaterialPreflightRequest, type PluginPlatformRfSecureMaterialRequest, type PluginPlatformRfSecureMaterialResponse, type PluginPlatformRfSecureMaterialStringResponse, type PluginPlatformRfSecureMaterialTripleResponse, type PluginPlatformRfStationAssetSnapshot, type PluginPlatformScanner, type PluginPlatformUpload, type PluginPlatformVirtualSerial, type PluginRegistryDocument, type PluginRuntimeContext, type PluginServiceBus, type PluginSignatureState, type PluginStepDef, type PluginStorage, type PluginStorageDeclaration, type PluginStorageScope, type PluginUiDisplayScaleRequestMessage, type PluginUiTransport, type PluginUploadFailureCode, type PluginUploadOutcome, type PluginUploadRequest, type PluginUploadSource, type PluginUploadedObject, type PluginVersionCleanupResult, type PluginVersionHistoryEntry, type PluginVersionOption, type PluginVersionState, type RawTextCodecConfig, type RegistryPublisherKey, type RegistrySnapshot, type RemotePlugin, type RemotePluginVersionOption, type RuntimeEvent, type RuntimeLogEntry, type RuntimeState, type RuntimeStatus, type ScannerCameraInfo, type ScannerCandidate, type ScannerErrorCode, type ScannerHealth, type ScannerRoi, type ScannerScanRequest, type ScannerSeatResult, type ScpiTextCodecConfig, type SerialChannelConfig, type SerialCodecConfig, type SerialDeviceSuggestion, type SerialPortCapability, type SerialPortInfo, type SerialPortRole, type SerialProbeAttempt, type SerialProbeKind, type SerialUsageSnapshot, type SerialUsageState, type SerialUsageUser, type ShellDisplayScaleMessage, type StationPaths, type StationPlatformApi, type StationPluginsApi, type StepEvent, type StepResult, T9W_DUT_BAUD_RATE, type TcpChannelConfig, type UnofficialPluginRunPrompt, type VirtualSerialPairInfo, allSerialPortPaths, asChannelStatus, asResponseObject, asSerialDeviceSuggestions, asSerialPorts, buildDutRawTextSerialConfig, buildFixtureSerialConfig, chooseFixtureAndDutPortPairs, chooseFixtureAndDutPorts, isFixtureReadyEvent, looksLikeUsbSerialPort, parseOperatorSignals, preferredSerialPathFromPort, preferredSerialPortPath, serialEndpointId, serialPortHasEndpoint };