使用验签工具包对 Skill 包验签

本文介绍如何使用 VeriAgent 技能验签工具包，对已签名 Skill 包进行本地验签。验签通过表示签名文件有效，且包内业务文件与签名时一致。

本方式适用于无法直接使用控制台页面验签，或需要在安装、加载、持续集成、交付接收环节自动执行验签的场景。

前置条件

开始前，请确认你已准备好：

已签名 Skill zip 包。
VeriAgent 技能验签工具包目录，例如 skill-verification。
Node.js。
openssl。
/usr/bin/unzip。

注意：验签对象必须是已签名的 Skill zip 包，不要传入解压后的 Skill 目录。未签名 Skill 包通常不包含 META-INF/SKILL_VERIFY.MF 和 META-INF/SKILL_VERIFY.P7S，会被判定为验签失败。

执行验签

bash

cd "/Users/<用户名>/Desktop/skill-verification"

请将上面的目录替换为实际工具包目录。该目录下应包含 SKILL.md 和 scripts/skill-verification.js。

执行验签命令。

bash

node scripts/skill-verification.js "<已签名 Skill 包路径>"

例如，已签名包在桌面：

bash

node scripts/skill-verification.js "/Users/<用户名>/Desktop/signed-skill.zip"

如需只输出 JSON，添加 --json 参数：

bash

node scripts/skill-verification.js "/Users/<用户名>/Desktop/signed-skill.zip" --json

不加 --json 时，终端会先输出摘要，再输出完整 JSON；加上 --json 时，只输出 JSON，便于自动化流程解析。

查看结果

摘要示例：

text

验签文件: signed-skill.zip
verified: true
manifestSignatureVerified: true
manifestSignatureMessage: P7S 已验证 MF 未被篡改
matchedFiles: 2/2
metadata.scanId: scan-task-id

重点查看以下字段：

字段	说明
`verified`	总体验签结果。为 `true` 表示签名和文件完整性校验通过。
`manifestSignatureVerified`	`P7S` 对 `MF` 的验签结果。
`matchedFiles` / `totalFiles`	与签名清单匹配的文件数量和签名清单中的文件总数。
`mismatchedFiles`	摘要不一致的文件列表。
`missingFiles`	当前包中缺失的文件列表。
`extraFiles`	签名后额外出现的业务文件列表。
`issues`	验签过程中发现的问题。
`metadata.scanId`	签名清单中的扫描任务 ID。

JSON 输出示例，以下内容已隐藏签名内容、文件摘要和扫描任务 ID，并省略了部分 fileDetails 明细：

json

{
  "verified": true,
  "manifestSignatureVerified": true,
  "manifestSignatureMessage": "P7S 已验证 MF 未被篡改",
  "totalFiles": 4,
  "matchedFiles": 4,
  "mismatchedFiles": [],
  "missingFiles": [],
  "extraFiles": [],
  "fileDetails": [
    {
      "name": "product-requirements-document/SKILL.md",
      "computedHash": "<文件摘要>",
      "originalHash": "<签名清单中的文件摘要>",
      "match": true
    }
  ],
  "signatureContent": "<已脱敏的 P7S 签名内容>",
  "originalDigestResult": "<签名清单中的摘要汇总>",
  "currentDigestResult": "<当前文件计算得到的摘要汇总>",
  "metadata": {
    "scanId": "<扫描任务 ID>",
    "hashType": "SHA-256"
  },
  "issues": []
}

验签通过时，通常满足：

verified 为 true。
manifestSignatureVerified 为 true。
mismatchedFiles、missingFiles、extraFiles 均为空。
issues 为空。

验签失败时，命令退出码通常为非零，自动化流程可根据退出码或 verified 字段阻断安装、发布或交付。

常见问题

现象	处理方式
`Cannot find module ...`	确认当前目录是验签工具包目录，且存在 `scripts/skill-verification.js`。
`文件不存在`	检查 Skill 包路径是否正确；路径中包含空格时，请使用英文双引号包裹。
`无法解析 ZIP 文件` 或 `unzip list failed`	确认传入的是原始已签名 Skill zip 包，不是解压后的目录或损坏文件。
缺少 `SKILL_VERIFY.MF` 或 `SKILL_VERIFY.P7S`	确认使用的是签名后的 Skill zip 包。
`openssl` 相关错误	执行 `openssl version` 确认本地环境可用。

下一步

验签通过后，可以将该 Skill 包导入 Agent、进入企业准入流程，或继续执行上架、交付和归档操作。如需查看签名记录，可进入 VeriAgent 控制台的对应签名详情页。