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

package/dist/index.cjs

@@ -52,7 +52,7 @@ node_assert = __toESM(node_assert);
 * it terse and parseable.
 */
 function getVersion() {
-	return "0.1.18-alpha.2";
+	return "0.1.18-alpha.3";
 }
 //#endregion
 //#region src/rule-engine/base.ts
@@ -2655,17 +2655,71 @@ function upgradeLarkLogFile(runId, checkOnly = false) {
 	return `${DIAGNOSE_DIR}/upgrade-lark${checkOnly ? "-check" : ""}-${ts}-${runId.slice(0, 8)}.log`;
 }
 //#endregion
+//#region src/constants.ts
+/**
+* 全局共享常量（插件名 / CLI 名 / 路径 / 插件集合）。
+*
+* 历史上这些字面量散落在 install-*、upgrade-lark、各 rule 等十余个文件里重复定义，
+* 易漂移。统一收口到此处，按用途分组，单一来源。
+*/
+/**
+* 官方插件：`openclaw-lark`（plugins.allow 中的短名；npm 发布名 `@larksuite/openclaw-lark`）。
+* 走 VERSION_COMPAT_MAP 按版本判定与 openclaw 的兼容性。
+*/
+const LARK_PLUGIN_NAME = "openclaw-lark";
+/**
+* fork 插件：`@lark-apaas/openclaw-lark`（@lark-apaas 内部 fork，全名带 scope）。
+* 版本号自成体系、不在 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。
+*/
+const BUILTIN_FEISHU_PLUGIN_NAME = "feishu";
+/**
+* 旧版插件：已弃用的 `feishu-openclaw-plugin`，始终不兼容，需替换为官方 openclaw-lark。
+*/
+const LEGACY_LARK_PLUGIN_NAME = "feishu-openclaw-plugin";
+const MIAODA_PLUGIN_NAME = "openclaw-extension-miaoda";
+const MIAODA_CODING_PLUGIN_NAME = "openclaw-extension-miaoda-coding";
+const GUARDIAN_PLUGIN_NAME = "openclaw-guardian-plugin";
+const MEM0_PLUGIN_NAME = "openclaw-mem0-plugin";
+/** 飞书 lark-cli 命令名（独立 CLI，与 openclaw-lark 插件配套）。 */
+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];
+/**
+* install-extension --all 安装的官方扩展插件集合（manifest role=extension）。
+* builtin-plugin-missing 与 miaoda-official-plugins-install-spec-unlock 共用此单一来源，
+* 二者此前各维护一份且注释明示"必须保持一致"。
+*/
+const OFFICIAL_EXTENSION_PLUGIN_NAMES = new Set([
+	LARK_PLUGIN_NAME,
+	MIAODA_PLUGIN_NAME,
+	MIAODA_CODING_PLUGIN_NAME,
+	GUARDIAN_PLUGIN_NAME,
+	MEM0_PLUGIN_NAME
+]);
+/** agent 工作区相对路径。 */
+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 LARK_PLUGIN_NAMES$1 = ["openclaw-lark", "feishu-openclaw-plugin"];
 const PE_XML_TAG = "lark-cli-pe";
 const PE_PLACEHOLDER = `
 <${PE_XML_TAG}>
 **【强制要求 - 无例外】飞书所有操作必须先读 feishu-lark-cli skill。未读skill不得调用任何飞书工具，违者视为操作失误。**
 </${PE_XML_TAG}>
 `;
-function isLarkPluginInstalled(configPath) {
+function isLarkPluginInstalled$1(configPath) {
 	const extDir = getExtensionsDir(configPath);
-	return LARK_PLUGIN_NAMES$1.some((name) => {
+	return FEISHU_PLUGIN_DIR_NAMES.some((name) => {
 		try {
 			return node_fs.default.existsSync(node_path.default.join(extDir, name, "package.json"));
 		} catch {
@@ -2837,7 +2891,7 @@ function collectFeishuAppIds(configPath) {
 }
 function runLarkCliInit(opts) {
 	const configPath = opts.configPath ?? CONFIG_PATH;
-	if (!isLarkPluginInstalled(configPath)) {
+	if (!isLarkPluginInstalled$1(configPath)) {
 		console.error("lark-cli-init: skipping — openclaw-lark plugin not installed");
 		return {
 			ok: true,
@@ -2915,7 +2969,66 @@ function runLarkCliInit(opts) {
 	};
 }
 //#endregion
-//#region src/rules/agents-md-lark-cli-pe.ts
+//#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"], {
@@ -2931,17 +3044,38 @@ function isLarkCliAvailable$1() {
 		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 = collectExistingAgentsMdPaths(ctx).find((filePath) => {
-			return !node_fs.default.readFileSync(filePath, "utf-8").includes(`<${PE_XML_TAG}>`);
-		});
-		if (!missingPath) return { pass: true };
-		return {
+		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;
@@ -2952,11 +3086,12 @@ let AgentsMdLarkCliPeRule = class AgentsMdLarkCliPeRule extends DiagnoseRule {
 			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: "检测各智能体 AGENTS.md 中是否缺失 lark-cli-pe PE 内容，lark-cli 存在时自动追加",
+	description: "lark-cli 存在时规范化环境：AGENTS.md 追加 lark-cli-pe PE + openclaw-lark 重叠工具写入 channels.feishu.tools.deny",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "standard",
 	level: "silent"
@@ -2966,15 +3101,8 @@ AgentsMdLarkCliPeRule = __decorate([Rule({
 /**
 * 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).
+* out of scope (users may pin them deliberately). 集合见 constants.OFFICIAL_EXTENSION_PLUGIN_NAMES。
 */
-const OFFICIAL_PLUGIN_NAMES = new Set([
-	"openclaw-extension-miaoda",
-	"openclaw-extension-miaoda-coding",
-	"openclaw-guardian-plugin",
-	"openclaw-mem0-plugin",
-	"openclaw-lark"
-]);
 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);
@@ -2989,7 +3117,7 @@ function* iterLockedOfficialInstalls(config) {
 	const installs = getNestedMap(config, "plugins", "installs");
 	if (!installs) return;
 	for (const [key, entry] of Object.entries(installs)) {
-		if (!OFFICIAL_PLUGIN_NAMES.has(key)) continue;
+		if (!OFFICIAL_EXTENSION_PLUGIN_NAMES.has(key)) continue;
 		const spec = asRecord(entry)?.spec;
 		if (isLockedNpmSpec(spec)) yield [key, spec];
 	}
@@ -3021,28 +3149,27 @@ MiaodaOfficialPluginsInstallSpecUnlockRule = __decorate([Rule({
 })], MiaodaOfficialPluginsInstallSpecUnlockRule);
 //#endregion
 //#region src/rules/miaoda-plugin-allow.ts
-const MIAODA_PLUGIN = "openclaw-extension-miaoda";
 let MiaodaPluginAllowRule = class MiaodaPluginAllowRule extends DiagnoseRule {
 	validate(ctx) {
-		if (!isPluginInstalledOnDisk(getExtensionsDir(ctx.configPath), MIAODA_PLUGIN)) return { pass: true };
-		if (getAllow$1(ctx.config).includes(MIAODA_PLUGIN)) return { pass: true };
+		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}（已在 extensions/ 下装但未启用）`
+			message: `plugins.allow 缺少 ${MIAODA_PLUGIN_NAME}（已在 extensions/ 下装但未启用）`
 		};
 	}
 	repair(ctx) {
-		if (!isPluginInstalledOnDisk(getExtensionsDir(ctx.configPath), MIAODA_PLUGIN)) return;
+		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] };
+			ctx.config.plugins = { allow: [MIAODA_PLUGIN_NAME] };
 			return;
 		}
 		const pluginsMap = plugins;
 		const rawAllow = pluginsMap.allow;
 		const allow = Array.isArray(rawAllow) ? rawAllow : [];
-		if (allow.includes(MIAODA_PLUGIN)) return;
-		allow.push(MIAODA_PLUGIN);
+		if (allow.includes("openclaw-extension-miaoda")) return;
+		allow.push(MIAODA_PLUGIN_NAME);
 		pluginsMap.allow = allow;
 	}
 };
@@ -3063,9 +3190,7 @@ function getAllow$1(config) {
 }
 //#endregion
 //#region src/rules/lark-plugin-allow.ts
-const LARK_PLUGIN = "openclaw-lark";
-const LEGACY_LARK_PLUGIN = "feishu-openclaw-plugin";
-const LARK_PLUGIN_NAMES = [LARK_PLUGIN, LEGACY_LARK_PLUGIN];
+const LARK_PLUGIN_NAMES = FEISHU_PLUGIN_DIR_NAMES;
 let LarkPluginAllowRule = class LarkPluginAllowRule extends DiagnoseRule {
 	validate(ctx) {
 		const allow = getAllow(ctx.config);
@@ -3113,7 +3238,7 @@ function getAllow(config) {
 * 不读 package.json 内容，只判存在性，避开 JSON 损坏。
 */
 function detectInstalledLarkPlugin(extDir) {
-	for (const name of [LARK_PLUGIN, LEGACY_LARK_PLUGIN]) if (pluginPackageJsonExists(extDir, name)) return name;
+	for (const name of LARK_PLUGIN_NAMES) if (pluginPackageJsonExists(extDir, name)) return name;
 	return null;
 }
 function pluginPackageJsonExists(extDir, pluginDir) {
@@ -3125,7 +3250,6 @@ function pluginPackageJsonExists(extDir, pluginDir) {
 }
 //#endregion
 //#region src/rules/old-miaoda-plugins-cleanup.ts
-const NEW_MIAODA = "openclaw-extension-miaoda";
 const OLD_PLUGIN_NAMES = Object.freeze([
 	"openclaw-feishu-greeting",
 	"openclaw-miaoda-keepalive",
@@ -3141,7 +3265,7 @@ function getPluginMaps(config) {
 	};
 }
 function hasNewMiaoda({ entries, installs, allow }) {
-	return asRecord(entries?.[NEW_MIAODA]) != null || asRecord(installs?.[NEW_MIAODA]) != null || (allow?.includes(NEW_MIAODA) ?? false);
+	return asRecord(entries?.["openclaw-extension-miaoda"]) != null || asRecord(installs?.["openclaw-extension-miaoda"]) != null || (allow?.includes("openclaw-extension-miaoda") ?? false);
 }
 function findResiduals({ entries, installs, allow }, extensionsDir) {
 	return OLD_PLUGIN_NAMES.filter((name) => entries?.[name] != null || installs?.[name] != null || (allow?.includes(name) ?? false) || node_fs.default.existsSync(node_path.default.join(extensionsDir, name)));
@@ -3193,20 +3317,9 @@ OldMiaodaPluginsCleanupRule = __decorate([Rule({
 })], OldMiaodaPluginsCleanupRule);
 //#endregion
 //#region src/rules/builtin-plugin-missing.ts
-/**
-* install-extension --all 安装的内置扩展插件列表（manifest role=extension）。
-* 与 miaoda-official-plugins-install-spec-unlock.ts 中的 OFFICIAL_PLUGIN_NAMES 保持一致。
-*/
-const BUILTIN_EXTENSION_PLUGINS = new Set([
-	"openclaw-lark",
-	"openclaw-extension-miaoda",
-	"openclaw-extension-miaoda-coding",
-	"openclaw-guardian-plugin",
-	"openclaw-mem0-plugin"
-]);
 function findMissingBuiltinPlugins(ctx) {
 	const extDir = getExtensionsDir(ctx.configPath);
-	return [...BUILTIN_EXTENSION_PLUGINS].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) {
@@ -3487,10 +3600,7 @@ function extractTarballTolerant(tarball, destDir, opts = {}) {
 }
 //#endregion
 //#region src/rules/feishu-plugin-state-normalize.ts
-const PLUGIN_NAME$2 = "openclaw-lark";
-const BUILTIN_FEISHU = "feishu";
-const LEGACY_PLUGIN_NAME = "feishu-openclaw-plugin";
-const LEGACY_DIRS_TO_REMOVE = [LEGACY_PLUGIN_NAME, BUILTIN_FEISHU];
+const LEGACY_DIRS_TO_REMOVE = [LEGACY_LARK_PLUGIN_NAME, BUILTIN_FEISHU_PLUGIN_NAME];
 const FEISHU_TOOLS = Object.freeze([
 	"feishu_bitable_app",
 	"feishu_bitable_app_table",
@@ -3536,9 +3646,10 @@ let FeishuPluginStateNormalizeRule = class FeishuPluginStateNormalizeRule extend
 	validate(ctx) {
 		if (!isPluginInstalled(ctx)) return { pass: true };
 		const fails = [];
-		if (!isNewPluginEnabled(ctx.config)) fails.push(`plugins.entries["${PLUGIN_NAME$2}"].enabled !== true（应启用）`);
+		if (!isNewPluginEnabled(ctx.config)) fails.push(`plugins.entries["${LARK_PLUGIN_NAME}"].enabled !== true（应启用）`);
 		if (isBuiltinFeishuEnabled(ctx.config)) fails.push("plugins.entries.feishu.enabled === true（应禁用）");
-		if (isTopLevelMissingFeishuTools(ctx.config)) fails.push("tools.alsoAllow 缺 feishu_* tools");
+		const grantGap = missingFeishuToolsGrant(ctx.config);
+		if (grantGap) fails.push(`tools.${grantGap} 缺 feishu_* tools`);
 		const legacyResiduals = findLegacyResiduals(ctx);
 		if (legacyResiduals.length > 0) fails.push(`legacy 飞书插件残留：${legacyResiduals.join(", ")}`);
 		if (fails.length === 0) return { pass: true };
@@ -3548,8 +3659,8 @@ let FeishuPluginStateNormalizeRule = class FeishuPluginStateNormalizeRule extend
 		};
 	}
 	repair(ctx) {
-		setEntryEnabled(ctx.config, PLUGIN_NAME$2, true);
-		setEntryEnabled(ctx.config, BUILTIN_FEISHU, false);
+		setEntryEnabled(ctx.config, LARK_PLUGIN_NAME, true);
+		setEntryEnabled(ctx.config, BUILTIN_FEISHU_PLUGIN_NAME, false);
 		ensureFeishuTools(ctx.config);
 		cleanupLegacyResiduals(ctx);
 	}
@@ -3562,36 +3673,54 @@ FeishuPluginStateNormalizeRule = __decorate([Rule({
 	level: "critical"
 })], FeishuPluginStateNormalizeRule);
 function isPluginInstalled(ctx) {
-	return node_fs.default.existsSync(node_path.default.join(getExtensionsDir(ctx.configPath), PLUGIN_NAME$2));
+	return node_fs.default.existsSync(node_path.default.join(getExtensionsDir(ctx.configPath), LARK_PLUGIN_NAME));
 }
 function isNewPluginEnabled(config) {
-	return asRecord(getNestedMap(config, "plugins", "entries")?.[PLUGIN_NAME$2])?.enabled === true;
+	return asRecord(getNestedMap(config, "plugins", "entries")?.[LARK_PLUGIN_NAME])?.enabled === true;
 }
 function isBuiltinFeishuEnabled(config) {
-	return asRecord(getNestedMap(config, "plugins", "entries")?.[BUILTIN_FEISHU])?.enabled === true;
-}
-/** 仅看顶层 tools.alsoAllow——agent 级 alsoAllow 是用户对单 agent 的精细化授权，doctor 不动。
-*  含 "*" 或任一 feishu_* 即视为已配。 */
-function isTopLevelMissingFeishuTools(config) {
-	return !hasFeishuTool(readAlsoAllow(config));
+	return asRecord(getNestedMap(config, "plugins", "entries")?.[BUILTIN_FEISHU_PLUGIN_NAME])?.enabled === true;
 }
-function readAlsoAllow(host) {
-	const tools = asRecord(host)?.tools;
-	const arr = asRecord(tools)?.alsoAllow;
+/** 读取顶层 tools.<key>（allow / alsoAllow）的字符串数组。 */
+function readTopLevelToolsList(config, key) {
+	const arr = asRecord(asRecord(config)?.tools)?.[key];
 	if (!Array.isArray(arr)) return [];
 	return arr.filter((e) => typeof e === "string");
 }
-function hasFeishuTool(alsoAllow) {
-	if (alsoAllow.includes("*")) return true;
-	return alsoAllow.some((t) => FEISHU_TOOLS.includes(t));
+function hasFeishuTool(list) {
+	if (list.includes("*")) return true;
+	return list.some((t) => FEISHU_TOOLS.includes(t));
+}
+/**
+* 决定 feishu_* 应补充到哪个授权键：
+*   - 已有非空 tools.allow（限制式白名单）→ 'allow'（合并进 allow，避免与 alsoAllow 冲突）
+*   - 否则 → 'alsoAllow'（追加式，叠加在 profile 基线上）
+* openclaw schema 禁止同一 scope 同时设 allow + alsoAllow，故有 allow 时必须并入 allow，
+* 否则会触发 tools_allow_also_allow_conflict 规则反复来回改写。
+*/
+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)?.[LEGACY_PLUGIN_NAME] != null) found.push("entries[legacy]");
+	if (asRecord(plugins?.entries)?.["feishu-openclaw-plugin"] != null) found.push("entries[legacy]");
 	const allow = plugins?.allow;
-	if (Array.isArray(allow) && allow.includes(LEGACY_PLUGIN_NAME)) found.push("allow[legacy]");
-	if (asRecord(plugins?.installs)?.[LEGACY_PLUGIN_NAME] != null) found.push("installs[legacy]");
+	if (Array.isArray(allow) && allow.includes("feishu-openclaw-plugin")) found.push("allow[legacy]");
+	if (asRecord(plugins?.installs)?.["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;
@@ -3604,21 +3733,22 @@ function setEntryEnabled(config, key, enabled) {
 	};
 }
 function ensureFeishuTools(config) {
-	const alsoAllow = readAlsoAllow(config);
-	if (hasFeishuTool(alsoAllow)) return;
-	ensureRecord(config, "tools").alsoAllow = [...new Set([...alsoAllow, ...FEISHU_TOOLS])];
+	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 && LEGACY_PLUGIN_NAME in entries) delete entries[LEGACY_PLUGIN_NAME];
+		if (entries && "feishu-openclaw-plugin" in entries) delete entries[LEGACY_LARK_PLUGIN_NAME];
 		const installs = asRecord(plugins.installs);
-		if (installs && LEGACY_PLUGIN_NAME in installs) delete installs[LEGACY_PLUGIN_NAME];
+		if (installs && "feishu-openclaw-plugin" in installs) delete installs[LEGACY_LARK_PLUGIN_NAME];
 		const allow = plugins.allow;
 		if (Array.isArray(allow)) {
-			for (let i = allow.length - 1; i >= 0; i--) if (allow[i] === LEGACY_PLUGIN_NAME) allow.splice(i, 1);
-			if (!allow.includes(PLUGIN_NAME$2)) allow.push(PLUGIN_NAME$2);
+			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 extDir = getExtensionsDir(ctx.configPath);
@@ -3791,6 +3921,17 @@ function effectiveCompatible(pluginVersion, openclawVersion) {
 	const max = coerceCalVer(maxInfo.max);
 	return maxInfo.exclusive ? semver.default.lt(oc, max) : !semver.default.gt(oc, max);
 }
+/**
+* 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";
 /**
 * Resolve the version to evaluate against VERSION_COMPAT_MAP for a given plugin.
@@ -3814,9 +3955,8 @@ function findClosestEntry(pluginVersion) {
 }
 //#endregion
 //#region src/rules/feishu-plugin-version-compat.ts
-const PLUGIN_NAME$1 = "openclaw-lark";
-const LEGACY_SHORT_NAMES = ["feishu-openclaw-plugin"];
-const FORK_SCOPES = ["@lark-apaas"];
+const LEGACY_SHORT_NAMES = [LEGACY_LARK_PLUGIN_NAME];
+const FORK_SCOPES = [FORK_LARK_PLUGIN_SCOPE];
 /**
 * fork 版兼容区间的下界，取自 VERSION_COMPAT_MAP 中 openclawLarkVersion=2026.4.1
 * 的 minOpenclawVersion，避免与映射表脱钩写死。仅用于区分升级方向
@@ -4027,7 +4167,7 @@ function detectInstalledPlugin(ctx) {
 	const allow = Array.isArray(allowRaw) ? allowRaw.filter((e) => typeof e === "string") : [];
 	const extDir = getExtensionsDir(ctx.configPath);
 	const installs = getNestedMap(ctx.config, "plugins", "installs");
-	for (const name of [PLUGIN_NAME$1, ...LEGACY_SHORT_NAMES]) {
+	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;
@@ -4120,12 +4260,10 @@ CleanupInstallBackupDirsRule = __decorate([Rule({
 })], CleanupInstallBackupDirsRule);
 //#endregion
 //#region src/rules/lark-cli-missing-for-installed-lark-plugin.ts
-const PLUGIN_NAME = "openclaw-lark";
-const FORK_PACKAGE_NAME = "@lark-apaas/openclaw-lark";
+/** 触发本规则自动安装 lark-cli 的特定 fork 版本（与对标的官方兼容版本无关）。 */
 const TARGET_VERSION = "2026.4.4";
-const LARK_CLI_NAME$1 = "lark-cli";
 function readInstalledLarkPlugin(ctx) {
-	const pkgPath = node_path.default.join(getExtensionsDir(ctx.configPath), PLUGIN_NAME, "package.json");
+	const pkgPath = node_path.default.join(getExtensionsDir(ctx.configPath), LARK_PLUGIN_NAME, "package.json");
 	if (!node_fs.default.existsSync(pkgPath)) return null;
 	let pkg = {};
 	try {
@@ -4138,14 +4276,14 @@ function readInstalledLarkPlugin(ctx) {
 		pkg = {};
 	}
 	const installs = getNestedMap(ctx.config, "plugins", "installs");
-	const installEntry = installs ? asRecord(installs[PLUGIN_NAME]) : void 0;
+	const installEntry = installs ? asRecord(installs[LARK_PLUGIN_NAME]) : void 0;
 	return {
 		name: pkg.name ?? extractScopedNameFromSpec(installEntry?.spec),
 		version: pkg.version ?? (typeof installEntry?.version === "string" ? installEntry.version : void 0)
 	};
 }
 function isTargetForkPlugin(plugin) {
-	return plugin?.name === FORK_PACKAGE_NAME && plugin.version === TARGET_VERSION;
+	return plugin?.name === "@lark-apaas/openclaw-lark" && plugin.version === TARGET_VERSION;
 }
 function extractScopedNameFromSpec(spec) {
 	if (typeof spec !== "string") return void 0;
@@ -4154,7 +4292,7 @@ function extractScopedNameFromSpec(spec) {
 }
 function isLarkCliAvailable() {
 	try {
-		return (0, node_child_process.spawnSync)(LARK_CLI_NAME$1, ["--version"], {
+		return (0, node_child_process.spawnSync)(LARK_CLI_NAME, ["--version"], {
 			encoding: "utf-8",
 			timeout: 5e3,
 			stdio: [
@@ -4196,7 +4334,7 @@ let LarkCliMissingForInstalledLarkPluginRule = class LarkCliMissingForInstalledL
 		if (isLarkCliAvailable()) return { pass: true };
 		return {
 			pass: false,
-			message: `${FORK_PACKAGE_NAME}@${TARGET_VERSION} 已安装，但 lark-cli 不可用；将执行一次 lark-cli 安装`
+			message: `${FORK_LARK_PLUGIN_FULL_NAME}@${TARGET_VERSION} 已安装，但 lark-cli 不可用；将执行一次 lark-cli 安装`
 		};
 	}
 	repair(ctx) {
@@ -5210,7 +5348,7 @@ async function installOpenclaw(openclawTag, ossFileMap, opts = {}) {
 	console.error(`[install-openclaw] done in ${Date.now() - t0}ms`);
 }
 //#endregion
-//#region src/lark-tools-update.ts
+//#region src/utils/lark-tools-update.ts
 /**
 * 共享的飞书插件备份 / 恢复 / `openclaw-lark-tools update` 调用。
 *
@@ -5221,8 +5359,8 @@ async function installOpenclaw(openclawTag, ossFileMap, opts = {}) {
 * `console.error`，独立调用方不传则静默。
 */
 const NOOP_LOG = () => {};
-/** 升级前需备份的 extensions/ 下的插件目录（含 legacy） */
-const FEISHU_PLUGIN_DIRS = ["openclaw-lark", "feishu-openclaw-plugin"];
+/** 升级前需备份的 extensions/ 下的插件目录（官方短名 + legacy）。 */
+const FEISHU_PLUGIN_DIRS = FEISHU_PLUGIN_DIR_NAMES;
 /** 读取 package.json 的 version 字段，失败返回 null（仅用于日志） */
 function readPkgVersion(pkgPath) {
 	try {
@@ -5342,6 +5480,8 @@ function runLarkToolsUpdate(opts) {
 		spawnError: r.error?.message
 	};
 }
+//#endregion
+//#region src/install-extension.ts
 async function installExtension(tag, ossFileMap, opts = {}) {
 	const homeBase = resolveHomeBase(opts.homeBase);
 	const hasAll = !!opts.all;
@@ -5364,18 +5504,18 @@ async function installExtension(tag, ossFileMap, opts = {}) {
 	}
 	console.error(`[install-extension] tag=${tag} targets=${targets.length}`);
 	const t0 = Date.now();
-	const larkTarget = opts.skipConfigUpdate ? void 0 : targets.find((p) => p.name === LARK_PLUGIN_NAME$1);
+	const larkTarget = opts.skipConfigUpdate ? void 0 : targets.find((p) => p.name === LARK_PLUGIN_NAME);
 	if (larkTarget) {
 		if (await installLarkPluginWithCompatCheck({
 			tag,
 			pkg: larkTarget,
 			homeBase,
-			configPath: opts.configPath ?? node_path.default.join(homeBase, "workspace/agent/openclaw.json"),
+			configPath: opts.configPath ?? node_path.default.join(homeBase, DEFAULT_CONFIG_REL),
 			workspaceDir: node_path.default.join(homeBase, "workspace", "agent"),
 			ossFileMap,
 			downloadOpts: opts
 		})) {
-			targets = targets.filter((p) => p.name !== LARK_PLUGIN_NAME$1);
+			targets = targets.filter((p) => p.name !== LARK_PLUGIN_NAME);
 			if (targets.length === 0) {
 				console.error(`[install-extension] done in ${Date.now() - t0}ms`);
 				return;
@@ -5394,13 +5534,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, "workspace/agent/openclaw.json"), targets);
+	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`);
 	console.error(`[install-extension] done ${targets.length}/${targets.length} in ${Date.now() - t0}ms`);
 }
-const LARK_PLUGIN_NAME$1 = "openclaw-lark";
-const MEM0_PLUGIN_NAME = "openclaw-mem0-plugin";
-const PLUGINS_TO_AUTO_ENABLE = ["openclaw-lark", "openclaw-extension-miaoda"];
+const PLUGINS_TO_AUTO_ENABLE = [LARK_PLUGIN_NAME, MIAODA_PLUGIN_NAME];
 /**
 * Merge each installed extension's installMetadata into openclaw.json's
 * plugins.installs[<pkg.name>]. Atomic write via tmp + rename.
@@ -5432,14 +5570,14 @@ function updatePluginInstalls(configPath, installedPkgs) {
 		installs[pkg.name] = pkg.installMetadata;
 		updated++;
 	} else skipped++;
-	if (installedPkgs.some((p) => p.name === MEM0_PLUGIN_NAME)) {
+	if (installedPkgs.some((p) => p.name === "openclaw-mem0-plugin")) {
 		const allowRaw = plugins.allow;
 		const allow = Array.isArray(allowRaw) ? allowRaw : [];
-		if (!allow.filter((e) => typeof e === "string").includes(MEM0_PLUGIN_NAME)) allow.push(MEM0_PLUGIN_NAME);
+		if (!allow.filter((e) => typeof e === "string").includes("openclaw-mem0-plugin")) allow.push(MEM0_PLUGIN_NAME);
 		plugins.allow = allow;
 		if (!plugins.entries || typeof plugins.entries !== "object" || Array.isArray(plugins.entries)) plugins.entries = {};
 		const entries = plugins.entries;
-		if (!(MEM0_PLUGIN_NAME in entries)) entries[MEM0_PLUGIN_NAME] = { enabled: false };
+		if (!("openclaw-mem0-plugin" in entries)) entries[MEM0_PLUGIN_NAME] = { enabled: false };
 	}
 	for (const pkg of installedPkgs) {
 		if (!PLUGINS_TO_AUTO_ENABLE.includes(pkg.name)) continue;
@@ -5557,7 +5695,9 @@ async function installLarkPluginWithCompatCheck(opts) {
 				recursive: true,
 				force: true
 			});
-		} catch {}
+		} catch (e) {
+			console.error(`[install-extension] WARN: failed to clean up backup dir ${backupDir}: ${e.message}`);
+		}
 	}
 }
 /**
@@ -5566,7 +5706,7 @@ async function installLarkPluginWithCompatCheck(opts) {
 */
 function validateLarkPluginInstall(opts) {
 	const { homeBase, configPath } = opts;
-	const pkgJson = node_path.default.join(homeBase, "workspace", "agent", "extensions", LARK_PLUGIN_NAME$1, "package.json");
+	const pkgJson = node_path.default.join(homeBase, "workspace", "agent", "extensions", LARK_PLUGIN_NAME, "package.json");
 	if (!node_fs.default.existsSync(pkgJson)) return {
 		ok: false,
 		error: `plugin directory missing: ${pkgJson}`
@@ -5576,9 +5716,9 @@ function validateLarkPluginInstall(opts) {
 		error: `openclaw.json not found at ${configPath}`
 	};
 	try {
-		if (asRecord(getNestedMap(loadJSON5().parse(node_fs.default.readFileSync(configPath, "utf-8")), "plugins", "entries")?.[LARK_PLUGIN_NAME$1])?.enabled !== true) return {
+		if (asRecord(getNestedMap(loadJSON5().parse(node_fs.default.readFileSync(configPath, "utf-8")), "plugins", "entries")?.["openclaw-lark"])?.enabled !== true) return {
 			ok: false,
-			error: `plugins.entries["${LARK_PLUGIN_NAME$1}"].enabled is not true`
+			error: `plugins.entries["${LARK_PLUGIN_NAME}"].enabled is not true`
 		};
 	} catch (e) {
 		return {
@@ -6868,34 +7008,6 @@ function reportError(params) {
 }
 //#endregion
 //#region src/install-cli.ts
-const LARK_CLI_NAME = "lark-cli";
-const AGENT_SKILLS_NAME = "agent-skills";
-const WORKSPACE_AGENT_REL = "workspace/agent";
-const LARK_PLUGIN_NAME = "openclaw-lark";
-/**
-* openclaw-lark tools that overlap with lark-cli functionality.
-* Written to channels.feishu.tools.deny after lark-cli is installed so that
-* openclaw-lark's shouldRegisterTool() skips them, avoiding duplicate tools.
-* Supports trailing-* wildcards (handled by openclaw-lark's matchesAnyPattern).
-*
-* Kept: feishu_chat*, feishu_get_user, feishu_search_user, feishu_im_*,
-*       feishu_oauth*, feishu_auth, feishu_diagnose, feishu_doctor
-*/
-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"
-]);
 async function installClis(tag, ossFileMap, opts) {
 	const homeBase = resolveHomeBase(opts.homeBase);
 	if (opts.names.length === 0) throw new Error("install-cli: must provide at least one --cli=<name>");
@@ -6935,7 +7047,7 @@ async function installClis(tag, ossFileMap, opts) {
 		linkBins(pkg, homeBase);
 		console.error(`[install-cli]   ${pkg.name}: installed`);
 	}
-	if (targets.some((p) => p.name === LARK_CLI_NAME)) {
+	if (targets.some((p) => p.name === "lark-cli")) {
 		const skillsInstallPath = await installAgentSkills(manifest, ossFileMap, opts, homeBase, opts.tmpRoot);
 		if (skillsInstallPath) linkAgentSkills(homeBase, skillsInstallPath);
 		const appIds = collectFeishuAppIds();
@@ -6997,7 +7109,7 @@ function linkBins(pkg, homeBase) {
 	}
 }
 async function installAgentSkills(manifest, ossFileMap, downloadOpts, homeBase, tmpRoot) {
-	const pkg = manifest.packages.find((p) => p.role === "template" && p.name === AGENT_SKILLS_NAME);
+	const pkg = manifest.packages.find((p) => p.role === "template" && p.name === "agent-skills");
 	if (!pkg) {
 		console.error(`[install-cli] installAgentSkills: ${AGENT_SKILLS_NAME} not found in manifest (tag may not bundle it) — skipping skill install`);
 		return null;
@@ -7155,18 +7267,14 @@ function disableLarkCliOverlapTools(configPath, homeBase) {
 	}
 	try {
 		const config = loadJSON5().parse(node_fs.default.readFileSync(configPath, "utf-8"));
-		if (!config.channels || typeof config.channels !== "object") config.channels = {};
-		const channels = config.channels;
-		if (!channels.feishu || typeof channels.feishu !== "object") channels.feishu = {};
-		const feishu = channels.feishu;
-		if (!feishu.tools || typeof feishu.tools !== "object") feishu.tools = {};
-		const tools = feishu.tools;
-		const existing = Array.isArray(tools.deny) ? tools.deny : [];
-		tools.deny = [...new Set([...existing, ...LARK_CLI_OVERLAP_TOOL_DENY])];
+		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 (${LARK_CLI_OVERLAP_TOOL_DENY.length} patterns)`);
+		console.error("[install-cli] disableLarkCliOverlapTools: channels.feishu.tools.deny updated");
 	} catch (e) {
 		console.error(`[install-cli] WARN: disableLarkCliOverlapTools failed: ${e.message}`);
 	}
@@ -11106,7 +11214,7 @@ async function reportCliRun(opts) {
 //#region src/help.ts
 const BIN = "mclaw-diagnose";
 function versionBanner() {
-	return `v0.1.18-alpha.2`;
+	return `v0.1.18-alpha.3`;
 }
 const COMMANDS = [
 	{
@@ -11805,8 +11913,8 @@ function snapshotVersions(cwd, log) {
 	});
 	const ocRaw = (ocResult.stdout ?? "").trim() || (ocResult.stderr ?? "").trim();
 	const extDir = node_path.default.join(cwd, "extensions");
-	const larkPkg = node_path.default.join(extDir, "openclaw-lark", "package.json");
-	const feishuPkg = node_path.default.join(extDir, "feishu-openclaw-plugin", "package.json");
+	const larkPkg = node_path.default.join(extDir, LARK_PLUGIN_NAME, "package.json");
+	const feishuPkg = node_path.default.join(extDir, LEGACY_LARK_PLUGIN_NAME, "package.json");
 	log(`  version-check paths: ${larkPkg} [${node_fs.default.existsSync(larkPkg) ? "exists" : "missing"}]`);
 	log(`  version-check paths: ${feishuPkg} [${node_fs.default.existsSync(feishuPkg) ? "exists" : "missing"}]`);
 	return {

package/package.json

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