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

package/README.md

@@ -0,0 +1,4 @@
+# @international-iot-association/plugin-contracts
+
+Station-shell 与插件之间协议的唯一真源（types-only，零运行时依赖）。
+属于**组 A · 协议锁步组**（与 `plugin-sdk`/`api-bridge`/`rct-state` 一起随 `agentApi` major 锁步发布）。

package/dist/index.cjs

@@ -0,0 +1,421 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CURRENT_METER_LOGICAL: () => CURRENT_METER_LOGICAL,
+  DIALOG_READ_CONTENT_MAX_BYTES: () => DIALOG_READ_CONTENT_MAX_BYTES,
+  DIALOG_SAVE_CONTENT_MAX_BYTES: () => DIALOG_SAVE_CONTENT_MAX_BYTES,
+  DUT_LOGICAL: () => DUT_LOGICAL,
+  FIXTURE_BAUD_RATE: () => FIXTURE_BAUD_RATE,
+  FIXTURE_BOARD_ADDRESS: () => FIXTURE_BOARD_ADDRESS,
+  FIXTURE_LOGICAL: () => FIXTURE_LOGICAL,
+  KNOWN_T9W_DUT_ENDPOINT: () => KNOWN_T9W_DUT_ENDPOINT,
+  KNOWN_T9W_FIXTURE_ENDPOINT: () => KNOWN_T9W_FIXTURE_ENDPOINT,
+  T9W_DUT_BAUD_RATE: () => T9W_DUT_BAUD_RATE,
+  allSerialPortPaths: () => allSerialPortPaths,
+  asChannelStatus: () => asChannelStatus,
+  asResponseObject: () => asResponseObject,
+  asSerialDeviceSuggestions: () => asSerialDeviceSuggestions,
+  asSerialPorts: () => asSerialPorts,
+  buildDutRawTextSerialConfig: () => buildDutRawTextSerialConfig,
+  buildFixtureSerialConfig: () => buildFixtureSerialConfig,
+  chooseFixtureAndDutPortPairs: () => chooseFixtureAndDutPortPairs,
+  chooseFixtureAndDutPorts: () => chooseFixtureAndDutPorts,
+  isFixtureReadyEvent: () => isFixtureReadyEvent,
+  looksLikeUsbSerialPort: () => looksLikeUsbSerialPort,
+  parseOperatorSignals: () => parseOperatorSignals,
+  preferredSerialPathFromPort: () => preferredSerialPathFromPort,
+  preferredSerialPortPath: () => preferredSerialPortPath,
+  serialEndpointId: () => serialEndpointId,
+  serialPortHasEndpoint: () => serialPortHasEndpoint
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/fixtureControl.ts
+var FIXTURE_LOGICAL = "serial.fixture";
+var DUT_LOGICAL = "serial.dut";
+var CURRENT_METER_LOGICAL = "instrument.current-meter";
+var FIXTURE_BOARD_ADDRESS = 250;
+var FIXTURE_BAUD_RATE = 115200;
+var T9W_DUT_BAUD_RATE = 460800;
+var KNOWN_T9W_FIXTURE_ENDPOINT = "58b20024743";
+var KNOWN_T9W_DUT_ENDPOINT = "58b20024741";
+function isFixtureReadyEvent(event) {
+  return event.fixtureReady === true || event.ok === true && event.functionCode === 6 && event.register === 201 && event.value === 1;
+}
+function preferredSerialPortPath(path) {
+  if (path.includes("/dev/tty.")) return path.replace("/dev/tty.", "/dev/cu.");
+  return path;
+}
+function allSerialPortPaths(port) {
+  return [port.path, ...port.aliases ?? []];
+}
+function serialEndpointId(path) {
+  const name = path.split("/").pop()?.toLowerCase() ?? "";
+  return name.match(/(?:wchusbserial|usbserial|usbmodem)([a-z0-9]+)$/)?.[1] ?? null;
+}
+function serialPortHasEndpoint(port, endpoint) {
+  return allSerialPortPaths(port).some(
+    (path) => serialEndpointId(path) === endpoint.toLowerCase()
+  );
+}
+function preferredSerialPathFromPort(port) {
+  return allSerialPortPaths(port).sort((a, b) => serialPathPreference(b) - serialPathPreference(a))[0] ?? port.path;
+}
+function looksLikeUsbSerialPort(port) {
+  const pathBlob = [port.path, ...port.aliases ?? []].filter(Boolean).join(" ").toLowerCase();
+  if (/(?:^|[\s\\/])com\d+\b/i.test(pathBlob) || /^com\d+$/i.test(port.path.trim())) {
+    return true;
+  }
+  const text = [
+    pathBlob,
+    port.manufacturer,
+    port.friendlyName,
+    port.serialNumber,
+    port.vendorId,
+    port.productId,
+    port.pnpId,
+    port.locationId
+  ].filter(Boolean).join(" ").toLowerCase().replace(/[\s_\-]+/g, "");
+  if (text.includes("wch") || text.includes("usbserial") || text.includes("usbmodem") || text.includes("ch340") || text.includes("ch341") || text.includes("ch910") || text.includes("cp210") || text.includes("ftdi") || text.includes("ft232") || text.includes("pl2303")) {
+    return true;
+  }
+  const vid = (port.vendorId ?? "").toLowerCase().replace(/^0x/, "");
+  if (vid === "1a86" || vid === "10c4" || vid === "0403" || vid === "067b") {
+    return true;
+  }
+  if (text.includes("vid_1a86") || text.includes("vid_10c4") || text.includes("vid_0403") || text.includes("vid_067b")) {
+    return true;
+  }
+  return false;
+}
+function chooseFixtureAndDutPorts(ports, suggestions = [], options = {}) {
+  const { pairs, reasons } = chooseFixtureAndDutPortPairs(ports, suggestions, {
+    ...options,
+    count: 1
+  });
+  const first = pairs[0];
+  if (first) return { fixture: first.fixture, dut: first.dut, reasons };
+  return { reasons };
+}
+function chooseFixtureAndDutPortPairs(ports, suggestions = [], options = {}) {
+  const count = Math.max(1, Math.floor(options.count ?? 1));
+  const allowKnown = options.allowKnownEndpointFallback !== false;
+  const reasons = [];
+  const pairs = [];
+  const used = /* @__PURE__ */ new Set();
+  for (const path of options.excludePaths ?? []) markPathsUsed(used, path);
+  const suggestedPorts = suggestions.filter(
+    (item) => item.kind === "fixture-modbus" || item.role === "fixture" || item.role === "dut"
+  ).map((item) => item.port);
+  const candidates = mergePortLists(
+    ports.filter(looksLikeUsbSerialPort),
+    suggestedPorts.filter((port) => ports.some((p) => samePhysicalPort(p, port)))
+  );
+  const available = () => candidates.filter((port) => !isPortUsed(used, port));
+  const availableAll = () => ports.filter((port) => !isPortUsed(used, port));
+  const protocolFixtures = suggestions.filter((item) => item.kind === "fixture-modbus").sort((a, b) => b.confidence - a.confidence);
+  for (const detected of protocolFixtures) {
+    if (pairs.length >= count) break;
+    const fixture = findPortInList(available(), detected.port) ?? findPortInList(availableAll(), detected.port);
+    if (!fixture) {
+      reasons.push(
+        `\u534F\u8BAE\u547D\u4E2D\u5939\u5177 ${detected.port.path}\uFF08\u7F6E\u4FE1\u5EA6 ${detected.confidence}%\uFF09\uFF0C\u4F46 listPorts \u4E2D\u65E0\u5BF9\u5E94\u7269\u7406\u53E3\uFF08\u53EF\u80FD\u5DF2\u62D4\u51FA\u6216\u8DEF\u5F84\u4E0D\u4E00\u81F4\uFF09`
+      );
+      continue;
+    }
+    const pool = mergePortLists(available(), availableAll());
+    const pairedDutPath = detected.pairedWith;
+    const pairedDut = pairedDutPath ? pool.find(
+      (port) => allSerialPortPaths(port).some(
+        (p) => p.toLowerCase() === pairedDutPath.toLowerCase()
+      )
+    ) : void 0;
+    const roleDut = suggestions.filter((item) => item.role === "dut" && !isPortUsed(used, item.port)).sort((a, b) => b.confidence - a.confidence).map((item) => findPortInList(pool, item.port)).find((port) => Boolean(port));
+    const dut = pairedDut ?? roleDut ?? chooseDutForFixture(fixture, pool) ?? pickSoleOtherPort(fixture, pool);
+    if (!dut) {
+      reasons.push(
+        `\u534F\u8BAE\u786E\u8BA4\u5939\u5177 ${preferredSerialPathFromPort(fixture)}\uFF08\u7F6E\u4FE1\u5EA6 ${detected.confidence}%\uFF09\uFF0C\u4F46\u672A\u627E\u5230\u53EF\u7528 DUT \u8F6C\u53D1\u53E3`
+      );
+      continue;
+    }
+    pairs.push({ fixture, dut });
+    markPortUsed(used, fixture);
+    markPortUsed(used, dut);
+    reasons.push(
+      `Agent \u81EA\u52A8\u63A2\u6D4B\u8BC6\u522B\u5939\u5177\u63A7\u5236\u677F\uFF1A${fixture.path}\uFF0C\u7F6E\u4FE1\u5EA6 ${detected.confidence}%\uFF080xFA \u534F\u8BAE\u63E1\u624B\u6210\u529F\uFF0C\u4E0D\u533A\u5206\u4EA7\u54C1\u578B\u53F7\uFF09`
+    );
+    reasons.push(
+      pairedDut || roleDut ? `\u6839\u636E Agent \u89D2\u8272/\u914D\u5BF9\u5EFA\u8BAE\u9009\u62E9 DUT \u8F6C\u53D1\u7AEF\u53E3\uFF08${preferredSerialPathFromPort(dut)}\uFF09` : `\u6839\u636E Agent \u5939\u5177\u63A2\u6D4B\u7ED3\u679C\u548C\u540C\u65CF USB \u4E32\u53E3\u63A8\u65AD DUT \u8F6C\u53D1\u7AEF\u53E3\uFF08${preferredSerialPathFromPort(dut)}\uFF09`
+    );
+  }
+  if (pairs.length < count && allowKnown) {
+    const fixtureEndpoint = options.fixtureEndpoint === null ? null : options.fixtureEndpoint ?? KNOWN_T9W_FIXTURE_ENDPOINT;
+    const dutEndpoint = options.dutEndpoint === null ? null : options.dutEndpoint ?? KNOWN_T9W_DUT_ENDPOINT;
+    if (fixtureEndpoint) {
+      const fixtureKnown = available().find(
+        (port) => serialPortHasEndpoint(port, fixtureEndpoint)
+      );
+      if (fixtureKnown) {
+        const dutKnown = dutEndpoint ? available().find((port) => serialPortHasEndpoint(port, dutEndpoint)) : void 0;
+        const dut = dutKnown ?? chooseDutForFixture(fixtureKnown, available());
+        if (dut && pairs.length < count) {
+          pairs.push({ fixture: fixtureKnown, dut });
+          markPortUsed(used, fixtureKnown);
+          markPortUsed(used, dut);
+          reasons.push(
+            `\u7AEF\u70B9\u515C\u5E95\uFF1A\u5939\u5177 ${fixtureEndpoint} \u2192 ${preferredSerialPathFromPort(fixtureKnown)}\uFF08\u534F\u8BAE\u63A2\u6D4B\u672A\u8986\u76D6\u65F6\u7684\u5B9E\u9A8C\u5BA4\u7EBF\u5E8F\uFF09`
+          );
+          reasons.push(
+            dutKnown ? `\u7AEF\u70B9\u515C\u5E95\uFF1ADUT ${dutEndpoint} \u2192 ${preferredSerialPathFromPort(dut)}` : `\u7AEF\u70B9\u515C\u5E95\uFF1ADUT \u540C\u65CF\u63A8\u65AD \u2192 ${preferredSerialPathFromPort(dut)}`
+          );
+        } else if (!dut) {
+          reasons.push(
+            `\u7AEF\u70B9\u515C\u5E95\u627E\u5230\u5939\u5177\u7AEF\u70B9 ${fixtureEndpoint}\uFF0C\u4F46\u65E0\u53EF\u7528 DUT \u8F6C\u53D1\u53E3`
+          );
+        }
+      }
+    }
+  }
+  if (pairs.length === 0) {
+    reasons.push(
+      "\u672A\u627E\u5230\u53EF\u53EF\u9760\u5F52\u7C7B\u7684\u5939\u5177\u53CC\u4E32\u53E3\u5019\u9009\uFF1A\u5939\u5177\u63A7\u5236\u677F\u5FC5\u987B\u901A\u8FC7\u5DF2\u77E5\u7AEF\u70B9\u6216 Modbus \u63A2\u6D4B\u786E\u8BA4\uFF08detectDevices \u2192 fixture-modbus / 0xFA \u534F\u8BAE\u63E1\u624B\uFF09\u3002\u8BF7\u786E\u8BA4 USB \u5DF2\u8FDE\u63A5\u4E14\u672A\u88AB\u5176\u5B83\u8FDB\u7A0B\u5360\u7528\u3002"
+    );
+  } else if (pairs.length < count) {
+    reasons.push(
+      `\u4EC5\u5206\u914D\u5230 ${pairs.length}/${count} \u5BF9\u5939\u5177+DUT\uFF1B\u591A\u5E2D\u4F4D\u8BF7\u63A5\u5165\u5BF9\u5E94\u6570\u91CF\u7684\u63A7\u5236\u677F/\u8F6C\u53D1\u53E3`
+    );
+  }
+  return { pairs, reasons };
+}
+function findPortInList(ports, target) {
+  return ports.find((port) => samePhysicalPort(port, target));
+}
+function pathKeys(path) {
+  const preferred = preferredSerialPortPath(path).toLowerCase();
+  const raw = path.toLowerCase();
+  return preferred === raw ? [raw] : [preferred, raw];
+}
+function markPathsUsed(used, path) {
+  for (const key of pathKeys(path)) used.add(key);
+}
+function markPortUsed(used, port) {
+  for (const path of allSerialPortPaths(port)) markPathsUsed(used, path);
+}
+function isPortUsed(used, port) {
+  return allSerialPortPaths(port).some(
+    (path) => pathKeys(path).some((key) => used.has(key))
+  );
+}
+function buildFixtureSerialConfig(port, options = {}) {
+  return {
+    logicalName: options.logicalName ?? FIXTURE_LOGICAL,
+    provider: "serial",
+    ...port ? { port: preferredSerialPortPath(preferredSerialPathFromPort(port)) } : {},
+    baudRate: FIXTURE_BAUD_RATE,
+    dataBits: 8,
+    stopBits: 1,
+    parity: "none",
+    codec: {
+      type: "modbus-rtu",
+      deviceAddress: options.boardAddress ?? FIXTURE_BOARD_ADDRESS,
+      maxFrameBytes: 256
+    },
+    timeouts: { openMs: 3e3, responseMs: 2e3, idleFrameMs: 50 },
+    signals: { dtr: false, rts: false },
+    openStabilizeMs: 200
+  };
+}
+function buildDutRawTextSerialConfig(port, options = {}) {
+  return {
+    logicalName: options.logicalName ?? DUT_LOGICAL,
+    provider: "serial",
+    ...port ? { port: preferredSerialPortPath(preferredSerialPathFromPort(port)) } : {},
+    baudRate: options.baudRate ?? T9W_DUT_BAUD_RATE,
+    dataBits: 8,
+    stopBits: 1,
+    parity: "none",
+    codec: {
+      type: "raw-text",
+      delimiter: "\r\n",
+      maxFrameBytes: 8192,
+      encoding: "utf8",
+      appendDelimiter: true
+    },
+    timeouts: { openMs: 3e3, responseMs: 1600, idleFrameMs: 80 },
+    signals: { dtr: false, rts: false },
+    openStabilizeMs: 300
+  };
+}
+function parseOperatorSignals(text) {
+  const normalized = normalizeText(text);
+  const keys = /* @__PURE__ */ new Set();
+  for (const match of normalized.matchAll(/\bkey[_-]?([0-9A-Za-z]+)\s+pressed\b/gi)) {
+    if (match[1]) keys.add(match[1]);
+  }
+  for (const match of normalized.matchAll(/\bkey\s*[=:]\s*([0-9A-Za-z]+)\b/gi)) {
+    if (match[1]) keys.add(match[1]);
+  }
+  for (const match of normalized.matchAll(/\bkey_press_map\s*[=:]\s*(0x[0-9a-f]+|\d+)/gi)) {
+    const map = parseIntegerToken(match[1]);
+    if (map == null || map === 0) continue;
+    for (let bit = 0; bit < 32; bit += 1) {
+      if (Math.trunc(map / 2 ** bit) % 2 === 1) keys.add(String(bit + 1));
+    }
+  }
+  const lower = normalized.toLowerCase();
+  const encoderForward = lower.includes("rotate direction is clockwise") || /\b(?:encoder|knob)[_-]?(?:forward|cw|clockwise)\s*[=:]\s*(?:1|true|yes|seen)\b/i.test(
+    normalized
+  ) || /\b(?:encoder|knob)[\s_-]*(?:direction|dir)\s*[=:]\s*(?:clockwise|cw|forward|right)\b/i.test(
+    normalized
+  );
+  const encoderReverse = lower.includes("rotate direction is anti-clockwise") || lower.includes("rotate direction is anticlockwise") || lower.includes("rotate direction is counterclockwise") || /\b(?:ccw|anti-clockwise|anticlockwise|counterclockwise)\b/i.test(normalized) || /\b(?:encoder|knob)[_-]?(?:reverse|ccw|anticlockwise|counterclockwise)\s*[=:]\s*(?:1|true|yes|seen)\b/i.test(
+    normalized
+  ) || /\b(?:encoder|knob)[\s_-]*(?:direction|dir)\s*[=:]\s*(?:anti-clockwise|anticlockwise|counterclockwise|ccw|reverse|left)\b/i.test(
+    normalized
+  );
+  return {
+    keys: [...keys],
+    encoderForward,
+    encoderReverse
+  };
+}
+function serialPathPreference(path) {
+  const p = path.toLowerCase();
+  let score = 0;
+  if (p.includes("/dev/cu.")) score += 20;
+  if (p.includes("wchusbserial")) score += 12;
+  if (p.includes("usbserial")) score += 8;
+  if (p.includes("usbmodem")) score += 2;
+  return score;
+}
+function normalizeText(value) {
+  return value.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+function parseIntegerToken(value) {
+  if (!value) return void 0;
+  const trimmed = value.trim();
+  const parsed = trimmed.toLowerCase().startsWith("0x") ? Number.parseInt(trimmed.slice(2), 16) : Number.parseInt(trimmed, 10);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function sameUsbFamily(a, b) {
+  return Boolean(
+    a.vendorId && b.vendorId && a.productId && b.productId && a.vendorId.toLowerCase() === b.vendorId.toLowerCase() && a.productId.toLowerCase() === b.productId.toLowerCase()
+  );
+}
+function endpointKey(port) {
+  for (const path of allSerialPortPaths(port)) {
+    const id = serialEndpointId(path);
+    if (id) return id;
+  }
+  return null;
+}
+function samePhysicalPort(a, b) {
+  const aPaths = new Set(allSerialPortPaths(a).map((path) => path.toLowerCase()));
+  return allSerialPortPaths(b).some((path) => aPaths.has(path.toLowerCase()));
+}
+function chooseDutForFixture(fixture, candidates) {
+  const fixtureEndpoint = endpointKey(fixture);
+  if (fixtureEndpoint) {
+    const sibling = candidates.find((port) => {
+      if (samePhysicalPort(port, fixture)) return false;
+      const endpoint = endpointKey(port);
+      return endpoint && endpoint !== fixtureEndpoint && sameUsbFamily(fixture, port);
+    });
+    if (sibling) return sibling;
+  }
+  const sameFamily = candidates.find(
+    (port) => !samePhysicalPort(port, fixture) && sameUsbFamily(fixture, port)
+  );
+  if (sameFamily) return sameFamily;
+  const sn = (fixture.serialNumber ?? "").trim().toLowerCase();
+  if (sn.length >= 4) {
+    const bySerial = candidates.find((port) => {
+      if (samePhysicalPort(port, fixture)) return false;
+      const other = (port.serialNumber ?? "").trim().toLowerCase();
+      return other.length >= 4 && (other === sn || other.startsWith(sn) || sn.startsWith(other));
+    });
+    if (bySerial) return bySerial;
+  }
+  return void 0;
+}
+function pickSoleOtherPort(fixture, candidates) {
+  const others = candidates.filter((port) => !samePhysicalPort(port, fixture));
+  return others.length === 1 ? others[0] : void 0;
+}
+function mergePortLists(...lists) {
+  const out = [];
+  for (const list of lists) {
+    for (const port of list) {
+      if (!out.some((existing) => samePhysicalPort(existing, port))) {
+        out.push(port);
+      }
+    }
+  }
+  return out;
+}
+
+// src/runtimeValues.ts
+function asSerialPorts(value) {
+  return Array.isArray(value) ? value : [];
+}
+function asSerialDeviceSuggestions(value) {
+  return Array.isArray(value) ? value : [];
+}
+function asChannelStatus(value) {
+  return value;
+}
+function asResponseObject(value) {
+  return value && typeof value === "object" ? value : {};
+}
+
+// src/index.ts
+var DIALOG_READ_CONTENT_MAX_BYTES = 4 * 1024 * 1024;
+var DIALOG_SAVE_CONTENT_MAX_BYTES = 8 * 1024 * 1024;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CURRENT_METER_LOGICAL,
+  DIALOG_READ_CONTENT_MAX_BYTES,
+  DIALOG_SAVE_CONTENT_MAX_BYTES,
+  DUT_LOGICAL,
+  FIXTURE_BAUD_RATE,
+  FIXTURE_BOARD_ADDRESS,
+  FIXTURE_LOGICAL,
+  KNOWN_T9W_DUT_ENDPOINT,
+  KNOWN_T9W_FIXTURE_ENDPOINT,
+  T9W_DUT_BAUD_RATE,
+  allSerialPortPaths,
+  asChannelStatus,
+  asResponseObject,
+  asSerialDeviceSuggestions,
+  asSerialPorts,
+  buildDutRawTextSerialConfig,
+  buildFixtureSerialConfig,
+  chooseFixtureAndDutPortPairs,
+  chooseFixtureAndDutPorts,
+  isFixtureReadyEvent,
+  looksLikeUsbSerialPort,
+  parseOperatorSignals,
+  preferredSerialPathFromPort,
+  preferredSerialPortPath,
+  serialEndpointId,
+  serialPortHasEndpoint
+});