@lark-apaas/openclaw-scripts-diagnose-cli 0.1.15-alpha.9 → 0.1.15

package/dist/index.cjs

@@ -52,7 +52,7 @@ node_assert = __toESM(node_assert);
 * it terse and parseable.
 */
 function getVersion() {
-	return "0.1.15-alpha.9";
+	return "0.1.15";
 }
 //#endregion
 //#region src/rule-engine/base.ts
@@ -1770,6 +1770,96 @@ SessionPersistenceRule = __decorate([Rule({
 	level: "silent"
 })], SessionPersistenceRule);
 //#endregion
+//#region src/rules/tools-allow-also-allow-conflict.ts
+/**
+* 检测 tools 配置中 allow 与 alsoAllow 同时非空的冲突。
+*
+* openclaw 的 Zod schema 在配置加载时会拒绝这种组合，原因是语义互斥：
+*   - allow：完全替换式白名单，只允许列出的工具
+*   - alsoAllow：追加式，在 profile 或默认基线上叠加额外工具
+* 两者同时存在会导致 openclaw 服务启动失败。
+*
+* 修复策略：将 alsoAllow 的条目去重合并进 allow，删除 alsoAllow。
+* 这是最保守的修复：保留原 allow 的精确白名单，不扩大权限范围。
+*
+* 检测范围：
+*   - 顶层 tools
+*   - tools.byProvider.*
+*   - agents.list[].tools
+*   - agents.list[].tools.byProvider.*
+*/
+let ToolsAllowAlsoAllowConflictRule = class ToolsAllowAlsoAllowConflictRule extends DiagnoseRule {
+	validate(ctx) {
+		const conflicts = [];
+		visitAllScopes(ctx.config, (scope, label) => {
+			if (hasConflict(scope)) conflicts.push(label);
+		});
+		if (conflicts.length === 0) return { pass: true };
+		return {
+			pass: false,
+			message: `tools allow 与 alsoAllow 冲突（${conflicts.length} 处）：${conflicts.join("；")}。修复方式：将 alsoAllow 合并进 allow 并删除 alsoAllow`
+		};
+	}
+	repair(ctx) {
+		visitAllScopes(ctx.config, (scope) => mergeInScope(scope));
+	}
+};
+ToolsAllowAlsoAllowConflictRule = __decorate([Rule({
+	key: "tools_allow_also_allow_conflict",
+	description: "tools 配置中 allow 与 alsoAllow 同时设置会导致 openclaw 启动失败；自动将 alsoAllow 合并进 allow（实验性）",
+	dependsOn: ["config_syntax_check"],
+	repairMode: "standard",
+	level: "critical",
+	profile: "experimental"
+})], ToolsAllowAlsoAllowConflictRule);
+/**
+* 遍历所有 tools-policy scope，对每个 scope 调用 callback。
+* validate 和 repair 共用同一套遍历逻辑，确保两者覆盖的 scope 始终一致。
+*/
+function visitAllScopes(config, cb) {
+	const topTools = asRecord(asRecord(config)?.tools);
+	if (topTools) {
+		cb(topTools, "tools");
+		const byProvider = asRecord(topTools.byProvider);
+		if (byProvider) for (const key of Object.keys(byProvider)) {
+			const scope = asRecord(byProvider[key]);
+			if (scope) cb(scope, `tools.byProvider.${key}`);
+		}
+	}
+	const agents = asRecord(asRecord(config)?.agents);
+	const list = Array.isArray(agents?.list) ? agents.list : [];
+	for (let i = 0; i < list.length; i++) {
+		const agent = asRecord(list[i]);
+		const agentId = typeof agent?.id === "string" ? agent.id : String(i);
+		const tools = asRecord(agent?.tools);
+		if (tools) {
+			cb(tools, `agents.list[${agentId}].tools`);
+			const byProvider = asRecord(tools.byProvider);
+			if (byProvider) for (const key of Object.keys(byProvider)) {
+				const scope = asRecord(byProvider[key]);
+				if (scope) cb(scope, `agents.list[${agentId}].tools.byProvider.${key}`);
+			}
+		}
+	}
+}
+/** scope 中 allow 与 alsoAllow 同时非空 */
+function hasConflict(scope) {
+	const allow = scope.allow;
+	const alsoAllow = scope.alsoAllow;
+	return Array.isArray(allow) && allow.length > 0 && Array.isArray(alsoAllow) && alsoAllow.length > 0;
+}
+/**
+* 将 alsoAllow 去重合并进 allow，删除 alsoAllow。
+* 仅保留字符串元素，过滤掉格式异常的非字符串条目，避免写入损坏配置。
+*/
+function mergeInScope(scope) {
+	if (!hasConflict(scope)) return;
+	const allow = scope.allow.filter((v) => typeof v === "string");
+	const alsoAllow = scope.alsoAllow.filter((v) => typeof v === "string");
+	scope.allow = [...new Set([...allow, ...alsoAllow])];
+	delete scope.alsoAllow;
+}
+//#endregion
 //#region src/rules/feishu-default-account.ts
 /**
 * Owns the multi-agent feishu-channel migration: turns legacy v1/v2
@@ -2544,6 +2634,19 @@ const SECRETS_FILE_PATH = "/home/gem/workspace/.force/openclaw/miaoda-openclaw-s
 /** Absolute path to the openclaw config JSON. */
 const CONFIG_PATH = `${WORKSPACE_DIR}/openclaw.json`;
 /**
+* upgrade-lark 场景专属修复状态的信号文件目录。
+* fixStatus 有值时在此目录下创建同名文件（如 /tmp/event/PORT_FIX_READY），
+* 文件内容为完整的 UpgradeLarkResult JSON，供外部进程轮询感知升级结果。
+*/
+const FIX_EVENT_DIR = "/tmp/event";
+/**
+* 安装指令互斥锁文件路径。
+* upgrade-lark / install-openclaw / install-extension / install-cli / reset --worker
+* 共享此锁，同一时刻只允许一个安装指令运行。
+* 锁文件内容：{ pid, command, startedAt }。
+*/
+const INSTALL_LOCK_FILE = `${DIAGNOSE_DIR}/install.lock`;
+/**
 * upgrade-lark 每次运行的日志文件路径，含时间戳便于按时间排序定位。
 * checkOnly=true 时文件名含 "-check" 后缀，便于与正式安装日志区分。
 */
@@ -3223,6 +3326,13 @@ function execCaptureErr(cmd) {
 		throw new Error(stderrStr ? `${base}\nstderr: ${stderrStr}` : base);
 	}
 }
+/**
+* Synchronous sleep using Atomics.wait on a shared buffer.
+* Works on the main thread (unlike setTimeout which requires an event loop tick).
+*/
+function sleepSync(ms) {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 /** POSIX single-quote shell escape. Paths with embedded quotes are rare but
 *  the token-file path conventions in sandboxes don't guarantee cleanliness. */
 function shellQuote(s) {
@@ -4070,9 +4180,10 @@ let FeishuBotChannelConfigRule = class FeishuBotChannelConfigRule extends Diagno
 		};
 	}
 	/** Check a single bot entry (either an account object or the feishu channel itself).
-	*  appSecret is validated based on its current type:
 	*  - object → must match canonical provider-ref
 	*  - string → must match larkApps plaintext
+	*  - undefined/null → missing
+	*  - other → unexpected type
 	*/
 	checkBot(label, bot, larkApp, issues) {
 		const creatorOpenID = larkApp.creatorOpenID;
@@ -4085,7 +4196,8 @@ let FeishuBotChannelConfigRule = class FeishuBotChannelConfigRule extends Diagno
 			if (!matchMap(secret, DEFAULT_FEISHU_APP_SECRET)) issues.push(`${label} appSecret is a provider-ref but not the canonical one`);
 		} else if (typeof secret === "string") {
 			if (secret !== larkApp.appSecret) issues.push(`${label} appSecret plaintext mismatch`);
-		} else issues.push(`${label} appSecret has unexpected type ${typeof secret}`);
+		} else if (secret === void 0 || secret === null) issues.push(`${label} appSecret is missing`);
+		else issues.push(`${label} appSecret has unexpected type ${typeof secret}`);
 	}
 	repair(ctx) {
 		const larkApps = ctx.vars.larkApps;
@@ -4109,9 +4221,8 @@ let FeishuBotChannelConfigRule = class FeishuBotChannelConfigRule extends Diagno
 		}
 	}
 	/** Fix a single bot entry in-place.
-	*  appSecret is repaired based on its current type:
-	*  - object → fix to canonical provider-ref
-	*  - string → fix to larkApps plaintext
+	*  - object (provider-ref) → fix to canonical
+	*  - otherwise → fix to larkApps plaintext
 	*/
 	fixBot(bot, larkApp) {
 		const creatorOpenID = larkApp.creatorOpenID;
@@ -4125,9 +4236,7 @@ let FeishuBotChannelConfigRule = class FeishuBotChannelConfigRule extends Diagno
 		const secret = bot.appSecret;
 		if (typeof secret === "object" && secret !== null && !Array.isArray(secret)) {
 			if (!matchMap(secret, DEFAULT_FEISHU_APP_SECRET)) bot.appSecret = { ...DEFAULT_FEISHU_APP_SECRET };
-		} else if (typeof secret === "string") {
-			if (secret !== larkApp.appSecret) bot.appSecret = larkApp.appSecret;
-		}
+		} else if (secret !== larkApp.appSecret) bot.appSecret = larkApp.appSecret;
 	}
 };
 FeishuBotChannelConfigRule = __decorate([Rule({
@@ -7013,45 +7122,56 @@ function fixBotChannelConfig(configPath, larkApps, log) {
 		return;
 	}
 	const config = loadJSON5().parse(node_fs.default.readFileSync(configPath, "utf-8"));
-	const accounts = asRecord(getNestedMap(config, "channels", "feishu")?.accounts);
-	if (!accounts) {
-		log("no feishu accounts in config, skip bot channel config fix");
+	const feishu = asRecord(getNestedMap(config, "channels", "feishu"));
+	if (!feishu) {
+		log("no feishu channel in config, skip bot channel config fix");
 		return;
 	}
 	let fixCount = 0;
-	for (const [, account] of Object.entries(accounts)) {
+	const accounts = asRecord(feishu.accounts);
+	if (accounts) for (const [, account] of Object.entries(accounts)) {
 		const bot = asRecord(account);
 		if (!bot) continue;
 		const appId = bot.appId;
 		if (typeof appId !== "string" || !appId.startsWith("cli_")) continue;
 		const larkApp = larkApps.find((e) => e.larkAppID === appId);
 		if (!larkApp) continue;
-		const creatorOpenID = larkApp.creatorOpenID;
-		if (typeof creatorOpenID === "string" && creatorOpenID !== "") {
-			const allowFrom = Array.isArray(bot.allowFrom) ? [...bot.allowFrom] : [];
-			if (!allowFrom.includes(creatorOpenID)) {
-				allowFrom.push(creatorOpenID);
-				bot.allowFrom = allowFrom;
-				fixCount++;
-			}
-		}
-		const secret = bot.appSecret;
-		let needsFix = false;
-		if (typeof secret === "object" && secret !== null && !Array.isArray(secret)) {
-			if (!matchMap(secret, DEFAULT_FEISHU_APP_SECRET)) needsFix = true;
-		} else if (typeof secret === "string") {
-			if (secret !== larkApp.appSecret) needsFix = true;
-		} else needsFix = true;
-		if (needsFix) {
-			bot.appSecret = { ...DEFAULT_FEISHU_APP_SECRET };
-			fixCount++;
-		}
+		fixCount += fixBot(bot, larkApp);
+	}
+	const singleAppId = feishu.appId;
+	if (typeof singleAppId === "string" && singleAppId.startsWith("cli_") && !accounts) {
+		const larkApp = larkApps.find((e) => e.larkAppID === singleAppId);
+		if (larkApp) fixCount += fixBot(feishu, larkApp);
 	}
 	if (fixCount > 0) {
 		node_fs.default.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
 		log(`fixed ${fixCount} bot channel config issue(s) (allowFrom/appSecret)`);
 	} else log("bot channel config ok, no fixes needed");
 }
+/** Fix a single bot entry in-place. Returns number of fixes applied. */
+function fixBot(bot, larkApp) {
+	let fixCount = 0;
+	const creatorOpenID = larkApp.creatorOpenID;
+	if (typeof creatorOpenID === "string" && creatorOpenID !== "") {
+		const allowFrom = Array.isArray(bot.allowFrom) ? [...bot.allowFrom] : [];
+		if (!allowFrom.includes(creatorOpenID)) {
+			allowFrom.push(creatorOpenID);
+			bot.allowFrom = allowFrom;
+			fixCount++;
+		}
+	}
+	const secret = bot.appSecret;
+	if (typeof secret === "object" && secret !== null && !Array.isArray(secret)) {
+		if (!matchMap(secret, DEFAULT_FEISHU_APP_SECRET)) {
+			bot.appSecret = { ...DEFAULT_FEISHU_APP_SECRET };
+			fixCount++;
+		}
+	} else if (secret !== larkApp.appSecret) {
+		bot.appSecret = larkApp.appSecret;
+		fixCount++;
+	}
+	return fixCount;
+}
 /**
 * Step 7: Verify startup scripts landed in configDir/scripts/.
 *
@@ -7275,14 +7395,6 @@ function getResetTask(taskId) {
 		progress: "等待中..."
 	};
 }
-/**
-* Synchronous sleep using Atomics.wait on a shared buffer.
-*/
-function sleepSync(ms) {
-	const buf = new SharedArrayBuffer(4);
-	const arr = new Int32Array(buf);
-	Atomics.wait(arr, 0, 0, ms);
-}
 //#endregion
 //#region src/oss/resolveOssFileMap.ts
 /**
@@ -10602,7 +10714,7 @@ async function reportCliRun(opts) {
 //#region src/help.ts
 const BIN = "mclaw-diagnose";
 function versionBanner() {
-	return `v0.1.15-alpha.9`;
+	return `v0.1.15`;
 }
 const COMMANDS = [
 	{
@@ -11188,42 +11300,6 @@ function reportDoctorRunToSlardar(opts) {
 		}
 	});
 }
-const LOG_PREFIX_RE = /^\[\d{4}-\d{2}-\d{2}T[\d:.]+Z\](?:\s+\[run=[^\]]+\])?\s*/;
-/**
-* 读取日志文件末尾最多 maxBytes 字节，过滤噪音后返回纯内容。
-* - 剥除每行的时间戳 + run tag 前缀
-* - 过滤纯分隔符行（全为 '='）
-* 日志头部为固定 banner，有价值的内容集中在末尾，从尾部截取。
-*/
-function readLogFileTail(filePath, maxBytes = 4e3) {
-	let fd = -1;
-	try {
-		fd = node_fs.default.openSync(filePath, "r");
-		const { size } = node_fs.default.fstatSync(fd);
-		const readOffset = size > maxBytes ? size - maxBytes : 0;
-		const readSize = size - readOffset;
-		const buf = Buffer.allocUnsafe(readSize);
-		node_fs.default.readSync(fd, buf, 0, readSize, readOffset);
-		let start = 0;
-		while (start < buf.length && buf[start] !== 10) start++;
-		return (start < buf.length ? buf.subarray(start + 1).toString("utf-8") : buf.toString("utf-8")).split("\n").map((line) => line.replace(LOG_PREFIX_RE, "")).filter((line) => !/^=+$/.test(line.trim())).join("\n").trim();
-	} catch {
-		return "";
-	} finally {
-		if (fd !== -1) try {
-			node_fs.default.closeSync(fd);
-		} catch {}
-	}
-}
-/**
-* 向 Slardar 上报 upgrade-lark 运行结果（upgrade_lark_run 事件）。
-*
-* extraCategories 记录字符串维度：scene、exit_code、rollback_ok、
-* validation_error、error_msg、log_content（日志文件末尾 4000 字节，含关键结果）。
-*
-* extraMetrics 记录各阶段耗时（毫秒）；未执行的阶段上报 -1 作为哨兵值，
-* 便于在 Slardar 查询时区分"未运行"和"运行了 0ms"。
-*/
 /**
 * 向 Slardar 上报 upgrade-lark 运行结果（upgrade_lark_run 事件）。
 *
@@ -11234,13 +11310,16 @@ function readLogFileTail(filePath, maxBytes = 4e3) {
 * ## extraCategories（字符串维度）
 * - scene：调用方标识（如 PageUpgradeLark）
 * - check_only：是否为 --check 仅诊断模式
-* - skipped："true" 表示前置门控未触发跳过安装（含 --check 模式），"false" 表示执行了安装
-* - skip_reason：跳过原因描述（skipped=true 时有值，"check" 表示 --check 模式）
-* - exit_code：npx 子进程退出码（跳过安装时为空）
-* - rollback_ok：回滚是否成功（未触发回滚时为空）
-* - validation_error：安装后校验失败的错误信息
-* - error_msg：命令级错误信息
-* - log_content：日志文件末尾 4000 字节（过滤时间戳和分隔符行）
+* - status：与 UpgradeLarkResult.status 一致（success / skipped / failed）
+* - skip_reason：跳过原因（对应 UpgradeLarkResult.skipReason）
+* - upgrade_needed：仅 --check 模式，是否检测到需要升级（对应 UpgradeLarkResult.upgradeNeeded）
+* - exit_code：npx 子进程退出码（对应 UpgradeLarkResult.exitCode，跳过安装时为空）
+* - rollback_ok：回滚是否成功（对应 UpgradeLarkResult.rollbackOk，未触发回滚时为空）
+* - validation_error：安装后校验失败信息（对应 UpgradeLarkResult.validationError）
+* - error：命令级错误信息（对应 UpgradeLarkResult.error）
+* - port_check_ok：端口存活检测结果（对应 UpgradeLarkResult.portCheckOk，未执行时为空）
+* - result：执行结果一行摘要（派生字段，见 buildUpgradeLarkResultSummary）
+* - log_file：日志文件绝对路径（对应 UpgradeLarkResult.logFile）
 *
 * ## extraMetrics（数值指标，单位毫秒）
 * 未执行的阶段上报 -1 作为哨兵值，便于与"运行了 0ms"区分。
@@ -11253,23 +11332,25 @@ function readLogFileTail(filePath, maxBytes = 4e3) {
 * 注：[7/7] 重启耗时写入日志但未单独上报，包含在 durationMs 总耗时中。
 */
 function reportUpgradeLarkToSlardar(opts) {
-	console.error(`[slardar] upgrade_lark_run scene=${opts.scene ?? ""} checkOnly=${opts.checkOnly} skipped=${opts.skipped ?? false} success=${opts.success} exitCode=${opts.exitCode ?? ""} rollbackOk=${opts.rollbackOk ?? ""}`);
+	console.error(`[slardar] upgrade_lark_run scene=${opts.scene ?? ""} checkOnly=${opts.checkOnly} status=${opts.resultStatus} exitCode=${opts.exitCode ?? ""} rollbackOk=${opts.rollbackOk ?? ""}`);
 	const t = opts.timing ?? {};
-	const logContent = readLogFileTail(opts.logFile);
 	reportTask({
 		eventName: "upgrade_lark_run",
 		durationMs: opts.durationMs,
-		status: opts.success ? "success" : "failed",
+		status: opts.resultStatus === "failed" || opts.upgradeNeeded ? "failed" : "success",
 		extraCategories: {
 			scene: opts.scene ?? "",
 			check_only: String(opts.checkOnly),
-			skipped: String(opts.skipped ?? false),
+			status: opts.resultStatus,
 			skip_reason: opts.skipReason ?? "",
+			upgrade_needed: String(opts.upgradeNeeded ?? ""),
 			exit_code: String(opts.exitCode ?? ""),
-			rollback_ok: opts.rollbackOk != null ? String(opts.rollbackOk) : "",
+			rollback_ok: String(opts.rollbackOk ?? ""),
 			validation_error: opts.validationError ?? "",
-			error_msg: opts.error ?? "",
-			log_content: logContent
+			error: opts.error ?? "",
+			port_check_ok: String(opts.portCheckOk ?? ""),
+			result: opts.resultSummary,
+			log_file: opts.logFile
 		},
 		extraMetrics: {
 			pre_probe_ms: t.preProbeMs ?? -1,
@@ -11277,10 +11358,28 @@ function reportUpgradeLarkToSlardar(opts) {
 			backup_ms: t.backupMs ?? -1,
 			npx_install_ms: t.npxInstallMs ?? -1,
 			post_probe_ms: t.postProbeMs ?? -1,
-			doctor_fix_ms: t.doctorFixMs ?? -1
+			doctor_fix_ms: t.doctorFixMs ?? -1,
+			port_check_ms: t.portCheckMs ?? -1
 		}
 	});
 }
+/**
+* 将 upgrade-lark 运行结果归纳为一行摘要字符串，用于 Slardar result 字段。
+*
+* 格式：
+*   "check: upgrade needed"  / "check: no upgrade needed"
+*   "skipped: <skipReason>"
+*   "success: upgrade installed"
+*   "failed: <error> (rolled back)" / "failed: <error> (rollback FAILED)"
+*/
+function buildUpgradeLarkResultSummary(result, checkOnly) {
+	if (result.status === "skipped") {
+		if (checkOnly) return result.upgradeNeeded ? "check: upgrade needed" : "check: no upgrade needed";
+		return `skipped: ${result.skipReason ?? "pre-check gate"}`;
+	}
+	if (result.status === "success") return "success: upgrade installed";
+	return `failed: ${result.error ?? result.validationError ?? "unknown error"}${result.rollbackOk === false ? " (rollback FAILED)" : result.rollbackOk ? " (rolled back)" : ""}`;
+}
 //#endregion
 //#region src/upgrade-lark.ts
 /** 升级前需备份的 extensions/ 下的插件目录 */
@@ -11419,6 +11518,82 @@ function probeChannels(label, log, timeoutMs) {
 		};
 	}
 }
+/**
+* 根据 scene、最终状态和端口检测结果，计算场景专属修复状态。
+* scene 不在已知场景列表时返回 undefined。
+*/
+function computeFixStatus(scene, status, portCheckOk = void 0) {
+	if (scene === "FromPreviewFailed") return status === "success" && portCheckOk !== false ? "PORT_FIX_READY" : "PORT_FIX_FAILED";
+	if (scene === "FromChannelFailed") return status === "success" ? "CHANNEL_FIX_READY" : "CHANNEL_FIX_FAILED";
+}
+/**
+* 轮询端口检测脚本，确认 openclaw-gateway 在重启后监听指定端口。
+*
+* 逻辑：
+*   1. 先等待 initialWaitMs（让服务有时间完成重启）
+*   2. 循环执行 `bash ${BUILTIN_PATH}/tool/port_check.sh <port>`，至多 maxAttempts 次：
+*      - 输出为空 → 服务尚未就绪，等 intervalMs 后重试
+*      - 输出含端口号 → 端口存活，返回 ok=true
+*      - 输出非空但不含端口号 → 端口异常，立即返回 ok=false
+*   3. 超过 maxAttempts 仍无响应 → 返回 ok=false
+*
+* 注意：${BUILTIN_PATH} 是沙箱 shell 环境变量，通过 `bash -c` 让 shell 自行展开，
+* Node 侧不读取、不拼接该路径。
+*/
+function pollPortCheck(opts) {
+	const { port, initialWaitMs, intervalMs, maxAttempts, log } = opts;
+	const portStr = String(port);
+	const cmd = "bash ${BUILTIN_PATH}/tool/port_check.sh " + portStr;
+	log(`  waiting ${initialWaitMs / 1e3}s before first port-check poll...`);
+	if (initialWaitMs > 0) sleepSync(initialWaitMs);
+	for (let i = 1; i <= maxAttempts; i++) {
+		const r = (0, node_child_process.spawnSync)("bash", ["-c", cmd], {
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			timeout: 1e4
+		});
+		const output = (r.stdout ?? "").trim();
+		const errout = (r.stderr ?? "").trim();
+		log(`  port-check [${i}/${maxAttempts}]: exit=${r.status ?? "null"} output=${JSON.stringify(output)}${errout ? ` stderr=${JSON.stringify(errout)}` : ""}`);
+		if (!output) {
+			sleepSync(intervalMs);
+			continue;
+		}
+		if (output.includes(portStr)) {
+			log(`  port-check: SUCCESS — port ${port} confirmed in output`);
+			return {
+				ok: true,
+				output
+			};
+		}
+		log(`  port-check: FAILED — output non-empty but port ${port} not found`);
+		return {
+			ok: false,
+			output
+		};
+	}
+	log(`  port-check: FAILED — no response after ${maxAttempts} attempts`);
+	return { ok: false };
+}
+/**
+* 将 fixStatus 信号文件写入 /tmp/event/<fixStatus>，内容为完整的 UpgradeLarkResult JSON。
+* 外部进程（如服务端诊断流程）通过轮询此文件感知升级结果。
+* 写入失败只记录日志，不影响主流程返回值。
+*/
+function writeFixStatusEvent(fixStatus, result, log) {
+	const filePath = `${FIX_EVENT_DIR}/${fixStatus}`;
+	try {
+		node_fs.default.mkdirSync(FIX_EVENT_DIR, { recursive: true });
+		node_fs.default.writeFileSync(filePath, JSON.stringify(result, null, 2));
+		log(`[fix-event] written: ${filePath}`);
+	} catch (e) {
+		log(`[fix-event] write failed: ${filePath} — ${e.message}`);
+	}
+}
 function runUpgradeLark(opts) {
 	const cwd = opts.cwd ?? "/home/gem/workspace/agent";
 	const configPath = opts.configPath ?? CONFIG_PATH;
@@ -11438,6 +11613,26 @@ function runUpgradeLark(opts) {
 	log(`  configPath : ${configPath}`);
 	log(`${"=".repeat(60)}`);
 	const timing = {};
+	for (const s of [
+		"PORT_FIX_READY",
+		"PORT_FIX_FAILED",
+		"CHANNEL_FIX_READY",
+		"CHANNEL_FIX_FAILED"
+	]) {
+		const f = `${FIX_EVENT_DIR}/${s}`;
+		try {
+			if (node_fs.default.existsSync(f)) {
+				node_fs.default.rmSync(f);
+				log(`[fix-event] cleared stale: ${f}`);
+			}
+		} catch (e) {
+			log(`[fix-event] clear failed: ${f} — ${e.message}`);
+		}
+	}
+	const finalReturn = (r) => {
+		if (r.fixStatus !== void 0) writeFixStatusEvent(r.fixStatus, r, log);
+		return r;
+	};
 	log("");
 	log("── [Pre-check A] channels probe（升级前）────────────────");
 	const t_preProbeStart = Date.now();
@@ -11476,14 +11671,14 @@ function runUpgradeLark(opts) {
 		log(`${"=".repeat(60)}`);
 		log("upgrade-lark skipped (pre-check gate)");
 		log(`${"=".repeat(60)}`);
-		return {
-			ok: true,
-			skipped: true,
+		return finalReturn({
+			status: "skipped",
 			skipReason: reason,
 			upgradeNeeded: false,
 			timing,
-			logFile
-		};
+			logFile,
+			fixStatus: computeFixStatus(opts.scene, "skipped")
+		});
 	}
 	if (beforeChannels.anyAccountWorking) {
 		const reason = "channels are working — upgrade not needed (issue detected but system is functional)";
@@ -11491,14 +11686,14 @@ function runUpgradeLark(opts) {
 		log(`${"=".repeat(60)}`);
 		log("upgrade-lark skipped (pre-check gate)");
 		log(`${"=".repeat(60)}`);
-		return {
-			ok: true,
-			skipped: true,
+		return finalReturn({
+			status: "skipped",
 			skipReason: reason,
 			upgradeNeeded: false,
 			timing,
-			logFile
-		};
+			logFile,
+			fixStatus: computeFixStatus(opts.scene, "skipped")
+		});
 	}
 	log(`  PROCEED: requiresLarkUpgrade=true (version=${versionIncompatible}, feishuConfig=${feishuConfigInvalid}) AND channels not working → running upgrade`);
 	if (opts.checkOnly) {
@@ -11506,14 +11701,13 @@ function runUpgradeLark(opts) {
 		log(`${"=".repeat(60)}`);
 		log("upgrade-lark check complete");
 		log(`${"=".repeat(60)}`);
-		return {
-			ok: true,
-			skipped: true,
+		return finalReturn({
+			status: "skipped",
 			skipReason: "check",
 			upgradeNeeded: true,
 			timing,
 			logFile
-		};
+		});
 	}
 	log("");
 	log("── [1/6] 文件备份 ────────────────────────────────────────");
@@ -11523,12 +11717,13 @@ function runUpgradeLark(opts) {
 	timing.backupMs = Date.now() - t_backupStart;
 	if (!backup.ok) {
 		log(`ERROR: ${backup.error}`);
-		return {
-			ok: false,
+		return finalReturn({
+			status: "failed",
 			error: backup.error,
 			timing,
-			logFile
-		};
+			logFile,
+			fixStatus: computeFixStatus(opts.scene, "failed")
+		});
 	}
 	log("backup: ok");
 	logVersionSnapshot("before-versions", snapshotVersions(cwd, log), log);
@@ -11569,15 +11764,15 @@ function runUpgradeLark(opts) {
 	if (statusCheckDelayMs > 0) {
 		log("");
 		log(`── 等待 ${statusCheckDelayMs / 1e3}s（让 openclaw 服务完成重启） ─────────────`);
-		Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, statusCheckDelayMs);
+		sleepSync(statusCheckDelayMs);
 		log("wait done");
 	}
 	const doRollback = (reason) => {
 		log(`ERROR: ${reason}`);
 		const rollbackOk = restoreFiles(fsOpts);
 		log(`rollback: ${rollbackOk ? "ok" : "FAILED"}`);
-		return {
-			ok: false,
+		return finalReturn({
+			status: "failed",
 			error: reason,
 			validationError: reason,
 			stdout: npxStdout,
@@ -11585,8 +11780,9 @@ function runUpgradeLark(opts) {
 			exitCode: npxExitCode,
 			rollbackOk,
 			timing,
-			logFile
-		};
+			logFile,
+			fixStatus: computeFixStatus(opts.scene, "failed")
+		});
 	};
 	log("");
 	log("── [4/5] 安装后诊断校验 ─────────────────────────────────");
@@ -11612,7 +11808,7 @@ function runUpgradeLark(opts) {
 	timing.postProbeMs = Date.now() - t_postProbeStart;
 	log(`  feishu config invalid after: ${afterChannels.feishuConfigInvalid}`);
 	const stillNeedsUpgrade = (afterVersionIncompatible || afterChannels.feishuConfigInvalid) && !afterChannels.anyAccountWorking;
-	const isNewDefaultOnly = !beforeChannels.anyAccountWorking && isDefaultOnlyState(afterChannels) && !afterVersionIncompatible;
+	const isNewDefaultOnly = !afterVersionIncompatible && !afterChannels.feishuConfigInvalid && !beforeChannels.anyAccountWorking && isDefaultOnlyState(afterChannels);
 	log(`  post-check: stillNeedsUpgrade=${stillNeedsUpgrade} (version=${afterVersionIncompatible}, feishuConfig=${afterChannels.feishuConfigInvalid}, channelsWorking=${afterChannels.anyAccountWorking}) isNewDefaultOnly=${isNewDefaultOnly}`);
 	if (stillNeedsUpgrade && !isNewDefaultOnly) return doRollback(`post-install diagnosis still shows anomaly: versionIncompatible=${afterVersionIncompatible}, feishuConfigInvalid=${afterChannels.feishuConfigInvalid}, anyAccountWorking=${afterChannels.anyAccountWorking}`);
 	if (isNewDefaultOnly) log("  post-install diagnosis: ok (new default account — plugin installed, awaiting configuration)");
@@ -11638,8 +11834,9 @@ function runUpgradeLark(opts) {
 	if (fixResult.stderr?.trim()) log(`doctor(fix) stderr:\n${fixResult.stderr.trim()}`);
 	log(`doctor(fix) exit: ${fixResult.status ?? "null"}${fixResult.error ? ` error: ${fixResult.error.message}` : ""}`);
 	log("");
-	log("── [7/7] 重启 openclaw 服务 ──────────────────────────────");
+	log("── [7/8] 重启 openclaw 服务 ──────────────────────────────");
 	const restartScript = "/opt/force/bin/openclaw_scripts/restart.sh";
+	let restartExecuted = false;
 	if (opts.skipRestart) log("  skipped: --skip-restart");
 	else if (node_fs.default.existsSync(restartScript)) {
 		const t_restart = Date.now();
@@ -11656,24 +11853,133 @@ function runUpgradeLark(opts) {
 		if (restartResult.stdout?.trim()) log(`  restart stdout:\n${restartResult.stdout.trim()}`);
 		if (restartResult.stderr?.trim()) log(`  restart stderr:\n${restartResult.stderr.trim()}`);
 		log(`  restart.sh exit: ${restartResult.status ?? "null"} (${restartMs}ms)${restartResult.error ? ` error: ${restartResult.error.message}` : ""}`);
+		restartExecuted = true;
 	} else log(`  skipped: ${restartScript} not found`);
 	log("");
+	log("── [8/8] 端口存活检测 ────────────────────────────────────");
+	let portCheckOk;
+	if (!restartExecuted) log("  skipped: restart was not executed");
+	else {
+		const t_portCheck = Date.now();
+		const pcResult = pollPortCheck({
+			port: 18789,
+			initialWaitMs: opts.portCheckInitialWaitMs ?? 3e3,
+			intervalMs: opts.portCheckIntervalMs ?? 1e3,
+			maxAttempts: opts.portCheckMaxAttempts ?? 30,
+			log
+		});
+		timing.portCheckMs = Date.now() - t_portCheck;
+		portCheckOk = pcResult.ok;
+		log(`  port-check result: ${portCheckOk ? "ok" : "FAILED"} (${timing.portCheckMs}ms)`);
+	}
+	log("");
 	log(`${"=".repeat(60)}`);
 	log("upgrade-lark completed successfully");
 	log(`${"=".repeat(60)}`);
-	return {
-		ok: true,
+	return finalReturn({
+		status: "success",
 		stdout: npxStdout,
 		stderr: npxStderr,
 		exitCode: npxExitCode,
+		portCheckOk,
 		timing,
-		logFile
+		logFile,
+		fixStatus: computeFixStatus(opts.scene, "success", portCheckOk)
+	});
+}
+//#endregion
+//#region src/install-lock.ts
+/**
+* 检查指定 PID 是否仍在运行（向进程发 signal 0，不影响其运行状态）。
+* 跨平台：Linux/macOS 均支持；Windows 不在目标平台范围内。
+*/
+function isPidAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (e) {
+		if (e.code === "EPERM") return true;
+		return false;
+	}
+}
+/**
+* 尝试获取安装操作互斥锁。
+*
+* 利用 open(O_CREAT | O_EXCL) 的 POSIX 原子性确保同一时刻只有一个安装指令运行。
+* 覆盖的安装指令：upgrade-lark / install-openclaw / install-extension / install-cli / reset --worker。
+*
+* 返回 null 表示成功获取锁；返回错误信息字符串表示锁被其他进程持有。
+* 与抛异常相比，返回值让调用方可以输出符合各自格式的 result，而不依赖 catch handler 统一处理。
+*
+* 成功获取后自动注册 process.once('exit') 释放锁，无需调用方手动清理。
+*/
+function acquireInstallLock(command) {
+	node_fs.default.mkdirSync(DIAGNOSE_DIR, { recursive: true });
+	const info = {
+		pid: process.pid,
+		command,
+		startedAt: (/* @__PURE__ */ new Date()).toISOString()
 	};
+	const content = JSON.stringify(info);
+	while (true) try {
+		const fd = node_fs.default.openSync(INSTALL_LOCK_FILE, node_fs.default.constants.O_CREAT | node_fs.default.constants.O_EXCL | node_fs.default.constants.O_WRONLY, 420);
+		node_fs.default.writeSync(fd, content);
+		node_fs.default.closeSync(fd);
+		process.once("exit", releaseInstallLock);
+		console.error(`[install-lock] acquired command=${command} pid=${process.pid}`);
+		return null;
+	} catch (e) {
+		if (e.code !== "EEXIST") throw e;
+		let existing = null;
+		try {
+			existing = JSON.parse(node_fs.default.readFileSync(INSTALL_LOCK_FILE, "utf-8"));
+		} catch {
+			try {
+				node_fs.default.rmSync(INSTALL_LOCK_FILE, { force: true });
+			} catch {}
+			continue;
+		}
+		if (!isPidAlive(existing.pid)) {
+			console.error(`[install-lock] stale lock detected (pid=${existing.pid} command=${existing.command}), removing`);
+			try {
+				node_fs.default.rmSync(INSTALL_LOCK_FILE, { force: true });
+			} catch {}
+			continue;
+		}
+		const conflictMsg = `另一个安装指令正在运行，请等待其完成后重试。\n  占用指令: ${existing.command}\n  进程 PID : ${existing.pid}\n  开始时间: ${existing.startedAt}\n  锁文件  : ${INSTALL_LOCK_FILE}`;
+		console.error(`[install-lock] conflict: command=${command} blocked by pid=${existing.pid} command=${existing.command}`);
+		return conflictMsg;
+	}
+}
+/**
+* 释放安装操作互斥锁。
+* 仅删除由本进程创建的锁文件，避免误删其他进程的锁。
+* 通常由 process.once('exit') 自动调用，不需要手动调用。
+*/
+function releaseInstallLock() {
+	try {
+		const raw = node_fs.default.readFileSync(INSTALL_LOCK_FILE, "utf-8");
+		const info = JSON.parse(raw);
+		if (info.pid === process.pid) {
+			node_fs.default.rmSync(INSTALL_LOCK_FILE, { force: true });
+			console.error(`[install-lock] released command=${info.command} pid=${process.pid}`);
+		}
+	} catch {}
 }
 //#endregion
 //#region src/index.ts
+/** 锁冲突时各 install 命令的统一处理：输出 { ok: false } 并退出 */
+function handleInstallLockConflict(lockErr) {
+	console.log(JSON.stringify({
+		ok: false,
+		error: lockErr
+	}));
+	node_process.default.exit(1);
+}
 const args = node_process.default.argv.slice(2);
 const mode = args.find((a) => !a.startsWith("-"));
+const t0 = Date.now();
+const scene = getFlag(args, "scene");
 /**
 * Pull the first non-flag positional after the mode name.
 * (The mode itself is args[0] in the filtered set, so we skip index 0.)
@@ -11757,13 +12063,11 @@ async function main() {
 	}
 	const caller = getFlag(args, "caller");
 	const traceId = getFlag(args, "trace-id");
-	const scene = getFlag(args, "scene");
 	const profile = getFlag(args, "profile") === "experimental" ? "experimental" : "standard";
 	const rc = setRunContext({
 		caller,
 		traceId
 	});
-	const t0 = Date.now();
 	console.error(`${mode}: begin argv=[${args.join(" ")}] version=${getVersion()} traceId=${traceId ?? "-"} caller=${caller ?? "-"} runIdGenerated=${rc.generated}`);
 	switch (mode) {
 		case "check": {
@@ -11871,6 +12175,17 @@ async function main() {
 					node_process.default.exit(1);
 				}
 				const resultFile = resetResultFile(taskId);
+				const resetLockErr = acquireInstallLock("reset");
+				if (resetLockErr) {
+					try {
+						node_fs.default.writeFileSync(resultFile, JSON.stringify({
+							status: "failed",
+							error: resetLockErr
+						}));
+					} catch {}
+					node_process.default.exitCode = 1;
+					return;
+				}
 				const raw = await fetchCtxViaInnerApi({
 					populate: planCtxPopulate({ command: "reset" }),
 					caller,
@@ -11914,6 +12229,8 @@ async function main() {
 				console.error("Usage: install-openclaw <tag> [--oss_file_map=<base64>]");
 				node_process.default.exit(1);
 			}
+			const installOcLockErr = acquireInstallLock("install-openclaw");
+			if (installOcLockErr) handleInstallLockConflict(installOcLockErr);
 			const ossFileMapFlag = getFlag(args, "oss_file_map");
 			let installOssFileMap;
 			let rawForTelemetry;
@@ -11956,6 +12273,8 @@ async function main() {
 				console.error("Usage: install-extension <tag> (--all | --extension=<name>...) [--home_base=<dir>] [--config_path=<path>] [--skip-config-update] [--oss_file_map=<base64>]");
 				node_process.default.exit(1);
 			}
+			const installExtLockErr = acquireInstallLock("install-extension");
+			if (installExtLockErr) handleInstallLockConflict(installExtLockErr);
 			const all = args.includes("--all");
 			const names = getMultiFlag(args, "extension");
 			const homeBase = getFlag(args, "home_base");
@@ -12019,6 +12338,8 @@ async function main() {
 				console.error("Usage: install-cli <tag> --cli=<name>... [--home_base=<dir>] [--oss_file_map=<base64>]");
 				node_process.default.exit(1);
 			}
+			const installCliLockErr = acquireInstallLock("install-cli");
+			if (installCliLockErr) handleInstallLockConflict(installCliLockErr);
 			const homeBase = getFlag(args, "home_base");
 			const ossFileMapFlag = getFlag(args, "oss_file_map");
 			let installOssFileMap;
@@ -12162,6 +12483,31 @@ async function main() {
 		}
 		case "upgrade-lark": {
 			const checkOnly = args.includes("--check");
+			if (!checkOnly) {
+				const upgradeLockErr = acquireInstallLock("upgrade-lark");
+				if (upgradeLockErr) {
+					const fixStatus = computeFixStatus(scene, "failed");
+					const failResult = {
+						status: "failed",
+						error: upgradeLockErr,
+						logFile: "",
+						fixStatus
+					};
+					if (fixStatus !== void 0) writeFixStatusEvent(fixStatus, failResult, console.error);
+					console.log(JSON.stringify(failResult));
+					reportUpgradeLarkToSlardar({
+						scene,
+						checkOnly,
+						durationMs: Date.now() - t0,
+						resultStatus: "failed",
+						error: upgradeLockErr,
+						logFile: "",
+						resultSummary: buildUpgradeLarkResultSummary(failResult, checkOnly)
+					});
+					node_process.default.exitCode = 1;
+					return;
+				}
+			}
 			const skipRestart = args.includes("--skip-restart");
 			const result = runUpgradeLark({
 				runId: rc.runId,
@@ -12175,14 +12521,16 @@ async function main() {
 				scene,
 				checkOnly,
 				durationMs: upgradeDurationMs,
-				success: result.ok,
-				skipped: result.skipped,
+				resultStatus: result.status,
+				upgradeNeeded: result.upgradeNeeded,
 				skipReason: result.skipReason,
 				logFile: result.logFile,
+				resultSummary: buildUpgradeLarkResultSummary(result, checkOnly),
 				exitCode: result.exitCode,
 				rollbackOk: result.rollbackOk,
 				validationError: result.validationError,
 				error: result.error,
+				portCheckOk: result.portCheckOk,
 				timing: result.timing
 			});
 			try {
@@ -12194,14 +12542,14 @@ async function main() {
 					durationMs: upgradeDurationMs,
 					caller: rc.caller,
 					traceId: rc.traceId,
-					success: result.ok,
+					success: result.status !== "failed",
 					result,
-					error: result.ok ? void 0 : { message: result.error ?? "upgrade-lark failed" }
+					error: result.status === "failed" ? { message: result.error ?? "upgrade-lark failed" } : void 0
 				});
 			} catch (e) {
 				console.error(`[telemetry] reportCliRun failed: ${e.message}`);
 			}
-			if (!result.ok || checkOnly && result.upgradeNeeded) {
+			if (result.status === "failed" || checkOnly && result.upgradeNeeded) {
 				node_process.default.exitCode = 1;
 				return;
 			}
@@ -12225,6 +12573,47 @@ main().catch((err) => {
 	const msg = err instanceof Error ? err.message : String(err);
 	console.error(`${mode ?? "<no-mode>"}: error message=${msg}`);
 	node_process.default.stderr.write(`Error: ${msg}\n`);
+	if (mode) {
+		const durationMs = Date.now() - t0;
+		if (mode === "upgrade-lark") {
+			const checkOnly = args.includes("--check");
+			const fixStatus = computeFixStatus(scene, "failed");
+			const failResult = {
+				status: "failed",
+				error: msg,
+				logFile: "",
+				fixStatus
+			};
+			if (fixStatus !== void 0) writeFixStatusEvent(fixStatus, failResult, console.error);
+			console.log(JSON.stringify(failResult));
+			reportUpgradeLarkToSlardar({
+				scene,
+				checkOnly,
+				durationMs,
+				resultStatus: "failed",
+				error: msg,
+				logFile: "",
+				resultSummary: buildUpgradeLarkResultSummary(failResult, checkOnly)
+			});
+		} else if ([
+			"doctor",
+			"check",
+			"repair",
+			"install-openclaw",
+			"install-extension",
+			"install-cli",
+			"download-resource",
+			"reset",
+			"lark-cli-init"
+		].includes(mode)) reportDoctorRunToSlardar({
+			command: mode,
+			scene,
+			profile: getFlag(args, "profile") === "experimental" ? "experimental" : "standard",
+			fix: args.includes("--fix"),
+			durationMs,
+			success: false
+		});
+	}
 	node_process.default.exitCode = 1;
 });
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/openclaw-scripts-diagnose-cli",
-  "version": "0.1.15-alpha.9",
+  "version": "0.1.15",
   "description": "CLI for OpenClaw config diagnose and repair with JSON5 support",
   "main": "dist/index.cjs",
   "bin": {