@lark-apaas/openclaw-scripts-diagnose-cli 0.1.6 → 0.1.7-alpha.0

package/dist/index.cjs

@@ -50,7 +50,7 @@ node_assert = __toESM(node_assert);
 * it terse and parseable.
 */
 function getVersion() {
-	return "0.1.6";
+	return "0.1.7-alpha.0";
 }
 //#endregion
 //#region src/rule-engine/base.ts
@@ -76,6 +76,19 @@ function Rule(meta) {
 function getAllRules() {
 	return topoSort(ruleRegistry.map((Ctor) => new Ctor()));
 }
+/** Return serialisable metadata for all registered rules (topo-sorted). */
+function getRuleMetas(keys) {
+	const rules = getAllRules();
+	return (keys && keys.length > 0 ? rules.filter((r) => keys.includes(r.meta.key)) : rules).map((r) => ({
+		key: r.meta.key,
+		description: r.meta.description ?? "(no description)",
+		repairMode: r.meta.repairMode,
+		profile: r.meta.profile ?? "standard",
+		dependsOn: r.meta.dependsOn ?? [],
+		hasSkipWhen: r.meta.skipWhen !== void 0,
+		hasRepair: r.repair !== DiagnoseRule.prototype.repair
+	}));
+}
 /**
 * 判断规则在当前 profile 下是否应执行。
 * experimental profile 运行所有规则；standard 只运行 standard（或未标注）规则。
@@ -1284,6 +1297,7 @@ let OpenclawRuntimeMissingRule = class OpenclawRuntimeMissingRule extends Diagno
 };
 OpenclawRuntimeMissingRule = __decorate([Rule({
 	key: "openclaw_runtime_missing",
+	description: "检查 openclaw 二进制是否在 PATH 中可用；缺失时提示重新安装",
 	repairMode: "user-confirm"
 })], OpenclawRuntimeMissingRule);
 //#endregion
@@ -1307,6 +1321,7 @@ let ProcessStatusRule = class ProcessStatusRule extends DiagnoseRule {
 };
 ProcessStatusRule = __decorate([Rule({
 	key: "multi_process_detect",
+	description: "通过 pgrep 检测是否存在多个并发的 openclaw-gateway 进程；多进程通常表明上次会话未正常退出",
 	repairMode: "standard"
 })], ProcessStatusRule);
 //#endregion
@@ -1372,6 +1387,7 @@ let ConfigFileBackupRule = class ConfigFileBackupRule extends DiagnoseRule {
 };
 ConfigFileBackupRule = __decorate([Rule({
 	key: "config_file_recover",
+	description: "扫描 .bak* 配置备份，当主配置 openclaw.json 缺失时恢复编号最高的备份",
 	repairMode: "standard"
 })], ConfigFileBackupRule);
 //#endregion
@@ -1405,6 +1421,7 @@ let ConfigFileMissingRule = class ConfigFileMissingRule extends DiagnoseRule {
 };
 ConfigFileMissingRule = __decorate([Rule({
 	key: "config_file_missing",
+	description: "在执行恢复后检查 openclaw.json 是否存在；若仍缺失则触发全量重置",
 	dependsOn: ["config_file_recover"],
 	repairMode: "reset"
 })], ConfigFileMissingRule);
@@ -1427,6 +1444,7 @@ let ConfigSyntaxRule = class ConfigSyntaxRule extends DiagnoseRule {
 };
 ConfigSyntaxRule = __decorate([Rule({
 	key: "config_syntax_check",
+	description: "验证 openclaw.json 的 JSON5 语法；schema 校验失败或解析错误时需要 AI 辅助修复",
 	dependsOn: ["config_file_recover", "config_file_missing"],
 	repairMode: "ai"
 })], ConfigSyntaxRule);
@@ -1456,6 +1474,7 @@ let TemplateVarsUnreplacedRule = class TemplateVarsUnreplacedRule extends Diagno
 };
 TemplateVarsUnreplacedRule = __decorate([Rule({
 	key: "template_vars_unreplaced",
+	description: "检测 openclaw.json 中未替换的 $__XXX__ 占位符，并从注入的环境变量中填充",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "standard",
 	usesVars: ["templateVars"]
@@ -1604,6 +1623,7 @@ let ModelProviderRule = class ModelProviderRule extends DiagnoseRule {
 };
 ModelProviderRule = __decorate([Rule({
 	key: "model_provider",
+	description: "检查妙搭 model provider 配置项（baseUrl、apiKey、必要 headers）是否存在且格式正确；非妙搭沙箱时跳过",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "standard",
 	usesVars: ["innerAPIKey", "baseURL"],
@@ -1671,6 +1691,7 @@ let SecretProviderRule = class SecretProviderRule extends DiagnoseRule {
 };
 SecretProviderRule = _SecretProviderRule = __decorate([Rule({
 	key: "secret_provider",
+	description: "验证 miaoda-provider / miaoda-secret-provider 配置块是否存在且完整；未检测到妙搭 provider 时跳过",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "standard",
 	skipWhen: ({ hasMiaoda, deps }) => !hasMiaoda || !deps.usesMiaodaProvider && !deps.usesMiaodaSecretProvider
@@ -1735,6 +1756,7 @@ let FeishuChannelRule = class FeishuChannelRule extends DiagnoseRule {
 };
 FeishuChannelRule = __decorate([Rule({
 	key: "feishu_channel",
+	description: "确保 channels.feishu 已启用，且包含单 agent 所需的 appId 和 appSecret 字段",
 	dependsOn: ["config_syntax_check", "feishu_default_account"],
 	repairMode: "standard",
 	usesVars: ["feishuAppID", "feishuAppSecret"]
@@ -1851,6 +1873,7 @@ let FeishuDefaultAccountRule = class FeishuDefaultAccountRule extends DiagnoseRu
 };
 FeishuDefaultAccountRule = __decorate([Rule({
 	key: "feishu_default_account",
+	description: "将旧版 v1/v2 飞书 channel 配置迁移为规范的 v3 bot-<appId> 账号结构",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "standard",
 	usesVars: ["feishuAppID", "teamChatID"]
@@ -1979,6 +2002,7 @@ let GatewayRule = class GatewayRule extends DiagnoseRule {
 };
 GatewayRule = __decorate([Rule({
 	key: "gateway",
+	description: "验证 gateway 必填字段（port、mode、bind、auth、trustedProxies）是否存在且有效；修复缺失或非法值",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "standard",
 	usesVars: ["gatewayToken"]
@@ -2024,6 +2048,7 @@ let AllowedOriginsRule = class AllowedOriginsRule extends DiagnoseRule {
 };
 AllowedOriginsRule = __decorate([Rule({
 	key: "allowed_origins",
+	description: "确保所有 expectedOrigins 条目都存在于 gateway.auth.allowedOrigins 中；自动追加缺失的条目",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "standard",
 	usesVars: ["expectedOrigins"]
@@ -2103,6 +2128,7 @@ let JwtTokenRule = class JwtTokenRule extends DiagnoseRule {
 };
 JwtTokenRule = __decorate([Rule({
 	key: "jwt_token",
+	description: "验证 miaoda provider 引用的 JWT token 文件存在且未过期；非妙搭沙箱时跳过",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "standard",
 	usesVars: ["providerFilePath"],
@@ -2159,6 +2185,7 @@ let SecretsFileRule = class SecretsFileRule extends DiagnoseRule {
 };
 SecretsFileRule = __decorate([Rule({
 	key: "secrets_file",
+	description: "验证 miaoda secret-provider 引用的 secrets.json 文件存在且可解析；非妙搭或非 secret-provider 沙箱时跳过",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "standard",
 	usesVars: [
@@ -2214,6 +2241,7 @@ let CleanupInstallBackupDirsRule = class CleanupInstallBackupDirsRule extends Di
 };
 CleanupInstallBackupDirsRule = __decorate([Rule({
 	key: "cleanup_install_backup_dirs",
+	description: "清理 extensions/ 目录中升级中断遗留的 .openclaw-install-stage-* 和 .openclaw-install-backups/ 脏目录",
 	repairMode: "standard"
 })], CleanupInstallBackupDirsRule);
 //#endregion
@@ -2269,6 +2297,7 @@ let MiaodaOfficialPluginsInstallSpecUnlockRule = class MiaodaOfficialPluginsInst
 };
 MiaodaOfficialPluginsInstallSpecUnlockRule = __decorate([Rule({
 	key: "miaoda_official_plugins_install_spec_unlock",
+	description: "移除官方妙搭插件安装条目中的锁版本 npm spec，使其跟随最新 manifest 版本",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "standard"
 })], MiaodaOfficialPluginsInstallSpecUnlockRule);
@@ -2335,6 +2364,7 @@ let OldMiaodaPluginsCleanupRule = class OldMiaodaPluginsCleanupRule extends Diag
 };
 OldMiaodaPluginsCleanupRule = __decorate([Rule({
 	key: "old_miaoda_plugins_cleanup",
+	description: "当新版 openclaw-extension-miaoda 已存在时，清理过时插件引用（openclaw-feishu-greeting、openclaw-miaoda-keepalive 等）",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "standard"
 })], OldMiaodaPluginsCleanupRule);
@@ -2372,6 +2402,7 @@ let LarkPluginAllowRule = class LarkPluginAllowRule extends DiagnoseRule {
 };
 LarkPluginAllowRule = __decorate([Rule({
 	key: "lark_plugin_allow",
+	description: "当飞书插件（openclaw-lark 或旧版名）已在磁盘安装但未加入 plugins.allow 时，自动添加",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "standard"
 })], LarkPluginAllowRule);
@@ -2427,6 +2458,7 @@ let MiaodaPluginAllowRule = class MiaodaPluginAllowRule extends DiagnoseRule {
 };
 MiaodaPluginAllowRule = __decorate([Rule({
 	key: "miaoda_plugin_allow",
+	description: "当 openclaw-extension-miaoda 已在磁盘安装但未在 allow 列表中时，将其添加到 plugins.allow（实验性）",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "standard",
 	profile: "experimental"
@@ -2468,6 +2500,7 @@ let BuiltinPluginMissingRule = class BuiltinPluginMissingRule extends DiagnoseRu
 };
 BuiltinPluginMissingRule = __decorate([Rule({
 	key: "builtin_plugin_missing",
+	description: "检查所有内置扩展插件（openclaw-lark、openclaw-extension-miaoda 等）是否已在磁盘安装；缺失时提示重新安装（实验性）",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "user-confirm",
 	profile: "experimental"
@@ -2510,6 +2543,7 @@ let BuiltinPluginInstallsCleanupRule = class BuiltinPluginInstallsCleanupRule ex
 };
 BuiltinPluginInstallsCleanupRule = __decorate([Rule({
 	key: "builtin_plugin_installs_cleanup",
+	description: "在 builtin_plugin_missing 通过后，清除 plugins.installs 中磁盘目录已不存在的条目（实验性）",
 	dependsOn: ["builtin_plugin_missing"],
 	repairMode: "standard",
 	profile: "experimental"
@@ -2792,6 +2826,7 @@ let FeishuPluginStateNormalizeRule = class FeishuPluginStateNormalizeRule extend
 };
 FeishuPluginStateNormalizeRule = __decorate([Rule({
 	key: "feishu_plugin_state_normalize",
+	description: "规范化磁盘上的飞书插件状态：删除旧版插件目录、清理内置 feishu 目录，并将 openclaw.json 条目对齐到 openclaw-lark 插件",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "standard"
 })], FeishuPluginStateNormalizeRule);
@@ -3025,6 +3060,7 @@ let FeishuPluginVersionCompatRule = class FeishuPluginVersionCompatRule extends
 };
 FeishuPluginVersionCompatRule = __decorate([Rule({
 	key: "feishu_plugin_version_compat",
+	description: "检查飞书插件与 openclaw 版本兼容性；不兼容时推荐 upgrade_openclaw 或 upgrade_lark 操作",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "user-confirm",
 	usesVars: ["recommendedOpenclawTag"]
@@ -3185,6 +3221,7 @@ let FeishuAccountsConsistencyRule = class FeishuAccountsConsistencyRule extends
 };
 FeishuAccountsConsistencyRule = __decorate([Rule({
 	key: "feishu_accounts_consistency",
+	description: "检测多 agent 配置中 channels.feishu.accounts、agents.list 与 feishu bindings 之间的数量/ID 不一致（实验性）",
 	dependsOn: ["config_syntax_check"],
 	repairMode: "check-only",
 	usesVars: ["feishuAppID"],
@@ -8149,7 +8186,7 @@ async function reportCliRun(opts) {
 //#region src/help.ts
 const BIN = "mclaw-diagnose";
 function versionBanner() {
-	return `v0.1.6`;
+	return `v0.1.7-alpha.0`;
 }
 const COMMANDS = [
 	{
@@ -8416,6 +8453,39 @@ OPTIONS
 EXIT CODES
   0    Success or skipped (prerequisites not met).
   1    Secret/path unresolvable, lark-cli failed, or config unreadable.
+`
+	},
+	{
+		name: "rules",
+		hidden: true,
+		summary: "List all registered rule metadata as JSON",
+		help: `USAGE
+  ${BIN} rules [--rule=<key>]...
+
+DESCRIPTION
+  Prints a JSON array of serialisable metadata for every registered rule,
+  topologically sorted by dependsOn. Useful for tooling, dashboards, and
+  analysis scripts that need a stable machine-readable view of the rule
+  registry.
+
+  Each element has the shape:
+    {
+      "key": "gateway",
+      "description": "...",
+      "repairMode": "standard" | "user-confirm" | "ai" | "reset" | "check-only",
+      "profile": "standard" | "experimental",
+      "dependsOn": ["config_syntax_check"],
+      "hasSkipWhen": false
+    }
+
+OPTIONS
+  --rule=<key>   Filter output to specific rule keys (repeatable). Returns
+                 all rules when omitted.
+
+EXAMPLES
+  ${BIN} rules                         # all rules
+  ${BIN} rules --rule=gateway          # single rule
+  ${BIN} rules --rule=gateway --rule=feishu_channel  # multiple rules
 `
 	},
 	{
@@ -10261,6 +10331,12 @@ async function main() {
 			if (error) throw error;
 			break;
 		}
+		case "rules": {
+			const keys = getMultiFlag(args, "rule");
+			const metas = getRuleMetas(keys.length > 0 ? keys : void 0);
+			console.log(JSON.stringify(metas));
+			break;
+		}
 		case "lark-cli-init": {
 			const appId = getFlag(args, "app-id");
 			if (!appId) {

package/package.json

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