Permission Manifest Guard

何时调用

在需要了解某个技能所需权限以决定是否信任之前，使用此技能。当满足以下情况时调用：

• 安装前审查新技能 — 技能已下载或被提出，您需要在允许执行前了解其访问的资源。
• 检查技能权限 — 想要获取所有与权限相关的信号摘要（二进制文件、网络请求、环境变量、文件路径、Shell 命令、配置文件、包管理器、高风险能力）。
• 生成权限清单 — 需要一份人类可读的 Markdown 报告和一份机器可解析的 JSON 清单，用于审计或策略决策。
• 决定是否沙盒化或拒绝安装 — 技能的观察行为可能超出其声明的能力，需要评分后的建议。
• 审计技能的声明行为与实际行为差异 — 想比较 SKILL.md 中声明的内容与源代码实际执行的行为。

如果任务不涉及评估技能的信任度、权限或安装安全性，则不应使用此技能。

如何调用 — CLI

从命令行运行该技能，将技能目录作为唯一参数传入：

npx permission-manifest-guard /path/to/skill

标准输出（stdout）： Markdown 格式的权限清单（人类可读报告）。可根据需要重定向或管道处理。

错误输出（stderr）： 分析各阶段产生的诊断警告，以及生成的 JSON 文件路径。

副作用： 在技能目录中写入 permission-manifest.json 文件。该文件包含结构化清单，供机器消费。

退出码： 成功时为 0，参数无效或分析失败时为 1。

如何调用 — 程序化方式

导入 analyzeSkill 并传入技能目录路径进行调用：

import { analyzeSkill } from 'permission-manifest-guard';

const result = await analyzeSkill('/path/to/skill');

返回的 AnalysisResult 包含三个字段：

如何处理输出

分析结果会基于技能声明的元数据与其源代码行为的匹配程度，生成一个处置建议。请根据建议采取相应行动：

• 允许 — 声明的能力与实际行为一致，未检测到未声明的访问。可正常安装。
• 审查 — 发现轻微不一致（例如未声明的环境变量或低严重性能力缺口）。应在继续前检查清单中的不一致项。需人工或策略审核确认意图。
• 沙盒 — 检测到显著的未声明能力。仅可在隔离执行环境中安装，限制文件系统、网络和进程访问。
• 拒绝 — 存在严重不一致或危险的未声明能力。不得安装。应标记该技能进行进一步调查或从注册表中移除。

Markdown 清单 是供人类使用的成果——可用于评审流程、审计日志或审批工作流。

JSON 清单 适用于自动化流水线——可输入策略引擎、仪表板或准入检查。

若 diagnostics 非空，说明部分文件未能完全分析。对带有分析警告的技能应更加谨慎——分析不完整意味着真实权限范围可能大于报告内容。

局限性

• 仅静态分析。该技能仅检查源代码和元数据文件，不会执行技能或追踪运行时行为。动态构造的命令、延迟导入或运行时代码生成无法被检测。
• 无传递依赖扫描。仅分析技能目录内的文件。若技能依赖外部包并执行特权操作，这些行为不会出现在清单中。
• 启发式提取。二进制文件、域名、环境变量和 Shell 命令的提取采用模式匹配。非典型代码结构可能导致误报或漏报。
• 单一目录范围。工具每次仅分析一个技能目录。多技能仓库需分别运行。