@xmoxmo/bncr 0.0.3 → 0.0.4

package/README.md

@@ -1,394 +1,80 @@
-# bncr-channel
+# bncr
 
-OpenClaw 的 Bncr WebSocket Bridge 频道插件（`channelId=bncr`）。
+OpenClaw 的 Bncr 频道插件（`channelId=bncr`）。
 
-这份文档按“拿到插件就能对接”的目标编写：你只看本 README，也能完成接入。
+作用很简单：把 **Bncr / 无界客户端** 接到 **OpenClaw 网关**，用于消息双向通信与媒体/文件传输。
 
 ---
 
-## 1. 概览
+## 安装
 
-- **OpenClaw Channel ID**：`bncr`
-- **Bridge Version**：`2`
-- **出站事件名**：`bncr.push`
-- **出站模式**：`push-only`（不依赖 pull 轮询）
-- **活动心跳方法**：`bncr.activity`
-- **诊断方法**：`bncr.diagnostics`
-- **文件互传方法（V1）**：
-  - `bncr.file.init`
-  - `bncr.file.chunk`
-  - `bncr.file.complete`
-  - `bncr.file.abort`
-  - `bncr.file.ack`
+### OpenClaw 侧
 
----
-
-## 2. 工作模式（重点）
-
-当前是 **push-only**：
-
-- Bncr 在线：OpenClaw 通过 WS `event=bncr.push` 直接下发回复。
-- Bncr 离线：消息进入 outbox；重连后自动冲队列。
-- `bncr.activity` 仅用于在线保活，不承载拉取。
-- `bncr.ack` 保留兼容，当前主链路不强依赖。
-
-> 结论：客户端最小实现只需两件事：
-> 1) 发 `bncr.inbound`；2) 监听 `bncr.push`。
-
----
-
-## 3. SessionKey 规则（严格）
-
-标准格式（canonical）：
-
-```text
-agent:main:bncr:direct:<hexScope>
-```
-
-其中：
-
-- `<hexScope>` = `platform:groupId:userId` 的 UTF-8 十六进制。
-- 推荐使用小写 hex（插件兼容大小写输入）。
-- 兼容输入会在内部归一到 `agent:main:bncr:direct:<hexScope>`。
-
-示例：
-
-```text
-scope      = qq:0:888888
-hexScope   = 71713a303a383838383838
-sessionKey = agent:main:bncr:direct:71713a303a383838383838
-```
-
----
-
-## 4. Gateway Methods
-
-插件注册方法：
-
-- `bncr.connect`
-- `bncr.inbound`
-- `bncr.activity`
-- `bncr.ack`
-- `bncr.diagnostics`
-- `bncr.file.init`
-- `bncr.file.chunk`
-- `bncr.file.complete`
-- `bncr.file.abort`
-- `bncr.file.ack`
-
----
-
-## 5. 接入流程（最小可用）
-
-### Step A：建立 WS 并发送 `bncr.connect`
-
-请求示例：
-
-```json
-{
-  "type": "req",
-  "id": "c1",
-  "method": "bncr.connect",
-  "params": {
-    "accountId": "Primary",
-    "clientId": "bncr-client-1"
-  }
-}
-```
-
-响应示例：
-
-```json
-{
-  "type": "res",
-  "id": "c1",
-  "ok": true,
-  "result": {
-    "channel": "bncr",
-    "accountId": "Primary",
-    "bridgeVersion": 2,
-    "pushEvent": "bncr.push",
-    "online": true,
-    "isPrimary": true,
-    "activeConnections": 1,
-    "pending": 0,
-    "deadLetter": 0,
-    "diagnostics": {
-      "health": {
-        "connected": true,
-        "pending": 0,
-        "deadLetter": 0,
-        "activeConnections": 1
-      },
-      "regression": {
-        "ok": true
-      }
-    },
-    "now": 1772476800000
-  }
-}
-```
-
-> `accountId` 示例是 `Primary`，请按你实际配置替换；不传默认使用 `Primary`。
-
-### Step B：上行消息用 `bncr.inbound`
-
-文本请求示例（`msg` 形态）：
-
-```json
-{
-  "type": "req",
-  "id": "i1",
-  "method": "bncr.inbound",
-  "params": {
-    "accountId": "Primary",
-    "platform": "qq",
-    "groupId": "0",
-    "userId": "888888",
-    "sessionKey": "agent:main:bncr:direct:71713a303a383838383838",
-    "msgId": "msg-1001",
-    "type": "text",
-    "msg": "你好"
-  }
-}
-```
-
-媒体请求示例（字段是 `base64`）：
-
-```json
-{
-  "type": "req",
-  "id": "i2",
-  "method": "bncr.inbound",
-  "params": {
-    "accountId": "Primary",
-    "platform": "qq",
-    "groupId": "0",
-    "userId": "888888",
-    "sessionKey": "agent:main:bncr:direct:71713a303a383838383838",
-    "msgId": "msg-1002",
-    "type": "image/png",
-    "msg": "",
-    "base64": "<BASE64_PAYLOAD>",
-    "mimeType": "image/png",
-    "fileName": "demo.png"
-  }
-}
-```
-
-响应示例：
-
-```json
-{
-  "type": "res",
-  "id": "i1",
-  "ok": true,
-  "result": {
-    "accepted": true,
-    "accountId": "Primary",
-    "sessionKey": "agent:main:bncr:direct:71713a303a383838383838",
-    "msgId": "msg-1001",
-    "taskKey": null
-  }
-}
-```
-
-> `bncr.inbound` 先快速 ACK，再异步处理，最终回复经 `bncr.push` 回推。
+在 OpenClaw 上执行：
 
-### Step C：消费 `bncr.push`
-
-事件示例：
-
-```json
-{
-  "type": "event",
-  "event": "bncr.push",
-  "payload": {
-    "type": "message.outbound",
-    "messageId": "3f8b1f9b-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
-    "idempotencyKey": "3f8b1f9b-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
-    "sessionKey": "agent:main:bncr:direct:71713a303a383838383838",
-    "message": {
-      "platform": "qq",
-      "groupId": "0",
-      "userId": "888888",
-      "type": "text",
-      "msg": "收到，已处理。",
-      "path": "",
-      "base64": "",
-      "fileName": ""
-    },
-    "ts": 1772476801234
-  }
-}
+```bash
+openclaw plugins install @xmoxmo/bncr
+openclaw plugins enable bncr
+openclaw gateway restart
 ```
 
----
-
-## 6. 字段协议
-
-### 6.1 Bncr -> OpenClaw（`bncr.inbound`）
-
-常用字段：
-
-- `accountId`：可选（默认 `Primary`）
-- `platform`：必填
-- `groupId`：可选，默认 `"0"`（私聊）
-- `userId`：建议填写（私聊/群聊都建议带上）
-- `sessionKey`：可选，建议传严格 sessionKey
-- `msgId`：建议传（便于短窗口去重）
-- `type`：`text/image/video/file/...`
-- `msg`：文本
-- `base64`：媒体 base64
-- `path`：可选，文件直传完成后的落盘路径（与 `base64` 二选一）
-- `mimeType` / `fileName`：媒体元数据（可选）
-
-校验失败常见错误：
-
-- `platform/groupId/userId required`
-
-#### 6.1.1 任务分流前缀（可选）
-
-`msg` 支持前缀：
+### Bncr / 无界侧
 
-- `#task:foo`
-- `/task:foo`
-- `/task foo 正文...`
+安装：
 
-命中后会把会话键附加为 `:task:<taskKey>` 用于子任务分流，ACK 中会返回 `taskKey`。
+- `openclawclient.js`
 
-### 6.2 OpenClaw -> Bncr（`bncr.push`）
+然后完成客户端配置，至少包括：
 
-关键字段：
+- OpenClaw 地址
+- 端口
+- Token
+- 连接相关参数
 
-- `type`（固定 `message.outbound`）
-- `messageId`
-- `idempotencyKey`（当前等于 `messageId`）
-- `sessionKey`
-- `message.platform/groupId/userId`
-- `message.type/msg/path/base64/fileName/mimeType`
-- `message.transferMode`（媒体场景可出现：`base64`/`chunk`）
-- `ts`
-
-说明：
-
-- 主类型固定为 `type="message.outbound"`。
-- 推荐客户端仅消费 `message.outbound` 主链路。
+配置完成后，让客户端成功连到 OpenClaw 网关即可。
 
 ---
 
-## 7. `message.send(channel=bncr)` 目标解析规则（重要）
-
-发送前支持并兼容以下 6 种目标输入：
+## 支持能力
 
-1. `agent:main:bncr:direct:<hex>`
-2. `agent:main:bncr:group:<hex>`
-3. `bncr:<hex>`
-4. `bncr:g-<hex>`
-5. `bncr:<platform>:<groupId>:<userId>`
-6. `bncr:g-<platform>:<groupId>:<userId>`
+### 支持内容
 
-推荐写法：
+- 文本
+- 图片
+- 视频
+- 语音
+- 音频
+- 文件
 
-- `to=bncr:<platform>:<groupId>:<userId>`
+### 其它特性
 
-内部会做**反查校验**：
-
-- 必须在已知会话路由中反查到真实 session 才发送。
-- 查不到会报：`target not found in known sessions`。
+- 下行推送
+- 离线消息自动排队
+- 重连后继续发送
+- 支持诊断信息
+- 支持文件互传
 
 ---
 
-## 8. 文件互传（V1）
-
-### 8.1 OpenClaw -> Bncr（下行媒体）
-
-当前默认 **强制分块**（chunk）传输：
-
-- `bncr.file.init`
-- `bncr.file.chunk`
-- `bncr.file.complete`
-- Bncr 客户端通过 `bncr.file.ack` 回 ACK
-
-特性：
-
-- 分块大小默认 256KB
-- chunk ACK 超时/失败会重试
-- 完成后 `message.outbound.message.path` 回填客户端可用路径
-
-### 8.2 Bncr -> OpenClaw（上行文件）
-
-Bncr 客户端可通过：
+## 安装后如何确认成功
 
-- `bncr.file.init`
-- `bncr.file.chunk`
-- `bncr.file.complete`
-- `bncr.file.abort`
+可以通过以下方式检查：
 
-完成上传后，OpenClaw 会落盘并在后续 `bncr.inbound` 中通过 `path` 传递。
-
----
-
-## 9. 可靠性
-
-- 离线入队 + 重连自动冲队列。
-- 指数退避：`1s,2s,4s,8s...`
-- 最大重试次数：`10`
-- 超限进入 dead-letter。
-
----
-
-## 10. 状态判定与诊断
-
-- 实际链路在线：`linked`
-- 已配置但离线：`configured`
-- 账户卡片离线展示口径会显示 `Status`
-
-常用状态字段：
-
-- `pending`
-- `deadLetter`
-- `lastSessionKey`
-- `lastSessionScope`（`bncr:platform:group:user`）
-- `lastSessionAt`
-- `lastActivityAt`
-- `lastInboundAt`
-- `lastOutboundAt`
-- `diagnostics`
-
-`diagnostics` 中包含：
-
-- `health`：连接数、pending、dead-letter、事件计数、uptime
-- `regression`：已知路由数、无效 sessionKey 残留、账号残留等
-
----
-
-## 11. FAQ
-
-### Q1：为什么看不到回复？
-
-1. 先确认 `bncr.connect` 成功。
-2. 客户端确认监听的是 `bncr.push`。
-3. `sessionKey` 是否符合规范。
-4. 若用 `message.send`，目标是否能反查到已知会话。
-
-### Q2：为什么不需要 `bncr.pull`？
-
-因为当前是 push-only，统一走 `bncr.push`。
-
-### Q3：如何避免重复消息？
+```bash
+openclaw gateway status
+openclaw health --json
+```
 
-- 入站带稳定 `msgId`。
-- 出站按 `idempotencyKey` 幂等处理。
-- 客户端侧建议仅消费 `message.outbound`，并按需过滤 `NO_REPLY/HEARTBEAT_OK`。
+重点看：
 
-### Q4：如何看桥接健康状态？
+- 网关是否正常运行
+- bncr 是否已经 `linked`
+- 是否存在异常 pending / deadLetter
 
-- 可直接调用 `bncr.diagnostics`。
-- 或看 `bncr.connect`/状态卡片中的 `diagnostics` 字段。
+如果 bncr 已成功连上，一般就说明插件安装和基础链路已经正常。
 
 ---
 
-## 12. 版本提示
+## 说明
 
-历史版本接入过的话，请以当前文档（push-only + 6 格式目标兼容 + 文件互传 V1 + 诊断字段）为准。
+如果你接触过旧版本，请以当前 README 和当前代码为准。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmoxmo/bncr",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "private": false,
   "type": "module",
   "license": "MIT",

package/src/channel.ts

@@ -21,6 +21,7 @@ const BRIDGE_VERSION = 2;
 const BNCR_PUSH_EVENT = 'bncr.push';
 const CONNECT_TTL_MS = 120_000;
 const MAX_RETRY = 10;
+const PUSH_DRAIN_INTERVAL_MS = 500;
 const FILE_FORCE_CHUNK = true; // 统一走 WS 分块，保留 base64 仅作兜底
 const FILE_INLINE_THRESHOLD = 5 * 1024 * 1024; // fallback 阈值（仅 FILE_FORCE_CHUNK=false 时生效）
 const FILE_CHUNK_SIZE = 256 * 1024; // 256KB
@@ -529,20 +530,20 @@ function resolveOutboundFileName(params: { mediaUrl?: string; fileName?: string;
   return `${stem}${ext}`;
 }
 
-function resolveBncrOutboundMessageType(params: { mimeType?: string; fileName?: string; hintedType?: string }): 'text' | 'image' | 'video' | 'file' {
+function resolveBncrOutboundMessageType(params: { mimeType?: string; fileName?: string; hintedType?: string; hasPayload?: boolean }): 'text' | 'image' | 'video' | 'voice' | 'audio' | 'file' {
   const hinted = asString(params.hintedType || '').toLowerCase();
-  // 优先使用可确定类型；“file”属于兜底，不覆盖更明确的 mime/扩展判断
-  if (hinted === 'text' || hinted === 'image' || hinted === 'video') return hinted as any;
-
+  const hasPayload = !!params.hasPayload;
   const mt = asString(params.mimeType || '').toLowerCase();
   const major = mt.split('/')[0] || '';
-  if (major === 'text') return 'text';
-  if (major === 'image') return 'image';
-  if (major === 'video') return 'video';
+  const isStandard = hinted === 'text' || hinted === 'image' || hinted === 'video' || hinted === 'voice' || hinted === 'audio' || hinted === 'file';
+
+  // 文本类附件不应落成 text：当上游显式给 text，或上游 type 不在标准列表时，若带文件载荷且 mime 主类型为 text，则归到 file。
+  if (hasPayload && major === 'text' && (hinted === 'text' || !isStandard)) return 'file';
+
+  // 优先使用上游已给出的标准类型；仅当不在支持列表时再尝试纠正
+  if (isStandard) return hinted as any;
 
-  const fn = asString(params.fileName || '').toLowerCase();
-  if (/\.(png|jpe?g|gif|webp|bmp|svg)$/.test(fn)) return 'image';
-  if (/\.(mp4|mov|mkv|avi|webm)$/.test(fn)) return 'video';
+  if (major === 'text' || major === 'image' || major === 'video' || major === 'audio') return major as any;
 
   return 'file';
 }
@@ -574,6 +575,7 @@ class BncrBridgeRuntime {
 
   private saveTimer: NodeJS.Timeout | null = null;
   private pushTimer: NodeJS.Timeout | null = null;
+  private pushDrainRunningAccounts = new Set<string>();
   private waiters = new Map<string, Array<() => void>>();
   private gatewayContext: GatewayRequestHandlerOptions['context'] | null = null;
 
@@ -965,55 +967,76 @@ class BncrBridgeRuntime {
     const delay = Math.max(0, Math.min(Number(delayMs || 0), 30_000));
     this.pushTimer = setTimeout(() => {
       this.pushTimer = null;
-      this.flushPushQueue();
+      void this.flushPushQueue();
     }, delay);
   }
 
-  private flushPushQueue(accountId?: string) {
-    const t = now();
+  private async flushPushQueue(accountId?: string): Promise<void> {
     const filterAcc = accountId ? normalizeAccountId(accountId) : null;
-    const entries = Array.from(this.outbox.values())
-      .filter((entry) => (filterAcc ? entry.accountId === filterAcc : true))
-      .sort((a, b) => a.createdAt - b.createdAt);
+    const targetAccounts = filterAcc
+      ? [filterAcc]
+      : Array.from(new Set(Array.from(this.outbox.values()).map((entry) => normalizeAccountId(entry.accountId))));
 
-    let changed = false;
-    let nextDelay: number | null = null;
+    let globalNextDelay: number | null = null;
 
-    for (const entry of entries) {
-      if (!this.isOnline(entry.accountId)) continue;
+    for (const acc of targetAccounts) {
+      if (!acc || this.pushDrainRunningAccounts.has(acc)) continue;
+      if (!this.isOnline(acc)) continue;
 
-      if (entry.nextAttemptAt > t) {
-        const wait = entry.nextAttemptAt - t;
-        nextDelay = nextDelay == null ? wait : Math.min(nextDelay, wait);
-        continue;
-      }
-
-      const pushed = this.tryPushEntry(entry);
-      if (pushed) {
-        changed = true;
-        continue;
-      }
+      this.pushDrainRunningAccounts.add(acc);
+      try {
+        let localNextDelay: number | null = null;
+
+        while (true) {
+          const t = now();
+          const entries = Array.from(this.outbox.values())
+            .filter((entry) => normalizeAccountId(entry.accountId) === acc)
+            .sort((a, b) => a.createdAt - b.createdAt);
+
+          if (!entries.length) break;
+          if (!this.isOnline(acc)) break;
+
+          const entry = entries.find((item) => item.nextAttemptAt <= t);
+          if (!entry) {
+            const wait = Math.max(0, entries[0].nextAttemptAt - t);
+            localNextDelay = localNextDelay == null ? wait : Math.min(localNextDelay, wait);
+            break;
+          }
+
+          const pushed = this.tryPushEntry(entry);
+          if (pushed) {
+            this.scheduleSave();
+            await this.sleepMs(PUSH_DRAIN_INTERVAL_MS);
+            continue;
+          }
+
+          const nextAttempt = entry.retryCount + 1;
+          if (nextAttempt > MAX_RETRY) {
+            this.moveToDeadLetter(entry, entry.lastError || 'push-retry-limit');
+            continue;
+          }
+
+          entry.retryCount = nextAttempt;
+          entry.lastAttemptAt = t;
+          entry.nextAttemptAt = t + backoffMs(nextAttempt);
+          entry.lastError = entry.lastError || 'push-retry';
+          this.outbox.set(entry.messageId, entry);
+          this.scheduleSave();
+
+          const wait = Math.max(0, entry.nextAttemptAt - t);
+          localNextDelay = localNextDelay == null ? wait : Math.min(localNextDelay, wait);
+          break;
+        }
 
-      const nextAttempt = entry.retryCount + 1;
-      if (nextAttempt > MAX_RETRY) {
-        this.moveToDeadLetter(entry, entry.lastError || 'push-retry-limit');
-        changed = true;
-        continue;
+        if (localNextDelay != null) {
+          globalNextDelay = globalNextDelay == null ? localNextDelay : Math.min(globalNextDelay, localNextDelay);
+        }
+      } finally {
+        this.pushDrainRunningAccounts.delete(acc);
       }
-
-      entry.retryCount = nextAttempt;
-      entry.lastAttemptAt = t;
-      entry.nextAttemptAt = t + backoffMs(nextAttempt);
-      entry.lastError = entry.lastError || 'push-retry';
-      this.outbox.set(entry.messageId, entry);
-      changed = true;
-
-      const wait = entry.nextAttemptAt - t;
-      nextDelay = nextDelay == null ? wait : Math.min(nextDelay, wait);
     }
 
-    if (changed) this.scheduleSave();
-    if (nextDelay != null) this.schedulePushDrain(nextDelay);
+    if (globalNextDelay != null) this.schedulePushDrain(globalNextDelay);
   }
 
   private async waitForOutbound(accountId: string, waitMs: number): Promise<void> {
@@ -1751,7 +1774,7 @@ class BncrBridgeRuntime {
             type: resolveBncrOutboundMessageType({
               mimeType: media.mimeType,
               fileName: media.fileName,
-              hintedType: 'file',
+              hasPayload: !!(media.path || media.mediaBase64),
             }),
             mimeType: media.mimeType || '',
             msg: mediaMsg,

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 xmoxmo
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.