@pwddd/skills-scanner 2.4.1 → 2026.3.10

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## [2026.3.10] - 2024-03-10
+
+### Added
+- 初始版本发布
+- 自动扫描新安装的 Skills
+- 定时日报功能（每天 08:00）
+- 支持三种扫描策略：strict/balanced/permissive
+- 可选的 LLM 语义分析
+- 自动隔离/删除不安全的 Skills
+- 聊天命令：/skills-scanner
+- CLI 命令：openclaw skills-scan
+- Gateway RPC 方法：skills-scanner.scan, skills-scanner.report
+- 首次运行配置向导
+
+### Features
+- Python 依赖自动安装（使用 uv）
+- 文件监控（fs.watch）
+- 状态持久化
+- 告警队列
+- 健康检查
+
+### Configuration
+- apiUrl: API 服务地址
+- scanDirs: 扫描目录列表
+- behavioral: 行为分析开关
+- useLLM: LLM 分析开关
+- policy: 扫描策略
+- preInstallScan: 安装前扫描开关
+- onUnsafe: 不安全 Skill 处理方式

package/INSTALL.md

@@ -0,0 +1,280 @@
+# Skills Scanner 安装指南
+
+## 快速开始
+
+### 1. 安装插件
+
+```bash
+# 从本地安装（开发模式）
+cd /path/to/openclaw
+openclaw plugins install ./extensions/skills-scanner
+
+# 或从 npm 安装（发布后）
+openclaw plugins install @openclaw/skills-scanner
+```
+
+### 2. 安装前置依赖
+
+#### 安装 uv（Python 包管理器）
+
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# 或使用 Homebrew
+brew install uv
+
+# Windows
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+#### 启动扫描 API 服务
+
+插件需要连接到 `skill-scanner-api` 服务。请确保该服务正在运行：
+
+```bash
+# 假设你已经有这个服务
+skill-scanner-api
+# 默认监听 http://localhost:8000
+```
+
+### 3. 配置插件
+
+编辑 `~/.openclaw/config.json` 或工作区配置：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "skills-scanner": {
+        "enabled": true,
+        "config": {
+          "apiUrl": "http://localhost:8000",
+          "scanDirs": [
+            "~/.openclaw/skills",
+            "~/.openclaw/workspace/skills"
+          ],
+          "behavioral": false,
+          "useLLM": false,
+          "policy": "balanced",
+          "preInstallScan": "on",
+          "onUnsafe": "quarantine"
+        }
+      }
+    }
+  }
+}
+```
+
+### 4. 重启 Gateway
+
+```bash
+openclaw gateway restart
+```
+
+### 5. 验证安装
+
+```bash
+# 检查插件状态
+openclaw plugins list
+
+# 检查 Python 依赖
+openclaw skills-scan health
+
+# 在聊天中测试
+/skills-scanner status
+```
+
+## 配置说明
+
+### apiUrl
+- 类型：`string`
+- 默认：`http://localhost:8000`
+- 说明：扫描 API 服务的地址
+
+### scanDirs
+- 类型：`string[]`
+- 默认：自动检测 `~/.openclaw/skills` 等目录
+- 说明：要监控的 Skills 目录列表，支持 `~` 路径
+
+### behavioral
+- 类型：`boolean`
+- 默认：`false`
+- 说明：是否启用行为分析（深度扫描，较慢但更准确）
+
+### useLLM
+- 类型：`boolean`
+- 默认：`false`
+- 说明：是否使用 LLM 进行语义分析
+
+### policy
+- 类型：`"strict" | "balanced" | "permissive"`
+- 默认：`"balanced"`
+- 说明：扫描策略
+  - `strict`: 严格模式，发现任何可疑行为都标记为不安全
+  - `balanced`: 平衡模式（推荐）
+  - `permissive`: 宽松模式，只标记明确的威胁
+
+### preInstallScan
+- 类型：`"on" | "off"`
+- 默认：`"on"`
+- 说明：是否在安装时自动扫描新 Skill
+
+### onUnsafe
+- 类型：`"quarantine" | "delete" | "warn"`
+- 默认：`"quarantine"`
+- 说明：发现不安全 Skill 的处理方式
+  - `quarantine`: 移入隔离目录（推荐）
+  - `delete`: 直接删除
+  - `warn`: 仅警告，不处理
+
+## 使用方法
+
+### 聊天命令
+
+```
+# 扫描单个 Skill
+/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
+/skills-scanner config reset
+
+# 定时任务管理
+/skills-scanner cron status
+/skills-scanner cron register
+/skills-scanner cron unregister
+
+# 帮助
+/skills-scanner help
+```
+
+### CLI 命令
+
+```bash
+# 扫描单个 Skill
+openclaw skills-scan scan ~/.openclaw/skills/my-skill
+
+# 批量扫描（递归）
+openclaw skills-scan batch ~/.openclaw/skills --recursive
+
+# 生成日报
+openclaw skills-scan report
+
+# 健康检查
+openclaw skills-scan health
+```
+
+## 故障排除
+
+### Python 依赖安装失败
+
+如果自动安装失败，可以手动安装：
+
+```bash
+cd extensions/skills-scanner/skills/skills-scanner
+uv venv .venv --python 3.10
+uv pip install --python .venv/bin/python requests>=2.31.0
+```
+
+### API 服务连接失败
+
+1. 确保 `skill-scanner-api` 服务正在运行
+2. 检查配置中的 `apiUrl` 是否正确
+3. 运行健康检查：
+
+```bash
+openclaw skills-scan health
+```
+
+### 定时任务未注册
+
+手动注册定时任务：
+
+```bash
+openclaw cron add \
+  --name "skills-daily-report" \
+  --cron "0 8 * * *" \
+  --tz "Asia/Shanghai" \
+  --session isolated \
+  --message "请执行 /skills-scanner scan --report 并把结果发送到此渠道" \
+  --announce
+```
+
+或在聊天中：
+
+```
+/skills-scanner cron register
+```
+
+### 文件监控不工作
+
+1. 检查 `preInstallScan` 配置是否为 `"on"`
+2. 检查 `scanDirs` 配置是否正确
+3. 查看 Gateway 日志：
+
+```bash
+openclaw logs gateway
+```
+
+### 查看详细日志
+
+```bash
+# Gateway 日志
+openclaw logs gateway
+
+# 或查看状态
+/skills-scanner status
+```
+
+## 开发模式
+
+如果你要修改插件代码：
+
+```bash
+# 1. 修改代码
+cd extensions/skills-scanner
+
+# 2. 重新安装
+openclaw plugins install ./
+
+# 3. 重启 Gateway
+openclaw gateway restart
+
+# 4. 查看日志
+openclaw logs gateway | grep skills-scanner
+```
+
+## 卸载
+
+```bash
+# 卸载插件
+openclaw plugins uninstall skills-scanner
+
+# 清理状态文件（可选）
+rm -rf ~/.openclaw/skills-scanner
+```
+
+## 支持
+
+如果遇到问题：
+
+1. 查看日志：`openclaw logs gateway | grep skills-scanner`
+2. 检查状态：`/skills-scanner status`
+3. 运行健康检查：`openclaw skills-scan health`
+4. 查看配置：`/skills-scanner config show`
+
+## 下一步
+
+- 阅读 [README.md](./README.md) 了解更多功能
+- 查看 [CHANGELOG.md](./CHANGELOG.md) 了解版本历史
+- 自定义配置以适应你的需求

package/QUICKSTART.md

@@ -0,0 +1,106 @@
+# Skills Scanner - 快速开始
+
+## 5 分钟快速上手
+
+### 1. 安装 uv（如果还没有）
+
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# 或使用 Homebrew
+brew install uv
+```
+
+### 2. 安装插件
+
+```bash
+# 在 openclaw 项目根目录
+openclaw plugins install ./extensions/skills-scanner
+```
+
+### 3. 配置插件
+
+创建或编辑 `~/.openclaw/config.json`：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "skills-scanner": {
+        "enabled": true,
+        "config": {
+          "apiUrl": "http://localhost:8000",
+          "policy": "balanced",
+          "preInstallScan": "on",
+          "onUnsafe": "quarantine"
+        }
+      }
+    }
+  }
+}
+```
+
+### 4. 重启 Gateway
+
+```bash
+openclaw gateway restart
+```
+
+### 5. 测试插件
+
+```bash
+# 在聊天中
+/skills-scanner status
+
+# 或使用 CLI
+openclaw skills-scan health
+```
+
+## 常用命令
+
+```bash
+# 扫描单个 Skill
+/skills-scanner scan ~/.openclaw/skills/my-skill
+
+# 扫描所有 Skills
+/skills-scanner scan ~/.openclaw/skills --recursive
+
+# 查看状态
+/skills-scanner status
+
+# 生成日报
+/skills-scanner scan ~/.openclaw/skills --report
+```
+
+## 注意事项
+
+⚠️ **重要**：当前 `scan.py` 是占位脚本，需要连接到实际的 `skill-scanner-api` 服务。
+
+如果你还没有 API 服务，插件仍然可以运行，但扫描功能会返回模拟结果。
+
+## 下一步
+
+1. 实现 `scan.py` 连接到你的 API 服务
+2. 启动 `skill-scanner-api` 服务
+3. 配置扫描目录和策略
+4. 开始使用！
+
+## 获取帮助
+
+```bash
+# 查看帮助
+/skills-scanner help
+
+# 查看配置
+/skills-scanner config show
+
+# 查看日志
+openclaw logs gateway | grep skills-scanner
+```
+
+## 完整文档
+
+- [README.md](./README.md) - 完整功能说明
+- [INSTALL.md](./INSTALL.md) - 详细安装指南
+- [SUMMARY.md](./SUMMARY.md) - 实现总结