@lark-apaas/openclaw-scripts-diagnose-cli 0.1.18-alpha.3 → 0.1.18-alpha.4

package/dist/index.cjs

@@ -52,7 +52,7 @@ node_assert = __toESM(node_assert);
 * it terse and parseable.
 */
 function getVersion() {
-	return "0.1.18-alpha.3";
+	return "0.1.18-alpha.4";
 }
 //#endregion
 //#region src/rule-engine/base.ts
@@ -1155,6 +1155,18 @@ function isValidJWT(token) {
 function asRecord(val) {
 	return val != null && typeof val === "object" && !Array.isArray(val) ? val : void 0;
 }
+/**
+* Get-or-create a nested record at `obj[key]`: returns the existing plain object,
+* or replaces a missing / non-object / array value with a fresh `{}` and returns it.
+* Mutates `obj`. Chainable for deep paths: `ensureRecord(ensureRecord(o,'a'),'b')`.
+*/
+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;
+}
 /** Collect existing AGENTS.md files from the default workspace and configured agent workspaces. */
 function collectExistingAgentsMdPaths(ctx) {
 	const paths = /* @__PURE__ */ new Set();
@@ -2610,51 +2622,6 @@ function upsertResourceConstrainedToolsBlock(content) {
 	return `${content}${content.length > 0 && !content.endsWith("\n") ? "\n\n" : "\n"}${RESOURCE_CONSTRAINED_TOOLS_BLOCK}\n`;
 }
 //#endregion
-//#region src/paths.ts
-/**
-* Central directory for all ephemeral diagnose/reset artifacts: task status
-* files (`reset-<taskId>.json`) and human-readable step logs
-* (`reset-<taskId>.log`). Having everything under one dir makes debugging a
-* stuck reset much easier — `ls /tmp/openclaw-diagnose/` shows every recent
-* run, and each run's log is right next to its state.
-*/
-const DIAGNOSE_DIR = "/tmp/openclaw-diagnose";
-function resetResultFile(taskId) {
-	return `${DIAGNOSE_DIR}/reset-${taskId}.json`;
-}
-function resetLogFile(taskId) {
-	return `${DIAGNOSE_DIR}/reset-${taskId}.log`;
-}
-/** Sandbox workspace root where openclaw config + agent state lives. */
-const WORKSPACE_DIR = "/home/gem/workspace/agent";
-/** File containing the provider key used by the openclaw miaoda provider. */
-const PROVIDER_FILE_PATH = "/home/gem/workspace/.force/openclaw/miaoda-provider-key";
-/** File containing the miaoda openclaw secrets JSON. */
-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 场景专属修复状态的信号文件目录。
-* fixStatus 有值时在此目录下创建同名文件（如 /tmp/event/PORT_FIX_READY），
-* 文件内容为完整的 UpgradeLarkResult JSON，供外部进程轮询感知升级结果。
-*/
-const FIX_EVENT_DIR = "/tmp/event";
-/**
-* 安装指令互斥锁文件路径。
-* upgrade-lark / install-openclaw / install-extension / install-cli / reset --worker
-* 共享此锁，同一时刻只允许一个安装指令运行。
-* 锁文件内容：{ pid, command, startedAt }。
-*/
-const INSTALL_LOCK_FILE = `${DIAGNOSE_DIR}/install.lock`;
-/**
-* upgrade-lark 每次运行的日志文件路径，含时间戳便于按时间排序定位。
-* checkOnly=true 时文件名含 "-check" 后缀，便于与正式安装日志区分。
-*/
-function upgradeLarkLogFile(runId, checkOnly = false) {
-	const ts = (/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replace(/:/g, "-");
-	return `${DIAGNOSE_DIR}/upgrade-lark${checkOnly ? "-check" : ""}-${ts}-${runId.slice(0, 8)}.log`;
-}
-//#endregion
 //#region src/constants.ts
 /**
 * 全局共享常量（插件名 / CLI 名 / 路径 / 插件集合）。
@@ -2672,8 +2639,6 @@ const LARK_PLUGIN_NAME = "openclaw-lark";
 * 版本号自成体系、不在 VERSION_COMPAT_MAP 内，按对标的官方版本判定兼容性。
 */
 const FORK_LARK_PLUGIN_FULL_NAME = "@lark-apaas/openclaw-lark";
-/** fork 插件的 scope 前缀。 */
-const FORK_LARK_PLUGIN_SCOPE = "@lark-apaas";
 /**
 * 社区插件：openclaw **内置** 的 `feishu` 插件（非独立扩展）。
 * 与官方/ fork openclaw-lark 互斥，规范化时应禁用以让位 openclaw-lark。
@@ -2691,8 +2656,12 @@ const MEM0_PLUGIN_NAME = "openclaw-mem0-plugin";
 const LARK_CLI_NAME = "lark-cli";
 /** agent-skills 模板包名（manifest role=template，随 lark-cli 一起安装）。 */
 const AGENT_SKILLS_NAME = "agent-skills";
-/** 飞书插件目录集合（官方短名 + 旧版名）：备份 / 清理 / 安装时迭代用。 */
-const FEISHU_PLUGIN_DIR_NAMES = [LARK_PLUGIN_NAME, LEGACY_LARK_PLUGIN_NAME];
+/**
+* lark 系**有 extension 目录**的插件名（官方 openclaw-lark + 旧版 feishu-openclaw-plugin）：
+* 备份 / 清理 / 安装、以及 plugins.allow 成员判定时迭代用。
+* 注意与「可启用的飞书插件集」区分——后者还含**无目录**的内置 feishu（见各规则局部定义）。
+*/
+const LARK_PLUGIN_DIR_NAMES = [LARK_PLUGIN_NAME, LEGACY_LARK_PLUGIN_NAME];
 /**
 * install-extension --all 安装的官方扩展插件集合（manifest role=extension）。
 * builtin-plugin-missing 与 miaoda-official-plugins-install-spec-unlock 共用此单一来源，
@@ -2710,535 +2679,147 @@ const WORKSPACE_AGENT_REL = "workspace/agent";
 /** openclaw.json 默认相对路径。 */
 const DEFAULT_CONFIG_REL = `${WORKSPACE_AGENT_REL}/openclaw.json`;
 //#endregion
-//#region src/lark-cli-init.ts
-const PE_XML_TAG = "lark-cli-pe";
-const PE_PLACEHOLDER = `
-<${PE_XML_TAG}>
-**【强制要求 - 无例外】飞书所有操作必须先读 feishu-lark-cli skill。未读skill不得调用任何飞书工具，违者视为操作失误。**
-</${PE_XML_TAG}>
-`;
-function isLarkPluginInstalled$1(configPath) {
-	const extDir = getExtensionsDir(configPath);
-	return FEISHU_PLUGIN_DIR_NAMES.some((name) => {
-		try {
-			return node_fs.default.existsSync(node_path.default.join(extDir, name, "package.json"));
-		} catch {
-			return false;
-		}
-	});
+//#region src/rules/miaoda-official-plugins-install-spec-unlock.ts
+/**
+* Official miaoda-side plugins that must track manifest — version-locked specs
+* here block upgrades. Third-party / user-installed plugins are intentionally
+* out of scope (users may pin them deliberately). 集合见 constants.OFFICIAL_EXTENSION_PLUGIN_NAMES。
+*/
+const LOCKED_NPM_SPEC = /^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*@[^@/:#\s]+$/i;
+function isLockedNpmSpec(spec) {
+	return typeof spec === "string" && LOCKED_NPM_SPEC.test(spec);
 }
-function isLarkCliAvailable$2() {
-	try {
-		return (0, node_child_process.spawnSync)("lark-cli", ["--version"], {
-			encoding: "utf-8",
-			timeout: 5e3,
-			stdio: [
-				"ignore",
-				"pipe",
-				"ignore"
-			]
-		}).status === 0;
-	} catch {
-		return false;
+function unlockSpec(spec) {
+	const slash = spec.indexOf("/");
+	const cut = slash === -1 ? spec.indexOf("@") : spec.indexOf("@", slash + 1);
+	return spec.slice(0, cut);
+}
+/** Yield `[key, lockedSpec]` for every official-plugin install whose `spec` is locked. */
+function* iterLockedOfficialInstalls(config) {
+	const installs = getNestedMap(config, "plugins", "installs");
+	if (!installs) return;
+	for (const [key, entry] of Object.entries(installs)) {
+		if (!OFFICIAL_EXTENSION_PLUGIN_NAMES.has(key)) continue;
+		const spec = asRecord(entry)?.spec;
+		if (isLockedNpmSpec(spec)) yield [key, spec];
 	}
 }
-function readConfig(configPath) {
-	try {
-		const raw = node_fs.default.readFileSync(configPath, "utf-8");
-		const parsed = loadJSON5().parse(raw);
-		return parsed != null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
-	} catch {
-		return null;
+let MiaodaOfficialPluginsInstallSpecUnlockRule = class MiaodaOfficialPluginsInstallSpecUnlockRule extends DiagnoseRule {
+	validate(ctx) {
+		const locked = [...iterLockedOfficialInstalls(ctx.config)].map(([k]) => k);
+		if (locked.length === 0) return { pass: true };
+		return {
+			pass: false,
+			message: "plugins.installs 中官方插件存在锁版本的 spec: " + locked.sort().join(",")
+		};
+	}
+	repair(ctx) {
+		for (const [key, spec] of iterLockedOfficialInstalls(ctx.config)) setNestedValue(ctx.config, [
+			"plugins",
+			"installs",
+			key,
+			"spec"
+		], unlockSpec(spec));
 	}
+};
+MiaodaOfficialPluginsInstallSpecUnlockRule = __decorate([Rule({
+	key: "miaoda_official_plugins_install_spec_unlock",
+	description: "移除官方妙搭插件安装条目中的锁版本 npm spec，使其跟随最新 manifest 版本",
+	dependsOn: ["config_syntax_check"],
+	repairMode: "standard",
+	level: "silent"
+})], MiaodaOfficialPluginsInstallSpecUnlockRule);
+//#endregion
+//#region src/rules/miaoda-plugin-allow.ts
+let MiaodaPluginAllowRule = class MiaodaPluginAllowRule extends DiagnoseRule {
+	validate(ctx) {
+		if (!isPluginInstalledOnDisk(getExtensionsDir(ctx.configPath), "openclaw-extension-miaoda")) return { pass: true };
+		if (getAllow$1(ctx.config).includes("openclaw-extension-miaoda")) return { pass: true };
+		return {
+			pass: false,
+			message: `plugins.allow 缺少 ${MIAODA_PLUGIN_NAME}（已在 extensions/ 下装但未启用）`
+		};
+	}
+	repair(ctx) {
+		if (!isPluginInstalledOnDisk(getExtensionsDir(ctx.configPath), "openclaw-extension-miaoda")) return;
+		const plugins = ctx.config.plugins;
+		if (plugins == null || typeof plugins !== "object" || Array.isArray(plugins)) {
+			ctx.config.plugins = { allow: [MIAODA_PLUGIN_NAME] };
+			return;
+		}
+		const pluginsMap = plugins;
+		const rawAllow = pluginsMap.allow;
+		const allow = Array.isArray(rawAllow) ? rawAllow : [];
+		if (allow.includes("openclaw-extension-miaoda")) return;
+		allow.push(MIAODA_PLUGIN_NAME);
+		pluginsMap.allow = allow;
+	}
+};
+MiaodaPluginAllowRule = __decorate([Rule({
+	key: "miaoda_plugin_allow",
+	description: "当 openclaw-extension-miaoda 已在磁盘安装但未在 allow 列表中时，将其添加到 plugins.allow（实验性）",
+	dependsOn: ["config_syntax_check"],
+	repairMode: "standard",
+	level: "critical",
+	profile: "standard"
+})], MiaodaPluginAllowRule);
+function getAllow$1(config) {
+	const plugins = config.plugins;
+	if (plugins == null || typeof plugins !== "object" || Array.isArray(plugins)) return [];
+	const allow = plugins.allow;
+	if (!Array.isArray(allow)) return [];
+	return allow.filter((e) => typeof e === "string");
 }
-/**
-* Resolve the feishu app secret for the given appId.
-*
-* Lookup order:
-*   1. channels.feishu.appSecret  (single-agent: feishu.appId === appId)
-*   2. channels.feishu.accounts[key].appSecret  (multi-agent: account.appId === appId)
-*
-* Value interpretation:
-*   - string  → use directly
-*   - object  → secret is managed by a provider; use `feishuAppSecret` param instead
-*
-* Returns null when the secret cannot be determined.
-*/
-function resolveAppSecret(appId, config, feishuAppSecret) {
-	const feishu = getNestedMap(config, "channels", "feishu");
-	if (!feishu) return null;
-	let rawSecret;
-	if (typeof feishu.appId === "string" && feishu.appId === appId) rawSecret = feishu.appSecret;
-	else {
-		const accounts = asRecord(feishu.accounts);
-		if (accounts) for (const [, val] of Object.entries(accounts)) {
-			const account = asRecord(val);
-			if (account?.appId === appId) {
-				rawSecret = account.appSecret ?? feishu.appSecret;
-				break;
-			}
+//#endregion
+//#region src/rules/lark-plugin-allow.ts
+let LarkPluginAllowRule = class LarkPluginAllowRule extends DiagnoseRule {
+	validate(ctx) {
+		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));
+		if (installed == null) return { pass: true };
+		return {
+			pass: false,
+			message: `plugins.allow 缺少飞书插件 ${installed}（已在 extensions/ 下装但未启用）`
+		};
+	}
+	repair(ctx) {
+		const installed = detectInstalledLarkPlugin$1(getExtensionsDir(ctx.configPath));
+		if (installed == null) return;
+		if (ctx.config.plugins == null || typeof ctx.config.plugins !== "object" || Array.isArray(ctx.config.plugins)) {
+			ctx.config.plugins = { allow: [installed] };
+			return;
 		}
+		const pluginsMap = ctx.config.plugins;
+		const rawAllow = pluginsMap.allow;
+		const original = Array.isArray(rawAllow) ? rawAllow : [];
+		const stringAllow = original.filter((e) => typeof e === "string");
+		if (LARK_PLUGIN_DIR_NAMES.some((name) => stringAllow.includes(name))) return;
+		original.push(installed);
+		pluginsMap.allow = original;
 	}
-	if (typeof rawSecret === "string" && rawSecret) return rawSecret;
-	if (rawSecret != null && typeof rawSecret === "object") return feishuAppSecret ?? null;
-	return null;
+};
+LarkPluginAllowRule = __decorate([Rule({
+	key: "lark_plugin_allow",
+	description: "当飞书插件（openclaw-lark 或旧版名）已在磁盘安装但未加入 plugins.allow 时，自动添加",
+	dependsOn: ["config_syntax_check"],
+	repairMode: "standard",
+	level: "critical"
+})], LarkPluginAllowRule);
+function getAllow(config) {
+	const plugins = config.plugins;
+	if (plugins == null || typeof plugins !== "object" || Array.isArray(plugins)) return [];
+	const allow = plugins.allow;
+	if (!Array.isArray(allow)) return [];
+	return allow.filter((e) => typeof e === "string");
 }
 /**
-* Resolve the agents.md path for the given appId from the openclaw config.
-*
-* Case 1: appId matches channels.feishu.appId (single-agent path)
-*   → WORKSPACE_DIR/AGENTS.md
-*
-* Case 2: appId found in channels.feishu.accounts (multi-agent path)
-*   → find account key where account.appId === appId
-*   → find binding where match.channel=feishu && match.accountId=that key
-*   → if agentId === 'main'  → WORKSPACE_DIR/agents.md
-*   → else find agent in agents.list by id → agent.workspace/agents.md
-*
-* Returns null when the path cannot be determined.
+* fs-only 检测：`<extDir>/<name>/package.json` 存在即视为已装。
+* 优先级 openclaw-lark（新版）> feishu-openclaw-plugin（legacy）。
+* 不读 package.json 内容，只判存在性，避开 JSON 损坏。
 */
-function resolveAgentsMdPath(appId, config) {
-	const feishu = getNestedMap(config, "channels", "feishu");
-	if (!feishu) {
-		console.error("resolveAgentsMdPath: channels.feishu not found");
-		return null;
-	}
-	if (typeof feishu.appId === "string" && feishu.appId === appId) {
-		console.error(`resolveAgentsMdPath: case=single-agent feishu.appId=${feishu.appId}`);
-		return node_path.default.join(WORKSPACE_DIR, "workspace", "AGENTS.md");
-	}
-	const accounts = asRecord(feishu.accounts);
-	if (!accounts) {
-		console.error("resolveAgentsMdPath: feishu.accounts not found");
-		return null;
-	}
-	let accountId;
-	for (const [key, val] of Object.entries(accounts)) if (asRecord(val)?.appId === appId) {
-		accountId = key;
-		break;
-	}
-	if (!accountId) {
-		console.error(`resolveAgentsMdPath: no account found with appId=${appId} in feishu.accounts keys=[${Object.keys(accounts).join(",")}]`);
-		return null;
-	}
-	console.error(`resolveAgentsMdPath: found accountId=${accountId}`);
-	const bindings = Array.isArray(config.bindings) ? config.bindings : [];
-	let agentId;
-	for (const b of bindings) {
-		const binding = asRecord(b);
-		if (!binding) continue;
-		const match = asRecord(binding.match);
-		if (match?.channel === "feishu" && match?.accountId === accountId) {
-			if (typeof binding.agentId === "string") {
-				agentId = binding.agentId;
-				break;
-			}
-		}
-	}
-	if (!agentId) {
-		console.error(`resolveAgentsMdPath: no binding found for accountId=${accountId} in bindings(count=${bindings.length})`);
-		return null;
-	}
-	console.error(`resolveAgentsMdPath: found agentId=${agentId}`);
-	if (agentId === "main") {
-		console.error("resolveAgentsMdPath: case=multi-agent-main");
-		return node_path.default.join(WORKSPACE_DIR, "workspace", "AGENTS.md");
-	}
-	const agentsObj = asRecord(config.agents);
-	const list = Array.isArray(agentsObj?.list) ? agentsObj.list : [];
-	for (const a of list) {
-		const agent = asRecord(a);
-		if (agent?.id === agentId) {
-			const ws = typeof agent.workspace === "string" ? agent.workspace : node_path.default.join(WORKSPACE_DIR, "workspace");
-			console.error(`resolveAgentsMdPath: case=multi-agent-custom agentId=${agentId} workspace=${ws}`);
-			return node_path.default.join(ws, "AGENTS.md");
-		}
-	}
-	console.error(`resolveAgentsMdPath: agentId=${agentId} not found in agents.list(count=${list.length})`);
-	return null;
-}
-function appendPeToAgentsMd(agentsMdPath) {
-	const dir = node_path.default.dirname(agentsMdPath);
-	if (!node_fs.default.existsSync(dir)) node_fs.default.mkdirSync(dir, { recursive: true });
-	const existing = node_fs.default.existsSync(agentsMdPath) ? node_fs.default.readFileSync(agentsMdPath, "utf-8") : "";
-	if (existing.includes(`<lark-cli-pe>`)) {
-		console.error(`lark-cli-init: <${PE_XML_TAG}> already present in ${agentsMdPath}, skipping`);
-		return;
-	}
-	const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-	node_fs.default.appendFileSync(agentsMdPath, `${sep}${PE_PLACEHOLDER}`, "utf-8");
-	console.error(`lark-cli-init: appended PE placeholder to ${agentsMdPath}`);
-}
-/**
-* Collect every Feishu bot appId declared in the openclaw config.
-* Covers both single-agent (channels.feishu.appId) and multi-agent
-* (channels.feishu.accounts[*].appId) layouts. Returns a deduplicated list.
-*/
-function collectFeishuAppIds(configPath) {
-	const config = readConfig(configPath ?? CONFIG_PATH);
-	if (!config) return [];
-	const feishu = getNestedMap(config, "channels", "feishu");
-	if (!feishu) return [];
-	const appIds = /* @__PURE__ */ new Set();
-	const topAppId = feishu.appId;
-	if (typeof topAppId === "string" && topAppId.trim()) appIds.add(topAppId.trim());
-	const accounts = asRecord(feishu.accounts);
-	if (accounts) for (const val of Object.values(accounts)) {
-		const appId = asRecord(val)?.appId;
-		if (typeof appId === "string" && appId.trim()) appIds.add(appId.trim());
-	}
-	return [...appIds];
-}
-function runLarkCliInit(opts) {
-	const configPath = opts.configPath ?? CONFIG_PATH;
-	if (!isLarkPluginInstalled$1(configPath)) {
-		console.error("lark-cli-init: skipping — openclaw-lark plugin not installed");
-		return {
-			ok: true,
-			skipped: true,
-			skipReason: "openclaw-lark plugin not installed"
-		};
-	}
-	if (!isLarkCliAvailable$2()) {
-		console.error("lark-cli-init: skipping — lark-cli command not found");
-		return {
-			ok: true,
-			skipped: true,
-			skipReason: "lark-cli command not found"
-		};
-	}
-	const config = readConfig(configPath);
-	if (!config) return {
-		ok: false,
-		error: `could not read config at ${configPath}`
-	};
-	const agentsMdPath = resolveAgentsMdPath(opts.appId, config);
-	console.error(`lark-cli-init: resolved agents.md path=${agentsMdPath ?? "(null)"}`);
-	if (!agentsMdPath) return {
-		ok: false,
-		error: `could not resolve agents.md path for appId=${opts.appId}`
-	};
-	const appSecret = resolveAppSecret(opts.appId, config, opts.feishuAppSecret);
-	if (!appSecret) return {
-		ok: false,
-		error: `could not resolve appSecret for appId=${opts.appId}`
-	};
-	console.error(`lark-cli-init: running lark-cli config init --name ${opts.appId} --app-id ${opts.appId} --brand feishu --app-secret-stdin --force-init`);
-	const initRes = (0, node_child_process.spawnSync)("lark-cli", [
-		"config",
-		"init",
-		"--name",
-		opts.appId,
-		"--app-id",
-		opts.appId,
-		"--brand",
-		"feishu",
-		"--app-secret-stdin",
-		"--force-init"
-	], {
-		stdio: [
-			"pipe",
-			"pipe",
-			"pipe"
-		],
-		encoding: "utf-8",
-		input: appSecret
-	});
-	const configInitStdout = initRes.stdout?.trim() || void 0;
-	const configInitStderr = initRes.stderr?.trim() || void 0;
-	if (configInitStdout) console.error(`lark-cli config init stdout: ${configInitStdout}`);
-	if (configInitStderr) console.error(`lark-cli config init stderr: ${configInitStderr}`);
-	if (initRes.error) return {
-		ok: false,
-		configInitStdout,
-		configInitStderr,
-		error: `lark-cli config init spawn error: ${initRes.error.message}`
-	};
-	if (initRes.status !== 0) return {
-		ok: false,
-		configInitExitCode: initRes.status ?? void 0,
-		configInitStdout,
-		configInitStderr,
-		error: `lark-cli config init exited with code ${initRes.status}`
-	};
-	appendPeToAgentsMd(agentsMdPath);
-	return {
-		ok: true,
-		configInitExitCode: 0,
-		agentsMdPath
-	};
-}
-//#endregion
-//#region src/utils/feishu-tools-deny.ts
-/**
-* openclaw-lark 中与 lark-cli 功能重叠的工具，写入 channels.feishu.tools.deny 后
-* 由 openclaw-lark 插件自身的 shouldRegisterTool() 跳过注册，避免与 lark-cli 重复。
-* 支持尾部 `*` 通配（openclaw-lark matchesAnyPattern 识别）。
-*
-* 保留（IM / 鉴权 / 诊断类，与 lark-cli 无重叠）：feishu_chat*、feishu_get_user、
-* feishu_search_user、feishu_im_*、feishu_oauth*、feishu_auth、feishu_diagnose、feishu_doctor。
-*
-* install-cli（安装 lark-cli 后即时写）与 agents_md_lark_cli_pe 规则（doctor --fix
-* 自愈）共用本常量与合并逻辑，单一来源。
-*/
-const LARK_CLI_OVERLAP_TOOL_DENY = Object.freeze([
-	"feishu_create_doc",
-	"feishu_fetch_doc",
-	"feishu_update_doc",
-	"feishu_doc_comments",
-	"feishu_doc_media",
-	"feishu_drive_file",
-	"feishu_wiki_space",
-	"feishu_wiki_space_node",
-	"feishu_search_doc_wiki",
-	"feishu_bitable_*",
-	"feishu_calendar_*",
-	"feishu_task_*",
-	"feishu_sheet"
-]);
-/** 读取 channels.feishu.tools.deny 的字符串数组（缺失/非法时返回空数组）。 */
-function readDenyList(config) {
-	const deny = asRecord(asRecord(asRecord(config.channels)?.feishu)?.tools)?.deny;
-	return Array.isArray(deny) ? deny.filter((e) => typeof e === "string") : [];
-}
-/** 返回 deny 列表中尚缺的重叠工具（用于 validate 判定）。 */
-function larkCliToolDenyMissing(config) {
-	const existing = new Set(readDenyList(config));
-	return LARK_CLI_OVERLAP_TOOL_DENY.filter((t) => !existing.has(t));
-}
-/**
-* 确保 channels.feishu.tools.deny 含全部重叠工具（只增不删，幂等合并）。
-* 直接 mutate 传入的 config 对象；返回是否发生了变更。
-*/
-function ensureLarkCliToolDeny(config) {
-	if (larkCliToolDenyMissing(config).length === 0) return false;
-	if (!config.channels || typeof config.channels !== "object" || Array.isArray(config.channels)) config.channels = {};
-	const channels = config.channels;
-	if (!channels.feishu || typeof channels.feishu !== "object" || Array.isArray(channels.feishu)) channels.feishu = {};
-	const feishu = channels.feishu;
-	if (!feishu.tools || typeof feishu.tools !== "object" || Array.isArray(feishu.tools)) feishu.tools = {};
-	const tools = feishu.tools;
-	const existing = readDenyList(config);
-	tools.deny = [...new Set([...existing, ...LARK_CLI_OVERLAP_TOOL_DENY])];
-	return true;
-}
-//#endregion
-//#region src/utils/lark-cli-detect.ts
-/**
-* 探测 lark-cli 是否可用（`lark-cli --version` 退出码为 0）。
-* 多条规则共用同一判定：feishu_plugin_state_normalize（是否补 feishu_* 授权）、
-* agents_md_lark_cli_pe（是否补 PE / deny）等。
-*/
-function isLarkCliAvailable$1() {
-	try {
-		return (0, node_child_process.spawnSync)("lark-cli", ["--version"], {
-			encoding: "utf-8",
-			timeout: 5e3,
-			stdio: [
-				"ignore",
-				"pipe",
-				"ignore"
-			]
-		}).status === 0;
-	} catch {
-		return false;
-	}
-}
-//#endregion
-//#region src/rules/agents-md-lark-cli-pe.ts
-/** openclaw-lark 插件是否已落盘安装（deny 仅在插件存在时有意义）。 */
-function isLarkPluginInstalled(ctx) {
-	return node_fs.default.existsSync(node_path.default.join(getExtensionsDir(ctx.configPath), LARK_PLUGIN_NAME));
-}
-/** 第一个缺失 PE 内容的 AGENTS.md 路径；无则 undefined。 */
-function findAgentsMdMissingPe(ctx) {
-	return collectExistingAgentsMdPaths(ctx).find((filePath) => {
-		return !node_fs.default.readFileSync(filePath, "utf-8").includes(`<${PE_XML_TAG}>`);
-	});
-}
-/**
-* lark-cli 存在时统一规范化环境：
-*   1. 给各智能体 AGENTS.md 追加 lark-cli-pe PE 内容
-*   2. openclaw-lark 已装时，把与 lark-cli 重叠的工具写入 channels.feishu.tools.deny
-*      （只增不删，避免与 lark-cli 重复注册）
-* 两者门禁同为「lark-cli 可用」，故合并为一条规则。
-*/
-let AgentsMdLarkCliPeRule = class AgentsMdLarkCliPeRule extends DiagnoseRule {
-	validate(ctx) {
-		if (!isLarkCliAvailable$1()) return { pass: true };
-		const missingPath = findAgentsMdMissingPe(ctx);
-		if (missingPath) return {
-			pass: false,
-			message: `${missingPath} 中缺少 lark-cli-pe PE 内容，需要追加`
-		};
-		if (isLarkPluginInstalled(ctx) && larkCliToolDenyMissing(ctx.config).length > 0) return {
-			pass: false,
-			message: "channels.feishu.tools.deny 缺少与 lark-cli 重叠的 openclaw-lark 工具，需要补充"
-		};
-		return { pass: true };
-	}
-	repair(ctx) {
-		if (!isLarkCliAvailable$1()) return;
-		for (const filePath of collectExistingAgentsMdPaths(ctx)) {
-			const content = node_fs.default.readFileSync(filePath, "utf-8");
-			if (content.includes(`<lark-cli-pe>`)) continue;
-			const sep = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
-			node_fs.default.appendFileSync(filePath, `${sep}${PE_PLACEHOLDER}`, "utf-8");
-			console.error(`agents-md-lark-cli-pe: appended PE to ${filePath}`);
-		}
-		if (isLarkPluginInstalled(ctx) && ensureLarkCliToolDeny(ctx.config)) console.error("agents-md-lark-cli-pe: merged lark-cli overlap tools into channels.feishu.tools.deny");
-	}
-};
-AgentsMdLarkCliPeRule = __decorate([Rule({
-	key: "agents_md_lark_cli_pe",
-	description: "lark-cli 存在时规范化环境：AGENTS.md 追加 lark-cli-pe PE + openclaw-lark 重叠工具写入 channels.feishu.tools.deny",
-	dependsOn: ["config_syntax_check"],
-	repairMode: "standard",
-	level: "silent"
-})], AgentsMdLarkCliPeRule);
-//#endregion
-//#region src/rules/miaoda-official-plugins-install-spec-unlock.ts
-/**
-* Official miaoda-side plugins that must track manifest — version-locked specs
-* here block upgrades. Third-party / user-installed plugins are intentionally
-* out of scope (users may pin them deliberately). 集合见 constants.OFFICIAL_EXTENSION_PLUGIN_NAMES。
-*/
-const LOCKED_NPM_SPEC = /^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*@[^@/:#\s]+$/i;
-function isLockedNpmSpec(spec) {
-	return typeof spec === "string" && LOCKED_NPM_SPEC.test(spec);
-}
-function unlockSpec(spec) {
-	const slash = spec.indexOf("/");
-	const cut = slash === -1 ? spec.indexOf("@") : spec.indexOf("@", slash + 1);
-	return spec.slice(0, cut);
-}
-/** Yield `[key, lockedSpec]` for every official-plugin install whose `spec` is locked. */
-function* iterLockedOfficialInstalls(config) {
-	const installs = getNestedMap(config, "plugins", "installs");
-	if (!installs) return;
-	for (const [key, entry] of Object.entries(installs)) {
-		if (!OFFICIAL_EXTENSION_PLUGIN_NAMES.has(key)) continue;
-		const spec = asRecord(entry)?.spec;
-		if (isLockedNpmSpec(spec)) yield [key, spec];
-	}
-}
-let MiaodaOfficialPluginsInstallSpecUnlockRule = class MiaodaOfficialPluginsInstallSpecUnlockRule extends DiagnoseRule {
-	validate(ctx) {
-		const locked = [...iterLockedOfficialInstalls(ctx.config)].map(([k]) => k);
-		if (locked.length === 0) return { pass: true };
-		return {
-			pass: false,
-			message: "plugins.installs 中官方插件存在锁版本的 spec: " + locked.sort().join(",")
-		};
-	}
-	repair(ctx) {
-		for (const [key, spec] of iterLockedOfficialInstalls(ctx.config)) setNestedValue(ctx.config, [
-			"plugins",
-			"installs",
-			key,
-			"spec"
-		], unlockSpec(spec));
-	}
-};
-MiaodaOfficialPluginsInstallSpecUnlockRule = __decorate([Rule({
-	key: "miaoda_official_plugins_install_spec_unlock",
-	description: "移除官方妙搭插件安装条目中的锁版本 npm spec，使其跟随最新 manifest 版本",
-	dependsOn: ["config_syntax_check"],
-	repairMode: "standard",
-	level: "silent"
-})], MiaodaOfficialPluginsInstallSpecUnlockRule);
-//#endregion
-//#region src/rules/miaoda-plugin-allow.ts
-let MiaodaPluginAllowRule = class MiaodaPluginAllowRule extends DiagnoseRule {
-	validate(ctx) {
-		if (!isPluginInstalledOnDisk(getExtensionsDir(ctx.configPath), "openclaw-extension-miaoda")) return { pass: true };
-		if (getAllow$1(ctx.config).includes("openclaw-extension-miaoda")) return { pass: true };
-		return {
-			pass: false,
-			message: `plugins.allow 缺少 ${MIAODA_PLUGIN_NAME}（已在 extensions/ 下装但未启用）`
-		};
-	}
-	repair(ctx) {
-		if (!isPluginInstalledOnDisk(getExtensionsDir(ctx.configPath), "openclaw-extension-miaoda")) return;
-		const plugins = ctx.config.plugins;
-		if (plugins == null || typeof plugins !== "object" || Array.isArray(plugins)) {
-			ctx.config.plugins = { allow: [MIAODA_PLUGIN_NAME] };
-			return;
-		}
-		const pluginsMap = plugins;
-		const rawAllow = pluginsMap.allow;
-		const allow = Array.isArray(rawAllow) ? rawAllow : [];
-		if (allow.includes("openclaw-extension-miaoda")) return;
-		allow.push(MIAODA_PLUGIN_NAME);
-		pluginsMap.allow = allow;
-	}
-};
-MiaodaPluginAllowRule = __decorate([Rule({
-	key: "miaoda_plugin_allow",
-	description: "当 openclaw-extension-miaoda 已在磁盘安装但未在 allow 列表中时，将其添加到 plugins.allow（实验性）",
-	dependsOn: ["config_syntax_check"],
-	repairMode: "standard",
-	level: "critical",
-	profile: "standard"
-})], MiaodaPluginAllowRule);
-function getAllow$1(config) {
-	const plugins = config.plugins;
-	if (plugins == null || typeof plugins !== "object" || Array.isArray(plugins)) return [];
-	const allow = plugins.allow;
-	if (!Array.isArray(allow)) return [];
-	return allow.filter((e) => typeof e === "string");
-}
-//#endregion
-//#region src/rules/lark-plugin-allow.ts
-const LARK_PLUGIN_NAMES = FEISHU_PLUGIN_DIR_NAMES;
-let LarkPluginAllowRule = class LarkPluginAllowRule extends DiagnoseRule {
-	validate(ctx) {
-		const allow = getAllow(ctx.config);
-		if (LARK_PLUGIN_NAMES.some((name) => allow.includes(name))) return { pass: true };
-		const installed = detectInstalledLarkPlugin(getExtensionsDir(ctx.configPath));
-		if (installed == null) return { pass: true };
-		return {
-			pass: false,
-			message: `plugins.allow 缺少飞书插件 ${installed}（已在 extensions/ 下装但未启用）`
-		};
-	}
-	repair(ctx) {
-		const installed = detectInstalledLarkPlugin(getExtensionsDir(ctx.configPath));
-		if (installed == null) return;
-		if (ctx.config.plugins == null || typeof ctx.config.plugins !== "object" || Array.isArray(ctx.config.plugins)) {
-			ctx.config.plugins = { allow: [installed] };
-			return;
-		}
-		const pluginsMap = ctx.config.plugins;
-		const rawAllow = pluginsMap.allow;
-		const original = Array.isArray(rawAllow) ? rawAllow : [];
-		const stringAllow = original.filter((e) => typeof e === "string");
-		if (LARK_PLUGIN_NAMES.some((name) => stringAllow.includes(name))) return;
-		original.push(installed);
-		pluginsMap.allow = original;
-	}
-};
-LarkPluginAllowRule = __decorate([Rule({
-	key: "lark_plugin_allow",
-	description: "当飞书插件（openclaw-lark 或旧版名）已在磁盘安装但未加入 plugins.allow 时，自动添加",
-	dependsOn: ["config_syntax_check"],
-	repairMode: "standard",
-	level: "critical"
-})], LarkPluginAllowRule);
-function getAllow(config) {
-	const plugins = config.plugins;
-	if (plugins == null || typeof plugins !== "object" || Array.isArray(plugins)) return [];
-	const allow = plugins.allow;
-	if (!Array.isArray(allow)) return [];
-	return allow.filter((e) => typeof e === "string");
-}
-/**
-* fs-only 检测：`<extDir>/<name>/package.json` 存在即视为已装。
-* 优先级 openclaw-lark（新版）> feishu-openclaw-plugin（legacy）。
-* 不读 package.json 内容，只判存在性，避开 JSON 损坏。
-*/
-function detectInstalledLarkPlugin(extDir) {
-	for (const name of LARK_PLUGIN_NAMES) if (pluginPackageJsonExists(extDir, name)) return name;
+function detectInstalledLarkPlugin$1(extDir) {
+	for (const name of LARK_PLUGIN_DIR_NAMES) if (pluginPackageJsonExists(extDir, name)) return name;
 	return null;
 }
 function pluginPackageJsonExists(extDir, pluginDir) {
@@ -3756,19 +3337,12 @@ function cleanupLegacyResiduals(ctx) {
 		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;
+		try {
+			rmrfTolerant(target);
+		} catch (e) {
+			console.error(`[feishu_plugin_state_normalize] rmrf ${target} failed: ${e.message}`);
+		}
+	}
 }
 //#endregion
 //#region src/version-compat.ts
@@ -3873,10 +3447,6 @@ function coerceCalVer(v) {
 function compareCalVer(a, b) {
 	return semver.default.compare(coerceCalVer(a), coerceCalVer(b));
 }
-/** 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);
-}
 /**
 * Infer the effective upper bound for a compat entry that has no explicit maxOpenclawVersion.
 *
@@ -3899,316 +3469,765 @@ function inferEffectiveMax(index) {
 	};
 }
 /**
-* Full version compatibility check that infers the effective maxOpenclawVersion for
-* entries that only define minOpenclawVersion.
+* 对一个**已对标到 VERSION_COMPAT_MAP 键**的版本评估其与 openclaw 的兼容性，
+* 并在不兼容时给出方向。fork 的 pin、legacy 分类等在 `checkPluginCompat` 处理，
+* 本函数只负责「版本 × openclaw 区间」这一段唯一逻辑。
+*
+* - index === -1（插件版本比全表都旧，无 floor 条目）→ 无区间可判，视为插件过旧 → 'lark'
+* - oc < entry.minOpenclawVersion → 'openclaw'
+* - oc ≥ 推断/显式上界 → 'lark'
+* - 否则兼容
+*
+* 上界语义：显式 maxOpenclawVersion 为 INCLUSIVE；推断上界为 EXCLUSIVE。
+*/
+function evaluateVersionRange(pluginVersion, openclawVersion) {
+	const index = VERSION_COMPAT_MAP.findIndex((e) => compareCalVer(e.openclawLarkVersion, pluginVersion) <= 0);
+	if (index === -1) return {
+		compatible: false,
+		direction: "lark",
+		entry: void 0
+	};
+	const entry = VERSION_COMPAT_MAP[index];
+	const oc = coerceCalVer(openclawVersion);
+	if (semver.default.lt(oc, coerceCalVer(entry.minOpenclawVersion))) return {
+		compatible: false,
+		direction: "openclaw",
+		entry
+	};
+	const maxInfo = inferEffectiveMax(index);
+	if (maxInfo) {
+		const max = coerceCalVer(maxInfo.max);
+		if (maxInfo.exclusive ? !semver.default.lt(oc, max) : semver.default.gt(oc, max)) return {
+			compatible: false,
+			direction: "lark",
+			entry
+		};
+	}
+	return {
+		compatible: true,
+		direction: null,
+		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 match: find the entry with the largest openclawLarkVersion that is
+* ≤ pluginVersion ("closest lower-or-equal version").
+*
+* The table is sorted descending, so the first entry whose version ≤
+* pluginVersion is the answer. Returns undefined only when pluginVersion
+* is older than every entry in the table.
+*/
+function findClosestEntry(pluginVersion) {
+	return VERSION_COMPAT_MAP.find((e) => compareCalVer(e.openclawLarkVersion, pluginVersion) <= 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/feishu-plugin-version-compat.ts
+const LEGACY_SHORT_NAMES = [LEGACY_LARK_PLUGIN_NAME];
+let _ocVersion = void 0;
+function getOcVersion() {
+	if (_ocVersion === void 0) _ocVersion = readOpenclawRuntimeVersion();
+	return _ocVersion;
+}
+const _installedCache = /* @__PURE__ */ new Map();
+function getInstalledPlugin(ctx) {
+	if (!_installedCache.has(ctx.configPath)) _installedCache.set(ctx.configPath, detectInstalledLarkPlugin(ctx));
+	return _installedCache.get(ctx.configPath);
+}
+/** 提取公共前置上下文；任何前置条件不满足时返回 null（规则 pass）。 */
+function resolveCompatContext(ctx) {
+	const ocCur = getOcVersion();
+	if (!ocCur) return null;
+	const installed = getInstalledPlugin(ctx);
+	if (installed == null) return null;
+	const compatResult = checkPluginCompat(pluginIdentifier(installed), installed.version, ocCur);
+	return {
+		ocCur,
+		installed,
+		isLegacy: isLegacyPlugin(installed),
+		compatResult
+	};
+}
+/**
+* 飞书插件与当前 openclaw 不兼容，且「升级 openclaw 有望转兼容」时 → 提示调整 openclaw。
+*
+* 判定顺序：
+*   1. 无 recommendedOpenclawTag（如 doctor 模式无目标）→ 前置短路 pass，连兼容性都不判
+*      （upgrade_openclaw 语义是「升到推荐目标」，没有目标就无从建议）。
+*   2. checkPluginCompat 判为兼容 → pass。
+*   3. 不兼容时只比较 ocCur 与 recommendedOc：仅当 ocCur < recommendedOc（升 openclaw 能拉到
+*      更高版本、有望满足插件要求）才报 upgrade_openclaw；ocCur ≥ recommendedOc 说明升 openclaw
+*      无益，交由 Rule 2 报 upgrade_lark。
+*
+*/
+let FeishuPluginOpenclawUpgradeRule = class FeishuPluginOpenclawUpgradeRule extends DiagnoseRule {
+	validate(ctx) {
+		const recommendedOc = ctx.vars.recommendedOpenclawTag;
+		if (!recommendedOc) return { pass: true };
+		const cc = resolveCompatContext(ctx);
+		if (!cc) return { pass: true };
+		const { ocCur, installed, isLegacy, compatResult } = cc;
+		if (compatResult.compatible) return { pass: true };
+		if (compareCalVer(ocCur, recommendedOc) >= 0) return { pass: true };
+		return {
+			pass: false,
+			action: "upgrade_openclaw",
+			message: `${buildCompatPrefix(installed, ocCur, isLegacy)}；将 openclaw 升级到 ${recommendedOc} 即可满足（飞书插件随之同步）`
+		};
+	}
+};
+FeishuPluginOpenclawUpgradeRule = __decorate([Rule({
+	key: "feishu_plugin_version_compat_openclaw",
+	description: "检查飞书插件是否要求更高版本的 openclaw；是则提示升级 openclaw",
+	dependsOn: ["config_syntax_check"],
+	repairMode: "user-confirm",
+	level: "critical",
+	usesVars: ["recommendedOpenclawTag"]
+})], FeishuPluginOpenclawUpgradeRule);
+/**
+* 飞书插件与当前 openclaw 不兼容 → 提示调整飞书插件（重装 / 换版本，含 legacy 旧包替换）。
+*
+* 仅判断兼容性，不依赖 recommendedOc：compatResult.compatible 为真 → pass，否则 → upgrade_lark。
+*
+* 与 Rule 1 的协作靠 dependsOn（LOAD-BEARING，非仅排序）：当「不兼容且 ocCur < recommendedOc」时
+* Rule 1 先报 upgrade_openclaw 并失败，dependsOn 使本规则被跳过，避免对同一不兼容同时报两个动作；
+* 其余不兼容场景（ocCur ≥ recommendedOc / 无推荐目标）Rule 1 pass，本规则如实报 upgrade_lark。
+* （--rule=lark 单独运行不经 Rule 1，会对任何不兼容直接报 upgrade_lark。）
+*/
+let FeishuPluginLarkUpgradeRule = class FeishuPluginLarkUpgradeRule extends DiagnoseRule {
+	validate(ctx) {
+		const cc = resolveCompatContext(ctx);
+		if (!cc) return { pass: true };
+		const { ocCur, installed, isLegacy, compatResult } = cc;
+		if (compatResult.compatible) return { pass: true };
+		return {
+			pass: false,
+			action: "upgrade_lark",
+			message: `${buildCompatPrefix(installed, ocCur, isLegacy)}；需要将飞书插件安装/升级到与当前 openclaw 兼容的版本`
+		};
+	}
+};
+FeishuPluginLarkUpgradeRule = __decorate([Rule({
+	key: "feishu_plugin_version_compat_lark",
+	description: "检查飞书插件版本是否落后于当前 openclaw；是则提示升级飞书插件",
+	dependsOn: ["config_syntax_check", "feishu_plugin_version_compat_openclaw"],
+	repairMode: "user-confirm",
+	level: "critical"
+})], FeishuPluginLarkUpgradeRule);
+/**
+* 传给 checkPluginCompat 的包标识：优先 package.json name（含 scope，用于识别 fork），
+* 退化到 plugins.allow 短名（legacy 旧包靠短名 feishu-openclaw-plugin 识别）。
+*/
+function pluginIdentifier(p) {
+	return p.fullName ?? p.allowName;
+}
+function isLegacyPlugin(p) {
+	return LEGACY_SHORT_NAMES.includes(p.allowName);
+}
+function buildCompatPrefix(installed, ocCur, isLegacy) {
+	const desc = describePlugin(installed);
+	if (isLegacy) return `检测到已弃用的旧包 ${desc}（包名 "${installed.allowName}" 已停止维护，需替换为 "openclaw-lark"）`;
+	return `飞书插件 ${desc} 与当前 openclaw@${ocCur} 不兼容（${describeCompatConstraint(installed.version ? findClosestEntry(installed.version) : void 0, installed.version)}）`;
+}
+function describeCompatConstraint(entry, pluginVersion) {
+	if (!entry) return `插件版本 ${pluginVersion ?? "未知"} 不在版本兼容表中`;
+	if (entry.maxOpenclawVersion) return `该插件版本要求 openclaw ∈ [${entry.minOpenclawVersion}, ${entry.maxOpenclawVersion}]`;
+	return `该插件版本要求 openclaw ≥ ${entry.minOpenclawVersion}`;
+}
+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 detectInstalledLarkPlugin(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 [LARK_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]);
+		return {
+			allowName: name,
+			fullName: pkg.name ?? extractScopedNameFromSpec$1(installEntry?.spec),
+			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$1(spec) {
+	if (typeof spec !== "string") return void 0;
+	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);
+	if (!cc) return false;
+	return !cc.compatResult.compatible;
+}
+//#endregion
+//#region src/paths.ts
+/**
+* Central directory for all ephemeral diagnose/reset artifacts: task status
+* files (`reset-<taskId>.json`) and human-readable step logs
+* (`reset-<taskId>.log`). Having everything under one dir makes debugging a
+* stuck reset much easier — `ls /tmp/openclaw-diagnose/` shows every recent
+* run, and each run's log is right next to its state.
+*/
+const DIAGNOSE_DIR = "/tmp/openclaw-diagnose";
+function resetResultFile(taskId) {
+	return `${DIAGNOSE_DIR}/reset-${taskId}.json`;
+}
+function resetLogFile(taskId) {
+	return `${DIAGNOSE_DIR}/reset-${taskId}.log`;
+}
+/** Sandbox workspace root where openclaw config + agent state lives. */
+const WORKSPACE_DIR = "/home/gem/workspace/agent";
+/** File containing the provider key used by the openclaw miaoda provider. */
+const PROVIDER_FILE_PATH = "/home/gem/workspace/.force/openclaw/miaoda-provider-key";
+/** File containing the miaoda openclaw secrets JSON. */
+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 场景专属修复状态的信号文件目录。
+* fixStatus 有值时在此目录下创建同名文件（如 /tmp/event/PORT_FIX_READY），
+* 文件内容为完整的 UpgradeLarkResult JSON，供外部进程轮询感知升级结果。
+*/
+const FIX_EVENT_DIR = "/tmp/event";
+/**
+* 安装指令互斥锁文件路径。
+* upgrade-lark / install-openclaw / install-extension / install-cli / reset --worker
+* 共享此锁，同一时刻只允许一个安装指令运行。
+* 锁文件内容：{ pid, command, startedAt }。
+*/
+const INSTALL_LOCK_FILE = `${DIAGNOSE_DIR}/install.lock`;
+/**
+* upgrade-lark 每次运行的日志文件路径，含时间戳便于按时间排序定位。
+* checkOnly=true 时文件名含 "-check" 后缀，便于与正式安装日志区分。
+*/
+function upgradeLarkLogFile(runId, checkOnly = false) {
+	const ts = (/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replace(/:/g, "-");
+	return `${DIAGNOSE_DIR}/upgrade-lark${checkOnly ? "-check" : ""}-${ts}-${runId.slice(0, 8)}.log`;
+}
+//#endregion
+//#region src/lark-cli-init.ts
+const PE_XML_TAG = "lark-cli-pe";
+const PE_PLACEHOLDER = `
+<${PE_XML_TAG}>
+**【强制要求 - 无例外】飞书所有操作必须先读 feishu-lark-cli skill。未读skill不得调用任何飞书工具，违者视为操作失误。**
+</${PE_XML_TAG}>
+`;
+function isLarkPluginInstalled(configPath) {
+	const extDir = getExtensionsDir(configPath);
+	return LARK_PLUGIN_DIR_NAMES.some((name) => {
+		try {
+			return node_fs.default.existsSync(node_path.default.join(extDir, name, "package.json"));
+		} catch {
+			return false;
+		}
+	});
+}
+function isLarkCliAvailable$2() {
+	try {
+		return (0, node_child_process.spawnSync)("lark-cli", ["--version"], {
+			encoding: "utf-8",
+			timeout: 5e3,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).status === 0;
+	} catch {
+		return false;
+	}
+}
+function readConfig(configPath) {
+	try {
+		const raw = node_fs.default.readFileSync(configPath, "utf-8");
+		const parsed = loadJSON5().parse(raw);
+		return parsed != null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Resolve the feishu app secret for the given appId.
 *
-* For entries with an explicit maxOpenclawVersion the upper bound is INCLUSIVE (existing
-* semantics). For entries without one the upper bound is EXCLUSIVE — it is derived from
-* the minOpenclawVersion of the next entry group that requires a higher openclaw version.
+* Lookup order:
+*   1. channels.feishu.appSecret  (single-agent: feishu.appId === appId)
+*   2. channels.feishu.accounts[key].appSecret  (multi-agent: account.appId === appId)
 *
-* Example: openclaw-lark@2026.4.10 (min=2026.4.27, no explicit max) gets an inferred
-* exclusive max of '2026.5.6', so openclaw@2026.5.7 is correctly detected as incompatible
-* whereas the old compatible() call would have returned true.
-*/
-function effectiveCompatible(pluginVersion, openclawVersion) {
-	const index = VERSION_COMPAT_MAP.findIndex((e) => compareCalVer(e.openclawLarkVersion, pluginVersion) <= 0);
-	if (index === -1) return false;
-	const entry = VERSION_COMPAT_MAP[index];
-	const oc = coerceCalVer(openclawVersion);
-	if (semver.default.lt(oc, coerceCalVer(entry.minOpenclawVersion))) return false;
-	const maxInfo = inferEffectiveMax(index);
-	if (!maxInfo) return true;
-	const max = coerceCalVer(maxInfo.max);
-	return maxInfo.exclusive ? semver.default.lt(oc, max) : !semver.default.gt(oc, max);
-}
-/**
-* Fork plugin handling.
+* Value interpretation:
+*   - string  → use directly
+*   - object  → secret is managed by a provider; use `feishuAppSecret` param instead
 *
-* `@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";
-/**
-* Resolve the version to evaluate against VERSION_COMPAT_MAP for a given plugin.
-* The fork is pinned to FORK_LARK_PLUGIN_PINNED_VERSION regardless of its own
-* version; everything else uses its real version.
+* Returns null when the secret cannot be determined.
 */
-function resolveCompatVersion(packageName, version) {
-	if (packageName === "@lark-apaas/openclaw-lark") return FORK_LARK_PLUGIN_PINNED_VERSION;
-	return version;
+function resolveAppSecret(appId, config, feishuAppSecret) {
+	const feishu = getNestedMap(config, "channels", "feishu");
+	if (!feishu) return null;
+	let rawSecret;
+	if (typeof feishu.appId === "string" && feishu.appId === appId) rawSecret = feishu.appSecret;
+	else {
+		const accounts = asRecord(feishu.accounts);
+		if (accounts) for (const [, val] of Object.entries(accounts)) {
+			const account = asRecord(val);
+			if (account?.appId === appId) {
+				rawSecret = account.appSecret ?? feishu.appSecret;
+				break;
+			}
+		}
+	}
+	if (typeof rawSecret === "string" && rawSecret) return rawSecret;
+	if (rawSecret != null && typeof rawSecret === "object") return feishuAppSecret ?? null;
+	return null;
 }
 /**
-* Floor match: find the entry with the largest openclawLarkVersion that is
-* ≤ pluginVersion ("closest lower-or-equal version").
+* Resolve the agents.md path for the given appId from the openclaw config.
 *
-* The table is sorted descending, so the first entry whose version ≤
-* pluginVersion is the answer. Returns undefined only when pluginVersion
-* is older than every entry in the table.
-*/
-function findClosestEntry(pluginVersion) {
-	return VERSION_COMPAT_MAP.find((e) => compareCalVer(e.openclawLarkVersion, pluginVersion) <= 0);
-}
-//#endregion
-//#region src/rules/feishu-plugin-version-compat.ts
-const LEGACY_SHORT_NAMES = [LEGACY_LARK_PLUGIN_NAME];
-const FORK_SCOPES = [FORK_LARK_PLUGIN_SCOPE];
-/**
-* fork 版兼容区间的下界，取自 VERSION_COMPAT_MAP 中 openclawLarkVersion=2026.4.1
-* 的 minOpenclawVersion，避免与映射表脱钩写死。仅用于区分升级方向
-* （oc 低于下界 → 升 openclaw；高于上界 → 升 lark）；该条目被移除时回退到已知值。
+* Case 1: appId matches channels.feishu.appId (single-agent path)
+*   → WORKSPACE_DIR/AGENTS.md
+*
+* Case 2: appId found in channels.feishu.accounts (multi-agent path)
+*   → find account key where account.appId === appId
+*   → find binding where match.channel=feishu && match.accountId=that key
+*   → if agentId === 'main'  → WORKSPACE_DIR/agents.md
+*   → else find agent in agents.list by id → agent.workspace/agents.md
+*
+* Returns null when the path cannot be determined.
 */
-const FORK_LARK_PLUGIN_MIN_OC_VERSION = findEntry("2026.4.1")?.minOpenclawVersion ?? "2026.3.28";
-let _ocVersion = void 0;
-function getOcVersion() {
-	if (_ocVersion === void 0) _ocVersion = readOpenclawRuntimeVersion();
-	return _ocVersion;
+function resolveAgentsMdPath(appId, config) {
+	const feishu = getNestedMap(config, "channels", "feishu");
+	if (!feishu) {
+		console.error("resolveAgentsMdPath: channels.feishu not found");
+		return null;
+	}
+	if (typeof feishu.appId === "string" && feishu.appId === appId) {
+		console.error(`resolveAgentsMdPath: case=single-agent feishu.appId=${feishu.appId}`);
+		return node_path.default.join(WORKSPACE_DIR, "workspace", "AGENTS.md");
+	}
+	const accounts = asRecord(feishu.accounts);
+	if (!accounts) {
+		console.error("resolveAgentsMdPath: feishu.accounts not found");
+		return null;
+	}
+	let accountId;
+	for (const [key, val] of Object.entries(accounts)) if (asRecord(val)?.appId === appId) {
+		accountId = key;
+		break;
+	}
+	if (!accountId) {
+		console.error(`resolveAgentsMdPath: no account found with appId=${appId} in feishu.accounts keys=[${Object.keys(accounts).join(",")}]`);
+		return null;
+	}
+	console.error(`resolveAgentsMdPath: found accountId=${accountId}`);
+	const bindings = Array.isArray(config.bindings) ? config.bindings : [];
+	let agentId;
+	for (const b of bindings) {
+		const binding = asRecord(b);
+		if (!binding) continue;
+		const match = asRecord(binding.match);
+		if (match?.channel === "feishu" && match?.accountId === accountId) {
+			if (typeof binding.agentId === "string") {
+				agentId = binding.agentId;
+				break;
+			}
+		}
+	}
+	if (!agentId) {
+		console.error(`resolveAgentsMdPath: no binding found for accountId=${accountId} in bindings(count=${bindings.length})`);
+		return null;
+	}
+	console.error(`resolveAgentsMdPath: found agentId=${agentId}`);
+	if (agentId === "main") {
+		console.error("resolveAgentsMdPath: case=multi-agent-main");
+		return node_path.default.join(WORKSPACE_DIR, "workspace", "AGENTS.md");
+	}
+	const agentsObj = asRecord(config.agents);
+	const list = Array.isArray(agentsObj?.list) ? agentsObj.list : [];
+	for (const a of list) {
+		const agent = asRecord(a);
+		if (agent?.id === agentId) {
+			const ws = typeof agent.workspace === "string" ? agent.workspace : node_path.default.join(WORKSPACE_DIR, "workspace");
+			console.error(`resolveAgentsMdPath: case=multi-agent-custom agentId=${agentId} workspace=${ws}`);
+			return node_path.default.join(ws, "AGENTS.md");
+		}
+	}
+	console.error(`resolveAgentsMdPath: agentId=${agentId} not found in agents.list(count=${list.length})`);
+	return null;
 }
-const _installedCache = /* @__PURE__ */ new Map();
-function getInstalledPlugin(ctx) {
-	if (!_installedCache.has(ctx.configPath)) _installedCache.set(ctx.configPath, detectInstalledPlugin(ctx));
-	return _installedCache.get(ctx.configPath);
+function appendPeToAgentsMd(agentsMdPath) {
+	const dir = node_path.default.dirname(agentsMdPath);
+	if (!node_fs.default.existsSync(dir)) node_fs.default.mkdirSync(dir, { recursive: true });
+	const existing = node_fs.default.existsSync(agentsMdPath) ? node_fs.default.readFileSync(agentsMdPath, "utf-8") : "";
+	if (existing.includes(`<lark-cli-pe>`)) {
+		console.error(`lark-cli-init: <${PE_XML_TAG}> already present in ${agentsMdPath}, skipping`);
+		return;
+	}
+	const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+	node_fs.default.appendFileSync(agentsMdPath, `${sep}${PE_PLACEHOLDER}`, "utf-8");
+	console.error(`lark-cli-init: appended PE placeholder to ${agentsMdPath}`);
 }
 /**
-* 解析升级方向。返回 null 表示当前状态无需任何升级。
-*
-* - isVersionCompatible → null（兼容）
-* - isRecommendedBelowEntryMin → null（推荐版本未到位，豁免）
-* - ocCur < recommendedOc → 'openclaw'
-* - ocCur ≥ recommendedOc → 'lark'
+* Collect every Feishu bot appId declared in the openclaw config.
+* Covers both single-agent (channels.feishu.appId) and multi-agent
+* (channels.feishu.accounts[*].appId) layouts. Returns a deduplicated list.
 */
-function resolveUpgradeDirection(installed, ocCur, recommendedOc, isLegacy) {
-	if (!isLegacy && isVersionCompatible(installed, ocCur)) return null;
-	if (!isLegacy && isRecommendedBelowEntryMin(installed, recommendedOc)) return null;
-	return compareCalVer(ocCur, recommendedOc) < 0 ? "openclaw" : "lark";
+function collectFeishuAppIds(configPath) {
+	const config = readConfig(configPath ?? CONFIG_PATH);
+	if (!config) return [];
+	const feishu = getNestedMap(config, "channels", "feishu");
+	if (!feishu) return [];
+	const appIds = /* @__PURE__ */ new Set();
+	const topAppId = feishu.appId;
+	if (typeof topAppId === "string" && topAppId.trim()) appIds.add(topAppId.trim());
+	const accounts = asRecord(feishu.accounts);
+	if (accounts) for (const val of Object.values(accounts)) {
+		const appId = asRecord(val)?.appId;
+		if (typeof appId === "string" && appId.trim()) appIds.add(appId.trim());
+	}
+	return [...appIds];
 }
-/** 提取公共前置上下文；任何前置条件不满足时返回 null（规则 pass）。 */
-function resolveCompatContext(ctx) {
-	const recommendedOc = ctx.vars.recommendedOpenclawTag;
-	const ocCur = getOcVersion();
-	if (!ocCur) return null;
-	const installed = getInstalledPlugin(ctx);
-	if (installed == null) return null;
+function runLarkCliInit(opts) {
+	const configPath = opts.configPath ?? CONFIG_PATH;
+	if (!isLarkPluginInstalled(configPath)) {
+		console.error("lark-cli-init: skipping — openclaw-lark plugin not installed");
+		return {
+			ok: true,
+			skipped: true,
+			skipReason: "openclaw-lark plugin not installed"
+		};
+	}
+	if (!isLarkCliAvailable$2()) {
+		console.error("lark-cli-init: skipping — lark-cli command not found");
+		return {
+			ok: true,
+			skipped: true,
+			skipReason: "lark-cli command not found"
+		};
+	}
+	const config = readConfig(configPath);
+	if (!config) return {
+		ok: false,
+		error: `could not read config at ${configPath}`
+	};
+	const agentsMdPath = resolveAgentsMdPath(opts.appId, config);
+	console.error(`lark-cli-init: resolved agents.md path=${agentsMdPath ?? "(null)"}`);
+	if (!agentsMdPath) return {
+		ok: false,
+		error: `could not resolve agents.md path for appId=${opts.appId}`
+	};
+	const appSecret = resolveAppSecret(opts.appId, config, opts.feishuAppSecret);
+	if (!appSecret) return {
+		ok: false,
+		error: `could not resolve appSecret for appId=${opts.appId}`
+	};
+	console.error(`lark-cli-init: running lark-cli config init --name ${opts.appId} --app-id ${opts.appId} --brand feishu --app-secret-stdin --force-init`);
+	const initRes = (0, node_child_process.spawnSync)("lark-cli", [
+		"config",
+		"init",
+		"--name",
+		opts.appId,
+		"--app-id",
+		opts.appId,
+		"--brand",
+		"feishu",
+		"--app-secret-stdin",
+		"--force-init"
+	], {
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		encoding: "utf-8",
+		input: appSecret
+	});
+	const configInitStdout = initRes.stdout?.trim() || void 0;
+	const configInitStderr = initRes.stderr?.trim() || void 0;
+	if (configInitStdout) console.error(`lark-cli config init stdout: ${configInitStdout}`);
+	if (configInitStderr) console.error(`lark-cli config init stderr: ${configInitStderr}`);
+	if (initRes.error) return {
+		ok: false,
+		configInitStdout,
+		configInitStderr,
+		error: `lark-cli config init spawn error: ${initRes.error.message}`
+	};
+	if (initRes.status !== 0) return {
+		ok: false,
+		configInitExitCode: initRes.status ?? void 0,
+		configInitStdout,
+		configInitStderr,
+		error: `lark-cli config init exited with code ${initRes.status}`
+	};
+	appendPeToAgentsMd(agentsMdPath);
 	return {
-		ocCur,
-		recommendedOc,
-		installed,
-		isLegacy: isLegacyPlugin(installed)
+		ok: true,
+		configInitExitCode: 0,
+		agentsMdPath
 	};
 }
+//#endregion
+//#region src/utils/feishu-tools-deny.ts
 /**
-* 检测是否需要升级 openclaw：
-*   - fork 版（@lark-apaas/openclaw-lark）低于最低要求 → upgrade_openclaw
-*   - legacy / 官方版不兼容且 ocCur < recommendedOc → upgrade_openclaw
-*/
-let FeishuPluginOpenclawUpgradeRule = class FeishuPluginOpenclawUpgradeRule extends DiagnoseRule {
-	validate(ctx) {
-		const cc = resolveCompatContext(ctx);
-		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,
-			action: "upgrade_openclaw",
-			message: `${buildCompatPrefix(installed, ocCur, isLegacy)}；将 openclaw 升级到 ${recommendedOc}，飞书插件会随之同步升级`
-		};
-	}
-};
-FeishuPluginOpenclawUpgradeRule = __decorate([Rule({
-	key: "feishu_plugin_version_compat_openclaw",
-	description: "检查飞书插件是否要求更高版本的 openclaw；是则提示升级 openclaw",
-	dependsOn: ["config_syntax_check"],
-	repairMode: "user-confirm",
-	level: "critical",
-	usesVars: ["recommendedOpenclawTag"]
-})], FeishuPluginOpenclawUpgradeRule);
-/**
-* 检测是否需要升级飞书插件（仅在 Rule 1 pass 后执行）：
-*   - fork 版已由 Rule 1 处理，这里直接 pass
-*   - legacy / 官方版不兼容且 ocCur ≥ recommendedOc → upgrade_lark
-*/
-let FeishuPluginLarkUpgradeRule = class FeishuPluginLarkUpgradeRule extends DiagnoseRule {
-	validate(ctx) {
-		const cc = resolveCompatContext(ctx);
-		if (!cc) return { pass: true };
-		const { ocCur, recommendedOc, installed, isLegacy } = cc;
-		if (isForkPlugin(installed)) {
-			if (installed.fullName !== "@lark-apaas/openclaw-lark") return { pass: true };
-			if (resolveForkUpgradeDirection(ocCur) !== "lark") return { pass: true };
-			return {
-				pass: false,
-				action: "upgrade_lark",
-				message: `飞书插件 ${describePlugin(installed)}（fork 版，对标 openclaw-lark@${FORK_LARK_PLUGIN_PINNED_VERSION}）与当前 openclaw@${ocCur} 不兼容；建议升级飞书插件至兼容版本`
-			};
-		}
-		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: `${prefix}；当前 openclaw@${ocCur} 已达推荐版本，可直接升级飞书插件`
-		};
-	}
-};
-FeishuPluginLarkUpgradeRule = __decorate([Rule({
-	key: "feishu_plugin_version_compat_lark",
-	description: "检查飞书插件版本是否落后于当前 openclaw；是则提示升级飞书插件",
-	dependsOn: ["config_syntax_check", "feishu_plugin_version_compat_openclaw"],
-	repairMode: "user-confirm",
-	level: "critical",
-	usesVars: ["recommendedOpenclawTag"]
-})], FeishuPluginLarkUpgradeRule);
-/**
-* 核心判断：非 fork 插件是否需要升级 lark，基于当前 openclaw 版本的兼容性。
+* openclaw-lark 中与 lark-cli 功能重叠的工具，写入 channels.feishu.tools.deny 后
+* 由 openclaw-lark 插件自身的 shouldRegisterTool() 跳过注册，避免与 lark-cli 重复。
+* 支持尾部 `*` 通配（openclaw-lark matchesAnyPattern 识别）。
 *
-* 被 FeishuPluginLarkUpgradeRule.validate 和 needsLarkUpgrade 共用。
-* 调用方需在调用前自行处理 fork 插件的情况（fork 插件不走本函数）。
+* 保留（IM / 鉴权 / 诊断类，与 lark-cli 无重叠）：feishu_chat*、feishu_get_user、
+* feishu_search_user、feishu_im_*、feishu_oauth*、feishu_auth、feishu_diagnose、feishu_doctor。
 *
-* - 有 recommendedOc：走 resolveUpgradeDirection 判断方向是否为 'lark'
-* - 无 recommendedOc（doctor 无推荐版本）：legacy 插件直接需要升级；
-*   非 legacy 则检查当前版本是否在兼容表内
+* install-cli（安装 lark-cli 后即时写）与 agents_md_lark_cli_pe 规则（doctor --fix
+* 自愈）共用本常量与合并逻辑，单一来源。
 */
-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);
-}
-function isLegacyPlugin(p) {
-	return LEGACY_SHORT_NAMES.includes(p.allowName);
+const LARK_CLI_OVERLAP_TOOL_DENY = Object.freeze([
+	"feishu_create_doc",
+	"feishu_fetch_doc",
+	"feishu_update_doc",
+	"feishu_doc_comments",
+	"feishu_doc_media",
+	"feishu_drive_file",
+	"feishu_wiki_space",
+	"feishu_wiki_space_node",
+	"feishu_search_doc_wiki",
+	"feishu_bitable_*",
+	"feishu_calendar_*",
+	"feishu_task_*",
+	"feishu_sheet"
+]);
+/** 读取 channels.feishu.tools.deny 的字符串数组（缺失/非法时返回空数组）。 */
+function readDenyList(config) {
+	const deny = asRecord(asRecord(asRecord(config.channels)?.feishu)?.tools)?.deny;
+	return Array.isArray(deny) ? deny.filter((e) => typeof e === "string") : [];
 }
-/**
-* 检查已装插件版本与当前 openclaw 版本是否兼容。
-* 使用 effectiveCompatible() 以正确推断无显式 maxOpenclawVersion 条目的上界。
-*/
-function isVersionCompatible(p, ocCur) {
-	if (!p.version) return false;
-	return effectiveCompatible(p.version, ocCur);
+/** 返回 deny 列表中尚缺的重叠工具（用于 validate 判定）。 */
+function larkCliToolDenyMissing(config) {
+	const existing = new Set(readDenyList(config));
+	return LARK_CLI_OVERLAP_TOOL_DENY.filter((t) => !existing.has(t));
 }
 /**
-* 豁免判断：若推荐的 openclaw 版本本身低于最近条目要求的最低版本，
-* 说明兼容表超前于推荐版本，不应由用户承担升级责任，视为通过。
+* 确保 channels.feishu.tools.deny 含全部重叠工具（只增不删，幂等合并）。
+* 直接 mutate 传入的 config 对象；返回是否发生了变更。
 */
-function isRecommendedBelowEntryMin(p, recommendedOc) {
-	if (!p.version) return false;
-	const entry = findClosestEntry(p.version);
-	if (!entry) return false;
-	return compareCalVer(recommendedOc, entry.minOpenclawVersion) < 0;
-}
-function buildCompatPrefix(installed, ocCur, isLegacy) {
-	const desc = describePlugin(installed);
-	if (isLegacy) return `检测到已弃用的旧包 ${desc}（包名 "${installed.allowName}" 已停止维护，需替换为 "openclaw-lark"）`;
-	return `飞书插件 ${desc} 与当前 openclaw@${ocCur} 不兼容（${describeCompatConstraint(installed.version ? findClosestEntry(installed.version) : void 0, installed.version)}）`;
-}
-function describeCompatConstraint(entry, pluginVersion) {
-	if (!entry) return `插件版本 ${pluginVersion ?? "未知"} 不在版本兼容表中`;
-	if (entry.maxOpenclawVersion) return `该插件版本要求 openclaw ∈ [${entry.minOpenclawVersion}, ${entry.maxOpenclawVersion}]`;
-	return `该插件版本要求 openclaw ≥ ${entry.minOpenclawVersion}`;
+function ensureLarkCliToolDeny(config) {
+	if (larkCliToolDenyMissing(config).length === 0) return false;
+	const tools = ensureRecord(ensureRecord(ensureRecord(config, "channels"), "feishu"), "tools");
+	const existing = readDenyList(config);
+	tools.deny = [...new Set([...existing, ...LARK_CLI_OVERLAP_TOOL_DENY])];
+	return true;
 }
 /**
-* fork @lark-apaas/openclaw-lark 的升级方向：复用官方 effectiveCompatible，按对标版本
-* FORK_LARK_PLUGIN_PINNED_VERSION (2026.4.1) 取完整兼容区间。
-*   null       → 兼容
-*   'openclaw' → oc 低于区间下界，需升级 openclaw
-*   'lark'     → oc 高于区间上界（插件相对当前 openclaw 过旧），需升级飞书插件
+* 文件级：读 openclaw.json → 合并 deny（ensureLarkCliToolDeny）→ 原子回写。
+* 仅当确实有变更时才写盘；config 不存在或解析失败仅记日志、不抛。
+*
+* 调用方负责门控「何时该写 deny」（即 lark-cli 存在时）——本函数不做 lark-cli 探测，
+* 只做「把 deny 合并进配置文件」这一件事，供 install-cli / install-extension /
+* upgrade-lark 在装好 lark-cli 或 openclaw-lark 后调用。
+*
+* @returns 是否发生了写盘
 */
-function resolveForkUpgradeDirection(ocCur) {
-	if (effectiveCompatible("2026.4.1", ocCur)) return null;
-	return compareCalVer(ocCur, FORK_LARK_PLUGIN_MIN_OC_VERSION) < 0 ? "openclaw" : "lark";
+function ensureLarkCliToolDenyInFile(configPath, log = () => {}) {
+	if (!node_fs.default.existsSync(configPath)) {
+		log(`tools.deny: config not found at ${configPath} — skip`);
+		return false;
+	}
+	try {
+		const config = loadJSON5().parse(node_fs.default.readFileSync(configPath, "utf-8"));
+		if (!ensureLarkCliToolDeny(config)) {
+			log("tools.deny: already up to date");
+			return false;
+		}
+		const tmp = configPath + ".lark-cli-deny-tmp";
+		node_fs.default.writeFileSync(tmp, JSON.stringify(config, null, 2), "utf-8");
+		moveSafe(tmp, configPath);
+		log("channels.feishu.tools.deny updated");
+		return true;
+	} catch (e) {
+		log(`WARN: ensure tools.deny failed: ${e.message}`);
+		return false;
+	}
 }
+//#endregion
+//#region src/utils/lark-cli-detect.ts
 /**
-* @lark-apaas/openclaw-lark 复用官方 effectiveCompatible（按对标版本 2026.4.1 完整区间）。
-* 本函数（Rule 1）只负责 openclaw 方向（oc 低于下界）；oc 高于上界由 Rule 2 报 upgrade_lark。
-* 其他 @lark-apaas scope 的 fork 插件继续无条件 pass。
-* recommendedOc 可为 undefined（doctor 模式），此时不指定目标升级版本。
+* 探测 lark-cli 是否可用（`lark-cli --version` 退出码为 0）。
+* 多条规则共用同一判定：feishu_plugin_state_normalize（是否补 feishu_* 授权）、
+* agents_md_lark_cli_pe（是否补 PE / deny）等。
 */
-function validateForkPlugin(installed, ocCur, recommendedOc) {
-	if (installed.fullName !== "@lark-apaas/openclaw-lark") return { pass: true };
-	if (resolveForkUpgradeDirection(ocCur) !== "openclaw") 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} 低于此要求${recommendation}`
-	};
-}
-function describePlugin(p) {
-	return (p.fullName ?? p.allowName) + (p.version ? `@${p.version}` : "");
-}
-function readPluginPackageJson(filePath) {
+function isLarkCliAvailable$1() {
 	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
-		};
+		return (0, node_child_process.spawnSync)("lark-cli", ["--version"], {
+			encoding: "utf-8",
+			timeout: 5e3,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).status === 0;
 	} catch {
-		return null;
+		return false;
 	}
 }
-/** "已装" = 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 [LARK_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$1(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;
+//#endregion
+//#region src/rules/agents-md-lark-cli-pe.ts
+/** 会注册 feishu_* 工具的三种飞书插件：官方 / 旧版 / 内置。 */
+const FEISHU_PLUGIN_NAMES = [
+	LARK_PLUGIN_NAME,
+	LEGACY_LARK_PLUGIN_NAME,
+	BUILTIN_FEISHU_PLUGIN_NAME
+];
+/**
+* 任一飞书插件是否在 config 中**启用**（plugins.entries[name].enabled === true）。
+* deny 的意义在于「有飞书插件会注册 feishu_* 工具」，故按启用判定——不看是否落盘安装：
+* 启用的可能是官方 openclaw-lark、旧版 feishu-openclaw-plugin 或内置 feishu 中的任意一个。
+*/
+function isAnyFeishuPluginEnabled(config) {
+	const entries = getNestedMap(config, "plugins", "entries");
+	return FEISHU_PLUGIN_NAMES.some((name) => asRecord(entries?.[name])?.enabled === true);
 }
-/** "@scope/name@1.2.3" / "name@1.2.3" / "@scope/name" / "name" → 去掉 @version 后缀 */
-function extractScopedNameFromSpec$1(spec) {
-	if (typeof spec !== "string") return void 0;
-	const at = spec.indexOf("@", 1);
-	return at === -1 ? spec : spec.slice(0, at);
+/** 第一个缺失 PE 内容的 AGENTS.md 路径；无则 undefined。 */
+function findAgentsMdMissingPe(ctx) {
+	return collectExistingAgentsMdPaths(ctx).find((filePath) => {
+		return !node_fs.default.readFileSync(filePath, "utf-8").includes(`<${PE_XML_TAG}>`);
+	});
 }
 /**
-* 判断已安装的飞书插件是否与当前 openclaw 版本不兼容（或为需要替换的 legacy 插件）。
-* 被 upgrade-lark 前置检测门控（--check-only 和正式安装模式）调用。
+* lark-cli 存在时统一规范化环境：
+*   1. 给各智能体 AGENTS.md 追加 lark-cli-pe PE 内容
+*   2. 有飞书插件启用时，把与 lark-cli 重叠的工具写入 channels.feishu.tools.deny
+*      （只增不删，避免与 lark-cli 重复注册）
+* 两者门禁同为「lark-cli 可用」，故合并为一条规则。
 */
-function needsLarkUpgrade(ctx) {
-	const cc = resolveCompatContext({
-		...ctx,
-		vars: {
-			...ctx.vars,
-			recommendedOpenclawTag: void 0
+let AgentsMdLarkCliPeRule = class AgentsMdLarkCliPeRule extends DiagnoseRule {
+	validate(ctx) {
+		if (!isLarkCliAvailable$1()) return { pass: true };
+		const missingPath = findAgentsMdMissingPe(ctx);
+		if (missingPath) return {
+			pass: false,
+			message: `${missingPath} 中缺少 lark-cli-pe PE 内容，需要追加`
+		};
+		if (isAnyFeishuPluginEnabled(ctx.config) && larkCliToolDenyMissing(ctx.config).length > 0) return {
+			pass: false,
+			message: "channels.feishu.tools.deny 缺少与 lark-cli 重叠的飞书工具，需要补充"
+		};
+		return { pass: true };
+	}
+	repair(ctx) {
+		if (!isLarkCliAvailable$1()) return;
+		for (const filePath of collectExistingAgentsMdPaths(ctx)) {
+			const content = node_fs.default.readFileSync(filePath, "utf-8");
+			if (content.includes(`<lark-cli-pe>`)) continue;
+			const sep = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
+			node_fs.default.appendFileSync(filePath, `${sep}${PE_PLACEHOLDER}`, "utf-8");
+			console.error(`agents-md-lark-cli-pe: appended PE to ${filePath}`);
 		}
-	});
-	if (!cc) return false;
-	const { ocCur, installed } = cc;
-	if (isForkPlugin(installed)) {
-		if (installed.fullName === "@lark-apaas/openclaw-lark") return !effectiveCompatible(FORK_LARK_PLUGIN_PINNED_VERSION, ocCur);
-		return false;
+		if (isAnyFeishuPluginEnabled(ctx.config) && ensureLarkCliToolDeny(ctx.config)) console.error("agents-md-lark-cli-pe: merged lark-cli overlap tools into channels.feishu.tools.deny");
 	}
-	return isLarkUpgradeNeededFromCC(cc);
-}
+};
+AgentsMdLarkCliPeRule = __decorate([Rule({
+	key: "agents_md_lark_cli_pe",
+	description: "lark-cli 存在时规范化环境：AGENTS.md 追加 lark-cli-pe PE + 飞书插件重叠工具写入 channels.feishu.tools.deny",
+	dependsOn: ["config_syntax_check"],
+	repairMode: "standard",
+	level: "silent"
+})], AgentsMdLarkCliPeRule);
 //#endregion
 //#region src/rules/cleanup-install-backup-dirs.ts
 const DIR_PREFIX = ".openclaw-install-";
@@ -5359,8 +5378,6 @@ async function installOpenclaw(openclawTag, ossFileMap, opts = {}) {
 * `console.error`，独立调用方不传则静默。
 */
 const NOOP_LOG = () => {};
-/** 升级前需备份的 extensions/ 下的插件目录（官方短名 + legacy）。 */
-const FEISHU_PLUGIN_DIRS = FEISHU_PLUGIN_DIR_NAMES;
 /** 读取 package.json 的 version 字段，失败返回 null（仅用于日志） */
 function readPkgVersion(pkgPath) {
 	try {
@@ -5371,13 +5388,20 @@ function readPkgVersion(pkgPath) {
 	}
 }
 /**
-* 备份 openclaw.json + FEISHU_PLUGIN_DIRS 下存在的插件目录到 backupDir。
+* 备份 openclaw.json + LARK_PLUGIN_DIR_NAMES 下存在的插件目录到 backupDir。
 * 只备份当前存在的文件；不存在的记日志后跳过（恢复时据此判断「升级前是否存在」）。
 */
 function backupFeishuPlugins(opts) {
 	const { workspaceDir, configPath, backupDir } = opts;
 	const log = opts.log ?? NOOP_LOG;
 	try {
+		if (node_fs.default.existsSync(backupDir)) {
+			node_fs.default.rmSync(backupDir, {
+				recursive: true,
+				force: true
+			});
+			log(`cleaned stale backup dir: ${backupDir}`);
+		}
 		node_fs.default.mkdirSync(backupDir, { recursive: true });
 		log(`backup dir: ${backupDir}`);
 		if (node_fs.default.existsSync(configPath)) {
@@ -5387,7 +5411,7 @@ function backupFeishuPlugins(opts) {
 		} else log(`  skipped: openclaw.json (not found)`);
 		node_fs.default.mkdirSync(node_path.default.join(backupDir, "extensions"), { recursive: true });
 		const extSrc = node_path.default.join(workspaceDir, "extensions");
-		for (const pluginDir of FEISHU_PLUGIN_DIRS) {
+		for (const pluginDir of LARK_PLUGIN_DIR_NAMES) {
 			const src = node_path.default.join(extSrc, pluginDir);
 			if (node_fs.default.existsSync(src)) {
 				const dst = node_path.default.join(backupDir, "extensions", pluginDir);
@@ -5419,7 +5443,7 @@ function restoreFeishuPlugins(opts) {
 			log(`  deleted: openclaw.json`);
 		}
 		const extDst = node_path.default.join(workspaceDir, "extensions");
-		for (const pluginDir of FEISHU_PLUGIN_DIRS) {
+		for (const pluginDir of LARK_PLUGIN_DIR_NAMES) {
 			const dst = node_path.default.join(extDst, pluginDir);
 			if (node_fs.default.existsSync(dst)) {
 				node_fs.default.rmSync(dst, {
@@ -5434,7 +5458,7 @@ function restoreFeishuPlugins(opts) {
 			node_fs.default.copyFileSync(configBackup, configPath);
 			log(`  restored: openclaw.json`);
 		} else log(`  skipped restore: openclaw.json (not in backup — was not present before upgrade)`);
-		for (const pluginDir of FEISHU_PLUGIN_DIRS) {
+		for (const pluginDir of LARK_PLUGIN_DIR_NAMES) {
 			const backupSrc = node_path.default.join(backupDir, "extensions", pluginDir);
 			if (node_fs.default.existsSync(backupSrc)) {
 				node_fs.default.cpSync(backupSrc, node_path.default.join(extDst, pluginDir), { recursive: true });
@@ -5476,8 +5500,7 @@ function runLarkToolsUpdate(opts) {
 	return {
 		exitCode,
 		stdout,
-		stderr,
-		spawnError: r.error?.message
+		stderr
 	};
 }
 //#endregion
@@ -5534,8 +5557,11 @@ async function installExtension(tag, ossFileMap, opts = {}) {
 		installOne$1(pkg, tarball, homeBase);
 		console.error(`[install-extension]   ${pkg.name}: installed`);
 	}
-	if (!opts.skipConfigUpdate) updatePluginInstalls(opts.configPath ?? node_path.default.join(homeBase, DEFAULT_CONFIG_REL), targets);
-	else console.error(`[install-extension] skipConfigUpdate=true — not touching openclaw.json`);
+	if (!opts.skipConfigUpdate) {
+		const configPath = opts.configPath ?? node_path.default.join(homeBase, DEFAULT_CONFIG_REL);
+		updatePluginInstalls(configPath, targets);
+		if (targets.some((p) => p.name === "openclaw-lark") && isLarkCliAvailable$1()) ensureLarkCliToolDenyInFile(configPath, (msg) => console.error(`[install-extension] ${msg}`));
+	} else console.error(`[install-extension] skipConfigUpdate=true — not touching openclaw.json`);
 	console.error(`[install-extension] done ${targets.length}/${targets.length} in ${Date.now() - t0}ms`);
 }
 const PLUGINS_TO_AUTO_ENABLE = [LARK_PLUGIN_NAME, MIAODA_PLUGIN_NAME];
@@ -5644,9 +5670,9 @@ async function installLarkPluginWithCompatCheck(opts) {
 		console.error("[install-extension] WARN: cannot read openclaw version — falling back to direct tarball install for openclaw-lark");
 		return false;
 	}
-	const compatVersion = resolveCompatVersion(pkg.packageName, pkg.version);
-	const compatible = compatVersion ? effectiveCompatible(compatVersion, ocCur) : true;
-	console.error(`[install-extension] ${pkg.packageName ?? pkg.name}@${pkg.version ?? "unknown"} (compat-as ${compatVersion ?? "unknown"}) vs openclaw@${ocCur}: ${compatible}`);
+	const compatResult = checkPluginCompat(pkg.packageName, pkg.version, ocCur);
+	const compatible = compatResult.resolvedVersion ? compatResult.compatible : true;
+	console.error(`[install-extension] ${pkg.packageName ?? pkg.name}@${pkg.version ?? "unknown"} (compat-as ${compatResult.resolvedVersion ?? "unknown"}) vs openclaw@${ocCur}: ${compatible}`);
 	if (compatible) return false;
 	console.error(`[install-extension] openclaw-lark@${pkg.version} incompatible with openclaw@${ocCur} — using openclaw-lark-tools update`);
 	const log = (msg) => console.error(`[install-extension] ${msg}`);
@@ -5687,6 +5713,7 @@ async function installLarkPluginWithCompatCheck(opts) {
 			});
 			throw new Error(`openclaw-lark post-install validation failed: ${validation.error}`);
 		}
+		ensureLarkCliToolDenyInFile(configPath, (msg) => console.error(`[install-extension] ${msg}`));
 		console.error("[install-extension] openclaw-lark-tools update succeeded");
 		return true;
 	} finally {
@@ -7034,7 +7061,15 @@ async function installClis(tag, ossFileMap, opts) {
 	}
 	console.error(`[install-cli] tag=${tag} targets=${targets.length}`);
 	const t0 = Date.now();
+	const larkCliAlreadyAvailable = targets.some((p) => p.name === "lark-cli") && isLarkCliAvailable$1();
 	const tarballs = await Promise.all(targets.map(async (p) => {
+		if (p.name === "lark-cli" && larkCliAlreadyAvailable) {
+			console.error(`[install-cli]   ${p.name}: already available (lark-cli --version) — skip download/extract/link`);
+			return {
+				pkg: p,
+				tarball: null
+			};
+		}
 		const tb = await downloadWithCache(p, ossFileMap, opts);
 		console.error(`[install-cli]   ${p.name}: downloaded`);
 		return {
@@ -7043,6 +7078,7 @@ async function installClis(tag, ossFileMap, opts) {
 		};
 	}));
 	for (const { pkg, tarball } of tarballs) {
+		if (tarball === null) continue;
 		installOne(pkg, tarball, homeBase, opts.tmpRoot);
 		linkBins(pkg, homeBase);
 		console.error(`[install-cli]   ${pkg.name}: installed`);
@@ -7072,7 +7108,9 @@ async function installClis(tag, ossFileMap, opts) {
 				}
 			});
 		}
-		disableLarkCliOverlapTools(node_path.default.join(homeBase, WORKSPACE_AGENT_REL, "openclaw.json"), homeBase);
+		const configPath = node_path.default.join(homeBase, WORKSPACE_AGENT_REL, "openclaw.json");
+		if (node_fs.default.existsSync(node_path.default.join(homeBase, "workspace/agent", "extensions", "openclaw-lark"))) ensureLarkCliToolDenyInFile(configPath, (msg) => console.error(`[install-cli] ${msg}`));
+		else console.error(`[install-cli] ${LARK_PLUGIN_NAME} not installed — skip tools.deny`);
 	}
 	console.error(`[install-cli] done ${targets.length}/${targets.length} in ${Date.now() - t0}ms`);
 }
@@ -7247,38 +7285,6 @@ function installOne(pkg, tarball, homeBase, tmpRoot) {
 		} catch {}
 	}
 }
-/**
-* Write overlapping tool names to channels.feishu.tools.deny in openclaw.json so that
-* openclaw-lark's shouldRegisterTool() skips them when lark-cli is present.
-*
-* Only runs when openclaw-lark is installed (extensions/openclaw-lark/ exists).
-* Idempotent: merges with any existing deny entries.
-* Failures are non-fatal (logged as warnings).
-*/
-function disableLarkCliOverlapTools(configPath, homeBase) {
-	const larkPluginDir = node_path.default.join(homeBase, WORKSPACE_AGENT_REL, "extensions", LARK_PLUGIN_NAME);
-	if (!node_fs.default.existsSync(larkPluginDir)) {
-		console.error(`[install-cli] disableLarkCliOverlapTools: ${LARK_PLUGIN_NAME} not installed — skipping`);
-		return;
-	}
-	if (!node_fs.default.existsSync(configPath)) {
-		console.error(`[install-cli] disableLarkCliOverlapTools: config not found at ${configPath} — skipping`);
-		return;
-	}
-	try {
-		const config = loadJSON5().parse(node_fs.default.readFileSync(configPath, "utf-8"));
-		if (!ensureLarkCliToolDeny(config)) {
-			console.error("[install-cli] disableLarkCliOverlapTools: deny already up to date");
-			return;
-		}
-		const tmp = configPath + ".lark-cli-deny-tmp";
-		node_fs.default.writeFileSync(tmp, JSON.stringify(config, null, 2), "utf-8");
-		moveSafe(tmp, configPath);
-		console.error("[install-cli] disableLarkCliOverlapTools: channels.feishu.tools.deny updated");
-	} catch (e) {
-		console.error(`[install-cli] WARN: disableLarkCliOverlapTools failed: ${e.message}`);
-	}
-}
 //#endregion
 //#region src/download-resource.ts
 /**
@@ -11214,7 +11220,7 @@ async function reportCliRun(opts) {
 //#region src/help.ts
 const BIN = "mclaw-diagnose";
 function versionBanner() {
-	return `v0.1.18-alpha.3`;
+	return `v0.1.18-alpha.4`;
 }
 const COMMANDS = [
 	{
@@ -12152,7 +12158,7 @@ function runUpgradeLark(opts) {
 		});
 	}
 	log("");
-	log("── [1/6] 文件备份 ────────────────────────────────────────");
+	log("── [1/7] 文件备份 ────────────────────────────────────────");
 	log(`before-state: botCount=${countFeishuBots(configPath)}`);
 	const t_backupStart = Date.now();
 	const backup = backupFeishuPlugins(fsOpts);
@@ -12170,7 +12176,7 @@ function runUpgradeLark(opts) {
 	log("backup: ok");
 	logVersionSnapshot("before-versions", snapshotVersions(cwd, log), log);
 	log("");
-	log("── [2/6] 清理本地 openclaw shim ─────────────────────────");
+	log("── [2/7] 清理本地 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);
@@ -12180,7 +12186,7 @@ function runUpgradeLark(opts) {
 	}
 	else log(`  skipped: ${localOpenclawBin} (not found)`);
 	log("");
-	log("── [3/6] npx install (@larksuite/openclaw-lark-tools update) ──");
+	log("── [3/7] npx install (@larksuite/openclaw-lark-tools update) ──");
 	const t_npxStart = Date.now();
 	const { exitCode: npxExitCode, stdout: npxStdout, stderr: npxStderr } = runLarkToolsUpdate({
 		cwd,
@@ -12211,7 +12217,7 @@ function runUpgradeLark(opts) {
 		});
 	};
 	log("");
-	log("── [4/5] 安装后诊断校验 ─────────────────────────────────");
+	log("── [4/7] 安装后诊断校验 ─────────────────────────────────");
 	logVersionSnapshot("after-versions", snapshotVersions(cwd, log), log);
 	let afterVersionIncompatible = false;
 	try {
@@ -12240,7 +12246,7 @@ function runUpgradeLark(opts) {
 	if (isNewDefaultOnly) log("  post-install diagnosis: ok (new default account — plugin installed, awaiting configuration)");
 	else log("  post-install diagnosis: ok (upgrade conditions resolved)");
 	log("");
-	log("── [6/6] doctor --fix ────────────────────────────────────");
+	log("── [5/7] doctor --fix ────────────────────────────────────");
 	const fixArgs = ["doctor", "--fix"];
 	if (opts.scene) fixArgs.push(`--scene=${opts.scene}`);
 	const t_doctorFixStart = Date.now();
@@ -12260,7 +12266,7 @@ function runUpgradeLark(opts) {
 	if (fixResult.stderr?.trim()) log(`doctor(fix) stderr:\n${fixResult.stderr.trim()}`);
 	log(`doctor(fix) exit: ${fixResult.status ?? "null"}${fixResult.error ? ` error: ${fixResult.error.message}` : ""}`);
 	log("");
-	log("── [7/8] 重启 openclaw 服务 ──────────────────────────────");
+	log("── [6/7] 重启 openclaw 服务 ──────────────────────────────");
 	const restartScript = "/opt/force/bin/openclaw_scripts/restart.sh";
 	let restartExecuted = false;
 	if (opts.skipRestart) log("  skipped: --skip-restart");
@@ -12282,7 +12288,7 @@ function runUpgradeLark(opts) {
 		restartExecuted = true;
 	} else log(`  skipped: ${restartScript} not found`);
 	log("");
-	log("── [8/8] 端口存活检测 ────────────────────────────────────");
+	log("── [7/7] 端口存活检测 ────────────────────────────────────");
 	let portCheckOk;
 	if (!restartExecuted) log("  skipped: restart was not executed");
 	else {