SafeSkill 安全中心

SafeSkill 是面向 Cursor、OpenAI Codex 和 Claude Code Agent Skill 的安全检测、安装防护和基础管理插件。0.5.0 起，安全结论全部来自 SafeSkill API，插件不再内置离线检测规则。

打开安全中心

点击 VS Code 左侧 Activity Bar 的 SafeSkill 盾牌图标，默认会打开中文安全中心。也可以执行命令 SafeSkill：打开安全中心。如不希望自动打开，可关闭 safeskill.openSecurityCenterOnView。

配置 API

1. 默认连接 https://safeskill.qianxin.com；本地开发时可修改 safeskill.serverUrl；
2. 在安全中心点击“配置 Token”，或执行 SafeSkill：配置 API Token；
3. Token 保存于 VS Code SecretStorage，不会写入 settings.json，也不会在页面显示明文。
4. Token 保存后会立即启用后续新增或更新 Skill 的 API 自动检测，但不会自动开始全盘扫描；如需检测全部现有 Skill，请点击“全盘扫描”。
5. Token 配置成功后，按钮显示为“修改 Token”，仍可点击以更新凭据。
6. 在“修改 Token”窗口中留空并提交，经二次确认后可清除 Token；按 Esc 则保留原 Token。

目录监控默认每 10 秒刷新一次。即使未配置 Token，新安装、删除或更新的 Skill 也会自动出现在树视图中；插件不会调用 API，新增或内容已变化的 Skill 显示为“未检测”。

插件先为待检测内容生成稳定 ZIP，并使用该 ZIP 的 SHA1 调用 /openapi/v1/judge 查询历史任务；遇到超时或临时网络错误时会指数退避重试，次数由 safeskill.judgeMaxRetries 控制，首次超时由 safeskill.judgeTimeoutSeconds 控制；命中已完成报告或进行中任务时不重复上传，未命中或查询不可用时才调用 /openapi/v1/submit，随后通过 /openapi/v1/report 获取结论。检测任务使用 is_public=false。没有 Token 时不会执行扫描，也不会以本地规则生成“安全”或“危险”结论。普通扫描、全盘扫描、安装监控和安装前检测均不会携带 force_rescan。

检测并安装 Skill

安全中心的“检测并安装 Skill”支持：

• 包含 SKILL.md 的本地文件夹；
• .zip 压缩包，SKILL.md 可以位于压缩包根目录或单个子目录中。

导入流程：

1. 先选择“ZIP 压缩包”或“本地文件夹”，再选择对应文件；
2. 选择 OpenAI Codex、Cursor 或 Claude Code；
3. 选择用户级或工作区级安装；
4. 计算稳定 ZIP 的 SHA1 并查询历史报告，未命中时再私密提交至 SafeSkill API；
5. API 判定危险时阻止安装，警告时要求人工确认；
6. 只有取得最终 API 结论后才复制到目标 Skill 目录。

检测开始后会打开独立的“安装前安全检测”窗口，展示读取、历史报告查询、提交、深度分析、安全决策和安装六个阶段。普通扫描的等待上限仍由 safeskill.pollTimeoutSeconds 控制；安装前检测单独使用 safeskill.installPollTimeoutSeconds，默认等待 600 秒。分析期间可以取消本地等待，关闭该窗口也会取消本次安装；已经提交的后台任务不会被删除。 安装成功，或安全结论阻止安装后，窗口标题会从“正在检测 Skill 名称”切换为“检测完成 Skill 名称”；具体结果继续由状态徽标显示。

窗口会区分“后台仍在分析”“后台分析失败”“API 结论无法识别”和“恶意并阻止安装”。MALICIOUS、DANGEROUS、BLOCK 都会映射为危险结论并在写入目标目录前阻断。

ZIP 导入会校验路径穿越、绝对路径、符号链接、重复路径、CRC、条目数和解压体积，并要求压缩包中恰好包含一个 SKILL.md。体积限制由 safeskill.maxPackageMb 控制。

用户级目标目录：

• Codex：$CODEX_HOME/skills 或 ~/.codex/skills
• Cursor：~/.cursor/skills
• Claude Code：~/.claude/skills

工作区级目标目录分别为 .codex/skills、.cursor/skills 和 .claude/skills。

自动检测与管理

默认启用 safeskill.scanOnInstall。目录监控始终运行，插件会发现系统级、用户级和工作区中新安装、删除或更新的 Skill；配置 Token 后，新增或更新的 Skill 会自动提交到 SafeSkill API。打开仓库子目录时，插件也会向上查找到 Git 仓库根目录，识别其中的 .codex/skills、.cursor/skills、.claude/skills 和 .agents/skills。第三方工具通常先写入文件再被插件发现，因此这属于快速安装后检测；需要安装前阻断时，请使用 SafeSkill 自带的导入流程。

自动检测结果为安全时不弹窗；警告结果提供“查看报告”，危险结果提供“查看报告”“打开目录”“删除 Skill”，检测失败可重试。删除操作始终需要二次确认。同一次巡检发现多个问题 Skill 时只显示一条摘要，详细记录保留在安全中心。

Codex Skill 根目录中的目录符号链接也会被发现。插件保留 .codex/skills 中的安装位置，同时解析真实目录来计算哈希、生成 ZIP 和读取报告位置，并按真实路径去重。左侧会显示 符号链接 · CC Switch、符号链接 · Codex Plugin 等已知来源；未知来源使用目标父目录名，并在详情中注明名称是根据目标路径推断的。插件不会把 ~/.cc-switch/skills 当成第二个扫描根目录。删除这类 Skill 时只移除 Codex 链接，不删除链接指向的真实目录。断开的链接、不可访问的链接和目录链接循环会被安全忽略。

左侧 Skill 安全管理树按“客户端 → 层级 → Skill”组织，只展示存在 Skill 的层级。层级包括系统级、用户级和工作区级。Codex .system Skill 显示为只读，仍可扫描、打开和查看报告，但不会提供修改调用模式或删除操作。

安全中心还支持查看报告、重新扫描、强制回扫、打开目录、切换“仅手动调用”和删除 Skill。Codex .system Skill 保持只读。

强制回扫

在安全中心的 Skill 行点击警示色“强制回扫”，或在左侧 Skill 菜单和命令面板执行 SafeSkill：强制回扫 Skill。确认后插件会跳过 /openapi/v1/judge 历史报告查询，直接调用 /openapi/v1/submit，并在 multipart 中附加 force_rescan=true，要求后台创建新的扫描任务。进度窗口会明确显示“强制提交”，日志会记录 force_rescan=true。

强制回扫只用于用户显式触发的单个 Skill，不会影响普通扫描、全盘扫描、自动安装监控或检测并安装流程。该操作会消耗新的后台扫描资源，因此执行前必须二次确认。

确认提交后按钮立即变为“回扫中…”并禁用，插件代码层也会阻止同一 Skill 重复提交。取得最终报告后恢复显示“强制回扫”，并通过绿色状态和悬停提示说明上次任务已完成；提交或后台分析失败后显示“重试回扫”。如果本地等待超时但后台仍在分析，按钮继续保持“回扫中…”，后台报告同步完成后再自动切换。按钮状态随扫描记录保存在 VS Code globalState，重载窗口后仍可恢复；初始化全部 Skill 状态会同时重置该状态。

日志

打开 查看 → 输出（Ctrl+Shift+U），选择 SafeSkill。日志包含发现目录、导入事件、文件哈希、API 任务 ID、轮询状态和错误。

最近活动

安全中心会把最近活动保存在 VS Code 本地 globalState 的 safeskill.activity.v1 中，重新加载窗口或重启 VS Code 后会自动恢复。最多保存 60 条、最长保留 30 天；启动时会立即移除过期或无效记录。活动包含 Skill 名称、API 任务 ID、结论、状态、失败原因及开始/完成时间，不保存 API Token 或 Skill 文件内容。

全盘扫描会同时记录总任务和每个 Skill 的最终结果。点击“最近活动”旁的“清空”需要二次确认，只删除活动历史，不删除扫描报告、Skill 或后台任务。

安全中心分页

安全中心的“已安装 Skill”按每页 15 条展示，“最近活动”按每页 10 条展示，并各自维护页码。列表底部提供“上一页”“下一页”、当前页/总页数、当前条目范围和总条数。扫描状态或后台报告刷新时保留用户当前所在页；数据减少导致页码超出范围时自动回退到最后一页，清空最近活动后回到第 1 页。分页只发生在插件 Webview，本地仍保留最多 60 条活动记录，不改变 API 请求或活动持久化格式。

“已安装 Skill”表格的状态列固定为 84px，状态内容保持单行。安全、危险、扫描中、等待中等状态切换时不会再挤压相邻列。

表格最后一列标题为“操作”。强制回扫完成后按钮仍显示“强制回扫”，绿色状态和悬停提示用于说明上次任务已完成；执行中显示“回扫中…”，失败时显示“重试回扫”。

初始化全部 Skill 状态

点击“已安装 Skill”标题旁的“初始化状态”，或在命令面板执行 SafeSkill：初始化全部 Skill 状态。确认后，插件会将当前发现的全部 Skill 恢复为“未检测”，并清除本地报告、风险项、任务 ID、后台等待状态、错误、编辑器诊断和强制回扫状态。

初始化不会删除 Skill 文件、最近活动或 SafeSkill 后台已有报告，也会保留内容哈希和压缩包哈希，因此不会把全部 Skill 误判为新安装并自动重新扫描。存在扫描中、等待后台结果或强制回扫中的 Skill 时，初始化操作会被阻止。

实时防护布局

实时防护进度条下方固定预留两行状态文字和一行 API 任务号。轮询期间状态文字长短变化、API 任务号出现或消失时不会改变卡片高度；过长内容以省略方式显示，鼠标悬停可查看完整文本。

安全中心宽屏布局使用统一的二维网格：“实时防护”和“防护模块”位于第一行，“已安装 Skill”和“最近活动”位于第二行。第二行的两个列表面板自动等高，分页栏固定在面板底部，从而保持面板顶边、底边和分页位置对齐。窄屏下恢复为“实时防护 → 已安装 Skill → 防护模块 → 最近活动”的单列顺序。

安全边界

该插件是 Skill 安全防护工具，不是操作系统沙箱。不同 Agent 产品不一定暴露可靠的隐式 Skill 调用事件，因此建议扫描所有已启用 Skill，并在需要强制执行时安装 Agent Hook。

LLM 静默失败

当后台返回 silent_long_zero_findings_small_skill 时，插件会停止轮询并显示“后台分析失败”，不会自动绕过缓存强制重新提交。普通“扫描”仍执行 SHA1 历史查询；确认需要后台重新分析时，可显式执行“强制回扫”。

暂停全盘扫描

全盘扫描进行时，可在安全中心的“实时防护”卡片点击“暂停扫描”。暂停只阻止插件继续提交新的 Skill；已经提交给 SafeSkill API 的当前任务仍会等待完成。点击“继续扫描”后从下一个 Skill 接着执行。取消扫描仍使用 VS Code 进度通知中的 Cancel 按钮；取消会立即停止本地轮询和后续提交，但不会删除已经提交给后台的任务。

API 风险项与本地文件

插件不包含离线风险规则。“API 风险项”全部来自 SafeSkill API 的报告，并缓存于 VS Code globalState。插件兼容新版 location.file_path、location.line_number、location.line_end、location.column_start 和旧版 file、line 字段，过滤 metadata.meta_false_positive=true 的误报项，再把有效风险的精确文件和行列范围映射到 VS Code“问题”面板。报告路径必须落在 Skill 根目录内，越界或不存在的路径会安全回退到 SKILL.md。

报告窗口采用完整技术版：安全与非安全结果都会展示 API 裁决、置信度、建议动作、扫描时间、耗时、报告 Schema、内容 SHA-256、稳定 ZIP SHA-1、文件数量、包大小、严重级别统计、分析器状态及降级信息。风险项还会展示规则、分类、分析器、精确位置、源码片段、匹配证据、修复建议、参考资料、威胁情报和元数据；安全报告会明确显示零有效风险项以及扫描覆盖情况。

网络模式

safeskill.networkMode 默认是 direct：插件使用 Node 原生 HTTP/HTTPS 套接字直接连接 SafeSkill API，不读取 HTTP_PROXY、HTTPS_PROXY 或 Windows HTTP 代理。必须通过企业代理时可改为 system。如果 VPN 使用 TUN/虚拟网卡在系统路由层接管流量，应用内直连设置无法绕过该路由。