@coclaw/openclaw-coclaw 0.26.1 → 0.26.3

package/src/auto-upgrade/worker.js

@@ -2,21 +2,26 @@
  * worker.js — 由 updater-spawn 以 detached 进程启动
  *
  * 用法：node worker.js --pluginDir <dir> --fromVersion <ver> --toVersion <ver>
- *                       --pluginId <id> --pkgName <name>
+ *                       --pluginId <id> --pkgName <name> [--baselineVersion <ver>]
  *
- * 流程：备份 → openclaw plugins update → 等待 gateway 重启 → 验证 → 成功清理/失败回滚
+ * 流程：备份 → 写 inflight → openclaw plugins update → L2 结局核对（inspect 安装记录）
+ *       → 等待 gateway 重启 → 验证 → 成功清理/失败回滚/未推进 no-op 跳过
+ *       → 终态记账（recordUpgradeTerminal 原子写 lastUpgrade + 清 inflight）
  *
  * 注意：
  * - 本模块作为独立 node 进程运行，与 gateway 进程隔离
  * - state dir 通过 OPENCLAW_STATE_DIR 环境变量由 spawner 传入
  * - shell 仅在 Windows 启用（openclaw 全局安装生成 .cmd 包装器，需 shell 解析）
+ * - 所有 state 写入非致命：独立 try/catch + 日志，失败继续流程（账目兜底交
+ *   scheduler 的 inflight 对账）；worker 是独立子进程，禁 remoteLog
  */
 
 import { execFile as nodeExecFile } from 'node:child_process';
 import { parseArgs } from 'node:util';
 import { createBackup, restoreFromBackup, removeBackup } from './worker-backup.js';
-import { verifyUpgrade, triggerGatewayRestart } from './worker-verify.js';
-import { addSkippedVersion, updateLastUpgrade, appendLog } from './state.js';
+import { verifyUpgrade, triggerGatewayRestart, isVersionReached } from './worker-verify.js';
+import { inspectPluginInstall } from './updater-check.js';
+import { appendLog, recordUpgradeTerminal, updateInflight, writeInflight } from './state.js';
 import { getCurrentNpmRegistry, pickFallbackRegistry } from './registry-fallback.js';
 
 const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.-]+)?$/;
@@ -25,21 +30,55 @@ const UPDATE_TIMEOUT_MS = 10 * 60 * 1000;
 // 回滚兜底重装旧版本走的是同一条 npm 下载链路，且触发前置本身是"备份已丢"的异常态，
 // 此时尽量兜住比快速失败更重要，与 UPDATE_TIMEOUT_MS 对齐
 const FALLBACK_INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
-const FALLBACK_UNINSTALL_TIMEOUT_MS = 60 * 1000;
+// 子命令双流各取尾部上限：真因（prerelease 拒装等）通常在输出尾部
+const CMD_OUTPUT_TAIL_CHARS = 500;
 
 /**
- * 执行 openclaw plugins update
+ * 把子命令失败的真因拼进错误消息。
+ * 上游错误 outcome 走 console.log（stdout）而 execFile err.message 只附 stderr，
+ * 必须双流都收。先脱敏再截尾：截断可能把凭据切半导致正则漏匹配。
+ * @param {string} prefix - 错误前缀（如 "plugins update failed"）
+ * @param {Error} err - execFile 回调的 err
+ * @param {string|Buffer} stdout
+ * @param {string|Buffer} stderr
+ * @returns {string}
+ */
+export function formatCmdFailure(prefix, err, stdout, stderr) {
+	const scrub = (s) => String(s ?? '')
+		// registry URL 的 userinfo（https://user:pass@host）
+		.replace(/:\/\/[^@\s/]+@/g, '://***@')
+		// .npmrc 风格 token（//host/:_authToken=xxx）
+		.replace(/(_authToken\s*=\s*)\S+/gi, '$1***');
+	const tail = (s) => {
+		const t = s.trim();
+		return t.length > CMD_OUTPUT_TAIL_CHARS ? t.slice(-CMD_OUTPUT_TAIL_CHARS) : t;
+	};
+	/* c8 ignore next -- ?? fallback */
+	const parts = [`${prefix}: ${tail(scrub(err?.message ?? String(err)))}`];
+	const out = tail(scrub(stdout));
+	if (out) parts.push(`stdout: ${out}`);
+	const errOut = tail(scrub(stderr));
+	if (errOut) parts.push(`stderr: ${errOut}`);
+	return parts.join(' | ');
+}
+
+/**
+ * 执行 openclaw plugins update（裸 npm 包名）
  *
  * 仅支持 source === "npm" 的安装（updater 已做前置过滤）。
+ * 用裸包名而非插件 id：裸包名 update 走包名匹配产生 specOverride，成功后把
+ * 安装记录的 spec 重写为裸名——一次 update 同时"装 latest + 解钉"。否则
+ * fallback install 留下的 `pkg@x.y.z` 精确 spec 会让 update 永远 resolve
+ * 同一版本，自动升级被永久钉死。
  * env 由调用方决定：缺省时子进程继承当前 process.env（含用户 .npmrc 自动生效）；
  * 显式传入时用于覆盖 registry 等 npm 配置以做兜底重试。
- * @param {string} pluginId - 插件 ID
+ * @param {string} pkgName - npm 包名
  * @param {object} [opts]
  * @param {Function} [opts.execFileFn]
  * @param {NodeJS.ProcessEnv} [opts.env]
  * @returns {Promise<void>}
  */
-function runPluginUpdate(pluginId, opts) {
+function runPluginUpdate(pkgName, opts) {
 	/* c8 ignore next -- ?./?? fallback */
 	const doExecFile = opts?.execFileFn ?? nodeExecFile;
 	return new Promise((resolve, reject) => {
@@ -49,53 +88,43 @@ function runPluginUpdate(pluginId, opts) {
 		};
 		// 不传 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}`));
+		doExecFile('openclaw', ['plugins', 'update', pkgName], execOpts, (err, stdout, stderr) => {
+			if (err) reject(new Error(formatCmdFailure('plugins update failed', err, stdout, stderr)));
 			else resolve();
 		});
 	});
 }
 
 /**
- * 尝试通过 npm 安装旧版本进行兜底回滚
- *
- * openclaw plugins install 不支持覆盖已安装插件，因此需先 uninstall。
- * uninstall 失败不阻断流程（插件可能已处于异常状态）。
+ * 尝试通过 npm 安装旧版本进行兜底回滚。
+ * 单命令 `plugins install <pkg>@<ver> --force`：--force 即覆盖装（上游映射
+ * mode=update，绕开 "already exists" 拒绝），不再需要 uninstall 前置——
+ * 旧的 uninstall 在非 TTY 下要求交互确认必失败且错误被静默吞。
  *
  * @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) {
+async function fallbackInstallOldVersion(pkgName, version, opts) {
 	// version 来自 package.json，正常不会有异常值，但 shell: true 下做防御校验
 	if (!SEMVER_RE.test(version)) {
 		throw new Error(`invalid version format: ${version}`);
 	}
 	/* c8 ignore next -- ?./?? fallback */
 	const doExecFile = opts?.execFileFn ?? nodeExecFile;
-	const run = (args, timeout) => new Promise((resolve, reject) => {
-		doExecFile('openclaw', args, { timeout, shell: process.platform === 'win32' }, (err) => {
-			if (err) reject(err);
-			else resolve();
-		});
+	return new Promise((resolve, reject) => {
+		doExecFile(
+			'openclaw',
+			['plugins', 'install', `${pkgName}@${version}`, '--force'],
+			{ timeout: FALLBACK_INSTALL_TIMEOUT_MS, shell: process.platform === 'win32' },
+			(err, stdout, stderr) => {
+				if (err) reject(new Error(formatCmdFailure('fallback install failed', err, stdout, stderr)));
+				else resolve();
+			},
+		);
 	});
-
-	// 先卸载：install 不支持覆盖已安装插件
-	try {
-		await run(['plugins', 'uninstall', pluginId], FALLBACK_UNINSTALL_TIMEOUT_MS);
-	} catch {
-		// uninstall 失败不阻断，继续尝试 install
-	}
-
-	try {
-		await run(['plugins', 'install', `${pkgName}@${version}`], FALLBACK_INSTALL_TIMEOUT_MS);
-	} catch (err) {
-		throw new Error(`fallback install failed: ${err.message}`);
-	}
 }
 
 /**
@@ -104,6 +133,7 @@ async function fallbackInstallOldVersion(pkgName, version, pluginId, opts) {
  * @param {string} params.pluginDir - 插件安装目录
  * @param {string} params.fromVersion - 当前版本
  * @param {string} params.toVersion - 目标版本
+ * @param {string} [params.baselineVersion] - 升级前权威安装记录的版本（L2 基线；可缺）
  * @param {string} params.pluginId - 插件 ID
  * @param {string} params.pkgName - npm 包名
  * @param {object} [params.opts] - 测试注入选项
@@ -112,7 +142,7 @@ async function fallbackInstallOldVersion(pkgName, version, pluginId, opts) {
  * @param {number} [params.opts.pollIntervalMs]
  * @param {Function} [params.logger] - 日志函数
  */
-export async function runUpgrade({ pluginDir, fromVersion, toVersion, pluginId, pkgName, opts, logger }) {
+export async function runUpgrade({ pluginDir, fromVersion, toVersion, baselineVersion, pluginId, pkgName, opts, logger }) {
 	const log = logger ?? console.log;
 
 	log(`[upgrade-worker] Starting upgrade: ${fromVersion} → ${toVersion}`);
@@ -120,14 +150,23 @@ export async function runUpgrade({ pluginDir, fromVersion, toVersion, pluginId,
 
 	// 1. 备份
 	log('[upgrade-worker] Creating backup...');
-	await createBackup(pluginDir);
+	await createBackup(pluginDir, pluginId);
 	log('[upgrade-worker] Backup created');
 
+	// 进入改盘阶段前写 inflight：worker 若没活到终态记账（典型：被自己触发的
+	// 网关重启杀死），scheduler 下轮锁空闲时据此对账补记终态
+	try {
+		await writeInflight({ from: fromVersion, to: toVersion, verifyTarget: toVersion, pluginDir, phase: 'update' });
+	}
+	catch (e) {
+		log(`[upgrade-worker] Failed to write inflight marker (non-fatal): ${e.message}`);
+	}
+
 	// 2. 执行升级（首次按用户原 env，失败后用反向 mirror 重试一次）
 	log('[upgrade-worker] Running plugins update...');
 	let updateErr = null;
 	try {
-		await runPluginUpdate(pluginId, opts);
+		await runPluginUpdate(pkgName, opts);
 		log('[upgrade-worker] Update command completed');
 	}
 	catch (firstErr) {
@@ -143,7 +182,7 @@ export async function runUpgrade({ pluginDir, fromVersion, toVersion, pluginId,
 			const retryEnv = { ...process.env };
 			delete retryEnv.NPM_CONFIG_REGISTRY;
 			retryEnv.npm_config_registry = fallback;
-			await runPluginUpdate(pluginId, { ...opts, env: retryEnv });
+			await runPluginUpdate(pkgName, { ...opts, env: retryEnv });
 			log('[upgrade-worker] Update command completed on retry');
 			updateErr = null;
 		}
@@ -162,24 +201,106 @@ export async function runUpgrade({ pluginDir, fromVersion, toVersion, pluginId,
 		return;
 	}
 
-	// 3. 等待 gateway 重启并验证
+	// 3. L2 结局核对：update exit 0 不代表真升级（老 host 出错也 exit 0、path/缺记录干净
+	// skip 也 exit 0、registry 假成功、latest-compatible 封顶）。经权威 inspect 读升级后
+	// 安装记录分流结局；stdout 文本无契约承诺，仅记日志不作判据。
+	// worker 是独立子进程、无 bridge 连接，禁 remoteLog——诊断只写本地日志，
+	// 结局经 lastUpgrade 接 scheduler 下轮上报链。
+	log('[upgrade-worker] Inspecting install record (post-update)...');
+	// inspectPluginInstall 契约是永不抛，但注入实现可能同步抛错；裸抛会 fatal exit 1
+	// （留备份、无状态记录），故归一化为 inspect 自身失败，走下方保守分支
+	let inspected;
+	try {
+		inspected = await inspectPluginInstall(pluginId, opts);
+	}
+	catch (err) {
+		/* c8 ignore next -- ?? fallback：err 字段缺省的兜底分支不强制覆盖 */
+		const msg = err?.message ?? String(err);
+		inspected = { ok: false, reason: `inspect threw: ${msg}` };
+	}
+
+	let verifyTarget = toVersion;
+	// record 推进但未达标：按实装版本验证健康，成功后对 toVersion 记跳过（已知到不了）
+	let advancedShortfall = false;
+	if (inspected.ok && typeof inspected.install?.version === 'string') {
+		const recordVersion = inspected.install.version;
+		if (isVersionReached(recordVersion, toVersion)) {
+			// 达标（等于或更新，覆盖 dist-tag 前移）：真升级，走现行 restart + 健康轮询流
+			log(`[upgrade-worker] Install record reached target: ${recordVersion}`);
+		}
+		else if (!baselineVersion) {
+			// 基线不可得：无从判断 record 是否推进，退化为现行流（restart + verify(toVersion)）
+			log(`[upgrade-worker] Record version ${recordVersion} below target but baseline unknown; proceeding with standard verify`);
+		}
+		else if (recordVersion === baselineVersion) {
+			// record 未推进：update 干净 skip / registry 假成功——磁盘什么都没变。
+			// no-op：不重启、不回滚，删备份，立即记 skipVersion 停止每小时空转重试
+			// （瞬时故障在新 host 上走 exit≠0 原路径，不会落到这里被永久跳过）
+			log(`[upgrade-worker] Install record did not advance (still ${recordVersion}); no-op skip for ${toVersion}`);
+			try { await removeBackup(pluginId); }
+			catch (e) { log(`[upgrade-worker] Backup cleanup failed (non-fatal): ${e.message}`); }
+			try {
+				await recordUpgradeTerminal({
+					from: fromVersion, to: toVersion, result: 'noop-skip', skipVersion: toVersion,
+				});
+			}
+			/* c8 ignore next -- 状态写入 catch：测试中 stub 不会失败 */
+			catch (e) { log(`[upgrade-worker] Failed to record terminal state (non-fatal): ${e.message}`); }
+			log(`[upgrade-worker] No-op skip complete. Version ${toVersion} added to skipped list`);
+			return;
+		}
+		else {
+			// record 推进但未达标（latest-compatible 封顶等）：磁盘确已换代，
+			// 必须健康验证实装版本，避免未经验证的新副本在下次自然重启时静默激活
+			log(`[upgrade-worker] Install record advanced to ${recordVersion} (target ${toVersion} not reached); verifying actual version`);
+			verifyTarget = recordVersion;
+			advancedShortfall = true;
+		}
+	}
+	else {
+		// inspect 自身失败 / 记录缺版本：保守按"真升级"处理，进现行 restart + verify
+		//（健康检查 + 回滚兜底），避免工具故障静默压制激活
+		const reason = inspected.ok ? 'install record missing version' : inspected.reason;
+		log(`[upgrade-worker] Post-update inspect unavailable (${reason}); proceeding with standard verify`);
+	}
+
+	// 4. 等待 gateway 重启并验证；phase/verifyTarget 推进进 inflight，
+	// 中断时 scheduler 对账据 verifyTarget 判定成败（advancedShortfall 语义同步）
+	try {
+		await updateInflight({ phase: 'verify', verifyTarget });
+	}
+	catch (e) {
+		log(`[upgrade-worker] Failed to update inflight marker (non-fatal): ${e.message}`);
+	}
 	log('[upgrade-worker] Verifying upgrade...');
-	const result = await verifyUpgrade(pluginDir, toVersion, opts, log);
+	const result = await verifyUpgrade(pluginDir, verifyTarget, opts, log);
 
 	if (result.ok) {
 		// 4a. 成功
 		log(`[upgrade-worker] Upgrade verified. Version: ${result.version}`);
 		try {
-			await removeBackup(pluginDir);
+			await removeBackup(pluginId);
 		}
 		catch (e) {
 			log(`[upgrade-worker] Backup cleanup failed (non-fatal): ${e.message}`);
 		}
 		// 记录真实装上的版本而非目标版本——dist-tag 前移窗口下两者可能不同。
 		// 不加 fallback：若 result.ok 时 version 缺失，说明上游契约被破坏，
-		// 宁可让状态里直接暴露 undefined 便于排障，也不要用 toVersion 糊过去
-		await updateLastUpgrade({ from: fromVersion, to: result.version, result: 'ok' });
-		await appendLog({ from: fromVersion, to: result.version, result: 'ok' });
+		// 宁可让状态里直接暴露 undefined 便于排障，也不要用 toVersion 糊过去。
+		// advancedShortfall：实装版本健康但 toVersion 在本 host 装不上 → 记跳过，
+		// 停止注定不达标的重试
+		try {
+			await recordUpgradeTerminal({
+				from: fromVersion, to: result.version, result: 'ok',
+				skipVersion: advancedShortfall ? toVersion : undefined,
+			});
+		}
+		catch (e) {
+			log(`[upgrade-worker] Failed to record terminal state (non-fatal): ${e.message}`);
+		}
+		if (advancedShortfall) {
+			log(`[upgrade-worker] Version ${toVersion} added to skipped list (host capped below target)`);
+		}
 		log('[upgrade-worker] Upgrade complete');
 	} else {
 		// 4b. 失败，回滚
@@ -192,52 +313,83 @@ export async function runUpgrade({ pluginDir, fromVersion, toVersion, pluginId,
 }
 
 /**
- * 回滚处理
+ * 回滚处理。
+ * result=rollback 指**文件态已恢复**（restore 或 fallback install 任一成功），
+ * 运行态恢复交还重启/上游 watcher；两路都失败记 rollback-failed（error 带真因）。
+ * 记账整体在 triggerGatewayRestart **之前**：回滚后文件态已定，记账不依赖重启，
+ * 且 worker 在不可脱逃形态下可能被自己触发的重启杀死。
  */
 async function handleRollback({ pluginDir, fromVersion, toVersion, pluginId, pkgName, error, skipVersion, opts, log }) {
 	log('[upgrade-worker] Attempting rollback...');
+	try {
+		await updateInflight({ phase: 'rollback' });
+	}
+	catch (e) {
+		log(`[upgrade-worker] Failed to update inflight marker (non-fatal): ${e.message}`);
+	}
 
-	// 首选 mv 备份目录
+	// 首选 rename 备份目录
 	let restored = false;
+	let fallbackOk = false;
+	let rollbackErrMsg = '';
 	try {
-		restored = await restoreFromBackup(pluginDir);
+		restored = await restoreFromBackup(pluginDir, pluginId, { log });
 	} catch (restoreErr) {
+		rollbackErrMsg = `restore: ${restoreErr.message}`;
 		log(`[upgrade-worker] Backup restore error: ${restoreErr.message}`);
 	}
 
 	if (restored) {
 		log('[upgrade-worker] Restored from backup');
 	} else {
-		// 兜底：先卸载再从 npm 安装旧版本
+		// 兜底：从 npm 覆盖安装旧版本
 		log('[upgrade-worker] Backup restore failed, falling back to npm install');
 		try {
-			await fallbackInstallOldVersion(pkgName, fromVersion, pluginId, opts);
+			await fallbackInstallOldVersion(pkgName, fromVersion, opts);
+			fallbackOk = true;
 			log('[upgrade-worker] Fallback install completed');
 		}
 		catch (fallbackErr) {
+			rollbackErrMsg = rollbackErrMsg ? `${rollbackErrMsg}; ${fallbackErr.message}` : fallbackErr.message;
 			log(`[upgrade-worker] Fallback install also failed: ${fallbackErr.message}`);
 		}
 	}
 
-	// 触发 gateway 重启让老版本回到运行态（尽力而为，不验证结果）
-	log('[upgrade-worker] Triggering gateway restart after rollback...');
-	await triggerGatewayRestart(opts);
+	const rollbackOk = restored || fallbackOk;
+	// rollback-failed 时 error 带真因：!rollbackOk 必经 fallback 抛错，rollbackErrMsg 非空
+	let finalError = error;
+	if (!rollbackOk) {
+		finalError = `${error}; rollback failed: ${rollbackErrMsg}`;
+	}
 
-	// 记录状态（顺序执行因共享 state 文件，但各自 try/catch 避免单个失败阻断其余）
+	// 记录状态（重启前完成；失败非致命，inflight 未清交 scheduler 对账兜底）
 	// 仅验证失败（新版本确实被加载并发现有问题）才标记为 skipped；
 	// update 命令失败可能是瞬态故障（网络、磁盘等），不应永久跳过该版本
-	if (skipVersion) {
-		try { await addSkippedVersion(toVersion); }
-		/* c8 ignore next -- 状态写入 catch：测试中 stub 不会失败 */
-		catch (e) { log(`[upgrade-worker] Failed to record skipped version (non-fatal): ${e.message}`); }
+	try {
+		await recordUpgradeTerminal({
+			from: fromVersion, to: toVersion,
+			result: rollbackOk ? 'rollback' : 'rollback-failed',
+			error: finalError,
+			skipVersion: skipVersion ? toVersion : undefined,
+		});
 	}
-	try { await updateLastUpgrade({ from: fromVersion, to: toVersion, result: 'rollback' }); }
-	/* c8 ignore next -- 状态写入 catch */
-	catch (e) { log(`[upgrade-worker] Failed to update lastUpgrade (non-fatal): ${e.message}`); }
-	try { await appendLog({ from: fromVersion, to: toVersion, result: 'rollback', error }); }
-	/* c8 ignore next -- 状态写入 catch */
-	catch (e) { log(`[upgrade-worker] Failed to append log (non-fatal): ${e.message}`); }
-	if (skipVersion) {
+	catch (e) {
+		log(`[upgrade-worker] Failed to record terminal state (non-fatal): ${e.message}`);
+	}
+
+	// 触发 gateway 重启让老版本回到运行态（尽力而为，不验证结果）
+	log('[upgrade-worker] Triggering gateway restart after rollback...');
+	const restartOk = await triggerGatewayRestart(opts);
+	if (!restartOk) {
+		// 文件态已恢复但运行态未刷新；worker 禁 remoteLog，只落 jsonl 事件供诊断
+		log('[upgrade-worker] Gateway restart command failed after rollback');
+		try { await appendLog({ event: 'rollback-restart-failed', from: fromVersion, to: toVersion }); }
+		catch (e) { log(`[upgrade-worker] Failed to append log (non-fatal): ${e.message}`); }
+	}
+
+	if (!rollbackOk) {
+		log(`[upgrade-worker] Rollback failed. Version ${toVersion} may still be active on disk`);
+	} else 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)`);
@@ -252,20 +404,21 @@ async function main() {
 			pluginDir: { type: 'string' },
 			fromVersion: { type: 'string' },
 			toVersion: { type: 'string' },
+			baselineVersion: { type: 'string' }, // 可缺：缺时按"基线不可得"退化处理
 			pluginId: { type: 'string' },
 			pkgName: { type: 'string' },
 		},
 		strict: true,
 	});
 
-	const { pluginDir, fromVersion, toVersion, pluginId, pkgName } = values;
+	const { pluginDir, fromVersion, toVersion, baselineVersion, 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>');
+		console.error('Usage: node worker.js --pluginDir <dir> --fromVersion <ver> --toVersion <ver> --pluginId <id> --pkgName <name> [--baselineVersion <ver>]');
 		process.exit(1);
 	}
 
 	try {
-		await runUpgrade({ pluginDir, fromVersion, toVersion, pluginId, pkgName });
+		await runUpgrade({ pluginDir, fromVersion, toVersion, baselineVersion, pluginId, pkgName });
 		process.exit(0);
 	}
 	catch (err) {

package/src/plugin-version.js

@@ -1,7 +1,9 @@
 import fs from 'node:fs/promises';
 import nodePath from 'node:path';
 
-// 延迟读取 + 缓存：避免模块加载时 package.json 损坏导致插件整体无法注册
+// 延迟读取 + 缓存：避免模块加载时 package.json 损坏导致插件整体无法注册。
+// 仅供 info 类展示；upgradeHealth / inflight 对账的判定禁用本原语，
+// 必须用 src/auto-upgrade/updater.js 的加载时刻快照（getLoadedPluginVersion）。
 let __pluginVersion = null;
 export async function getPluginVersion() {
 	if (__pluginVersion) return __pluginVersion;

package/src/provider-auth/portal-model-catalog.js

@@ -15,15 +15,18 @@
  *   返回的 proper-case，name 用展示名。
  * - 只维护**最必须的运行元数据**：`reasoning`（是否推理模型——缺省会被当成 false，导致推理
  *   模型被按普通模型处理、思考模式出错）、`contextWindow`、`maxTokens`。**不写 `cost`**：
- *   portal 走 token plan、不按量计费，价格无意义；`input` 也不写（系统默认即 `['text']`）。
+ *   portal 走 token plan、不按量计费，价格无意义；`input` 默认不写（系统默认即 `['text']`），
+ *   除非该型号多模态（如 M3 支持 `['text', 'image']`）才显式写出。
  *   这几个值与上游 `model-definitions.ts`（DEFAULT_MINIMAX_CONTEXT_WINDOW=204800 /
- *   DEFAULT_MINIMAX_MAX_TOKENS=131072）+ `provider-models.ts`（reasoning 标记）对齐。
+ *   MINIMAX_M3_CONTEXT_WINDOW=1_000_000 / DEFAULT_MINIMAX_MAX_TOKENS=131072）+
+ *   `provider-models.ts`（reasoning / input 标记）对齐。
  */
 
 export const PORTAL_MODEL_CATALOG = {
-	// 与 openclaw-repo/extensions/minimax/ 的 provider-models.ts(reasoning) +
-	// model-definitions.ts(contextWindow/maxTokens) 对齐
+	// 与 openclaw-repo/extensions/minimax/ 的 provider-models.ts(reasoning/input) +
+	// model-definitions.ts(contextWindow/maxTokens) 对齐；M3 起为上游默认型号、放首位
 	'minimax-portal': [
+		{ id: 'MiniMax-M3', name: 'MiniMax M3', reasoning: true, input: ['text', 'image'], contextWindow: 1000000, maxTokens: 131072 },
 		{ id: 'MiniMax-M2.7', name: 'MiniMax M2.7', reasoning: true, contextWindow: 204800, maxTokens: 131072 },
 		{ id: 'MiniMax-M2.7-highspeed', name: 'MiniMax M2.7 Highspeed', reasoning: true, contextWindow: 204800, maxTokens: 131072 },
 	],
@@ -31,15 +34,16 @@ export const PORTAL_MODEL_CATALOG = {
 
 /**
  * 取某 provider 的静态清单。返回**深拷贝**，避免调用方改到共享常量。
- * 未知 provider → 空数组。条目字段为扁平基本类型，`{ ...m }` 即为完整深拷贝。
+ * 未知 provider → 空数组。用 `structuredClone` 而非 `{ ...m }`：条目含嵌套字段（如 M3 的
+ * `input` 数组），浅拷贝会让返回值与共享常量复用同一个数组引用，调用方 push/splice 即污染原表。
  *
  * @param {string} providerId
- * @returns {{id:string, name:string, reasoning?:boolean, contextWindow?:number, maxTokens?:number}[]}
+ * @returns {{id:string, name:string, reasoning?:boolean, input?:string[], contextWindow?:number, maxTokens?:number}[]}
  */
 export function getPortalModels(providerId) {
 	const list = PORTAL_MODEL_CATALOG[providerId];
 	if (!Array.isArray(list)) return [];
-	return list.map((m) => ({ ...m }));
+	return list.map((m) => structuredClone(m));
 }
 
 /**

package/src/provider-auth/reconcile.js

@@ -21,25 +21,35 @@ import { getPortalModels, portalModelsCoveredById } from './portal-model-catalog
  * @param {Function} opts.getConfig - () → 当前 cfg 快照（getClawConfig）；null/缺时跳过
  * @param {Function} opts.mutateConfigFile - openclaw/plugin-sdk/config-mutation 的写盘入口
  * @param {string} [opts.providerId] - 默认 minimax-portal
+ * @param {object} [opts.logger] - gateway 注入的 pino 风格 logger（本地诊断）
+ * @param {Function} [opts.remoteLog] - remoteLog(text)（远程诊断；启动一次、低频）
  * @returns {Promise<{changed:boolean, reason:string}>} reason: no-config|not-bound|no-catalog|in-sync|updated
  */
-export async function reconcilePortalModels({ getConfig, mutateConfigFile, providerId = PORTAL_PROVIDER_ID }) {
+export async function reconcilePortalModels({ getConfig, mutateConfigFile, providerId = PORTAL_PROVIDER_ID, logger, remoteLog }) {
 	const cfg = getConfig?.();
-	// runtime 未注入 / config 不可读：跳过，下次启动再对
+	// runtime 未注入 / config 不可读：跳过，下次启动再对（非事件，不记诊断）
 	if (!cfg || typeof cfg !== 'object') return { changed: false, reason: 'no-config' };
 	const node = cfg.models?.providers?.[providerId];
-	// 未绑定（无 provider 节点）→ 不碰。登录成功时已写过节点 + 清单，绑定后才谈得上对账
+	// 未绑定（无 provider 节点）→ 不碰。登录成功时已写过节点 + 清单，绑定后才谈得上对账。
+	// 同属非事件（未用该 provider 的网关每次启动都会到这）→ 不记诊断，避免刷屏
 	if (!node || typeof node !== 'object' || Array.isArray(node)) return { changed: false, reason: 'not-bound' };
+	// 到这里 provider 已绑定，"模型清单是否需要注入"才成立——后续每个结果都记诊断（本地 log + remoteLog）。
+	// remoteLog 一次启动一条、低频，符合约定。
 	const target = getPortalModels(providerId);
+	const finish = (changed, reason, count) => {
+		logger?.info?.(`[coclaw] ${providerId} model reconcile: ${changed ? 'synced' : 'no write'} (reason=${reason}, models=${count})`);
+		remoteLog?.(`providerAuth.portalReconcile reason=${reason} changed=${changed} provider=${providerId} models=${count}`);
+		return { changed, reason };
+	};
 	// 表里没这个 provider（理论不该发生）→ 不动用户已有清单
-	if (target.length === 0) return { changed: false, reason: 'no-catalog' };
+	if (target.length === 0) return finish(false, 'no-catalog', 0);
 	// 只按 id 判"已覆盖"：目标里每个 model id 都已在配置现有清单出现 → 视为已同步、零写入。
 	// 比"全等"宽容——配置是我们的超集（别的来源，如官方 MiniMax 插件，多写了几个模型）时也判已覆盖、
 	// 不去动它，避免和它来回覆盖、反复重启。仅当配置缺了我们某个 id（升级新增模型 / 老配置不全）才写。
 	// 顺带说清读/写不对称：getConfig 读「解析后」配置（config.current()），mutateConfigFile 默认写
 	// 「源」配置。即便上游将来在解析期给第三方 portal 注入额外模型，那也只是让配置成超集、我们的 id 仍在
 	// → 判已覆盖 → 不写，不会触发"永远判不一致、每次启动都写"的循环。
-	if (portalModelsCoveredById(node.models, target)) return { changed: false, reason: 'in-sync' };
+	if (portalModelsCoveredById(node.models, target)) return finish(false, 'in-sync', target.length);
 
 	await mutateConfigFile({
 		afterWrite: { mode: 'auto' },
@@ -50,5 +60,5 @@ export async function reconcilePortalModels({ getConfig, mutateConfigFile, provi
 			p.models = getPortalModels(providerId);
 		},
 	});
-	return { changed: true, reason: 'updated' };
+	return finish(true, 'updated', target.length);
 }