@lark-apaas/openclaw-scripts-diagnose-cli 0.1.4-alpha.1 → 0.1.4-alpha.2

package/dist/index.cjs

@@ -23,12 +23,12 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 let node_process = require("node:process");
 node_process = __toESM(node_process);
+let node_path = require("node:path");
+node_path = __toESM(node_path);
 let json5 = require("json5");
 json5 = __toESM(json5);
 let node_fs = require("node:fs");
 node_fs = __toESM(node_fs);
-let node_path = require("node:path");
-node_path = __toESM(node_path);
 let node_child_process = require("node:child_process");
 let node_crypto = require("node:crypto");
 node_crypto = __toESM(node_crypto);
@@ -53,7 +53,7 @@ let json_diff = require("json-diff");
 * it terse and parseable.
 */
 function getVersion() {
-	return "0.1.4-alpha.1";
+	return "0.1.4-alpha.2";
 }
 //#endregion
 //#region src/rule-engine/base.ts
@@ -105,6 +105,9 @@ function topoSort(rules) {
 }
 //#endregion
 //#region src/utils.ts
+function getExtensionsDir(configPath) {
+	return node_path.default.join(node_path.default.dirname(configPath), "extensions");
+}
 /**
 * Canonical provider-ref for the feishu app secret. Both
 * `feishu_default_account` (multi-agent path) and `feishu_channel`
@@ -262,6 +265,32 @@ function shell(cmd, timeoutMs = 6e4) {
 	}).trim();
 }
 //#endregion
+//#region src/oc-runtime.ts
+/**
+* 探测 openclaw 运行时版本。能成功跑出版本号 = 已安装且可用。
+*
+* 比单纯 fs.existsSync 路径更可靠：能挡住 dangling symlink、依赖丢失、
+* bin 是错误版本等"看似装好但跑不起来"的状态。
+*
+* 失败（命令缺失 / 解析失败 / 超时）返回 null。
+*/
+function readOpenclawRuntimeVersion() {
+	try {
+		const lines = (0, node_child_process.execSync)("openclaw --version", {
+			encoding: "utf-8",
+			timeout: 5e3,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).split("\n").map((l) => l.trim()).filter(Boolean);
+		return (lines[lines.length - 1]?.match(/(?:OpenClaw\s+)?(\d+\.\d+\.\d+)/))?.[1] ?? null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
 //#region \0@oxc-project+runtime@0.115.0/helpers/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -270,6 +299,33 @@ function __decorate(decorators, target, key, desc) {
 	return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 //#endregion
+//#region src/rules/openclaw-runtime-missing.ts
+/**
+* doctor 入口最先执行：检查 openclaw 是否已安装且可用（执行 `openclaw --version`）。
+*
+* 触发条件：openclaw 不可用 AND openclaw.json 存在。
+* 配合 `config_file_missing`（reset）形成完整覆盖：
+*   - oc 可用 + config 存在 → 都 pass，进业务规则
+*   - oc 可用 + config 缺   → 仅 config_file_missing fail（reset）
+*   - oc 缺   + config 存在 → 仅本规则 fail（user_confirm: install_openclaw）
+*   - oc 缺   + config 缺   → 仅 config_file_missing fail（reset 同时装 oc + 初始化 config）
+*/
+let OpenclawRuntimeMissingRule = class OpenclawRuntimeMissingRule extends DiagnoseRule {
+	validate(ctx) {
+		if (readOpenclawRuntimeVersion() != null) return { pass: true };
+		if (!node_fs.default.existsSync(ctx.configPath)) return { pass: true };
+		return {
+			pass: false,
+			action: "install_openclaw",
+			message: `openclaw 不可用（无法执行 'openclaw --version'），但 ${ctx.configPath} 已存在；请重新安装 openclaw`
+		};
+	}
+};
+OpenclawRuntimeMissingRule = __decorate([Rule({
+	key: "openclaw_runtime_missing",
+	repairMode: "user-confirm"
+})], OpenclawRuntimeMissingRule);
+//#endregion
 //#region src/rules/multi-process-detect.ts
 let ProcessStatusRule = class ProcessStatusRule extends DiagnoseRule {
 	validate(_ctx) {
@@ -1312,9 +1368,6 @@ function getPluginMaps(config) {
 		allow: Array.isArray(rawAllow) ? rawAllow : void 0
 	};
 }
-function getExtensionsDir(configPath) {
-	return node_path.default.join(node_path.default.dirname(configPath), "extensions");
-}
 function hasNewMiaoda({ entries, installs, allow }) {
 	return asRecord(entries?.[NEW_MIAODA]) != null || asRecord(installs?.[NEW_MIAODA]) != null || (allow?.includes(NEW_MIAODA) ?? false);
 }
@@ -1404,6 +1457,588 @@ function getAllow(config) {
 	return allow.filter((e) => typeof e === "string");
 }
 //#endregion
+//#region src/fs-utils.ts
+/**
+* Rename src → dst, falling back to `mv` (which handles cross-device copy)
+* when the kernel returns EXDEV.
+*
+* Sandbox filesystems can put sibling paths on different "devices" from
+* rename(2)'s point of view: bind mounts, overlayfs copy-up, and
+* mount-point children inside a single directory all trip EXDEV. Seen in
+* production when reset's atomic swap did
+*   /home/gem/.npm-global/lib/node_modules/openclaw → openclaw.bak
+* and the openclaw subdir was a bind-mounted volume.
+*
+* Behavior:
+*   - Happy path hits rename(2) — atomic, single syscall, microseconds.
+*   - EXDEV path shells out to `mv`, which does rename() then copy+unlink
+*     on failure. Non-atomic but correct; callers already have rollback
+*     logic (install-openclaw restores from .bak) so loss of atomicity
+*     only matters if the process dies mid-copy, and that's survivable.
+*   - Any other error (ENOENT, EACCES, EBUSY...) rethrows as-is so callers
+*     see the real problem instead of a misleading `mv` fallback failure.
+*/
+function moveSafe(src, dst) {
+	try {
+		node_fs.default.renameSync(src, dst);
+	} catch (e) {
+		if (e?.code !== "EXDEV") throw e;
+		execCaptureErr(`mv ${shellQuote(src)} ${shellQuote(dst)}`);
+	}
+}
+/**
+* Run a shell command, re-throwing with stderr attached on failure.
+*
+* Node's `execSync(..., { stdio: 'ignore' })` swallows stderr entirely —
+* callers only see "Command failed: <cmd>" with no hint of the real error
+* (ENOSPC, EROFS, "unrecognized option", etc.). Production debugging on
+* sandboxed boxes is painful without the underlying message, so we pipe
+* stderr, capture it, and embed it in the thrown Error. stdout stays
+* suppressed because the commands we run here (tar/mv) are silent on
+* success.
+*/
+function execCaptureErr(cmd) {
+	try {
+		(0, node_child_process.execSync)(cmd, { stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		] });
+	} catch (e) {
+		const stderr = e?.stderr;
+		const stderrStr = (typeof stderr === "string" ? stderr : stderr?.toString("utf8") ?? "").trim();
+		const base = e?.message ?? "command failed";
+		throw new Error(stderrStr ? `${base}\nstderr: ${stderrStr}` : base);
+	}
+}
+/** 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) {
+	return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+* Recursively remove a path, retrying on transient overlayfs races.
+*
+* `fs.rmSync(..., { recursive: true, force: true })` walks the tree
+* issuing rmdir() per directory. On overlayfs (sandbox containers) a
+* just-emptied subdir can return EAGAIN/EBUSY/ENOTEMPTY for a short
+* window before whiteout propagation finishes — even though every
+* child has been unlinked. Same family of races as the tar/rename
+* issue handled by extractTarballTolerant + the install-openclaw
+* tmpfs swap.
+*
+* Retries with linear backoff (50 → 250 → 750 ms). Any non-transient
+* error (EACCES, EROFS, ENOSPC...) bubbles immediately. Returns true
+* if the path is absent at the end (success or never existed).
+*/
+function rmrfTolerant(target) {
+	if (!node_fs.default.existsSync(target)) return true;
+	const transient = new Set([
+		"EAGAIN",
+		"EBUSY",
+		"ENOTEMPTY"
+	]);
+	const delaysMs = [
+		50,
+		250,
+		750
+	];
+	for (let attempt = 0; attempt <= delaysMs.length; attempt++) try {
+		node_fs.default.rmSync(target, {
+			recursive: true,
+			force: true
+		});
+		return true;
+	} catch (e) {
+		const code = e.code ?? "";
+		if (!transient.has(code) || attempt === delaysMs.length) throw e;
+		(0, node_child_process.execSync)(`sleep ${delaysMs[attempt] / 1e3}`);
+	}
+	return !node_fs.default.existsSync(target);
+}
+/**
+* Snapshot the current `openclaw.json` to `<configPath>.<YYYYMMDD_HHMMSS>.bak`
+* before a repair / fix flow rewrites it. Local-time stamp matches the
+* shell-style backup convention (`cp openclaw.json openclaw.json.$(date
+* +%Y%m%d_%H%M%S).bak`) so operators triaging on the sandbox see the
+* familiar filename pattern.
+*
+* Returns the absolute backup path on success, or `null` when:
+*   - source doesn't exist (first-time setup; nothing to back up)
+*   - copy fails for any reason (disk full, permission denied, etc.)
+*
+* Failure is logged to cli.log via console.error and swallowed — the
+* caller's repair/fix work goes ahead either way. The backup is a safety
+* net, not a correctness gate; better to do the repair than refuse over
+* a missing rollback file.
+*/
+function backupConfigSync(configPath) {
+	if (!node_fs.default.existsSync(configPath)) {
+		console.error(`backupConfigSync: skip — source missing path=${configPath}`);
+		return null;
+	}
+	const d = /* @__PURE__ */ new Date();
+	const pad = (n) => String(n).padStart(2, "0");
+	const backupPath = `${configPath}.${`${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}_${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`}.bak`;
+	try {
+		node_fs.default.copyFileSync(configPath, backupPath);
+		const bytes = node_fs.default.statSync(backupPath).size;
+		console.error(`backupConfigSync: ok src=${configPath} dst=${backupPath} bytes=${bytes}`);
+		return backupPath;
+	} catch (e) {
+		console.error(`backupConfigSync: failed src=${configPath} message=${e.message}`);
+		return null;
+	}
+}
+/**
+* Extract an npm-packed gzipped tarball.
+*
+* ## The problem this works around
+*
+* Some tarballs (openclaw's among them — they're not packed by vanilla
+* `npm pack`) include relative symlinks inside nested .bin/ dirs whose
+* targets contain `..`, e.g.
+*   node_modules/<pkg>/node_modules/.bin/foo -> ../foo/bin/cli.js
+*
+* GNU tar classifies any symlink target with `..` or a leading `/` as
+* "dangerous" and defers its extraction to a post-files pass, while also
+* needing a post-files pass to restore directory permissions/mtimes. The
+* two passes race: the deferred-symlink handling mutates parent-dir inodes,
+* then the directory stat-restore pass does `fstatat()` and the recorded
+* inode doesn't match, firing
+*
+*   tar: <path>: Directory renamed before its status could be extracted
+*
+* from `apply_nonancestor_delayed_set_stat()` in extract.c. This is an
+* `ERROR` (hard-fail, exit 2) — the `--warning=no-rename-directory`
+* keyword controls a different, incremental-archive code path and does
+* NOT silence this. Reference: Paul Eggert, bug-tar 2004-04:
+* https://lists.gnu.org/archive/html/bug-tar/2004-04/msg00021.html
+*
+* ## The fix
+*
+* Pass `--absolute-names` (aka `-P`). Per GNU tar docs, this disables the
+* "normalize dangerous names" logic — including the deferred-symlink pass
+* that's racing us. Also stops stripping leading `/`, but our tarballs
+* only contain relative (`./node_modules/...`) paths so there's nothing
+* to strip. Safe because:
+*   - The tarball is sha512-verified upstream (downloadWithCache)
+*   - All entry paths are relative, no absolute-path escape risk
+*   - All dangerous symlink targets resolve within the extracted tree
+*
+* ## Belt-and-suspenders
+*
+* If some tar variant still emits the error despite -P, we fall through
+* to checking the stderr pattern: if every error line is the benign
+* "Directory renamed …" text (no real failures like ENOSPC/EACCES/gzip
+* CRC/etc.), swallow exit 2. Callers MUST still verify extraction
+* (e.g. `fs.existsSync(path.join(dest, 'package.json'))`) — tar's
+* `skip_this_one = 1` after the error means some dirs missed their
+* mtime/mode restore, but content was written.
+*/
+function extractTarballTolerant(tarball, destDir, opts = {}) {
+	const strip = opts.stripComponents ?? 0;
+	const stripFlag = strip > 0 ? ` --strip-components=${strip}` : "";
+	const cmd = `tar -xzf ${shellQuote(tarball)} -C ${shellQuote(destDir)}${stripFlag} -P`;
+	try {
+		execCaptureErr(cmd);
+		return;
+	} catch (e) {
+		const msg = e?.message ?? "";
+		const hasFalseAlarm = msg.includes("Directory renamed before its status could be extracted");
+		const hasFatal = [
+			/Cannot open/i,
+			/Cannot mkdir/i,
+			/Cannot create/i,
+			/No space left on device/i,
+			/Disk quota exceeded/i,
+			/Permission denied/i,
+			/Read-only file system/i,
+			/unrecognized option/i,
+			/gzip:/i,
+			/Unexpected EOF/i,
+			/Invalid argument/i
+		].some((r) => r.test(msg));
+		if (!hasFalseAlarm || hasFatal) throw e;
+		console.error(`[tar] -P did not suppress "Directory renamed" on ${tarball}; tolerating (content must be verified by caller)`);
+	}
+}
+//#endregion
+//#region src/rules/feishu-plugin-state-normalize.ts
+const PLUGIN_NAME$1 = "openclaw-lark";
+const BUILTIN_FEISHU = "feishu";
+const LEGACY_PLUGIN_NAME = "feishu-openclaw-plugin";
+const LEGACY_DIRS_TO_REMOVE = [LEGACY_PLUGIN_NAME, BUILTIN_FEISHU];
+const FEISHU_TOOLS = Object.freeze([
+	"feishu_bitable_app",
+	"feishu_bitable_app_table",
+	"feishu_bitable_app_table_field",
+	"feishu_bitable_app_table_record",
+	"feishu_bitable_app_table_view",
+	"feishu_calendar_calendar",
+	"feishu_calendar_event",
+	"feishu_calendar_event_attendee",
+	"feishu_calendar_freebusy",
+	"feishu_chat",
+	"feishu_chat_members",
+	"feishu_create_doc",
+	"feishu_doc_comments",
+	"feishu_doc_media",
+	"feishu_drive_file",
+	"feishu_fetch_doc",
+	"feishu_get_user",
+	"feishu_im_bot_image",
+	"feishu_im_user_fetch_resource",
+	"feishu_im_user_get_messages",
+	"feishu_im_user_get_thread_messages",
+	"feishu_im_user_message",
+	"feishu_im_user_search_messages",
+	"feishu_oauth",
+	"feishu_oauth_batch_auth",
+	"feishu_search_doc_wiki",
+	"feishu_search_user",
+	"feishu_sheet",
+	"feishu_task_comment",
+	"feishu_task_subtask",
+	"feishu_task_task",
+	"feishu_task_tasklist",
+	"feishu_update_doc",
+	"feishu_wiki_space",
+	"feishu_wiki_space_node"
+]);
+/**
+* 飞书插件状态规范化：fs 上 <extDir>/openclaw-lark/ 已落盘后统一收尾环境。
+* 各 fail 与 repair 一一对应，详见 fails.push(...) 字符串与 repair() 调用。
+*/
+let FeishuPluginStateNormalizeRule = class FeishuPluginStateNormalizeRule extends DiagnoseRule {
+	validate(ctx) {
+		if (!isPluginInstalled(ctx)) return { pass: true };
+		const fails = [];
+		if (!isNewPluginEnabled(ctx.config)) fails.push(`plugins.entries["${PLUGIN_NAME$1}"].enabled !== true（应启用）`);
+		if (isBuiltinFeishuEnabled(ctx.config)) fails.push("plugins.entries.feishu.enabled === true（应禁用）");
+		if (isTopLevelMissingFeishuTools(ctx.config)) fails.push("tools.alsoAllow 缺 feishu_* tools");
+		const legacyResiduals = findLegacyResiduals(ctx);
+		if (legacyResiduals.length > 0) fails.push(`legacy 飞书插件残留：${legacyResiduals.join(", ")}`);
+		if (fails.length === 0) return { pass: true };
+		return {
+			pass: false,
+			message: fails.join("；")
+		};
+	}
+	repair(ctx) {
+		setEntryEnabled(ctx.config, PLUGIN_NAME$1, true);
+		setEntryEnabled(ctx.config, BUILTIN_FEISHU, false);
+		ensureFeishuTools(ctx.config);
+		cleanupLegacyResiduals(ctx);
+	}
+};
+FeishuPluginStateNormalizeRule = __decorate([Rule({
+	key: "feishu_plugin_state_normalize",
+	dependsOn: ["config_syntax_check"],
+	repairMode: "standard"
+})], FeishuPluginStateNormalizeRule);
+function isPluginInstalled(ctx) {
+	return node_fs.default.existsSync(node_path.default.join(getExtensionsDir(ctx.configPath), PLUGIN_NAME$1));
+}
+function isNewPluginEnabled(config) {
+	return asRecord(getNestedMap(config, "plugins", "entries")?.[PLUGIN_NAME$1])?.enabled === true;
+}
+function isBuiltinFeishuEnabled(config) {
+	return asRecord(getNestedMap(config, "plugins", "entries")?.[BUILTIN_FEISHU])?.enabled === true;
+}
+/** 仅看顶层 tools.alsoAllow——agent 级 alsoAllow 是用户对单 agent 的精细化授权，doctor 不动。
+*  含 "*" 或任一 feishu_* 即视为已配。 */
+function isTopLevelMissingFeishuTools(config) {
+	return !hasFeishuTool(readAlsoAllow(config));
+}
+function readAlsoAllow(host) {
+	const tools = asRecord(host)?.tools;
+	const arr = asRecord(tools)?.alsoAllow;
+	if (!Array.isArray(arr)) return [];
+	return arr.filter((e) => typeof e === "string");
+}
+function hasFeishuTool(alsoAllow) {
+	if (alsoAllow.includes("*")) return true;
+	return alsoAllow.some((t) => FEISHU_TOOLS.includes(t));
+}
+function findLegacyResiduals(ctx) {
+	const found = [];
+	const plugins = asRecord(ctx.config.plugins);
+	if (asRecord(plugins?.entries)?.[LEGACY_PLUGIN_NAME] != null) found.push("entries[legacy]");
+	const allow = plugins?.allow;
+	if (Array.isArray(allow) && allow.includes(LEGACY_PLUGIN_NAME)) found.push("allow[legacy]");
+	if (asRecord(plugins?.installs)?.[LEGACY_PLUGIN_NAME] != null) found.push("installs[legacy]");
+	const extDir = getExtensionsDir(ctx.configPath);
+	for (const name of LEGACY_DIRS_TO_REMOVE) if (node_fs.default.existsSync(node_path.default.join(extDir, name))) found.push(`fs/${name}`);
+	return found;
+}
+function setEntryEnabled(config, key, enabled) {
+	const entries = ensureRecord(ensureRecord(config, "plugins"), "entries");
+	entries[key] = {
+		...asRecord(entries[key]) ?? {},
+		enabled
+	};
+}
+function ensureFeishuTools(config) {
+	const alsoAllow = readAlsoAllow(config);
+	if (hasFeishuTool(alsoAllow)) return;
+	ensureRecord(config, "tools").alsoAllow = [...new Set([...alsoAllow, ...FEISHU_TOOLS])];
+}
+function cleanupLegacyResiduals(ctx) {
+	const plugins = asRecord(ctx.config.plugins);
+	if (plugins) {
+		const entries = asRecord(plugins.entries);
+		if (entries && LEGACY_PLUGIN_NAME in entries) delete entries[LEGACY_PLUGIN_NAME];
+		const installs = asRecord(plugins.installs);
+		if (installs && LEGACY_PLUGIN_NAME in installs) delete installs[LEGACY_PLUGIN_NAME];
+		const allow = plugins.allow;
+		if (Array.isArray(allow)) {
+			for (let i = allow.length - 1; i >= 0; i--) if (allow[i] === LEGACY_PLUGIN_NAME) allow.splice(i, 1);
+			if (!allow.includes(PLUGIN_NAME$1)) allow.push(PLUGIN_NAME$1);
+		}
+	}
+	const extDir = getExtensionsDir(ctx.configPath);
+	for (const name of LEGACY_DIRS_TO_REMOVE) {
+		const target = node_path.default.join(extDir, name);
+		const rel = node_path.default.relative(extDir, target);
+		if (!rel || rel.startsWith("..") || node_path.default.isAbsolute(rel)) continue;
+		try {
+			rmrfTolerant(target);
+		} catch (e) {
+			console.error(`[feishu_plugin_state_normalize] rmrf ${target} failed: ${e.message}`);
+		}
+	}
+}
+function ensureRecord(obj, key) {
+	const cur = obj[key];
+	if (cur != null && typeof cur === "object" && !Array.isArray(cur)) return cur;
+	const fresh = {};
+	obj[key] = fresh;
+	return fresh;
+}
+//#endregion
+//#region src/version-compat.ts
+const VERSION_COMPAT_MAP = Object.freeze([
+	{
+		openclawLarkVersion: "2026.4.8",
+		minOpenclawVersion: "2026.3.28"
+	},
+	{
+		openclawLarkVersion: "2026.4.7",
+		minOpenclawVersion: "2026.3.28"
+	},
+	{
+		openclawLarkVersion: "2026.4.1",
+		minOpenclawVersion: "2026.3.28"
+	},
+	{
+		openclawLarkVersion: "2026.3.31",
+		minOpenclawVersion: "2026.3.28"
+	},
+	{
+		openclawLarkVersion: "2026.3.30",
+		minOpenclawVersion: "2026.3.28"
+	},
+	{
+		openclawLarkVersion: "2026.3.29",
+		minOpenclawVersion: "2026.3.28"
+	},
+	{
+		openclawLarkVersion: "2026.3.26",
+		minOpenclawVersion: "2026.3.22"
+	},
+	{
+		openclawLarkVersion: "2026.3.25",
+		minOpenclawVersion: "2026.3.22"
+	},
+	{
+		openclawLarkVersion: "2026.3.24",
+		minOpenclawVersion: "2026.3.22"
+	},
+	{
+		openclawLarkVersion: "2026.3.18",
+		minOpenclawVersion: "2026.2.26",
+		maxOpenclawVersion: "2026.3.13"
+	},
+	{
+		openclawLarkVersion: "2026.3.17",
+		minOpenclawVersion: "2026.2.26",
+		maxOpenclawVersion: "2026.3.13"
+	},
+	{
+		openclawLarkVersion: "2026.3.15",
+		minOpenclawVersion: "2026.2.26",
+		maxOpenclawVersion: "2026.3.13"
+	},
+	{
+		openclawLarkVersion: "2026.3.12",
+		minOpenclawVersion: "2026.2.26",
+		maxOpenclawVersion: "2026.3.13"
+	},
+	{
+		openclawLarkVersion: "2026.3.10",
+		minOpenclawVersion: "2026.2.26",
+		maxOpenclawVersion: "2026.3.13"
+	},
+	{
+		openclawLarkVersion: "2026.3.9",
+		minOpenclawVersion: "2026.2.26",
+		maxOpenclawVersion: "2026.3.13"
+	}
+]);
+/**
+* "YYYY.M.D" 按数值分量比较（宽松解析：缺失/非数字段视为 0，suffix 如 "-rc.1" 被忽略）。
+* 不能用字符串比较 —— '2026.3.18' < '2026.3.9' 字符串语义为 true。
+*/
+function compareCalVer(a, b) {
+	const pa = parseCalVer(a);
+	const pb = parseCalVer(b);
+	for (let i = 0; i < 3; i++) {
+		if (pa[i] < pb[i]) return -1;
+		if (pa[i] > pb[i]) return 1;
+	}
+	return 0;
+}
+function parseCalVer(v) {
+	const parts = v.split(".");
+	return [
+		toNum(parts[0]),
+		toNum(parts[1]),
+		toNum(parts[2])
+	];
+}
+function toNum(s) {
+	const n = s != null ? parseInt(s, 10) : 0;
+	return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+/** Whether the given openclaw version falls inside this plugin entry's compat range. */
+function compatible(entry, openclawVersion) {
+	if (compareCalVer(openclawVersion, entry.minOpenclawVersion) < 0) return false;
+	if (entry.maxOpenclawVersion != null && compareCalVer(openclawVersion, entry.maxOpenclawVersion) > 0) return false;
+	return true;
+}
+/** Look up an entry by exact plugin version; undefined if not in the table. */
+function findEntry(pluginVersion) {
+	return VERSION_COMPAT_MAP.find((e) => e.openclawLarkVersion === pluginVersion);
+}
+//#endregion
+//#region src/rules/feishu-plugin-version-compat.ts
+const PLUGIN_NAME = "openclaw-lark";
+const LEGACY_SHORT_NAMES = ["feishu-openclaw-plugin"];
+const FORK_SCOPES = ["@lark-apaas"];
+/**
+* 飞书插件 ↔ openclaw 版本兼容检测。
+*
+* 检测顺序（短路）：
+*   1. fork 魔改版（@lark-apaas scope）→ pass，不查版本
+*   2. legacy 老插件（feishu-openclaw-plugin 短名）→ 走升级流程
+*   3. 官方版（@larksuite scope 或其他）→ 按 VERSION_COMPAT_MAP 校验
+*
+* 决策方向：oc < 推荐 → upgrade_openclaw；oc ≥ 推荐 → upgrade_lark。
+*
+* `repairMode: user-confirm` —— 失败结果进 failedRules.userConfirm；CLI 不
+* 自动执行升级，由消费方弹用户确认后调对应升级接口。
+*/
+let FeishuPluginVersionCompatRule = class FeishuPluginVersionCompatRule extends DiagnoseRule {
+	validate(ctx) {
+		const recommendedOc = ctx.vars.recommendedOpenclawTag;
+		if (!recommendedOc) {
+			console.error("[feishu_plugin_version_compat] vars.recommendedOpenclawTag 未注入，跳过本规则");
+			return { pass: true };
+		}
+		const ocCur = readOpenclawRuntimeVersion();
+		if (!ocCur) return { pass: true };
+		const installed = detectInstalledPlugin(ctx);
+		if (installed == null) return { pass: true };
+		if (isForkPlugin(installed)) return { pass: true };
+		const isLegacy = isLegacyPlugin(installed);
+		if (!isLegacy && isVersionCompatible(installed, ocCur)) return { pass: true };
+		return decideUpgrade({
+			ocCur,
+			recommendedOc,
+			installed,
+			isLegacy
+		});
+	}
+};
+FeishuPluginVersionCompatRule = __decorate([Rule({
+	key: "feishu_plugin_version_compat",
+	dependsOn: ["config_syntax_check"],
+	repairMode: "user-confirm",
+	usesVars: ["recommendedOpenclawTag"]
+})], FeishuPluginVersionCompatRule);
+function isForkPlugin(p) {
+	return p.scope != null && FORK_SCOPES.includes(p.scope);
+}
+function isLegacyPlugin(p) {
+	return LEGACY_SHORT_NAMES.includes(p.allowName);
+}
+/** 装了但版本读不到、版本不在表里、或不在 entry 区间内，都视为不兼容。 */
+function isVersionCompatible(p, ocCur) {
+	if (!p.version) return false;
+	const entry = findEntry(p.version);
+	return entry != null && compatible(entry, ocCur);
+}
+function decideUpgrade(args) {
+	const { ocCur, recommendedOc, installed, isLegacy } = args;
+	const desc = describePlugin(installed);
+	const prefix = isLegacy ? `检测到老飞书插件 (${desc})` : `飞书插件 ${desc} 与 openclaw@${ocCur} 不兼容`;
+	if (compareCalVer(ocCur, recommendedOc) < 0) return {
+		pass: false,
+		action: "upgrade_openclaw",
+		message: `${prefix}；将 openclaw 升级到 ${recommendedOc}，飞书插件会随之同步升级`
+	};
+	return {
+		pass: false,
+		action: "upgrade_lark",
+		message: `${prefix}；当前 openclaw@${ocCur} 已达推荐版本，可直接升级飞书插件`
+	};
+}
+function describePlugin(p) {
+	return (p.fullName ?? p.allowName) + (p.version ? `@${p.version}` : "");
+}
+function readPluginPackageJson(filePath) {
+	try {
+		if (!node_fs.default.existsSync(filePath)) return null;
+		const raw = node_fs.default.readFileSync(filePath, "utf-8");
+		const parsed = JSON.parse(raw);
+		return {
+			name: typeof parsed.name === "string" ? parsed.name : void 0,
+			version: typeof parsed.version === "string" ? parsed.version : void 0
+		};
+	} catch {
+		return null;
+	}
+}
+/** "已装" = plugins.allow 含名 AND extensions/<name>/package.json 真实存在。 */
+function detectInstalledPlugin(ctx) {
+	const allowRaw = asRecord(ctx.config.plugins)?.allow;
+	const allow = Array.isArray(allowRaw) ? allowRaw.filter((e) => typeof e === "string") : [];
+	const extDir = getExtensionsDir(ctx.configPath);
+	const installs = getNestedMap(ctx.config, "plugins", "installs");
+	for (const name of [PLUGIN_NAME, ...LEGACY_SHORT_NAMES]) {
+		if (!allow.includes(name)) continue;
+		const pkgPath = node_path.default.join(extDir, name, "package.json");
+		if (!node_fs.default.existsSync(pkgPath)) continue;
+		const pkg = readPluginPackageJson(pkgPath) ?? {};
+		const installEntry = installs && asRecord(installs[name]);
+		const fullName = pkg.name ?? extractScopedNameFromSpec(installEntry?.spec);
+		return {
+			allowName: name,
+			fullName,
+			scope: fullName?.startsWith("@") ? fullName.split("/")[0] : void 0,
+			version: pkg.version ?? (typeof installEntry?.version === "string" ? installEntry.version : void 0)
+		};
+	}
+	return null;
+}
+/** "@scope/name@1.2.3" / "name@1.2.3" / "@scope/name" / "name" → 去掉 @version 后缀 */
+function extractScopedNameFromSpec(spec) {
+	if (typeof spec !== "string") return void 0;
+	const at = spec.indexOf("@", 1);
+	return at === -1 ? spec : spec.slice(0, at);
+}
+//#endregion
 //#region src/check.ts
 /** Telemetry-aware entry: returns both the legacy CheckResult (for stdout)
 *  AND a DoctorReport-shape payload (for `openclaw.report_cli_run`). The
@@ -1416,7 +2051,8 @@ function runCheckImpl(input) {
 	const result = { failedRules: {
 		standard: [],
 		ai: [],
-		reset: []
+		reset: [],
+		userConfirm: []
 	} };
 	const outcomes = [];
 	const disabledSet = new Set(input.disabledRules || []);
@@ -1516,10 +2152,11 @@ function runCheckImpl(input) {
 			outcomes.push({
 				rule: meta.key,
 				status: "failed",
-				message: r.message
+				message: r.message,
+				action: r.action
 			});
 			failedKeys.add(meta.key);
-			pushFailedRule(result, meta.repairMode, meta.key, r.message || "");
+			pushFailedRule(result, meta.repairMode, meta.key, r.message || "", r.action);
 		}
 	}
 	console.error(`runCheck: end totalMs=${Date.now() - tStart} failed={standard:${result.failedRules.standard.length},ai:${result.failedRules.ai.length},reset:${result.failedRules.reset.length}}`);
@@ -1528,7 +2165,7 @@ function runCheckImpl(input) {
 		report: finalize$2(outcomes, aborted)
 	};
 }
-function pushFailedRule(result, repairMode, key, detail) {
+function pushFailedRule(result, repairMode, key, detail, action) {
 	switch (repairMode) {
 		case "standard":
 			result.failedRules.standard.push(key);
@@ -1545,6 +2182,13 @@ function pushFailedRule(result, repairMode, key, detail) {
 				detail
 			});
 			break;
+		case "user-confirm":
+			result.failedRules.userConfirm.push({
+				rule_name: key,
+				detail,
+				action
+			});
+			break;
 	}
 }
 function finalize$2(results, aborted) {
@@ -1587,173 +2231,6 @@ function finalize$2(results, aborted) {
 	};
 }
 //#endregion
-//#region src/fs-utils.ts
-/**
-* Rename src → dst, falling back to `mv` (which handles cross-device copy)
-* when the kernel returns EXDEV.
-*
-* Sandbox filesystems can put sibling paths on different "devices" from
-* rename(2)'s point of view: bind mounts, overlayfs copy-up, and
-* mount-point children inside a single directory all trip EXDEV. Seen in
-* production when reset's atomic swap did
-*   /home/gem/.npm-global/lib/node_modules/openclaw → openclaw.bak
-* and the openclaw subdir was a bind-mounted volume.
-*
-* Behavior:
-*   - Happy path hits rename(2) — atomic, single syscall, microseconds.
-*   - EXDEV path shells out to `mv`, which does rename() then copy+unlink
-*     on failure. Non-atomic but correct; callers already have rollback
-*     logic (install-openclaw restores from .bak) so loss of atomicity
-*     only matters if the process dies mid-copy, and that's survivable.
-*   - Any other error (ENOENT, EACCES, EBUSY...) rethrows as-is so callers
-*     see the real problem instead of a misleading `mv` fallback failure.
-*/
-function moveSafe(src, dst) {
-	try {
-		node_fs.default.renameSync(src, dst);
-	} catch (e) {
-		if (e?.code !== "EXDEV") throw e;
-		execCaptureErr(`mv ${shellQuote(src)} ${shellQuote(dst)}`);
-	}
-}
-/**
-* Run a shell command, re-throwing with stderr attached on failure.
-*
-* Node's `execSync(..., { stdio: 'ignore' })` swallows stderr entirely —
-* callers only see "Command failed: <cmd>" with no hint of the real error
-* (ENOSPC, EROFS, "unrecognized option", etc.). Production debugging on
-* sandboxed boxes is painful without the underlying message, so we pipe
-* stderr, capture it, and embed it in the thrown Error. stdout stays
-* suppressed because the commands we run here (tar/mv) are silent on
-* success.
-*/
-function execCaptureErr(cmd) {
-	try {
-		(0, node_child_process.execSync)(cmd, { stdio: [
-			"ignore",
-			"ignore",
-			"pipe"
-		] });
-	} catch (e) {
-		const stderr = e?.stderr;
-		const stderrStr = (typeof stderr === "string" ? stderr : stderr?.toString("utf8") ?? "").trim();
-		const base = e?.message ?? "command failed";
-		throw new Error(stderrStr ? `${base}\nstderr: ${stderrStr}` : base);
-	}
-}
-/** 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) {
-	return `'${s.replace(/'/g, `'\\''`)}'`;
-}
-/**
-* Snapshot the current `openclaw.json` to `<configPath>.<YYYYMMDD_HHMMSS>.bak`
-* before a repair / fix flow rewrites it. Local-time stamp matches the
-* shell-style backup convention (`cp openclaw.json openclaw.json.$(date
-* +%Y%m%d_%H%M%S).bak`) so operators triaging on the sandbox see the
-* familiar filename pattern.
-*
-* Returns the absolute backup path on success, or `null` when:
-*   - source doesn't exist (first-time setup; nothing to back up)
-*   - copy fails for any reason (disk full, permission denied, etc.)
-*
-* Failure is logged to cli.log via console.error and swallowed — the
-* caller's repair/fix work goes ahead either way. The backup is a safety
-* net, not a correctness gate; better to do the repair than refuse over
-* a missing rollback file.
-*/
-function backupConfigSync(configPath) {
-	if (!node_fs.default.existsSync(configPath)) {
-		console.error(`backupConfigSync: skip — source missing path=${configPath}`);
-		return null;
-	}
-	const d = /* @__PURE__ */ new Date();
-	const pad = (n) => String(n).padStart(2, "0");
-	const backupPath = `${configPath}.${`${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}_${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`}.bak`;
-	try {
-		node_fs.default.copyFileSync(configPath, backupPath);
-		const bytes = node_fs.default.statSync(backupPath).size;
-		console.error(`backupConfigSync: ok src=${configPath} dst=${backupPath} bytes=${bytes}`);
-		return backupPath;
-	} catch (e) {
-		console.error(`backupConfigSync: failed src=${configPath} message=${e.message}`);
-		return null;
-	}
-}
-/**
-* Extract an npm-packed gzipped tarball.
-*
-* ## The problem this works around
-*
-* Some tarballs (openclaw's among them — they're not packed by vanilla
-* `npm pack`) include relative symlinks inside nested .bin/ dirs whose
-* targets contain `..`, e.g.
-*   node_modules/<pkg>/node_modules/.bin/foo -> ../foo/bin/cli.js
-*
-* GNU tar classifies any symlink target with `..` or a leading `/` as
-* "dangerous" and defers its extraction to a post-files pass, while also
-* needing a post-files pass to restore directory permissions/mtimes. The
-* two passes race: the deferred-symlink handling mutates parent-dir inodes,
-* then the directory stat-restore pass does `fstatat()` and the recorded
-* inode doesn't match, firing
-*
-*   tar: <path>: Directory renamed before its status could be extracted
-*
-* from `apply_nonancestor_delayed_set_stat()` in extract.c. This is an
-* `ERROR` (hard-fail, exit 2) — the `--warning=no-rename-directory`
-* keyword controls a different, incremental-archive code path and does
-* NOT silence this. Reference: Paul Eggert, bug-tar 2004-04:
-* https://lists.gnu.org/archive/html/bug-tar/2004-04/msg00021.html
-*
-* ## The fix
-*
-* Pass `--absolute-names` (aka `-P`). Per GNU tar docs, this disables the
-* "normalize dangerous names" logic — including the deferred-symlink pass
-* that's racing us. Also stops stripping leading `/`, but our tarballs
-* only contain relative (`./node_modules/...`) paths so there's nothing
-* to strip. Safe because:
-*   - The tarball is sha512-verified upstream (downloadWithCache)
-*   - All entry paths are relative, no absolute-path escape risk
-*   - All dangerous symlink targets resolve within the extracted tree
-*
-* ## Belt-and-suspenders
-*
-* If some tar variant still emits the error despite -P, we fall through
-* to checking the stderr pattern: if every error line is the benign
-* "Directory renamed …" text (no real failures like ENOSPC/EACCES/gzip
-* CRC/etc.), swallow exit 2. Callers MUST still verify extraction
-* (e.g. `fs.existsSync(path.join(dest, 'package.json'))`) — tar's
-* `skip_this_one = 1` after the error means some dirs missed their
-* mtime/mode restore, but content was written.
-*/
-function extractTarballTolerant(tarball, destDir, opts = {}) {
-	const strip = opts.stripComponents ?? 0;
-	const stripFlag = strip > 0 ? ` --strip-components=${strip}` : "";
-	const cmd = `tar -xzf ${shellQuote(tarball)} -C ${shellQuote(destDir)}${stripFlag} -P`;
-	try {
-		execCaptureErr(cmd);
-		return;
-	} catch (e) {
-		const msg = e?.message ?? "";
-		const hasFalseAlarm = msg.includes("Directory renamed before its status could be extracted");
-		const hasFatal = [
-			/Cannot open/i,
-			/Cannot mkdir/i,
-			/Cannot create/i,
-			/No space left on device/i,
-			/Disk quota exceeded/i,
-			/Permission denied/i,
-			/Read-only file system/i,
-			/unrecognized option/i,
-			/gzip:/i,
-			/Unexpected EOF/i,
-			/Invalid argument/i
-		].some((r) => r.test(msg));
-		if (!hasFalseAlarm || hasFatal) throw e;
-		console.error(`[tar] -P did not suppress "Directory renamed" on ${tarball}; tolerating (content must be verified by caller)`);
-	}
-}
-//#endregion
 //#region src/repair.ts
 /** Telemetry-aware entry. Same per-rule pass + side effects, but also
 *  builds a `DoctorReport`-shape payload from per-rule revalidate
@@ -2210,22 +2687,88 @@ function startAsyncReset(ctxBase64) {
 }
 //#endregion
 //#region src/oss/fetchWithDiag.ts
+/** Methods retried automatically on transient transport errors. POST and
+*  PATCH are deliberately excluded: a transient ECONNRESET / ETIMEDOUT
+*  after the request body has been written might mean the server
+*  received and processed it (just couldn't reply) — auto-retrying
+*  would cause duplicate side effects. AWS / GCP / Aliyun SDKs all use
+*  the same allowlist. */
+const IDEMPOTENT_METHODS = new Set([
+	"GET",
+	"HEAD",
+	"OPTIONS",
+	"DELETE",
+	"PUT"
+]);
+/** Errno codes treated as transient — almost always a stale connection
+*  or momentary network blip that succeeds on retry. The list mirrors
+*  what AWS / GCP / Aliyun SDKs retry by default. Only used for fetch
+*  rejection cause; HTTP 4xx/5xx responses pass through unchanged
+*  (caller decides whether the application-level status is retryable). */
+const TRANSIENT_CODES = new Set([
+	"ECONNRESET",
+	"ETIMEDOUT",
+	"EPIPE",
+	"ECONNREFUSED",
+	"EHOSTUNREACH",
+	"ENETUNREACH",
+	"EAI_AGAIN"
+]);
 async function fetchWithDiag(url, opts = {}) {
+	const maxRetries = opts.maxRetries ?? 2;
+	const method = (opts.init?.method ?? "GET").toUpperCase();
+	const retrySafe = opts.retryNonIdempotent || IDEMPOTENT_METHODS.has(method);
+	let lastErr;
+	for (let attempt = 0; attempt <= maxRetries; attempt++) try {
+		return await fetchOnce(url, opts);
+	} catch (e) {
+		lastErr = e;
+		const code = extractCauseCode(e);
+		if (!(code !== void 0 && TRANSIENT_CODES.has(code)) || attempt === maxRetries) throw e;
+		if (!retrySafe) {
+			console.error(`fetch ${opts.label ?? originOf(url)}: transient ${code} but method=${method} is non-idempotent, NOT retrying`);
+			throw e;
+		}
+		const delay = 200 * Math.pow(2, attempt) + Math.floor(Math.random() * 100);
+		console.error(`fetch ${opts.label ?? originOf(url)}: transient ${code}, retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries})`);
+		await new Promise((r) => setTimeout(r, delay));
+	}
+	throw lastErr;
+}
+/** One fetch attempt with timeout. Throws on transport / abort failures
+*  (caught by the retry loop above) and on its own enriched message form. */
+async function fetchOnce(url, opts) {
 	const label = opts.label ?? originOf(url);
 	const timeoutMs = opts.timeoutMs ?? 3e4;
 	const start = Date.now();
 	const ac = new AbortController();
 	const timer = timeoutMs > 0 && Number.isFinite(timeoutMs) ? setTimeout(() => ac.abort(), timeoutMs) : void 0;
 	try {
-		return await fetch(url, { signal: ac.signal });
+		return await fetch(url, {
+			...opts.init,
+			signal: ac.signal
+		});
 	} catch (e) {
 		const durationMs = Date.now() - start;
 		const causeStr = e.name === "AbortError" || ac.signal.aborted && timeoutMs > 0 ? `request aborted after ${timeoutMs}ms (timeout)` : describeCause(e.cause) || e.message;
-		throw new Error(`fetch ${label} failed: ${causeStr} (url=${redactUrl(url)} durationMs=${durationMs})`);
+		const enriched = /* @__PURE__ */ new Error(`fetch ${label} failed: ${causeStr} (url=${redactUrl(url)} durationMs=${durationMs})`);
+		enriched.cause = e.cause ?? e;
+		throw enriched;
 	} finally {
 		if (timer) clearTimeout(timer);
 	}
 }
+/** Pull the errno-style code from the deepest cause we can reach. Used by
+*  retry-classification only — error messages still get the human-readable
+*  describeCause() rendering. */
+function extractCauseCode(e) {
+	let cur = e.cause ?? e;
+	for (let depth = 0; depth < 5 && cur; depth++) {
+		const code = cur.code;
+		if (typeof code === "string") return code;
+		cur = cur.cause;
+	}
+}
 /** Walk the Error.cause chain and produce a single-line summary like
 *  `ENOTFOUND getaddrinfo ENOTFOUND oss.example.com`. */
 function describeCause(c, depth = 0) {
@@ -3504,7 +4047,8 @@ async function runDoctor(rawCtx, opts) {
 			results.push({
 				rule: key,
 				status: "failed",
-				message: v1.message
+				message: v1.message,
+				action: v1.action
 			});
 			failedKeys.add(key);
 			continue;
@@ -3514,7 +4058,8 @@ async function runDoctor(rawCtx, opts) {
 			results.push({
 				rule: key,
 				status: "failed",
-				message: v1.message
+				message: v1.message,
+				action: v1.action
 			});
 			failedKeys.add(key);
 			continue;
@@ -3731,7 +4276,7 @@ async function reportCliRun(opts) {
 //#region src/help.ts
 const BIN = "mclaw-diagnose";
 function versionBanner() {
-	return `v0.1.4-alpha.1`;
+	return `v0.1.4-alpha.2`;
 }
 const COMMANDS = [
 	{

package/package.json

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