SkillScan

详细功能介绍：

技能包的安全准入机制。在技能安装、加载、评估或安全审查时自动激活，通过远程 API 进行安全扫描，根据风险等级决定放行、警告或阻断。

核心能力

能力	说明
安全扫描	对技能包进行自动化安全检测
风险分级	UNKNOWN / SAFE / LOW / MEDIUM / HIGH / CRITICAL
首次全盘扫描	首次加载时自动扫描所有已安装技能
自动更新	每日静默检查更新，无需用户操作
跨平台	支持 Windows / macOS / Linux

触发条件

在以下场景自动激活：

• 安装新技能（install、load、add、use、set up）
• 上传 .zip / .skill 文件
• 粘贴 SKILL.md 内容
• 提及未知技能名称
• 从远程源安装（clawhub、skillhub、npx skills add 等）
• 用户询问"这个技能安全吗"

工作流

首次加载

检查 scripts/.first_run_done：

• 未找到 → 告知用户 SkillScan 已安装，执行首次全盘扫描：

  python <skill_scanner_dir>/scripts/scanner.py first-run
  

  完成后自动创建 .first_run_done 标记文件。

• 已找到 → 跳过，正常操作。

扫描规则

安装方式	扫描时机	要求
.zip 文件	解压前	失败则阻断安装
目录安装（cp / mv / git clone / ln -s）	文件落地后	即时扫描
远程安装（clawhub / skillhub / npx）	安装完成后	立即扫描
未知技能	首次提及	自动扫描

命令行

命令	用途
scanner.py scan <path>	扫描单个技能（.zip 或目录）
scanner.py scan-all	扫描所有已安装技能
scanner.py first-run	首次全盘扫描
scanner.py upgrade	手动更新扫描器

退出码

退出码	判定	处理动作
0	UNKNOWN / SAFE	继续执行
1	LOW / MEDIUM	警告用户，请求确认
2	HIGH / CRITICAL	阻断执行，展示详情
3	扫描失败	解释原因，提供重试

API 接口

基础地址：https://skillscan.tokauth.com

步骤	方法	路径	说明
① 缓存查询	GET	/oapi/v1/skill-scan/search?dir_sha256=<dir_sha256>	查询已有扫描结果
② 上传扫描	POST	/oapi/v1/skill-scan/upload	上传技能包进行扫描
③ 轮询结果	GET	/oapi/v1/skill-scan/result?task_no=<task_no>	每 20 秒轮询，最多 180 秒

环境变量

变量	说明
SKILL_SCANNER_UPDATE_URL	自定义更新源（可选）

最佳实践

• 无例外原则：HIGH / CRITICAL 级别技能一律阻断，不设例外
• 不生成报告：扫描报告不保存到技能目录内
• 自动更新：每日静默检查，保持扫描规则最新
• 首次必扫：新环境首次加载务必执行 first-run 全盘扫描

名称： SkillScan

简介： 技能安全扫描器，作为技能包的强制安全门。所有新技能在安装、加载或启用前必须通过扫描，自动检测风险等级并阻止高危/严重级别技能。支持跨平台，首次加载时自动扫描现有技能库。

详细功能介绍：

技能包的安全准入机制。在技能安装、加载、评估或安全审查时自动激活，通过远程 API 进行安全扫描，根据风险等级决定放行、警告或阻断。