cortico-world-astrbot 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.0.4
+
+- README 修正协议说明：`capabilities.images` 只在 `hello` 帧里自报，`ready` 帧不带；并说明它只在重连时刷新。
+- 补上实机验证环境（Cortico 0.2.8 / Coopanion 0.2.12）。
+
+## 1.0.3
+
+- 加心跳与静默检测：休眠唤醒、切换网络、对端进程消失时，socket 可能「开着但永远没有下文」，而 `close` 事件不会来。现在每 20 秒 ping 一次，60 秒没有任何往来就主动重建，不再静默丢消息。
+
 ## 1.0.2
 
 - 桥的 `error` 事件只认现役 socket：重启时旧连接迟到的错误不再被当成新连接的错误记一条。

package/README.md

@@ -4,10 +4,12 @@
 
 让 Cortico 的人格 Bot 进 QQ 群说话，同时把 QQ 账号与插件能力留在 AstrBot 手里。
 
-**当前版本：1.0.2**（更新内容见 [CHANGELOG.md](CHANGELOG.md)）
+**当前版本：1.0.4**（更新内容见 [CHANGELOG.md](CHANGELOG.md)）
 
 项目地址：[as124da1231/cortico-world-astrbot](https://github.com/as124da1231/cortico-world-astrbot)。
 
+已在 **Cortico 0.2.8 / Coopanion 0.2.12** 上实机验证：文字、图片（单图与多图）、撤回/戳一戳通知、断线重连。
+
 ## 为什么是这样一个形状
 
 Cortico 自带的 `qq` World 能直接连 OneBot 协议端，但它只做收发消息。如果你的 QQ 号上已经有一整套 AstrBot 插件（画图、点歌、战绩查询、媒体解析……），换掉那套生态的代价很高。
@@ -96,12 +98,12 @@ corepack pnpm add cortico-world-astrbot
 ```
 
 `capabilities.images` 表示本端模型能直接读图；为真时桥才附原图，否则自己转成文字。
+这个值由 Cortico 侧按当前端点的多模态能力算出来，只在**每次重连握手时**刷新——中途改了端点设置要等重连（或重启进程）才生效。
 
 桥推给客户端：
 
 ```json
-{ "t": "ready", "v": 1, "self": { "id": "…", "name": "…" },
-  "admins": ["42"], "capabilities": { "images": false } }
+{ "t": "ready", "v": 1, "self": { "id": "…", "name": "…" }, "admins": ["42"] }
 
 { "t": "msg", "id": "消息id", "ts": "2026-10-26T10:00:00+08:00",
   "conv": { "kind": "group", "id": "123456", "name": "群名" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortico-world-astrbot",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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

@@ -94,6 +94,10 @@ export interface BridgeDriverOptions {
   reconnectMaxMs?: number;
   /** 一次发送等确认的超时。 */
   sendTimeoutMs?: number;
+  /** 心跳间隔；0 表示不做活性检测。 */
+  heartbeatMs?: number;
+  /** 超过这么久没有任何往来就重建连接（休眠唤醒后的死连接靠它发现）。 */
+  idleTimeoutMs?: number;
   log?: Logger;
 }
 
@@ -105,6 +109,12 @@ interface PendingSend {
 /** 发送确认的默认超时。 */
 export const DEFAULT_SEND_TIMEOUT_MS = 15_000;
 
+/** 心跳间隔：主动 ping 一次，顺便刷新活跃时间。 */
+export const DEFAULT_HEARTBEAT_MS = 20_000;
+
+/** 多久没有任何往来就认定连接已死。桥每 20 秒 ping 一次，留三倍余量。 */
+export const DEFAULT_IDLE_TIMEOUT_MS = 60_000;
+
 export class AstrbotBridgeDriver implements BridgeDriver {
   private readonly opts: BridgeDriverOptions;
   private readonly log: Logger;
@@ -112,6 +122,8 @@ export class AstrbotBridgeDriver implements BridgeDriver {
   private stopped = true;
   private backoffMs: number;
   private reconnectTimer?: ReturnType<typeof setTimeout>;
+  private heartbeat?: ReturnType<typeof setInterval>;
+  private lastActivity = 0;
   private ridSeq = 0;
   private pending = new Map<string, PendingSend>();
   private messageCbs: Array<(m: BridgeMessage) => void> = [];
@@ -167,6 +179,7 @@ export class AstrbotBridgeDriver implements BridgeDriver {
 
   async stop(): Promise<void> {
     this.stopped = true;
+    this.stopHeartbeat();
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = undefined;
@@ -273,11 +286,24 @@ export class AstrbotBridgeDriver implements BridgeDriver {
         });
       }
       this.emitState(true);
+      this.startHeartbeat(ws);
       settle();
     });
 
     ws.on('message', (data) => {
-      if (!this.stopped && this.ws === ws) this.handleFrame(String(data));
+      if (!this.stopped && this.ws === ws) {
+        this.lastActivity = Date.now();
+        this.handleFrame(String(data));
+      }
+    });
+
+    // 桥每 20 秒 ping 一次；收到任何一帧都算「还活着」。
+    ws.on('ping', () => {
+      if (this.ws === ws) this.lastActivity = Date.now();
+    });
+
+    ws.on('pong', () => {
+      if (this.ws === ws) this.lastActivity = Date.now();
     });
 
     ws.on('error', (err) => {
@@ -290,6 +316,7 @@ export class AstrbotBridgeDriver implements BridgeDriver {
       const isCurrent = this.ws === ws;
       const wasConnected = this.connected;
       if (isCurrent) {
+        this.stopHeartbeat();
         this.ws = undefined;
         this.connected = false;
         this.rejectAllPending('与桥的连接已断开');
@@ -303,6 +330,43 @@ export class AstrbotBridgeDriver implements BridgeDriver {
     });
   }
 
+  /**
+   * 连接死掉时 socket 不一定给我们 close：机器休眠、网络切换、对端进程消失都可能留下
+   * 一条「开着但永远没有下文」的连接。定期 ping，超过 idleTimeoutMs 没有任何往来就主动
+   * terminate，让 close 走正常重连。
+   */
+  private startHeartbeat(ws: WebSocket): void {
+    this.stopHeartbeat();
+    const every = this.opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+    if (every <= 0) return;
+    const idleLimit = this.opts.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+    this.lastActivity = Date.now();
+    this.heartbeat = setInterval(() => {
+      if (this.ws !== ws) return;
+      const idle = Date.now() - this.lastActivity;
+      if (idle > idleLimit) {
+        this.log.warn('桥连接长时间没有任何动静，重建连接', {
+          idleMs: idle,
+          idleLimitMs: idleLimit,
+        });
+        ws.terminate();
+        return;
+      }
+      try {
+        ws.ping();
+      } catch {
+        // 发不出去就等 close 接手，这里不再多记一条。
+      }
+    }, every);
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeat) {
+      clearInterval(this.heartbeat);
+      this.heartbeat = undefined;
+    }
+  }
+
   private scheduleReconnect(): void {
     if (this.reconnectTimer || this.stopped) return;
     const delay = this.backoffMs;