@zqagent/shared 0.0.0-stage → 0.1.0

package/dist/media.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 音视频判定与 HTTP Range 解析（节点 / 控制台 / 网关共用同一套规则）
+ *
+ * 只收录浏览器原生 `<audio>` / `<video>` 能直接播放的容器。mkv / avi / wmv / flv
+ * 等需要转码的格式返回 null，由上层提示「下载后查看」而不是给一个永远播不了的
+ * 播放器（错误提示会更难解释）。
+ *
+ * Range 解析按 RFC 7233：只接受单段（多段请求直接忽略，回整个文件），
+ * 语法不合法回 null（调用方忽略 Range），语法合法但区间落在文件外回
+ * "unsatisfiable"（调用方回 416）。
+ */
+type MediaKind = "audio" | "video";
+interface MediaInfo {
+    /** 响应用 Content-Type */
+    mime: string;
+    kind: MediaKind;
+}
+/** 文件名 → 可播放媒体的 MIME 与类别；不可（或浏览器不支持）返回 null */
+declare function mediaInfo(fileName: string): MediaInfo | null;
+/** 文件名 → MIME；非可播放媒体返回 null */
+declare function mediaMime(fileName: string): string | null;
+/** 文件名 → audio / video；非可播放媒体返回 null */
+declare function mediaKind(fileName: string): MediaKind | null;
+/** 文件名 → 可内嵌预览的文档 MIME；非文档返回 null */
+declare function docPreviewMime(fileName: string): string | null;
+/**
+ * 文件名 → 可用于 **HTTP Range 流式预览**的 MIME（音视频 + 可内嵌文档）。
+ *
+ * 节点签发文件票据 / `/files/range` 用它决定 `Content-Type`：票据里没有 MIME 时
+ * 前端会直接放弃流式通道，退回整文件下载（大 PDF 尤其痛），所以 PDF 必须在这里
+ * 被认出来。
+ */
+declare function previewMime(fileName: string): string | null;
+interface ByteRange {
+    /** 起始偏移（含） */
+    start: number;
+    /** 结束偏移（含） */
+    end: number;
+}
+/**
+ * 解析 `Range: bytes=...`。
+ *
+ * @param header 原始头值（可为 null / 空）
+ * @param size   文件总字节数
+ * @returns 单段区间；`null` = 忽略该头（无 Range / 多段 / 语法不合法）；
+ *          `"unsatisfiable"` = 范围越界，调用方应回 416。
+ */
+declare function parseByteRange(header: string | null | undefined, size: number): ByteRange | "unsatisfiable" | null;
+/** Range 响应的 `Content-Range` 头值 */
+declare function contentRangeHeader(range: ByteRange, size: number): string;
+/**
+ * 文件 ETag（强校验）。
+ *
+ * 由 size + mtime 组成：文件内容变化几乎必然改变其中一个；不读文件本身，
+ * 因此 `HEAD` / `304` 可以在完全不触达节点的情况下应答。
+ */
+declare function fileEtag(size: number, mtimeMs: number): string;
+
+export { type ByteRange, type MediaInfo, type MediaKind, contentRangeHeader, docPreviewMime, fileEtag, mediaInfo, mediaKind, mediaMime, parseByteRange, previewMime };

package/dist/media.js

@@ -0,0 +1,79 @@
+// src/media.ts
+var MEDIA_MIME = {
+  // 视频
+  mp4: { mime: "video/mp4", kind: "video" },
+  m4v: { mime: "video/mp4", kind: "video" },
+  webm: { mime: "video/webm", kind: "video" },
+  ogv: { mime: "video/ogg", kind: "video" },
+  mov: { mime: "video/quicktime", kind: "video" },
+  // 音频
+  mp3: { mime: "audio/mpeg", kind: "audio" },
+  wav: { mime: "audio/wav", kind: "audio" },
+  m4a: { mime: "audio/mp4", kind: "audio" },
+  aac: { mime: "audio/aac", kind: "audio" },
+  flac: { mime: "audio/flac", kind: "audio" },
+  ogg: { mime: "audio/ogg", kind: "audio" },
+  oga: { mime: "audio/ogg", kind: "audio" },
+  opus: { mime: "audio/ogg", kind: "audio" },
+  weba: { mime: "audio/webm", kind: "audio" }
+};
+function extOf(fileName) {
+  return fileName.toLowerCase().split(".").pop() ?? "";
+}
+function mediaInfo(fileName) {
+  return MEDIA_MIME[extOf(fileName)] ?? null;
+}
+function mediaMime(fileName) {
+  return MEDIA_MIME[extOf(fileName)]?.mime ?? null;
+}
+function mediaKind(fileName) {
+  return MEDIA_MIME[extOf(fileName)]?.kind ?? null;
+}
+var DOC_PREVIEW_MIME = {
+  pdf: "application/pdf"
+};
+function docPreviewMime(fileName) {
+  return DOC_PREVIEW_MIME[extOf(fileName)] ?? null;
+}
+function previewMime(fileName) {
+  return mediaMime(fileName) ?? docPreviewMime(fileName);
+}
+function parseByteRange(header, size) {
+  const raw = (header ?? "").trim();
+  if (!raw) return null;
+  const m = /^bytes=(\d*)-(\d*)$/i.exec(raw);
+  if (!m) return null;
+  const startRaw = m[1] ?? "";
+  const endRaw = m[2] ?? "";
+  if (!startRaw && !endRaw) return null;
+  if (size <= 0) return "unsatisfiable";
+  if (!startRaw) {
+    const suffix = Number(endRaw);
+    if (!Number.isFinite(suffix) || suffix <= 0) return "unsatisfiable";
+    return { start: Math.max(size - suffix, 0), end: size - 1 };
+  }
+  const start = Number(startRaw);
+  if (!Number.isFinite(start) || start < 0) return null;
+  if (start >= size) return "unsatisfiable";
+  if (!endRaw) return { start, end: size - 1 };
+  const end = Number(endRaw);
+  if (!Number.isFinite(end) || end < start) return null;
+  return { start, end: Math.min(end, size - 1) };
+}
+function contentRangeHeader(range, size) {
+  return `bytes ${range.start}-${range.end}/${size}`;
+}
+function fileEtag(size, mtimeMs) {
+  return `"${size.toString(16)}-${Math.trunc(mtimeMs).toString(16)}"`;
+}
+export {
+  contentRangeHeader,
+  docPreviewMime,
+  fileEtag,
+  mediaInfo,
+  mediaKind,
+  mediaMime,
+  parseByteRange,
+  previewMime
+};
+//# sourceMappingURL=media.js.map

package/dist/media.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/media.ts"],"sourcesContent":["/**\n * 音视频判定与 HTTP Range 解析（节点 / 控制台 / 网关共用同一套规则）\n *\n * 只收录浏览器原生 `<audio>` / `<video>` 能直接播放的容器。mkv / avi / wmv / flv\n * 等需要转码的格式返回 null，由上层提示「下载后查看」而不是给一个永远播不了的\n * 播放器（错误提示会更难解释）。\n *\n * Range 解析按 RFC 7233：只接受单段（多段请求直接忽略，回整个文件），\n * 语法不合法回 null（调用方忽略 Range），语法合法但区间落在文件外回\n * \"unsatisfiable\"（调用方回 416）。\n */\n\nexport type MediaKind = \"audio\" | \"video\";\n\nexport interface MediaInfo {\n  /** 响应用 Content-Type */\n  mime: string;\n  kind: MediaKind;\n}\n\n/**\n * 扩展名 → MIME / 类别。\n *\n * `mov` 只有 Safari 稳定支持；`webm` 在旧 Safari 上不支持。是否真能播由浏览器\n * 决定，前端监听 `<video onError>` 兜底，不在这里做设备探测。\n */\nconst MEDIA_MIME: Record<string, MediaInfo> = {\n  // 视频\n  mp4: { mime: \"video/mp4\", kind: \"video\" },\n  m4v: { mime: \"video/mp4\", kind: \"video\" },\n  webm: { mime: \"video/webm\", kind: \"video\" },\n  ogv: { mime: \"video/ogg\", kind: \"video\" },\n  mov: { mime: \"video/quicktime\", kind: \"video\" },\n  // 音频\n  mp3: { mime: \"audio/mpeg\", kind: \"audio\" },\n  wav: { mime: \"audio/wav\", kind: \"audio\" },\n  m4a: { mime: \"audio/mp4\", kind: \"audio\" },\n  aac: { mime: \"audio/aac\", kind: \"audio\" },\n  flac: { mime: \"audio/flac\", kind: \"audio\" },\n  ogg: { mime: \"audio/ogg\", kind: \"audio\" },\n  oga: { mime: \"audio/ogg\", kind: \"audio\" },\n  opus: { mime: \"audio/ogg\", kind: \"audio\" },\n  weba: { mime: \"audio/webm\", kind: \"audio\" },\n};\n\nfunction extOf(fileName: string): string {\n  return fileName.toLowerCase().split(\".\").pop() ?? \"\";\n}\n\n/** 文件名 → 可播放媒体的 MIME 与类别；不可（或浏览器不支持）返回 null */\nexport function mediaInfo(fileName: string): MediaInfo | null {\n  return MEDIA_MIME[extOf(fileName)] ?? null;\n}\n\n/** 文件名 → MIME；非可播放媒体返回 null */\nexport function mediaMime(fileName: string): string | null {\n  return MEDIA_MIME[extOf(fileName)]?.mime ?? null;\n}\n\n/** 文件名 → audio / video；非可播放媒体返回 null */\nexport function mediaKind(fileName: string): MediaKind | null {\n  return MEDIA_MIME[extOf(fileName)]?.kind ?? null;\n}\n\n/**\n * 浏览器可**内嵌**渲染的文档 MIME。\n *\n * 与 `MEDIA_MIME` 分开维护：那张表的语义是「`<video>` / `<audio>` 能直接播放」，\n * PDF 不是音视频，混进去会让 `mediaKind()` 返回一个不存在的 kind。这里只声明\n * 「浏览器自带查看器能显示」，由前端决定用 `<iframe>` 还是保底提示。\n *\n * 注意浏览器支持面不是重点：Chrome / Edge / Firefox / Safari / WebView2 都有\n * 内置 PDF 查看器，WebKitGTK（Linux 桌面壳）没有——前端必须能优雅退化。\n */\nconst DOC_PREVIEW_MIME: Record<string, string> = {\n  pdf: \"application/pdf\",\n};\n\n/** 文件名 → 可内嵌预览的文档 MIME；非文档返回 null */\nexport function docPreviewMime(fileName: string): string | null {\n  return DOC_PREVIEW_MIME[extOf(fileName)] ?? null;\n}\n\n/**\n * 文件名 → 可用于 **HTTP Range 流式预览**的 MIME（音视频 + 可内嵌文档）。\n *\n * 节点签发文件票据 / `/files/range` 用它决定 `Content-Type`：票据里没有 MIME 时\n * 前端会直接放弃流式通道，退回整文件下载（大 PDF 尤其痛），所以 PDF 必须在这里\n * 被认出来。\n */\nexport function previewMime(fileName: string): string | null {\n  return mediaMime(fileName) ?? docPreviewMime(fileName);\n}\n\nexport interface ByteRange {\n  /** 起始偏移（含） */\n  start: number;\n  /** 结束偏移（含） */\n  end: number;\n}\n\n/**\n * 解析 `Range: bytes=...`。\n *\n * @param header 原始头值（可为 null / 空）\n * @param size   文件总字节数\n * @returns 单段区间；`null` = 忽略该头（无 Range / 多段 / 语法不合法）；\n *          `\"unsatisfiable\"` = 范围越界，调用方应回 416。\n */\nexport function parseByteRange(\n  header: string | null | undefined,\n  size: number,\n): ByteRange | \"unsatisfiable\" | null {\n  const raw = (header ?? \"\").trim();\n  if (!raw) return null;\n  const m = /^bytes=(\\d*)-(\\d*)$/i.exec(raw);\n  if (!m) return null; // 多段与其它单位一律忽略\n\n  const startRaw = m[1] ?? \"\";\n  const endRaw = m[2] ?? \"\";\n  if (!startRaw && !endRaw) return null; // \"bytes=-\"\n  if (size <= 0) return \"unsatisfiable\";\n\n  // 后缀形式：bytes=-N → 最后 N 字节\n  if (!startRaw) {\n    const suffix = Number(endRaw);\n    if (!Number.isFinite(suffix) || suffix <= 0) return \"unsatisfiable\";\n    return { start: Math.max(size - suffix, 0), end: size - 1 };\n  }\n\n  const start = Number(startRaw);\n  if (!Number.isFinite(start) || start < 0) return null;\n  if (start >= size) return \"unsatisfiable\";\n\n  // 省略结束：bytes=N- → 到文件末尾\n  if (!endRaw) return { start, end: size - 1 };\n\n  const end = Number(endRaw);\n  if (!Number.isFinite(end) || end < start) return null;\n  return { start, end: Math.min(end, size - 1) };\n}\n\n/** Range 响应的 `Content-Range` 头值 */\nexport function contentRangeHeader(range: ByteRange, size: number): string {\n  return `bytes ${range.start}-${range.end}/${size}`;\n}\n\n/**\n * 文件 ETag（强校验）。\n *\n * 由 size + mtime 组成：文件内容变化几乎必然改变其中一个；不读文件本身，\n * 因此 `HEAD` / `304` 可以在完全不触达节点的情况下应答。\n */\nexport function fileEtag(size: number, mtimeMs: number): string {\n  return `\"${size.toString(16)}-${Math.trunc(mtimeMs).toString(16)}\"`;\n}\n"],"mappings":";AA0BA,IAAM,aAAwC;AAAA;AAAA,EAE5C,KAAK,EAAE,MAAM,aAAa,MAAM,QAAQ;AAAA,EACxC,KAAK,EAAE,MAAM,aAAa,MAAM,QAAQ;AAAA,EACxC,MAAM,EAAE,MAAM,cAAc,MAAM,QAAQ;AAAA,EAC1C,KAAK,EAAE,MAAM,aAAa,MAAM,QAAQ;AAAA,EACxC,KAAK,EAAE,MAAM,mBAAmB,MAAM,QAAQ;AAAA;AAAA,EAE9C,KAAK,EAAE,MAAM,cAAc,MAAM,QAAQ;AAAA,EACzC,KAAK,EAAE,MAAM,aAAa,MAAM,QAAQ;AAAA,EACxC,KAAK,EAAE,MAAM,aAAa,MAAM,QAAQ;AAAA,EACxC,KAAK,EAAE,MAAM,aAAa,MAAM,QAAQ;AAAA,EACxC,MAAM,EAAE,MAAM,cAAc,MAAM,QAAQ;AAAA,EAC1C,KAAK,EAAE,MAAM,aAAa,MAAM,QAAQ;AAAA,EACxC,KAAK,EAAE,MAAM,aAAa,MAAM,QAAQ;AAAA,EACxC,MAAM,EAAE,MAAM,aAAa,MAAM,QAAQ;AAAA,EACzC,MAAM,EAAE,MAAM,cAAc,MAAM,QAAQ;AAC5C;AAEA,SAAS,MAAM,UAA0B;AACvC,SAAO,SAAS,YAAY,EAAE,MAAM,GAAG,EAAE,IAAI,KAAK;AACpD;AAGO,SAAS,UAAU,UAAoC;AAC5D,SAAO,WAAW,MAAM,QAAQ,CAAC,KAAK;AACxC;AAGO,SAAS,UAAU,UAAiC;AACzD,SAAO,WAAW,MAAM,QAAQ,CAAC,GAAG,QAAQ;AAC9C;AAGO,SAAS,UAAU,UAAoC;AAC5D,SAAO,WAAW,MAAM,QAAQ,CAAC,GAAG,QAAQ;AAC9C;AAYA,IAAM,mBAA2C;AAAA,EAC/C,KAAK;AACP;AAGO,SAAS,eAAe,UAAiC;AAC9D,SAAO,iBAAiB,MAAM,QAAQ,CAAC,KAAK;AAC9C;AASO,SAAS,YAAY,UAAiC;AAC3D,SAAO,UAAU,QAAQ,KAAK,eAAe,QAAQ;AACvD;AAiBO,SAAS,eACd,QACA,MACoC;AACpC,QAAM,OAAO,UAAU,IAAI,KAAK;AAChC,MAAI,CAAC,IAAK,QAAO;AACjB,QAAM,IAAI,uBAAuB,KAAK,GAAG;AACzC,MAAI,CAAC,EAAG,QAAO;AAEf,QAAM,WAAW,EAAE,CAAC,KAAK;AACzB,QAAM,SAAS,EAAE,CAAC,KAAK;AACvB,MAAI,CAAC,YAAY,CAAC,OAAQ,QAAO;AACjC,MAAI,QAAQ,EAAG,QAAO;AAGtB,MAAI,CAAC,UAAU;AACb,UAAM,SAAS,OAAO,MAAM;AAC5B,QAAI,CAAC,OAAO,SAAS,MAAM,KAAK,UAAU,EAAG,QAAO;AACpD,WAAO,EAAE,OAAO,KAAK,IAAI,OAAO,QAAQ,CAAC,GAAG,KAAK,OAAO,EAAE;AAAA,EAC5D;AAEA,QAAM,QAAQ,OAAO,QAAQ;AAC7B,MAAI,CAAC,OAAO,SAAS,KAAK,KAAK,QAAQ,EAAG,QAAO;AACjD,MAAI,SAAS,KAAM,QAAO;AAG1B,MAAI,CAAC,OAAQ,QAAO,EAAE,OAAO,KAAK,OAAO,EAAE;AAE3C,QAAM,MAAM,OAAO,MAAM;AACzB,MAAI,CAAC,OAAO,SAAS,GAAG,KAAK,MAAM,MAAO,QAAO;AACjD,SAAO,EAAE,OAAO,KAAK,KAAK,IAAI,KAAK,OAAO,CAAC,EAAE;AAC/C;AAGO,SAAS,mBAAmB,OAAkB,MAAsB;AACzE,SAAO,SAAS,MAAM,KAAK,IAAI,MAAM,GAAG,IAAI,IAAI;AAClD;AAQO,SAAS,SAAS,MAAc,SAAyB;AAC9D,SAAO,IAAI,KAAK,SAAS,EAAE,CAAC,IAAI,KAAK,MAAM,OAAO,EAAE,SAAS,EAAE,CAAC;AAClE;","names":[]}

package/dist/messages-CiXjdR1Z.d.cts

@@ -0,0 +1,257 @@
+/**
+ * 消息编解码（Envelope / Ack / Status / Event）
+ *
+ * 字段定义见 proto/fleet.proto。手写编解码，规则与 prost 对齐（proto3 默认值省略、
+ * 字段号升序、string 严格 UTF-8），未知字段按 wire type 跳过以支持前向兼容。
+ *
+ * 签名：`signableBytes()` 给出「不含 sig」的编码字节；`sig` 是 10 号字段（最后），
+ * 因此 `encode(env, sig 置空) === signableBytes(env)` 恒成立，校验方可重编码比对。
+ */
+
+/** 与现有 FleetCmdEnvelope（packages/shared/src/fleet.ts:159-178）语义一致 */
+interface Envelope {
+    /** 毫秒时间戳 */
+    t: number;
+    nonce: string;
+    reqId: string;
+    type: string;
+    clientId: string;
+    nodeId: string;
+    projectId?: string;
+    sessionId?: string;
+    /** 载荷字节（按 type 选择强类型消息或 JSON 字节） */
+    payload?: Uint8Array;
+    /**
+     * 执行预算（毫秒，可选）：由发起方指定，网关据此决定等待回执的上限。
+     * 0/缺省表示按 `type` 的默认分级（见 docs/wire-protocol.md §5.2）。
+     */
+    timeoutMs?: number;
+    /** HMAC-SHA256 原始 32 字节（**必须是最后一个字段**：其前缀即签名字节） */
+    sig?: Uint8Array;
+}
+interface Ack {
+    reqId: string;
+    type: string;
+    ok: boolean;
+    error?: string;
+    data?: Uint8Array;
+}
+interface Status {
+    nodeId: string;
+    online: boolean;
+    /** 毫秒时间戳（现有 JSON 协议为 ISO 字符串，映射在 M2） */
+    ts: number;
+    label?: string;
+    platform?: string;
+    mode?: string;
+    version?: string;
+    ip?: string;
+}
+interface EventMsg {
+    seq: number;
+    ts: number;
+    type: string;
+    projectId?: string;
+    sessionId?: string;
+    data?: Uint8Array;
+    /**
+     * 事件来源节点。由**网关**按连接绑定的 nodeId 填充（节点上行时留空）。
+     *
+     * 终端面一条连接可订阅多个节点，缺了它就无法分辨事件来自哪台节点。
+     */
+    nodeId?: string;
+}
+/**
+ * 命令终端数据（`FrameType.TERMINAL`）。
+ *
+ * 与 `EventMsg` 完全平行的另一条通道，**不是** Event 的一种：它不参与
+ * seq 游标、不入事件环形缓冲、不跨副本广播（理由见 proto 注释）。
+ */
+interface TerminalData {
+    /** 目标节点；节点上行时留空，由网关按连接绑定填充 */
+    nodeId?: string;
+    /** 终端实例 ID（节点侧生成，`t_` 前缀；与会话 ID 不同空间） */
+    terminalId: string;
+    /**
+     * 帧种类：
+     *   opened | data | exited | error   —— 节点 → 网关 → 终端
+     *   input | resize                    —— 终端 → 网关 → 节点
+     *
+     * 开/关终端不走这条通道（见 `terminal_create` / `terminal_close` 指令）。
+     */
+    kind: string;
+    /** data/input 为原始字节；resize 为 JSON 字节（{"cols":N,"rows":N}） */
+    data?: Uint8Array;
+    /** 终端内局部序号（仅该终端内有效，不参与 resume）；文件流中为 stream_id */
+    seq?: number;
+    /**
+     * 通道：0/缺省 = 终端；1 = 文件流（音视频预览）。
+     *
+     * 文件流复用 TERMINAL 帧以避开协议版本升级（帧类型低 4 位已用尽），
+     * 但网关按该字段分流，不会 fanout 给终端连接。
+     */
+    channel?: number;
+    /**
+     * P2P 打洞信令（`channel=2`）的会话标识。
+     *
+     * 网关按它把信令**回发给发起连接**，不 fanout——否则双方公网 IP 会泄漏给
+     * 同一节点的其他协作者。
+     */
+    session?: string;
+}
+declare function encodeEnvelope(env: Envelope): Uint8Array;
+/** 参与签名的字节（字段 1..10，不含 sig） */
+declare function signableBytes(env: Envelope): Uint8Array;
+declare function decodeEnvelope(bytes: Uint8Array): Envelope;
+declare function encodeAck(ack: Ack): Uint8Array;
+declare function decodeAck(bytes: Uint8Array): Ack;
+declare function encodeStatus(st: Status): Uint8Array;
+declare function decodeStatus(bytes: Uint8Array): Status;
+declare function encodeEvent(ev: EventMsg): Uint8Array;
+declare function decodeEvent(bytes: Uint8Array): EventMsg;
+
+interface Info {
+    nodeId: string;
+    platform?: string;
+    version?: string;
+    ip?: string;
+    /** 项目数 */
+    projects: number;
+    /** 会话数 */
+    sessions: number;
+    /** 运行中的会话数 */
+    running: number;
+    /** 等待审批/提问的会话数 */
+    waiting: number;
+    /** 毫秒时间戳 */
+    ts: number;
+    /**
+     * 节点上报的**原始 info JSON**（含 label / 项目明细 / stats / usage）。
+     *
+     * 5..9 的计数供网关快速聚合；本字段原样承载完整快照，供控制面读取
+     * （替代从前经 MQTT retained info 的那条路径），避免为视图反复改 schema。
+     */
+    detail?: Uint8Array;
+}
+declare function encodeInfo(info: Info): Uint8Array;
+declare function decodeInfo(bytes: Uint8Array): Info;
+/**
+ * 节点通知：审批请求 / 提问 / 回合完成 / 错误。
+ *
+ * 与 `EventMsg` 的分工：Event 是高频实时进度，Notify 是低频但重要（审批/提问挂起必须
+ * 让终端看到）。两者共用网关分配的 `seq` 游标与缓冲，因此 `resume` 时都能回放。
+ */
+interface NotifyMsg {
+    /** 由网关分配的游标（节点上报时留 0） */
+    seq: number;
+    ts: number;
+    kind: string;
+    projectId?: string;
+    sessionId?: string;
+    data?: Uint8Array;
+    /** 通知来源节点；由网关填充（多路复用终端据此归属到具体节点） */
+    nodeId?: string;
+}
+declare function encodeNotify(n: NotifyMsg): Uint8Array;
+declare function decodeNotify(bytes: Uint8Array): NotifyMsg;
+interface Auth {
+    /** 节点面：nodeId；终端面：userId */
+    id: string;
+    /** 毫秒时间戳（±60s 窗口） */
+    ts: number;
+    nonce: string;
+    /** 协议能力版本 */
+    proto: number;
+    /** "node" | "terminal" */
+    kind: string;
+    /** 终端载体："web" | "miniapp" | "app"（节点面留空） */
+    client?: string;
+    /**
+     * 终端面 = HMAC-SHA256(terminalSecret, signableAuthBytes)；节点面 = HMAC-SHA256(fleetSecret, …)
+     *
+     * 注意 `scope`/`expires` 在 `token` **之后**：proto3 按字段号升序编码，因此它们仍在
+     * `signableAuthBytes` 内 —— 即**同样受签名完整性保护**（改 scope 会让 token 失效）。
+     */
+    token?: Uint8Array;
+    /** 终端面被授权的 nodeId 列表（非空时网关严格校验；见 `verifyTerminalAuth`） */
+    scope?: string[];
+    /** 终端面过期时刻（毫秒）；>0 时网关跳过 ±60s 窗口 */
+    expires?: number;
+    /**
+     * 客户端能力位（见 `frame.ts` 的 `CAP_DEFLATE`）。
+     *
+     * 只用于声明支持；节点只有在 `AuthOk.caps` 也回同样位时才启用压缩上行。
+     * 旧网关忽略未知字段，行为不变。
+     */
+    caps?: number;
+}
+interface AuthOk {
+    ok: boolean;
+    error?: string;
+    serverTs: number;
+    /** 网关能力位（语义同 `Auth.caps`）；旧网关不回此字段（视为 0） */
+    caps?: number;
+}
+declare function encodeAuth(auth: Auth): Uint8Array;
+/**
+ * 参与签名的字节：清空 `token` 后编码。
+ *
+ * `scope`/`expires` 字段号大于 `token`，但 prost/本实现都按字段号升序编码，
+ * 因此它们**仍在签名字节内**（受完整性保护），不是「token 之后的免费字段」。
+ */
+declare function signableAuthBytes(auth: Auth): Uint8Array;
+declare function decodeAuth(bytes: Uint8Array): Auth;
+declare function encodeAuthOk(ok: AuthOk): Uint8Array;
+declare function decodeAuthOk(bytes: Uint8Array): AuthOk;
+declare function encodeTerminalData(td: TerminalData): Uint8Array;
+declare function decodeTerminalData(bytes: Uint8Array): TerminalData;
+interface NodeState {
+    nodeId: string;
+    online: boolean;
+    lastSeen: number;
+    platform?: string;
+    version?: string;
+    ip?: string;
+    /**
+     * 节点上报的原始 info JSON（`Info.detail` 的转发），供终端快照读取项目/统计。
+     *
+     * 快照借此**替代 MQTT retained info**：订阅后一次拿到，不必逐节点发指令。
+     * 节点从未上报过 INFO 时为空。
+     */
+    detail?: Uint8Array;
+}
+interface Snapshot {
+    nodes: NodeState[];
+    /** 当前事件游标（客户端据此发起 resume） */
+    seq: number;
+}
+declare function encodeNodeState(n: NodeState): Uint8Array;
+declare function decodeNodeState(bytes: Uint8Array): NodeState;
+declare function encodeSnapshot(snap: Snapshot): Uint8Array;
+declare function decodeSnapshot(bytes: Uint8Array): Snapshot;
+declare function encodeNodeIds(ids: string[]): Uint8Array;
+declare function decodeNodeIds(bytes: Uint8Array): string[];
+/**
+ * 订阅帧：节点列表 + 是否要内容增量。
+ *
+ * `noDetail` 用反向布尔的 `.proto` 字段（`Subscribe.no_detail`）：默认 false
+ * 表示「要细节」，与本字段出现前的行为一致。只有双方（控制台/网关）都支持时
+ * 才会真正省下带宽；旧网关忽略未知字段，退化为全量推送。
+ */
+declare function encodeSubscribe(ids: string[], noDetail?: boolean): Uint8Array;
+/** 只取节点列表（保持既有调用方与测试的返回类型不变） */
+declare const decodeSubscribe: typeof decodeNodeIds;
+/** 连 `no_detail` 一起解出（网关侧 / 测试需要判定订阅意图时用） */
+declare function decodeSubscribeDetail(bytes: Uint8Array): {
+    nodeIds: string[];
+    noDetail: boolean;
+};
+declare const encodeUnsubscribe: typeof encodeNodeIds;
+declare const decodeUnsubscribe: typeof decodeNodeIds;
+declare function encodeResume(since: number, nodeIds?: string[]): Uint8Array;
+declare function decodeResume(bytes: Uint8Array): {
+    since: number;
+    nodeIds: string[];
+};
+
+export { type Auth as A, encodeNodeState as B, encodeNotify as C, encodeResume as D, type Envelope as E, encodeSnapshot as F, encodeStatus as G, encodeSubscribe as H, type Info as I, encodeTerminalData as J, encodeUnsubscribe as K, signableAuthBytes as L, signableBytes as M, type NodeState as N, type Snapshot as S, type TerminalData as T, type Ack as a, type AuthOk as b, type EventMsg as c, type NotifyMsg as d, type Status as e, decodeAck as f, decodeAuth as g, decodeAuthOk as h, decodeEnvelope as i, decodeEvent as j, decodeInfo as k, decodeNodeState as l, decodeNotify as m, decodeResume as n, decodeSnapshot as o, decodeStatus as p, decodeSubscribe as q, decodeSubscribeDetail as r, decodeTerminalData as s, decodeUnsubscribe as t, encodeAck as u, encodeAuth as v, encodeAuthOk as w, encodeEnvelope as x, encodeEvent as y, encodeInfo as z };

package/dist/messages-CiXjdR1Z.d.ts

@@ -0,0 +1,257 @@
+/**
+ * 消息编解码（Envelope / Ack / Status / Event）
+ *
+ * 字段定义见 proto/fleet.proto。手写编解码，规则与 prost 对齐（proto3 默认值省略、
+ * 字段号升序、string 严格 UTF-8），未知字段按 wire type 跳过以支持前向兼容。
+ *
+ * 签名：`signableBytes()` 给出「不含 sig」的编码字节；`sig` 是 10 号字段（最后），
+ * 因此 `encode(env, sig 置空) === signableBytes(env)` 恒成立，校验方可重编码比对。
+ */
+
+/** 与现有 FleetCmdEnvelope（packages/shared/src/fleet.ts:159-178）语义一致 */
+interface Envelope {
+    /** 毫秒时间戳 */
+    t: number;
+    nonce: string;
+    reqId: string;
+    type: string;
+    clientId: string;
+    nodeId: string;
+    projectId?: string;
+    sessionId?: string;
+    /** 载荷字节（按 type 选择强类型消息或 JSON 字节） */
+    payload?: Uint8Array;
+    /**
+     * 执行预算（毫秒，可选）：由发起方指定，网关据此决定等待回执的上限。
+     * 0/缺省表示按 `type` 的默认分级（见 docs/wire-protocol.md §5.2）。
+     */
+    timeoutMs?: number;
+    /** HMAC-SHA256 原始 32 字节（**必须是最后一个字段**：其前缀即签名字节） */
+    sig?: Uint8Array;
+}
+interface Ack {
+    reqId: string;
+    type: string;
+    ok: boolean;
+    error?: string;
+    data?: Uint8Array;
+}
+interface Status {
+    nodeId: string;
+    online: boolean;
+    /** 毫秒时间戳（现有 JSON 协议为 ISO 字符串，映射在 M2） */
+    ts: number;
+    label?: string;
+    platform?: string;
+    mode?: string;
+    version?: string;
+    ip?: string;
+}
+interface EventMsg {
+    seq: number;
+    ts: number;
+    type: string;
+    projectId?: string;
+    sessionId?: string;
+    data?: Uint8Array;
+    /**
+     * 事件来源节点。由**网关**按连接绑定的 nodeId 填充（节点上行时留空）。
+     *
+     * 终端面一条连接可订阅多个节点，缺了它就无法分辨事件来自哪台节点。
+     */
+    nodeId?: string;
+}
+/**
+ * 命令终端数据（`FrameType.TERMINAL`）。
+ *
+ * 与 `EventMsg` 完全平行的另一条通道，**不是** Event 的一种：它不参与
+ * seq 游标、不入事件环形缓冲、不跨副本广播（理由见 proto 注释）。
+ */
+interface TerminalData {
+    /** 目标节点；节点上行时留空，由网关按连接绑定填充 */
+    nodeId?: string;
+    /** 终端实例 ID（节点侧生成，`t_` 前缀；与会话 ID 不同空间） */
+    terminalId: string;
+    /**
+     * 帧种类：
+     *   opened | data | exited | error   —— 节点 → 网关 → 终端
+     *   input | resize                    —— 终端 → 网关 → 节点
+     *
+     * 开/关终端不走这条通道（见 `terminal_create` / `terminal_close` 指令）。
+     */
+    kind: string;
+    /** data/input 为原始字节；resize 为 JSON 字节（{"cols":N,"rows":N}） */
+    data?: Uint8Array;
+    /** 终端内局部序号（仅该终端内有效，不参与 resume）；文件流中为 stream_id */
+    seq?: number;
+    /**
+     * 通道：0/缺省 = 终端；1 = 文件流（音视频预览）。
+     *
+     * 文件流复用 TERMINAL 帧以避开协议版本升级（帧类型低 4 位已用尽），
+     * 但网关按该字段分流，不会 fanout 给终端连接。
+     */
+    channel?: number;
+    /**
+     * P2P 打洞信令（`channel=2`）的会话标识。
+     *
+     * 网关按它把信令**回发给发起连接**，不 fanout——否则双方公网 IP 会泄漏给
+     * 同一节点的其他协作者。
+     */
+    session?: string;
+}
+declare function encodeEnvelope(env: Envelope): Uint8Array;
+/** 参与签名的字节（字段 1..10，不含 sig） */
+declare function signableBytes(env: Envelope): Uint8Array;
+declare function decodeEnvelope(bytes: Uint8Array): Envelope;
+declare function encodeAck(ack: Ack): Uint8Array;
+declare function decodeAck(bytes: Uint8Array): Ack;
+declare function encodeStatus(st: Status): Uint8Array;
+declare function decodeStatus(bytes: Uint8Array): Status;
+declare function encodeEvent(ev: EventMsg): Uint8Array;
+declare function decodeEvent(bytes: Uint8Array): EventMsg;
+
+interface Info {
+    nodeId: string;
+    platform?: string;
+    version?: string;
+    ip?: string;
+    /** 项目数 */
+    projects: number;
+    /** 会话数 */
+    sessions: number;
+    /** 运行中的会话数 */
+    running: number;
+    /** 等待审批/提问的会话数 */
+    waiting: number;
+    /** 毫秒时间戳 */
+    ts: number;
+    /**
+     * 节点上报的**原始 info JSON**（含 label / 项目明细 / stats / usage）。
+     *
+     * 5..9 的计数供网关快速聚合；本字段原样承载完整快照，供控制面读取
+     * （替代从前经 MQTT retained info 的那条路径），避免为视图反复改 schema。
+     */
+    detail?: Uint8Array;
+}
+declare function encodeInfo(info: Info): Uint8Array;
+declare function decodeInfo(bytes: Uint8Array): Info;
+/**
+ * 节点通知：审批请求 / 提问 / 回合完成 / 错误。
+ *
+ * 与 `EventMsg` 的分工：Event 是高频实时进度，Notify 是低频但重要（审批/提问挂起必须
+ * 让终端看到）。两者共用网关分配的 `seq` 游标与缓冲，因此 `resume` 时都能回放。
+ */
+interface NotifyMsg {
+    /** 由网关分配的游标（节点上报时留 0） */
+    seq: number;
+    ts: number;
+    kind: string;
+    projectId?: string;
+    sessionId?: string;
+    data?: Uint8Array;
+    /** 通知来源节点；由网关填充（多路复用终端据此归属到具体节点） */
+    nodeId?: string;
+}
+declare function encodeNotify(n: NotifyMsg): Uint8Array;
+declare function decodeNotify(bytes: Uint8Array): NotifyMsg;
+interface Auth {
+    /** 节点面：nodeId；终端面：userId */
+    id: string;
+    /** 毫秒时间戳（±60s 窗口） */
+    ts: number;
+    nonce: string;
+    /** 协议能力版本 */
+    proto: number;
+    /** "node" | "terminal" */
+    kind: string;
+    /** 终端载体："web" | "miniapp" | "app"（节点面留空） */
+    client?: string;
+    /**
+     * 终端面 = HMAC-SHA256(terminalSecret, signableAuthBytes)；节点面 = HMAC-SHA256(fleetSecret, …)
+     *
+     * 注意 `scope`/`expires` 在 `token` **之后**：proto3 按字段号升序编码，因此它们仍在
+     * `signableAuthBytes` 内 —— 即**同样受签名完整性保护**（改 scope 会让 token 失效）。
+     */
+    token?: Uint8Array;
+    /** 终端面被授权的 nodeId 列表（非空时网关严格校验；见 `verifyTerminalAuth`） */
+    scope?: string[];
+    /** 终端面过期时刻（毫秒）；>0 时网关跳过 ±60s 窗口 */
+    expires?: number;
+    /**
+     * 客户端能力位（见 `frame.ts` 的 `CAP_DEFLATE`）。
+     *
+     * 只用于声明支持；节点只有在 `AuthOk.caps` 也回同样位时才启用压缩上行。
+     * 旧网关忽略未知字段，行为不变。
+     */
+    caps?: number;
+}
+interface AuthOk {
+    ok: boolean;
+    error?: string;
+    serverTs: number;
+    /** 网关能力位（语义同 `Auth.caps`）；旧网关不回此字段（视为 0） */
+    caps?: number;
+}
+declare function encodeAuth(auth: Auth): Uint8Array;
+/**
+ * 参与签名的字节：清空 `token` 后编码。
+ *
+ * `scope`/`expires` 字段号大于 `token`，但 prost/本实现都按字段号升序编码，
+ * 因此它们**仍在签名字节内**（受完整性保护），不是「token 之后的免费字段」。
+ */
+declare function signableAuthBytes(auth: Auth): Uint8Array;
+declare function decodeAuth(bytes: Uint8Array): Auth;
+declare function encodeAuthOk(ok: AuthOk): Uint8Array;
+declare function decodeAuthOk(bytes: Uint8Array): AuthOk;
+declare function encodeTerminalData(td: TerminalData): Uint8Array;
+declare function decodeTerminalData(bytes: Uint8Array): TerminalData;
+interface NodeState {
+    nodeId: string;
+    online: boolean;
+    lastSeen: number;
+    platform?: string;
+    version?: string;
+    ip?: string;
+    /**
+     * 节点上报的原始 info JSON（`Info.detail` 的转发），供终端快照读取项目/统计。
+     *
+     * 快照借此**替代 MQTT retained info**：订阅后一次拿到，不必逐节点发指令。
+     * 节点从未上报过 INFO 时为空。
+     */
+    detail?: Uint8Array;
+}
+interface Snapshot {
+    nodes: NodeState[];
+    /** 当前事件游标（客户端据此发起 resume） */
+    seq: number;
+}
+declare function encodeNodeState(n: NodeState): Uint8Array;
+declare function decodeNodeState(bytes: Uint8Array): NodeState;
+declare function encodeSnapshot(snap: Snapshot): Uint8Array;
+declare function decodeSnapshot(bytes: Uint8Array): Snapshot;
+declare function encodeNodeIds(ids: string[]): Uint8Array;
+declare function decodeNodeIds(bytes: Uint8Array): string[];
+/**
+ * 订阅帧：节点列表 + 是否要内容增量。
+ *
+ * `noDetail` 用反向布尔的 `.proto` 字段（`Subscribe.no_detail`）：默认 false
+ * 表示「要细节」，与本字段出现前的行为一致。只有双方（控制台/网关）都支持时
+ * 才会真正省下带宽；旧网关忽略未知字段，退化为全量推送。
+ */
+declare function encodeSubscribe(ids: string[], noDetail?: boolean): Uint8Array;
+/** 只取节点列表（保持既有调用方与测试的返回类型不变） */
+declare const decodeSubscribe: typeof decodeNodeIds;
+/** 连 `no_detail` 一起解出（网关侧 / 测试需要判定订阅意图时用） */
+declare function decodeSubscribeDetail(bytes: Uint8Array): {
+    nodeIds: string[];
+    noDetail: boolean;
+};
+declare const encodeUnsubscribe: typeof encodeNodeIds;
+declare const decodeUnsubscribe: typeof decodeNodeIds;
+declare function encodeResume(since: number, nodeIds?: string[]): Uint8Array;
+declare function decodeResume(bytes: Uint8Array): {
+    since: number;
+    nodeIds: string[];
+};
+
+export { type Auth as A, encodeNodeState as B, encodeNotify as C, encodeResume as D, type Envelope as E, encodeSnapshot as F, encodeStatus as G, encodeSubscribe as H, type Info as I, encodeTerminalData as J, encodeUnsubscribe as K, signableAuthBytes as L, signableBytes as M, type NodeState as N, type Snapshot as S, type TerminalData as T, type Ack as a, type AuthOk as b, type EventMsg as c, type NotifyMsg as d, type Status as e, decodeAck as f, decodeAuth as g, decodeAuthOk as h, decodeEnvelope as i, decodeEvent as j, decodeInfo as k, decodeNodeState as l, decodeNotify as m, decodeResume as n, decodeSnapshot as o, decodeStatus as p, decodeSubscribe as q, decodeSubscribeDetail as r, decodeTerminalData as s, decodeUnsubscribe as t, encodeAck as u, encodeAuth as v, encodeAuthOk as w, encodeEnvelope as x, encodeEvent as y, encodeInfo as z };