@xmoxmo/bncr 0.0.4 → 0.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+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.

package/README.md

@@ -4,13 +4,22 @@ OpenClaw 的 Bncr 频道插件（`channelId=bncr`）。
 
 作用很简单：把 **Bncr / 无界客户端** 接到 **OpenClaw 网关**，用于消息双向通信与媒体/文件传输。
 
+> 当前定位说明：bncr **不是 agent**。它保留既有 **WS 接入链路** 作为 transport / 通信承载，
+> 在 OpenClaw 内部则按 **正式频道插件（channel plugin）** 建模。
+
 ---
 
-## 安装
+## 1. 这是什么
 
-### OpenClaw 侧
+- 一个 OpenClaw 的正式频道插件
+- 负责把 Bncr / 无界客户端接入 OpenClaw
+- 负责消息、媒体、文件与基础状态链路
+
+---
+
+## 2. 安装方式
 
-在 OpenClaw 上执行：
+### OpenClaw 侧
 
 ```bash
 openclaw plugins install @xmoxmo/bncr
@@ -24,20 +33,11 @@ openclaw gateway restart
 
 - `openclawclient.js`
 
-然后完成客户端配置，至少包括：
-
-- OpenClaw 地址
-- 端口
-- Token
-- 连接相关参数
-
-配置完成后，让客户端成功连到 OpenClaw 网关即可。
+然后完成客户端配置并连上 OpenClaw 网关即可。
 
 ---
 
-## 支持能力
-
-### 支持内容
+## 3. 当前能力
 
 - 文本
 - 图片
@@ -45,20 +45,62 @@ openclaw gateway restart
 - 语音
 - 音频
 - 文件
-
-### 其它特性
-
 - 下行推送
-- 离线消息自动排队
+- ACK
+- 离线消息排队
 - 重连后继续发送
-- 支持诊断信息
-- 支持文件互传
+- 状态诊断
+- 文件互传
+
+---
+
+## 4. 架构定位
+
+bncr 当前采用两层模型：
+
+1. **WS 承载层**
+   - Bncr 客户端通过 WebSocket 接入 OpenClaw 网关
+   - 负责连接、推送、ACK、文件分块等 transport 能力
+
+2. **OpenClaw 频道插件层**
+   - 在 OpenClaw 内部按正式 `channel plugin` 建模
+   - 负责入站解析、消息分发、出站适配、状态与治理
+
+当前代码结构：
+
+```text
+plugins/bncr/src/
+  channel.ts
+  core/
+  messaging/
+```
+
+---
+
+## 5. 配置项总览
+
+当前主要配置字段：
+
+- `enabled`
+- `dmPolicy`
+- `groupPolicy`
+- `allowFrom`
+- `groupAllowFrom`
+- `outboundRequireAck`
+- `requireMention`
+- `accounts`
+
+补充：
+
+- `dmPolicy` / `groupPolicy` 支持：`open | allowlist | disabled`
+- `outboundRequireAck` 控制文本外发是否等待 `bncr.ack` 再出队
+- `requireMention` 当前仍是保留字段
 
 ---
 
-## 安装后如何确认成功
+## 6. 状态与诊断
 
-可以通过以下方式检查：
+常用检查：
 
 ```bash
 openclaw gateway status
@@ -67,14 +109,42 @@ openclaw health --json
 
 重点看：
 
-- 网关是否正常运行
-- bncr 是否已经 `linked`
-- 是否存在异常 pending / deadLetter
+- `linked`
+- `pending`
+- `deadLetter`
+- diagnostics / probe / status 摘要
+
+---
 
-如果 bncr 已成功连上，一般就说明插件安装和基础链路已经正常。
+## 7. 自检与测试
+
+```bash
+cd plugins/bncr
+npm test
+npm run selfcheck
+npm pack
+```
+
+用途：
+
+- `npm test`：跑回归测试
+- `npm run selfcheck`：检查插件骨架是否完整
+- `npm pack`：确认当前版本可正常打包
 
 ---
 
-## 说明
+## 8. 上线前检查
+
+上线前建议至少确认：
+
+- README 与当前实现一致
+- 配置 schema 与实际字段一致
+- 测试通过
+- 自检通过
+- 可以正常打包
+- 本地版本号与 npm / 发布目标一致
+- 运行态 `linked / pending / deadLetter` 正常
+
+---
 
 如果你接触过旧版本，请以当前 README 和当前代码为准。

package/index.ts

@@ -1,21 +1,47 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import {
-  emptyPluginConfigSchema,
   type GatewayRequestHandlerOptions,
 } from "openclaw/plugin-sdk";
+import { BncrConfigSchema } from "./src/core/config-schema.js";
 import { createBncrBridge, createBncrChannelPlugin } from "./src/channel.js";
 
+type BridgeSingleton = ReturnType<typeof createBncrBridge>;
+
+const getBridgeSingleton = (api: OpenClawPluginApi) => {
+  const g = globalThis as typeof globalThis & { __bncrBridge?: BridgeSingleton };
+  if (!g.__bncrBridge) g.__bncrBridge = createBncrBridge(api);
+  return g.__bncrBridge;
+};
+
 const plugin = {
   id: "bncr",
   name: "Bncr",
   description: "Bncr channel plugin",
-  configSchema: emptyPluginConfigSchema(),
+  configSchema: BncrConfigSchema,
   register(api: OpenClawPluginApi) {
-    const bridge = createBncrBridge(api);
+    const bridge = getBridgeSingleton(api);
+    const debugLog = (...args: any[]) => {
+      if (!bridge.isDebugEnabled?.()) return;
+      api.logger.info?.(...args);
+    };
+
+    debugLog(`bncr plugin register bridge=${(bridge as any)?.bridgeId || 'unknown'}`);
+
+    const resolveDebug = async () => {
+      try {
+        const cfg = await api.runtime.config.loadConfig();
+        return Boolean((cfg as any)?.channels?.bncr?.debug?.verbose);
+      } catch {
+        return false;
+      }
+    };
 
     api.registerService({
       id: "bncr-bridge-service",
-      start: bridge.startService,
+      start: async (ctx) => {
+        const debug = await resolveDebug();
+        await bridge.startService(ctx, debug);
+      },
       stop: bridge.stopService,
     });
 

package/openclaw.plugin.json

@@ -3,7 +3,38 @@
   "channels": ["bncr"],
   "configSchema": {
     "type": "object",
-    "additionalProperties": false,
-    "properties": {}
+    "additionalProperties": true,
+    "properties": {
+      "enabled": { "type": "boolean" },
+      "dmPolicy": {
+        "type": "string",
+        "enum": ["open", "allowlist", "disabled"]
+      },
+      "groupPolicy": {
+        "type": "string",
+        "enum": ["open", "allowlist", "disabled"]
+      },
+      "allowFrom": {
+        "type": "array",
+        "items": { "type": "string" }
+      },
+      "groupAllowFrom": {
+        "type": "array",
+        "items": { "type": "string" }
+      },
+      "requireMention": { "type": "boolean" },
+      "outboundRequireAck": { "type": "boolean" },
+      "accounts": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "name": { "type": "string" }
+          }
+        }
+      }
+    }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmoxmo/bncr",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -20,8 +20,13 @@
     "openclaw.plugin.json",
     "README.md",
     "LICENSE",
-    "src"
+    "src",
+    "scripts"
   ],
+  "scripts": {
+    "selfcheck": "node ./scripts/selfcheck.mjs",
+    "test": "node --import ./tests/register-ts-hooks.mjs --test ./tests/*.test.mjs"
+  },
   "openclaw": {
     "extensions": [
       "./index.ts"

package/scripts/selfcheck.mjs

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const root = path.resolve(__dirname, '..');
+
+const requiredFiles = [
+  'index.ts',
+  'openclaw.plugin.json',
+  'src/channel.ts',
+  'src/core/types.ts',
+  'src/core/accounts.ts',
+  'src/core/targets.ts',
+  'src/core/status.ts',
+  'src/core/probe.ts',
+  'src/core/config-schema.ts',
+  'src/core/policy.ts',
+  'src/core/permissions.ts',
+  'src/messaging/inbound/parse.ts',
+  'src/messaging/inbound/gate.ts',
+  'src/messaging/inbound/dispatch.ts',
+  'src/messaging/outbound/send.ts',
+  'src/messaging/outbound/media.ts',
+  'src/messaging/outbound/actions.ts',
+];
+
+const missing = requiredFiles.filter((rel) => !fs.existsSync(path.join(root, rel)));
+const result = {
+  ok: missing.length === 0,
+  checkedRoot: root,
+  requiredCount: requiredFiles.length,
+  missing,
+};
+
+console.log(JSON.stringify(result, null, 2));
+if (missing.length > 0) process.exit(1);