Claude Plugins Validation

Claude插件验证（CPV）

检查您的Claude Code插件是否正确、安全，是否可以发布，而无需花费任何令牌。

CPV是一套Python脚本，用于在您的计算机上本地分析Claude Code插件。每一次检查都是离线运行的，可以立即产生结果，而且不需要任何费用。无需人工智能调用，无需API密钥，无需云服务。

有 使用CPV的两种方法。选择适合您工作流程的选项：

______________________________________________________________________

目录

• CPV检查什么？

- Claude代码文档

• 第1部分：独立验证（通过uvx）

- 入门指南 - 可用脚本 - 选项 - 阅读结果

• 第2部分：克劳德代码插件

- 安装 - AI代理——主界面 - 斜杠命令

• 对于开发者
• 需求
• 故障排除

______________________________________________________________________

CPV检查什么？

CPV运行 20名专业验证者 覆盖 190+条规则 在Claude Code插件的每个部分（17个插件验证器+3个市场/设置验证器）：

经验插件加载漏洞CPV捕获

通过对Claude Code的插件加载器进行广泛的实证测试（2026年4月），CPV确定了官方文档隐藏的五种无声故障模式和CC自己的故障模式 claude plugin validate 未检测到。CPV捕获了所有五个：

1. agents 带有文件夹路径的字段 --CC以隐晦的方式拒绝 agents: Invalid input。如果跳过验证，则代理将在运行时自动删除。CPV发出MAJOR，具有有用的修复配方(.md 仅文件路径）。官方文档自己的完整模式示例显示 "./custom/agents/" 不正确。
2. hooks: "./hooks/hooks.json" 级联 --将覆盖指向自动发现的默认文件会自动通过验证，但在运行时CC会发出 Duplicate hooks file detected 与 禁用插件的MCP服务器 随着 error type: hook-load-failed.CPV发射MAJOR。
3. MCP跨源服务器名称冲突 --两者中的服务器名称相同 .mcp.json 和内联 plugin.json:mcpServers 导致无声的内联赢得阴影；这 .mcp.json 声明在没有警告的情况下被删除。CPV每次复制都会发出MAJOR。
4. LSP跨源服务器名称冲突 --LSP服务器同样存在无声阴影风险。CPV每次复制都会发出MAJOR。
5. mcpServers: "./.mcp.json" 冗余 --将覆盖指向自动发现的默认文件。无害的单负载（没有级联式挂钩），但冗余且令人困惑。CPV发出轻微的轻推。

所有五条规则都有实证证据记录在 skills/fix-validation/references/empirical-loading-bugs.md （13个测试插件场景、调试日志摘录、运行时探测）。

跨市场依赖分配表（TRDD-20108ab7）

当 plugin.json 声明依赖关系 dependencies[i].marketplace Claude Code指向一个非声明插件所在的市场，在运行时使用 cross-marketplace 除非宿主 marketplace.json::allowCrossMarketplaceDependenciesOn array按名称列出目标市场。CPV在安装之前就抓住了这个主要问题，通过三种部署形状在磁盘上自动发现托管marketplace.json：

• 布局C（插件中的市场） --插件自己的 .claude-plugin/marketplace.json
• 布局B（嵌套单仓库） --家长 .claude-plugin/marketplace.json （步行至3层）
• 缓存布局 — `~/.claude/plugins/cache//

/ （直系父母 marketplace.json`)

当自动发现找不到托管marketplace.json（独立插件克隆，CI中的新PR）时，CPV会发出INFO而不是MAJOR。通过 validate_plugin --marketplace-context PATH 强制使用特定的marketplace.json。规格： 插件依赖项.md:54-79.

所有进程内检查都作为纯Python运行——没有API调用，没有使用令牌，也没有向任何地方发送数据。

外部安全扫描程序（始终运行，仅可编程）

validate_security.py 编排 五台外部扫描仪 以及其进程内规则包。每次扫描时，每个都会无条件调用，当其源二进制文件无法在PATH上解析或无法从其源URL安装时，会自动跳过INFO咨询 无退出标志 --防止呼叫者意外地使覆盖静音。这 enable_* 关键字参数 validate_security() 仅作为测试隔离旋钮存活。

v2.48--已删除gitleaks。 trufflehog（约700个探测器 --concurrency 并行扫描支持）提供超集覆盖。gitleaks运送了约150个探测器，但在可靠的并行扫描下崩溃，因此已从外部扫描仪名单中退役。

v2.48-- cpv-doctor --install-scanners. 新的批处理安装程序通过一个命令（静默和幂等）获取CPV使用的每个扫描仪。它还安装 fclones (丙氧基/氟喹诺酮类)，一个基于Rust的重复文件查找器，用作每次CPV扫描的第一步，以跳过重复文件（跨插件共享的README、供应商提供的库、相同的SKILL.md模板）。每个平台级联：macOS= brew install fclones，Linux= snap install fclones 然后 cargo install fclones，Windows=GitHub发布下载 cargo install fclones.根据工具选择退出： CPV_NO__INSTALL=1 （例如。 CPV_NO_FCLONES_INSTALL=1).

v2.48-- cpv-doctor --prune-old-versions. 释放累积的磁盘空间 claude plugin update 不会删除旧版本。两阶段用户体验： --prune-dry-run 预览； --prune-old-versions 实际上删除。始终保持活动版本（以Claude Code在中引用的版本为准 enabledPlugins). --prune-keep N 每个插件保留N个最新版本（默认值1）。

v2.48——URL/归档摄取+松散模式。 position参数现在接受：

• GitHub网址: https://github.com/owner/repo 或速记 github:owner/repo --克隆与 gh repo clone --depth 1 扫描到tmpdir，然后自动清理。
• 地方档案: *.zip, *.tar.gz, *.tgz, *.tar.bz2, *.tar.xz, *.tar --提取到tmpdir（具有路径遍历保护），扫描，清理。
• 宽松模式 对于扁平技能包： --loose （别名 --bare-folder)绕过 .claude-plugin/ 前提条件。CPV自动检测扁平包装（5+ *.md 文件，否 plugin.json，没有规范 skills//SKILL.md 布局）并打印HINT推荐 --loose 在错误消息中。

v2.48--使用dedup扫描一次市场树。 --marketplace 现在将每个插件放在一个tmpdir下，运行 fclones 在整个语料库上删除一次重复的硬链接（缓存不变——硬链接安全地共享索引节点），然后扫描每个插件的重复数据删除暂存。对规范文件的发现会自动传播到最初包含相同内容副本的对等插件（去重没有覆盖漏洞）。现实世界：ai maestro插件（10个插件）每次扫描可保存约1849个重复文件/约21 MB。

v2.48-- cpv-main-menu. 单个交互式入口点通过嵌套的AskUserQuestion子菜单（验证/GitHub/修复/创建/管理/GitHub设置/语义/帮助）路由每个CPV命令。每个菜单/子菜单都包含一个取消/退出选项。当您不记得要直接调用哪个斜线命令时，请使用此选项。

每个外部扫描仪的结果都通过相同的自扫描过滤器链进行路由，CPV适用于自己的规则(cpv_self_scan_skip → 卖方付款→ 开发划痕→ 测试文件→ FP语料库标记→ 每行目录/docstring/注释模式源谓词）。这保证了使用CPV扫描CPV——或扫描任何附带自己的规则目录的插件——永远不会将目录源作为发现。然后，聚合器将所有发现按以下方式分组 (level, rule_id) 因此，每个漏洞类型只显示一次完整的解释，然后是发生次数和上限文件：行列表——有限制的报告大小，没有发现会被默默地删除。

Claude代码文档

CPV根据官方的Claude Code规范验证插件。如果你正在构建一个插件，以下是关键参考：

• 发现插件 --查找和安装插件
• 插件参考 --plugin.json模式、CLI命令、组件规范
• CLI命令参考 --安装、卸载、启用、禁用、更新
• 技能参考 --SKILL.md前体、替换、动态上下文
• 挂钩参考 --27钩事件，匹配，钩类型
• Claude Code发行说明 --最新更改和插件更新

______________________________________________________________________

第1部分：独立验证（通过uvx）

无需安装。 只需运行命令并将其指向您的插件文件夹即可。

入门指南

你需要 紫外线 安装。然后：

# Validate a plugin (runs all 20 checks + linting)
uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml \
    cpv-remote-validate validate_plugin /path/to/your-plugin

就这样 uvx 将CPV临时下载到隔离环境中，在完全环境隔离的情况下运行验证（目标插件的本地配置不能干扰），并显示结果。没有什么是永久安装的。

这 --with pyyaml 标志确保YAML解析器依赖关系可用。

远程启动器

cpv-remote-validate 是验证外部插件的推荐方法。它用环境隔离封装任何CPV脚本，以便目标插件的本地文件(pyproject.toml, .mypy.ini过时的模块副本）不能干扰验证。

# Full plugin validation (short alias)
uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml \
    cpv-remote-validate plugin /path/to/plugin

# Save a report to a file
uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml \
    cpv-remote-validate plugin /path/to/plugin -o report.md

# Validate a single skill with strict mode
uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml \
    cpv-remote-validate skill /path/to/skill --strict

# Security scan
uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml \
    cpv-remote-validate security /path/to/plugin

# Show help and all available commands
uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml \
    cpv-remote-validate --help

# From the CPV plugin cache (inside Claude Code):
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/remote_validation.py" plugin /path/to/plugin

提示： 创建shell别名以缩短命令： ``bash alias cpv='uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml cpv-remote-validate' ` 那么，只需： cpv plugin /path/to/plugin 或 cpv skill /path/to/skill --strict`

可用脚本

其中任何一个都可以作为第一个参数传递给 cpv-remote-validate。短别名和完整脚本名称都有效。

选项

这些标志适用于所有验证器：

默认输出仅为路径。 没有 --json 或 --report, validate_security.py 自动将聚合报告保存到 `$CLAUDE_PROJECT_DIR/reports/security/-

.md （或 $TMPDIR/reports/security/... 当 CLAUDE_PROJECT_DIR 未设置，例如在遥控器上 uvx` 调用）和打印 仅 将简洁的摘要（计数表+判决+插件路径+报告路径）发送到stdout。这保证了调用验证器的代理获得一个微小的、可预测的stdout有效负载，该负载永远不会淹没其上下文窗口。

外部扫描仪始终运行。 没有 --no-tirith / --no-trufflehog / --no-semgrep 选择退出标志。如果无法在PATH上解析其源二进制文件或无法从其源URL安装，则每个外部扫描仪都会自动跳过，并显示INFO提示。Set CPV_NO_TIRITH_INSTALL=1 在阻止容器拉取的CI沙箱中禁用tirith的自动安装回退；集 CPV_CISCO_SCAN_TIMEOUT_S= 覆盖非常大的树的600s默认值。看 外部安全扫描器 以上为完整库存。

阅读结果

严重级别

退出代码

用于脚本和CI/CD管道：

______________________________________________________________________

第2部分：克劳德代码插件

适用于Claude Code用户。 只需安装一次CPV，即可在Claude Code中直接获取斜线命令、AI代理和插件管理工具。

安装

有关完整的CLI命令参考，请参阅 官方人类学文档.

# Add the Emasoft marketplace (first time only)
claude plugin marketplace add emasoft-plugins --url https://github.com/Emasoft/emasoft-plugins

# Install CPV (--scope user = available in all your projects, recommended)
claude plugin install claude-plugins-validation@emasoft-plugins --scope user

# OR install for this project only (--scope local, gitignored)
claude plugin install claude-plugins-validation@emasoft-plugins --scope local

# IMPORTANT: Restart Claude Code after installing, or run /reload-plugins

管理插件

# Update to the latest version
claude plugin update claude-plugins-validation@emasoft-plugins --scope user

# Disable without removing
claude plugin disable claude-plugins-validation@emasoft-plugins --scope user

# Re-enable
claude plugin enable claude-plugins-validation@emasoft-plugins --scope user

# Uninstall completely
claude plugin uninstall claude-plugins-validation@emasoft-plugins --scope user

# Uninstall but keep persistent data
claude plugin uninstall claude-plugins-validation@emasoft-plugins --scope user --keep-data

替换 --scope user 随着 --scope local 或 --scope project 取决于您安装它的位置：

发展： claude --plugin-dir ./claude-plugins-validation

AI代理——主界面

当用作Claude Code插件时， 代理是与CPV交互的主要方式每个代理都是一个专门的人工智能助手，它知道要运行哪些脚本，要咨询哪些技能，以及如何指导你完成整个过程。只要告诉克劳德你需要什么，合适的经纪人就会接管。

每个代理在调用时都会显示一个菜单，询问您需要什么，并逐步指导您。您不需要记住命令名称或标志。

关注点分离：插件与市场

CPV治疗 插件 和 市场 作为专用验证器、修复代理和错误索引的两个不同关注点。这避免了厨房水槽修复器的问题，即一个代理试图对单个插件进行推理 plugin.json 以及市场 marketplace.json +同时释放管道。

机械修复与架构迁移。 这 fix-validation 和 fix-marketplace-validation 技能做 每次错误的机械修复 --一个规则，一个修复，最少的用户输入。分开的 migrate-marketplace-architecture 技能（由加载 marketplace-fixer)确实如此 交互式建筑转换 与广泛 AskUserQuestion 提示：它引导您完成将布局a中心辐射市场转换为布局B嵌套单仓库市场的过程，反之亦然，包括发布管道、CI和CHANGELOG重组。

支持的市场布局

CPV验证并支持两种市场布局——两者都是一流的：

完整的布局规范和决策标准： skills/create-plugin/references/marketplace-layouts.md.

脚本验证与语义验证

CPV有两个验证层：

语义验证器总是警告成本，并在运行前要求确认。在大多数情况下，您只需要脚本验证。

条件支柱——通道MCP服务器源代码安全

/cpv-semantic-validation 自动激活 通道源安全 当目标插件的 plugin.json 声明非空 channels 阵列（克劳德代码v2.1.80+研究预览频道）。该支柱读取MCP服务器入口点源代码（Types/JavaScript/Python），并根据 channels-reference.md --没有语法验证器可以执行的检查。

确定性预过滤器(scripts/cpv_channel_source_predicate.py)限制了LLM的阅读，并使不附带频道的插件的支柱完全短路——零opus令牌花费。看 skills/semantic-validation-skill/references/channel-source-security.md 对于四个规则（关键：无发件人门控，关键：无门控的权限中继能力，主要：仅限聊天ID门控，通过：完全门控）。

斜杠命令

22个命令——13个直接运行脚本（零AI令牌），7个生成代理，2个是专门的实用程序脚本。

脚本命令（免费——无AI标记）

代理命令（交互式——使用AI令牌）

专用实用程序命令

______________________________________________________________________

对于开发者

Project Overview

Validation Scripts

始终通过启动器调用验证器。 直接调用来自 插件缓存被拒绝 check_remote_execution_guard(). 使用 python "${CLAUDE_PLUGIN_ROOT}/scripts/remote_validation.py" . 看 规范启动器调用 在......下面 或 python "${CLAUDE_PLUGIN_ROOT}/scripts/remote_validation.py" --help 为了 完整的别名表。

Management Scripts

Creation and Utility Scripts

______________________________________________________________________

需求

必需

CPV用途 uv 运行脚本(uv run)，安装Python linters(ruff, mypy)当在本地找不到时(uvx)，并管理虚拟环境。Python依赖关系，如 pyyaml 自动安装。

可选工具（增强棉绒）

CPV在中验证脚本 6种语言。对于每种语言，它首先尝试本地安装，然后 uvx/npx。如果没有找到过梁，CPV会报告缺失的内容并跳过该检查。

其他可选工具：

任何验证都不需要API密钥、帐户或云服务。

故障排除

许可证

MIT许可证——请参阅许可证文件。

作者

易玛软件（713559+Emasoft@users.noreply.github.com)