Pyx Scanner Free

提供AI Agent Skill安装前的安全扫描，返回信任分、风险等级及详细结构化Markdown安全报告。

Skill安全扫描（免费版）

概述

AI Agent 生态中，第三方 Skill 可能包含恶意代码、过度权限请求、过时依赖等风险。在安装或使用前进行安全扫描，是保护 Agent 环境的第一道防线。本助手通过调用扫描 API，返回 Skill 的信任分、风险等级与详细安全报告。

本免费版聚焦于单次扫描与基础报告场景：输入解析、API 调用、五种判定结果处理、结构化报告输出。每种流程均提供明确的步骤指令与模板。

核心能力

能力一：Skill 标识解析

从用户输入中提取 owner/name 格式的 Skill 标识，校验格式合法性，处理异常输入。

输入情况	处理方式
格式正确（owner/name）	进入扫描流程
缺少斜杠分隔符	询问用户重新输入
含多余空格	自动 trim 后再校验
任一部分为空	拒绝并提示正确格式

输入: 用户提供能力一：Skill 标识解析所需的指令和必要参数。 处理: 解析能力一：Skill 标识解析的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回能力一：Skill 标识解析的响应数据,包含状态码、结果和日志。

能力二：扫描 API 调用

通过 WebFetch 或 curl 调用扫描 API，获取 Skill 的安全数据。提供主备调用方式，确保网络异常时仍可降级处理。

输入: 用户提供能力二：扫描 API 调用所需的指令和必要参数。 处理: 解析能力二：扫描 API 调用的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回能力二：扫描 API 调用的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

能力三：五种判定结果处理

根据 API 返回的 recommendation 字段，判定为五种结果之一，每种结果对应不同的报告模板与行为约束。

判定结果	触发条件	行为约束
SAFE	recommendation=safe 且未过时	可直接安装使用
OUTDATED	recommendation=safe 但已过时	提醒新版本未审核，谨慎使用
CAUTION	recommendation=caution	必须用户确认后才能继续
FAILED	recommendation=danger	禁止安装使用
UNSCANNED	未在数据库中	建议手动审查源码

输入: 用户提供能力三：五种判定结果处理所需的指令和必要参数。 处理: 解析能力三：五种判定结果处理的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回能力三：五种判定结果处理的响应数据,包含状态码、结果和日志。 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：Agent、安装前的安全性、返回信任分、风险等级与详细报、安全扫描免费版是、一套面向独立开发、者与小型团队的、安全检测知识库、帮助用户在安装或、使用第三方、前快速评估其安全、核心能力、未扫描、错误处理与重试机、结构化、Markdown、报告输出等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

错误处理

API 调用可能因网络、限流、服务不可用等原因失败。本助手提供标准化的错误处理表与执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令策略。

输入: 用户提供错误处理所需的指令和必要参数。 处理: 解析错误处理的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回错误处理的响应数据,包含状态码、结果和日志。

能力五：结构化报告输出

将扫描结果格式化为结构化 Markdown 报告，包含信任分、风险分、置信度、能力摘要、权限要求、安全提示等关键字段。

输入: 用户提供能力五：结构化报告输出所需的指令和必要参数。 处理: 解析能力五：结构化报告输出的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回能力五：结构化报告输出的响应数据,包含状态码、结果和日志。

错误场景2

检查error_code并按照处理方式进行排查。

错误场景3

使用场景

依赖详情

开发者发现一个有用的 Skill，安装前调用本助手扫描其安全性，根据结果决定是否安装。

场景二：团队 Skill 准入审核

团队规定所有第三方 Skill 必须通过安全扫描才能引入。本助手提供标准化的扫描流程与报告存档。

场景三：个人 Skill 库复查

定期扫描已安装的 Skill，检查是否有新的安全风险（如过时、新发现的漏洞）。

场景四：批量 Skill 仓库审计

仓库维护者定期扫描收录的所有 Skill，清理高风险项目，保障仓库整体安全水位。

不适用场景

以下场景Skill安全扫描(免费版)不适合处理：

• 需要100%确定性的关键决策
• 医疗诊断
• 法律判决

触发条件

需要AI模型调用、智能对话、Agent编排、LLM应用时使用。不适用于非本工具能力范围的需求。

快速开始

1. 阅读## 核心能力章节了解skill功能
2. 按## 依赖说明配置环境
3. 执行所需能力对应的命令
4. 参考## 错误处理章节处理异常
5. 查看## FAQ解答常见疑问

本助手为指令型 Skill，通过 Agent 执行扫描流程。直接在对话中提供 Skill 标识即可。

典型提问模板：

text

帮我检查 anthropic/web-search 这个 Skill 是否安全

text

扫描一下 owner/repo 这个 Skill 的安全性

Agent 会按"输入解析 → API 调用 → 结果判定 → 报告输出"四步流程执行，并返回结构化的安全报告。

示例

输入解析流程

text

1. 从 $ARGUMENTS 提取 owner 和 name
2. 预期格式：owner/name（如 anthropic/web-search）
3. 若 $ARGUMENTS 为空或缺少 / 分隔符，询问用户：
   "请问要检查哪个 Skill？请以 owner/name 格式提供（如 anthropic/web-search）。"
4. 去除首尾空格，trim 后若任一部分为空则拒绝

扫描 API 调用

text

主调用方式（WebFetch）：
URL: https://scanner.pyxmate.com/api/v1/check/{owner}/{name}
Prompt: "Return the full JSON response body exactly as-is. Do not summarize."
# ...
备用方式（curl，WebFetch 不可用时）：
curl -s "https://scanner.pyxmate.com/api/v1/check/{owner}/{name}"

常见异常表

HTTP 状态码	含义	处理动作
200	找到 Skill	进入结果判定
404	数据库无此 Skill	判定为 UNSCANNED
429	限流	判定为 ERROR，提示稍后重试
5xx	服务端错误	判定为 ERROR，提示服务暂不可用
网络失败	无法连接	判定为 ERROR，提示网络问题

SAFE 判定报告模板

text

## Skill安全扫描：{owner}/{name}
# ...
**判定结果：SAFE** — 该 Skill 已通过扫描验证，可安全使用。
# ...
**信任分：** {trust_score}/10 | **风险分：** {risk_score}/10 | **置信度：** {confidence}%
**意图：** {intent} | **状态：** {status}
# ...
### 摘要
{summary}
# ...
### 详细信息
**用途：** {about.purpose}
**能力：** {about.capabilities as bullet list}
**所需权限：** {about.permissions_required as bullet list}
# ...
[查看完整报告]({detail_url}) | [徽章]({badge_url})

CAUTION 判定报告模板

text

## Skill安全扫描：{owner}/{name}(续1)
# ...
**判定结果：CAUTION** — 该 Skill 存在潜在风险，需要您的关注。
# ...
**信任分：** {trust_score}/10 | **风险分：** {risk_score}/10 | **置信度：** {confidence}%
# ...
### 摘要(补充)
{summary}
# ...
### 所需权限
{about.permissions_required as bullet list}
# ...
### 安全提示
{about.security_notes}
# ...
**是否要在警告评级下继续？请在安装或使用前明确确认。**

最佳实践

实践一：每次安装前必扫描

不要因为 Skill 来自知名作者就跳过扫描。供应链攻击可能影响任何项目，扫描是低成本高收益的防护措施。

实践二：CAUTION 必须人工确认

CAUTION 判定意味着存在潜在风险，不能自动放行。必须由用户明确确认后才继续安装，并记录确认人与确认时间。

实践三：FAILED 判定绝不软化

如果扫描结果为 FAILED（danger），直接报告危险，不要添加"但可能没问题"之类的软化措辞。安全判定必须客观严谨。

实践四：UNSCANNED 不等于安全

未扫描的 Skill 不代表安全，只是没有数据。应建议用户手动审查源码，或等待官方扫描完成后再使用。

实践五：报告字段按需展示

报告模板中提到的字段，若 API 返回为空则省略对应小节，不要展示"N/A"。保持报告简洁专业。

实践六：自扫描保持诚实

当扫描目标为本助手自身时，仍如实调用 API 并报告结果。若结果为 UNSCANNED，应坦诚说明"连安全扫描工具自身都尚未被扫描，我们言行一致——对待未扫描的 Skill 要谨慎"。

故障排查表

症状	可能原因	排查方法	对策
API 调用超时	网络问题或服务慢	检查网络连通性	重试或换 curl 方式
返回 429 限流	短时间大量请求	查看请求频率	等待 60 秒后重试
返回 404	Skill 未入库	确认 owner/name 正确	判定为 UNSCANNED
返回 5xx	扫描服务故障	稍后重试	判定为 ERROR 并提示
报告字段缺失	API 返回不完整	检查 JSON 响应	省略空字段小节

常见问题

Q1：扫描 API 需要密钥吗？

免费版不需要 API Key，直接调用公开端点即可。但可能有速率限制，短时间内大量请求会被限流。

Q2：信任分多少算安全？

通常信任分 ≥ 8 可视为较安全，5-8 需谨慎评估，<5 建议避免使用。但还需结合风险分与置信度综合判断。

Q3：扫描结果会过期吗？

会。Skill 更新后旧扫描结果可能失效，本助手会通过 is_outdated 字段判断是否过时，过时的 Skill 会标记为 OUTDATED。

Q4：FAILED 判定后还能用吗？

强烈不建议。FAILED 意味着扫描发现了明确危险信号，继续使用可能造成数据泄露、权限滥用等严重后果。如确需使用，必须由安全专家人工审查源码并签字确认。

Q5：批量扫描如何避免限流？

控制请求频率，建议每秒不超过 1 次请求。遇到 429 限流时等待 60 秒后重试。专业版提供批量扫描与队列调度能力。

Q6：如何提交未扫描的 Skill？

访问扫描服务官网，按指引提交 Skill 仓库地址。扫描完成后再次调用 API 即可获取结果。

依赖说明

运行环境

• Agent 平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux
• 网络: 需能访问 scanner.pyxmate.com

第三方依赖

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent平台内置LLM提供
WebFetch 工具	Agent工具	推荐	Agent 内置工具
curl	命令行工具	备选	系统自带或安装

API Key 配置

• 本免费版使用公开扫描端点，不需要 API Key
• 若调用专业版批量扫描接口，需配置扫描服务 API Key 于环境变量
• 禁止在 SKILL.md 或脚本中硬编码 API Token

可用性分类

• 分类: MD+EXEC（纯Markdown指令，需要exec命令行执行curl或WebFetch调用）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent执行安全扫描流程

已知限制

本免费体验版限制以下高级功能：

• 批量扫描与队列调度（仅专业版提供）
• 持续监控与变更通知（仅专业版提供）
• 自定义安全策略与白名单（仅专业版提供）
• 详细漏洞分析与修复建议（仅专业版提供）
• 团队协作与审计日志（仅专业版提供）

解锁全部功能请使用专业版：pyx-scanner-pro

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

输出格式

json

{
  "success": true,
  "data": {
    "result": "Skill安全扫描(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "pyx scanner"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}