@coclaw/openclaw-coclaw 0.9.2 → 0.11.0

package/README.md

@@ -88,15 +88,6 @@ openclaw coclaw enroll [--server <url>]
 
 需要 gateway 运行中。
 
-### 方式三：独立 CLI（遗留）
-
-```bash
-node ~/.openclaw/extensions/coclaw/src/cli.js bind <binding-code> --server <url>
-node ~/.openclaw/extensions/coclaw/src/cli.js unbind --server <url>
-```
-
-> 注意：独立 CLI 不走 gateway RPC，直接在 CLI 进程中执行 bind/unbind 并通过 `coclaw.refreshBridge`/`coclaw.stopBridge` 通知 gateway。此路径不具备瘦 CLI 的架构保证（所有 config 操作在同一进程内）。推荐使用方式一。
-
 ## 配置存储
 
 绑定信息存储在 `~/.openclaw/coclaw/bindings.json`（通过 `resolveStateDir()` + channel ID 组合路径），**不存储在 `openclaw.json` 中**。
@@ -137,6 +128,25 @@ openclaw gateway call coclaw.upgradeHealth --json
 
 详见设计文档 `docs/auto-upgrade.md`。
 
+## WebRTC 实现
+
+插件支持两个 WebRTC 实现，运行时自动选择：
+
+1. **node-datachannel**（首选）— 基于 libdatachannel 的工业级实现，通过 vendor 预编译 native binary 部署。
+2. **werift**（回退）— 纯 JavaScript 实现，作为 node-datachannel 加载失败时的兜底。
+
+选择结果通过 remoteLog 上报（`ndc.loaded` 或 `ndc.using-werift`）。
+
+### vendor 预编译包
+
+由于 OpenClaw 使用 `--ignore-scripts` 安装插件，node-datachannel 的 native binary 需通过 vendor 预编译包提供：
+
+```bash
+bash scripts/download-ndc-prebuilds.sh   # 下载 5 平台预编译包到 vendor/ndc-prebuilds/
+```
+
+支持的平台：linux-x64、linux-arm64、darwin-x64、darwin-arm64、win32-x64。vendor 目录不入 git，通过 npm publish 的 `files` 字段包含在发布包中。
+
 ## 运行与排障日志
 
 ### 日志级别建议
@@ -176,10 +186,8 @@ openclaw logs --limit 300 --plain | rg -n "ui->server req|bot->server res|bot->s
 ## 测试门禁
 
 ```bash
-pnpm check       # lint + typecheck
-pnpm test         # 全部单测
-pnpm coverage     # 覆盖率检查
-pnpm verify       # 完整验证（check → test:standalone → test:plugin → test → coverage）
+pnpm check        # lint + typecheck
+pnpm test         # 测试 + 覆盖率检查
 ```
 
 覆盖率阈值：lines/statements/functions 100%，branches ≥ 95%。未通过禁止接入 gateway。

package/index.js

@@ -1,12 +1,10 @@
-import fs from 'node:fs/promises';
-import nodePath from 'node:path';
-
 import { bindBot, unbindBot, enrollBot, waitForClaimAndSave } from './src/common/bot-binding.js';
 import { registerCoclawCli } from './src/cli-registrar.js';
 import { resolveErrorMessage } from './src/common/errors.js';
 import { notBound, bindOk, unbindOk, claimCodeCreated } from './src/common/messages.js';
 import { coclawChannelPlugin } from './src/channel-plugin.js';
-import { ensureAgentSession, gatewayAgentRpc, restartRealtimeBridge, stopRealtimeBridge, waitForSessionsReady } from './src/realtime-bridge.js';
+import { ensureAgentSession, gatewayAgentRpc, restartRealtimeBridge, stopRealtimeBridge, waitForSessionsReady, broadcastPluginEvent } from './src/realtime-bridge.js';
+import { getHostName, readSettings, writeName, MAX_NAME_LENGTH } from './src/settings.js';
 import { setRuntime } from './src/runtime.js';
 import { createSessionManager } from './src/session-manager/manager.js';
 import { TopicManager } from './src/topic-manager/manager.js';
@@ -16,27 +14,12 @@ import { AutoUpgradeScheduler } from './src/auto-upgrade/updater.js';
 import { getPackageInfo } from './src/auto-upgrade/updater-check.js';
 import { createFileHandler } from './src/file-manager/handler.js';
 
-// 延迟读取 + 缓存：避免模块加载时 package.json 损坏导致插件整体无法注册
-let __pluginVersion = null;
-export async function getPluginVersion() {
-	if (__pluginVersion) return __pluginVersion;
-	try {
-		const pkgPath = nodePath.resolve(import.meta.dirname, 'package.json');
-		const raw = await fs.readFile(pkgPath, 'utf8');
-		__pluginVersion = JSON.parse(raw).version ?? 'unknown';
-	} catch {
-		return 'unknown';
-	}
-	return __pluginVersion;
-}
-// 测试用：重置缓存
-export function __resetPluginVersion() { __pluginVersion = null; }
-
+import { getPluginVersion, __resetPluginVersion } from './src/plugin-version.js';
+export { getPluginVersion, __resetPluginVersion };
 
+/* c8 ignore start */
 function parseCommandArgs(args) {
-	/* c8 ignore next */
 	const tokens = (args ?? '').split(/\s+/).filter(Boolean);
-	/* c8 ignore next */
 	const action = tokens[0] ?? 'help';
 	const options = {};
 	const positionals = [];
@@ -67,7 +50,6 @@ function buildHelpText() {
 function respondError(respond, err) {
 	respond(false, undefined, {
 		code: err?.code ?? 'INTERNAL_ERROR',
-		/* c8 ignore next */
 		message: String(err?.message ?? err),
 	});
 }
@@ -75,8 +57,6 @@ function respondError(respond, err) {
 function respondInvalid(respond, message) {
 	respond(false, undefined, { code: 'INVALID_INPUT', message });
 }
-
-/* c8 ignore start */
 const plugin = {
 	id: 'openclaw-coclaw',
 	name: 'CoClaw',
@@ -130,26 +110,6 @@ const plugin = {
 			},
 		});
 
-		api.registerGatewayMethod('coclaw.refreshBridge', async ({ respond }) => {
-			try {
-				await restartRealtimeBridge({ logger, pluginConfig: api.pluginConfig });
-				respond(true, { status: 'refreshed' });
-			}
-			catch (err) {
-				respondError(respond, err);
-			}
-		});
-
-		api.registerGatewayMethod('coclaw.stopBridge', async ({ respond }) => {
-			try {
-				await stopRealtimeBridge();
-				respond(true, { status: 'stopped' });
-			}
-			catch (err) {
-				respondError(respond, err);
-			}
-		});
-
 		// --- bind/unbind 共享逻辑（RPC handler + 斜杠命令共用） ---
 
 		async function doBind({ code, serverUrl }) {
@@ -290,14 +250,48 @@ const plugin = {
 			}
 		});
 
-		api.registerGatewayMethod('coclaw.info', async ({ respond }) => {
+		async function handleInfoGet({ respond }) {
 			try {
 				await waitForSessionsReady();
 				const version = await getPluginVersion();
 				const rawClawVersion = api.runtime?.version;
 				// OpenClaw 打包后 resolveVersion() 路径失配导致返回 'unknown'，此时不传该字段
 				const clawVersion = (rawClawVersion && rawClawVersion !== 'unknown') ? rawClawVersion : undefined;
-				respond(true, { version, clawVersion, capabilities: ['topics', 'chatHistory'] });
+				const settings = await readSettings();
+				const name = settings.name ?? null;
+				const hostName = getHostName();
+				respond(true, { version, clawVersion, capabilities: ['topics', 'chatHistory'], name, hostName });
+			}
+			catch (err) {
+				respondError(respond, err);
+			}
+		}
+
+		api.registerGatewayMethod('coclaw.info', handleInfoGet);
+		api.registerGatewayMethod('coclaw.info.get', handleInfoGet);
+
+		api.registerGatewayMethod('coclaw.info.patch', async ({ params, respond }) => {
+			try {
+				const rawName = params?.name;
+				if (rawName === undefined) {
+					respondInvalid(respond, 'name field is required');
+					return;
+				}
+				if (rawName !== null && typeof rawName !== 'string') {
+					respondInvalid(respond, 'name must be a string or null');
+					return;
+				}
+				const trimmed = typeof rawName === 'string' ? rawName.trim() : '';
+				if (trimmed.length > MAX_NAME_LENGTH) {
+					respondInvalid(respond, `name exceeds maximum length of ${MAX_NAME_LENGTH} characters`);
+					return;
+				}
+				const nameToSave = trimmed || null;
+				await writeName(nameToSave);
+				const hostName = getHostName();
+				respond(true, { name: nameToSave, hostName });
+				// 异步广播变更事件到 server 和其他 UI 实例
+				broadcastPluginEvent('coclaw.info.updated', { name: nameToSave, hostName });
 			}
 			catch (err) {
 				respondError(respond, err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.9.2",
+  "version": "0.11.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",
@@ -32,6 +32,7 @@
     "!src/**/*.test.js",
     "!src/mock-server.helper.js",
     "openclaw.plugin.json",
+    "vendor/ndc-prebuilds/**",
     "LICENSE"
   ],
   "main": "index.js",
@@ -40,20 +41,14 @@
       "./index.js"
     ]
   },
-  "bin": {
-    "coclaw": "src/cli.js"
-  },
   "scripts": {
-    "dev": "node src/cli.js --help",
     "build": "echo 'No build step needed (pure ES modules)'",
     "lint": "eslint \"**/*.{js,mjs,cjs}\" --no-error-on-unmatched-pattern",
     "typecheck": "echo \"No typecheck configured yet (coclaw openclaw plugin)\"",
     "check": "pnpm lint && pnpm typecheck",
-    "test:standalone": "node --test src/standalone-mode.test.js",
     "test:plugin": "node --test src/plugin-mode.test.js",
-    "test": "node --test",
-    "coverage": "c8 --check-coverage --lines 100 --functions 100 --branches 95 --statements 100 --reporter=text --reporter=lcov node --test",
-    "verify": "pnpm check && pnpm coverage",
+    "test": "c8 --check-coverage --lines 100 --functions 100 --branches 94 --statements 100 --reporter=text --reporter=lcov bash -c 'for f in src/**/*.test.js src/*.test.js index.test.js; do node --test \"$f\" || exit 1; done'",
+    "verify": "pnpm check && pnpm test",
     "link": "bash ./scripts/link.sh",
     "unlink": "bash ./scripts/unlink.sh",
     "install:npm": "bash ./scripts/install-npm.sh",
@@ -64,6 +59,7 @@
     "release:versions": "npm view @coclaw/openclaw-coclaw versions --json --registry=https://registry.npmjs.org/ && npm view @coclaw/openclaw-coclaw versions --json"
   },
   "dependencies": {
+    "node-datachannel": "0.32.1",
     "werift": "^0.19.0"
   },
   "devDependencies": {

package/src/auto-upgrade/updater.js

@@ -5,6 +5,7 @@ import { checkForUpdate } from './updater-check.js';
 import { spawnUpgradeWorker } from './updater-spawn.js';
 import { resolveStateDir } from './state.js';
 import { getRuntime } from '../runtime.js';
+import { remoteLog } from '../remote-log.js';
 
 const INITIAL_DELAY_MS = 5 * 60 * 1000; // 5 分钟
 const CHECK_INTERVAL_MS = 60 * 60 * 1000; // 1 小时
@@ -203,6 +204,7 @@ export class AutoUpgradeScheduler {
 			// 若上一次 spawn 的 worker 仍在运行，跳过本次检查
 			const isLocked = this.__opts.isUpgradeLockedFn ?? isUpgradeLocked;
 			if (await isLocked({ logger: this.__logger })) {
+				remoteLog('upgrade.worker-locked');
 				this.__logger.info?.('[auto-upgrade] Upgrade worker still running, skipping check');
 				return;
 			}
@@ -221,11 +223,13 @@ export class AutoUpgradeScheduler {
 				return;
 			}
 
+			remoteLog(`upgrade.available from=${result.currentVersion} to=${result.latestVersion}`);
 			this.__logger.info?.(`[auto-upgrade] Update available: ${result.currentVersion} → ${result.latestVersion}`);
 
 			const getInstallPath = this.__opts.getPluginInstallPathFn ?? getPluginInstallPath;
 			const pluginDir = getInstallPath(this.__pluginId);
 			if (!pluginDir) {
+				remoteLog('upgrade.no-install-path');
 				this.__logger.warn?.('[auto-upgrade] Cannot determine plugin install path');
 				return;
 			}
@@ -245,6 +249,7 @@ export class AutoUpgradeScheduler {
 			await writeLock(child.pid);
 		}
 		catch (err) {
+			remoteLog(`upgrade.check-failed msg=${err.message}`);
 			this.__logger.warn?.(`[auto-upgrade] Check failed: ${err.message}`);
 		}
 		finally {

package/src/common/gateway-notify.js

@@ -15,16 +15,33 @@ export function escapeJsonForCmd(json) {
 /**
  * 通过 spawn 调用 `openclaw gateway call <method> --json`
  *
- * 背景：openclaw CLI 在完成 gateway RPC 后，因 WebSocket handle 未清理，
- * 进程不会自然退出。execSync 会一直阻塞直到超时，导致误报失败。
+ * ## 设计背景
  *
- * 策略：
- * 1. spawn 子进程，监听 stdout
- * 2. 解析 JSON 输出判断 RPC 是否成功
- * 3. 检测到输出后延迟 KILL_DELAY_MS 再 kill（给进程自然退出的机会）
- * 4. 无论成功失败，最终都主动 kill 子进程
+ * openclaw CLI 完成 gateway RPC 后，因 GatewayClient（WebSocket）handle 未完全销毁，
+ * 事件循环仍活跃，进程不会自然退出。早期使用 execSync 会阻塞等待进程退出而非输出完成，
+ * 导致 RPC 实际在 ~2s 内成功，但 10s 超时后误报 100% 失败。
  *
- * @param {string} method - gateway method 名（如 coclaw.refreshBridge）
+ * ## 策略
+ *
+ * 1. spawn 子进程执行 `openclaw gateway call <method> --json`
+ * 2. 监听 stdout，解析 JSON 输出判断 RPC 成功/失败
+ * 3. 检测到完整 JSON 后启动 KILL_DELAY_MS grace period 等待自然退出
+ * 4. 总超时默认 NOTIFY_TIMEOUT_MS（注册 CLI 路径覆盖为 30s）
+ * 5. 无论成功失败，最终都主动 kill 子进程
+ *
+ * grace period 设计：openclaw 进程因 WS handle 滞留可能 10s+ 才退出，
+ * 延迟 kill 是为兼容未来 OpenClaw 修复 WS 清理后进程能优雅退出的场景。
+ *
+ * ## stdout 判断策略
+ *
+ * `openclaw gateway call --json` 直接输出 method 的 result payload（respond 第二参数），
+ * 而非 gateway 协议层 { ok, result, error } 包装：
+ * - 有 stdout + 可解析 JSON → RPC 成功
+ * - 有 stdout + 非 JSON → 也视为成功（兜底）
+ * - 无 stdout + 非零退出码 → RPC 失败
+ * - 无 stdout + 超时 → RPC 失败
+ *
+ * @param {string} method - gateway method 名（如 coclaw.bind）
  * @param {Function} [spawnFn] - 可注入的 spawn 函数（测试用）
  * @param {object} [opts] - 可选配置（测试用）
  * @param {number} [opts.timeoutMs] - 总超时毫秒数

package/src/common/messages.js

@@ -17,16 +17,6 @@ export function notBound() {
 	return 'Not bound. Nothing to unbind.';
 }
 
-export function gatewayNotified(action) {
-	return action === 'refresh'
-		? 'Bridge connection refreshed.'
-		: 'Bridge connection stopped.';
-}
-
-export function gatewayNotifyFailed() {
-	return 'Note: could not notify the running gateway. If it is running, restart it manually.';
-}
-
 export function claimCodeCreated({ code, appUrl, expiresMinutes }) {
 	return [
 		`Claim code: ${code}`,

package/src/config.js

@@ -7,10 +7,10 @@ import { atomicWriteJsonFile } from './utils/atomic-write.js';
 import { createMutex } from './utils/mutex.js';
 
 export const DEFAULT_ACCOUNT_ID = 'default';
-const CHANNEL_ID = 'coclaw';
+export const CHANNEL_ID = 'coclaw';
 const BINDINGS_FILENAME = 'bindings.json';
 
-function resolveStateDir() {
+export function resolveStateDir() {
 	const rt = getRuntime();
 	if (rt?.state?.resolveStateDir) {
 		return rt.state.resolveStateDir();
@@ -42,8 +42,10 @@ async function readJson(filePath) {
 	try {
 		return JSON.parse(raw);
 	}
-	catch {
+	catch (err) {
 		// 文件损坏，删除后当空文件处理
+		/* c8 ignore next -- ?./?? fallback */
+		console.warn?.(`[coclaw] corrupt bindings file deleted: ${filePath} (${String(err?.message ?? err)})`);
 		await fs.unlink(filePath).catch(() => {});
 		return {};
 	}

package/src/device-identity.js

@@ -115,8 +115,10 @@ export function loadOrCreateDeviceIdentity(filePath) {
 			}
 		}
 	}
-	catch {
-		// 读取/解析失败时重新生成
+	catch (err) {
+		// 读取/解析失败时重新生成（将产生新 deviceId，需重新 enroll）
+		/* c8 ignore next -- ?./?? fallback */
+		console.warn?.(`[coclaw] device identity read failed, regenerating: ${String(err?.message ?? err)}`);
 	}
 
 	const identity = generateIdentity();

package/src/plugin-version.js

@@ -0,0 +1,18 @@
+import fs from 'node:fs/promises';
+import nodePath from 'node:path';
+
+// 延迟读取 + 缓存：避免模块加载时 package.json 损坏导致插件整体无法注册
+let __pluginVersion = null;
+export async function getPluginVersion() {
+	if (__pluginVersion) return __pluginVersion;
+	try {
+		const pkgPath = nodePath.resolve(import.meta.dirname, '..', 'package.json');
+		const raw = await fs.readFile(pkgPath, 'utf8');
+		__pluginVersion = JSON.parse(raw).version ?? 'unknown';
+	} catch {
+		return 'unknown';
+	}
+	return __pluginVersion;
+}
+// 测试用：重置缓存
+export function __resetPluginVersion() { __pluginVersion = null; }