@pwddd/skills-scanner 1.0.2

package/README.md

@@ -0,0 +1,138 @@
+# openclaw-skills-scanner
+
+OpenClaw Plugin，基于 [cisco-ai-skill-scanner](https://github.com/cisco-ai-defense/skill-scanner) 实现对 OpenClaw Skills 的安全扫描。
+
+## 功能
+
+| 功能 | 实现方式 | 状态 |
+|---|---|---|
+| 启动时自动安装 Python 依赖 | `registerService` | ✅ 全自动 |
+| `/scan-skill` `/scan-skills` 按需扫描 | `registerCommand` | ✅ 全自动 |
+| `/scan-report` 立即日报 | `registerCommand` | ✅ 全自动 |
+| `/scan-status` 状态查看 | `registerCommand` | ✅ 全自动 |
+| `openclaw skills-scan` CLI | `registerCli` | ✅ 全自动 |
+| 安装前扫描（新 Skill 出现时自动扫描） | `fs.watch` | ✅ 全自动 |
+| Gateway 启动时在日志里打印配置提示 | Plugin Hook `gateway:startup` | ✅ 全自动 |
+| 每日定期日报 | Cron Job | ⚠️ **需手动注册一次** |
+
+---
+
+## 安装
+
+```bash
+# 从本地目录安装
+openclaw plugins install ./openclaw-skills-scanner
+
+# 或从 npm 安装（发布后）
+openclaw plugins install @yourscope/openclaw-skills-scanner
+
+# 重启 Gateway（Plugin 变更必须重启）
+openclaw gateway restart
+```
+
+重启后 Gateway 会自动：
+1. 创建 Python venv 并安装 `cisco-ai-skill-scanner`
+2. 开始监听 Skills 目录（安装前扫描）
+3. 在启动日志里打印是否需要注册 Cron Job
+
+---
+
+## 注册每日日报（一次性操作）
+
+Plugin 无法自动注册 Cron Job（OpenClaw Plugin API 不提供此能力），需要手动执行一次：
+
+```bash
+openclaw cron add \
+  --name "skills-daily-report" \
+  --cron "0 8 * * *" \
+  --tz "Asia/Shanghai" \
+  --session isolated \
+  --message "请执行 /scan-report 并把结果发送到此渠道" \
+  --announce
+```
+
+想投递到特定渠道（如 Telegram）：
+
+```bash
+openclaw cron add \
+  --name "skills-daily-report" \
+  --cron "0 8 * * *" \
+  --tz "Asia/Shanghai" \
+  --session isolated \
+  --message "请执行 /scan-report 并把结果发送到此渠道" \
+  --announce \
+  --channel telegram \
+  --to "+8613312345678"
+```
+
+验证已注册：
+
+```bash
+openclaw cron list
+```
+
+---
+
+## 聊天命令
+
+| 命令 | 说明 |
+|---|---|
+| `/scan-skill <路径>` | 扫描单个 Skill 目录 |
+| `/scan-skill <路径> --detailed` | 显示完整 findings |
+| `/scan-skill <路径> --behavioral` | 启用 AST 行为分析 |
+| `/scan-skills <目录>` | 批量扫描目录 |
+| `/scan-skills <目录> --recursive` | 递归扫描子目录 |
+| `/scan-report` | 立即执行全量扫描并输出日报 |
+| `/scan-status` | 查看状态、待查告警、Cron 注册命令 |
+
+---
+
+## 安装前扫描说明
+
+Plugin 启动后用 `fs.watch` 监听所有 Skills 目录。任何新 Skill 出现（无论通过 `clawhub install`、CLI 还是手动复制）都会触发扫描。
+
+扫描结果通过 `persistWatcherAlert` 写入 `~/.openclaw/skills-scanner/state.json`，运行 `/scan-status` 查看并清空告警列表。
+
+> **为什么不直接发聊天消息？**
+> OpenClaw Plugin API 没有提供在后台任务里主动推送消息给用户的方法。`event.messages.push()` 只在 Hook handler 的同步上下文中有效，`registerCommand` 的 handler 需要用户主动触发。这是平台限制，不是实现缺陷。
+
+处置方式通过 `onUnsafe` 配置：
+
+| 值 | 行为 |
+|---|---|
+| `"quarantine"`（默认）| 移入 `~/.openclaw/skills-scanner/quarantine/` |
+| `"delete"` | 直接删除 |
+| `"warn"` | 仅写告警日志，保留文件 |
+
+---
+
+## 配置
+
+```jsonc
+// ~/.openclaw/openclaw.json
+{
+  "plugins": {
+    "entries": {
+      "skills-scanner": {
+        "enabled": true,
+        "config": {
+          "scanDirs": ["~/.openclaw/skills"],   // 留空自动检测
+          "behavioral": false,                  // 行为分析（较慢）
+          "preInstallScan": "on",               // fs.watch 安装前扫描
+          "onUnsafe": "quarantine"              // quarantine | delete | warn
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## 发布到 npm
+
+```bash
+# 修改 package.json 里的 name 为你的 scope
+npm login
+npm publish --access public
+```

package/index.ts

@@ -0,0 +1,488 @@
+/**
+ * OpenClaw Plugin: skills-scanner
+ *
+ * 已确认可用的功能（全部有文档依据）：
+ * 1. registerService  — 启动时自动安装 Python 依赖（uv venv）
+ * 2. registerCommand  — 聊天命令 /scan-skill /scan-skills /scan-report /scan-status
+ * 3. registerGatewayMethod — RPC 供 Control UI 调用
+ * 4. registerCli      — CLI 命令 openclaw skills-scan
+ * 5. registerPluginHooksFromDir — 捆绑 gateway:startup hook（日报提醒）
+ * 6. skills/ 目录     — 捆绑内置 Skill
+ * 7. fs.watch         — 监听 Skills 目录，新 Skill 出现后立即扫描（安装前扫描）
+ *
+ * 已删除的不实功能：
+ * - api.registerPluginHook()         ← 该方法不存在
+ * - api.runtime.gateway.call()       ← 文档无记录
+ * - api.runtime.gateway.call("cron.add") ← 文档无记录
+ * - message:preprocessed hook 拦截   ← 该事件不存在
+ *
+ * Cron 日报：需用户安装后手动执行一次 CLI 命令注册（见 README）。
+ */
+
+import { execSync, exec } from "child_process";
+import {
+  existsSync, readFileSync, writeFileSync,
+  mkdirSync, watch as fsWatch, renameSync, rmSync,
+} from "fs";
+import { join, basename } from "path";
+import { homedir } from "os";
+import { promisify } from "util";
+
+const execAsync = promisify(exec);
+
+const PLUGIN_ROOT  = __dirname;
+const SKILL_DIR    = join(PLUGIN_ROOT, "skills", "skills-scanner");
+const VENV_PYTHON  = join(SKILL_DIR, ".venv", "bin", "python");
+const SCAN_SCRIPT  = join(SKILL_DIR, "scan.py");
+const STATE_DIR    = join(homedir(), ".openclaw", "skills-scanner");
+const STATE_FILE   = join(STATE_DIR, "state.json");
+const QUARANTINE_DIR = join(STATE_DIR, "quarantine");
+
+// ── 型別 ──────────────────────────────────────────────────────────────────────
+
+interface ScannerConfig {
+  /** 扫描目录列表，默认自动检测 */
+  scanDirs?: string[];
+  /** 是否启用行为分析（较慢但更准确） */
+  behavioral?: boolean;
+  /**
+   * 安装前扫描（fs.watch）：
+   * - "on"  监听所有 scanDirs（默认）
+   * - "off" 禁用
+   */
+  preInstallScan?: "on" | "off";
+  /**
+   * 发现不安全 Skill 时的处理方式：
+   * - "quarantine" 移入隔离目录（默认）
+   * - "delete"     直接删除
+   * - "warn"       仅警告，保留文件
+   */
+  onUnsafe?: "quarantine" | "delete" | "warn";
+}
+
+interface ScanState {
+  lastScanAt?: string;
+  lastUnsafeSkills?: string[];
+}
+
+// ── 工具函数 ──────────────────────────────────────────────────────────────────
+
+function hasUv(): boolean {
+  try { execSync("uv --version", { stdio: "ignore" }); return true; }
+  catch { return false; }
+}
+
+function isVenvReady(): boolean {
+  return existsSync(VENV_PYTHON);
+}
+
+function expandPath(p: string): string {
+  return p.replace(/^~/, homedir());
+}
+
+function defaultScanDirs(): string[] {
+  return [
+    join(homedir(), ".openclaw", "skills"),
+    join(homedir(), ".openclaw", "workspace", "skills"),
+  ].filter(existsSync);
+}
+
+function loadState(): ScanState {
+  try { return JSON.parse(readFileSync(STATE_FILE, "utf-8")); }
+  catch { return {}; }
+}
+
+function saveState(s: ScanState) {
+  mkdirSync(STATE_DIR, { recursive: true });
+  writeFileSync(STATE_FILE, JSON.stringify(s, null, 2));
+}
+
+async function ensureDeps(logger: any): Promise<boolean> {
+  if (isVenvReady()) {
+    logger.info("[skills-scanner] Python 依赖已就绪");
+    return true;
+  }
+  if (!hasUv()) {
+    logger.warn("[skills-scanner] uv 未安装：brew install uv 或 curl -LsSf https://astral.sh/uv/install.sh | sh");
+    return false;
+  }
+  logger.info("[skills-scanner] 首次启动，正在安装 cisco-ai-skill-scanner...");
+  try {
+    await execAsync(`uv venv "${join(SKILL_DIR, ".venv")}" --python 3.10 --quiet`);
+    await execAsync(`uv pip install --python "${VENV_PYTHON}" cisco-ai-skill-scanner --quiet`);
+    logger.info("[skills-scanner] ✅ 依赖安装完成");
+    return true;
+  } catch (err: any) {
+    logger.warn(`[skills-scanner] ⚠️  依赖安装失败: ${err.message}`);
+    return false;
+  }
+}
+
+async function runScan(
+  mode: "scan" | "batch",
+  target: string,
+  opts: { detailed?: boolean; behavioral?: boolean; recursive?: boolean; jsonOut?: string } = {}
+): Promise<{ exitCode: number; output: string }> {
+  const args = [mode, target];
+  if (opts.detailed)   args.push("--detailed");
+  if (opts.behavioral) args.push("--behavioral");
+  if (opts.recursive)  args.push("--recursive");
+  if (opts.jsonOut)    args.push("--json", opts.jsonOut);
+
+  const cmd = `"${VENV_PYTHON}" "${SCAN_SCRIPT}" ${args.map(a => `"${a}"`).join(" ")}`;
+  try {
+    const { stdout, stderr } = await execAsync(cmd, { timeout: 180_000 });
+    return { exitCode: 0, output: (stdout + stderr).trim() };
+  } catch (err: any) {
+    return { exitCode: err.code ?? 1, output: (err.stdout + err.stderr || "").trim() || err.message };
+  }
+}
+
+// ── 日报 ──────────────────────────────────────────────────────────────────────
+
+async function buildDailyReport(dirs: string[], behavioral: boolean, logger: any): Promise<string> {
+  const now     = new Date();
+  const dateStr = now.toLocaleDateString("zh-CN", { year: "numeric", month: "2-digit", day: "2-digit" });
+  const timeStr = now.toLocaleTimeString("zh-CN", { hour: "2-digit", minute: "2-digit" });
+  const jsonOut = join(STATE_DIR, `report-${now.toISOString().slice(0, 10)}.json`);
+  mkdirSync(STATE_DIR, { recursive: true });
+
+  let total = 0, safe = 0, unsafe = 0, errors = 0;
+  const unsafeList: string[] = [];
+  const allResults: any[] = [];
+
+  for (const dir of dirs) {
+    const expanded = expandPath(dir);
+    if (!existsSync(expanded)) continue;
+    const tmpJson = join(STATE_DIR, `tmp-${Date.now()}.json`);
+    await runScan("batch", expanded, { behavioral, recursive: true, jsonOut: tmpJson });
+    try {
+      const rows: any[] = JSON.parse(readFileSync(tmpJson, "utf-8"));
+      try { rmSync(tmpJson); } catch {}
+      for (const r of rows) {
+        allResults.push(r);
+        total++;
+        if (r.error)        errors++;
+        else if (r.is_safe) safe++;
+        else { unsafe++; unsafeList.push(r.name || basename(r.path ?? "")); }
+      }
+    } catch { logger.warn(`[skills-scanner] 无法解析 ${tmpJson}`); }
+  }
+
+  writeFileSync(jsonOut, JSON.stringify(allResults, null, 2));
+  saveState({ ...loadState(), lastScanAt: now.toISOString(), lastUnsafeSkills: unsafeList });
+
+  const lines = [
+    `🔍 *Skills 安全日报* — ${dateStr} ${timeStr}`,
+    "─".repeat(36),
+  ];
+  if (total === 0) {
+    lines.push("📭 未找到任何 Skill，请检查扫描目录。");
+  } else {
+    lines.push(`📊 扫描总计：${total} 个 Skill`);
+    lines.push(`✅ 安全：${safe} 个`);
+    lines.push(`❌ 问题：${unsafe} 个`);
+    if (errors) lines.push(`⚠️  错误：${errors} 个`);
+    if (unsafe > 0) {
+      lines.push("", "🚨 *需要关注的 Skills：*");
+      for (const name of unsafeList) {
+        const r = allResults.find(x => (x.name || basename(x.path ?? "")) === name);
+        lines.push(`  • ${name} [${r?.max_severity ?? "?"}] — ${r?.findings ?? "?"} 条发现`);
+      }
+      lines.push("", "💡 运行 `/scan-skill <路径> --detailed` 查看详情");
+    } else {
+      lines.push("", "🎉 所有 Skills 安全，未发现威胁。");
+    }
+  }
+  lines.push("", `📁 完整报告：${jsonOut}`);
+  return lines.join("\n");
+}
+
+// ── 安装前扫描（fs.watch）────────────────────────────────────────────────────
+
+async function handleNewSkill(
+  skillPath: string,
+  onUnsafe: "quarantine" | "delete" | "warn",
+  behavioral: boolean,
+  notifyFn: (msg: string) => void,
+  logger: any
+) {
+  if (!existsSync(join(skillPath, "SKILL.md"))) return; // 不是合法 Skill
+  const name = basename(skillPath);
+  logger.info(`[skills-scanner] 🔍 检测到新 Skill，开始安装前扫描: ${name}`);
+  notifyFn(`🔍 检测到新 Skill \`${name}\`，正在安全扫描...`);
+
+  const res = await runScan("scan", skillPath, { behavioral, detailed: true });
+
+  if (res.exitCode === 0) {
+    notifyFn(`✅ \`${name}\` 安全检查通过，可以正常使用。`);
+    return;
+  }
+
+  // 不安全 — 按配置处置
+  let action = "";
+  try {
+    if (onUnsafe === "quarantine") {
+      mkdirSync(QUARANTINE_DIR, { recursive: true });
+      const dest = join(QUARANTINE_DIR, `${name}-${Date.now()}`);
+      renameSync(skillPath, dest);
+      action = `已移入隔离目录：\`${dest}\``;
+    } else if (onUnsafe === "delete") {
+      rmSync(skillPath, { recursive: true, force: true });
+      action = "已自动删除";
+    } else {
+      action = "仅警告，Skill 已保留（请谨慎使用）";
+    }
+  } catch (e: any) {
+    action = `处置失败：${e.message}`;
+  }
+
+  notifyFn([
+    `❌ *安全警告：\`${name}\` 未通过扫描*`,
+    `处置：${action}`,
+    "```",
+    res.output.slice(0, 600),
+    "```",
+  ].join("\n"));
+}
+
+function startWatcher(
+  dirs: string[],
+  onUnsafe: "quarantine" | "delete" | "warn",
+  behavioral: boolean,
+  notifyFn: (msg: string) => void,
+  logger: any
+): () => void {
+  const timers = new Map<string, NodeJS.Timeout>();
+
+  const watchers = dirs.map(dir => {
+    const expanded = expandPath(dir);
+    if (!existsSync(expanded)) mkdirSync(expanded, { recursive: true });
+    logger.info(`[skills-scanner] 👁  监听目录：${expanded}`);
+
+    return fsWatch(expanded, { persistent: false }, (_evt, filename) => {
+      if (!filename) return;
+      const skillPath = join(expanded, filename);
+      if (!existsSync(skillPath)) return;
+
+      // 防抖 500ms，等文件写入完毕
+      const prev = timers.get(skillPath);
+      if (prev) clearTimeout(prev);
+      timers.set(skillPath, setTimeout(() => {
+        timers.delete(skillPath);
+        handleNewSkill(skillPath, onUnsafe, behavioral, notifyFn, logger);
+      }, 500));
+    });
+  });
+
+  return () => {
+    watchers.forEach(w => w.close());
+    timers.forEach(t => clearTimeout(t));
+    timers.clear();
+    logger.info("[skills-scanner] 目录监听已停止");
+  };
+}
+
+// ── Plugin 入口 ───────────────────────────────────────────────────────────────
+
+export default function register(api: any) {
+  const cfg: ScannerConfig = api.config?.plugins?.entries?.["skills-scanner"]?.config ?? {};
+  const scanDirs       = (cfg.scanDirs?.map(expandPath) ?? []).filter(existsSync).length > 0
+    ? (cfg.scanDirs!.map(expandPath))
+    : defaultScanDirs();
+  const behavioral     = cfg.behavioral     ?? false;
+  const preInstallScan = cfg.preInstallScan ?? "on";
+  const onUnsafe       = cfg.onUnsafe       ?? "quarantine";
+
+  // 向聊天发消息的辅助（用于 watcher 通知）——使用 registerCommand handler
+  // 文档确认：registerCommand handler 可以直接 return { text }，
+  // 但 watcher 是异步后台任务，没有 handler context。
+  // 唯一有文档依据的方式：写入 event.messages（仅限 hook handler 内）。
+  // 这里退而求其次：写到日志 + 持久化到 STATE_FILE，让用户可通过 /scan-status 查看。
+  function persistWatcherAlert(msg: string) {
+    const state = loadState();
+    const alerts: string[] = (state as any).pendingAlerts ?? [];
+    alerts.push(`[${new Date().toLocaleString("zh-CN")}] ${msg}`);
+    saveState({ ...state, pendingAlerts: alerts } as any);
+    api.logger.warn(`[skills-scanner] ${msg}`);
+  }
+
+  // ── 1. 后台服务：安装依赖 + 启动 watcher ─────────────────────────────────
+  let stopWatcher: (() => void) | null = null;
+
+  api.registerService({
+    id: "skills-scanner-setup",
+    start: async () => {
+      await ensureDeps(api.logger);
+
+      if (preInstallScan === "on" && scanDirs.length > 0) {
+        stopWatcher = startWatcher(scanDirs, onUnsafe, behavioral, persistWatcherAlert, api.logger);
+      }
+    },
+    stop: () => { stopWatcher?.(); stopWatcher = null; },
+  });
+
+  // ── 2. Startup logging ────────────────────────────────────────────────────
+  // 在 Gateway 启动时输出配置提示
+  api.logger.info("[skills-scanner] Plugin 已加载");
+  api.logger.info(`[skills-scanner] 安装前扫描：${preInstallScan === "on" ? `✅ 监听 ${scanDirs.length} 个目录` : "❌ 已禁用"}`);
+  
+  // 检查是否需要注册 Cron Job
+  const state = loadState() as any;
+  if (!state.cronJobId) {
+    api.logger.warn("[skills-scanner] ⚠️  未检测到日报 Cron Job，请手动注册一次：");
+    api.logger.info('[skills-scanner]   openclaw cron add --name "skills-daily-report" --cron "0 8 * * *" --tz "Asia/Shanghai" --session isolated --message "请执行 /scan-report 并把结果发送到此渠道" --announce');
+  }
+
+  // ── 3. /scan-skill ────────────────────────────────────────────────────────
+  api.registerCommand({
+    name: "scan-skill",
+    description: "扫描单个 Skill 目录。用法: /scan-skill <路径> [--detailed] [--behavioral]",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: async (ctx: any) => {
+      const raw = (ctx.args ?? "").trim();
+      if (!raw) return { text: "用法：`/scan-skill <路径> [--detailed] [--behavioral]`" };
+      if (!isVenvReady()) return { text: "⏳ Python 依赖尚未就绪，请稍后重试" };
+
+      const parts      = raw.split(/\s+/);
+      const skillPath  = expandPath(parts.find(p => !p.startsWith("--")) ?? "");
+      const detailed   = parts.includes("--detailed");
+      const useBehav   = parts.includes("--behavioral") || behavioral;
+
+      const res = await runScan("scan", skillPath, { detailed, behavioral: useBehav });
+      const icon = res.exitCode === 0 ? "✅" : "❌";
+      return { text: `${icon} 扫描完成\n\`\`\`\n${res.output}\n\`\`\`` };
+    },
+  });
+
+  // ── 4. /scan-skills ───────────────────────────────────────────────────────
+  api.registerCommand({
+    name: "scan-skills",
+    description: "批量扫描目录下所有 Skills。用法: /scan-skills <目录> [--recursive] [--detailed]",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: async (ctx: any) => {
+      const raw = (ctx.args ?? "").trim();
+      if (!raw) return { text: "用法：`/scan-skills <目录> [--recursive] [--detailed]`" };
+      if (!isVenvReady()) return { text: "⏳ Python 依赖尚未就绪，请稍后重试" };
+
+      const parts     = raw.split(/\s+/);
+      const dirPath   = expandPath(parts.find(p => !p.startsWith("--")) ?? "");
+      const recursive = parts.includes("--recursive");
+      const detailed  = parts.includes("--detailed");
+      const useBehav  = parts.includes("--behavioral") || behavioral;
+
+      const res = await runScan("batch", dirPath, { recursive, detailed, behavioral: useBehav });
+      const icon = res.exitCode === 0 ? "✅" : "❌";
+      return { text: `${icon} 批量扫描完成\n\`\`\`\n${res.output}\n\`\`\`` };
+    },
+  });
+
+  // ── 5. /scan-report ───────────────────────────────────────────────────────
+  api.registerCommand({
+    name: "scan-report",
+    description: "立即执行全量扫描并生成安全日报",
+    acceptsArgs: false,
+    requireAuth: true,
+    handler: async (_ctx: any) => {
+      if (!isVenvReady()) return { text: "⏳ Python 依赖尚未就绪，请稍后重试" };
+      if (scanDirs.length === 0) return { text: "⚠️ 未找到可扫描目录，请检查配置" };
+      const report = await buildDailyReport(scanDirs, behavioral, api.logger);
+      return { text: report };
+    },
+  });
+
+  // ── 6. /scan-status ───────────────────────────────────────────────────────
+  api.registerCommand({
+    name: "scan-status",
+    description: "查看 Skills Scanner 状态和待查告警",
+    acceptsArgs: false,
+    requireAuth: true,
+    handler: (_ctx: any) => {
+      const state = loadState() as any;
+      const alerts: string[] = state.pendingAlerts ?? [];
+
+      const lines = [
+        "📋 *Skills Scanner 状态*",
+        `Python 依赖：${isVenvReady() ? "✅ 就绪" : "❌ 未就绪"}`,
+        `安装前扫描：${preInstallScan === "on" ? `✅ 监听中（${onUnsafe}）` : "❌ 已禁用"}`,
+        `上次扫描：${state.lastScanAt ? new Date(state.lastScanAt).toLocaleString("zh-CN") : "从未"}`,
+        `上次问题 Skills：${state.lastUnsafeSkills?.length ? state.lastUnsafeSkills.join(", ") : "无"}`,
+        `扫描目录：\n${scanDirs.map(d => `  • ${d}`).join("\n")}`,
+      ];
+
+      if (alerts.length > 0) {
+        lines.push("", `🔔 *待查告警（${alerts.length} 条）：*`);
+        alerts.slice(-5).forEach(a => lines.push(`  ${a}`));
+        // 读取后清空
+        saveState({ ...state, pendingAlerts: [] });
+      }
+
+      lines.push(
+        "",
+        "定期日报（需手动注册一次）：",
+        "```",
+        "openclaw cron add \\",
+        '  --name "skills-daily-report" \\',
+        '  --cron "0 8 * * *" --tz "Asia/Shanghai" \\',
+        "  --session isolated \\",
+        '  --message "请执行 /scan-report 并把结果发送到此渠道" \\',
+        "  --announce",
+        "```",
+      );
+      return { text: lines.join("\n") };
+    },
+  });
+
+  // ── 7. Gateway RPC ────────────────────────────────────────────────────────
+  api.registerGatewayMethod("skillsScanner.scan", async ({ respond, params }: any) => {
+    const { path: p, mode = "scan", recursive = false, detailed = false } = params ?? {};
+    if (!p)             return respond(false, { error: "缺少 path 参数" });
+    if (!isVenvReady()) return respond(false, { error: "Python 依赖未就绪" });
+    const res = await runScan(mode === "batch" ? "batch" : "scan", expandPath(p), { recursive, detailed, behavioral });
+    respond(res.exitCode === 0, { output: res.output, exitCode: res.exitCode, is_safe: res.exitCode === 0 });
+  });
+
+  api.registerGatewayMethod("skillsScanner.report", async ({ respond }: any) => {
+    if (!isVenvReady())          return respond(false, { error: "Python 依赖未就绪" });
+    if (scanDirs.length === 0)   return respond(false, { error: "未找到可扫描目录" });
+    const report = await buildDailyReport(scanDirs, behavioral, api.logger);
+    respond(true, { report, state: loadState() });
+  });
+
+  // ── 8. CLI ────────────────────────────────────────────────────────────────
+  api.registerCli(({ program }: any) => {
+    const cmd = program.command("skills-scan").description("OpenClaw Skills 安全扫描");
+
+    cmd.command("scan <path>")
+      .description("扫描单个 Skill")
+      .option("--detailed",   "显示所有 findings")
+      .option("--behavioral", "启用行为分析")
+      .action(async (p: string, opts: any) => {
+        const res = await runScan("scan", expandPath(p), opts);
+        console.log(res.output);
+        process.exit(res.exitCode);
+      });
+
+    cmd.command("batch <directory>")
+      .description("批量扫描目录")
+      .option("--recursive",  "递归子目录")
+      .option("--detailed",   "显示所有 findings")
+      .option("--behavioral", "启用行为分析")
+      .action(async (d: string, opts: any) => {
+        const res = await runScan("batch", expandPath(d), opts);
+        console.log(res.output);
+        process.exit(res.exitCode);
+      });
+
+    cmd.command("report")
+      .description("立即执行全量扫描并打印日报")
+      .action(async () => {
+        const report = await buildDailyReport(scanDirs, behavioral, console);
+        console.log(report);
+      });
+  }, { commands: ["skills-scan"] });
+
+  api.logger.info("[skills-scanner] Plugin 已注册 ✅");
+}

package/openclaw.plugin.json

@@ -0,0 +1,40 @@
+{
+  "id": "skills-scanner",
+  "name": "Skills Security Scanner",
+  "description": "Skills 安全扫描：安装前扫描（fs.watch）、按需扫描、安全日报",
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "scanDirs": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "扫描目录列表，留空自动检测 ~/.openclaw/skills"
+      },
+      "behavioral": {
+        "type": "boolean",
+        "default": false,
+        "description": "启用 AST 行为分析（更准确但较慢）"
+      },
+      "preInstallScan": {
+        "type": "string",
+        "enum": ["on", "off"],
+        "default": "on",
+        "description": "是否启用 fs.watch 安装前扫描"
+      },
+      "onUnsafe": {
+        "type": "string",
+        "enum": ["quarantine", "delete", "warn"],
+        "default": "quarantine",
+        "description": "发现不安全 Skill 时的处置：隔离 / 删除 / 仅警告"
+      }
+    }
+  },
+  "uiHints": {
+    "scanDirs":       { "label": "扫描目录（留空自动检测）" },
+    "behavioral":     { "label": "启用行为分析器" },
+    "preInstallScan": { "label": "安装前扫描（fs.watch）" },
+    "onUnsafe":       { "label": "不安全 Skill 的处置方式" }
+  }
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@pwddd/skills-scanner",
+  "version": "1.0.2",
+  "description": "OpenClaw Plugin：Skills 安全扫描、安装前拦截、安全日报",
+  "main": "index.ts",
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "hooks/**",
+    "skills/**"
+  ],
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  },
+  "keywords": ["openclaw", "openclaw-plugin", "security", "skill-scanner"],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/skills-scanner/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: skills-scanner
+description: Security scanner for OpenClaw Skills using Cisco AI Skill Scanner. Supports single skill scan and batch scan of multiple skills.
+version: 1.0.0
+user-invocable: true
+metadata: {"openclaw": {"emoji": "🔍", "requires": {"bins": ["uv", "python3"]}, "install": [{"id": "uv-brew", "kind": "brew", "formula": "uv", "bins": ["uv"], "label": "Install uv (macOS)", "os": ["darwin"]}, {"id": "uv-curl", "kind": "download", "url": "https://astral.sh/uv/install.sh", "label": "Install uv (Linux)", "os": ["linux"]}]}}
+---
+
+# Skills Security Scanner 🔍
+
+使用 Cisco AI Skill Scanner 对 OpenClaw Skills 进行安全扫描，检测恶意代码、数据窃取、提示注入等威胁。
+
+## 环境准备（首次使用）
+
+在首次运行任何扫描命令前，先检查并安装依赖：
+
+```bash
+# 检查 uv 是否可用
+which uv || echo "请先安装 uv: brew install uv 或 curl -LsSf https://astral.sh/uv/install.sh | sh"
+
+# 安装 cisco-ai-skill-scanner 到隔离虚拟环境
+uv venv {baseDir}/.venv --python 3.10 --quiet
+uv pip install --python {baseDir}/.venv/bin/python cisco-ai-skill-scanner --quiet
+```
+
+安装只需执行一次，后续直接使用即可。
+
+---
+
+## 单个 Skill 扫描
+
+**触发词**: 用户说"扫描 skill"、"检查这个 skill"、"scan skill"、"安全检查 [路径]"
+
+### 基础扫描（推荐，速度快）
+
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py scan <skill路径>
+```
+
+### 详细模式（显示所有 findings）
+
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py scan <skill路径> --detailed
+```
+
+### 深度扫描（加入行为分析）
+
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py scan <skill路径> --detailed --behavioral
+```
+
+### 最强扫描（加入 LLM 语义分析，需要 API Key）
+
+在使用 `--llm` 前，确认环境变量已设置：
+```bash
+export SKILL_SCANNER_LLM_API_KEY="your-api-key"
+export SKILL_SCANNER_LLM_MODEL="claude-3-5-sonnet-20241022"
+```
+然后运行：
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py scan <skill路径> --detailed --behavioral --llm
+```
+
+---
+
+## 批量扫描
+
+**触发词**: 用户说"批量扫描"、"扫描所有 skills"、"scan all"、"检查 skills 目录"
+
+### 扫描指定目录下的所有 Skills
+
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py batch <目录路径>
+```
+
+### 递归扫描（含子目录）
+
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py batch <目录路径> --recursive
+```
+
+### 批量扫描并输出 JSON 报告
+
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py batch <目录路径> --detailed --json /tmp/scan-report.json
+```
+
+### 常用目录示例
+
+扫描 OpenClaw 默认 skills 目录：
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py batch ~/.openclaw/skills
+```
+
+扫描 workspace skills：
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py batch ~/.openclaw/workspace/skills --recursive
+```
+
+---
+
+## 结果解读
+
+| 状态 | 含义 |
+|------|------|
+| ✅ 安全 | 未检测到 HIGH/CRITICAL 问题，可正常使用 |
+| ⚠️ 需关注 | 存在 LOW/MEDIUM 问题，建议人工复核 |
+| ❌ 发现问题 | 存在 HIGH/CRITICAL 威胁，**强烈建议不要安装** |
+
+### 严重级别说明
+
+- **CRITICAL**: 主动利用尝试（数据窃取、代码注入）
+- **HIGH**: 危险模式（提示注入、未授权访问）
+- **MEDIUM**: 可疑行为（未声明的能力、误导性描述）
+- **LOW**: 轻微风险，需人工判断
+
+---
+
+## 参数说明
+
+| 参数 | 说明 |
+|------|------|
+| `--detailed` | 显示每条 finding 的完整详情 |
+| `--behavioral` | 启用 AST 数据流分析（更准确，稍慢） |
+| `--llm` | 启用 LLM 语义分析（最准确，需 API Key） |
+| `--recursive` | 批量扫描时递归子目录 |
+| `--json <文件>` | 将结果保存为 JSON 文件 |
+
+---
+
+## 注意事项
+
+- **扫描结果不等于安全保证**。`is_safe=True` 表示未检测到已知威胁模式，不代表 skill 绝对安全。
+- 扫描使用静态分析，不会执行任何 skill 中的代码。
+- 如需 LLM 分析，任何兼容 OpenAI 格式的 API Key 均可使用（Anthropic、OpenAI、Azure 等）。
+- 退出码 `0` 表示安全，`1` 表示存在问题（便于 CI/CD 集成）。

package/skills/skills-scanner/scan.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+# /// script
+# dependencies = [
+#   "cisco-ai-skill-scanner>=0.1.0",
+# ]
+# ///
+"""
+OpenClaw Skills Security Scanner
+基于 cisco-ai-skill-scanner，支持单个/批量扫描
+"""
+
+import sys
+import os
+import json
+import argparse
+from pathlib import Path
+
+# ── 依赖检查 ──────────────────────────────────────────────────────────────────
+try:
+    from skill_scanner import SkillScanner
+    from skill_scanner.core.analyzers import (
+        StaticAnalyzer,
+        BehavioralAnalyzer,
+        PipelineAnalyzer,
+    )
+except ImportError:
+    print("❌ cisco-ai-skill-scanner 未安装。")
+    print("   请运行: uv pip install cisco-ai-skill-scanner")
+    sys.exit(1)
+
+
+# ── 颜色输出 ──────────────────────────────────────────────────────────────────
+USE_COLOR = sys.stdout.isatty()
+
+def c(text, code):
+    return f"\033[{code}m{text}\033[0m" if USE_COLOR else text
+
+RED    = lambda t: c(t, "31")
+YELLOW = lambda t: c(t, "33")
+GREEN  = lambda t: c(t, "32")
+CYAN   = lambda t: c(t, "36")
+BOLD   = lambda t: c(t, "1")
+DIM    = lambda t: c(t, "2")
+
+
+# ── 严重级别 ──────────────────────────────────────────────────────────────────
+SEVERITY_COLORS = {
+    "CRITICAL": RED,
+    "HIGH":     RED,
+    "MEDIUM":   YELLOW,
+    "LOW":      GREEN,
+    "INFO":     CYAN,
+}
+
+def severity_label(sev: str) -> str:
+    sev = (sev or "INFO").upper()
+    color = SEVERITY_COLORS.get(sev, CYAN)
+    return color(f"[{sev}]")
+
+
+# ── 构建 Scanner ──────────────────────────────────────────────────────────────
+def build_scanner(use_behavioral: bool = False, use_llm: bool = False) -> SkillScanner:
+    analyzers = [StaticAnalyzer(), PipelineAnalyzer()]
+    if use_behavioral:
+        analyzers.append(BehavioralAnalyzer())
+    if use_llm:
+        try:
+            from skill_scanner.core.analyzers import LLMAnalyzer
+            api_key = os.environ.get("SKILL_SCANNER_LLM_API_KEY")
+            if not api_key:
+                print(YELLOW("⚠️  未设置 SKILL_SCANNER_LLM_API_KEY，跳过 LLM 分析器"))
+            else:
+                analyzers.append(LLMAnalyzer())
+        except ImportError:
+            print(YELLOW("⚠️  LLM 分析器不可用，请安装: pip install cisco-ai-skill-scanner[llm]"))
+    return SkillScanner(analyzers=analyzers)
+
+
+# ── 单个 Skill 扫描 ───────────────────────────────────────────────────────────
+def scan_single(path: str, args) -> dict:
+    skill_path = Path(path).expanduser().resolve()
+
+    if not skill_path.exists():
+        return {"path": str(skill_path), "error": "路径不存在", "is_safe": False}
+
+    if not skill_path.is_dir():
+        return {"path": str(skill_path), "error": "必须是目录（Skill 文件夹）", "is_safe": False}
+
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        return {"path": str(skill_path), "error": "未找到 SKILL.md，不是合法的 Skill", "is_safe": False}
+
+    print(f"\n{BOLD('🔍 扫描:')} {CYAN(str(skill_path))}")
+
+    scanner = build_scanner(
+        use_behavioral=getattr(args, "behavioral", False),
+        use_llm=getattr(args, "llm", False),
+    )
+
+    result = scanner.scan_skill(str(skill_path))
+    findings = result.findings if hasattr(result, "findings") else []
+    max_sev   = str(result.max_severity) if hasattr(result, "max_severity") else "UNKNOWN"
+    is_safe   = bool(result.is_safe) if hasattr(result, "is_safe") else len(findings) == 0
+
+    # 状态行
+    if is_safe:
+        status = GREEN("✅ 安全")
+    else:
+        status = RED("❌ 发现问题") if max_sev in ("CRITICAL", "HIGH") else YELLOW("⚠️  需关注")
+
+    print(f"  状态: {status}  |  最高严重级别: {severity_label(max_sev)}  |  发现: {len(findings)} 条")
+
+    # 详细 findings
+    if findings and getattr(args, "detailed", False):
+        print(f"\n  {BOLD('发现详情:')}")
+        for i, f in enumerate(findings, 1):
+            sev  = str(getattr(f, "severity", "INFO")).upper()
+            name = getattr(f, "rule_id", getattr(f, "name", "unknown"))
+            desc = getattr(f, "description", getattr(f, "message", ""))
+            loc  = getattr(f, "location", getattr(f, "file", ""))
+            print(f"  {DIM(str(i)+'.')} {severity_label(sev)} {BOLD(name)}")
+            if desc:
+                print(f"     {desc}")
+            if loc:
+                print(f"     {DIM('位置: ' + str(loc))}")
+    elif findings and not getattr(args, "detailed", False):
+        # 非 detailed 模式只显示 HIGH/CRITICAL
+        serious = [f for f in findings if str(getattr(f, "severity", "")).upper() in ("CRITICAL", "HIGH")]
+        if serious:
+            print(f"\n  {BOLD('HIGH/CRITICAL 问题:')}")
+            for f in serious:
+                sev  = str(getattr(f, "severity", "HIGH")).upper()
+                name = getattr(f, "rule_id", getattr(f, "name", "unknown"))
+                desc = getattr(f, "description", getattr(f, "message", ""))
+                print(f"    {severity_label(sev)} {BOLD(name)}: {desc}")
+
+    return {
+        "path":         str(skill_path),
+        "name":         skill_path.name,
+        "is_safe":      is_safe,
+        "max_severity": max_sev,
+        "findings":     len(findings),
+    }
+
+
+# ── 批量扫描 ──────────────────────────────────────────────────────────────────
+def scan_batch(directory: str, args) -> list[dict]:
+    base = Path(directory).expanduser().resolve()
+
+    if not base.exists() or not base.is_dir():
+        print(RED(f"❌ 目录不存在: {base}"))
+        return []
+
+    # 查找所有含 SKILL.md 的子目录
+    skills: list[Path] = []
+
+    if getattr(args, "recursive", False):
+        for skill_md in sorted(base.rglob("SKILL.md")):
+            skills.append(skill_md.parent)
+    else:
+        for entry in sorted(base.iterdir()):
+            if entry.is_dir() and (entry / "SKILL.md").exists():
+                skills.append(entry)
+
+    if not skills:
+        print(YELLOW(f"⚠️  在 {base} 中未找到任何 Skill（含 SKILL.md 的目录）"))
+        return []
+
+    print(f"\n{BOLD('📂 批量扫描目录:')} {CYAN(str(base))}")
+    print(f"   发现 {BOLD(str(len(skills)))} 个 Skill\n")
+    print("─" * 60)
+
+    results = []
+    safe_count    = 0
+    unsafe_count  = 0
+    error_count   = 0
+
+    for skill_path in skills:
+        r = scan_single(str(skill_path), args)
+        results.append(r)
+        if r.get("error"):
+            error_count += 1
+        elif r.get("is_safe"):
+            safe_count += 1
+        else:
+            unsafe_count += 1
+
+    # 汇总
+    print("\n" + "═" * 60)
+    print(BOLD("📊 批量扫描汇总"))
+    print("═" * 60)
+    print(f"  总计:    {len(results)} 个 Skill")
+    print(f"  {GREEN('✅ 安全:')}   {safe_count} 个")
+    print(f"  {RED('❌ 问题:')}   {unsafe_count} 个")
+    if error_count:
+        print(f"  {YELLOW('⚠️  错误:')}   {error_count} 个")
+
+    # 问题 Skill 列表
+    unsafe = [r for r in results if not r.get("is_safe") and not r.get("error")]
+    if unsafe:
+        print(f"\n  {BOLD(RED('需要关注的 Skills:'))}")
+        for r in unsafe:
+            sev = r.get("max_severity", "UNKNOWN")
+            print(f"    {severity_label(sev)} {r['name']}  ({r.get('findings', 0)} 条发现)")
+            print(f"        {DIM(r['path'])}")
+
+    return results
+
+
+# ── JSON 输出 ─────────────────────────────────────────────────────────────────
+def save_json(data, output_path: str):
+    with open(output_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2)
+    print(f"\n{GREEN('💾 结果已保存:')} {output_path}")
+
+
+# ── CLI 入口 ──────────────────────────────────────────────────────────────────
+def main():
+    parser = argparse.ArgumentParser(
+        prog="scan.py",
+        description="OpenClaw Skills 安全扫描器（基于 cisco-ai-skill-scanner）",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+示例:
+  单个扫描:
+    python scan.py scan ~/.openclaw/skills/my-skill
+    python scan.py scan ./my-skill --detailed --behavioral
+
+  批量扫描:
+    python scan.py batch ~/.openclaw/skills
+    python scan.py batch ~/.openclaw/skills --recursive --json results.json
+    python scan.py batch ./skills --detailed --llm
+        """,
+    )
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # -- scan 子命令
+    p_scan = sub.add_parser("scan", help="扫描单个 Skill 目录")
+    p_scan.add_argument("path", help="Skill 目录路径（含 SKILL.md 的文件夹）")
+    p_scan.add_argument("--detailed",   action="store_true", help="显示所有 findings 详情")
+    p_scan.add_argument("--behavioral", action="store_true", help="启用行为分析器（AST dataflow）")
+    p_scan.add_argument("--llm",        action="store_true", help="启用 LLM 语义分析器（需要 API Key）")
+    p_scan.add_argument("--json",       metavar="FILE",      help="将结果保存为 JSON 文件")
+
+    # -- batch 子命令
+    p_batch = sub.add_parser("batch", help="批量扫描目录下所有 Skills")
+    p_batch.add_argument("directory", help="包含多个 Skill 的目录")
+    p_batch.add_argument("--recursive",  action="store_true", help="递归扫描子目录")
+    p_batch.add_argument("--detailed",   action="store_true", help="显示所有 findings 详情")
+    p_batch.add_argument("--behavioral", action="store_true", help="启用行为分析器")
+    p_batch.add_argument("--llm",        action="store_true", help="启用 LLM 语义分析器")
+    p_batch.add_argument("--json",       metavar="FILE",      help="将结果保存为 JSON 文件")
+
+    args = parser.parse_args()
+
+    if args.command == "scan":
+        result = scan_single(args.path, args)
+        if args.json:
+            save_json(result, args.json)
+        # 退出码：不安全返回 1
+        sys.exit(0 if result.get("is_safe") else 1)
+
+    elif args.command == "batch":
+        results = scan_batch(args.directory, args)
+        if args.json:
+            save_json(results, args.json)
+        unsafe = [r for r in results if not r.get("is_safe")]
+        sys.exit(0 if not unsafe else 1)
+
+
+if __name__ == "__main__":
+    main()