@pwddd/skills-scanner 3.0.23 → 4.0.0

package/src/config.ts

@@ -1,170 +1,187 @@
-/**
- * 配置管理模块
- */
-
-import { Type } from "@sinclair/typebox";
-import type { OpenClawPluginConfigSchema } from "openclaw/plugin-sdk";
-import type { ScannerConfig } from "./types.js";
-
-export const skillsScannerConfigSchema: OpenClawPluginConfigSchema = {
-  safeParse: (value: unknown) => {
-    try {
-      const config = value as ScannerConfig;
-      
-      // 验证 policy
-      if (config.policy && !["strict", "balanced", "permissive"].includes(config.policy)) {
-        return {
-          success: false,
-          error: {
-            issues: [{
-              path: ["policy"],
-              message: "policy 必须是 strict、balanced 或 permissive"
-            }]
-          }
-        };
-      }
-      
-      // 验证 preInstallScan
-      if (config.preInstallScan && !["on", "off"].includes(config.preInstallScan)) {
-        return {
-          success: false,
-          error: {
-            issues: [{
-              path: ["preInstallScan"],
-              message: "preInstallScan 必须是 on 或 off"
-            }]
-          }
-        };
-      }
-      
-      // 验证 onUnsafe
-      if (config.onUnsafe && !["quarantine", "delete", "warn"].includes(config.onUnsafe)) {
-        return {
-          success: false,
-          error: {
-            issues: [{
-              path: ["onUnsafe"],
-              message: "onUnsafe 必须是 quarantine、delete 或 warn"
-            }]
-          }
-        };
-      }
-      
-      return { success: true, data: config };
-    } catch (err) {
-      return {
-        success: false,
-        error: {
-          issues: [{
-            path: [],
-            message: String(err)
-          }]
-        }
-      };
-    }
-  },
-  
-  uiHints: {
-    apiUrl: {
-      label: "API 服务地址",
-      help: "扫描 API 服务的 URL 地址",
-      placeholder: "https://110.vemic.com/skills-scanner"
-    },
-    scanDirs: {
-      label: "扫描目录",
-      help: "要监控的 Skills 目录列表，支持 ~ 路径"
-    },
-    behavioral: {
-      label: "行为分析",
-      help: "启用深度行为分析（较慢但更准确）"
-    },
-    useLLM: {
-      label: "LLM 分析",
-      help: "使用 LLM 进行语义分析"
-    },
-    policy: {
-      label: "扫描策略",
-      help: "strict=严格 / balanced=平衡（推荐）/ permissive=宽松"
-    },
-    preInstallScan: {
-      label: "安装前扫描",
-      help: "监听新 Skill 并自动扫描"
-    },
-    onUnsafe: {
-      label: "不安全处理",
-      help: "warn=仅警告（推荐）/ quarantine=隔离 / delete=删除"
-    }
-  }
-};
-
-export function generateConfigGuide(
-  cfg: ScannerConfig,
-  apiUrl: string,
-  scanDirs: string[],
-  behavioral: boolean,
-  useLLM: boolean,
-  policy: string,
-  preInstallScan: string,
-  onUnsafe: string
-): string {
-  return [
-    "",
-    "╔════════════════════════════════════════════════════════════════╗",
-    "║  🎉 Skills Scanner 首次运行 - 配置向导                         ║",
-    "╚════════════════════════════════════════════════════════════════╝",
-    "",
-    "当前使用默认配置。建议根据您的需求自定义配置：",
-    "",
-    "📋 当前配置：",
-    `  • API 服务地址: ${apiUrl}`,
-    `  • 扫描目录: ${scanDirs.length} 个（自动检测）`,
-    `  • 行为分析: ${behavioral ? "✅ 启用" : "❌ 禁用"}`,
-    `  • LLM 分析: ${useLLM ? "✅ 启用" : "❌ 禁用"}`,
-    `  • 扫描策略: ${policy}`,
-    `  • 安装前扫描: ${preInstallScan === "on" ? "✅ 启用" : "❌ 禁用"}`,
-    `  • 不安全处理: ${onUnsafe}`,
-    "",
-    "🔧 配置文件位置：",
-    "  ~/.openclaw/config.json",
-    "",
-    "📝 推荐配置示例：",
-    "",
-    "```json",
-    "{",
-    '  "plugins": {',
-    '    "entries": {',
-    '      "skills-scanner": {',
-    '        "enabled": true,',
-    '        "config": {',
-    '          "apiUrl": "https://110.vemic.com/skills-scanner",',
-    '          "scanDirs": ["~/.openclaw/skills"],',
-    '          "behavioral": false,',
-    '          "useLLM": false,',
-    '          "policy": "balanced",',
-    '          "preInstallScan": "on",',
-    '          "onUnsafe": "warn"',
-    '        }',
-    '      }',
-    '    }',
-    '  }',
-    "}",
-    "```",
-    "",
-    "💡 配置说明：",
-    "",
-    "1. apiUrl        默认 https://110.vemic.com/skills-scanner，需先启动 skill-scanner-api 服务",
-    "2. scanDirs      可添加多个目录（默认自动检测 ~/.openclaw/skills）",
-    "3. behavioral    false=快速扫描（推荐），true=深度分析",
-    "4. useLLM        false=不使用 LLM（推荐），true=语义分析",
-    "5. policy        strict / balanced（推荐）/ permissive",
-    "6. preInstallScan on=监听新 Skill 并自动扫描（推荐），off=禁用",
-    "7. onUnsafe      warn=仅警告（推荐），quarantine=隔离，delete=删除",
-    "",
-    "🚀 快速开始：",
-    "  编辑配置文件后重启 Gateway",
-    "  /skills-scanner health",
-    "",
-    "提示：此消息只在首次运行时显示。",
-    "════════════════════════════════════════════════════════════════",
-  ].join("\n");
-}
+/**
+ * 配置管理模块
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginConfigSchema } from "openclaw/plugin-sdk/plugin-entry";
+import type { ScannerConfig } from "./types.js";
+
+export const skillsScannerConfigSchema: OpenClawPluginConfigSchema = {
+  safeParse: (value: unknown) => {
+    try {
+      const config = value as ScannerConfig;
+
+      // 验证 policy
+      if (config.policy && !["strict", "balanced", "permissive"].includes(config.policy)) {
+        return {
+          success: false,
+          error: {
+            issues: [{
+              path: ["policy"],
+              message: "policy 必须是 strict、balanced 或 permissive"
+            }]
+          }
+        };
+      }
+
+      // 验证 onUnsafe
+      if (config.onUnsafe && !["quarantine", "delete", "warn"].includes(config.onUnsafe)) {
+        return {
+          success: false,
+          error: {
+            issues: [{
+              path: ["onUnsafe"],
+              message: "onUnsafe 必须是 quarantine、delete 或 warn"
+            }]
+          }
+        };
+      }
+
+      return { success: true, data: config };
+    } catch (err) {
+      return {
+        success: false,
+        error: {
+          issues: [{
+            path: [],
+            message: String(err)
+          }]
+        }
+      };
+    }
+  },
+
+  uiHints: {
+    apiUrl: {
+      label: "API 服务地址",
+      help: "扫描 API 服务的 URL 地址",
+      placeholder: "https://110.vemic.com/skills-scanner",
+      type: "string",
+      format: "uri",
+    },
+    behavioral: {
+      label: "行为分析",
+      help: "启用深度行为分析（较慢但更准确）。检测运行时行为模式，如网络请求、文件操作等",
+      type: "boolean",
+      default: false,
+    },
+    useLLM: {
+      label: "LLM 分析",
+      help: "使用 LLM 进行语义分析。可以检测更复杂的恶意模式，但需要更多时间和资源",
+      type: "boolean",
+      default: false,
+    },
+    policy: {
+      label: "扫描策略",
+      help: "strict=严格（零容忍）/ balanced=平衡（推荐，误报率低）/ permissive=宽松（仅检测明显威胁）",
+      type: "string",
+      enum: ["strict", "balanced", "permissive"],
+      default: "balanced",
+    },
+    onUnsafe: {
+      label: "不安全处理",
+      help: "warn=仅警告（推荐，不影响使用）/ quarantine=隔离到隔离区 / delete=直接删除（危险）",
+      type: "string",
+      enum: ["warn", "quarantine", "delete"],
+      default: "warn",
+    },
+    enableBeforeInstallHook: {
+      label: "安装前拦截",
+      help: "启用 before_install hook，在安装前强制拦截不安全的 Skills（强烈推荐）。这是最后一道防线",
+      type: "boolean",
+      default: true,
+    },
+    injectSecurityGuidance: {
+      label: "注入安全指导",
+      help: "在系统提示中注入安全指导，提醒 AI 注意 Skills 安全问题",
+      type: "boolean",
+      default: true,
+    },
+    scanTimeoutMs: {
+      label: "扫描超时（毫秒）",
+      help: "单次扫描的最大时长，超时后自动取消。默认 180000ms (3分钟)",
+      type: "number",
+      minimum: 10000,
+      maximum: 600000,
+      default: 180000,
+    },
+    reportDir: {
+      label: "报告目录",
+      help: "扫描报告保存目录。留空则使用默认位置",
+      type: "string",
+    },
+    quarantineDir: {
+      label: "隔离目录",
+      help: "隔离文件保存目录。留空则使用默认位置",
+      type: "string",
+    },
+  }
+};
+
+export function generateConfigGuide(
+  cfg: ScannerConfig,
+  apiUrl: string,
+  behavioral: boolean,
+  useLLM: boolean,
+  policy: string,
+  onUnsafe: string
+): string {
+  return [
+    "",
+    "╔════════════════════════════════════════════════════════════════╗",
+    "║  🎉 Skills Scanner 首次运行 - 配置向导                         ║",
+    "╚════════════════════════════════════════════════════════════════╝",
+    "",
+    "当前使用默认配置。建议根据您的需求自定义配置：",
+    "",
+    "📋 当前配置：",
+    `  • API 服务地址：${apiUrl}`,
+    `  • 行为分析：${behavioral ? "✅ 启用" : "❌ 禁用"}`,
+    `  • LLM 分析：${useLLM ? "✅ 启用" : "❌ 禁用"}`,
+    `  • 扫描策略：${policy}`,
+    `  • 目录监控：❌ 已禁用（需手动扫描）`,
+    `  • 不安全处理：${onUnsafe}`,
+    "",
+    "🔧 配置文件位置：",
+    "  ~/.openclaw/config.json",
+    "",
+    "📝 推荐配置示例：",
+    "",
+    "```json",
+    "{",
+    '  "plugins": {',
+    '    "entries": {',
+    '      "skills-scanner": {',
+    '        "enabled": true,',
+    '        "config": {',
+    '          "apiUrl": "https://110.vemic.com/skills-scanner",',
+    '          "behavioral": false,',
+    '          "useLLM": false,',
+    '          "policy": "balanced",',
+    '          "onUnsafe": "warn"',
+    '        }',
+    '      }',
+    '    }',
+    '  }',
+    "}",
+    "```",
+    "",
+    "💡 配置说明：",
+    "",
+    "1. apiUrl        默认 https://110.vemic.com/skills-scanner",
+    "2. behavioral    false=快速扫描（推荐），true=深度分析",
+    "3. useLLM        false=不使用 LLM（推荐），true=语义分析",
+    "4. policy        strict / balanced（推荐）/ permissive",
+    "5. onUnsafe      warn=仅警告（推荐），quarantine=隔离，delete=删除",
+    "",
+    "⚠️ 注意：目录监控功能已禁用，请使用以下命令手动扫描：",
+    "  /skills-scanner scan <路径>",
+    "",
+    "🚀 快速开始：",
+    "  编辑配置文件后重启 Gateway",
+    "  /skills-scanner health",
+    "",
+    "提示：此消息只在首次运行时显示。",
+    "════════════════════════════════════════════════════════════════",
+  ].join("\n");
+}

package/src/cron-manager.ts

@@ -0,0 +1,158 @@
+import { exec, execSync } from "node:child_process";
+import { promisify } from "node:util";
+import type { Logger } from "@openclaw/plugin-sdk";
+
+const execAsync = promisify(exec);
+
+const CRON_JOB_NAME = "skills-weekly-report";
+const CLEANUP_JOB_NAME = "skills-scanner-cleanup";
+const CRON_SCHEDULE = "5 12 * * 1"; // Every Monday at 12:05
+const CLEANUP_SCHEDULE = "0 3 * * *"; // Every day at 3:00 AM
+const CRON_TIMEZONE = "Asia/Shanghai";
+
+export interface CronManagerOptions {
+  logger: Logger;
+  config: any;
+}
+
+/**
+ * Detect the correct OpenClaw command (openclaw vs npx openclaw)
+ */
+function getOpenClawCommand(): string {
+  // 1. Check environment variable
+  if (process.env.OPENCLAW_CLI_PATH) {
+    return process.env.OPENCLAW_CLI_PATH;
+  }
+
+  // 2. Check if running via npx
+  const argv1 = process.argv[1];
+  if (argv1?.includes("npx") || argv1?.includes("_npx")) {
+    return "npx openclaw";
+  }
+
+  if (process.env.npm_execpath?.includes("npx")) {
+    return "npx openclaw";
+  }
+
+  // 3. Try global openclaw command
+  try {
+    execSync("openclaw --version", {
+      encoding: "utf-8",
+      timeout: 3000,
+      stdio: "pipe"
+    });
+    return "openclaw";
+  } catch {
+    // openclaw command not available
+  }
+
+  // 4. Try npx as fallback
+  try {
+    execSync("npx openclaw --version", {
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: "pipe"
+    });
+    return "npx openclaw";
+  } catch {
+    // npx also not available
+  }
+
+  // 5. Default to openclaw (will fail with clear error)
+  return "openclaw";
+}
+
+/**
+ * Ensure system crontab exists for cleanup
+ */
+export async function ensureCronJob(options: CronManagerOptions): Promise<void> {
+  const { logger } = options;
+
+  logger.info(`[skills-scanner] Setting up system crontab for cleanup...`);
+
+  try {
+    // Check if crontab entry already exists
+    const { stdout: currentCrontab } = await execAsync("crontab -l", {
+      timeout: 5000,
+    }).catch(() => ({ stdout: "" }));
+
+    const cleanupMarker = "# skills-scanner cleanup";
+
+    if (currentCrontab.includes(cleanupMarker)) {
+      logger.info(`[skills-scanner] System crontab already exists`);
+      return;
+    }
+
+    // Create cleanup command - remove ALL skills-weekly-report jobs
+    // Escape $(...) and $variables once: \\$ in JS → \$ in string → $ in crontab
+    const openclawCmd = getOpenClawCommand();
+    const cleanupCmd = `for id in \\$(${openclawCmd} cron list | grep skills-weekly-report | awk '{print \\$1}'); do ${openclawCmd} cron remove \\$id; done > /dev/null 2>&1`;
+
+    // Add new crontab entry (comment on separate line) - runs at 2:00 AM daily
+    const newCrontabEntry = `${cleanupMarker}\n0 4 * * * ${cleanupCmd}`;
+    const newCrontab = currentCrontab ? `${currentCrontab}\n${newCrontabEntry}` : newCrontabEntry;
+
+    // Install new crontab
+    await execAsync(`echo "${newCrontab.replace(/"/g, '\\"')}" | crontab -`, {
+      timeout: 5000,
+      shell: "/bin/bash",
+    });
+
+    logger.info(`[skills-scanner] ✅ System crontab created: runs daily at 3:00 AM`);
+  } catch (err: any) {
+    logger.warn(`[skills-scanner] ⚠️  Failed to setup system crontab: ${err.message}`);
+  }
+}
+
+/**
+ * Cleanup system crontab (called on plugin uninstall)
+ */
+export async function cleanupCronJob(options: CronManagerOptions): Promise<void> {
+  const { logger } = options;
+
+  logger.info(`[skills-scanner] Removing system crontab...`);
+
+  try {
+    // Get current crontab
+    const { stdout: currentCrontab } = await execAsync("crontab -l", {
+      timeout: 5000,
+    }).catch(() => ({ stdout: "" }));
+
+    const cleanupMarker = "# skills-scanner cleanup";
+
+    if (!currentCrontab.includes(cleanupMarker)) {
+      logger.info(`[skills-scanner] No system crontab to remove`);
+      return;
+    }
+
+    // Remove the cleanup entry (marker line + cron line)
+    const lines = currentCrontab.split("\n");
+    const newLines: string[] = [];
+    let skipNext = false;
+
+    for (const line of lines) {
+      if (line.includes(cleanupMarker)) {
+        skipNext = true;
+        continue;
+      }
+      if (skipNext) {
+        skipNext = false;
+        continue;
+      }
+      newLines.push(line);
+    }
+
+    const newCrontab = newLines.join("\n").trim();
+
+    // Always update crontab, even if empty (don't use crontab -r)
+    await execAsync(`echo "${newCrontab.replace(/"/g, '\\"')}" | crontab -`, {
+      timeout: 5000,
+      shell: "/bin/bash",
+    });
+
+    logger.info(`[skills-scanner] ✅ System crontab removed`);
+  } catch (err: any) {
+    logger.warn(`[skills-scanner] ⚠️  Failed to remove system crontab: ${err.message}`);
+  }
+}
+

package/src/debug.ts

@@ -0,0 +1,40 @@
+/**
+ * Debug utilities module
+ */
+
+import type { PluginLogger } from "./types.js";
+
+// Check if debug mode is enabled via environment variable
+const DEBUG_MODE = process.env.SKILLS_SCANNER_DEBUG === "1" ||
+                   process.env.SKILLS_SCANNER_DEBUG === "true";
+
+/**
+ * Log debug message if debug mode is enabled
+ */
+export function debugLog(logger: PluginLogger, message: string, data?: any): void {
+  if (DEBUG_MODE) {
+    if (data) {
+      logger.debug(`[skills-scanner:debug] ${message}`, data);
+    } else {
+      logger.debug(`[skills-scanner:debug] ${message}`);
+    }
+  }
+}
+
+/**
+ * Check if debug mode is enabled
+ */
+export function isDebugMode(): boolean {
+  return DEBUG_MODE;
+}
+
+/**
+ * Format debug data for logging
+ */
+export function formatDebugData(data: any): string {
+  try {
+    return JSON.stringify(data, null, 2);
+  } catch {
+    return String(data);
+  }
+}

package/src/error-handler.ts

@@ -0,0 +1,103 @@
+/**
+ * Error handling utilities
+ */
+
+/**
+ * Create a user-friendly error message with actionable suggestions
+ */
+export function createActionableError(
+  operation: string,
+  error: Error,
+  context?: {
+    apiUrl?: string;
+    path?: string;
+    [key: string]: any;
+  }
+): string {
+  const lines: string[] = [];
+
+  // Main error message
+  lines.push(`❌ ${operation} 失败: ${error.message}`);
+  lines.push("");
+
+  // Context information
+  if (context) {
+    if (context.path) {
+      lines.push(`📁 文件路径: ${context.path}`);
+    }
+    if (context.apiUrl) {
+      lines.push(`🌐 API 地址: ${context.apiUrl}`);
+    }
+  }
+
+  // Possible causes and solutions
+  lines.push("");
+  lines.push("🔍 可能的原因:");
+
+  if (error.message.includes("ECONNREFUSED") || error.message.includes("fetch failed")) {
+    lines.push("  • API 服务不可用或无法连接");
+    lines.push("  • 网络连接问题");
+    lines.push("  • 防火墙阻止了连接");
+    lines.push("");
+    lines.push("💡 解决方案:");
+    lines.push("  1. 检查 API 服务状态: /skills-scanner health");
+    lines.push("  2. 验证网络连接");
+    lines.push("  3. 检查防火墙设置");
+    if (context?.apiUrl) {
+      lines.push(`  4. 尝试访问: ${context.apiUrl}/health`);
+    }
+  } else if (error.message.includes("timeout") || error.message.includes("ETIMEDOUT")) {
+    lines.push("  • 扫描操作超时");
+    lines.push("  • API 响应过慢");
+    lines.push("  • 网络延迟过高");
+    lines.push("");
+    lines.push("💡 解决方案:");
+    lines.push("  1. 增加超时时间配置 (scanTimeoutMs)");
+    lines.push("  2. 检查网络质量");
+    lines.push("  3. 稍后重试");
+  } else if (error.message.includes("ENOENT") || error.message.includes("not found")) {
+    lines.push("  • 文件或目录不存在");
+    lines.push("  • 路径配置错误");
+    lines.push("  • 文件已被移动或删除");
+    lines.push("");
+    lines.push("💡 解决方案:");
+    lines.push("  1. 验证文件路径是否正确");
+    lines.push("  2. 检查文件权限");
+    lines.push("  3. 确认文件未被其他程序占用");
+  } else if (error.message.includes("EACCES") || error.message.includes("permission denied")) {
+    lines.push("  • 文件权限不足");
+    lines.push("  • 目录访问被拒绝");
+    lines.push("");
+    lines.push("💡 解决方案:");
+    lines.push("  1. 检查文件/目录权限");
+    lines.push("  2. 确保当前用户有读写权限");
+    lines.push("  3. 尝试使用管理员权限运行");
+  } else {
+    lines.push("  • 未知错误");
+    lines.push("");
+    lines.push("💡 解决方案:");
+    lines.push("  1. 查看完整错误日志");
+    lines.push("  2. 启用调试模式: SKILLS_SCANNER_DEBUG=1");
+    lines.push("  3. 联系技术支持");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Wrap an async operation with error handling
+ */
+export async function withErrorHandling<T>(
+  operation: string,
+  fn: () => Promise<T>,
+  context?: any
+): Promise<T> {
+  try {
+    return await fn();
+  } catch (error: any) {
+    const message = createActionableError(operation, error, context);
+    const enhancedError = new Error(message);
+    enhancedError.stack = error.stack;
+    throw enhancedError;
+  }
+}