@pwddd/skills-scanner 1.0.0-beta.1

package/src/commands.ts

@@ -0,0 +1,289 @@
+/**
+ * Command handlers module
+ */
+
+import { existsSync } from "node:fs";
+import { join, basename } from "node:path";
+import { runScan } from "./scanner.js";
+import { buildDailyReport } from "./report.js";
+import { loadState, saveState, expandPath } from "./state.js";
+import { generateConfigGuide } from "./config.js";
+import { ensureCronJobViaGateway, checkCronJobStatus } from "./cron-manager.js";
+import type { ScannerConfig, CommandResponse, PluginLogger } from "./types.js";
+
+export function createCommandHandlers(
+  cfg: ScannerConfig,
+  apiUrl: string,
+  scanDirs: string[],
+  behavioral: boolean,
+  useLLM: boolean,
+  policy: string,
+  preInstallScan: string,
+  onUnsafe: string,
+  logger: PluginLogger,
+  callGateway: (method: string, params: any) => Promise<any>
+) {
+  async function handleScanCommand(args: string): Promise<CommandResponse> {
+    if (!args) {
+      return {
+        text: "用法：`/skills-scanner scan <路径> [--detailed] [--behavioral] [--recursive] [--report]`\n或：`/skills-scanner scan clawhub <URL> [--detailed] [--behavioral]`",
+      };
+    }
+
+    const parts = args.split(/\s+/);
+
+    // Check if this is a ClawHub scan
+    if (parts[0] === "clawhub") {
+      const clawhubUrl = parts.find((p) => p.startsWith("https://clawhub.ai/"));
+      if (!clawhubUrl) {
+        return { text: "⚠️ 请提供有效的 ClawHub URL (例如：https://clawhub.ai/username/project)" };
+      }
+
+      const detailed = parts.includes("--detailed");
+      const useBehav = parts.includes("--behavioral") || behavioral;
+
+      const res = await runScan("clawhub", clawhubUrl, {
+        detailed,
+        behavioral: useBehav,
+        apiUrl,
+        useLLM,
+        policy,
+      });
+      const icon = res.exitCode === 0 ? "✅" : "❌";
+      return { text: `${icon} ClawHub 扫描完成\n\`\`\`\n${res.output}\n\`\`\`` };
+    }
+
+    const targetPath = expandPath(parts.find((p) => !p.startsWith("--")) ?? "");
+    const detailed = parts.includes("--detailed");
+    const useBehav = parts.includes("--behavioral") || behavioral;
+    const recursive = parts.includes("--recursive");
+    const isReport = parts.includes("--report");
+
+    // Report mode: use configured scanDirs
+    if (isReport) {
+      if (scanDirs.length === 0) {
+        return { text: "⚠️ 未找到可扫描目录，请检查配置" };
+      }
+      const report = await buildDailyReport(
+        scanDirs,
+        useBehav,
+        apiUrl,
+        useLLM,
+        policy,
+        logger
+      );
+      return { text: report };
+    }
+
+    // Regular scan mode: require path
+    if (!targetPath) {
+      return { text: "⚠️ 请指定扫描路径" };
+    }
+
+    if (!existsSync(targetPath)) {
+      return { text: `⚠️ 路径不存在：${targetPath}` };
+    }
+
+    const isSingleSkill = existsSync(join(targetPath, "SKILL.md"));
+
+    if (isSingleSkill) {
+      const res = await runScan("scan", targetPath, {
+        detailed,
+        behavioral: useBehav,
+        apiUrl,
+        useLLM,
+        policy,
+      });
+      const icon = res.exitCode === 0 ? "✅" : "❌";
+      return { text: `${icon} 扫描完成\n\`\`\`\n${res.output}\n\`\`\`` };
+    } else {
+      const res = await runScan("batch", targetPath, {
+        recursive,
+        detailed,
+        behavioral: useBehav,
+        apiUrl,
+        useLLM,
+        policy,
+      });
+      const icon = res.exitCode === 0 ? "✅" : "❌";
+      return { text: `${icon} 批量扫描完成\n\`\`\`\n${res.output}\n\`\`\`` };
+    }
+  }
+
+  async function handleHealthCommand(): Promise<CommandResponse> {
+    const state = loadState();
+    const alerts: string[] = (state as any).pendingAlerts ?? [];
+
+    const lines = [
+      "✅ *Skills Scanner 状态*",
+      `API 地址：${apiUrl}`,
+      `安装前扫描：${preInstallScan === "on" ? `✅ 监听中 (${onUnsafe})` : "⏭️ 已禁用"}`,
+      `扫描策略：${policy}`,
+      `LLM 分析：${useLLM ? "✅ 启用" : "❌ 禁用"}`,
+      `行为分析：${behavioral ? "✅ 启用" : "❌ 禁用"}`,
+      `上次扫描：${state.lastScanAt ? new Date(state.lastScanAt).toLocaleString("zh-CN") : "从未"}`,
+      `扫描目录:\n${scanDirs.map((d) => `  📁 ${d}`).join("\n")}`,
+    ];
+
+    // API health check
+    lines.push("", "✅ *API 服务检查*");
+    try {
+      const res = await runScan("health", "", { apiUrl });
+      if (res.exitCode === 0) {
+        lines.push(`API 服务：✅ 正常`);
+        if (res.data) {
+          const healthData = res.data as any;
+          if (healthData.analyzers_available) {
+            lines.push(`可用分析器：${healthData.analyzers_available.join(", ")}`);
+          }
+        }
+      } else {
+        lines.push(`API 服务：⚠️ 不可用`);
+        lines.push(`错误：${res.output}`);
+      }
+    } catch (err: any) {
+      lines.push(`API 服务：⚠️ 连接失败`);
+      lines.push(`错误：${err.message}`);
+    }
+
+    if (alerts.length > 0) {
+      lines.push("", `⚠️ *待查告警 (${alerts.length} 条):*`);
+      alerts.slice(-5).forEach((a) => lines.push(`  ${a}`));
+      saveState({ ...state, pendingAlerts: [] });
+    }
+
+    lines.push("", "✅ *定时任务*");
+    if (state.cronJobId && state.cronJobId !== "manual-created") {
+      lines.push(`状态：✅ 已注册 (${state.cronJobId})`);
+    } else {
+      lines.push("状态：❌ 未注册");
+      lines.push("ℹ️ 使用 `/skills-scanner cron register` 注册");
+    }
+
+    return { text: lines.join("\n") };
+  }
+
+  async function handleConfigCommand(args: string): Promise<CommandResponse> {
+    const action = args.trim().toLowerCase() || "show";
+
+    if (action === "show" || action === "") {
+      const configGuide = generateConfigGuide(
+        cfg,
+        apiUrl,
+        scanDirs,
+        behavioral,
+        useLLM,
+        policy,
+        preInstallScan,
+        onUnsafe
+      );
+      return { text: "```\n" + configGuide + "\n```" };
+    } else if (action === "reset") {
+      const state = loadState() as any;
+      saveState({ ...state, configReviewed: false });
+      return {
+        text: "✅ 配置审查标记已重置\n下次重启 Gateway 时将再次显示配置向导",
+      };
+    } else {
+      return { text: "用法：`/skills-scanner config [show|reset]`" };
+    }
+  }
+
+  async function handleCronCommand(args: string): Promise<CommandResponse> {
+    const action = args.trim().toLowerCase() || "status";
+
+    if (action === "setup" || action === "register") {
+      try {
+        await ensureCronJobViaGateway({
+          logger,
+          callGateway,
+        });
+        return { text: "✅ 定时任务注册完成\n请查看日志了解详情" };
+      } catch (err: any) {
+        return { text: `⚠️ 定时任务注册失败：${err.message}` };
+      }
+    } else if (action === "unregister") {
+      try {
+        // 列出所有任务
+        const listResult = await callGateway("cron.list", {});
+        const jobs = Array.isArray(listResult?.jobs) ? listResult.jobs : [];
+        const existingJobs = jobs.filter((job: any) => job.name === "skills-weekly-report");
+
+        if (existingJobs.length === 0) {
+          return { text: "ℹ️ 未找到已注册的定时任务" };
+        }
+
+        // 删除所有同名任务
+        const deletedIds: string[] = [];
+        for (const job of existingJobs) {
+          const jobId = job.jobId || job.id;
+          try {
+            await callGateway("cron.remove", { jobId });
+            deletedIds.push(jobId);
+          } catch (err: any) {
+            logger.warn(`删除任务 ${jobId} 失败: ${err.message}`);
+          }
+        }
+
+        if (deletedIds.length > 0) {
+          return {
+            text: `✅ 已删除 ${deletedIds.length} 个定时任务\n${deletedIds.map(id => `- ${id}`).join("\n")}`,
+          };
+        } else {
+          return { text: "⚠️ 删除失败，请查看日志" };
+        }
+      } catch (err: any) {
+        return { text: `⚠️ 删除失败：${err.message}` };
+      }
+    } else {
+      // status
+      try {
+        const statusText = await checkCronJobStatus({
+          logger,
+          callGateway,
+        });
+        return { text: statusText };
+      } catch (err: any) {
+        return { text: `⚠️ 查询状态失败：${err.message}` };
+      }
+    }
+  }
+
+  function getHelpText(): string {
+    return [
+      "✅ *Skills Scanner - 帮助*",
+      "",
+      "═══ 扫描命令 ═══",
+      "`/skills-scanner scan <路径> [选项]`",
+      "`/skills-scanner scan clawhub <URL> [选项]`",
+      "",
+      "选项:",
+      "• `--detailed` - 显示详细发现",
+      "• `--behavioral` - 启用行为分析",
+      "• `--recursive` - 递归扫描子目录",
+      "• `--report` - 生成日报格式",
+      "",
+      "示例:",
+      "```",
+      "/skills-scanner scan ~/.openclaw/skills/my-skill",
+      "/skills-scanner scan ~/.openclaw/skills --recursive",
+      "/skills-scanner scan ~/.openclaw/skills --report",
+      "/skills-scanner scan clawhub https://clawhub.ai/username/project",
+      "/skills-scanner scan clawhub https://clawhub.ai/username/project --detailed",
+      "```",
+      "",
+      "═══ 其他命令 ═══",
+      "• `/skills-scanner health` - 健康检查",
+      "• `/skills-scanner config [show|reset]` - 配置管理",
+      "• `/skills-scanner cron [register|unregister|status]` - 定时任务管理",
+    ].join("\n");
+  }
+
+  return {
+    handleScanCommand,
+    handleHealthCommand,
+    handleConfigCommand,
+    handleCronCommand,
+    getHelpText,
+  };
+}

package/src/config-validator.ts

@@ -0,0 +1,110 @@
+/**
+ * Configuration validation module
+ */
+
+import { existsSync } from "node:fs";
+import type { ScannerConfig } from "./types.js";
+import type { PluginLogger } from "openclaw/plugin-sdk/plugin-entry";
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Validate plugin configuration
+ */
+export function validateConfig(
+  cfg: ScannerConfig,
+  logger: PluginLogger
+): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Validate API URL
+  if (cfg.apiUrl) {
+    try {
+      new URL(cfg.apiUrl);
+    } catch {
+      errors.push(`Invalid apiUrl: "${cfg.apiUrl}" is not a valid URL`);
+    }
+  }
+
+  // Validate scan directories
+  if (cfg.scanDirs && cfg.scanDirs.length > 0) {
+    for (const dir of cfg.scanDirs) {
+      if (!existsSync(dir)) {
+        warnings.push(`Scan directory does not exist: ${dir}`);
+      }
+    }
+  }
+
+  // Validate policy
+  if (cfg.policy && !["strict", "balanced", "permissive"].includes(cfg.policy)) {
+    errors.push(
+      `Invalid policy: "${cfg.policy}". Must be one of: strict, balanced, permissive`
+    );
+  }
+
+  // Validate preInstallScan
+  if (cfg.preInstallScan && !["on", "off"].includes(cfg.preInstallScan)) {
+    errors.push(
+      `Invalid preInstallScan: "${cfg.preInstallScan}". Must be "on" or "off"`
+    );
+  }
+
+  // Validate onUnsafe
+  if (cfg.onUnsafe && !["warn", "delete", "quarantine"].includes(cfg.onUnsafe)) {
+    errors.push(
+      `Invalid onUnsafe: "${cfg.onUnsafe}". Must be one of: warn, delete, quarantine`
+    );
+  }
+
+  // Validate reportDir if specified
+  if (cfg.reportDir && !existsSync(cfg.reportDir)) {
+    warnings.push(`Report directory does not exist: ${cfg.reportDir}`);
+  }
+
+  // Validate quarantineDir if specified
+  if (cfg.quarantineDir && !existsSync(cfg.quarantineDir)) {
+    warnings.push(`Quarantine directory does not exist: ${cfg.quarantineDir}`);
+  }
+
+  // Validate scanTimeoutMs
+  if (cfg.scanTimeoutMs !== undefined) {
+    if (typeof cfg.scanTimeoutMs !== "number" || cfg.scanTimeoutMs <= 0) {
+      errors.push(
+        `Invalid scanTimeoutMs: must be a positive number (milliseconds)`
+      );
+    } else if (cfg.scanTimeoutMs < 10000) {
+      warnings.push(
+        `scanTimeoutMs is very low (${cfg.scanTimeoutMs}ms). Scans may timeout prematurely.`
+      );
+    } else if (cfg.scanTimeoutMs > 600000) {
+      warnings.push(
+        `scanTimeoutMs is very high (${cfg.scanTimeoutMs}ms). Consider reducing for better responsiveness.`
+      );
+    }
+  }
+
+  // Log validation results
+  if (errors.length > 0) {
+    logger.error("[skills-scanner] Configuration validation failed", {
+      errors,
+    });
+  }
+
+  if (warnings.length > 0) {
+    logger.warn("[skills-scanner] Configuration warnings", {
+      warnings,
+    });
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+

package/src/config.ts

@@ -0,0 +1,230 @@
+/**
+ * 配置管理模块
+ */
+
+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"
+            }]
+          }
+        };
+      }
+
+      // 验证 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",
+      type: "string",
+      format: "uri",
+    },
+    scanDirs: {
+      label: "扫描目录",
+      help: "要监控的 Skills 目录列表，支持 ~ 路径。默认监控 ~/.openclaw/skills 和 ~/.openclaw/workspace/skills",
+      type: "array",
+      items: { type: "string" },
+    },
+    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",
+    },
+    preInstallScan: {
+      label: "安装前扫描",
+      help: "监听新 Skill 并自动扫描。启用后会实时监控 scanDirs 中的文件变化",
+      type: "string",
+      enum: ["on", "off"],
+      default: "on",
+    },
+    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,
+    },
+    enablePromptInjectionGuard: {
+      label: "提示注入防护",
+      help: "启用提示注入攻击防护，检测并阻止恶意提示",
+      type: "boolean",
+      default: false,
+    },
+    enableHighRiskOperationGuard: {
+      label: "高风险操作防护",
+      help: "启用高风险操作防护，对敏感操作进行额外检查",
+      type: "boolean",
+      default: false,
+    },
+    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,
+  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",
+    "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");
+}