@napuketto/adapter 0.2.1 → 0.3.1

package/dist/kurobot/index.d.mts

@@ -0,0 +1,840 @@
+import { i as ProtocolConfig, n as BaseProtocolAdapter } from "../index-CDKj-jus.mjs";
+import { CanonicalElement, MsgEventChannel, Peer, RawMessage } from "@napuketto/kernel";
+import { z } from "zod";
+//#region src/kurobot/config.d.ts
+/** kurobot 配置 schema。 */
+declare const kurobotConfigSchema: z.ZodObject<{
+  url: z.ZodURL;
+  token: z.ZodDefault<z.ZodString>;
+  client: z.ZodOptional<z.ZodString>;
+  commandPrefix: z.ZodDefault<z.ZodString>;
+  pingIntervalMs: z.ZodDefault<z.ZodNumber>;
+  chatTemplate: z.ZodDefault<z.ZodString>;
+  joinTemplate: z.ZodDefault<z.ZodString>;
+  leaveTemplate: z.ZodDefault<z.ZodString>;
+  deathTemplate: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/** kurobot 配置类型（由 schema 推导）。 */
+type KurobotConfig = z.infer<typeof kurobotConfigSchema>;
+/**
+ * ConfigBase 必填的 defaults 形参兜底值（url 必填 → 无法 `parse({})`）。
+ * 装配走 seed 模式（段存在才装配，seed 已校验），defaults 不参与生效值；
+ * 仅在「无 seed 且配置文件缺失」的直连场景被落盘——端口 0 地址连接会失败退避，
+ * 不会静默假在线。
+ */
+declare function kurobotConfigDefaults(): KurobotConfig;
+//#endregion
+//#region src/kurobot/schema.d.ts
+declare const PROTOCOL_NAME: "kurobridge-ws";
+/** 语义化版本（主版本相同即兼容，ADR-026：0.2.x/0.3.0 服务端均接受 0.3.1 hello）。 */
+declare const PROTOCOL_VERSION: "0.4.0";
+/** WS 子协议（握手期校验，服务端 handleProtocols 不带即拒连）。 */
+declare const WS_SUBPROTOCOL: "kurobridge-ws.v1";
+/** 协议版本兼容判定（镜像 meta.ts 同名函数）：主版本号相同即兼容。 */
+declare function isProtocolVersionCompatible(peerVersion: string, serverVersion: string): boolean;
+/**
+ * 通用线格式帧（两段式解析的第一段）：只约束帧骨架（type 受 snake_case、
+ * id 存在时须 UUID、body 任意），供收帧侧「先取 type、再分发到具体 schema」。
+ */
+declare const wireFrameSchema: z.ZodObject<{
+  header: z.ZodObject<{
+    type: z.ZodString;
+    id: z.ZodOptional<z.ZodUUID>;
+  }, z.core.$strip>;
+  body: z.ZodUnknown;
+}, z.core.$strip>;
+/** 出帧：扁平消息 → 线格式 JSON 文本（单行，可直接走 WS 文本帧） */
+declare function encodeFrame(message: {
+  type: string;
+  body: unknown;
+  id?: string;
+}): string;
+/** 请求-响应的命令结果体（ok 分支可选 `output`：命令输出行；与 query/命令链共用）。 */
+declare const commandResultBodySchema: z.ZodUnion<readonly [z.ZodObject<{
+  ok: z.ZodLiteral<true>;
+  output: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+  ok: z.ZodLiteral<false>;
+  error: z.ZodString;
+}, z.core.$strip>]>;
+type CommandResultBody = z.infer<typeof commandResultBodySchema>;
+declare const helloBodySchema: z.ZodObject<{
+  peerId: z.ZodString;
+  platform: z.ZodString;
+  version: z.ZodString;
+  protocolVersion: z.ZodString;
+  token: z.ZodOptional<z.ZodString>;
+  client: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** 对端注册（请求，服务端必须回同 id 的 hello_ack）。 */
+declare const helloFrame: z.ZodPipe<z.ZodObject<{
+  header: z.ZodObject<{
+    type: z.ZodLiteral<"hello">;
+    id: z.ZodUUID;
+  }, z.core.$strip>;
+  body: z.ZodObject<{
+    peerId: z.ZodString;
+    platform: z.ZodString;
+    version: z.ZodString;
+    protocolVersion: z.ZodString;
+    token: z.ZodOptional<z.ZodString>;
+    client: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+  type: "hello";
+  id: string;
+  body: {
+    peerId: string;
+    platform: string;
+    version: string;
+    protocolVersion: string;
+    token?: string | undefined;
+    client?: string | undefined;
+  };
+}, {
+  header: {
+    type: "hello";
+    id: string;
+  };
+  body: {
+    peerId: string;
+    platform: string;
+    version: string;
+    protocolVersion: string;
+    token?: string | undefined;
+    client?: string | undefined;
+  };
+}>>;
+type HelloBody = z.infer<typeof helloBodySchema>;
+/** 心跳请求（应用层帧——服务端空闲检测只认应用层入帧，WS 层 ping 无效）。 */
+declare const pingFrame: z.ZodPipe<z.ZodObject<{
+  header: z.ZodObject<{
+    type: z.ZodLiteral<"ping">;
+    id: z.ZodUUID;
+  }, z.core.$strip>;
+  body: z.ZodObject<{
+    timestamp: z.ZodNumber;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+  type: "ping";
+  id: string;
+  body: {
+    timestamp: number;
+  };
+}, {
+  header: {
+    type: "ping";
+    id: string;
+  };
+  body: {
+    timestamp: number;
+  };
+}>>;
+declare const platformChatBodySchema: z.ZodObject<{
+  channel: z.ZodString;
+  sender: z.ZodString;
+  content: z.ZodString;
+}, z.core.$strip>;
+/** 平台 → 游戏聊天（事件；服务端按绑定表过滤未绑定频道）。 */
+declare const platformChatFrame: z.ZodPipe<z.ZodObject<{
+  header: z.ZodObject<{
+    type: z.ZodLiteral<"chat">;
+  }, z.core.$strict>;
+  body: z.ZodObject<{
+    channel: z.ZodString;
+    sender: z.ZodString;
+    content: z.ZodString;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+  type: "chat";
+  body: {
+    channel: string;
+    sender: string;
+    content: string;
+  };
+}, {
+  header: {
+    type: "chat";
+  };
+  body: {
+    channel: string;
+    sender: string;
+    content: string;
+  };
+}>>;
+type PlatformChatBody = z.infer<typeof platformChatBodySchema>;
+declare const commandBodySchema: z.ZodObject<{
+  command: z.ZodString;
+  source: z.ZodObject<{
+    channel: z.ZodString;
+    userId: z.ZodString;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+/** 群指令 → 执行游戏命令（请求；响应为同 id command_result）。 */
+declare const commandFrame: z.ZodPipe<z.ZodObject<{
+  header: z.ZodObject<{
+    type: z.ZodLiteral<"command">;
+    id: z.ZodUUID;
+  }, z.core.$strip>;
+  body: z.ZodObject<{
+    command: z.ZodString;
+    source: z.ZodObject<{
+      channel: z.ZodString;
+      userId: z.ZodString;
+    }, z.core.$strip>;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+  type: "command";
+  id: string;
+  body: {
+    command: string;
+    source: {
+      channel: string;
+      userId: string;
+    };
+  };
+}, {
+  header: {
+    type: "command";
+    id: string;
+  };
+  body: {
+    command: string;
+    source: {
+      channel: string;
+      userId: string;
+    };
+  };
+}>>;
+type CommandBody = z.infer<typeof commandBodySchema>;
+type CommandFrame = z.infer<typeof commandFrame>;
+/** 状态/绑定查询（请求；响应为同 id query_result）。 */
+declare const queryFrame: z.ZodPipe<z.ZodObject<{
+  header: z.ZodObject<{
+    type: z.ZodLiteral<"query">;
+    id: z.ZodUUID;
+  }, z.core.$strip>;
+  body: z.ZodObject<{
+    kind: z.ZodUnion<readonly [z.ZodLiteral<"status">, z.ZodLiteral<"bindings">]>;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+  type: "query";
+  id: string;
+  body: {
+    kind: "bindings" | "status";
+  };
+}, {
+  header: {
+    type: "query";
+    id: string;
+  };
+  body: {
+    kind: "bindings" | "status";
+  };
+}>>;
+declare const helloAckOkBodySchema: z.ZodObject<{
+  ok: z.ZodLiteral<true>;
+  serverId: z.ZodString;
+  version: z.ZodString;
+  protocolVersion: z.ZodString;
+  channelBindings: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+declare const helloAckErrorBodySchema: z.ZodObject<{
+  ok: z.ZodLiteral<false>;
+  reason: z.ZodString;
+}, z.core.$strip>;
+/** 握手结果（响应，同 id）。 */
+declare const helloAckFrame: z.ZodUnion<readonly [z.ZodPipe<z.ZodObject<{
+  header: z.ZodObject<{
+    type: z.ZodLiteral<"hello_ack">;
+    id: z.ZodUUID;
+  }, z.core.$strip>;
+  body: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    serverId: z.ZodString;
+    version: z.ZodString;
+    protocolVersion: z.ZodString;
+    channelBindings: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+  type: "hello_ack";
+  id: string;
+  body: {
+    ok: true;
+    serverId: string;
+    version: string;
+    protocolVersion: string;
+    channelBindings: string[];
+  };
+}, {
+  header: {
+    type: "hello_ack";
+    id: string;
+  };
+  body: {
+    ok: true;
+    serverId: string;
+    version: string;
+    protocolVersion: string;
+    channelBindings: string[];
+  };
+}>>, z.ZodPipe<z.ZodObject<{
+  header: z.ZodObject<{
+    type: z.ZodLiteral<"hello_ack">;
+    id: z.ZodUUID;
+  }, z.core.$strip>;
+  body: z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    reason: z.ZodString;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+  type: "hello_ack";
+  id: string;
+  body: {
+    ok: false;
+    reason: string;
+  };
+}, {
+  header: {
+    type: "hello_ack";
+    id: string;
+  };
+  body: {
+    ok: false;
+    reason: string;
+  };
+}>>]>;
+type HelloAckOkBody = z.infer<typeof helloAckOkBodySchema>;
+type HelloAckErrorBody = z.infer<typeof helloAckErrorBodySchema>;
+type HelloAckBody = HelloAckOkBody | HelloAckErrorBody;
+declare const pongBodySchema: z.ZodObject<{
+  timestamp: z.ZodNumber;
+}, z.core.$strip>;
+/** 心跳响应（不需要处理：收不到就等服务端 1001 关闭走重连）。 */
+declare const pongFrame: z.ZodPipe<z.ZodObject<{
+  header: z.ZodObject<{
+    type: z.ZodLiteral<"pong">;
+    id: z.ZodUUID;
+  }, z.core.$strip>;
+  body: z.ZodObject<{
+    timestamp: z.ZodNumber;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+  type: "pong";
+  id: string;
+  body: {
+    timestamp: number;
+  };
+}, {
+  header: {
+    type: "pong";
+    id: string;
+  };
+  body: {
+    timestamp: number;
+  };
+}>>;
+type PongBody = z.infer<typeof pongBodySchema>;
+declare const gameChatBodySchema: z.ZodObject<{
+  channel: z.ZodString;
+  playerName: z.ZodString;
+  content: z.ZodString;
+}, z.core.$strip>;
+/** 游戏 → 平台聊天（事件）。 */
+declare const gameChatFrame: z.ZodPipe<z.ZodObject<{
+  header: z.ZodObject<{
+    type: z.ZodLiteral<"chat">;
+  }, z.core.$strict>;
+  body: z.ZodObject<{
+    channel: z.ZodString;
+    playerName: z.ZodString;
+    content: z.ZodString;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+  type: "chat";
+  body: {
+    channel: string;
+    playerName: string;
+    content: string;
+  };
+}, {
+  header: {
+    type: "chat";
+  };
+  body: {
+    channel: string;
+    playerName: string;
+    content: string;
+  };
+}>>;
+type GameChatBody = z.infer<typeof gameChatBodySchema>;
+declare const joinBodySchema: z.ZodObject<{
+  channel: z.ZodString;
+  playerName: z.ZodString;
+}, z.core.$strip>;
+/** 玩家进服（事件，按绑定频道 fan-out）。 */
+declare const joinFrame: z.ZodPipe<z.ZodObject<{
+  header: z.ZodObject<{
+    type: z.ZodLiteral<"join">;
+  }, z.core.$strict>;
+  body: z.ZodObject<{
+    channel: z.ZodString;
+    playerName: z.ZodString;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+  type: "join";
+  body: {
+    channel: string;
+    playerName: string;
+  };
+}, {
+  header: {
+    type: "join";
+  };
+  body: {
+    channel: string;
+    playerName: string;
+  };
+}>>;
+type JoinBody = z.infer<typeof joinBodySchema>;
+declare const leaveBodySchema: z.ZodObject<{
+  channel: z.ZodString;
+  playerName: z.ZodString;
+}, z.core.$strip>;
+/** 玩家退服（事件，按绑定频道 fan-out）。 */
+declare const leaveFrame: z.ZodPipe<z.ZodObject<{
+  header: z.ZodObject<{
+    type: z.ZodLiteral<"leave">;
+  }, z.core.$strict>;
+  body: z.ZodObject<{
+    channel: z.ZodString;
+    playerName: z.ZodString;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+  type: "leave";
+  body: {
+    channel: string;
+    playerName: string;
+  };
+}, {
+  header: {
+    type: "leave";
+  };
+  body: {
+    channel: string;
+    playerName: string;
+  };
+}>>;
+type LeaveBody = z.infer<typeof leaveBodySchema>;
+declare const statusBodySchema: z.ZodObject<{
+  tps: z.ZodNumber;
+  onlinePlayers: z.ZodNumber;
+  uptimeSeconds: z.ZodNumber;
+}, z.core.$strip>;
+/** 服务器状态（事件；无 channel——全服状态而非频道消息）。 */
+declare const statusFrame: z.ZodPipe<z.ZodObject<{
+  header: z.ZodObject<{
+    type: z.ZodLiteral<"status">;
+  }, z.core.$strict>;
+  body: z.ZodObject<{
+    tps: z.ZodNumber;
+    onlinePlayers: z.ZodNumber;
+    uptimeSeconds: z.ZodNumber;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+  type: "status";
+  body: {
+    tps: number;
+    onlinePlayers: number;
+    uptimeSeconds: number;
+  };
+}, {
+  header: {
+    type: "status";
+  };
+  body: {
+    tps: number;
+    onlinePlayers: number;
+    uptimeSeconds: number;
+  };
+}>>;
+type StatusBody = z.infer<typeof statusBodySchema>;
+declare const bindingsUpdatedBodySchema: z.ZodObject<{
+  channelBindings: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/** 绑定表变更推送（事件）。 */
+declare const bindingsUpdatedFrame: z.ZodPipe<z.ZodObject<{
+  header: z.ZodObject<{
+    type: z.ZodLiteral<"bindings_updated">;
+  }, z.core.$strict>;
+  body: z.ZodObject<{
+    channelBindings: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+  type: "bindings_updated";
+  body: {
+    channelBindings: string[];
+  };
+}, {
+  header: {
+    type: "bindings_updated";
+  };
+  body: {
+    channelBindings: string[];
+  };
+}>>;
+type BindingsUpdatedBody = z.infer<typeof bindingsUpdatedBodySchema>;
+/** 群指令的执行结果（响应，同 id）。 */
+declare const commandResultFrame: z.ZodPipe<z.ZodObject<{
+  header: z.ZodObject<{
+    type: z.ZodLiteral<"command_result">;
+    id: z.ZodUUID;
+  }, z.core.$strip>;
+  body: z.ZodUnion<readonly [z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    output: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  }, z.core.$strip>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    error: z.ZodString;
+  }, z.core.$strip>]>;
+}, z.core.$strip>, z.ZodTransform<{
+  type: "command_result";
+  id: string;
+  body: {
+    ok: true;
+    output?: string[] | undefined;
+  } | {
+    ok: false;
+    error: string;
+  };
+}, {
+  header: {
+    type: "command_result";
+    id: string;
+  };
+  body: {
+    ok: true;
+    output?: string[] | undefined;
+  } | {
+    ok: false;
+    error: string;
+  };
+}>>;
+declare const queryResultBodySchema: z.ZodUnion<readonly [z.ZodObject<{
+  ok: z.ZodLiteral<true>;
+  data: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+  ok: z.ZodLiteral<false>;
+  error: z.ZodString;
+}, z.core.$strip>]>;
+/** 查询结果（响应，同 id）。 */
+declare const queryResultFrame: z.ZodPipe<z.ZodObject<{
+  header: z.ZodObject<{
+    type: z.ZodLiteral<"query_result">;
+    id: z.ZodUUID;
+  }, z.core.$strip>;
+  body: z.ZodUnion<readonly [z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    data: z.ZodUnknown;
+  }, z.core.$strip>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    error: z.ZodString;
+  }, z.core.$strip>]>;
+}, z.core.$strip>, z.ZodTransform<{
+  type: "query_result";
+  id: string;
+  body: {
+    ok: true;
+    data: unknown;
+  } | {
+    ok: false;
+    error: string;
+  };
+}, {
+  header: {
+    type: "query_result";
+    id: string;
+  };
+  body: {
+    ok: true;
+    data: unknown;
+  } | {
+    ok: false;
+    error: string;
+  };
+}>>;
+type QueryResultBody = z.infer<typeof queryResultBodySchema>;
+declare const deathBodySchema: z.ZodObject<{
+  channel: z.ZodString;
+  player: z.ZodString;
+  message: z.ZodString;
+}, z.core.$strip>;
+/** 玩家死亡（事件，按绑定频道 fan-out 对齐 join/leave）。 */
+declare const deathFrame: z.ZodPipe<z.ZodObject<{
+  header: z.ZodObject<{
+    type: z.ZodLiteral<"death">;
+  }, z.core.$strict>;
+  body: z.ZodObject<{
+    channel: z.ZodString;
+    player: z.ZodString;
+    message: z.ZodString;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+  type: "death";
+  body: {
+    channel: string;
+    player: string;
+    message: string;
+  };
+}, {
+  header: {
+    type: "death";
+  };
+  body: {
+    channel: string;
+    player: string;
+    message: string;
+  };
+}>>;
+type DeathBody = z.infer<typeof deathBodySchema>;
+//#endregion
+//#region src/kurobot/connection.d.ts
+/** 连接层日志最小面（装配方传 pino 实例；缺省静默）。 */
+interface KurobotLogger {
+  debug(obj: unknown, msg: string): void;
+  info(obj: unknown, msg: string): void;
+  warn(obj: unknown, msg: string): void;
+  error(obj: unknown, msg: string): void;
+}
+/** 服务端 → 对端的已知业务帧（扁平消息；hello_ack 由连接层内部消费不经此回调）。 */
+type ServerEventMessage = {
+  type: "pong";
+  id: string;
+  body: PongBody;
+} | {
+  type: "chat";
+  body: GameChatBody;
+} | {
+  type: "join";
+  body: JoinBody;
+} | {
+  type: "leave";
+  body: LeaveBody;
+} | {
+  type: "death";
+  body: DeathBody;
+} | {
+  type: "status";
+  body: StatusBody;
+} | {
+  type: "bindings_updated";
+  body: BindingsUpdatedBody;
+} | {
+  type: "command_result";
+  id: string;
+  body: CommandResultBody;
+} | {
+  type: "query_result";
+  id: string;
+  body: QueryResultBody;
+};
+/** 连接终止原因（onEnded 只在永久停止时触发一次；用户 stop() 不触发）。 */
+interface ConnectionEndedReason {
+  /** true = 不可恢复（版本不符 / token 错 / hello_ack 拒绝）。 */
+  permanent: boolean;
+  /** WS close code（可得时）。 */
+  code?: number;
+  /** 人读描述。 */
+  detail: string;
+}
+/** hello body（protocolVersion 固定 0.3.1；peerId/platform/version/client 由适配器解析）。 */
+interface KurobotHello {
+  peerId: string;
+  platform: string;
+  version: string;
+  protocolVersion: string;
+  token?: string;
+  client?: string;
+}
+/** 连接层参数（重连节奏等可注入测试快值；生产用缺省）。 */
+interface KurobotConnectionOptions {
+  /** KuroBot 服务端完整地址（ws:// / wss://）。 */
+  url: string;
+  hello: KurobotHello;
+  /** 应用层心跳间隔毫秒（须显著小于服务端 30s 空闲阈值；0 = 关闭）。 */
+  pingIntervalMs: number;
+  /** 建立（hello → ack）超时毫秒。 */
+  helloTimeoutMs: number;
+  /** 重连退避基数毫秒（指数 2^attempt）。 */
+  retryBaseDelayMs: number;
+  /** 重连退避上限毫秒。 */
+  retryMaxDelayMs: number;
+  /** 握手成功（ack ok，含绑定快照）。 */
+  onEstablished: (ack: HelloAckOkBody) => void;
+  /** 服务端业务帧（hello_ack 内部消费不回调；pong 透传由消费方忽略）。 */
+  onFrame: (msg: ServerEventMessage) => void;
+  /** 连接永久停止（1002/1008/hello_ack 拒绝）；用户 stop() 不触发。 */
+  onEnded: (reason: ConnectionEndedReason) => void;
+  /** 日志（缺省静默）。 */
+  logger?: KurobotLogger;
+}
+/** kurobridge-ws 客户端连接（子协议 + hello + 应用层 ping + 感知 close code 的指数退避）。 */
+declare class KurobotConnection {
+  private readonly opts;
+  private readonly log;
+  private state;
+  private ws;
+  /** 用户主动 stop（其后一切 close 都不再重连、不上报 onEnded）。 */
+  private userStopped;
+  /** 已判定永久拒绝（版本/token），不再重连。 */
+  private rejected;
+  private pendingHelloId;
+  private helloTimer;
+  private pingTimer;
+  private retryTimer;
+  /** 连续失败计数（established 成功后清零）。 */
+  private attempt;
+  constructor(opts: KurobotConnectionOptions);
+  /** 当前是否已建立（ack ok）。 */
+  isEstablished(): boolean;
+  /** 启动：发起首次连接（异步，结果经回调上报；重复调用幂等）。 */
+  start(): void;
+  /** 停止：关闭连接、清定时器、不再重连（幂等；不触发 onEnded）。 */
+  stop(): void;
+  /** 发送出站帧（chat/command/query 等扁平消息）；未 established 丢弃 + debug。 */
+  send(message: {
+    type: string;
+    body: unknown;
+    id?: string;
+  }): boolean;
+  /** 发起一次连接。 */
+  private connect;
+  /** 连接建立：立即发 hello（每次连接都重发——服务端按连接会话握手）。 */
+  private onOpen;
+  /** 收到文本帧：两段式解析（wire 取 type → 分发具体 schema）+ 未知帧容忍。 */
+  private onText;
+  /** 已知 type 的具体 schema 校验（未知 type 走容忍；body 非法 warn 丢弃）。 */
+  private parseServerFrame;
+  /** 未知帧容忍（对齐 ADR-026 服务端策略）：事件帧忽略；请求帧回 `<type>_result` 失败回执；`_result` 结尾不回执（防乒乓）。 */
+  private handleUnknownFrame;
+  /** hello_ack 处理：ok → 建立；ok:false → 永久停止（版本/鉴权问题不可自愈）。 */
+  private handleHelloAck;
+  /** 应用层心跳：每 pingIntervalMs 发 ping 帧（服务端任何入帧重置 30s 空闲计时）。 */
+  private startPing;
+  private stopPing;
+  private clearTimers;
+  /** 永久拒绝：关闭连接，不再重连，上报 onEnded。 */
+  private reject;
+  /** close：区分用户停止 / 永久拒绝（1002/1008）/ 可重连断开。 */
+  private onClose;
+  /** 指数退避重连：base * 2^attempt 封顶 retryMaxDelayMs；established 成功清零。 */
+  private scheduleRetry;
+}
+//#endregion
+//#region src/kurobot/adapter.d.ts
+/** 发群消息最小面（kernel MsgApi.sendMessage 的结构子集，便于测试桩替换）。 */
+interface KurobotMsgApi {
+  sendMessage(target: Peer, elements: CanonicalElement[]): Promise<{
+    msgId: string;
+  }>;
+}
+/** 适配器构造参数。 */
+interface KurobotAdapterOptions {
+  /** 协议配置（zod 校验 + seed 装配）。 */
+  config: ProtocolConfig<KurobotConfig>;
+  /** kernel 消息事件通道（QQ 消息收链路入口）。 */
+  msgChannel: MsgEventChannel;
+  /** kernel 消息 API（MC → QQ 群文本发送）。 */
+  msgApi: KurobotMsgApi;
+  /** 当前登录账号（自消息过滤 + hello peerId）。 */
+  self: {
+    uin: string;
+    nickname: string;
+  };
+  /** 日志（缺省静默）。 */
+  logger?: KurobotLoggerAlias;
+}
+/** 适配器日志面（复用连接层最小面）。 */
+type KurobotLoggerAlias = KurobotConnectionOptions["logger"];
+/** kurobot 协议适配器。 */
+declare class NapukettoKurobotAdapter extends BaseProtocolAdapter<KurobotConfig> {
+  readonly protocol = "kurobot";
+  private readonly msgChannel;
+  private readonly msgApi;
+  private readonly selfUin;
+  private readonly log;
+  private connection;
+  private unsubscribe;
+  /** 当前生效配置（收链路取 commandPrefix 等；onStart/onReload 刷新）。 */
+  private currentConfig;
+  /** 出站绑定集（hello_ack 快照 + bindings_updated 全量替换；空集 = 全部不发）。 */
+  private bindings;
+  /** command 请求 UUID → 回发群号（command_result 帧无 channel，靠 id 关联）。 */
+  private pendingCommands;
+  /** query 请求 UUID → 查询类别。 */
+  private pendingQueries;
+  /** 最近一帧 status 快照（仅缓存不发群，M-04 决策同构）。 */
+  private lastStatus;
+  constructor(opts: KurobotAdapterOptions);
+  /** 最近一帧 status 快照（仅缓存；无帧时 null）。 */
+  getLastStatus(): StatusBody | null;
+  /** 连接是否已建立（hello_ack ok 后为 true）。 */
+  isConnected(): boolean;
+  /** 发起 query 请求（status/bindings）。MVP 未接 QQ 触发面——预留能力（见 design.md §8）。 */
+  query(kind: "status" | "bindings"): boolean;
+  /** 启动：建连接（异步握手，日志可见）+ 订阅 kernel 消息。 */
+  private startKurobot;
+  /** 配置热更新：停旧连接/退订 → 按新配置重建（对齐 satori reloadTransports）。 */
+  private reloadKurobot;
+  /** 停止：退订 + 关连接 + 清 pending 表。 */
+  private stopAll;
+  /** 握手成功：绑定集整体替换为服务端快照 + 清上一连接的 pending 表。 */
+  private onEstablished;
+  /** 连接永久停止（1002/1008/hello_ack 拒绝）：清 pending（绑定集留给下次握手覆盖）。 */
+  private onEnded;
+  /** 服务端帧分发（渲染回群 / 缓存 / 绑定集维护 / 命令结果关联回发）。 */
+  private onServerFrame;
+  /** query_result 处理：bindings 刷新绑定集（防御性收窄）；status 缓存。 */
+  private onQueryResult;
+  /** kernel 群消息 → kurobot 出站（仅群聊 + 自消息过滤 + 命令分流 + 绑定过滤）。 */
+  private handleIncomingMessage;
+  /** 发 chat 事件帧（无 id）。 */
+  private sendChat;
+  /** 发 command 请求帧（登记 pending 表供 command_result 关联）。 */
+  private sendCommand;
+  /** 群文本发送（失败 error 日志不抛出——不影响连接与收链路）。 */
+  private sendToGroup;
+  /** 当前生效配置（收链路保证已 start）。 */
+  private requireConfig;
+  /** 订阅 kernel 消息事件（幂等）。 */
+  private subscribe;
+  /** 退订（幂等）。 */
+  private unsubscribeAll;
+}
+//#endregion
+//#region src/kurobot/translate.d.ts
+/** 发往 QQ 文本的总长上限（超出截断追加 …(截断)；任务书对 command_result 规定，统一套用）。 */
+declare const MAX_GROUP_TEXT_LENGTH = 1500;
+/** 超长截断（按 UTF-16 码元计，超限部分丢弃）。 */
+declare function truncateForGroup(text: string): string;
+/** QQ 群消息发送者显示名：sendMemberName ?? sendNickName（双空兜底 senderUin，schema min(1)）。 */
+declare function resolveSenderName(msg: RawMessage): string;
+/** canonical 元素序列 → 降级文本（text 原文、@、图片/表情/回复占位；空白返回 null = 不发）。 */
+declare function degradeElements(elements: CanonicalElement[]): string | null;
+/** RawMessage → 降级文本（便捷封装；null = 空消息不发）。 */
+declare function degradeMessage(msg: RawMessage): string | null;
+/** 渲染模板变量（player 必有；content = 聊天内容；message = 死亡消息）。 */
+interface TemplateVars {
+  player: string;
+  content?: string;
+  message?: string;
+}
+/** 渲染模板：替换 {player}/{content}/{message} 占位符（未知占位符原样保留）。 */
+declare function renderTemplate(template: string, vars: TemplateVars): string;
+/** death 事件 → 群文本（message 空串时以「死亡了」代入：Bukkit deathMessage null 兜底）。 */
+declare function renderDeathText(template: string, player: string, message: string): string;
+/** command_result body → 群文本（ok 合并 output；error → 命令失败：{error}）。 */
+declare function renderCommandResult(body: CommandResultBody): string;
+//#endregion
+export { type BindingsUpdatedBody, type CommandBody, type CommandFrame, type CommandResultBody, type ConnectionEndedReason, type DeathBody, type GameChatBody, type HelloAckBody, type HelloBody, type JoinBody, type KurobotAdapterOptions, type KurobotConfig, KurobotConnection, type KurobotConnectionOptions, type KurobotHello, type KurobotLogger, type KurobotMsgApi, type LeaveBody, MAX_GROUP_TEXT_LENGTH, NapukettoKurobotAdapter, PROTOCOL_NAME, PROTOCOL_VERSION, type PlatformChatBody, type QueryResultBody, type ServerEventMessage, type StatusBody, WS_SUBPROTOCOL, bindingsUpdatedFrame, commandFrame, commandResultFrame, deathFrame, degradeElements, degradeMessage, encodeFrame, gameChatFrame, helloAckFrame, helloFrame, isProtocolVersionCompatible, joinFrame, kurobotConfigDefaults, kurobotConfigSchema, leaveFrame, pingFrame, platformChatFrame, pongFrame, queryFrame, queryResultFrame, renderCommandResult, renderDeathText, renderTemplate, resolveSenderName, statusFrame, truncateForGroup, wireFrameSchema };
+//# sourceMappingURL=index.d.mts.map