cortico-world-astrbot 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.0.2
+
+- 桥的 `error` 事件只认现役 socket：重启时旧连接迟到的错误不再被当成新连接的错误记一条。
+- `start()` 先撤掉挂起的重连定时器。之前退避等待期间重新连接，会同时留下两条 socket（桥会把旧的踢掉，但会多一次握手）。
+
 ## 1.0.1
 
 - 加上扩展图标（`cortico.icon`），首发时市场卡片是空白的。

package/README.md

@@ -4,7 +4,7 @@
 
 让 Cortico 的人格 Bot 进 QQ 群说话，同时把 QQ 账号与插件能力留在 AstrBot 手里。
 
-**当前版本：1.0.1**（更新内容见 [CHANGELOG.md](CHANGELOG.md)）
+**当前版本：1.0.2**（更新内容见 [CHANGELOG.md](CHANGELOG.md)）
 
 项目地址：[as124da1231/cortico-world-astrbot](https://github.com/as124da1231/cortico-world-astrbot)。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortico-world-astrbot",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "type": "module",
   "description": "Cortico World: join QQ conversations through an AstrBot bridge, so the bot keeps AstrBot's plugins while a Cortico persona drives the talking",
   "license": "MIT",

package/src/driver.ts

@@ -1,458 +1,466 @@
-/**
- * AstrbotBridgeDriver —— 薄连接层。
- *
- * 本 World 作 WS **客户端**连 AstrBot 侧的桥。选这个方向是因为服务器有公网地址、
- * 本机没有：让能被动接受连接的一方当服务端，就不必在内网穿透上再搭一层。
- *
- * 这一层不做语义判断：收到什么形状就交给 World，发送失败一律返回结果对象而不抛。
- * 断线按指数退避重连，重连期间 stop() 能干净退出。
- */
-import WebSocket from 'ws';
-import type { Logger } from 'cortico/core/types.ts';
-import { nullLogger } from 'cortico/core/util.ts';
-
-/** 会话种类：群聊或私聊。 */
-export type ConvKind = 'group' | 'private';
-
-/** 会话标识；id 用字符串，群号/QQ 号由桥给什么就存什么。 */
-export interface Conv {
-  kind: ConvKind;
-  id: string;
-  /** 群名或对方昵称，仅用于展示。 */
-  name?: string;
-}
-
-/** 桥推进来的一条消息。字段保持扁平，语义由 World 解释。 */
-export interface BridgeMessage {
-  /** 桥侧的消息唯一标识，用于引用回复与去重。 */
-  id: string;
-  /** ISO 8601；缺失时由 World 补当前时间。 */
-  ts?: string;
-  conv: Conv;
-  sender?: { id?: string; name?: string };
-  text: string;
-  /** 这条消息是否点了名（@ 或叫到称呼）。由桥判断并如实告知。 */
-  mentioned?: boolean;
-  /** 桥允许这条消息的发送者要截图；没有这个字段一律当作不允许。 */
-  canScreenshot?: boolean;
-  /** 说话人在 AstrBot 那边是不是管理员（= Cortico 的主人）。 */
-  role?: 'admin' | 'member';
-  /** 随消息一起来的图片；只有本端自报能读图时桥才会带。 */
-  images?: Array<{ mime: string; base64: string }>;
-  /** 通知类（撤回/入群/戳一戳），不是人说的话，只当上下文。 */
-  notice?: boolean;
-  /** 撤回通知指向的消息号。 */
-  ref?: string;
-}
-
-/** 桥的状态通知，例如 QQ 侧掉线、桥重启。 */
-export interface BridgeNotice {
-  /** 稳定的通知种类，可缺省。 */
-  kind?: string;
-  text: string;
-  ts?: string;
-}
-
-export interface SendResult {
-  ok: boolean;
-  /** ok 为 false 时的原因，可直接进工具回执。 */
-  error?: string;
-}
-
-/** 随消息一起发出的图片。桥按 base64 转给 AstrBot 的消息链。 */
-export interface OutgoingImage {
-  mime: string;
-  /** 不带 data: 前缀的 base64。 */
-  base64: string;
-}
-
-/**
- * World 依赖的连接层形状。抽成接口是为了让测试塞假驱动进来，
- * 不必为了测 World 的投递逻辑去开真的 WebSocket。
- */
-export interface BridgeDriver {
-  readonly connected: boolean;
-  readonly self?: { id?: string; name?: string };
-  /** 桥报来的管理员 QQ 号；空数组表示还没收到。 */
-  readonly ownerIds: string[];
-  onMessage(cb: (m: BridgeMessage) => void): void;
-  onNotice(cb: (n: BridgeNotice) => void): void;
-  onState(cb: (connected: boolean) => void): void;
-  start(): Promise<void>;
-  stop(): Promise<void>;
-  send(conv: Conv, text: string, replyTo?: string, image?: OutgoingImage): Promise<SendResult>;
-}
-
-export interface BridgeDriverOptions {
-  wsUrl: string;
-  token?: string;
-  /** 握手时自报的能力；桥据此决定要不要把图片传过来。 */
-  capabilities?: Record<string, boolean>;
-  /** 重连等待起点。 */
-  reconnectBaseMs?: number;
-  /** 重连等待封顶。 */
-  reconnectMaxMs?: number;
-  /** 一次发送等确认的超时。 */
-  sendTimeoutMs?: number;
-  log?: Logger;
-}
-
-interface PendingSend {
-  resolve: (r: SendResult) => void;
-  timer: ReturnType<typeof setTimeout>;
-}
-
-/** 发送确认的默认超时。 */
-export const DEFAULT_SEND_TIMEOUT_MS = 15_000;
-
-export class AstrbotBridgeDriver implements BridgeDriver {
-  private readonly opts: BridgeDriverOptions;
-  private readonly log: Logger;
-  private ws?: WebSocket;
-  private stopped = true;
-  private backoffMs: number;
-  private reconnectTimer?: ReturnType<typeof setTimeout>;
-  private ridSeq = 0;
-  private pending = new Map<string, PendingSend>();
-  private messageCbs: Array<(m: BridgeMessage) => void> = [];
-  private noticeCbs: Array<(n: BridgeNotice) => void> = [];
-  private stateCbs: Array<(connected: boolean) => void> = [];
-
-  /** 最近一次 ready 帧里桥自报的身份。 */
-  self?: { id?: string; name?: string };
-  /** 桥报来的管理员 QQ 号：QQ 上这些人是主人本人。 */
-  ownerIds: string[] = [];
-
-  connected = false;
-
-  constructor(opts: BridgeDriverOptions) {
-    this.opts = opts;
-    this.log = opts.log ?? nullLogger();
-    this.backoffMs = opts.reconnectBaseMs ?? 1000;
-  }
-
-  onMessage(cb: (m: BridgeMessage) => void): void {
-    this.messageCbs.push(cb);
-  }
-
-  onNotice(cb: (n: BridgeNotice) => void): void {
-    this.noticeCbs.push(cb);
-  }
-
-  onState(cb: (connected: boolean) => void): void {
-    this.stateCbs.push(cb);
-  }
-
-  /**
-   * 开始连接。首次尝试结束（连上或失败）后 resolve；
-   * 失败时后台继续按退避重连，**不 reject** —— 装配层不该因为桥没开而挂掉。
-   */
-  start(): Promise<void> {
-    if (!this.opts.wsUrl) {
-      this.log.info('未配置桥地址，保持未连接');
-      return Promise.resolve();
-    }
-    this.stopped = false;
-    this.backoffMs = this.opts.reconnectBaseMs ?? 1000;
-    return new Promise((resolve) => {
-      this.connectAttempt(resolve);
-    });
-  }
-
-  async stop(): Promise<void> {
-    this.stopped = true;
-    if (this.reconnectTimer) {
-      clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = undefined;
-    }
-    this.rejectAllPending('驱动已停止');
-    const ws = this.ws;
-    this.ws = undefined;
-    const was = this.connected;
-    this.connected = false;
-    if (ws) ws.terminate();
-    if (was) this.emitState(false);
-  }
-
-  /**
-   * 发一条消息给指定会话。未连接、超时或被桥拒绝都返回 { ok:false }，
-   * 由 World 把它写成失败回执，不抛错。
-   */
-  send(conv: Conv, text: string, replyTo?: string, image?: OutgoingImage): Promise<SendResult> {
-    return new Promise((resolve) => {
-      const ws = this.ws;
-      if (!ws || ws.readyState !== WebSocket.OPEN) {
-        resolve({ ok: false, error: '与 AstrBot 桥的连接未建立' });
-        return;
-      }
-      const rid = `a-${++this.ridSeq}`;
-      // 带图的帧更大，给桥多一点时间。
-      const timeout = (this.opts.sendTimeoutMs ?? DEFAULT_SEND_TIMEOUT_MS) + (image ? 15_000 : 0);
-      const timer = setTimeout(() => {
-        this.pending.delete(rid);
-        resolve({ ok: false, error: `桥没有在 ${timeout}ms 内确认` });
-      }, timeout);
-      this.pending.set(rid, { resolve, timer });
-      const frame: Record<string, unknown> = {
-        t: 'send',
-        rid,
-        conv: { kind: conv.kind, id: conv.id },
-        text,
-      };
-      if (replyTo) frame.replyTo = replyTo;
-      if (image) frame.image = { mime: image.mime, base64: image.base64 };
-      try {
-        ws.send(JSON.stringify(frame));
-      } catch (err) {
-        clearTimeout(timer);
-        this.pending.delete(rid);
-        resolve({ ok: false, error: err instanceof Error ? err.message : String(err) });
-      }
-    });
-  }
-
-  private connectAttempt(onSettled?: () => void): void {
-    if (this.stopped) {
-      onSettled?.();
-      return;
-    }
-    let settled = false;
-    const settle = (): void => {
-      if (!settled) {
-        settled = true;
-        onSettled?.();
-      }
-    };
-
-    const token = this.opts.token;
-    let ws: WebSocket;
-    try {
-      ws = new WebSocket(this.opts.wsUrl, {
-        headers: token ? { Authorization: `Bearer ${token}` } : undefined,
-      });
-    } catch (err) {
-      this.log.warn('桥地址无法解析', {
-        wsUrl: this.opts.wsUrl,
-        error: err instanceof Error ? err.message : String(err),
-      });
-      settle();
-      this.scheduleReconnect();
-      return;
-    }
-    this.ws = ws;
-
-    ws.on('open', () => {
-      if (this.stopped || this.ws !== ws) {
-        ws.terminate();
-        settle();
-        return;
-      }
-      this.connected = true;
-      this.backoffMs = this.opts.reconnectBaseMs ?? 1000;
-      this.log.info('已连上 AstrBot 桥', { wsUrl: this.opts.wsUrl });
-      try {
-        // 握手帧：带上 token 与自己的显示名，桥据此认人。
-        ws.send(
-          JSON.stringify({
-            t: 'hello',
-            v: 1,
-            token: token ?? '',
-            name: 'Cortico',
-            capabilities: this.opts.capabilities ?? {},
-          }),
-        );
-      } catch (err) {
-        this.log.warn('握手帧发送失败', {
-          error: err instanceof Error ? err.message : String(err),
-        });
-      }
-      this.emitState(true);
-      settle();
-    });
-
-    ws.on('message', (data) => {
-      if (!this.stopped && this.ws === ws) this.handleFrame(String(data));
-    });
-
-    ws.on('error', (err) => {
-      this.log.warn('桥连接错误', { error: err.message });
-    });
-
-    ws.on('close', () => {
-      const isCurrent = this.ws === ws;
-      const wasConnected = this.connected;
-      if (isCurrent) {
-        this.ws = undefined;
-        this.connected = false;
-        this.rejectAllPending('与桥的连接已断开');
-        if (wasConnected) this.log.info('与 AstrBot 桥的连接已断开');
-      }
-      settle();
-      if (isCurrent && !this.stopped) {
-        if (wasConnected) this.emitState(false);
-        this.scheduleReconnect();
-      }
-    });
-  }
-
-  private scheduleReconnect(): void {
-    if (this.reconnectTimer || this.stopped) return;
-    const delay = this.backoffMs;
-    this.backoffMs = Math.min(this.backoffMs * 2, this.opts.reconnectMaxMs ?? 30_000);
-    this.log.debug(`${delay}ms 后重连桥`);
-    this.reconnectTimer = setTimeout(() => {
-      this.reconnectTimer = undefined;
-      if (!this.stopped) this.connectAttempt();
-    }, delay);
-  }
-
-  private handleFrame(raw: string): void {
-    let frame: Record<string, unknown>;
-    try {
-      frame = JSON.parse(raw) as Record<string, unknown>;
-    } catch {
-      this.log.warn('收到无法解析的帧，已忽略');
-      return;
-    }
-
-    const t = typeof frame.t === 'string' ? frame.t : '';
-
-    if (t === 'ack') {
-      const rid = String(frame.rid ?? '');
-      const call = this.pending.get(rid);
-      if (!call) return;
-      this.pending.delete(rid);
-      clearTimeout(call.timer);
-      const ok = frame.ok === true;
-      call.resolve(
-        ok ? { ok: true } : { ok: false, error: String(frame.error ?? '桥拒绝发送') },
-      );
-      return;
-    }
-
-    if (t === 'ready') {
-      const self = frame.self as { id?: unknown; name?: unknown } | undefined;
-      this.self = {
-        id: self?.id === undefined ? undefined : String(self.id),
-        name: self?.name === undefined ? undefined : String(self.name),
-      };
-      const admins = frame.admins;
-      this.ownerIds = Array.isArray(admins)
-        ? admins.map((v) => String(v).trim()).filter((v) => v !== '')
-        : [];
-      this.log.info('桥已就绪', { self: this.self, owners: this.ownerIds.length });
-      return;
-    }
-
-    if (t === 'msg') {
-      const msg = parseMessage(frame);
-      if (!msg) {
-        this.log.warn('消息帧形状不符，已忽略');
-        return;
-      }
-      for (const cb of [...this.messageCbs]) {
-        try {
-          cb(msg);
-        } catch (err) {
-          this.log.error('消息回调抛错', {
-            error: err instanceof Error ? err.message : String(err),
-          });
-        }
-      }
-      return;
-    }
-
-    if (t === 'notice') {
-      const notice: BridgeNotice = {
-        kind: typeof frame.kind === 'string' ? frame.kind : undefined,
-        text: typeof frame.text === 'string' ? frame.text : '',
-        ts: typeof frame.ts === 'string' ? frame.ts : undefined,
-      };
-      if (!notice.text) return;
-      for (const cb of [...this.noticeCbs]) {
-        try {
-          cb(notice);
-        } catch (err) {
-          this.log.error('通知回调抛错', {
-            error: err instanceof Error ? err.message : String(err),
-          });
-        }
-      }
-      return;
-    }
-
-    this.log.debug('未知帧类型，已忽略', { t });
-  }
-
-  private emitState(connected: boolean): void {
-    for (const cb of [...this.stateCbs]) {
-      try {
-        cb(connected);
-      } catch (err) {
-        this.log.error('状态回调抛错', {
-          error: err instanceof Error ? err.message : String(err),
-        });
-      }
-    }
-  }
-
-  private rejectAllPending(reason: string): void {
-    for (const call of this.pending.values()) {
-      clearTimeout(call.timer);
-      call.resolve({ ok: false, error: reason });
-    }
-    this.pending.clear();
-  }
-}
-
-/** 把一帧 `msg` 收敛成 BridgeMessage；形状不对时返回 null。 */
-export function parseMessage(frame: Record<string, unknown>): BridgeMessage | null {
-  const convRaw = frame.conv as Record<string, unknown> | undefined;
-  if (!convRaw) return null;
-  const kind = convRaw.kind === 'private' ? 'private' : convRaw.kind === 'group' ? 'group' : null;
-  if (!kind) return null;
-  const id = convRaw.id === undefined || convRaw.id === null ? '' : String(convRaw.id);
-  if (!id) return null;
-
-  const text = typeof frame.text === 'string' ? frame.text : '';
-  const senderRaw = frame.sender as Record<string, unknown> | undefined;
-
-  return {
-    id: frame.id === undefined ? '' : String(frame.id),
-    ts: typeof frame.ts === 'string' ? frame.ts : undefined,
-    conv: {
-      kind,
-      id,
-      name: typeof convRaw.name === 'string' ? convRaw.name : undefined,
-    },
-    sender: senderRaw
-      ? {
-          id: senderRaw.id === undefined ? undefined : String(senderRaw.id),
-          name: typeof senderRaw.name === 'string' ? senderRaw.name : undefined,
-        }
-      : undefined,
-    text,
-    mentioned: frame.mentioned === true,
-    canScreenshot: (frame.can as Record<string, unknown> | undefined)?.screenshot === true,
-    role: frame.role === 'admin' ? 'admin' : 'member',
-    images: parseImages(frame.images),
-    notice: frame.kind === 'notice',
-    ref: typeof frame.ref === 'string' && frame.ref !== '' ? frame.ref : undefined,
-  };
-}
-
-/** 帧里的图片数组；形状不对的项直接丢掉。 */
-function parseImages(raw: unknown): Array<{ mime: string; base64: string }> | undefined {
-  if (!Array.isArray(raw)) return undefined;
-  const out: Array<{ mime: string; base64: string }> = [];
-  for (const item of raw) {
-    if (!item || typeof item !== 'object') continue;
-    const rec = item as Record<string, unknown>;
-    const mime = typeof rec.mime === 'string' ? rec.mime : '';
-    const base64 = typeof rec.base64 === 'string' ? rec.base64 : '';
-    if (!base64 || !mime.startsWith('image/')) continue;
-    out.push({ mime, base64 });
-    if (out.length >= 4) break;
-  }
-  return out.length > 0 ? out : undefined;
-}
+/**
+ * AstrbotBridgeDriver —— 薄连接层。
+ *
+ * 本 World 作 WS **客户端**连 AstrBot 侧的桥。选这个方向是因为服务器有公网地址、
+ * 本机没有：让能被动接受连接的一方当服务端，就不必在内网穿透上再搭一层。
+ *
+ * 这一层不做语义判断：收到什么形状就交给 World，发送失败一律返回结果对象而不抛。
+ * 断线按指数退避重连，重连期间 stop() 能干净退出。
+ */
+import WebSocket from 'ws';
+import type { Logger } from 'cortico/core/types.ts';
+import { nullLogger } from 'cortico/core/util.ts';
+
+/** 会话种类：群聊或私聊。 */
+export type ConvKind = 'group' | 'private';
+
+/** 会话标识；id 用字符串，群号/QQ 号由桥给什么就存什么。 */
+export interface Conv {
+  kind: ConvKind;
+  id: string;
+  /** 群名或对方昵称，仅用于展示。 */
+  name?: string;
+}
+
+/** 桥推进来的一条消息。字段保持扁平，语义由 World 解释。 */
+export interface BridgeMessage {
+  /** 桥侧的消息唯一标识，用于引用回复与去重。 */
+  id: string;
+  /** ISO 8601；缺失时由 World 补当前时间。 */
+  ts?: string;
+  conv: Conv;
+  sender?: { id?: string; name?: string };
+  text: string;
+  /** 这条消息是否点了名（@ 或叫到称呼）。由桥判断并如实告知。 */
+  mentioned?: boolean;
+  /** 桥允许这条消息的发送者要截图；没有这个字段一律当作不允许。 */
+  canScreenshot?: boolean;
+  /** 说话人在 AstrBot 那边是不是管理员（= Cortico 的主人）。 */
+  role?: 'admin' | 'member';
+  /** 随消息一起来的图片；只有本端自报能读图时桥才会带。 */
+  images?: Array<{ mime: string; base64: string }>;
+  /** 通知类（撤回/入群/戳一戳），不是人说的话，只当上下文。 */
+  notice?: boolean;
+  /** 撤回通知指向的消息号。 */
+  ref?: string;
+}
+
+/** 桥的状态通知，例如 QQ 侧掉线、桥重启。 */
+export interface BridgeNotice {
+  /** 稳定的通知种类，可缺省。 */
+  kind?: string;
+  text: string;
+  ts?: string;
+}
+
+export interface SendResult {
+  ok: boolean;
+  /** ok 为 false 时的原因，可直接进工具回执。 */
+  error?: string;
+}
+
+/** 随消息一起发出的图片。桥按 base64 转给 AstrBot 的消息链。 */
+export interface OutgoingImage {
+  mime: string;
+  /** 不带 data: 前缀的 base64。 */
+  base64: string;
+}
+
+/**
+ * World 依赖的连接层形状。抽成接口是为了让测试塞假驱动进来，
+ * 不必为了测 World 的投递逻辑去开真的 WebSocket。
+ */
+export interface BridgeDriver {
+  readonly connected: boolean;
+  readonly self?: { id?: string; name?: string };
+  /** 桥报来的管理员 QQ 号；空数组表示还没收到。 */
+  readonly ownerIds: string[];
+  onMessage(cb: (m: BridgeMessage) => void): void;
+  onNotice(cb: (n: BridgeNotice) => void): void;
+  onState(cb: (connected: boolean) => void): void;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  send(conv: Conv, text: string, replyTo?: string, image?: OutgoingImage): Promise<SendResult>;
+}
+
+export interface BridgeDriverOptions {
+  wsUrl: string;
+  token?: string;
+  /** 握手时自报的能力；桥据此决定要不要把图片传过来。 */
+  capabilities?: Record<string, boolean>;
+  /** 重连等待起点。 */
+  reconnectBaseMs?: number;
+  /** 重连等待封顶。 */
+  reconnectMaxMs?: number;
+  /** 一次发送等确认的超时。 */
+  sendTimeoutMs?: number;
+  log?: Logger;
+}
+
+interface PendingSend {
+  resolve: (r: SendResult) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+/** 发送确认的默认超时。 */
+export const DEFAULT_SEND_TIMEOUT_MS = 15_000;
+
+export class AstrbotBridgeDriver implements BridgeDriver {
+  private readonly opts: BridgeDriverOptions;
+  private readonly log: Logger;
+  private ws?: WebSocket;
+  private stopped = true;
+  private backoffMs: number;
+  private reconnectTimer?: ReturnType<typeof setTimeout>;
+  private ridSeq = 0;
+  private pending = new Map<string, PendingSend>();
+  private messageCbs: Array<(m: BridgeMessage) => void> = [];
+  private noticeCbs: Array<(n: BridgeNotice) => void> = [];
+  private stateCbs: Array<(connected: boolean) => void> = [];
+
+  /** 最近一次 ready 帧里桥自报的身份。 */
+  self?: { id?: string; name?: string };
+  /** 桥报来的管理员 QQ 号：QQ 上这些人是主人本人。 */
+  ownerIds: string[] = [];
+
+  connected = false;
+
+  constructor(opts: BridgeDriverOptions) {
+    this.opts = opts;
+    this.log = opts.log ?? nullLogger();
+    this.backoffMs = opts.reconnectBaseMs ?? 1000;
+  }
+
+  onMessage(cb: (m: BridgeMessage) => void): void {
+    this.messageCbs.push(cb);
+  }
+
+  onNotice(cb: (n: BridgeNotice) => void): void {
+    this.noticeCbs.push(cb);
+  }
+
+  onState(cb: (connected: boolean) => void): void {
+    this.stateCbs.push(cb);
+  }
+
+  /**
+   * 开始连接。首次尝试结束（连上或失败）后 resolve；
+   * 失败时后台继续按退避重连，**不 reject** —— 装配层不该因为桥没开而挂掉。
+   */
+  start(): Promise<void> {
+    if (!this.opts.wsUrl) {
+      this.log.info('未配置桥地址，保持未连接');
+      return Promise.resolve();
+    }
+    this.stopped = false;
+    this.backoffMs = this.opts.reconnectBaseMs ?? 1000;
+    // 上一次的退避还挂着时重新 start，必须先把定时器撤掉：
+    // 否则这次手动连接和定时器各建一条 socket，桥那边会看到两次握手。
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = undefined;
+    }
+    return new Promise((resolve) => {
+      this.connectAttempt(resolve);
+    });
+  }
+
+  async stop(): Promise<void> {
+    this.stopped = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = undefined;
+    }
+    this.rejectAllPending('驱动已停止');
+    const ws = this.ws;
+    this.ws = undefined;
+    const was = this.connected;
+    this.connected = false;
+    if (ws) ws.terminate();
+    if (was) this.emitState(false);
+  }
+
+  /**
+   * 发一条消息给指定会话。未连接、超时或被桥拒绝都返回 { ok:false }，
+   * 由 World 把它写成失败回执，不抛错。
+   */
+  send(conv: Conv, text: string, replyTo?: string, image?: OutgoingImage): Promise<SendResult> {
+    return new Promise((resolve) => {
+      const ws = this.ws;
+      if (!ws || ws.readyState !== WebSocket.OPEN) {
+        resolve({ ok: false, error: '与 AstrBot 桥的连接未建立' });
+        return;
+      }
+      const rid = `a-${++this.ridSeq}`;
+      // 带图的帧更大，给桥多一点时间。
+      const timeout = (this.opts.sendTimeoutMs ?? DEFAULT_SEND_TIMEOUT_MS) + (image ? 15_000 : 0);
+      const timer = setTimeout(() => {
+        this.pending.delete(rid);
+        resolve({ ok: false, error: `桥没有在 ${timeout}ms 内确认` });
+      }, timeout);
+      this.pending.set(rid, { resolve, timer });
+      const frame: Record<string, unknown> = {
+        t: 'send',
+        rid,
+        conv: { kind: conv.kind, id: conv.id },
+        text,
+      };
+      if (replyTo) frame.replyTo = replyTo;
+      if (image) frame.image = { mime: image.mime, base64: image.base64 };
+      try {
+        ws.send(JSON.stringify(frame));
+      } catch (err) {
+        clearTimeout(timer);
+        this.pending.delete(rid);
+        resolve({ ok: false, error: err instanceof Error ? err.message : String(err) });
+      }
+    });
+  }
+
+  private connectAttempt(onSettled?: () => void): void {
+    if (this.stopped) {
+      onSettled?.();
+      return;
+    }
+    let settled = false;
+    const settle = (): void => {
+      if (!settled) {
+        settled = true;
+        onSettled?.();
+      }
+    };
+
+    const token = this.opts.token;
+    let ws: WebSocket;
+    try {
+      ws = new WebSocket(this.opts.wsUrl, {
+        headers: token ? { Authorization: `Bearer ${token}` } : undefined,
+      });
+    } catch (err) {
+      this.log.warn('桥地址无法解析', {
+        wsUrl: this.opts.wsUrl,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      settle();
+      this.scheduleReconnect();
+      return;
+    }
+    this.ws = ws;
+
+    ws.on('open', () => {
+      if (this.stopped || this.ws !== ws) {
+        ws.terminate();
+        settle();
+        return;
+      }
+      this.connected = true;
+      this.backoffMs = this.opts.reconnectBaseMs ?? 1000;
+      this.log.info('已连上 AstrBot 桥', { wsUrl: this.opts.wsUrl });
+      try {
+        // 握手帧：带上 token 与自己的显示名，桥据此认人。
+        ws.send(
+          JSON.stringify({
+            t: 'hello',
+            v: 1,
+            token: token ?? '',
+            name: 'Cortico',
+            capabilities: this.opts.capabilities ?? {},
+          }),
+        );
+      } catch (err) {
+        this.log.warn('握手帧发送失败', {
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+      this.emitState(true);
+      settle();
+    });
+
+    ws.on('message', (data) => {
+      if (!this.stopped && this.ws === ws) this.handleFrame(String(data));
+    });
+
+    ws.on('error', (err) => {
+      // 旧 socket 在关闭前还会补一条 error；那不是现在的连接状态，别记成新错误。
+      if (this.stopped || this.ws !== ws) return;
+      this.log.warn('桥连接错误', { error: err.message });
+    });
+
+    ws.on('close', () => {
+      const isCurrent = this.ws === ws;
+      const wasConnected = this.connected;
+      if (isCurrent) {
+        this.ws = undefined;
+        this.connected = false;
+        this.rejectAllPending('与桥的连接已断开');
+        if (wasConnected) this.log.info('与 AstrBot 桥的连接已断开');
+      }
+      settle();
+      if (isCurrent && !this.stopped) {
+        if (wasConnected) this.emitState(false);
+        this.scheduleReconnect();
+      }
+    });
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectTimer || this.stopped) return;
+    const delay = this.backoffMs;
+    this.backoffMs = Math.min(this.backoffMs * 2, this.opts.reconnectMaxMs ?? 30_000);
+    this.log.debug(`${delay}ms 后重连桥`);
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined;
+      if (!this.stopped) this.connectAttempt();
+    }, delay);
+  }
+
+  private handleFrame(raw: string): void {
+    let frame: Record<string, unknown>;
+    try {
+      frame = JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      this.log.warn('收到无法解析的帧，已忽略');
+      return;
+    }
+
+    const t = typeof frame.t === 'string' ? frame.t : '';
+
+    if (t === 'ack') {
+      const rid = String(frame.rid ?? '');
+      const call = this.pending.get(rid);
+      if (!call) return;
+      this.pending.delete(rid);
+      clearTimeout(call.timer);
+      const ok = frame.ok === true;
+      call.resolve(
+        ok ? { ok: true } : { ok: false, error: String(frame.error ?? '桥拒绝发送') },
+      );
+      return;
+    }
+
+    if (t === 'ready') {
+      const self = frame.self as { id?: unknown; name?: unknown } | undefined;
+      this.self = {
+        id: self?.id === undefined ? undefined : String(self.id),
+        name: self?.name === undefined ? undefined : String(self.name),
+      };
+      const admins = frame.admins;
+      this.ownerIds = Array.isArray(admins)
+        ? admins.map((v) => String(v).trim()).filter((v) => v !== '')
+        : [];
+      this.log.info('桥已就绪', { self: this.self, owners: this.ownerIds.length });
+      return;
+    }
+
+    if (t === 'msg') {
+      const msg = parseMessage(frame);
+      if (!msg) {
+        this.log.warn('消息帧形状不符，已忽略');
+        return;
+      }
+      for (const cb of [...this.messageCbs]) {
+        try {
+          cb(msg);
+        } catch (err) {
+          this.log.error('消息回调抛错', {
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+      return;
+    }
+
+    if (t === 'notice') {
+      const notice: BridgeNotice = {
+        kind: typeof frame.kind === 'string' ? frame.kind : undefined,
+        text: typeof frame.text === 'string' ? frame.text : '',
+        ts: typeof frame.ts === 'string' ? frame.ts : undefined,
+      };
+      if (!notice.text) return;
+      for (const cb of [...this.noticeCbs]) {
+        try {
+          cb(notice);
+        } catch (err) {
+          this.log.error('通知回调抛错', {
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+      return;
+    }
+
+    this.log.debug('未知帧类型，已忽略', { t });
+  }
+
+  private emitState(connected: boolean): void {
+    for (const cb of [...this.stateCbs]) {
+      try {
+        cb(connected);
+      } catch (err) {
+        this.log.error('状态回调抛错', {
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  }
+
+  private rejectAllPending(reason: string): void {
+    for (const call of this.pending.values()) {
+      clearTimeout(call.timer);
+      call.resolve({ ok: false, error: reason });
+    }
+    this.pending.clear();
+  }
+}
+
+/** 把一帧 `msg` 收敛成 BridgeMessage；形状不对时返回 null。 */
+export function parseMessage(frame: Record<string, unknown>): BridgeMessage | null {
+  const convRaw = frame.conv as Record<string, unknown> | undefined;
+  if (!convRaw) return null;
+  const kind = convRaw.kind === 'private' ? 'private' : convRaw.kind === 'group' ? 'group' : null;
+  if (!kind) return null;
+  const id = convRaw.id === undefined || convRaw.id === null ? '' : String(convRaw.id);
+  if (!id) return null;
+
+  const text = typeof frame.text === 'string' ? frame.text : '';
+  const senderRaw = frame.sender as Record<string, unknown> | undefined;
+
+  return {
+    id: frame.id === undefined ? '' : String(frame.id),
+    ts: typeof frame.ts === 'string' ? frame.ts : undefined,
+    conv: {
+      kind,
+      id,
+      name: typeof convRaw.name === 'string' ? convRaw.name : undefined,
+    },
+    sender: senderRaw
+      ? {
+          id: senderRaw.id === undefined ? undefined : String(senderRaw.id),
+          name: typeof senderRaw.name === 'string' ? senderRaw.name : undefined,
+        }
+      : undefined,
+    text,
+    mentioned: frame.mentioned === true,
+    canScreenshot: (frame.can as Record<string, unknown> | undefined)?.screenshot === true,
+    role: frame.role === 'admin' ? 'admin' : 'member',
+    images: parseImages(frame.images),
+    notice: frame.kind === 'notice',
+    ref: typeof frame.ref === 'string' && frame.ref !== '' ? frame.ref : undefined,
+  };
+}
+
+/** 帧里的图片数组；形状不对的项直接丢掉。 */
+function parseImages(raw: unknown): Array<{ mime: string; base64: string }> | undefined {
+  if (!Array.isArray(raw)) return undefined;
+  const out: Array<{ mime: string; base64: string }> = [];
+  for (const item of raw) {
+    if (!item || typeof item !== 'object') continue;
+    const rec = item as Record<string, unknown>;
+    const mime = typeof rec.mime === 'string' ? rec.mime : '';
+    const base64 = typeof rec.base64 === 'string' ? rec.base64 : '';
+    if (!base64 || !mime.startsWith('image/')) continue;
+    out.push({ mime, base64 });
+    if (out.length >= 4) break;
+  }
+  return out.length > 0 ? out : undefined;
+}