@lark-apaas/openclaw-scripts-diagnose-cli 0.1.21-alpha.2 → 0.1.21-beta.0

package/dist/index.cjs

@@ -52,7 +52,7 @@ node_assert = __toESM(node_assert);
 * it terse and parseable.
 */
 function getVersion() {
-	return "0.1.21-alpha.2";
+	return "0.1.21-beta.0";
 }
 //#endregion
 //#region src/rule-engine/base.ts
@@ -2639,11 +2639,9 @@ const LARK_PLUGIN_NAME = "openclaw-lark";
 * 版本号自成体系、不在 VERSION_COMPAT_MAP 内，按对标的官方版本判定兼容性。
 */
 const FORK_LARK_PLUGIN_FULL_NAME = "@lark-apaas/openclaw-lark";
-/** OpenClaw 从该版本起使用内置飞书插件作为目标态，不再安装外置 openclaw-lark。 */
-const BUILTIN_FEISHU_MIN_OPENCLAW_VERSION = "2026.6.6";
 /**
-* openclaw **内置** 的 `feishu` 插件（非独立扩展）。
-* OpenClaw 2026.6.6 及之后以该内置能力作为目标态；更早版本仍使用外置 openclaw-lark。
+* 社区插件：openclaw **内置** 的 `feishu` 插件（非独立扩展）。
+* 与官方/ fork openclaw-lark 互斥，规范化时应禁用以让位 openclaw-lark。
 */
 const BUILTIN_FEISHU_PLUGIN_NAME = "feishu";
 /**
@@ -2823,282 +2821,9 @@ function getAllow$1(config) {
 	return allow.filter((e) => typeof e === "string");
 }
 //#endregion
-//#region src/version-compat.ts
-const VERSION_COMPAT_MAP = Object.freeze([
-	{
-		openclawLarkVersion: "2026.5.20",
-		minOpenclawVersion: "2026.5.7"
-	},
-	{
-		openclawLarkVersion: "2026.5.13",
-		minOpenclawVersion: "2026.5.7"
-	},
-	{
-		openclawLarkVersion: "2026.5.12",
-		minOpenclawVersion: "2026.5.7"
-	},
-	{
-		openclawLarkVersion: "2026.5.7",
-		minOpenclawVersion: "2026.5.6"
-	},
-	{
-		openclawLarkVersion: "2026.4.10",
-		minOpenclawVersion: "2026.4.27"
-	},
-	{
-		openclawLarkVersion: "2026.4.9",
-		minOpenclawVersion: "2026.3.28"
-	},
-	{
-		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"
-	}
-]);
-/**
-* Coerce a CalVer string ("YYYY.M.D[suffix]") to a clean semver string.
-* semver.coerce strips non-numeric suffixes (e.g. "-rc.1") and fills in
-* missing components with 0. Returns "0.0.0" for unparseable input.
-*/
-function coerceCalVer(v) {
-	return semver.default.coerce(v)?.version ?? "0.0.0";
-}
-/**
-* Compare two CalVer strings ("YYYY.M.D") numerically.
-* Delegates to semver for correct numeric component ordering —
-* plain string comparison would give wrong results (e.g. '2026.3.18' < '2026.3.9').
-* Suffixes like "-rc.1" are stripped via coercion before comparison.
-*/
-function compareCalVer(a, b) {
-	return semver.default.compare(coerceCalVer(a), coerceCalVer(b));
-}
-/** Whether this OpenClaw version should use the built-in feishu plugin target state. */
-function supportsBuiltinFeishu(openclawVersion) {
-	if (!openclawVersion) return false;
-	return semver.default.gte(coerceCalVer(openclawVersion), coerceCalVer(BUILTIN_FEISHU_MIN_OPENCLAW_VERSION));
-}
-/**
-* 该条目的有效上界——开区间（EXCLUSIVE）：openclaw ≥ 此值即不兼容。
-* undefined = 最高档，无上界。
-*
-* 上界一律为开区间，两种来源：
-*   - 有显式 maxOpenclawVersion → 直接用它（它本身就是「首个不兼容的 openclaw 版本」）。
-*   - 无显式 max → 向更高插件版本（表降序，index 更小）扫描，取首个「严格更高 min」的
-*     minOpenclawVersion，即下一不兼容区间的起点。
-*
-* 只接受严格更高的 min（跳过相同 min 的同档；跳过更低 min 防止非单调表产生空区间
-* [min, max) 把本条目永久判为不兼容）。
-*/
-function inferEffectiveMax(index) {
-	const cur = VERSION_COMPAT_MAP[index];
-	if (cur.maxOpenclawVersion != null) return cur.maxOpenclawVersion;
-	for (let i = index - 1; i >= 0; i--) if (compareCalVer(VERSION_COMPAT_MAP[i].minOpenclawVersion, cur.minOpenclawVersion) > 0) return VERSION_COMPAT_MAP[i].minOpenclawVersion;
-}
-/**
-* 单一真相源：floor 匹配 + 有效上界，得到某插件版本的半开兼容区间 [min, max)（含命中条目）。
-* evaluateVersionRange / findClosestEntry / effectiveCompatRange 全部基于它，
-* 避免 floor 匹配与 inferEffectiveMax 在多处重复。max 一律为开区间上界（EXCLUSIVE）；
-* 最高档 max 为 undefined（无上界）。undefined = 版本比全表都旧（无 floor 条目）。
-*/
-function resolveRange(pluginVersion) {
-	const index = VERSION_COMPAT_MAP.findIndex((e) => compareCalVer(e.openclawLarkVersion, pluginVersion) <= 0);
-	if (index === -1) return void 0;
-	const entry = VERSION_COMPAT_MAP[index];
-	return {
-		entry,
-		min: entry.minOpenclawVersion,
-		max: inferEffectiveMax(index)
-	};
-}
-/**
-* 对一个**已对标到 VERSION_COMPAT_MAP 键**的版本评估其与 openclaw 的兼容性，
-* 并在不兼容时给出方向。fork 的 pin、legacy 分类等在 `checkPluginCompat` 处理，
-* 本函数只负责「版本 × openclaw 区间」这一段唯一逻辑。
-*
-* - index === -1（插件版本比全表都旧，无 floor 条目）→ 无区间可判，视为插件过旧 → 'lark'
-* - oc < entry.minOpenclawVersion → 'openclaw'
-* - oc ≥ 有效上界（开区间）→ 'lark'
-* - 否则兼容
-*
-* 区间统一为半开 [min, max)：min 闭、max 开（显式与推断上界一律 EXCLUSIVE）。
-*/
-function evaluateVersionRange(pluginVersion, openclawVersion) {
-	const r = resolveRange(pluginVersion);
-	if (!r) return {
-		compatible: false,
-		direction: "lark",
-		entry: void 0
-	};
-	const oc = coerceCalVer(openclawVersion);
-	if (semver.default.lt(oc, coerceCalVer(r.min))) return {
-		compatible: false,
-		direction: "openclaw",
-		entry: r.entry
-	};
-	if (r.max !== void 0 && semver.default.gte(oc, coerceCalVer(r.max))) return {
-		compatible: false,
-		direction: "lark",
-		entry: r.entry
-	};
-	return {
-		compatible: true,
-		direction: null,
-		entry: r.entry
-	};
-}
-/**
-* Fork plugin handling.
-*
-* `@lark-apaas/openclaw-lark` is an internal fork whose own version numbers
-* (e.g. 2026.4.3, 2026.4.4) are NOT keys in VERSION_COMPAT_MAP. Floor-matching
-* a fork version against the official-keyed map only works by coincidence of
-* numbering and breaks once the fork version drifts past an official entry.
-* Both the install-time compat check and the diagnose rule must therefore pin
-* the fork to its official-equivalent version before consulting the map.
-*/
-/** fork 对标的官方 openclaw-lark 版本（与 VERSION_COMPAT_MAP 强耦合，故留在此处）。 */
-const FORK_LARK_PLUGIN_PINNED_VERSION = "2026.4.1";
-/**
-* 返回某插件版本（floor 匹配后）的有效兼容区间 [min, max)，含 evaluateVersionRange 所用的
-* （显式或推断的）开区间上界——区别于仅暴露显式 maxOpenclawVersion 的 findClosestEntry。
-* undefined = 版本比全表都旧（无 floor 条目）。
-*/
-function effectiveCompatRange(pluginVersion) {
-	const r = resolveRange(pluginVersion);
-	return r ? {
-		min: r.min,
-		max: r.max
-	} : void 0;
-}
-/** "@scope/name" → "name"；无 scope 原样返回。 */
-function extractBaseName(name) {
-	if (!name) return void 0;
-	return name.startsWith("@") ? name.split("/")[1] : name;
-}
-function reasonFromRange(r) {
-	if (r.compatible) return "compatible";
-	if (r.direction === "openclaw") return "oc-below-min";
-	return r.entry ? "oc-above-max" : "version-not-in-map";
-}
-/**
-* 统一的飞书插件兼容判定入口——唯一的判定真相源。
-*
-* 入参只有三个：插件包名、插件版本、当前 openclaw 版本（**不涉及 recommendedOpenclawTag**，
-* 推荐版本的处理交由各业务点）。判定算法：
-*
-*   1. fork `@lark-apaas/openclaw-lark`：先 pin 到对标官方版本（FORK_LARK_PLUGIN_PINNED_VERSION）
-*      再按区间判定上下界。
-*   2. 其他 `@lark-apaas/*` fork：无条件豁免（兼容）。
-*   3. legacy `feishu-openclaw-plugin`（含带 scope 形式）：一律不兼容，方向 = 换飞书插件。
-*   4. 官方版及其余包：用自身版本按 VERSION_COMPAT_MAP 区间判定；读不到版本号 → 不兼容（换插件）。
-*
-* 所有消费方（install-extension 预检、feishu_plugin_version_compat 两条规则、needsLarkUpgrade）
-* 都应消费本方法，不再各自实现兼容/方向逻辑，避免口径漂移。
-*/
-function checkPluginCompat(packageName, pluginVersion, openclawVersion) {
-	if (packageName === "@lark-apaas/openclaw-lark") {
-		const resolvedVersion = FORK_LARK_PLUGIN_PINNED_VERSION;
-		const r = evaluateVersionRange(resolvedVersion, openclawVersion);
-		return {
-			...r,
-			reason: reasonFromRange(r),
-			resolvedVersion
-		};
-	}
-	if ((packageName && packageName.startsWith("@") ? packageName.split("/")[0] : void 0) === "@lark-apaas") return {
-		compatible: true,
-		direction: null,
-		reason: "fork-exempt",
-		resolvedVersion: pluginVersion,
-		entry: void 0
-	};
-	if (extractBaseName(packageName) === "feishu-openclaw-plugin") return {
-		compatible: false,
-		direction: "lark",
-		reason: "legacy",
-		resolvedVersion: pluginVersion,
-		entry: void 0
-	};
-	if (!pluginVersion) return {
-		compatible: false,
-		direction: "lark",
-		reason: "version-unknown",
-		resolvedVersion: void 0,
-		entry: void 0
-	};
-	const r = evaluateVersionRange(pluginVersion, openclawVersion);
-	return {
-		...r,
-		reason: reasonFromRange(r),
-		resolvedVersion: pluginVersion
-	};
-}
-//#endregion
 //#region src/rules/lark-plugin-allow.ts
 let LarkPluginAllowRule = class LarkPluginAllowRule extends DiagnoseRule {
 	validate(ctx) {
-		if (supportsBuiltinFeishu(readOpenclawRuntimeVersion())) return { pass: true };
 		const allow = getAllow(ctx.config);
 		if (LARK_PLUGIN_DIR_NAMES.some((name) => allow.includes(name))) return { pass: true };
 		const installed = detectInstalledLarkPlugin$1(getExtensionsDir(ctx.configPath));
@@ -3226,8 +2951,7 @@ OldMiaodaPluginsCleanupRule = __decorate([Rule({
 //#region src/rules/builtin-plugin-missing.ts
 function findMissingBuiltinPlugins(ctx) {
 	const extDir = getExtensionsDir(ctx.configPath);
-	const supportsBuiltin = supportsBuiltinFeishu(readOpenclawRuntimeVersion());
-	return [...OFFICIAL_EXTENSION_PLUGIN_NAMES].filter((name) => !(supportsBuiltin && name === "openclaw-lark")).filter((name) => !isPluginInstalledOnDisk(extDir, name)).sort();
+	return [...OFFICIAL_EXTENSION_PLUGIN_NAMES].filter((name) => !isPluginInstalledOnDisk(extDir, name)).sort();
 }
 let BuiltinPluginMissingRule = class BuiltinPluginMissingRule extends DiagnoseRule {
 	validate(ctx) {
@@ -3242,7 +2966,7 @@ let BuiltinPluginMissingRule = class BuiltinPluginMissingRule extends DiagnoseRu
 };
 BuiltinPluginMissingRule = __decorate([Rule({
 	key: "builtin_plugin_missing",
-	description: "检查当前 OpenClaw 版本需要的内置扩展插件是否已在磁盘安装；缺失时提示重新安装（实验性）",
+	description: "检查所有内置扩展插件（openclaw-lark、openclaw-extension-miaoda 等）是否已在磁盘安装；缺失时提示重新安装（实验性）",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "check-only",
 	level: "critical",
@@ -3550,14 +3274,6 @@ const FEISHU_TOOLS = Object.freeze([
 */
 let FeishuPluginStateNormalizeRule = class FeishuPluginStateNormalizeRule extends DiagnoseRule {
 	validate(ctx) {
-		if (isBuiltinFeishuTarget()) {
-			const residuals = findExternalLarkResiduals(ctx);
-			if (residuals.length === 0) return { pass: true };
-			return {
-				pass: false,
-				message: `外置飞书插件残留：${residuals.join(", ")}`
-			};
-		}
 		if (!isPluginInstalled(ctx)) return { pass: true };
 		const fails = [];
 		if (!isNewPluginEnabled(ctx.config)) fails.push(`plugins.entries["${LARK_PLUGIN_NAME}"].enabled !== true（应启用）`);
@@ -3573,10 +3289,6 @@ let FeishuPluginStateNormalizeRule = class FeishuPluginStateNormalizeRule extend
 		};
 	}
 	repair(ctx) {
-		if (isBuiltinFeishuTarget()) {
-			cleanupExternalLarkResiduals(ctx);
-			return;
-		}
 		setEntryEnabled(ctx.config, LARK_PLUGIN_NAME, true);
 		setEntryEnabled(ctx.config, BUILTIN_FEISHU_PLUGIN_NAME, false);
 		ensureFeishuTools(ctx.config);
@@ -3590,9 +3302,6 @@ FeishuPluginStateNormalizeRule = __decorate([Rule({
 	repairMode: "standard",
 	level: "critical"
 })], FeishuPluginStateNormalizeRule);
-function isBuiltinFeishuTarget() {
-	return supportsBuiltinFeishu(readOpenclawRuntimeVersion());
-}
 function isPluginInstalled(ctx) {
 	return node_fs.default.existsSync(node_path.default.join(getExtensionsDir(ctx.configPath), LARK_PLUGIN_NAME));
 }
@@ -3619,113 +3328,340 @@ function hasFeishuTool(list) {
 * openclaw schema 禁止同一 scope 同时设 allow + alsoAllow，故有 allow 时必须并入 allow，
 * 否则会触发 tools_allow_also_allow_conflict 规则反复来回改写。
 */
-function feishuGrantTarget(config) {
-	return readTopLevelToolsList(config, "allow").length > 0 ? "allow" : "alsoAllow";
+function feishuGrantTarget(config) {
+	return readTopLevelToolsList(config, "allow").length > 0 ? "allow" : "alsoAllow";
+}
+/**
+* 仅看顶层 tools——agent 级授权是用户对单 agent 的精细化配置，doctor 不动。
+* 返回缺失的目标键名（'allow' / 'alsoAllow'），不缺时返回 null。
+*
+* 不关心 lark-cli：tools.alsoAllow（授权层）与 channels.feishu.tools.deny（插件注册层）
+* 是两个正交的 config key，可并存——授权一个被 deny 的工具是无害空操作。因此本规则始终
+* 补全 FEISHU_TOOLS（让 openclaw-lark 实际注册的工具都可用），重叠工具的"不可用"由独立的
+* deny 规则在注册层处理，互不干扰。
+*/
+function missingFeishuToolsGrant(config) {
+	const target = feishuGrantTarget(config);
+	return hasFeishuTool(readTopLevelToolsList(config, target)) ? null : target;
+}
+function findLegacyResiduals(ctx) {
+	const found = [];
+	const plugins = asRecord(ctx.config.plugins);
+	if (asRecord(plugins?.entries)?.["feishu-openclaw-plugin"] != null) found.push("entries[legacy]");
+	const allow = plugins?.allow;
+	if (Array.isArray(allow) && allow.includes("feishu-openclaw-plugin")) found.push("allow[legacy]");
+	if (asRecord(getPluginInstallsMap(ctx.configPath, ctx.config)["feishu-openclaw-plugin"]) != 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 target = feishuGrantTarget(config);
+	const current = readTopLevelToolsList(config, target);
+	if (hasFeishuTool(current)) return;
+	ensureRecord(config, "tools")[target] = [...new Set([...current, ...FEISHU_TOOLS])];
+}
+function cleanupLegacyResiduals(ctx) {
+	const plugins = asRecord(ctx.config.plugins);
+	if (plugins) {
+		const entries = asRecord(plugins.entries);
+		if (entries && "feishu-openclaw-plugin" in entries) delete entries[LEGACY_LARK_PLUGIN_NAME];
+		const allow = plugins.allow;
+		if (Array.isArray(allow)) {
+			for (let i = allow.length - 1; i >= 0; i--) if (allow[i] === "feishu-openclaw-plugin") allow.splice(i, 1);
+			if (!allow.includes("openclaw-lark")) allow.push(LARK_PLUGIN_NAME);
+		}
+	}
+	const installs = { ...getPluginInstallsMap(ctx.configPath, ctx.config) };
+	if ("feishu-openclaw-plugin" in installs) {
+		delete installs[LEGACY_LARK_PLUGIN_NAME];
+		setPluginInstallsMap(ctx.configPath, ctx.config, installs);
+	}
+	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}`);
+		}
+	}
+}
+//#endregion
+//#region src/version-compat.ts
+const VERSION_COMPAT_MAP = Object.freeze([
+	{
+		openclawLarkVersion: "2026.5.20",
+		minOpenclawVersion: "2026.5.7"
+	},
+	{
+		openclawLarkVersion: "2026.5.13",
+		minOpenclawVersion: "2026.5.7"
+	},
+	{
+		openclawLarkVersion: "2026.5.12",
+		minOpenclawVersion: "2026.5.7"
+	},
+	{
+		openclawLarkVersion: "2026.5.7",
+		minOpenclawVersion: "2026.5.6"
+	},
+	{
+		openclawLarkVersion: "2026.4.10",
+		minOpenclawVersion: "2026.4.27"
+	},
+	{
+		openclawLarkVersion: "2026.4.9",
+		minOpenclawVersion: "2026.3.28"
+	},
+	{
+		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"
+	}
+]);
+/**
+* Coerce a CalVer string ("YYYY.M.D[suffix]") to a clean semver string.
+* semver.coerce strips non-numeric suffixes (e.g. "-rc.1") and fills in
+* missing components with 0. Returns "0.0.0" for unparseable input.
+*/
+function coerceCalVer(v) {
+	return semver.default.coerce(v)?.version ?? "0.0.0";
+}
+/**
+* Compare two CalVer strings ("YYYY.M.D") numerically.
+* Delegates to semver for correct numeric component ordering —
+* plain string comparison would give wrong results (e.g. '2026.3.18' < '2026.3.9').
+* Suffixes like "-rc.1" are stripped via coercion before comparison.
+*/
+function compareCalVer(a, b) {
+	return semver.default.compare(coerceCalVer(a), coerceCalVer(b));
 }
 /**
-* 仅看顶层 tools——agent 级授权是用户对单 agent 的精细化配置，doctor 不动。
-* 返回缺失的目标键名（'allow' / 'alsoAllow'），不缺时返回 null。
+* 该条目的有效上界——开区间（EXCLUSIVE）：openclaw ≥ 此值即不兼容。
+* undefined = 最高档，无上界。
 *
-* 不关心 lark-cli：tools.alsoAllow（授权层）与 channels.feishu.tools.deny（插件注册层）
-* 是两个正交的 config key，可并存——授权一个被 deny 的工具是无害空操作。因此本规则始终
-* 补全 FEISHU_TOOLS（让 openclaw-lark 实际注册的工具都可用），重叠工具的"不可用"由独立的
-* deny 规则在注册层处理，互不干扰。
+* 上界一律为开区间，两种来源：
+*   - 有显式 maxOpenclawVersion → 直接用它（它本身就是「首个不兼容的 openclaw 版本」）。
+*   - 无显式 max → 向更高插件版本（表降序，index 更小）扫描，取首个「严格更高 min」的
+*     minOpenclawVersion，即下一不兼容区间的起点。
+*
+* 只接受严格更高的 min（跳过相同 min 的同档；跳过更低 min 防止非单调表产生空区间
+* [min, max) 把本条目永久判为不兼容）。
 */
-function missingFeishuToolsGrant(config) {
-	const target = feishuGrantTarget(config);
-	return hasFeishuTool(readTopLevelToolsList(config, target)) ? null : target;
-}
-function findLegacyResiduals(ctx) {
-	const found = [];
-	const plugins = asRecord(ctx.config.plugins);
-	if (asRecord(plugins?.entries)?.["feishu-openclaw-plugin"] != null) found.push("entries[legacy]");
-	const allow = plugins?.allow;
-	if (Array.isArray(allow) && allow.includes("feishu-openclaw-plugin")) found.push("allow[legacy]");
-	if (asRecord(getPluginInstallsMap(ctx.configPath, ctx.config)["feishu-openclaw-plugin"]) != 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 inferEffectiveMax(index) {
+	const cur = VERSION_COMPAT_MAP[index];
+	if (cur.maxOpenclawVersion != null) return cur.maxOpenclawVersion;
+	for (let i = index - 1; i >= 0; i--) if (compareCalVer(VERSION_COMPAT_MAP[i].minOpenclawVersion, cur.minOpenclawVersion) > 0) return VERSION_COMPAT_MAP[i].minOpenclawVersion;
 }
-function findExternalLarkResiduals(ctx) {
-	const found = [];
-	const plugins = asRecord(ctx.config.plugins);
-	const entries = asRecord(plugins?.entries);
-	const installs = getPluginInstallsMap(ctx.configPath, ctx.config);
-	const allow = plugins?.allow;
-	for (const name of [LARK_PLUGIN_NAME, LEGACY_LARK_PLUGIN_NAME]) {
-		if (entries?.[name] != null) found.push(`entries[${name}]`);
-		if (Array.isArray(allow) && allow.includes(name)) found.push(`allow[${name}]`);
-		if (asRecord(installs[name]) != null) found.push(`installs[${name}]`);
-		if (node_fs.default.existsSync(node_path.default.join(getExtensionsDir(ctx.configPath), name))) found.push(`fs/${name}`);
-	}
-	return found;
+/**
+* 单一真相源：floor 匹配 + 有效上界，得到某插件版本的半开兼容区间 [min, max)（含命中条目）。
+* evaluateVersionRange / findClosestEntry / effectiveCompatRange 全部基于它，
+* 避免 floor 匹配与 inferEffectiveMax 在多处重复。max 一律为开区间上界（EXCLUSIVE）；
+* 最高档 max 为 undefined（无上界）。undefined = 版本比全表都旧（无 floor 条目）。
+*/
+function resolveRange(pluginVersion) {
+	const index = VERSION_COMPAT_MAP.findIndex((e) => compareCalVer(e.openclawLarkVersion, pluginVersion) <= 0);
+	if (index === -1) return void 0;
+	const entry = VERSION_COMPAT_MAP[index];
+	return {
+		entry,
+		min: entry.minOpenclawVersion,
+		max: inferEffectiveMax(index)
+	};
 }
-function setEntryEnabled(config, key, enabled) {
-	const entries = ensureRecord(ensureRecord(config, "plugins"), "entries");
-	entries[key] = {
-		...asRecord(entries[key]) ?? {},
-		enabled
+/**
+* 对一个**已对标到 VERSION_COMPAT_MAP 键**的版本评估其与 openclaw 的兼容性，
+* 并在不兼容时给出方向。fork 的 pin、legacy 分类等在 `checkPluginCompat` 处理，
+* 本函数只负责「版本 × openclaw 区间」这一段唯一逻辑。
+*
+* - index === -1（插件版本比全表都旧，无 floor 条目）→ 无区间可判，视为插件过旧 → 'lark'
+* - oc < entry.minOpenclawVersion → 'openclaw'
+* - oc ≥ 有效上界（开区间）→ 'lark'
+* - 否则兼容
+*
+* 区间统一为半开 [min, max)：min 闭、max 开（显式与推断上界一律 EXCLUSIVE）。
+*/
+function evaluateVersionRange(pluginVersion, openclawVersion) {
+	const r = resolveRange(pluginVersion);
+	if (!r) return {
+		compatible: false,
+		direction: "lark",
+		entry: void 0
+	};
+	const oc = coerceCalVer(openclawVersion);
+	if (semver.default.lt(oc, coerceCalVer(r.min))) return {
+		compatible: false,
+		direction: "openclaw",
+		entry: r.entry
+	};
+	if (r.max !== void 0 && semver.default.gte(oc, coerceCalVer(r.max))) return {
+		compatible: false,
+		direction: "lark",
+		entry: r.entry
+	};
+	return {
+		compatible: true,
+		direction: null,
+		entry: r.entry
 	};
 }
-function ensureFeishuTools(config) {
-	const target = feishuGrantTarget(config);
-	const current = readTopLevelToolsList(config, target);
-	if (hasFeishuTool(current)) return;
-	ensureRecord(config, "tools")[target] = [...new Set([...current, ...FEISHU_TOOLS])];
+/**
+* Fork plugin handling.
+*
+* `@lark-apaas/openclaw-lark` is an internal fork whose own version numbers
+* (e.g. 2026.4.3, 2026.4.4) are NOT keys in VERSION_COMPAT_MAP. Floor-matching
+* a fork version against the official-keyed map only works by coincidence of
+* numbering and breaks once the fork version drifts past an official entry.
+* Both the install-time compat check and the diagnose rule must therefore pin
+* the fork to its official-equivalent version before consulting the map.
+*/
+/** fork 对标的官方 openclaw-lark 版本（与 VERSION_COMPAT_MAP 强耦合，故留在此处）。 */
+const FORK_LARK_PLUGIN_PINNED_VERSION = "2026.4.1";
+/**
+* 返回某插件版本（floor 匹配后）的有效兼容区间 [min, max)，含 evaluateVersionRange 所用的
+* （显式或推断的）开区间上界——区别于仅暴露显式 maxOpenclawVersion 的 findClosestEntry。
+* undefined = 版本比全表都旧（无 floor 条目）。
+*/
+function effectiveCompatRange(pluginVersion) {
+	const r = resolveRange(pluginVersion);
+	return r ? {
+		min: r.min,
+		max: r.max
+	} : void 0;
 }
-function cleanupLegacyResiduals(ctx) {
-	const plugins = asRecord(ctx.config.plugins);
-	if (plugins) {
-		const entries = asRecord(plugins.entries);
-		if (entries && "feishu-openclaw-plugin" in entries) delete entries[LEGACY_LARK_PLUGIN_NAME];
-		const allow = plugins.allow;
-		if (Array.isArray(allow)) {
-			for (let i = allow.length - 1; i >= 0; i--) if (allow[i] === "feishu-openclaw-plugin") allow.splice(i, 1);
-			if (!allow.includes("openclaw-lark")) allow.push(LARK_PLUGIN_NAME);
-		}
-	}
-	const installs = { ...getPluginInstallsMap(ctx.configPath, ctx.config) };
-	if ("feishu-openclaw-plugin" in installs) {
-		delete installs[LEGACY_LARK_PLUGIN_NAME];
-		setPluginInstallsMap(ctx.configPath, ctx.config, installs);
-	}
-	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}`);
-		}
-	}
+/** "@scope/name" → "name"；无 scope 原样返回。 */
+function extractBaseName(name) {
+	if (!name) return void 0;
+	return name.startsWith("@") ? name.split("/")[1] : name;
 }
-function cleanupExternalLarkResiduals(ctx) {
-	const externalNames = new Set([LARK_PLUGIN_NAME, LEGACY_LARK_PLUGIN_NAME]);
-	const plugins = asRecord(ctx.config.plugins);
-	if (plugins) {
-		const entries = asRecord(plugins.entries);
-		if (entries) for (const name of externalNames) delete entries[name];
-		const allow = plugins.allow;
-		if (Array.isArray(allow)) {
-			for (let i = allow.length - 1; i >= 0; i--) if (externalNames.has(String(allow[i]))) allow.splice(i, 1);
-		}
-	}
-	const installs = { ...getPluginInstallsMap(ctx.configPath, ctx.config) };
-	for (const name of externalNames) delete installs[name];
-	setPluginInstallsMap(ctx.configPath, ctx.config, installs);
-	const extDir = getExtensionsDir(ctx.configPath);
-	for (const name of externalNames) {
-		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 reasonFromRange(r) {
+	if (r.compatible) return "compatible";
+	if (r.direction === "openclaw") return "oc-below-min";
+	return r.entry ? "oc-above-max" : "version-not-in-map";
+}
+/**
+* 统一的飞书插件兼容判定入口——唯一的判定真相源。
+*
+* 入参只有三个：插件包名、插件版本、当前 openclaw 版本（**不涉及 recommendedOpenclawTag**，
+* 推荐版本的处理交由各业务点）。判定算法：
+*
+*   1. fork `@lark-apaas/openclaw-lark`：先 pin 到对标官方版本（FORK_LARK_PLUGIN_PINNED_VERSION）
+*      再按区间判定上下界。
+*   2. 其他 `@lark-apaas/*` fork：无条件豁免（兼容）。
+*   3. legacy `feishu-openclaw-plugin`（含带 scope 形式）：一律不兼容，方向 = 换飞书插件。
+*   4. 官方版及其余包：用自身版本按 VERSION_COMPAT_MAP 区间判定；读不到版本号 → 不兼容（换插件）。
+*
+* 所有消费方（install-extension 预检、feishu_plugin_version_compat 两条规则、needsLarkUpgrade）
+* 都应消费本方法，不再各自实现兼容/方向逻辑，避免口径漂移。
+*/
+function checkPluginCompat(packageName, pluginVersion, openclawVersion) {
+	if (packageName === "@lark-apaas/openclaw-lark") {
+		const resolvedVersion = FORK_LARK_PLUGIN_PINNED_VERSION;
+		const r = evaluateVersionRange(resolvedVersion, openclawVersion);
+		return {
+			...r,
+			reason: reasonFromRange(r),
+			resolvedVersion
+		};
 	}
+	if ((packageName && packageName.startsWith("@") ? packageName.split("/")[0] : void 0) === "@lark-apaas") return {
+		compatible: true,
+		direction: null,
+		reason: "fork-exempt",
+		resolvedVersion: pluginVersion,
+		entry: void 0
+	};
+	if (extractBaseName(packageName) === "feishu-openclaw-plugin") return {
+		compatible: false,
+		direction: "lark",
+		reason: "legacy",
+		resolvedVersion: pluginVersion,
+		entry: void 0
+	};
+	if (!pluginVersion) return {
+		compatible: false,
+		direction: "lark",
+		reason: "version-unknown",
+		resolvedVersion: void 0,
+		entry: void 0
+	};
+	const r = evaluateVersionRange(pluginVersion, openclawVersion);
+	return {
+		...r,
+		reason: reasonFromRange(r),
+		resolvedVersion: pluginVersion
+	};
 }
 //#endregion
 //#region src/rules/feishu-plugin-version-compat.ts
@@ -5674,21 +5610,6 @@ async function installExtension(tag, ossFileMap, opts = {}) {
 	}
 	console.error(`[install-extension] tag=${tag} targets=${targets.length}`);
 	const t0 = Date.now();
-	const targetOpenclawVersion = resolveInstallTargetOpenclawVersion(tag);
-	if (supportsBuiltinFeishu(targetOpenclawVersion) && targets.some((p) => p.name === "openclaw-lark")) {
-		const configPath = opts.configPath ?? node_path.default.join(homeBase, DEFAULT_CONFIG_REL);
-		console.error(`[install-extension] openclaw@${targetOpenclawVersion} uses built-in feishu — skipping external ${LARK_PLUGIN_NAME}`);
-		cleanupExternalLarkForBuiltinFeishu({
-			homeBase,
-			configPath,
-			updateConfig: !opts.skipConfigUpdate
-		});
-		targets = targets.filter((p) => p.name !== LARK_PLUGIN_NAME);
-		if (targets.length === 0) {
-			console.error(`[install-extension] done in ${Date.now() - t0}ms`);
-			return;
-		}
-	}
 	const larkTarget = opts.skipConfigUpdate ? void 0 : targets.find((p) => p.name === LARK_PLUGIN_NAME);
 	if (larkTarget) {
 		if (await installLarkPluginWithCompatCheck({
@@ -5816,41 +5737,6 @@ function installOne$1(pkg, tarball, homeBase) {
 		force: true
 	});
 }
-function resolveInstallTargetOpenclawVersion(tag) {
-	return tag.match(/\d+\.\d+\.\d+/)?.[0] ?? readOpenclawRuntimeVersion();
-}
-function cleanupExternalLarkForBuiltinFeishu(opts) {
-	const externalNames = new Set([LARK_PLUGIN_NAME, LEGACY_LARK_PLUGIN_NAME]);
-	const extDir = node_path.default.join(opts.homeBase, "workspace", "agent", "extensions");
-	for (const name of externalNames) {
-		const target = node_path.default.join(extDir, name);
-		try {
-			node_fs.default.rmSync(target, {
-				recursive: true,
-				force: true
-			});
-		} catch (e) {
-			console.error(`[install-extension] WARN: failed to remove ${target}: ${e.message}`);
-		}
-	}
-	if (!opts.updateConfig || !node_fs.default.existsSync(opts.configPath)) return;
-	const config = loadJSON5().parse(node_fs.default.readFileSync(opts.configPath, "utf-8"));
-	const plugins = asRecord(config.plugins);
-	if (plugins) {
-		const allow = plugins.allow;
-		if (Array.isArray(allow)) {
-			for (let i = allow.length - 1; i >= 0; i--) if (externalNames.has(String(allow[i]))) allow.splice(i, 1);
-		}
-		const entries = asRecord(plugins.entries);
-		if (entries) for (const name of externalNames) delete entries[name];
-	}
-	const installs = { ...getPluginInstallsMap(opts.configPath, config) };
-	for (const name of externalNames) delete installs[name];
-	setPluginInstallsMap(opts.configPath, config, installs);
-	const tmpPath = opts.configPath + ".builtin-feishu-tmp";
-	node_fs.default.writeFileSync(tmpPath, JSON.stringify(config, null, 2), "utf-8");
-	moveSafe(tmpPath, opts.configPath);
-}
 /**
 * Install openclaw-lark with a pre-flight compatibility check.
 *
@@ -11419,7 +11305,7 @@ async function reportCliRun(opts) {
 //#region src/help.ts
 const BIN = "mclaw-diagnose";
 function versionBanner() {
-	return `v0.1.21-alpha.2`;
+	return `v0.1.21-beta.0`;
 }
 const COMMANDS = [
 	{

package/package.json

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