@coclaw/openclaw-coclaw 0.1.7 → 0.2.0

package/README.md

@@ -4,6 +4,7 @@ CoClaw 的 OpenClaw 插件（npm: `@coclaw/openclaw-coclaw`，plugin id: `opencl
 
 - **transport bridge** — CoClaw server 与 OpenClaw gateway 之间的实时消息桥接
 - **session-manager** — 会话列表/读取能力（`nativeui.sessions.listAll` / `nativeui.sessions.get`）
+- **auto-upgrade** — 从 npm 安装的插件自动检查并升级到最新版本
 
 ## 安装与模式切换
 
@@ -46,11 +47,10 @@ pnpm run prerelease -- --upgrade # 升级验证（先装 npm 旧版，再用本
 ### 发布到 npm
 
 ```bash
-pnpm run release
+pnpm run release                 # 默认：verify → 发布 → 轮询确认
+pnpm run release -- --prerelease # 含预发布验证（pack + 安装测试 + 发布）
 ```
 
-发布流程：预发布验证（自动） → npm 凭据检查 → dry-run → 发布 → 轮询确认生效。
-
 ### 检查发布状态
 
 ```bash
@@ -113,6 +113,24 @@ node ~/.openclaw/extensions/coclaw/src/cli.js unbind --server <url>
 - `config.js` 是读写绑定信息的唯一入口。
 - 绑定时不提交 bot `name`；server 通过 gateway WebSocket 获取 OpenClaw 实例名。若未设置实例名，前端回退显示 `OpenClaw`。
 
+## 自动升级
+
+从 npm 安装的插件（`source: "npm"`）会自动检查并升级。link 模式和 tarball 安装不触发自动升级。
+
+- **检查频率**：gateway 启动后延迟 5~10 分钟首次检查，之后每 1 小时
+- **升级方式**：独立 detached 进程执行，不阻塞 gateway
+- **安全机制**：升级前物理备份；升级后验证 gateway + 插件状态；验证失败自动回滚
+- **状态文件**：`~/.openclaw/coclaw/upgrade-state.json`（运行时状态）、`upgrade-log.jsonl`（升级历史）
+
+可通过 gateway RPC 检查升级模块状态：
+
+```bash
+openclaw gateway call coclaw.upgradeHealth --json
+# → {"version":"0.1.7"}
+```
+
+详见设计文档 `docs/auto-upgrade.md`。
+
 ## 运行与排障日志
 
 ### 日志级别建议

package/index.js

@@ -6,6 +6,8 @@ import { coclawChannelPlugin } from './src/channel-plugin.js';
 import { refreshRealtimeBridge, startRealtimeBridge, stopRealtimeBridge } from './src/realtime-bridge.js';
 import { setRuntime } from './src/runtime.js';
 import { createSessionManager } from './src/session-manager/manager.js';
+import { AutoUpgradeScheduler } from './src/auto-upgrade/updater.js';
+import { getPackageInfo } from './src/auto-upgrade/updater-check.js';
 
 
 function parseCommandArgs(args) {
@@ -104,6 +106,23 @@ const plugin = {
 			}
 		});
 
+		api.registerGatewayMethod('coclaw.upgradeHealth', async ({ respond }) => {
+			try {
+				const { version } = await getPackageInfo();
+				respond(true, { version });
+			}
+			catch (err) {
+				respondError(respond, err);
+			}
+		});
+
+		const scheduler = new AutoUpgradeScheduler({ pluginId: api.id, logger });
+		api.registerService({
+			id: 'coclaw-auto-upgrade',
+			start() { scheduler.start(); },
+			stop() { scheduler.stop(); },
+		});
+
 		api.registerCli(registerCoclawCli, { commands: ['coclaw'] });
 
 		api.registerCommand({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",

package/src/auto-upgrade/state.js

@@ -0,0 +1,127 @@
+/**
+ * state.js — upgrade-state.json 与 upgrade-log.jsonl 读写
+ *
+ * 状态文件存储在 OpenClaw state 目录下（~/.openclaw/coclaw/），
+ * 与 bindings.json 共享同一目录。路径解析优先级：
+ * 1. runtime.state.resolveStateDir()（gateway 进程内）
+ * 2. OPENCLAW_STATE_DIR 环境变量（worker 进程，由 spawner 传入）
+ * 3. ~/.openclaw（兜底默认值）
+ */
+import fs from 'node:fs/promises';
+import nodePath from 'node:path';
+import os from 'node:os';
+
+import { getRuntime } from '../runtime.js';
+
+const CHANNEL_ID = 'coclaw';
+const STATE_FILENAME = 'upgrade-state.json';
+const LOG_FILENAME = 'upgrade-log.jsonl';
+const LOG_MAX_LINES = 200;
+const LOG_KEEP_LINES = 100;
+
+export function resolveStateDir() {
+	const rt = getRuntime();
+	if (rt?.state?.resolveStateDir) {
+		return rt.state.resolveStateDir();
+	}
+	return process.env.OPENCLAW_STATE_DIR
+		? nodePath.resolve(process.env.OPENCLAW_STATE_DIR)
+		: nodePath.join(os.homedir(), '.openclaw');
+}
+
+export function getStatePath() {
+	return nodePath.join(resolveStateDir(), CHANNEL_ID, STATE_FILENAME);
+}
+
+export function getLogPath() {
+	return nodePath.join(resolveStateDir(), CHANNEL_ID, LOG_FILENAME);
+}
+
+/**
+ * 读取 upgrade-state.json
+ * @returns {Promise<{ skippedVersions?: string[], lastCheck?: string, lastUpgrade?: object }>}
+ */
+export async function readState() {
+	const filePath = getStatePath();
+	try {
+		const raw = await fs.readFile(filePath, 'utf8');
+		const trimmed = raw.trim();
+		if (!trimmed) return {};
+		return JSON.parse(trimmed);
+	}
+	catch (err) {
+		if (err?.code === 'ENOENT') return {};
+		throw err;
+	}
+}
+
+/**
+ * 写入 upgrade-state.json（完整覆盖）
+ * @param {object} state
+ */
+export async function writeState(state) {
+	const filePath = getStatePath();
+	await fs.mkdir(nodePath.dirname(filePath), { recursive: true });
+	await fs.writeFile(filePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * 将版本加入 skippedVersions
+ * @param {string} version
+ */
+export async function addSkippedVersion(version) {
+	const state = await readState();
+	const skipped = Array.isArray(state.skippedVersions) ? state.skippedVersions : [];
+	if (!skipped.includes(version)) {
+		skipped.push(version);
+	}
+	state.skippedVersions = skipped;
+	await writeState(state);
+}
+
+/**
+ * 更新 lastCheck 时间戳
+ */
+export async function updateLastCheck() {
+	const state = await readState();
+	state.lastCheck = new Date().toISOString();
+	await writeState(state);
+}
+
+/**
+ * 更新 lastUpgrade 信息
+ * @param {{ from: string, to: string, result: string }} info
+ */
+export async function updateLastUpgrade(info) {
+	const state = await readState();
+	state.lastUpgrade = { ...info, ts: new Date().toISOString() };
+	await writeState(state);
+}
+
+/**
+ * 追加升级日志
+ * @param {{ from: string, to: string, result: string, error?: string }} entry
+ */
+export async function appendLog(entry) {
+	const filePath = getLogPath();
+	await fs.mkdir(nodePath.dirname(filePath), { recursive: true });
+	const line = JSON.stringify({ ts: new Date().toISOString(), ...entry });
+	await fs.appendFile(filePath, `${line}\n`, 'utf8');
+	await trimLog(filePath);
+}
+
+/**
+ * 日志超过 LOG_MAX_LINES 时截断，保留最近 LOG_KEEP_LINES 行
+ */
+async function trimLog(filePath) {
+	try {
+		const content = await fs.readFile(filePath, 'utf8');
+		const lines = content.split('\n').filter(Boolean);
+		if (lines.length <= LOG_MAX_LINES) return;
+		const kept = lines.slice(-LOG_KEEP_LINES);
+		await fs.writeFile(filePath, `${kept.join('\n')}\n`, 'utf8');
+	}
+	catch {
+		// 截断失败不影响主流程
+	}
+}

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

@@ -0,0 +1,103 @@
+/**
+ * updater-check.js — 版本检查
+ *
+ * 通过 `npm view` 查询 registry 最新版本，与本地 package.json 对比。
+ * 选择 npm view 而非直接 fetch registry API，是因为它自动继承用户完整的
+ * npm 环境配置（registry 镜像、proxy、scoped registry、auth token 等），
+ * 避免自行解析多层 .npmrc 的复杂性。每小时一次的频率下进程启动开销可忽略。
+ */
+import { execFile as nodeExecFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import nodePath from 'node:path';
+
+import { readState, updateLastCheck } from './state.js';
+
+/**
+ * 读取本地 package.json 获取包名和版本号
+ * @param {string} [pluginDir] - 插件根目录（默认自动检测）
+ * @returns {Promise<{ name: string, version: string }>}
+ */
+export async function getPackageInfo(pluginDir) {
+	const dir = pluginDir ?? nodePath.resolve(import.meta.dirname, '../..');
+	const pkgPath = nodePath.join(dir, 'package.json');
+	const raw = await readFile(pkgPath, 'utf8');
+	const pkg = JSON.parse(raw);
+	return { name: pkg.name, version: pkg.version };
+}
+
+/**
+ * 查询 npm registry 上的最新版本
+ * @param {string} pkgName - npm 包名
+ * @param {object} [opts]
+ * @param {Function} [opts.execFileFn] - 可注入的 execFile（测试用）
+ * @returns {Promise<string>}
+ */
+export async function getLatestVersion(pkgName, opts) {
+	const doExecFile = opts?.execFileFn ?? nodeExecFile;
+	return new Promise((resolve, reject) => {
+		doExecFile('npm', ['view', pkgName, 'version'], {
+			timeout: 30_000,
+			shell: true,
+		}, (err, stdout) => {
+			if (err) {
+				reject(new Error(`npm view failed: ${err.message}`));
+				return;
+			}
+			const version = String(stdout).trim();
+			if (!version) {
+				reject(new Error('npm view returned empty version'));
+				return;
+			}
+			resolve(version);
+		});
+	});
+}
+
+/**
+ * 简易 semver 比较：a > b 返回 true
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function isNewerVersion(a, b) {
+	// 先比较 major.minor.patch（去掉 pre-release 后缀）
+	const parse = (v) => v.replace(/-.*$/, '').split('.').map(Number);
+	const pa = parse(a);
+	const pb = parse(b);
+	for (let i = 0; i < 3; i++) {
+		if ((pa[i] ?? 0) > (pb[i] ?? 0)) return true;
+		if ((pa[i] ?? 0) < (pb[i] ?? 0)) return false;
+	}
+	// x.y.z 相同时：release > pre-release（semver 规则）
+	const aHasPre = a.includes('-');
+	const bHasPre = b.includes('-');
+	if (bHasPre && !aHasPre) return true;
+	return false;
+}
+
+/**
+ * 检查是否有可用更新
+ * @param {object} [opts]
+ * @param {Function} [opts.execFileFn] - 可注入的 execFile（测试用）
+ * @param {string} [opts.pluginDir] - 插件目录
+ * @returns {Promise<{ available: boolean, currentVersion: string, latestVersion?: string, pkgName: string }>}
+ */
+export async function checkForUpdate(opts) {
+	const { name: pkgName, version: currentVersion } = await getPackageInfo(opts?.pluginDir);
+	const latestVersion = await getLatestVersion(pkgName, opts);
+
+	await updateLastCheck();
+
+	if (!isNewerVersion(latestVersion, currentVersion)) {
+		return { available: false, currentVersion, pkgName };
+	}
+
+	// 检查是否在 skippedVersions 中（曾升级失败并回滚的版本）
+	const state = await readState();
+	const skipped = Array.isArray(state.skippedVersions) ? state.skippedVersions : [];
+	if (skipped.includes(latestVersion)) {
+		return { available: false, currentVersion, latestVersion, pkgName, skipped: true };
+	}
+
+	return { available: true, currentVersion, latestVersion, pkgName };
+}

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

@@ -0,0 +1,63 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import nodePath from 'node:path';
+import { resolveStateDir } from './state.js';
+
+const WORKER_FILENAME = 'worker.js';
+
+/**
+ * 获取 worker.js 的路径
+ * @returns {string}
+ */
+export function getWorkerPath() {
+	return nodePath.join(import.meta.dirname, WORKER_FILENAME);
+}
+
+/**
+ * 以 detached 进程方式启动 upgrade worker
+ *
+ * 使用 process.execPath 确保与 gateway 使用同一 node 版本。
+ * detached + unref 确保 gateway 进程不会等待 worker。
+ * 通过 -- 命名参数传递业务数据，worker 使用 util.parseArgs 解析。
+ *
+ * @param {object} params
+ * @param {string} params.pluginDir - 插件安装目录
+ * @param {string} params.fromVersion - 当前版本
+ * @param {string} params.toVersion - 目标版本
+ * @param {string} params.pluginId - 插件 ID
+ * @param {string} params.pkgName - npm 包名
+ * @param {object} [params.opts]
+ * @param {Function} [params.opts.spawnFn] - 可注入的 spawn（测试用）
+ * @param {Function} [params.logger]
+ * @returns {{ child: object }}
+ */
+export function spawnUpgradeWorker({ pluginDir, fromVersion, toVersion, pluginId, pkgName, opts, logger }) {
+	const log = typeof logger?.log === 'function' ? logger.log.bind(logger) : (logger ?? console.log);
+	const doSpawn = opts?.spawnFn ?? nodeSpawn;
+	const workerPath = getWorkerPath();
+
+	log(`[spawner] Spawning upgrade worker: ${fromVersion} → ${toVersion}`);
+
+	// 将 state dir 传递给 worker，确保 worker 写入正确的路径
+	const stateDir = resolveStateDir();
+	const env = { ...process.env };
+	if (stateDir) env.OPENCLAW_STATE_DIR = stateDir;
+
+	const child = doSpawn(process.execPath, [
+		workerPath,
+		'--pluginDir', pluginDir,
+		'--fromVersion', fromVersion,
+		'--toVersion', toVersion,
+		'--pluginId', pluginId,
+		'--pkgName', pkgName,
+	], {
+		detached: true,
+		stdio: 'ignore',
+		env,
+	});
+
+	child.unref();
+
+	log(`[spawner] Worker spawned (pid: ${child.pid})`);
+	return { child };
+}
+

package/src/auto-upgrade/updater.js

@@ -0,0 +1,254 @@
+import fs from 'node:fs/promises';
+import nodePath from 'node:path';
+
+import { checkForUpdate } from './updater-check.js';
+import { spawnUpgradeWorker } from './updater-spawn.js';
+import { resolveStateDir } from './state.js';
+import { getRuntime } from '../runtime.js';
+
+const INITIAL_DELAY_MS = 5 * 60 * 1000; // 5 分钟
+const CHECK_INTERVAL_MS = 60 * 60 * 1000; // 1 小时
+const CHANNEL_ID = 'coclaw';
+const LOCK_FILENAME = 'upgrade.lock';
+
+// ── upgrade.lock：保证同时最多一个 worker 进程 ──
+
+export function getLockPath() {
+	return nodePath.join(resolveStateDir(), CHANNEL_ID, LOCK_FILENAME);
+}
+
+/**
+ * 检查升级锁是否被持有（worker 进程是否存活）
+ *
+ * 若锁文件存在但 PID 已死（过期锁），顺手清理残留文件。
+ * @param {object} [opts]
+ * @param {object} [opts.logger]
+ * @returns {Promise<boolean>}
+ */
+export async function isUpgradeLocked(opts) {
+	const lockPath = getLockPath();
+	const logger = opts?.logger;
+	let raw;
+	try {
+		raw = await fs.readFile(lockPath, 'utf8');
+	}
+	catch {
+		return false; // 文件不存在，无需清理
+	}
+	try {
+		const lock = JSON.parse(raw);
+		if (!lock.pid) {
+			logger?.log?.('[auto-upgrade] Stale lock removed (missing pid)');
+			await fs.rm(lockPath, { force: true }).catch(() => {});
+			return false;
+		}
+		// signal 0 不发信号，仅检查进程存活性；进程不存在时抛异常
+		process.kill(lock.pid, 0);
+		return true;
+	}
+	catch {
+		// JSON 无效 / PID 已死 → 清理过期锁
+		logger?.log?.('[auto-upgrade] Stale lock removed (worker pid no longer alive)');
+		await fs.rm(lockPath, { force: true }).catch(() => {});
+		return false;
+	}
+}
+
+/**
+ * 写入升级锁（spawn worker 后调用）
+ * @param {number} pid - worker 进程 PID
+ */
+export async function writeUpgradeLock(pid) {
+	const lockPath = getLockPath();
+	await fs.mkdir(nodePath.dirname(lockPath), { recursive: true });
+	await fs.writeFile(
+		lockPath,
+		`${JSON.stringify({ pid, ts: new Date().toISOString() })}\n`,
+		'utf8',
+	);
+}
+
+/**
+ * 判断是否应跳过自动升级
+ *
+ * `openclaw plugins update` 仅对 source === "npm" 的安装生效。
+ * source 的可能值：
+ * - "npm"：从 npm registry 安装（生产环境，允许自动升级）
+ * - "path"：link 模式（本地开发，跳过）
+ * - "archive"：从 tarball 安装（跳过）
+ *
+ * @param {string} pluginId
+ * @returns {boolean} true 表示应跳过自动升级
+ */
+export function shouldSkipAutoUpgrade(pluginId) {
+	const rt = getRuntime();
+	if (!rt?.config?.loadConfig) return true;
+	try {
+		const config = rt.config.loadConfig();
+		const installInfo = config?.plugins?.installs?.[pluginId];
+		return installInfo?.source !== 'npm';
+	}
+	catch {
+		return true;
+	}
+}
+
+/**
+ * 获取插件安装路径
+ * @param {string} pluginId
+ * @returns {string|null}
+ */
+export function getPluginInstallPath(pluginId) {
+	const rt = getRuntime();
+	if (!rt?.config?.loadConfig) return null;
+	try {
+		const config = rt.config.loadConfig();
+		return config?.plugins?.installs?.[pluginId]?.installPath ?? null;
+	}
+	catch {
+		return null;
+	}
+}
+
+/**
+ * 自动升级调度器
+ */
+export class AutoUpgradeScheduler {
+	/** @type {ReturnType<typeof setTimeout>|null} */
+	__initialTimer = null;
+	/** @type {ReturnType<typeof setInterval>|null} */
+	__intervalTimer = null;
+	__running = false;
+	__checking = false;
+	__pluginId = null;
+	__logger = console;
+	__opts = {};
+
+	/**
+	 * @param {object} [params]
+	 * @param {string} [params.pluginId] - 插件 ID（来自 api.id）
+	 * @param {Function} [params.logger]
+	 * @param {object} [params.opts] - 测试注入选项
+	 * @param {number} [params.opts.initialDelayMs]
+	 * @param {number} [params.opts.checkIntervalMs]
+	 * @param {Function} [params.opts.execFileFn]
+	 * @param {Function} [params.opts.spawnFn]
+	 * @param {Function} [params.opts.shouldSkipFn]
+	 * @param {Function} [params.opts.getPluginInstallPathFn]
+	 */
+	constructor(params) {
+		if (params?.pluginId) this.__pluginId = params.pluginId;
+		if (params?.logger) this.__logger = params.logger;
+		if (params?.opts) this.__opts = params.opts;
+	}
+
+	/**
+	 * 启动调度器
+	 */
+	start() {
+		if (this.__running) return;
+		this.__running = true;
+
+		if (!this.__pluginId) {
+			this.__logger.warn?.('[auto-upgrade] Skipping: pluginId not provided');
+			this.__running = false;
+			return;
+		}
+
+		const shouldSkip = this.__opts.shouldSkipFn ?? shouldSkipAutoUpgrade;
+		if (shouldSkip(this.__pluginId)) {
+			this.__logger.log?.('[auto-upgrade] Skipping: not an npm-installed plugin');
+			this.__running = false;
+			return;
+		}
+
+		// 默认 5~10 分钟随机延迟，避免多实例同时发起检查
+		const initialDelay = this.__opts.initialDelayMs
+			?? (INITIAL_DELAY_MS + Math.floor(Math.random() * INITIAL_DELAY_MS));
+		this.__logger.log?.(`[auto-upgrade] Scheduler started. First check in ${Math.round(initialDelay / 1000)}s`);
+
+		this.__initialTimer = setTimeout(() => {
+			this.__initialTimer = null;
+			this.__check().catch(() => {});
+			const interval = this.__opts.checkIntervalMs ?? CHECK_INTERVAL_MS;
+			this.__intervalTimer = setInterval(() => this.__check().catch(() => {}), interval);
+		}, initialDelay);
+	}
+
+	/**
+	 * 停止调度器
+	 */
+	stop() {
+		if (!this.__running) return;
+		this.__running = false;
+
+		if (this.__initialTimer) {
+			clearTimeout(this.__initialTimer);
+			this.__initialTimer = null;
+		}
+		if (this.__intervalTimer) {
+			clearInterval(this.__intervalTimer);
+			this.__intervalTimer = null;
+		}
+		this.__logger.log?.('[auto-upgrade] Scheduler stopped');
+	}
+
+	/**
+	 * 执行一次检查
+	 */
+	async __check() {
+		if (this.__checking) return;
+		this.__checking = true;
+		try {
+			// 若上一次 spawn 的 worker 仍在运行，跳过本次检查
+			const isLocked = this.__opts.isUpgradeLockedFn ?? isUpgradeLocked;
+			if (await isLocked({ logger: this.__logger })) {
+				this.__logger.log?.('[auto-upgrade] Upgrade worker still running, skipping check');
+				return;
+			}
+
+			this.__logger.log?.('[auto-upgrade] Checking for updates...');
+			const result = await checkForUpdate({
+				execFileFn: this.__opts.execFileFn,
+			});
+
+			if (!result.available) {
+				if (result.skipped) {
+					this.__logger.log?.(`[auto-upgrade] Version ${result.latestVersion} skipped (previously failed)`);
+				} else {
+					this.__logger.log?.(`[auto-upgrade] No update available (current: ${result.currentVersion})`);
+				}
+				return;
+			}
+
+			this.__logger.log?.(`[auto-upgrade] Update available: ${result.currentVersion} → ${result.latestVersion}`);
+
+			const getInstallPath = this.__opts.getPluginInstallPathFn ?? getPluginInstallPath;
+			const pluginDir = getInstallPath(this.__pluginId);
+			if (!pluginDir) {
+				this.__logger.warn?.('[auto-upgrade] Cannot determine plugin install path');
+				return;
+			}
+
+			const { child } = spawnUpgradeWorker({
+				pluginDir,
+				fromVersion: result.currentVersion,
+				toVersion: result.latestVersion,
+				pluginId: this.__pluginId,
+				pkgName: result.pkgName,
+				opts: { spawnFn: this.__opts.spawnFn },
+				logger: this.__logger,
+			});
+
+			// 记录 worker PID，下次 check 时据此判断 worker 是否仍在运行
+			const writeLock = this.__opts.writeUpgradeLockFn ?? writeUpgradeLock;
+			await writeLock(child.pid);
+		}
+		catch (err) {
+			this.__logger.warn?.(`[auto-upgrade] Check failed: ${err.message}`);
+		}
+		finally {
+			this.__checking = false;
+		}
+	}
+}

package/src/auto-upgrade/worker-backup.js

@@ -0,0 +1,86 @@
+/**
+ * worker-backup.js — 插件目录物理备份与恢复
+ *
+ * 使用 Node.js 内置 fs.cp()（16.7+）进行跨平台物理复制，无外部依赖。
+ * 备份采用原子操作：先 cp 到 .tmp.bak，再 rename 到 .bak，
+ * 避免中途失败产生不完整的备份目录。
+ *
+ * 命名约束：备份目录（含临时目录）必须以 .bak 结尾。
+ * OpenClaw gateway 启动时会扫描 extensions/ 下所有子目录并尝试作为插件加载，
+ * 但会跳过以 .bak 结尾的目录（discovery.ts shouldIgnoreScannedDirectory）。
+ * 若临时目录不以 .bak 结尾（如曾用的 .bak-tmp），在 fs.cp 期间 gateway
+ * 重启会将不完整的目录当作插件加载，导致 method 重复注册或加载异常。
+ */
+import fs from 'node:fs/promises';
+import nodePath from 'node:path';
+
+/**
+ * 备份插件目录
+ * @param {string} pluginDir - 插件安装目录
+ * @returns {Promise<string>} 备份目录路径
+ */
+export async function createBackup(pluginDir) {
+	const backupDir = `${pluginDir}.bak`;
+
+	// 若上次异常退出遗留了 .bak，先清理
+	await fs.rm(backupDir, { recursive: true, force: true });
+
+	// 先复制到临时名，再 rename，确保原子性
+	const tmpDir = `${pluginDir}.tmp.bak`;
+	await fs.rm(tmpDir, { recursive: true, force: true });
+	await fs.cp(pluginDir, tmpDir, { recursive: true });
+	await fs.rename(tmpDir, backupDir);
+
+	return backupDir;
+}
+
+/**
+ * 从备份恢复插件目录
+ * @param {string} pluginDir - 插件安装目录
+ * @returns {Promise<boolean>} 是否成功恢复
+ */
+export async function restoreFromBackup(pluginDir) {
+	const backupDir = `${pluginDir}.bak`;
+
+	try {
+		await fs.access(backupDir);
+	}
+	catch {
+		return false;
+	}
+
+	// 删除损坏的新版本
+	await fs.rm(pluginDir, { recursive: true, force: true });
+	// 恢复备份
+	await fs.rename(backupDir, pluginDir);
+	return true;
+}
+
+/**
+ * 删除备份目录
+ * @param {string} pluginDir - 插件安装目录
+ */
+export async function removeBackup(pluginDir) {
+	const backupDir = `${pluginDir}.bak`;
+	await fs.rm(backupDir, { recursive: true, force: true });
+}
+
+/**
+ * 从 extensions 目录路径推算备份目录路径
+ * @param {string} pluginDir
+ * @returns {string}
+ */
+export function getBackupDir(pluginDir) {
+	return `${pluginDir}.bak`;
+}
+
+/**
+ * 读取指定目录下 package.json 的版本号
+ * @param {string} dir
+ * @returns {Promise<string>}
+ */
+export async function readVersionFromDir(dir) {
+	const pkgPath = nodePath.join(dir, 'package.json');
+	const raw = await fs.readFile(pkgPath, 'utf8');
+	return JSON.parse(raw).version;
+}

package/src/auto-upgrade/worker-verify.js

@@ -0,0 +1,133 @@
+/**
+ * worker-verify.js — 升级后验证
+ *
+ * 三步验证策略（任一失败即判定升级失败）：
+ * 1. Gateway 存活：轮询 `openclaw gateway status`，超时 60s
+ * 2. 插件已加载：`openclaw plugins list` 包含指定插件
+ * 3. 升级模块健康：`openclaw gateway call coclaw.upgradeHealth` 返回版本号
+ *
+ * 第 3 步同时验证了插件代码能正常执行、gateway method 注册链路正常，
+ * 确保插件仍具备自我升级能力。
+ */
+import { execFile as nodeExecFile } from 'node:child_process';
+
+const GATEWAY_READY_TIMEOUT_MS = 60_000;
+const POLL_INTERVAL_MS = 2000;
+const CMD_TIMEOUT_MS = 30_000;
+
+/**
+ * 执行命令并返回 stdout
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {object} [opts]
+ * @param {Function} [opts.execFileFn]
+ * @returns {Promise<string>}
+ */
+function exec(cmd, args, opts) {
+	const doExecFile = opts?.execFileFn ?? nodeExecFile;
+	return new Promise((resolve, reject) => {
+		doExecFile(cmd, args, { timeout: CMD_TIMEOUT_MS, shell: true }, (err, stdout) => {
+			if (err) reject(err);
+			else resolve(String(stdout).trim());
+		});
+	});
+}
+
+/**
+ * 步骤 1：等待 gateway 恢复运行
+ * @param {object} [opts]
+ * @param {Function} [opts.execFileFn]
+ * @param {number} [opts.timeoutMs]
+ * @param {number} [opts.pollIntervalMs]
+ * @returns {Promise<void>}
+ */
+export async function waitForGateway(opts) {
+	// 主动触发重启，不依赖 OpenClaw 的文件变更自动重启策略
+	try {
+		await exec('openclaw', ['gateway', 'restart'], opts);
+	}
+	catch {
+		// restart 命令失败不阻断流程，仍尝试等待
+	}
+
+	const timeout = opts?.timeoutMs ?? GATEWAY_READY_TIMEOUT_MS;
+	const interval = opts?.pollIntervalMs ?? POLL_INTERVAL_MS;
+	const start = Date.now();
+
+	while (Date.now() - start < timeout) {
+		try {
+			const output = await exec('openclaw', ['gateway', 'status'], opts);
+			if (output.includes('running')) return;
+		}
+		catch {
+			// gateway 未就绪，继续轮询
+		}
+		await sleep(interval);
+	}
+
+	throw new Error('Gateway did not become ready within timeout');
+}
+
+/**
+ * 步骤 2：验证插件已加载
+ * @param {string} pluginId - 插件 ID
+ * @param {object} [opts]
+ * @param {Function} [opts.execFileFn]
+ * @returns {Promise<void>}
+ */
+export async function verifyPluginLoaded(pluginId, opts) {
+	const output = await exec('openclaw', ['plugins', 'list'], opts);
+	if (!output.includes(pluginId)) {
+		throw new Error(`Plugin ${pluginId} not found in plugins list`);
+	}
+}
+
+/**
+ * 步骤 3：验证升级模块健康
+ * @param {object} [opts]
+ * @param {Function} [opts.execFileFn]
+ * @returns {Promise<string>} 返回版本号
+ */
+export async function verifyUpgradeHealth(opts) {
+	const output = await exec(
+		'openclaw',
+		['gateway', 'call', 'coclaw.upgradeHealth', '--json'],
+		opts,
+	);
+	try {
+		const result = JSON.parse(output);
+		if (!result.version) {
+			throw new Error('upgradeHealth response missing version');
+		}
+		return result.version;
+	}
+	catch (err) {
+		if (err.message?.includes('upgradeHealth')) throw err;
+		throw new Error(`Failed to parse upgradeHealth response: ${output}`);
+	}
+}
+
+/**
+ * 执行完整验证流程
+ * @param {string} pluginId - 插件 ID
+ * @param {object} [opts]
+ * @param {Function} [opts.execFileFn]
+ * @param {number} [opts.timeoutMs]
+ * @param {number} [opts.pollIntervalMs]
+ * @returns {Promise<{ ok: boolean, version?: string, error?: string }>}
+ */
+export async function verifyUpgrade(pluginId, opts) {
+	try {
+		await waitForGateway(opts);
+		await verifyPluginLoaded(pluginId, opts);
+		const version = await verifyUpgradeHealth(opts);
+		return { ok: true, version };
+	}
+	catch (err) {
+		return { ok: false, error: String(err?.message ?? err) };
+	}
+}
+
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/auto-upgrade/worker.js

@@ -0,0 +1,248 @@
+/**
+ * worker.js — 由 updater-spawn 以 detached 进程启动
+ *
+ * 用法：node worker.js --pluginDir <dir> --fromVersion <ver> --toVersion <ver>
+ *                       --pluginId <id> --pkgName <name>
+ *
+ * 流程：备份 → openclaw plugins update → 等待 gateway 重启 → 验证 → 成功清理/失败回滚
+ *
+ * 注意：
+ * - 本模块作为独立 node 进程运行，与 gateway 进程隔离
+ * - state dir 通过 OPENCLAW_STATE_DIR 环境变量由 spawner 传入
+ * - shell: true 为 Windows 兼容性所需（openclaw 全局安装生成 .cmd 包装器）
+ */
+
+import { execFile as nodeExecFile } from 'node:child_process';
+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';
+
+const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.-]+)?$/;
+
+/**
+ * 执行 openclaw plugins update
+ * @param {string} pluginId - 插件 ID
+ * @param {object} [opts]
+ * @param {Function} [opts.execFileFn]
+ * @returns {Promise<void>}
+ */
+// openclaw plugins update 内部实现为 staged backup-and-replace，
+// 仅支持 source === "npm" 的安装（updater 已做前置过滤）
+function runPluginUpdate(pluginId, opts) {
+	const doExecFile = opts?.execFileFn ?? nodeExecFile;
+	return new Promise((resolve, reject) => {
+		doExecFile('openclaw', ['plugins', 'update', pluginId], {
+			timeout: 120_000,
+			shell: true,
+		}, (err) => {
+			if (err) reject(new Error(`plugins update failed: ${err.message}`));
+			else resolve();
+		});
+	});
+}
+
+/**
+ * 尝试通过 npm 安装旧版本进行兜底回滚
+ *
+ * openclaw plugins install 不支持覆盖已安装插件，因此需先 uninstall。
+ * uninstall 失败不阻断流程（插件可能已处于异常状态）。
+ *
+ * @param {string} pkgName - npm 包名
+ * @param {string} version
+ * @param {string} pluginId - 插件 ID
+ * @param {object} [opts]
+ * @param {Function} [opts.execFileFn]
+ * @returns {Promise<void>}
+ */
+// 回滚兜底：当物理备份恢复失败时，尝试从 npm 重新安装旧版本
+async function fallbackInstallOldVersion(pkgName, version, pluginId, opts) {
+	// version 来自 package.json，正常不会有异常值，但 shell: true 下做防御校验
+	if (!SEMVER_RE.test(version)) {
+		throw new Error(`invalid version format: ${version}`);
+	}
+	const doExecFile = opts?.execFileFn ?? nodeExecFile;
+	const run = (args, timeout = 120_000) => new Promise((resolve, reject) => {
+		doExecFile('openclaw', args, { timeout, shell: true }, (err) => {
+			if (err) reject(err);
+			else resolve();
+		});
+	});
+
+	// 先卸载：install 不支持覆盖已安装插件
+	try {
+		await run(['plugins', 'uninstall', pluginId], 60_000);
+	} catch {
+		// uninstall 失败不阻断，继续尝试 install
+	}
+
+	try {
+		await run(['plugins', 'install', `${pkgName}@${version}`]);
+	} catch (err) {
+		throw new Error(`fallback install failed: ${err.message}`);
+	}
+}
+
+/**
+ * 执行升级流程
+ * @param {object} params
+ * @param {string} params.pluginDir - 插件安装目录
+ * @param {string} params.fromVersion - 当前版本
+ * @param {string} params.toVersion - 目标版本
+ * @param {string} params.pluginId - 插件 ID
+ * @param {string} params.pkgName - npm 包名
+ * @param {object} [params.opts] - 测试注入选项
+ * @param {Function} [params.opts.execFileFn]
+ * @param {number} [params.opts.timeoutMs]
+ * @param {number} [params.opts.pollIntervalMs]
+ * @param {Function} [params.logger] - 日志函数
+ */
+export async function runUpgrade({ pluginDir, fromVersion, toVersion, pluginId, pkgName, opts, logger }) {
+	const log = logger ?? console.log;
+
+	log(`[upgrade-worker] Starting upgrade: ${fromVersion} → ${toVersion}`);
+	log(`[upgrade-worker] Plugin dir: ${pluginDir}`);
+
+	// 1. 备份
+	log('[upgrade-worker] Creating backup...');
+	await createBackup(pluginDir);
+	log('[upgrade-worker] Backup created');
+
+	// 2. 执行升级
+	log('[upgrade-worker] Running plugins update...');
+	try {
+		await runPluginUpdate(pluginId, opts);
+	}
+	catch (updateErr) {
+		// 升级命令本身失败（可能是瞬态故障），恢复备份但不标记版本为 skipped
+		log(`[upgrade-worker] Update command failed: ${updateErr.message}`);
+		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...');
+	const result = await verifyUpgrade(pluginId, opts);
+
+	if (result.ok) {
+		// 4a. 成功
+		log(`[upgrade-worker] Upgrade verified. Version: ${result.version}`);
+		try {
+			await removeBackup(pluginDir);
+		}
+		catch (e) {
+			log(`[upgrade-worker] Backup cleanup failed (non-fatal): ${e.message}`);
+		}
+		await updateLastUpgrade({ from: fromVersion, to: toVersion, result: 'ok' });
+		await appendLog({ from: fromVersion, to: toVersion, result: 'ok' });
+		log('[upgrade-worker] Upgrade complete');
+	} else {
+		// 4b. 失败，回滚
+		log(`[upgrade-worker] Verification failed: ${result.error}`);
+		await handleRollback({
+			pluginDir, fromVersion, toVersion, pluginId, pkgName,
+			error: result.error, skipVersion: true, opts, log,
+		});
+	}
+}
+
+/**
+ * 回滚处理
+ */
+async function handleRollback({ pluginDir, fromVersion, toVersion, pluginId, pkgName, error, skipVersion, opts, log }) {
+	log('[upgrade-worker] Attempting rollback...');
+
+	// 首选 mv 备份目录
+	let restored = false;
+	try {
+		restored = await restoreFromBackup(pluginDir);
+	} catch (restoreErr) {
+		log(`[upgrade-worker] Backup restore error: ${restoreErr.message}`);
+	}
+
+	if (restored) {
+		log('[upgrade-worker] Restored from backup');
+	} else {
+		// 兜底：先卸载再从 npm 安装旧版本
+		log('[upgrade-worker] Backup restore failed, falling back to npm install');
+		try {
+			await fallbackInstallOldVersion(pkgName, fromVersion, pluginId, opts);
+			log('[upgrade-worker] Fallback install completed');
+		}
+		catch (fallbackErr) {
+			log(`[upgrade-worker] Fallback install also failed: ${fallbackErr.message}`);
+		}
+	}
+
+	// 等待 gateway 重启
+	log('[upgrade-worker] Waiting for gateway to restart after rollback...');
+	try {
+		await waitForGateway(opts);
+		log('[upgrade-worker] Gateway restarted after rollback');
+	}
+	catch {
+		log('[upgrade-worker] Gateway did not restart after rollback');
+	}
+
+	// 记录状态（顺序执行因共享 state 文件，但各自 try/catch 避免单个失败阻断其余）
+	// 仅验证失败（新版本确实被加载并发现有问题）才标记为 skipped；
+	// update 命令失败可能是瞬态故障（网络、磁盘等），不应永久跳过该版本
+	if (skipVersion) {
+		try { await addSkippedVersion(toVersion); }
+		catch (e) { log(`[upgrade-worker] Failed to record skipped version (non-fatal): ${e.message}`); }
+	}
+	try { await updateLastUpgrade({ from: fromVersion, to: toVersion, result: 'rollback' }); }
+	catch (e) { log(`[upgrade-worker] Failed to update lastUpgrade (non-fatal): ${e.message}`); }
+	try { await appendLog({ from: fromVersion, to: toVersion, result: 'rollback', error }); }
+	catch (e) { log(`[upgrade-worker] Failed to append log (non-fatal): ${e.message}`); }
+	if (skipVersion) {
+		log(`[upgrade-worker] Rollback complete. Version ${toVersion} added to skipped list`);
+	} else {
+		log(`[upgrade-worker] Rollback complete. Version ${toVersion} not skipped (transient failure)`);
+	}
+}
+
+// 作为独立进程执行时的入口
+/* c8 ignore start */
+async function main() {
+	const { values } = parseArgs({
+		options: {
+			pluginDir: { type: 'string' },
+			fromVersion: { type: 'string' },
+			toVersion: { type: 'string' },
+			pluginId: { type: 'string' },
+			pkgName: { type: 'string' },
+		},
+		strict: true,
+	});
+
+	const { pluginDir, fromVersion, toVersion, pluginId, pkgName } = values;
+	if (!pluginDir || !fromVersion || !toVersion || !pluginId || !pkgName) {
+		console.error('Usage: node worker.js --pluginDir <dir> --fromVersion <ver> --toVersion <ver> --pluginId <id> --pkgName <name>');
+		process.exit(1);
+	}
+
+	try {
+		await runUpgrade({ pluginDir, fromVersion, toVersion, pluginId, pkgName });
+		process.exit(0);
+	}
+	catch (err) {
+		console.error(`[upgrade-worker] Fatal error: ${err.message}`);
+		process.exit(1);
+	}
+}
+
+// 仅在直接执行时运行 main
+import { fileURLToPath } from 'node:url';
+import nodePath from 'node:path';
+if (process.argv[1] && nodePath.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+	main().catch((err) => {
+		console.error(`[upgrade-worker] Fatal: ${err.message}`);
+		process.exit(1);
+	});
+}
+/* c8 ignore stop */

package/src/realtime-bridge.js

@@ -8,6 +8,8 @@ import { getRuntime } from './runtime.js';
 const DEFAULT_GATEWAY_WS_URL = 'ws://127.0.0.1:18789';
 const RECONNECT_MS = 10_000;
 const CONNECT_TIMEOUT_MS = 10_000;
+const SERVER_HB_PING_MS = 25_000;
+const SERVER_HB_TIMEOUT_MS = 45_000;
 
 function toServerWsUrl(baseUrl, token) {
 	const url = new URL(baseUrl);
@@ -84,6 +86,8 @@ export class RealtimeBridge {
 		this.logger = console;
 		this.pluginConfig = {};
 		this.intentionallyClosed = false;
+		this.serverHbInterval = null;
+		this.serverHbTimer = null;
 	}
 
 	__resolveWebSocket() {
@@ -96,6 +100,31 @@ export class RealtimeBridge {
 		}
 	}
 
+	__startServerHeartbeat(sock) {
+		this.__clearServerHeartbeat();
+		this.serverHbInterval = setInterval(() => {
+			if (sock.readyState === 1) {
+				try { sock.send(JSON.stringify({ type: 'ping' })); } catch {}
+			}
+		}, SERVER_HB_PING_MS);
+		this.serverHbInterval.unref?.();
+		this.__resetServerHbTimeout(sock);
+	}
+
+	__resetServerHbTimeout(sock) {
+		if (this.serverHbTimer) clearTimeout(this.serverHbTimer);
+		this.serverHbTimer = setTimeout(() => {
+			this.logger.warn?.(`[coclaw] server ws heartbeat timeout (${SERVER_HB_TIMEOUT_MS / 1000}s), closing`);
+			try { sock.close(4000, 'heartbeat_timeout'); } catch {}
+		}, SERVER_HB_TIMEOUT_MS);
+		this.serverHbTimer.unref?.();
+	}
+
+	__clearServerHeartbeat() {
+		if (this.serverHbInterval) { clearInterval(this.serverHbInterval); this.serverHbInterval = null; }
+		if (this.serverHbTimer) { clearTimeout(this.serverHbTimer); this.serverHbTimer = null; }
+	}
+
 	__resolveGatewayWsUrl() {
 		return this.pluginConfig?.gatewayWsUrl
 			?? process.env.COCLAW_GATEWAY_WS_URL
@@ -486,10 +515,12 @@ export class RealtimeBridge {
 		sock.addEventListener('open', () => {
 			this.__clearConnectTimer();
 			this.logger.info?.(`[coclaw] realtime bridge connected: ${maskedTarget}`);
+			this.__startServerHeartbeat(sock);
 			this.__ensureGatewayConnection();
 		});
 
 		sock.addEventListener('message', async (event) => {
+			this.__resetServerHbTimeout(sock);
 			try {
 				const payload = JSON.parse(String(event.data ?? '{}'));
 				if (payload?.type === 'bot.unbound') {
@@ -513,6 +544,7 @@ export class RealtimeBridge {
 		});
 
 		sock.addEventListener('close', async (event) => {
+			this.__clearServerHeartbeat();
 			this.__clearConnectTimer();
 			// 若 serverWs 已指向新实例（如 refresh 后），跳过旧 sock 的清理
 			if (this.serverWs !== null && this.serverWs !== sock) {
@@ -538,6 +570,7 @@ export class RealtimeBridge {
 			if (this.serverWs !== sock || this.intentionallyClosed) {
 				return;
 			}
+			this.__clearServerHeartbeat();
 			this.__clearConnectTimer();
 			this.logger.warn?.(`[coclaw] realtime bridge error, will retry in ${RECONNECT_MS}ms: ${String(err?.message ?? err)}`);
 			this.serverWs = null;
@@ -568,6 +601,7 @@ export class RealtimeBridge {
 		this.started = false;
 		this.mainSessionEnsured = false;
 		this.mainSessionEnsurePromise = null;
+		this.__clearServerHeartbeat();
 		this.__clearConnectTimer();
 		if (this.reconnectTimer) {
 			clearTimeout(this.reconnectTimer);

package/src/session-manager/manager.js

@@ -103,7 +103,7 @@ function parseSessionFileName(fileName) {
 }
 
 function archiveTypePriority(archiveType) {
-	return archiveType === 'reset' ? 2 : 1;
+	return archiveType === 'live' ? 2 : 1;
 }
 
 function shouldReplaceByPriority(current, next) {
@@ -266,6 +266,12 @@ export function createSessionManager(options = {}) {
 
 	function resolveTranscriptFile(agentId, sessionId) {
 		const dir = sessionsDir(agentId);
+		// live 文件优先：同一 sessionId 可能同时存在 live 和 reset 文件
+		// （OpenClaw reset 后复用 sessionId），live 代表当前活跃 transcript
+		const livePath = nodePath.join(dir, `${sessionId}.jsonl`);
+		if (fs.existsSync(livePath)) {
+			return livePath;
+		}
 		const files = fs.existsSync(dir) ? fs.readdirSync(dir) : [];
 		const resetPrefix = `${sessionId}.jsonl.reset.`;
 		const resetCandidates = files
@@ -288,10 +294,6 @@ export function createSessionManager(options = {}) {
 		if (resetCandidates.length > 0) {
 			return resetCandidates[0].path;
 		}
-		const livePath = nodePath.join(dir, `${sessionId}.jsonl`);
-		if (fs.existsSync(livePath)) {
-			return livePath;
-		}
 		return null;
 	}