@coclaw/openclaw-coclaw 0.15.0 → 0.17.0

package/README.md

@@ -172,22 +172,14 @@ openclaw gateway call coclaw.upgradeHealth --json
 
 ## WebRTC 实现
 
-插件支持两个 WebRTC 实现，运行时自动选择：
+插件在运行时按优先级选择 WebRTC 实现：
 
-1. **node-datachannel**（首选）— 基于 libdatachannel 的工业级实现，通过 vendor 预编译 native binary 部署。
-2. **werift**（回退）— 纯 JavaScript 实现，作为 node-datachannel 加载失败时的兜底。
+1. **pion**（主力）— 通过 `@coclaw/pion-node` SDK 驱动 Go 侧 pion-ipc 进程，实现完整 WebRTC 能力。
+2. **werift**（回退）— 纯 JavaScript 实现，作为 pion 加载失败时的兜底。
 
-选择结果通过 remoteLog 上报（`ndc.loaded` 或 `ndc.using-werift`）。
+选择结果通过 `bridge.started` / `coclaw.env impl=...` 日志上报。
 
-### 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` 字段包含在发布包中。
+> `ndc-preloader.js`（node-datachannel 路径）的代码仍保留但已摘除 `node-datachannel` 依赖和 vendor 预编译包（2026-04-19）——运行时必然走 fallback 到 werift，待 pion 在全部线上平台稳定观察期结束后与 werift 一并移除。
 
 ## 运行与排障日志
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",
@@ -32,7 +32,6 @@
     "!src/**/*.test.js",
     "!src/mock-server.helper.js",
     "openclaw.plugin.json",
-    "vendor/ndc-prebuilds/**",
     "LICENSE"
   ],
   "main": "index.js",
@@ -59,8 +58,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.2",
-    "@coclaw/pion-node": "^0.1.2",
+    "@coclaw/pion-node": "^0.1.3",
     "werift": "^0.19.0",
     "ws": "^8.19.0"
   },

package/src/auto-upgrade/registry-fallback.js

@@ -0,0 +1,61 @@
+/**
+ * registry-fallback.js — npm registry 反向兜底
+ *
+ * 升级首次失败（timeout/429/网络异常等）后，按当前用户的 registry 选反方向源
+ * 再试一次：用户原本走 npmmirror 卡住时切到 npmjs；走 npmjs 卡住（如 IP 段被
+ * 限流）时切到 npmmirror。两侧任一可用即能脱困。
+ */
+import { execFile as nodeExecFile } from 'node:child_process';
+
+export const NPMJS_REGISTRY = 'https://registry.npmjs.org/';
+export const NPMMIRROR_REGISTRY = 'https://registry.npmmirror.com/';
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/**
+ * 读取当前 npm 默认 registry（继承用户 .npmrc 与 env）
+ *
+ * 失败 / 空字符串均回退到 npmjs URL；上层 pickFallbackRegistry 会据此选 npmmirror。
+ * 即"npm 命令本身坏掉时盲选 npmmirror"——在 worker 这种"反正只重试一次"的场景下
+ * 是合理代价。
+ *
+ * 调用方应优先传入 execFileFn 以避免在测试环境拉起真实 npm 进程。
+ * @param {object} [opts]
+ * @param {Function} [opts.execFileFn]
+ * @param {number} [opts.timeoutMs]
+ * @returns {Promise<string>}
+ */
+export function getCurrentNpmRegistry(opts) {
+	/* c8 ignore next -- ?./?? fallback */
+	const doExecFile = opts?.execFileFn ?? nodeExecFile;
+	/* c8 ignore next -- ?? fallback */
+	const timeout = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	return new Promise((resolve) => {
+		doExecFile('npm', ['config', 'get', 'registry'], {
+			timeout,
+			shell: process.platform === 'win32',
+		}, (err, stdout) => {
+			if (err) { resolve(NPMJS_REGISTRY); return; }
+			const raw = String(stdout).trim();
+			resolve(raw || NPMJS_REGISTRY);
+		});
+	});
+}
+
+/**
+ * 根据当前 registry 选反向兜底：
+ * - 含 `npmmirror.com` → 切到 npmjs
+ * - 其他（含 npmjs / cnpmjs.org / 自建 / 非字符串等异常输入） → 一律切到 npmmirror
+ *
+ * "反向"语义只严格区分 npmmirror，因为它是国内绝对主流；其他国内镜像（cnpmjs 等）
+ * 当前直接切到 npmmirror（同方向但换实例），属于"换源"兜底而非真正反向，是有意为之
+ * 的简化。
+ * @param {string} current
+ * @returns {string}
+ */
+export function pickFallbackRegistry(current) {
+	if (typeof current === 'string' && /npmmirror\.com/i.test(current)) {
+		return NPMJS_REGISTRY;
+	}
+	return NPMMIRROR_REGISTRY;
+}

package/src/auto-upgrade/updater-check.js

@@ -2,7 +2,7 @@
  * updater-check.js — 版本检查
  *
  * 通过 `npm view` 查询 registry 最新版本，与本地 package.json 对比。
- * 选择 npm view 而非直接 fetch registry API，是因为它自动继承用户完整的
+ * 选择 npm view 而非自己打 registry HTTP 接口，是因为它自动继承用户完整的
  * npm 环境配置（registry 镜像、proxy、scoped registry、auth token 等），
  * 避免自行解析多层 .npmrc 的复杂性。每小时一次的频率下进程启动开销可忽略。
  */

package/src/auto-upgrade/updater.js

@@ -7,7 +7,10 @@ import { readState, resolveStateDir, writeState } from './state.js';
 import { getRuntime } from '../runtime.js';
 import { remoteLog } from '../remote-log.js';
 
-const INITIAL_DELAY_MS = 5 * 60 * 1000; // 5 分钟
+// 首次检查延迟较长：失败时由 worker 触发 gateway restart，scheduler 重启后会重新计时；
+// 60 分钟基线（实际随机 60-120 分钟）能把"失败→重启→再次检查"的循环周期拉长，
+// 避免连续升级失败时 gateway 在短时间内反复被打扰。
+const INITIAL_DELAY_MS = 60 * 60 * 1000; // 60 分钟
 const CHECK_INTERVAL_MS = 60 * 60 * 1000; // 1 小时
 const CHANNEL_ID = 'coclaw';
 const LOCK_FILENAME = 'upgrade.lock';

package/src/auto-upgrade/worker.js

@@ -17,26 +17,35 @@ import { parseArgs } from 'node:util';
 import { createBackup, restoreFromBackup, removeBackup } from './worker-backup.js';
 import { verifyUpgrade, waitForGateway } from './worker-verify.js';
 import { addSkippedVersion, updateLastUpgrade, appendLog } from './state.js';
+import { getCurrentNpmRegistry, pickFallbackRegistry } from './registry-fallback.js';
 
 const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.-]+)?$/;
+// 单次 plugins update 上限：包含 npm install 大型 native deps，慢网络 + 弱机器需较长时间
+const UPDATE_TIMEOUT_MS = 10 * 60 * 1000;
 
 /**
  * 执行 openclaw plugins update
+ *
+ * 仅支持 source === "npm" 的安装（updater 已做前置过滤）。
+ * env 由调用方决定：缺省时子进程继承当前 process.env（含用户 .npmrc 自动生效）；
+ * 显式传入时用于覆盖 registry 等 npm 配置以做兜底重试。
  * @param {string} pluginId - 插件 ID
  * @param {object} [opts]
  * @param {Function} [opts.execFileFn]
+ * @param {NodeJS.ProcessEnv} [opts.env]
  * @returns {Promise<void>}
  */
-// openclaw plugins update 内部实现为 staged backup-and-replace，
-// 仅支持 source === "npm" 的安装（updater 已做前置过滤）
 function runPluginUpdate(pluginId, opts) {
 	/* c8 ignore next -- ?./?? fallback */
 	const doExecFile = opts?.execFileFn ?? nodeExecFile;
 	return new Promise((resolve, reject) => {
-		doExecFile('openclaw', ['plugins', 'update', pluginId], {
-			timeout: 120_000,
+		const execOpts = {
+			timeout: UPDATE_TIMEOUT_MS,
 			shell: process.platform === 'win32',
-		}, (err) => {
+		};
+		// 不传 env 时让 Node 默认继承父进程；显式 env 才覆盖
+		if (opts?.env) execOpts.env = opts.env;
+		doExecFile('openclaw', ['plugins', 'update', pluginId], execOpts, (err) => {
 			if (err) reject(new Error(`plugins update failed: ${err.message}`));
 			else resolve();
 		});
@@ -110,21 +119,44 @@ export async function runUpgrade({ pluginDir, fromVersion, toVersion, pluginId,
 	await createBackup(pluginDir);
 	log('[upgrade-worker] Backup created');
 
-	// 2. 执行升级
+	// 2. 执行升级（首次按用户原 env，失败后用反向 mirror 重试一次）
 	log('[upgrade-worker] Running plugins update...');
+	let updateErr = null;
 	try {
 		await runPluginUpdate(pluginId, opts);
+		log('[upgrade-worker] Update command completed');
+	}
+	catch (firstErr) {
+		log(`[upgrade-worker] Update command failed: ${firstErr.message}`);
+		updateErr = firstErr;
+		try {
+			const current = await getCurrentNpmRegistry(opts);
+			const fallback = pickFallbackRegistry(current);
+			log(`[upgrade-worker] Retrying with fallback registry: ${fallback}`);
+			// npm 同时认 npm_config_X 与 NPM_CONFIG_X 两种 env 命名，
+			// 若用户已 export 大写版（国内常见），仅 set 小写不足以覆盖，
+			// 显式 delete 大写避免 retry 仍走原 registry。
+			const retryEnv = { ...process.env };
+			delete retryEnv.NPM_CONFIG_REGISTRY;
+			retryEnv.npm_config_registry = fallback;
+			await runPluginUpdate(pluginId, { ...opts, env: retryEnv });
+			log('[upgrade-worker] Update command completed on retry');
+			updateErr = null;
+		}
+		catch (retryErr) {
+			log(`[upgrade-worker] Retry with fallback registry failed: ${retryErr.message}`);
+			updateErr = retryErr;
+		}
 	}
-	catch (updateErr) {
-		// 升级命令本身失败（可能是瞬态故障），恢复备份但不标记版本为 skipped
-		log(`[upgrade-worker] Update command failed: ${updateErr.message}`);
+
+	if (updateErr) {
+		// 两次都失败仍按瞬态故障处理（保留原 skipVersion: false 设计意图）
 		await handleRollback({
 			pluginDir, fromVersion, toVersion, pluginId, pkgName,
 			error: updateErr.message, skipVersion: false, opts, log,
 		});
 		return;
 	}
-	log('[upgrade-worker] Update command completed');
 
 	// 3. 等待 gateway 重启并验证
 	log('[upgrade-worker] Verifying upgrade...');

package/src/webrtc/ndc-preloader.js

@@ -46,6 +46,7 @@ export function defaultResolvePaths(platformKey, pluginRoot) {
 	// 定位 node-datachannel 包根：从入口路径向上查找 package.json
 	const require = createRequire(nodePath.join(pluginRoot, 'package.json'));
 	const entryPath = require.resolve('node-datachannel');
+	/* c8 ignore start -- node-datachannel 依赖已于 2026-04-19 摘除，以下路径仅在 ndc 实际安装时命中；代码保留作为过渡期 fallback 自然失败锚点，待 ndc-preloader 整体清理时一并删除 */
 	let pkgRoot = nodePath.dirname(entryPath);
 	while (pkgRoot !== nodePath.dirname(pkgRoot)) {
 		try {
@@ -58,6 +59,7 @@ export function defaultResolvePaths(platformKey, pluginRoot) {
 	const dest = nodePath.join(destDir, 'node_datachannel.node');
 
 	return { src, dest, destDir };
+	/* c8 ignore stop */
 }
 
 /**

package/src/webrtc/webrtc-peer.js

@@ -6,13 +6,13 @@ import { remoteLog } from '../remote-log.js';
 // 用于诊断 dump：过大会撑爆 remoteLog 单帧，20 足以覆盖典型多文件传输会话。
 const FILE_CHANNEL_HISTORY_LIMIT = 20;
 
-// Failed session 保留 24 小时，支持 Capacitor 长时间后台恢复后 ICE restart。
+// Failed session 保留 12 小时，支持 Capacitor 后台恢复后 ICE restart。
 // 超时后 session 被回收释放 IPC listeners 和 Go 侧资源。
-const FAILED_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
+const FAILED_SESSION_TTL_MS = 12 * 60 * 60 * 1000;
 
 // Session 总数上限（活跃 + failed）。溢出时淘汰最旧的 failed session。
-// 20 足以覆盖多 UI 实例（浏览器多标签 + 移动端）的典型场景。
-const MAX_SESSIONS = 20;
+// 10 足以覆盖多 UI 实例（浏览器多标签 + 移动端）的典型场景。
+const MAX_SESSIONS = 10;
 
 /**
  * 管理多个 WebRTC PeerConnection（以 connId 为粒度）。
@@ -110,9 +110,32 @@ export class WebRtcPeer {
 		}
 	}
 
+	/**
+	 * 向指定 connId 的 rpc DC 单播一个 JSON 帧（不走 server 中转）。
+	 * 若 session/DC 未就绪返回 false，由调用方决定是否重试。
+	 * @param {string} connId
+	 * @param {object} payload - 完整的 JSON 帧（通常是 { type: 'event', event, payload }）
+	 * @returns {boolean} true=已入队发送，false=未能发送（session 不存在 / DC 未 open）
+	 */
+	sendTo(connId, payload) {
+		const session = this.__sessions.get(connId);
+		if (!session) return false;
+		const q = session.rpcSendQueue;
+		if (!q || session.rpcChannel?.readyState !== 'open') return false;
+		try {
+			q.send(JSON.stringify(payload));
+			return true;
+		} catch (err) {
+			this.__logDebug(`[${connId}] sendTo failed: ${err.message}`);
+			return false;
+		}
+	}
+
 	async __handleOffer(msg) {
 		const connId = msg.fromConnId;
 		const isIceRestart = !!msg.payload?.iceRestart;
+		const credRemain = this.__credRemainSec(msg.turnCreds);
+		const credRemainStr = credRemain ?? 'none';
 
 		// ICE restart：在现有 PC 上重新协商，保持 DTLS session
 		if (isIceRestart) {
@@ -120,7 +143,7 @@ export class WebRtcPeer {
 			if (existing) {
 				// 仅已验证支持 ICE restart 的 impl 放行，其余立即 reject 让 UI 走 rebuild
 				if (this.__impl !== 'pion') {
-					this.__remoteLog(`rtc.ice-restart-unsupported conn=${connId} impl=${this.__impl}`);
+					this.__remoteLog(`rtc.ice-restart-unsupported conn=${connId} impl=${this.__impl} credRemain=${credRemainStr}`);
 					this.logger.info?.(`${this.__rtcTag} ICE restart rejected: impl=${this.__impl} not verified`);
 					this.__onSend({
 						type: 'rtc:restart-rejected',
@@ -134,7 +157,7 @@ export class WebRtcPeer {
 					clearTimeout(existing.__failedTimer);
 					existing.__failedTimer = null;
 				}
-				this.__remoteLog(`rtc.ice-restart conn=${connId}`);
+				this.__remoteLog(`rtc.ice-restart conn=${connId} credRemain=${credRemainStr}`);
 				this.logger.info?.(`${this.__rtcTag} ICE restart offer from ${connId}, renegotiating`);
 				try {
 					await existing.pc.setRemoteDescription({ type: 'offer', sdp: msg.payload.sdp });
@@ -156,7 +179,7 @@ export class WebRtcPeer {
 					return;
 				} catch (err) {
 					// ICE restart 协商失败 → reject，不 fall through
-					this.__remoteLog(`rtc.ice-restart-failed conn=${connId}`);
+					this.__remoteLog(`rtc.ice-restart-failed conn=${connId} credRemain=${credRemainStr}`);
 					this.logger.warn?.(`${this.__rtcTag} ICE restart failed for ${connId}: ${err?.message}`);
 					this.__onSend({
 						type: 'rtc:restart-rejected',
@@ -171,7 +194,7 @@ export class WebRtcPeer {
 				}
 			}
 			// 无 session → reject（plugin 可能已重启）
-			this.__remoteLog(`rtc.ice-restart-no-session conn=${connId}`);
+			this.__remoteLog(`rtc.ice-restart-no-session conn=${connId} credRemain=${credRemainStr}`);
 			this.logger.warn?.(`${this.__rtcTag} ICE restart from ${connId} but no session, rejecting`);
 			this.__onSend({
 				type: 'rtc:restart-rejected',
@@ -307,6 +330,9 @@ export class WebRtcPeer {
 				if (pair) {
 					this.__logNominatedPair(connId, pair);
 				}
+				// ICE restart 或初次选中都会触发；让出一次 CPU 后再单播 transport 信息。
+				// 签名去重保证 pair 不变时不会重复发送。
+				queueMicrotask(() => this.__sendPeerTransport(connId));
 			};
 		}
 
@@ -424,6 +450,12 @@ export class WebRtcPeer {
 		dc.onopen = () => {
 			this.__remoteLog(`dc.open conn=${connId} label=${dc.label}`);
 			this.logger.info?.(`${this.__rtcTag} [${connId}] DataChannel "${dc.label}" opened`);
+			// rpc DC 建立后，把本端 transport 信息单播给 UI。
+			// queueMicrotask 让出一次 CPU：确保 pion 侧 selectedCandidatePair setter 已 assign，
+			// 同时避免在 onopen 同步栈里触发可能的重入。
+			if (dc.label === 'rpc') {
+				queueMicrotask(() => this.__sendPeerTransport(connId));
+			}
 		};
 		dc.onclose = () => {
 			this.__remoteLog(`dc.closed conn=${connId} label=${dc.label}`);
@@ -481,16 +513,65 @@ export class WebRtcPeer {
 	}
 
 	__logNominatedPair(connId, pair) {
-		const localInfo = `${pair.local?.type ?? '?'} ${pair.local?.address ?? pair.local?.host ?? '?'}:${pair.local?.port ?? '?'}`;
-		const remoteInfo = `${pair.remote?.type ?? '?'} ${pair.remote?.address ?? pair.remote?.host ?? '?'}:${pair.remote?.port ?? '?'}`;
+		const l = pair.local, r = pair.remote;
+		const lProto = (l?.protocol ?? '?').toLowerCase();
+		const rProto = (r?.protocol ?? '?').toLowerCase();
+		const lRelay = l?.relayProtocol ? `(${String(l.relayProtocol).toLowerCase()})` : '';
+		const localInfo = `${l?.type ?? '?'}/${lProto}${lRelay} ${l?.address ?? l?.host ?? '?'}:${l?.port ?? '?'}`;
+		const remoteInfo = `${r?.type ?? '?'}/${rProto} ${r?.address ?? r?.host ?? '?'}:${r?.port ?? '?'}`;
 		this.__remoteLog(`rtc.ice-nominated conn=${connId} local=${localInfo} remote=${remoteInfo}`);
 		this.logger.info?.(`${this.__rtcTag} [${connId}] ICE nominated: local=${localInfo} remote=${remoteInfo}`);
 	}
 
+	/**
+	 * 把当前 session 本端 candidate 的 transport 信息（type/protocol/relayProtocol）
+	 * 通过 coclaw.rtc.peerTransport 事件单播给对应 UI。已内置签名去重，
+	 * 同一签名不会重复发送；发送失败（DC 未 open）时回滚签名允许后续重试。
+	 *
+	 * @param {string} connId
+	 */
+	__sendPeerTransport(connId) {
+		const session = this.__sessions.get(connId);
+		if (!session) return;
+		const local = session.pc?.selectedCandidatePair?.local;
+		if (!local) return; // nominated pair 尚未产生
+		const payload = {
+			candidateType: local.type ?? 'unknown',
+			protocol: String(local.protocol ?? 'udp').toLowerCase(),
+			relayProtocol: local.relayProtocol
+				? String(local.relayProtocol).toLowerCase()
+				: null,
+		};
+		const sig = `${payload.candidateType}|${payload.protocol}|${payload.relayProtocol ?? ''}`;
+		if (session.__lastPeerTransportSig === sig) return;
+		session.__lastPeerTransportSig = sig;
+		const ok = this.sendTo(connId, {
+			type: 'event',
+			event: 'coclaw.rtc.peerTransport',
+			payload,
+		});
+		if (!ok) {
+			// DC 尚未 open，回滚签名以便 dc.onopen 再次触发时重发
+			session.__lastPeerTransportSig = null;
+			return;
+		}
+		this.__remoteLog(`rtc.peer-transport conn=${connId} type=${payload.candidateType} proto=${payload.protocol} relay=${payload.relayProtocol ?? '-'}`);
+	}
+
 	__remoteLog(msg) {
 		remoteLog(this.__impl ? `${msg} rtc=${this.__impl}` : msg);
 	}
 
+	// 解析 HMAC turnCreds 中的剩余秒数（username 形如 "<expireAt>:<userId>"）；
+	// 负值表示已过期；解析失败或 turnCreds 缺失返回 null。仅用于 ICE restart 日志诊断。
+	__credRemainSec(turnCreds) {
+		const username = turnCreds?.username;
+		if (typeof username !== 'string') return null;
+		const expireAt = Number(username.split(':')[0]);
+		if (!Number.isFinite(expireAt)) return null;
+		return expireAt - Math.floor(Date.now() / 1000);
+	}
+
 	/** 淘汰最旧的 failed session（Map 迭代序 ≈ 创建时间序），用于 queue length 限制 */
 	__evictOldestFailed() {
 		for (const [connId, session] of this.__sessions) {