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

package/dist/index.cjs

@@ -52,7 +52,7 @@ node_assert = __toESM(node_assert);
 * it terse and parseable.
 */
 function getVersion() {
-	return "0.1.14";
+	return "0.1.15-alpha.1";
 }
 //#endregion
 //#region src/rule-engine/base.ts
@@ -2543,6 +2543,10 @@ const PROVIDER_FILE_PATH = "/home/gem/workspace/.force/openclaw/miaoda-provider-
 const SECRETS_FILE_PATH = "/home/gem/workspace/.force/openclaw/miaoda-openclaw-secrets.json";
 /** Absolute path to the openclaw config JSON. */
 const CONFIG_PATH = `${WORKSPACE_DIR}/openclaw.json`;
+/** upgrade-lark 每次运行的日志文件路径，含时间戳便于按时间排序定位。 */
+function upgradeLarkLogFile(runId) {
+	return `${DIAGNOSE_DIR}/upgrade-lark-${(/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replace(/:/g, "-")}-${runId.slice(0, 8)}.log`;
+}
 //#endregion
 //#region src/lark-cli-init.ts
 const LARK_PLUGIN_NAMES$1 = ["openclaw-lark", "feishu-openclaw-plugin"];
@@ -3678,7 +3682,6 @@ function resolveUpgradeDirection(installed, ocCur, recommendedOc, isLegacy) {
 /** 提取公共前置上下文；任何前置条件不满足时返回 null（规则 pass）。 */
 function resolveCompatContext(ctx) {
 	const recommendedOc = ctx.vars.recommendedOpenclawTag;
-	if (!recommendedOc) return null;
 	const ocCur = getOcVersion();
 	if (!ocCur) return null;
 	const installed = getInstalledPlugin(ctx);
@@ -3701,6 +3704,7 @@ let FeishuPluginOpenclawUpgradeRule = class FeishuPluginOpenclawUpgradeRule exte
 		if (!cc) return { pass: true };
 		const { ocCur, recommendedOc, installed, isLegacy } = cc;
 		if (isForkPlugin(installed)) return validateForkPlugin(installed, ocCur, recommendedOc);
+		if (!recommendedOc) return { pass: true };
 		if (resolveUpgradeDirection(installed, ocCur, recommendedOc, isLegacy) !== "openclaw") return { pass: true };
 		return {
 			pass: false,
@@ -3728,11 +3732,17 @@ let FeishuPluginLarkUpgradeRule = class FeishuPluginLarkUpgradeRule extends Diag
 		if (!cc) return { pass: true };
 		const { ocCur, recommendedOc, installed, isLegacy } = cc;
 		if (isForkPlugin(installed)) return { pass: true };
-		if (resolveUpgradeDirection(installed, ocCur, recommendedOc, isLegacy) !== "lark") return { pass: true };
+		if (!isLarkUpgradeNeededFromCC(cc)) return { pass: true };
+		const prefix = buildCompatPrefix(installed, ocCur, isLegacy);
+		if (!recommendedOc) return {
+			pass: false,
+			action: "upgrade_lark",
+			message: `${prefix}；建议升级飞书插件至兼容版本`
+		};
 		return {
 			pass: false,
 			action: "upgrade_lark",
-			message: `${buildCompatPrefix(installed, ocCur, isLegacy)}；当前 openclaw@${ocCur} 已达推荐版本，可直接升级飞书插件`
+			message: `${prefix}；当前 openclaw@${ocCur} 已达推荐版本，可直接升级飞书插件`
 		};
 	}
 };
@@ -3744,6 +3754,21 @@ FeishuPluginLarkUpgradeRule = __decorate([Rule({
 	level: "critical",
 	usesVars: ["recommendedOpenclawTag"]
 })], FeishuPluginLarkUpgradeRule);
+/**
+* 核心判断：非 fork 插件是否需要升级 lark，基于当前 openclaw 版本的兼容性。
+*
+* 被 FeishuPluginLarkUpgradeRule.validate 和 needsLarkUpgrade 共用。
+* 调用方需在调用前自行处理 fork 插件的情况（fork 插件不走本函数）。
+*
+* - 有 recommendedOc：走 resolveUpgradeDirection 判断方向是否为 'lark'
+* - 无 recommendedOc（doctor 无推荐版本）：legacy 插件直接需要升级；
+*   非 legacy 则检查当前版本是否在兼容表内
+*/
+function isLarkUpgradeNeededFromCC(cc) {
+	const { ocCur, recommendedOc, installed, isLegacy } = cc;
+	if (!recommendedOc) return isLegacy || !isVersionCompatible(installed, ocCur);
+	return resolveUpgradeDirection(installed, ocCur, recommendedOc, isLegacy) === "lark";
+}
 function isForkPlugin(p) {
 	return p.scope != null && FORK_SCOPES.includes(p.scope);
 }
@@ -3782,14 +3807,16 @@ function describeCompatConstraint(entry, pluginVersion) {
 /**
 * @lark-apaas/openclaw-lark 豁免 VERSION_COMPAT_MAP，但仍要求 openclaw ≥ FORK_LARK_PLUGIN_MIN_OC_VERSION。
 * 其他 @lark-apaas scope 的 fork 插件继续无条件 pass。
+* recommendedOc 可为 undefined（doctor 模式），此时只检测最低版本要求，不指定目标升级版本。
 */
 function validateForkPlugin(installed, ocCur, recommendedOc) {
 	if (installed.fullName !== FORK_LARK_PLUGIN_FULL_NAME) return { pass: true };
 	if (compareCalVer(ocCur, FORK_LARK_PLUGIN_MIN_OC_VERSION) >= 0) return { pass: true };
+	const recommendation = recommendedOc ? `；将 openclaw 升级到 ${recommendedOc} 即可满足` : `；请升级 openclaw 至 ${FORK_LARK_PLUGIN_MIN_OC_VERSION} 或更高版本`;
 	return {
 		pass: false,
 		action: "upgrade_openclaw",
-		message: `飞书插件 ${describePlugin(installed)}（fork 版）要求 openclaw ≥ ${FORK_LARK_PLUGIN_MIN_OC_VERSION}，当前 openclaw@${ocCur} 低于此要求；将 openclaw 升级到 ${recommendedOc} 即可满足`
+		message: `飞书插件 ${describePlugin(installed)}（fork 版）要求 openclaw ≥ ${FORK_LARK_PLUGIN_MIN_OC_VERSION}，当前 openclaw@${ocCur} 低于此要求${recommendation}`
 	};
 }
 function describePlugin(p) {
@@ -3836,6 +3863,26 @@ function extractScopedNameFromSpec$1(spec) {
 	const at = spec.indexOf("@", 1);
 	return at === -1 ? spec : spec.slice(0, at);
 }
+/**
+* 判断已安装的飞书插件是否与当前 openclaw 版本不兼容（或为需要替换的 legacy 插件）。
+* 被 upgrade-lark 前置检测门控（--check-only 和正式安装模式）调用。
+*/
+function needsLarkUpgrade(ctx) {
+	const cc = resolveCompatContext({
+		...ctx,
+		vars: {
+			...ctx.vars,
+			recommendedOpenclawTag: void 0
+		}
+	});
+	if (!cc) return false;
+	const { ocCur, installed } = cc;
+	if (isForkPlugin(installed)) {
+		if (installed.fullName === FORK_LARK_PLUGIN_FULL_NAME) return compareCalVer(ocCur, FORK_LARK_PLUGIN_MIN_OC_VERSION) < 0;
+		return false;
+	}
+	return isLarkUpgradeNeededFromCC(cc);
+}
 //#endregion
 //#region src/rules/cleanup-install-backup-dirs.ts
 const DIR_PREFIX = ".openclaw-install-";
@@ -10339,6 +10386,122 @@ function finalize(results, aborted) {
 	};
 }
 //#endregion
+//#region src/channels-probe.ts
+const FEISHU_INVALID_CONFIG_MSG = "channels.feishu: invalid config: must NOT have additional properties";
+const CHANNEL_LINE_RE = /^-\s+Feishu\s+([^:]+):\s+(.+)$/;
+/**
+* 判断单个飞书账号是否处于"可用"状态。
+* 移植自 feishu-channel-success-rate skill 的 Python `_account_is_working`。
+*
+* 会先剥离 "key:value" 形式的 bit（dm:、bot:、in:、out:、token:、allow:、
+* intents:、groups:、health: 等），再按以下公式判断：
+*
+* @param ignoreProbeFailed  为 true 时忽略 "probe failed" bit，不视为失败。
+*   升级前置检测中传 true，因为 probe 失败通常反映网络状况而非配置问题。
+* @param gatewayReachable   为 false 时（gateway 尚未启动），只要 enabled+configured
+*   即视为可用；为 true 时还需要 running/works 且无 error: bit。
+*/
+function accountIsWorking(bits, ignoreProbeFailed = true, gatewayReachable = true) {
+	const bitTokens = /* @__PURE__ */ new Set();
+	let hasError = false;
+	let hasProbeFailed = false;
+	for (const raw of bits) {
+		const b = raw.trim();
+		if (!b) continue;
+		if (b.startsWith("error:")) {
+			hasError = true;
+			continue;
+		}
+		if (b === "probe failed") {
+			hasProbeFailed = true;
+			continue;
+		}
+		bitTokens.add(b.split(":")[0]);
+	}
+	if (!bitTokens.has("enabled") || !bitTokens.has("configured")) return false;
+	if (!gatewayReachable) return true;
+	if (bitTokens.has("works")) return true;
+	if (bitTokens.has("running") && !hasError && (ignoreProbeFailed || !hasProbeFailed)) return true;
+	return false;
+}
+/**
+* 解析 `openclaw channels status --probe` 的原始 stdout。
+* 移植自 feishu-channel-success-rate skill 的 Python `extract_channels_probe`。
+*/
+function parseChannelsProbeOutput(text, { ignoreProbeFailed = true } = {}) {
+	const gatewayReachable = text.includes("Gateway reachable");
+	const feishuConfigInvalid = text.includes(FEISHU_INVALID_CONFIG_MSG);
+	const accounts = [];
+	let anyAccountWorking = false;
+	for (const line of text.split("\n")) {
+		const m = CHANNEL_LINE_RE.exec(line.trim());
+		if (!m) continue;
+		const [, acct, rest] = m;
+		const bits = rest.split(",").map((b) => b.trim());
+		const isWorking = accountIsWorking(bits, ignoreProbeFailed, gatewayReachable);
+		if (isWorking) anyAccountWorking = true;
+		accounts.push({
+			id: acct.trim(),
+			bits,
+			isWorking,
+			raw: line.trim()
+		});
+	}
+	return {
+		gatewayReachable,
+		feishuConfigInvalid,
+		accounts,
+		anyAccountWorking
+	};
+}
+/**
+* 执行 `openclaw channels status --probe`，返回结构化结果。
+*
+* 部分 bot 账号 probe 失败时命令会以非零退出码退出，但 stdout 仍有可用内容。
+* 因此即使退出码非零，也尝试解析 stdout；只有真正没有任何输出时才返回 unavailable。
+*
+* @param timeoutMs         最长等待时长，默认 60 s。v2026.4.x 缺少单请求 HTTP 超时，
+*   可能无限阻塞，此超时是唯一保护。
+* @param ignoreProbeFailed 为 true 时，"probe failed" 账号仍计入"可用"。
+*   升级前置检测中应传 true，避免网络抖动导致误判为不可用。
+*/
+function runChannelsProbe(timeoutMs = 6e4, { ignoreProbeFailed = true } = {}) {
+	let stdout = "";
+	let stderrText = "";
+	let execError;
+	try {
+		stdout = (0, node_child_process.execSync)("openclaw channels status --probe", {
+			encoding: "utf-8",
+			timeout: timeoutMs,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+	} catch (e) {
+		const err = e;
+		const stdoutRaw = err.stdout;
+		stdout = typeof stdoutRaw === "string" ? stdoutRaw : stdoutRaw?.toString("utf-8") ?? "";
+		execError = err.message;
+		const stderrRaw = err.stderr;
+		stderrText = (typeof stderrRaw === "string" ? stderrRaw : stderrRaw?.toString("utf-8") ?? "").trim();
+		if (stderrText) console.error(`channels-probe: stderr from CLI: ${stderrText}`);
+	}
+	if (stdout.trim()) return {
+		available: true,
+		...parseChannelsProbeOutput(stdout, { ignoreProbeFailed })
+	};
+	return {
+		available: false,
+		gatewayReachable: false,
+		feishuConfigInvalid: stderrText.includes(FEISHU_INVALID_CONFIG_MSG),
+		accounts: [],
+		anyAccountWorking: false,
+		error: execError ?? "no output from openclaw channels status --probe"
+	};
+}
+//#endregion
 //#region src/innerapi/reportCliRun.ts
 /**
 * CLI-side client for studio_server's `openclaw.report_cli_run` inner
@@ -10418,7 +10581,7 @@ async function reportCliRun(opts) {
 //#region src/help.ts
 const BIN = "mclaw-diagnose";
 function versionBanner() {
-	return `v0.1.14`;
+	return `v0.1.15-alpha.1`;
 }
 const COMMANDS = [
 	{
@@ -10705,6 +10868,58 @@ OPTIONS
 EXIT CODES
   0    Success or skipped (prerequisites not met).
   1    Secret/path unresolvable, lark-cli failed, or config unreadable.
+`
+	},
+	{
+		name: "upgrade-lark",
+		hidden: false,
+		summary: "Upgrade the Feishu/Lark plugin via @larksuite/openclaw-lark-tools",
+		help: `USAGE
+  ${BIN} upgrade-lark [--check-only] [--scene=<scene>] [--caller=<n>] [--trace-id=<id>]
+
+DESCRIPTION
+  Upgrades the Feishu/Lark plugin by running:
+    npx -y @larksuite/openclaw-lark-tools update --use-existing
+
+  Before the upgrade, a pre-check gate runs to verify the upgrade is needed:
+    - version incompatible OR feishu channel config invalid, AND
+    - no feishu account is currently working
+  If the gate is not triggered, the command skips with exit code 0.
+
+  Before the upgrade, the following files are backed up:
+    - openclaw.json
+    - extensions/openclaw-lark/  (if present)
+    - extensions/feishu-openclaw-plugin/  (if present)
+  After the upgrade, the result is validated:
+    - feishu.accounts bot count must not decrease
+    - gateway config structure must remain valid (port/mode/bind/auth/trustedProxies)
+  If the upgrade command fails, or validation fails, the backed-up files are
+  restored to roll back the changes.
+
+  Execution is logged to /tmp/openclaw-diagnose/upgrade-lark-<runId>.log.
+
+  Output is a single JSON object on stdout:
+    { "ok": true, "stdout": "...", "stderr": "...", "logFile": "..." }
+    { "ok": false, "error": "...", "stderr": "...", "exitCode": 1,
+      "rollbackOk": true, "validationError": "...", "logFile": "..." }
+
+  With --check-only:
+    { "ok": true, "skipped": true, "upgradeNeeded": false, "logFile": "..." }
+    { "ok": true, "skipped": true, "upgradeNeeded": true,  "logFile": "..." }  ← exit 1
+
+OPTIONS
+  --check-only       Diagnose only: run the pre-check gate and report whether
+                     upgrade is needed without installing. Exit 1 if needed.
+  --scene=<scene>    Telemetry label forwarded to Slardar only.
+                     Known values: PageUpgradeLark, etc. Custom strings accepted.
+  --caller=<name>    Optional metadata passed to innerapi.
+  --trace-id=<id>    Optional log-correlation id.
+
+EXIT CODES
+  0    Success: upgrade ran and all validations passed; or gate skipped upgrade.
+  1    Failure: npx error, validation failed, or git commit failed.
+       File rollback was attempted (see rollbackOk in the JSON output).
+       With --check-only: exit 1 means upgrade IS needed.
 `
 	},
 	{
@@ -10738,6 +10953,41 @@ EXAMPLES
   ${BIN} rules                         # all rules
   ${BIN} rules --rule=gateway          # single rule
   ${BIN} rules --rule=gateway --rule=feishu_channel  # multiple rules
+`
+	},
+	{
+		name: "channels-probe",
+		hidden: true,
+		summary: "Check feishu channel health via openclaw channels status --probe",
+		help: `USAGE
+  ${BIN} channels-probe [--timeout=<ms>]
+
+DESCRIPTION
+  Runs \`openclaw channels status --probe\` and returns a structured JSON
+  summary of whether the current environment's feishu channels are
+  configured and working correctly.
+
+  Output:
+    {
+      "available": true,
+      "gatewayReachable": true,
+      "accounts": [
+        { "id": "default", "bits": ["enabled","configured","running","works"],
+          "isWorking": true, "raw": "- Feishu default: ..." }
+      ],
+      "anyAccountWorking": true
+    }
+
+  An account is considered working when:
+    enabled ∧ configured ∧ ( works ∨ ( running ∧ no error: ∧ no probe failed ) )
+
+  "available": false means the CLI invocation itself failed (openclaw not
+  found, gateway unreachable, or no parseable output returned).
+
+OPTIONS
+  --timeout=<ms>   Max wait in milliseconds (default: 60000).  The probe
+                   can hang indefinitely on openclaw v2026.4.x due to a
+                   missing per-request HTTP timeout — set this accordingly.
 `
 	},
 	{
@@ -10912,6 +11162,403 @@ function reportDoctorRunToSlardar(opts) {
 		}
 	});
 }
+/** 读取日志文件全文；文件不存在或读取失败时返回空字符串。 */
+function readLogFile(filePath) {
+	try {
+		return node_fs.default.readFileSync(filePath, "utf-8");
+	} catch {
+		return "";
+	}
+}
+/**
+* 向 Slardar 上报 upgrade-lark 运行结果（upgrade_lark_run 事件）。
+*
+* extraCategories 记录字符串维度：scene、exit_code、rollback_ok、
+* validation_error、error_msg、log_content（日志文件全文）。
+*
+* extraMetrics 记录各阶段耗时（毫秒）；未执行的阶段上报 -1 作为哨兵值，
+* 便于在 Slardar 查询时区分"未运行"和"运行了 0ms"。
+*/
+function reportUpgradeLarkToSlardar(opts) {
+	console.error(`[slardar] upgrade_lark_run scene=${opts.scene ?? ""} success=${opts.success} exitCode=${opts.exitCode ?? ""} rollbackOk=${opts.rollbackOk ?? ""}`);
+	const t = opts.timing ?? {};
+	const logContent = readLogFile(opts.logFile);
+	reportTask({
+		eventName: "upgrade_lark_run",
+		durationMs: opts.durationMs,
+		status: opts.success ? "success" : "failed",
+		extraCategories: {
+			scene: opts.scene ?? "",
+			exit_code: String(opts.exitCode ?? ""),
+			rollback_ok: opts.rollbackOk != null ? String(opts.rollbackOk) : "",
+			validation_error: opts.validationError ?? "",
+			error_msg: opts.error ?? "",
+			log_content: logContent
+		},
+		extraMetrics: {
+			pre_probe_ms: t.preProbeMs ?? -1,
+			version_check_ms: t.versionCheckMs ?? -1,
+			backup_ms: t.backupMs ?? -1,
+			npx_install_ms: t.npxInstallMs ?? -1,
+			post_probe_ms: t.postProbeMs ?? -1,
+			doctor_fix_ms: t.doctorFixMs ?? -1
+		}
+	});
+}
+//#endregion
+//#region src/upgrade-lark.ts
+/** 升级前需备份的 extensions/ 下的插件目录 */
+const FEISHU_PLUGIN_DIRS = ["openclaw-lark", "feishu-openclaw-plugin"];
+function backupFiles(opts) {
+	const { workspaceDir, configPath, backupDir, log } = opts;
+	try {
+		node_fs.default.mkdirSync(backupDir, { recursive: true });
+		log(`backup dir: ${backupDir}`);
+		if (node_fs.default.existsSync(configPath)) {
+			const stat = node_fs.default.statSync(configPath);
+			node_fs.default.copyFileSync(configPath, node_path.default.join(backupDir, "openclaw.json"));
+			log(`  backed up: openclaw.json (${stat.size} bytes)`);
+		} else log(`  skipped: openclaw.json (not found)`);
+		const extSrc = node_path.default.join(workspaceDir, "extensions");
+		for (const pluginDir of FEISHU_PLUGIN_DIRS) {
+			const src = node_path.default.join(extSrc, pluginDir);
+			if (node_fs.default.existsSync(src)) {
+				const dst = node_path.default.join(backupDir, "extensions", pluginDir);
+				node_fs.default.cpSync(src, dst, { recursive: true });
+				const version = readPkgVersion(node_path.default.join(src, "package.json"));
+				log(`  backed up: extensions/${pluginDir}${version ? ` (version: ${version})` : ""}`);
+			} else log(`  skipped: extensions/${pluginDir} (not found)`);
+		}
+		return { ok: true };
+	} catch (e) {
+		return {
+			ok: false,
+			error: `backup failed: ${e.message}`
+		};
+	}
+}
+function restoreFiles(opts) {
+	const { workspaceDir, configPath, backupDir, log } = opts;
+	try {
+		const configBackup = node_path.default.join(backupDir, "openclaw.json");
+		if (node_fs.default.existsSync(configBackup)) {
+			node_fs.default.copyFileSync(configBackup, configPath);
+			log(`  restored: openclaw.json`);
+		}
+		const extDst = node_path.default.join(workspaceDir, "extensions");
+		for (const pluginDir of FEISHU_PLUGIN_DIRS) {
+			const backupSrc = node_path.default.join(backupDir, "extensions", pluginDir);
+			if (node_fs.default.existsSync(backupSrc)) {
+				const dst = node_path.default.join(extDst, pluginDir);
+				if (node_fs.default.existsSync(dst)) node_fs.default.rmSync(dst, {
+					recursive: true,
+					force: true
+				});
+				node_fs.default.cpSync(backupSrc, dst, { recursive: true });
+				log(`  restored: extensions/${pluginDir}`);
+			}
+		}
+		return true;
+	} catch (e) {
+		log(`  restore error: ${e.message}`);
+		return false;
+	}
+}
+function readPkgVersion(pkgPath) {
+	try {
+		const pkg = JSON.parse(node_fs.default.readFileSync(pkgPath, "utf-8"));
+		return typeof pkg.version === "string" ? pkg.version : null;
+	} catch {
+		return null;
+	}
+}
+function snapshotVersions(cwd, log) {
+	const ocResult = (0, node_child_process.spawnSync)("openclaw", ["--version"], {
+		cwd,
+		encoding: "utf-8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		timeout: 5e3
+	});
+	const ocRaw = (ocResult.stdout ?? "").trim() || (ocResult.stderr ?? "").trim();
+	const extDir = node_path.default.join(cwd, "extensions");
+	const larkPkg = node_path.default.join(extDir, "openclaw-lark", "package.json");
+	const feishuPkg = node_path.default.join(extDir, "feishu-openclaw-plugin", "package.json");
+	log(`  version-check paths: ${larkPkg} [${node_fs.default.existsSync(larkPkg) ? "exists" : "missing"}]`);
+	log(`  version-check paths: ${feishuPkg} [${node_fs.default.existsSync(feishuPkg) ? "exists" : "missing"}]`);
+	return {
+		openclaw: ocRaw || null,
+		openclawLark: readPkgVersion(larkPkg),
+		feishuOpenclawPlugin: readPkgVersion(feishuPkg)
+	};
+}
+function logVersionSnapshot(label, v, log) {
+	log(`${label}: openclaw=${v.openclaw ?? "n/a"} openclaw-lark=${v.openclawLark ?? "n/a"} feishu-openclaw-plugin=${v.feishuOpenclawPlugin ?? "n/a"}`);
+}
+function countFeishuBots(configPath) {
+	try {
+		const raw = node_fs.default.readFileSync(configPath, "utf-8");
+		const config = loadJSON5().parse(raw);
+		const accounts = getNestedMap(config, "channels", "feishu", "accounts");
+		if (accounts) return Object.keys(accounts).length;
+		const feishu = getNestedMap(config, "channels", "feishu");
+		return typeof feishu?.appId === "string" && feishu.appId ? 1 : 0;
+	} catch {
+		return 0;
+	}
+}
+/** 执行 channels probe 并将结果写入日志，从不抛出异常（异常时返回全零结果）。 */
+function probeChannels(label, log, timeoutMs) {
+	try {
+		const r = runChannelsProbe(timeoutMs);
+		log(`  ${label} available=${r.available} anyAccountWorking=${r.anyAccountWorking}`);
+		if (r.error) log(`  ${label} error: ${r.error}`);
+		if (r.gatewayReachable != null) log(`  ${label} gatewayReachable: ${r.gatewayReachable}`);
+		for (const acct of r.accounts ?? []) log(`  ${label} account ${acct.id}: isWorking=${acct.isWorking} bits=[${acct.bits.join(",")}]`);
+		return r;
+	} catch (e) {
+		log(`  ${label} channels probe threw: ${e.message}`);
+		return {
+			available: false,
+			gatewayReachable: false,
+			feishuConfigInvalid: false,
+			accounts: [],
+			anyAccountWorking: false
+		};
+	}
+}
+function runUpgradeLark(opts) {
+	const cwd = opts.cwd ?? "/home/gem/workspace/agent";
+	const configPath = opts.configPath ?? CONFIG_PATH;
+	const logFile = upgradeLarkLogFile(opts.runId);
+	const log = makeLogger(logFile);
+	const fsOpts = {
+		workspaceDir: cwd,
+		configPath,
+		backupDir: node_path.default.join(opts.backupBaseDir ?? "/tmp/openclaw-diagnose", `upgrade-lark-backup-${opts.runId}`),
+		log
+	};
+	const cliScript = opts.cliScript ?? process.argv[1];
+	const statusCheckDelayMs = opts.statusCheckDelayMs ?? 5e3;
+	log(`${"=".repeat(60)}`);
+	log(`upgrade-lark started  runId=${opts.runId}`);
+	log(`  cwd        : ${cwd}`);
+	log(`  configPath : ${configPath}`);
+	log(`${"=".repeat(60)}`);
+	const timing = {};
+	log("");
+	log("── [Pre-check A] channels probe（升级前）────────────────");
+	const t_preProbeStart = Date.now();
+	const beforeChannels = probeChannels("before", log, 6e4);
+	timing.preProbeMs = Date.now() - t_preProbeStart;
+	log("");
+	log("── [Pre-check B] 版本兼容预检 ───────────────────────────");
+	let versionIncompatible = false;
+	const t_versionCheckStart = Date.now();
+	try {
+		const rawConfig = node_fs.default.readFileSync(configPath, "utf-8");
+		versionIncompatible = needsLarkUpgrade({
+			config: loadJSON5().parse(rawConfig),
+			configPath,
+			vars: {},
+			providerDeps: {
+				usesMiaodaProvider: false,
+				usesMiaodaSecretProvider: false
+			}
+		});
+		log(`  version-compat pre-check: ${versionIncompatible ? "NEEDS_UPGRADE" : "ok"}`);
+	} catch (e) {
+		log(`  version-compat pre-check error: ${e.message} — version signal unavailable`);
+	}
+	timing.versionCheckMs = Date.now() - t_versionCheckStart;
+	const feishuConfigInvalid = beforeChannels.feishuConfigInvalid;
+	log(`  feishu config invalid  : ${feishuConfigInvalid}`);
+	log("");
+	log("── [Gate] 升级前置条件检查 ───────────────────────────────");
+	log(`  versionIncompatible    : ${versionIncompatible}`);
+	log(`  feishuConfigInvalid    : ${feishuConfigInvalid}`);
+	log(`  channels working before: ${beforeChannels.anyAccountWorking}`);
+	if (!(versionIncompatible || feishuConfigInvalid)) {
+		const reason = "version compatible and feishu channel config valid — upgrade not needed";
+		log(`  SKIP: ${reason}`);
+		log(`${"=".repeat(60)}`);
+		log("upgrade-lark skipped (pre-check gate)");
+		log(`${"=".repeat(60)}`);
+		return {
+			ok: true,
+			skipped: true,
+			skipReason: reason,
+			upgradeNeeded: false,
+			timing,
+			logFile
+		};
+	}
+	if (beforeChannels.anyAccountWorking) {
+		const reason = "channels are working — upgrade not needed (issue detected but system is functional)";
+		log(`  SKIP: ${reason}`);
+		log(`${"=".repeat(60)}`);
+		log("upgrade-lark skipped (pre-check gate)");
+		log(`${"=".repeat(60)}`);
+		return {
+			ok: true,
+			skipped: true,
+			skipReason: reason,
+			upgradeNeeded: false,
+			timing,
+			logFile
+		};
+	}
+	log(`  PROCEED: requiresLarkUpgrade=true (version=${versionIncompatible}, feishuConfig=${feishuConfigInvalid}) AND channels not working → running upgrade`);
+	if (opts.checkOnly) {
+		log(`  check-only: upgrade IS needed — returning without installing`);
+		log(`${"=".repeat(60)}`);
+		log("upgrade-lark check-only complete");
+		log(`${"=".repeat(60)}`);
+		return {
+			ok: true,
+			skipped: true,
+			skipReason: "check-only",
+			upgradeNeeded: true,
+			timing,
+			logFile
+		};
+	}
+	log("");
+	log("── [1/6] 文件备份 ────────────────────────────────────────");
+	log(`before-state: botCount=${countFeishuBots(configPath)}`);
+	const t_backupStart = Date.now();
+	const backup = backupFiles(fsOpts);
+	timing.backupMs = Date.now() - t_backupStart;
+	if (!backup.ok) {
+		log(`ERROR: ${backup.error}`);
+		return {
+			ok: false,
+			error: backup.error,
+			timing,
+			logFile
+		};
+	}
+	log("backup: ok");
+	logVersionSnapshot("before-versions", snapshotVersions(cwd, log), log);
+	log("");
+	log("── [2/6] 清理本地 openclaw shim ─────────────────────────");
+	const localOpenclawBin = node_path.default.join(cwd, "node_modules", ".bin", "openclaw");
+	if (node_fs.default.existsSync(localOpenclawBin)) try {
+		node_fs.default.rmSync(localOpenclawBin);
+		log(`  removed: ${localOpenclawBin}`);
+	} catch (e) {
+		log(`  WARN: failed to remove ${localOpenclawBin}: ${e.message}`);
+	}
+	else log(`  skipped: ${localOpenclawBin} (not found)`);
+	log("");
+	log("── [3/6] npx install (@larksuite/openclaw-lark-tools update) ──");
+	const t_npxStart = Date.now();
+	const npxResult = (0, node_child_process.spawnSync)("npx", [
+		"-y",
+		"@larksuite/openclaw-lark-tools",
+		"update"
+	], {
+		cwd,
+		encoding: "utf-8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		timeout: 12e4
+	});
+	timing.npxInstallMs = Date.now() - t_npxStart;
+	const npxStdout = npxResult.stdout?.trim() ?? "";
+	const npxStderr = npxResult.stderr?.trim() ?? "";
+	const npxExitCode = npxResult.status ?? 1;
+	if (npxStdout) log(`npx stdout:\n${npxStdout}`);
+	if (npxStderr) log(`npx stderr:\n${npxStderr}`);
+	log(`npx exit: ${npxExitCode}${npxResult.error ? ` error: ${npxResult.error.message}` : ""}`);
+	if (statusCheckDelayMs > 0) {
+		log("");
+		log(`── 等待 ${statusCheckDelayMs / 1e3}s（让 openclaw 服务完成重启） ─────────────`);
+		Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, statusCheckDelayMs);
+		log("wait done");
+	}
+	const doRollback = (reason) => {
+		log(`ERROR: ${reason}`);
+		const rollbackOk = restoreFiles(fsOpts);
+		log(`rollback: ${rollbackOk ? "ok" : "FAILED"}`);
+		return {
+			ok: false,
+			error: reason,
+			validationError: reason,
+			stdout: npxStdout,
+			stderr: npxStderr,
+			exitCode: npxExitCode,
+			rollbackOk,
+			timing,
+			logFile
+		};
+	};
+	log("");
+	log("── [4/5] 安装后诊断校验 ─────────────────────────────────");
+	logVersionSnapshot("after-versions", snapshotVersions(cwd, log), log);
+	let afterVersionIncompatible = false;
+	try {
+		const rawConfig = node_fs.default.readFileSync(configPath, "utf-8");
+		afterVersionIncompatible = needsLarkUpgrade({
+			config: loadJSON5().parse(rawConfig),
+			configPath,
+			vars: {},
+			providerDeps: {
+				usesMiaodaProvider: false,
+				usesMiaodaSecretProvider: false
+			}
+		});
+		log(`  version-compat post-check: ${afterVersionIncompatible ? "STILL_INCOMPATIBLE" : "ok"}`);
+	} catch (e) {
+		log(`  version-compat post-check error: ${e.message} — version signal unavailable`);
+	}
+	const t_postProbeStart = Date.now();
+	const afterChannels = probeChannels("after", log, 6e4);
+	timing.postProbeMs = Date.now() - t_postProbeStart;
+	log(`  feishu config invalid after: ${afterChannels.feishuConfigInvalid}`);
+	const stillNeedsUpgrade = (afterVersionIncompatible || afterChannels.feishuConfigInvalid) && !afterChannels.anyAccountWorking;
+	log(`  post-check: stillNeedsUpgrade=${stillNeedsUpgrade} (version=${afterVersionIncompatible}, feishuConfig=${afterChannels.feishuConfigInvalid}, channelsWorking=${afterChannels.anyAccountWorking})`);
+	if (stillNeedsUpgrade) return doRollback(`post-install diagnosis still shows anomaly: versionIncompatible=${afterVersionIncompatible}, feishuConfigInvalid=${afterChannels.feishuConfigInvalid}, anyAccountWorking=${afterChannels.anyAccountWorking}`);
+	log("  post-install diagnosis: ok (upgrade conditions resolved)");
+	log("");
+	log("── [6/6] doctor --fix ────────────────────────────────────");
+	const fixArgs = ["doctor", "--fix"];
+	if (opts.scene) fixArgs.push(`--scene=${opts.scene}`);
+	const t_doctorFixStart = Date.now();
+	const fixResult = (0, node_child_process.spawnSync)(process.execPath, [cliScript, ...fixArgs], {
+		cwd,
+		encoding: "utf-8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		timeout: 6e4,
+		env: process.env
+	});
+	timing.doctorFixMs = Date.now() - t_doctorFixStart;
+	if (fixResult.stdout?.trim()) log(`doctor(fix) stdout:\n${fixResult.stdout.trim()}`);
+	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(`${"=".repeat(60)}`);
+	log("upgrade-lark completed successfully");
+	log(`${"=".repeat(60)}`);
+	return {
+		ok: true,
+		stdout: npxStdout,
+		stderr: npxStderr,
+		exitCode: npxExitCode,
+		timing,
+		logFile
+	};
+}
 //#endregion
 //#region src/index.ts
 const args = node_process.default.argv.slice(2);
@@ -11402,6 +12049,53 @@ async function main() {
 			if (!result.ok) node_process.default.exit(1);
 			break;
 		}
+		case "upgrade-lark": {
+			const checkOnly = args.includes("--check-only");
+			const result = runUpgradeLark({
+				runId: rc.runId,
+				scene,
+				checkOnly
+			});
+			const upgradeDurationMs = Date.now() - t0;
+			console.log(JSON.stringify(result));
+			reportUpgradeLarkToSlardar({
+				scene,
+				durationMs: upgradeDurationMs,
+				success: result.ok,
+				logFile: result.logFile,
+				exitCode: result.exitCode,
+				rollbackOk: result.rollbackOk,
+				validationError: result.validationError,
+				error: result.error,
+				timing: result.timing
+			});
+			try {
+				await reportCliRun({
+					command: "upgrade-lark",
+					runId: rc.runId,
+					version: getVersion(),
+					invocation: args.join(" "),
+					durationMs: upgradeDurationMs,
+					caller: rc.caller,
+					traceId: rc.traceId,
+					success: result.ok,
+					result,
+					error: result.ok ? void 0 : { message: result.error ?? "upgrade-lark failed" }
+				});
+			} catch (e) {
+				console.error(`[telemetry] reportCliRun failed: ${e.message}`);
+			}
+			if (!result.ok || checkOnly && result.upgradeNeeded) {
+				node_process.default.exitCode = 1;
+				return;
+			}
+			break;
+		}
+		case "channels-probe": {
+			const result = runChannelsProbe(getFlag(args, "timeout") ? Number(getFlag(args, "timeout")) : void 0);
+			console.log(JSON.stringify(result));
+			break;
+		}
 		default:
 			node_process.default.stderr.write(`Unknown command: ${mode}\n\n`);
 			node_process.default.stderr.write(formatTopLevelHelp(helpFlags.expert));

package/package.json

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