@pwddd/skills-scanner 2.1.0 → 2.3.0

package/README.md

@@ -73,15 +73,40 @@ openclaw gateway restart
 重启后 Gateway 会自动：
 1. 创建 Python venv 并安装 `requests` 库
 2. 开始监听 Skills 目录（安装前扫描）
-3. 在启动日志里打印是否需要注册 Cron Job
+3. **智能注册定时任务**（检测已有任务，防止重复）
 
 ---
 
-## 注册每日日报（一次性操作）
+## 定时任务自动注册
 
-Plugin 无法自动注册 Cron Job（OpenClaw Plugin API 不提供此能力），需要手动执行一次：
+插件启动时会**自动智能注册**定时任务，特点：
+
+- ✅ **幂等操作**：多次启动不会创建重复任务
+- ✅ **智能检测**：自动发现已存在的同名任务
+- ✅ **自动更新**：配置变更时自动更新任务
+- ✅ **防止冲突**：即使手动创建过任务也能正确识别
+
+如果自动注册失败，可以使用 `/scan-cron register` 命令手动注册。
+
+---
+
+## 注册每日日报（已自动化）
+
+~~Plugin 无法自动注册 Cron Job（OpenClaw Plugin API 不提供此能力），需要手动执行一次：~~
+
+**更新**：从 v2.2.0 开始，插件会在启动时自动注册定时任务，无需手动操作！
+
+如果需要手动管理，使用以下命令：
+
+如果需要手动管理，使用以下命令：
 
 ```bash
+# 使用聊天命令（推荐）
+/scan-cron register    # 注册定时任务
+/scan-cron unregister  # 删除定时任务
+/scan-cron status      # 查看状态
+
+# 或使用 CLI 命令
 openclaw cron add \
   --name "skills-daily-report" \
   --cron "0 8 * * *" \
@@ -91,39 +116,132 @@ openclaw cron add \
   --announce
 ```
 
-想投递到特定渠道（如 Telegram）：
+验证已注册：
+
+```bash
+openclaw cron list
+```
+
+---
+
+## 聊天命令
+
+### 主命令
+
+```bash
+/skills-scanner [子命令] [参数]
+```
+
+### 子命令
+
+| 命令 | 说明 |
+|---|---|
+| `/skills-scanner scan <路径> [选项]` | 扫描 Skill（智能判断单个/批量） |
+| `/skills-scanner status` | 查看状态、API 服务、定时任务 |
+| `/skills-scanner config [操作]` | 配置管理（show/reset） |
+| `/skills-scanner cron [操作]` | 定时任务管理（register/unregister/status） |
+| `/skills-scanner help` | 显示帮助文档 |
+
+### 扫描选项
+
+| 选项 | 说明 |
+|---|---|
+| `--detailed` | 显示所有 findings 详情 |
+| `--behavioral` | 启用 AST 行为分析（更准确但较慢） |
+| `--recursive` | 递归扫描子目录 |
+| `--report` | 生成日报格式输出 |
+
+### 使用示例
+
+```bash
+# 扫描单个 Skill
+/skills-scanner scan ~/.openclaw/skills/my-skill
+
+# 批量扫描（递归）
+/skills-scanner scan ~/.openclaw/skills --recursive
+
+# 生成日报
+/skills-scanner scan ~/.openclaw/skills --report
+
+# 详细扫描 + 行为分析
+/skills-scanner scan ~/my-skill --detailed --behavioral
+
+# 查看状态
+/skills-scanner status
+
+# 配置管理
+/skills-scanner config show
+/skills-scanner config reset
+
+# 定时任务管理
+/skills-scanner cron status
+/skills-scanner cron register
+/skills-scanner cron unregister
+
+# 查看帮助
+/skills-scanner help
+```
+
+---
+
+## 定时任务说明
+
+插件会在启动时**自动智能注册**定时任务，无需手动操作：
+
+### 智能注册机制
+
+1. **检测已有任务**：启动时查询系统中是否已有同名任务
+2. **幂等操作**：如果任务已存在，保存 ID 并跳过创建
+3. **自动更新**：如果任务配置变更（时间、时区），自动删除旧任务并创建新任务
+4. **防止重复**：即使多次重启或重新安装，也不会创建重复任务
+
+### 默认配置
+
+- **任务名称**：`skills-daily-report`
+- **执行时间**：每天 08:00
+- **时区**：Asia/Shanghai
+- **执行内容**：发送 `/scan-report` 命令到指定渠道
+
+### 手动管理
+
+如果自动注册失败，可以手动操作：
 
 ```bash
+# 查看所有定时任务
+openclaw cron list
+
+# 手动注册
 openclaw cron add \
   --name "skills-daily-report" \
   --cron "0 8 * * *" \
   --tz "Asia/Shanghai" \
   --session isolated \
   --message "请执行 /scan-report 并把结果发送到此渠道" \
-  --announce \
-  --channel telegram \
-  --to "+8613312345678"
-```
+  --announce
 
-验证已注册：
+# 删除定时任务
+openclaw cron remove <job-id>
 
-```bash
-openclaw cron list
+# 修改执行时间（先删除再创建）
+openclaw cron remove <job-id>
+openclaw cron add --name "skills-daily-report" --cron "0 9 * * *" ...
 ```
 
----
+### 投递到特定渠道
 
-## 聊天命令
+如果想将日报发送到特定渠道（如 Telegram）：
 
-| 命令 | 说明 |
-|---|---|
-| `/scan-skill <路径>` | 扫描单个 Skill 目录 |
-| `/scan-skill <路径> --detailed` | 显示完整 findings |
-| `/scan-skill <路径> --behavioral` | 启用 AST 行为分析 |
-| `/scan-skills <目录>` | 批量扫描目录 |
-| `/scan-skills <目录> --recursive` | 递归扫描子目录 |
-| `/scan-report` | 立即执行全量扫描并输出日报 |
-| `/scan-status` | 查看状态、待查告警、Cron 注册命令 |
+```bash
+openclaw cron add \
+  --name "skills-daily-report" \
+  --cron "0 8 * * *" \
+  --tz "Asia/Shanghai" \
+  --session isolated \
+  --message "请执行 /scan-report 并把结果发送到此渠道" \
+  --announce \
+  --channel telegram \
+  --to "+8613312345678"
+```
 
 ---
 

package/index.ts

@@ -70,6 +70,7 @@ interface ScannerConfig {
 interface ScanState {
   lastScanAt?: string;
   lastUnsafeSkills?: string[];
+  configReviewed?: boolean;  // 标记配置是否已审查
 }
 
 // ── 工具函数 ──────────────────────────────────────────────────────────────────
@@ -119,6 +120,144 @@ function saveState(s: ScanState) {
   writeFileSync(STATE_FILE, JSON.stringify(s, null, 2));
 }
 
+/**
+ * 检查是否是首次运行（使用默认配置）
+ */
+function isFirstRun(cfg: ScannerConfig): boolean {
+  const state = loadState() as any;
+  
+  // 如果 state 中已标记为非首次运行，直接返回 false
+  if (state.configReviewed) {
+    return false;
+  }
+  
+  // 检查是否所有配置都是默认值
+  const isDefaultConfig = 
+    !cfg.apiUrl &&                    // 未设置 apiUrl
+    (!cfg.scanDirs || cfg.scanDirs.length === 0) &&  // 未设置 scanDirs
+    cfg.behavioral !== true &&        // 未启用 behavioral
+    cfg.useLLM !== true &&           // 未启用 useLLM
+    cfg.policy !== "strict" &&       // 未设置为 strict
+    cfg.policy !== "permissive" &&   // 未设置为 permissive
+    cfg.preInstallScan !== "off" &&  // 未禁用 preInstallScan
+    cfg.onUnsafe !== "delete" &&     // 未设置为 delete
+    cfg.onUnsafe !== "warn";         // 未设置为 warn
+  
+  return isDefaultConfig;
+}
+
+/**
+ * 标记配置已审查
+ */
+function markConfigReviewed() {
+  const state = loadState() as any;
+  saveState({ ...state, configReviewed: true });
+}
+
+/**
+ * 生成配置建议提示
+ */
+function generateConfigGuide(cfg: ScannerConfig, apiUrl: string, scanDirs: string[], behavioral: boolean, useLLM: boolean, policy: string, preInstallScan: string, onUnsafe: string): string {
+  const configPath = join(homedir(), ".openclaw", "openclaw.json");
+  
+  const lines = [
+    "",
+    "╔════════════════════════════════════════════════════════════════╗",
+    "║  🎉 Skills Scanner 首次运行 - 配置向导                         ║",
+    "╚════════════════════════════════════════════════════════════════╝",
+    "",
+    "当前使用默认配置。建议根据您的需求自定义配置：",
+    "",
+    "📋 当前配置：",
+    `  • API 服务地址: ${apiUrl}`,
+    `  • 扫描目录: ${scanDirs.length} 个（自动检测）`,
+    `  • 行为分析: ${behavioral ? "✅ 启用" : "❌ 禁用"}`,
+    `  • LLM 分析: ${useLLM ? "✅ 启用" : "❌ 禁用"}`,
+    `  • 扫描策略: ${policy}`,
+    `  • 安装前扫描: ${preInstallScan === "on" ? "✅ 启用" : "❌ 禁用"}`,
+    `  • 不安全处理: ${onUnsafe}`,
+    "",
+    "🔧 配置文件位置：",
+    `  ${configPath}`,
+    "",
+    "📝 推荐配置示例：",
+    "",
+    "```json",
+    "{",
+    '  "plugins": {',
+    '    "entries": {',
+    '      "skills-scanner": {',
+    '        "enabled": true,',
+    '        "config": {',
+    '          "apiUrl": "http://localhost:8000",     // API 服务地址',
+    '          "scanDirs": [',
+    '            "~/.openclaw/skills",                // 全局 skills',
+    '            "~/.openclaw/workspace/skills"       // workspace skills',
+    '          ],',
+    '          "behavioral": false,                   // 启用行为分析（更准确但较慢）',
+    '          "useLLM": false,                       // 启用 LLM 分析（需 API 支持）',
+    '          "policy": "balanced",                  // strict | balanced | permissive',
+    '          "preInstallScan": "on",                // 安装前扫描（推荐）',
+    '          "onUnsafe": "quarantine"               // quarantine | delete | warn',
+    '        }',
+    '      }',
+    '    }',
+    '  }',
+    "}",
+    "```",
+    "",
+    "💡 配置说明：",
+    "",
+    "1. apiUrl - API 服务地址",
+    "   • 默认: http://localhost:8000",
+    "   • 需要先启动 skill-scanner-api 服务",
+    "",
+    "2. scanDirs - 扫描目录列表",
+    "   • 默认: 自动检测 ~/.openclaw/skills",
+    "   • 可添加多个目录",
+    "",
+    "3. behavioral - 行为分析",
+    "   • false: 快速扫描（推荐）",
+    "   • true: 深度分析（更准确但较慢）",
+    "",
+    "4. useLLM - LLM 分析",
+    "   • false: 不使用 LLM（推荐）",
+    "   • true: 使用 LLM 语义分析（需 API 服务配置 LLM）",
+    "",
+    "5. policy - 扫描策略",
+    "   • strict: 严格模式（更多误报）",
+    "   • balanced: 平衡模式（推荐）",
+    "   • permissive: 宽松模式（可能漏报）",
+    "",
+    "6. preInstallScan - 安装前扫描",
+    "   • on: 监听新 Skill 并自动扫描（推荐）",
+    "   • off: 禁用自动扫描",
+    "",
+    "7. onUnsafe - 不安全 Skill 处理",
+    "   • quarantine: 移入隔离目录（推荐）",
+    "   • delete: 直接删除",
+    "   • warn: 仅警告，保留文件",
+    "",
+    "🚀 快速开始：",
+    "",
+    "1. 编辑配置文件：",
+    `   nano ${configPath}`,
+    "",
+    "2. 重启 Gateway 使配置生效：",
+    "   openclaw gateway restart",
+    "",
+    "3. 验证配置：",
+    "   /scan-status",
+    "",
+    "💬 或者在聊天中执行 /scan-status 查看当前状态",
+    "",
+    "提示：此消息只在首次运行时显示。",
+    "════════════════════════════════════════════════════════════════",
+  ];
+  
+  return lines.join("\n");
+}
+
 async function ensureDeps(logger: any): Promise<boolean> {
   if (isVenvReady()) {
     logger.info("[skills-scanner] Python 依赖已就绪（requests 已安装）");
@@ -199,6 +338,156 @@ async function runScan(
   }
 }
 
+// ── 智能 Cron 任务管理 ───────────────────────────────────────────────────
+
+const CRON_JOB_NAME = "skills-daily-report";
+const CRON_SCHEDULE = "0 8 * * *";
+const CRON_TIMEZONE = "Asia/Shanghai";
+
+/**
+ * 智能注册 Cron 任务（幂等操作）
+ * 1. 先查询系统中是否已有同名任务
+ * 2. 如果存在，保存 ID 并跳过
+ * 3. 如果不存在，创建新任务
+ * 4. 支持配置自定义时间和时区
+ */
+async function ensureCronJob(logger: any): Promise<void> {
+  const state = loadState() as any;
+  
+  logger.info("[skills-scanner] ─────────────────────────────────────");
+  logger.info("[skills-scanner] 🕐 检查定时任务...");
+  
+  try {
+    // 1. 查询所有定时任务
+    let jobs: any[] = [];
+    try {
+      const listResult = execSync('openclaw cron list --format json', { 
+        encoding: 'utf-8',
+        timeout: 5000 
+      });
+      jobs = JSON.parse(listResult.trim());
+    } catch (listErr: any) {
+      // 如果 --format json 不支持，尝试解析文本输出
+      logger.debug("[skills-scanner] JSON 格式不支持，尝试文本解析");
+      try {
+        const listResult = execSync('openclaw cron list', { 
+          encoding: 'utf-8',
+          timeout: 5000 
+        });
+        // 简单解析：查找包含任务名的行
+        if (listResult.includes(CRON_JOB_NAME)) {
+          logger.info(`[skills-scanner] ✅ 发现已存在的任务: ${CRON_JOB_NAME}`);
+          // 无法获取 ID，但至少知道任务存在
+          if (!state.cronJobId) {
+            saveState({ ...state, cronJobId: 'manual-created' });
+          }
+          return;
+        }
+      } catch {
+        logger.debug("[skills-scanner] 无法列出定时任务，可能是权限问题");
+      }
+    }
+    
+    // 2. 查找同名任务
+    const existingJob = jobs.find((j: any) => 
+      j.name === CRON_JOB_NAME || 
+      j.jobName === CRON_JOB_NAME ||
+      j.id === state.cronJobId
+    );
+    
+    if (existingJob) {
+      const jobId = existingJob.id || existingJob.jobId || state.cronJobId;
+      
+      // 检查任务配置是否需要更新
+      const needsUpdate = 
+        existingJob.schedule !== CRON_SCHEDULE ||
+        existingJob.timezone !== CRON_TIMEZONE;
+      
+      if (needsUpdate) {
+        logger.info(`[skills-scanner] 🔄 任务配置已变更，尝试更新...`);
+        try {
+          // 先删除旧任务
+          execSync(`openclaw cron remove ${jobId}`, { encoding: 'utf-8', timeout: 5000 });
+          logger.info(`[skills-scanner] ✅ 已删除旧任务: ${jobId}`);
+          // 继续创建新任务（不 return）
+        } catch (removeErr: any) {
+          logger.warn(`[skills-scanner] ⚠️  删除旧任务失败: ${removeErr.message}`);
+          // 如果删除失败，保留现有任务
+          if (state.cronJobId !== jobId) {
+            saveState({ ...state, cronJobId: jobId });
+          }
+          logger.info(`[skills-scanner] ✅ 保留现有任务: ${jobId}`);
+          return;
+        }
+      } else {
+        // 配置未变，保存 ID 并返回
+        if (state.cronJobId !== jobId) {
+          saveState({ ...state, cronJobId: jobId });
+          logger.info(`[skills-scanner] ✅ 发现已存在的任务: ${jobId}`);
+        } else {
+          logger.info(`[skills-scanner] ✅ 任务已存在: ${jobId}`);
+        }
+        return;
+      }
+    }
+    
+    // 3. 任务不存在或已删除，创建新任务
+    logger.info("[skills-scanner] 📝 正在创建定时任务...");
+    
+    const cronCmd = [
+      'openclaw cron add',
+      `--name "${CRON_JOB_NAME}"`,
+      `--cron "${CRON_SCHEDULE}"`,
+      `--tz "${CRON_TIMEZONE}"`,
+      '--session isolated',
+      '--message "请执行 /scan-report 并把结果发送到此渠道"',
+      '--announce'
+    ].join(' ');
+    
+    const result = execSync(cronCmd, { encoding: 'utf-8', timeout: 10000 });
+    
+    // 4. 提取并保存 Job ID
+    const jobIdMatch = result.match(/Job ID[:\s]+([a-zA-Z0-9-]+)/i) || 
+                       result.match(/jobId[:\s]+([a-zA-Z0-9-]+)/i) ||
+                       result.match(/id[:\s]+([a-zA-Z0-9-]+)/i);
+    
+    if (jobIdMatch) {
+      const cronJobId = jobIdMatch[1];
+      saveState({ ...state, cronJobId });
+      logger.info(`[skills-scanner] ✅ 任务创建成功: ${cronJobId}`);
+      logger.info(`[skills-scanner] 📅 执行时间: 每天 ${CRON_SCHEDULE.split(' ')[1]}:${CRON_SCHEDULE.split(' ')[0]} (${CRON_TIMEZONE})`);
+    } else {
+      // 无法提取 ID，但命令执行成功
+      logger.info("[skills-scanner] ✅ 任务创建命令已执行");
+      logger.debug(`[skills-scanner] 输出: ${result.trim()}`);
+      saveState({ ...state, cronJobId: 'created-unknown-id' });
+    }
+    
+  } catch (err: any) {
+    // 5. 创建失败，提供手动注册指引
+    logger.warn("[skills-scanner] ⚠️  自动注册失败");
+    logger.debug(`[skills-scanner] 错误详情: ${err.message}`);
+    
+    // 检查是否是权限问题
+    if (err.message.includes('permission') || err.message.includes('EACCES')) {
+      logger.error("[skills-scanner] ❌ 权限不足，请使用管理员权限运行");
+    } else if (err.message.includes('command not found') || err.message.includes('ENOENT')) {
+      logger.error("[skills-scanner] ❌ openclaw 命令未找到，请检查安装");
+    } else {
+      logger.info("[skills-scanner] 💡 请手动执行以下命令注册定时任务：");
+      logger.info("[skills-scanner]");
+      logger.info('[skills-scanner]   openclaw cron add \\');
+      logger.info(`[skills-scanner]     --name "${CRON_JOB_NAME}" \\`);
+      logger.info(`[skills-scanner]     --cron "${CRON_SCHEDULE}" \\`);
+      logger.info(`[skills-scanner]     --tz "${CRON_TIMEZONE}" \\`);
+      logger.info('[skills-scanner]     --session isolated \\');
+      logger.info('[skills-scanner]     --message "请执行 /scan-report 并把结果发送到此渠道" \\');
+      logger.info('[skills-scanner]     --announce');
+      logger.info("[skills-scanner]");
+    }
+  }
+}
+
 // ── 日报 ──────────────────────────────────────────────────────────────────────
 
 async function buildDailyReport(
@@ -372,7 +661,7 @@ function startWatcher(
 
 // ── Plugin 入口 ───────────────────────────────────────────────────────────────
 
-export default function register(api: any) {
+export default async function register(api: any) {
   const cfg: ScannerConfig = api.config?.plugins?.entries?.["skills-scanner"]?.config ?? {};
   const apiUrl         = cfg.apiUrl         ?? "http://localhost:8000";
   const scanDirs       = (cfg.scanDirs?.map(expandPath) ?? []).filter(existsSync).length > 0
@@ -394,6 +683,21 @@ export default function register(api: any) {
   api.logger.info(`[skills-scanner] 扫描目录: ${scanDirs.join(", ")}`);
   api.logger.info(`[skills-scanner] Python 依赖状态: ${isVenvReady() ? "✅ 已就绪" : "❌ 未安装"}`);
 
+  // 检查是否首次运行
+  const firstRun = isFirstRun(cfg);
+  if (firstRun) {
+    api.logger.info("[skills-scanner] ═══════════════════════════════════════");
+    api.logger.info("[skills-scanner] 🎉 首次运行检测");
+    api.logger.info("[skills-scanner] ═══════════════════════════════════════");
+    
+    // 输出配置向导
+    const configGuide = generateConfigGuide(cfg, apiUrl, scanDirs, behavioral, useLLM, policy, preInstallScan, onUnsafe);
+    console.log(configGuide);
+    
+    // 标记为已审查（避免每次启动都显示）
+    markConfigReviewed();
+  }
+
   // 立即尝试安装依赖（不等待 service start）
   if (!isVenvReady()) {
     api.logger.info("[skills-scanner] 开始安装 Python 依赖...");
@@ -450,35 +754,291 @@ export default function register(api: any) {
     },
   });
 
-  // ── 2. 启动日志和 Cron 自动注册 ────────────────────────────────────────────
-  const state = loadState() as any;
-  if (!state.cronJobId) {
-    api.logger.warn("[skills-scanner] ⚠️  未检测到日报 Cron Job");
-    api.logger.info("[skills-scanner] 尝试自动注册...");
+  // ── 2. 智能 Cron 任务注册 ────────────────────────────────────────────────
+  await ensureCronJob(api.logger);
+  api.logger.info("[skills-scanner] ═══════════════════════════════════════");
+
+  // ── 3. /skills-scanner 主命令（命名空间）─────────────────────────────────
+  api.registerCommand({
+    name: "skills-scanner",
+    description: "Skills 安全扫描工具。用法: /skills-scanner <子命令> [参数]",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: async (ctx: any) => {
+      const args = (ctx.args ?? "").trim();
+      
+      // 无参数时显示帮助
+      if (!args) {
+        return { 
+          text: [
+            "🔍 *Skills Scanner - 安全扫描工具*",
+            "",
+            "可用命令：",
+            "• `/skills-scanner scan <路径> [选项]` - 扫描 Skill",
+            "• `/skills-scanner status` - 查看状态",
+            "• `/skills-scanner config [操作]` - 配置管理",
+            "• `/skills-scanner cron [操作]` - 定时任务管理",
+            "",
+            "扫描选项：",
+            "• `--detailed` - 显示详细发现",
+            "• `--behavioral` - 启用行为分析",
+            "• `--recursive` - 递归扫描子目录",
+            "• `--report` - 生成日报格式",
+            "",
+            "示例：",
+            "```",
+            "/skills-scanner scan ~/my-skill",
+            "/skills-scanner scan ~/skills --recursive",
+            "/skills-scanner scan ~/skills --report",
+            "/skills-scanner status",
+            "```",
+            "",
+            "💡 使用 `/skills-scanner help` 查看详细帮助"
+          ].join("\n")
+        };
+      }
+
+      const parts = args.split(/\s+/);
+      const subCommand = parts[0].toLowerCase();
+      const subArgs = parts.slice(1).join(" ");
+
+      // 路由到子命令
+      if (subCommand === "scan") {
+        return await handleScanCommand(subArgs);
+      } else if (subCommand === "status") {
+        return await handleStatusCommand();
+      } else if (subCommand === "config") {
+        return await handleConfigCommand(subArgs);
+      } else if (subCommand === "cron") {
+        return await handleCronCommand(subArgs);
+      } else if (subCommand === "help" || subCommand === "--help" || subCommand === "-h") {
+        return { text: getHelpText() };
+      } else {
+        return { text: `❌ 未知子命令: ${subCommand}\n\n使用 \`/skills-scanner help\` 查看帮助` };
+      }
+    },
+  });
+
+  // ── 子命令处理器 ──────────────────────────────────────────────────────────
+
+  async function handleScanCommand(args: string): Promise<any> {
+    if (!args) {
+      return { text: "用法：`/skills-scanner scan <路径> [--detailed] [--behavioral] [--recursive] [--report]`" };
+    }
     
-    try {
-      const cronCmd = 'openclaw cron add --name "skills-daily-report" --cron "0 8 * * *" --tz "Asia/Shanghai" --session isolated --message "请执行 /scan-report 并把结果发送到此渠道" --announce';
-      const result = execSync(cronCmd, { encoding: 'utf-8' });
+    if (!isVenvReady()) {
+      return { text: "⏳ Python 依赖尚未就绪，请稍后重试或查看日志" };
+    }
+
+    const parts = args.split(/\s+/);
+    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");
+
+    if (!targetPath) {
+      return { text: "❌ 请指定扫描路径" };
+    }
+
+    if (!existsSync(targetPath)) {
+      return { text: `❌ 路径不存在: ${targetPath}` };
+    }
+
+    // 判断是单个 Skill 还是批量扫描
+    const isSingleSkill = existsSync(join(targetPath, "SKILL.md"));
+    
+    if (isReport) {
+      // 生成日报
+      if (scanDirs.length === 0) {
+        return { text: "⚠️ 未找到可扫描目录，请检查配置" };
+      }
+      const report = await buildDailyReport(scanDirs, useBehav, apiUrl, useLLM, policy, api.logger);
+      return { text: report };
+    } else if (isSingleSkill) {
+      // 单个 Skill 扫描
+      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 handleStatusCommand(): Promise<any> {
+    const state = loadState() as any;
+    const alerts: string[] = state.pendingAlerts ?? [];
+
+    const lines = [
+      "📋 *Skills Scanner 状态*",
+      `API 服务地址：${apiUrl}`,
+      `Python 依赖：${isVenvReady() ? "✅ 就绪" : "❌ 未就绪"}`,
+      `安装前扫描：${preInstallScan === "on" ? `✅ 监听中（${onUnsafe}）` : "❌ 已禁用"}`,
+      `扫描策略：${policy}`,
+      `LLM 分析：${useLLM ? "✅ 启用" : "❌ 禁用"}`,
+      `行为分析：${behavioral ? "✅ 启用" : "❌ 禁用"}`,
+      `上次扫描：${state.lastScanAt ? new Date(state.lastScanAt).toLocaleString("zh-CN") : "从未"}`,
+      `扫描目录：\n${scanDirs.map(d => `  • ${d}`).join("\n")}`,
+    ];
+    
+    // API 健康检查
+    if (isVenvReady()) {
+      lines.push("", "🔍 *API 服务检查*");
+      try {
+        const cmd = `"${VENV_PYTHON}" "${SCAN_SCRIPT}" --api-url "${apiUrl}" health`;
+        const env = { ...process.env };
+        delete env.http_proxy;
+        delete env.https_proxy;
+        delete env.HTTP_PROXY;
+        delete env.HTTPS_PROXY;
+        delete env.all_proxy;
+        delete env.ALL_PROXY;
+        
+        const { stdout, stderr } = await execAsync(cmd, { timeout: 5000, env });
+        const output = (stdout + stderr).trim();
+        
+        if (output.includes("✓") || output.includes("正常")) {
+          lines.push(`API 服务：✅ 正常`);
+          const jsonMatch = output.match(/\{[\s\S]*\}/);
+          if (jsonMatch) {
+            try {
+              const healthData = JSON.parse(jsonMatch[0]);
+              if (healthData.analyzers_available) {
+                lines.push(`可用分析器：${healthData.analyzers_available.join(", ")}`);
+              }
+            } catch {}
+          }
+        } else {
+          lines.push(`API 服务：❌ 不可用`);
+        }
+      } catch (err: any) {
+        lines.push(`API 服务：❌ 连接失败`);
+        lines.push(`错误：无法连接到 ${apiUrl}`);
+      }
+    }
+
+    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<any> {
+    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<any> {
+    const action = args.trim().toLowerCase() || "status";
+    const state = loadState() as any;
+    
+    if (action === "register") {
+      const oldJobId = state.cronJobId;
+      if (oldJobId && oldJobId !== 'manual-created') {
+        try {
+          execSync(`openclaw cron remove ${oldJobId}`, { encoding: 'utf-8', timeout: 5000 });
+        } catch {}
+      }
       
-      // 尝试从输出中提取 job ID
-      const jobIdMatch = result.match(/Job ID[:\s]+([a-zA-Z0-9-]+)/i) || result.match(/jobId[:\s]+([a-zA-Z0-9-]+)/i);
-      if (jobIdMatch) {
-        const cronJobId = jobIdMatch[1];
-        saveState({ ...state, cronJobId });
-        api.logger.info(`[skills-scanner] ✅ Cron Job 自动注册成功: ${cronJobId}`);
+      saveState({ ...state, cronJobId: undefined });
+      await ensureCronJob(api.logger);
+      
+      const newState = loadState() as any;
+      if (newState.cronJobId) {
+        return { text: `✅ 定时任务注册成功\n任务 ID: ${newState.cronJobId}` };
+      } else {
+        return { text: "❌ 定时任务注册失败，请查看日志" };
+      }
+    } else if (action === "unregister") {
+      if (!state.cronJobId) {
+        return { text: "⚠️ 未找到已注册的定时任务" };
+      }
+      
+      try {
+        execSync(`openclaw cron remove ${state.cronJobId}`, { encoding: 'utf-8', timeout: 5000 });
+        saveState({ ...state, cronJobId: undefined });
+        return { text: `✅ 定时任务已删除: ${state.cronJobId}` };
+      } catch (err: any) {
+        return { text: `❌ 删除失败: ${err.message}` };
+      }
+    } else {
+      const lines = ["🕐 *定时任务状态*"];
+      if (state.cronJobId && state.cronJobId !== 'manual-created') {
+        lines.push(`任务 ID: ${state.cronJobId}`);
+        lines.push(`执行时间: 每天 08:00 (Asia/Shanghai)`);
+        lines.push("状态: ✅ 已注册");
       } else {
-        api.logger.info("[skills-scanner] ✅ Cron Job 注册命令已执行");
-        api.logger.info("[skills-scanner] 输出: " + result.trim());
+        lines.push("状态: ❌ 未注册");
+        lines.push("", "💡 使用 `/skills-scanner cron register` 注册");
       }
-    } catch (err: any) {
-      api.logger.warn("[skills-scanner] ⚠️  自动注册失败，请手动执行：");
-      api.logger.info('[skills-scanner]   openclaw cron add --name "skills-daily-report" --cron "0 8 * * *" --tz "Asia/Shanghai" --session isolated --message "请执行 /scan-report 并把结果发送到此渠道" --announce');
-      api.logger.debug(`[skills-scanner] 错误详情: ${err.message}`);
+      return { text: lines.join("\n") };
     }
-  } else {
-    api.logger.info(`[skills-scanner] ✅ 日报 Cron Job 已存在: ${state.cronJobId}`);
   }
-  api.logger.info("[skills-scanner] ═══════════════════════════════════════");
+
+  function getHelpText(): string {
+    return [
+      "🔍 *Skills Scanner - 帮助文档*",
+      "",
+      "═══ 扫描命令 ═══",
+      "`/skills-scanner scan <路径> [选项]`",
+      "",
+      "选项：",
+      "• `--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 status` - 查看状态",
+      "• `/skills-scanner config [show|reset]` - 配置管理",
+      "• `/skills-scanner cron [register|unregister|status]` - 定时任务",
+    ].join("\n");
+  }
 
   // ── 3. /scan-skill ────────────────────────────────────────────────────────
   api.registerCommand({
@@ -649,23 +1209,146 @@ export default function register(api: any) {
         saveState({ ...state, pendingAlerts: [] });
       }
 
-      lines.push(
-        "",
-        "定期日报（需手动注册一次）：",
-        "```",
-        "openclaw cron add \\",
-        '  --name "skills-daily-report" \\',
-        '  --cron "0 8 * * *" --tz "Asia/Shanghai" \\',
-        "  --session isolated \\",
-        '  --message "请执行 /scan-report 并把结果发送到此渠道" \\',
-        "  --announce",
-        "```",
-      );
+      // 定时任务状态
+      lines.push("", "🕐 *定时任务状态*");
+      if (state.cronJobId && state.cronJobId !== 'manual-created' && state.cronJobId !== 'created-unknown-id') {
+        lines.push(`任务 ID：${state.cronJobId}`);
+        lines.push(`任务名称：${CRON_JOB_NAME}`);
+        lines.push(`执行时间：每天 ${CRON_SCHEDULE.split(' ')[1]}:${CRON_SCHEDULE.split(' ')[0]} (${CRON_TIMEZONE})`);
+        lines.push("状态：✅ 已注册");
+        lines.push("", "💡 查看所有定时任务：`openclaw cron list`");
+        lines.push("💡 删除定时任务：`openclaw cron remove " + state.cronJobId + "`");
+      } else if (state.cronJobId === 'manual-created') {
+        lines.push("状态：✅ 已手动创建（无法获取 ID）");
+        lines.push("", "💡 查看所有定时任务：`openclaw cron list`");
+      } else {
+        lines.push("状态：❌ 未注册");
+        lines.push("", "💡 手动注册定时任务：");
+        lines.push("```");
+        lines.push("openclaw cron add \\");
+        lines.push(`  --name "${CRON_JOB_NAME}" \\`);
+        lines.push(`  --cron "${CRON_SCHEDULE}" \\`);
+        lines.push(`  --tz "${CRON_TIMEZONE}" \\`);
+        lines.push("  --session isolated \\");
+        lines.push('  --message "请执行 /scan-report 并把结果发送到此渠道" \\');
+        lines.push("  --announce");
+        lines.push("```");
+      }
+
       return { text: lines.join("\n") };
     },
   });
 
-  // ── 7. Gateway RPC ────────────────────────────────────────────────────────
+  // ── 7. /scan-cron ─────────────────────────────────────────────────────────
+  api.registerCommand({
+    name: "scan-cron",
+    description: "管理定时任务。用法: /scan-cron [register|unregister|status]",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: async (ctx: any) => {
+      const action = (ctx.args ?? "").trim().toLowerCase() || "status";
+      const state = loadState() as any;
+      
+      if (action === "register" || action === "add") {
+        // 强制重新注册
+        api.logger.info("[skills-scanner] 用户请求重新注册定时任务");
+        
+        // 清除旧的 cronJobId，强制重新创建
+        const oldJobId = state.cronJobId;
+        if (oldJobId && oldJobId !== 'manual-created' && oldJobId !== 'created-unknown-id') {
+          try {
+            execSync(`openclaw cron remove ${oldJobId}`, { encoding: 'utf-8', timeout: 5000 });
+            api.logger.info(`[skills-scanner] 已删除旧任务: ${oldJobId}`);
+          } catch (err: any) {
+            api.logger.warn(`[skills-scanner] 删除旧任务失败: ${err.message}`);
+          }
+        }
+        
+        saveState({ ...state, cronJobId: undefined });
+        await ensureCronJob(api.logger);
+        
+        const newState = loadState() as any;
+        if (newState.cronJobId) {
+          return { text: `✅ 定时任务注册成功\n任务 ID: ${newState.cronJobId}\n执行时间: 每天 ${CRON_SCHEDULE.split(' ')[1]}:${CRON_SCHEDULE.split(' ')[0]} (${CRON_TIMEZONE})` };
+        } else {
+          return { text: "❌ 定时任务注册失败，请查看日志或手动注册" };
+        }
+        
+      } else if (action === "unregister" || action === "remove" || action === "delete") {
+        // 删除定时任务
+        if (!state.cronJobId) {
+          return { text: "⚠️ 未找到已注册的定时任务" };
+        }
+        
+        if (state.cronJobId === 'manual-created' || state.cronJobId === 'created-unknown-id') {
+          return { text: "⚠️ 无法自动删除手动创建的任务，请使用：\n`openclaw cron list` 查看任务\n`openclaw cron remove <job-id>` 删除任务" };
+        }
+        
+        try {
+          execSync(`openclaw cron remove ${state.cronJobId}`, { encoding: 'utf-8', timeout: 5000 });
+          saveState({ ...state, cronJobId: undefined });
+          return { text: `✅ 定时任务已删除: ${state.cronJobId}` };
+        } catch (err: any) {
+          return { text: `❌ 删除失败: ${err.message}\n请手动执行: \`openclaw cron remove ${state.cronJobId}\`` };
+        }
+        
+      } else if (action === "status" || action === "info") {
+        // 显示状态
+        const lines = ["🕐 *定时任务状态*"];
+        
+        if (state.cronJobId && state.cronJobId !== 'manual-created' && state.cronJobId !== 'created-unknown-id') {
+          lines.push(`任务 ID: ${state.cronJobId}`);
+          lines.push(`任务名称: ${CRON_JOB_NAME}`);
+          lines.push(`执行时间: 每天 ${CRON_SCHEDULE.split(' ')[1]}:${CRON_SCHEDULE.split(' ')[0]} (${CRON_TIMEZONE})`);
+          lines.push("状态: ✅ 已注册");
+          lines.push("");
+          lines.push("可用操作:");
+          lines.push("• `/scan-cron unregister` - 删除定时任务");
+          lines.push("• `/scan-cron register` - 重新注册定时任务");
+          lines.push("• `openclaw cron list` - 查看所有定时任务");
+        } else if (state.cronJobId === 'manual-created') {
+          lines.push("状态: ✅ 已手动创建（无法获取 ID）");
+          lines.push("");
+          lines.push("💡 使用 `openclaw cron list` 查看所有定时任务");
+        } else {
+          lines.push("状态: ❌ 未注册");
+          lines.push("");
+          lines.push("💡 使用 `/scan-cron register` 注册定时任务");
+        }
+        
+        return { text: lines.join("\n") };
+        
+      } else {
+        return { text: "用法: `/scan-cron [register|unregister|status]`\n\n• `register` - 注册定时任务\n• `unregister` - 删除定时任务\n• `status` - 查看状态（默认）" };
+      }
+    },
+  });
+
+  // ── 8. /scan-config ───────────────────────────────────────────────────────
+  api.registerCommand({
+    name: "scan-config",
+    description: "显示配置向导和当前配置",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: async (ctx: any) => {
+      const action = (ctx.args ?? "").trim().toLowerCase() || "show";
+      
+      if (action === "show" || action === "guide" || action === "help") {
+        // 显示配置向导
+        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: "用法: `/scan-config [show|reset]`\n\n• `show` - 显示配置向导（默认）\n• `reset` - 重置首次运行标记" };
+      }
+    },
+  });
+
+  // ── 9. 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 参数" });
@@ -688,7 +1371,7 @@ export default function register(api: any) {
     respond(true, { report, state: loadState() });
   });
 
-  // ── 8. CLI ────────────────────────────────────────────────────────────────
+  // ── 9. CLI ────────────────────────────────────────────────────────────────
   api.registerCli(({ program }: any) => {
     const cmd = program.command("skills-scan").description("OpenClaw Skills 安全扫描");
 

package/package.json

@@ -1,18 +1,17 @@
 {
   "name": "@pwddd/skills-scanner",
-  "version": "2.1.0",
-  "description": "OpenClaw Plugin：Skills 安全扫描、安装前拦截、安全日报（HTTP API 客户端模式）",
+  "version": "2.3.0",
+  "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", "http-client"],
+  "keywords": ["openclaw", "openclaw-plugin", "security", "skill-scanner", "http-client", "cron", "namespace"],
   "license": "MIT",
   "publishConfig": {
     "access": "public"