# https://github.com/Emasoft/claude-plugins-validation 项目说明书

生成时间：2026-07-28 19:56:36 UTC

## 目录

- [Overview, Installation & Two Usage Modes](#page-1)
- [Repository Structure & Component Map](#page-2)
- [Pipeline & CLI Architecture](#page-3)
- [Validation Engines (25 validate_*.py Scripts, 190+ Rules)](#page-4)
- [Security Scanning & Skillaudit (FP-handling Pipeline)](#page-5)
- [AI Agents — Routing, Diagnose, Fix, Devitalize, Harden](#page-6)
- [Skill Catalog & The Skills Menu](#page-7)
- [Canonical Pipeline, publish.py & CI/CD](#page-8)
- [Batch, Fleet & Parallel Operations](#page-9)
- [Known False-Positives, Failure Modes & Community Bugs](#page-10)
- [Standardize, Migrate, Cache & Plugin Lifecycle](#page-11)
- [Configuration, Rules, Extensibility & Diagnostics](#page-12)

<a id='page-1'></a>

## Overview, Installation & Two Usage Modes

### 相关页面

相关主题：[Repository Structure & Component Map](#page-2), [AI Agents — Routing, Diagnose, Fix, Devitalize, Harden](#page-6)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/README.md)
- [CHANGELOG.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/CHANGELOG.md)
- [pyproject.toml](https://github.com/Emasoft/claude-plugins-validation/blob/main/pyproject.toml)
- [.claude-plugin/plugin.json](https://github.com/Emasoft/claude-plugins-validation/blob/main/.claude-plugin/plugin.json)
- [scripts/cpv-remote-validate](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv-remote-validate)
- [scripts/publish.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/publish.py)
- [scripts/cpv_validation_common.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_validation_common.py)
</details>

# Overview, Installation & Two Usage Modes

## 项目概述

Claude Plugins Validation（简称 CPV）是一个用于校验 Claude Code 插件合规性的元工具。它会对待发布的插件目录进行多维度检查，包括 `.claude-plugin/plugin.json` 清单完整性、技能 frontmatter 字段、MCP 服务声明、依赖脚本以及潜在的提示词注入风险（skillaudit 维度）。

CPV 既可以作为 Claude Code 插件加载供 AI 助手调用，也可以作为独立的 CLI 工具在 CI 流水线中执行非交互式校验。这种"双重身份"是本项目的核心设计：同一套校验逻辑在两种部署形态下复用，避免开发者在本地与远端看到不同的检测结论。

最新版本 `v3.23.1` 在 orchestrator 中修复了进度标记从调度线程而非工作线程发出的问题，确保在 CI 长时运行场景下日志可观测。 资料来源：[CHANGELOG.md:5-7]()

## 安装方式

CPV 的安装路径由其双重使用模式决定，因此 README 与 `pyproject.toml` 同时描述了 Python 包安装与插件目录安装两种途径。

| 安装方式 | 适用场景 | 关键产物 |
| --- | --- | --- |
| `pip install`（或 `uv tool install`） | CI/CD、远程校验 | `cpv-remote-validate` 可执行命令 |
| 克隆到 `~/.claude/plugins/` | Claude Code 交互式会话 | `.claude-plugin/plugin.json` + skills/commands |

Python 包入口在 `pyproject.toml` 中声明，指向 `scripts/` 下的多个脚本模块；插件清单 `.claude-plugin/plugin.json` 则描述了被 Claude Code 加载时的命令与技能元数据。 资料来源：[pyproject.toml:1-40]() 资料来源：[.claude-plugin/plugin.json:1-20]()

## 两种使用模式

### 模式 A：Claude Code 插件模式

当 CPV 仓库被放置到 `~/.claude/plugins/` 下后，Claude Code 会读取 `.claude-plugin/plugin.json` 并将 CPV 注册为一个可调用的插件。AI 助手可以在对话中触发其内部命令与技能（如 `ci-preflight`、`/cpv:validate` 等），对当前工作区的插件树进行交互式诊断。该模式的优势在于：校验结果可以由 AI 助手直接解读，并辅助用户修复 frontmatter 错误或 MCP 声明问题。 资料来源：[README.md:1-50]()

### 模式 B：独立 CLI 验证模式

通过 `cpv-remote-validate plugin <path> --strict` 命令直接对本地或远程拉取的插件目录执行校验。该模式专为非交互场景设计，常被 `scripts/publish.py` 的 canonical pipeline 调用作为发布门禁。`cpv_validation_common.py` 提供了 CLI 模式下的共享数据常量与辅助函数。 资料来源：[scripts/cpv-remote-validate:1-30]() 资料来源：[scripts/cpv_validation_common.py:1-30]()

```mermaid
flowchart LR
    A[插件源码] --> B{使用模式}
    B -- 插件模式 --> C[Claude Code 会话]
    B -- CLI 模式 --> D[cpv-remote-validate]
    C --> E[AI 解读 + 修复建议]
    D --> F[CI 流水线 / publish.py]
    E --> G[校验报告]
    F --> G
```

## 模式差异与社区关注点

两种模式共享底层检测器，但触发时机与输出形态不同。CLI 模式因被 `publish.py` 的 `run()` 包装且默认 `timeout=300`，在大型测试套件场景下可能无法满足时长要求（社区 issue #179）；插件模式则常因 AI 误判 PROSE 中的反注入守卫代码而触发 skillaudit 误报（issue #170、#177、#178）。在 `--strict` 模式下，校验范围还会延伸至非可发布的 tracked 内容，需要通过 `.cpvignore` 或文件白名单收敛（issue #176）。 资料来源：[scripts/publish.py:1-40]()

## 小结

- 安装：pip 安装 CLI，克隆目录安装插件，两种产物互不冲突。
- 模式 A：Claude Code 插件，适合开发期交互式诊断。
- 模式 B：CLI 校验，适合 CI 与发布门禁，需关注超时与检测范围配置。

---

<a id='page-2'></a>

## Repository Structure & Component Map

### 相关页面

相关主题：[Overview, Installation & Two Usage Modes](#page-1), [Pipeline & CLI Architecture](#page-3), [AI Agents — Routing, Diagnose, Fix, Devitalize, Harden](#page-6)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- 资料来源： [agents/cpv-agent.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/agents/cpv-agent.md)
- 资料来源： [commands/cpv-main-menu.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/commands/cpv-main-menu.md)
- 资料来源： [scripts/cli.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cli.py)
- 资料来源： [scripts/manage_plugin.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/manage_plugin.py)
</details>

>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agents/cpv-agent.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/agents/cpv-agent.md)
- [commands/cpv-main-menu.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/commands/cpv-main-menu.md)
- [commands/cpv-remote-validate.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/commands/cpv-remote-validate.md)
- [scripts/cli.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cli.py)
- [scripts/manage_plugin.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/manage_plugin.py)
- [scripts/publish.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/publish.py)
- [scripts/cpv_validation_common.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_validation_common.py)
- [scripts/skillaudit.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/skillaudit.py)
- [.github/workflows/release.yml](https://github.com/Emasoft/claude-plugins-validation/blob/main/.github/workflows/release.yml)
- [pyproject.toml](https://github.com/Emasoft/claude-plugins-validation/blob/main/pyproject.toml)
</details>

# Repository Structure & Component Map

## 1. 仓库定位与顶层布局

`claude-plugins-validation`（CPV）是一个 Claude Code 插件，其自身也是一种「要被打包、发布、CI 校验」的插件。因此仓库在文件层面同时扮演两个角色：① 面向终端用户的「校验工具」；② 面向其他插件作者的「参考实现」。整个仓库以 Claude 插件的标准约定（`commands/`、`agents/`、`scripts/`）为核心，辅以 Python 打包与 CI 资源。

顶层目录大致如下：

- `agents/` — Claude agent 定义，决定哪些任务由代理而非 CLI 直接执行。`cpv-agent.md` 描述了入口 agent 的角色与工具使用范围。
- `commands/` — 暴露给用户的斜杠命令；`cpv-main-menu.md` 提供主菜单式 UX，`cpv-remote-validate.md` 则是对远端产物做严格校验的入口。
- `scripts/` — 真正干活的 Python 库与 CLI；`cli.py` 提供注册式子命令，`manage_plugin.py` 负责本地插件装配，`publish.py` 是上游「canonical pipeline」模板化的发布脚本，`cpv_validation_common.py` 给出跨命令共享的校验原语，`skillaudit.py` 是一个独立的子审阅器。
- `.github/workflows/` — GitHub Actions，其中 `release.yml` 把「build → validate → publish」三步串成 release。
- `pyproject.toml` — 声明 Python 端依赖与入口点。

资料来源：[pyproject.toml:1-40]()，[.github/workflows/release.yml:1-60]()。

## 2. 三大组件图：CLI、Commands、Agent

CPV 的运行时被刻意拆成三层，使校验既能由人类斜杠命令触发，也能由 Claude agent 直接驱动。

```mermaid
flowchart LR
    A[commands/cpv-main-menu.md] --> B[scripts/cli.py]
    A2[commands/cpv-remote-validate.md] --> B
    C[agents/cpv-agent.md] --> B
    B --> D[scripts/manage_plugin.py]
    B --> E[scripts/publish.py]
    B --> F[scripts/cpv_validation_common.py]
    E --> F
    G[scripts/skillaudit.py] --> F
    H[GitHub Actions release.yml] --> B
    H --> E
```

- **CLI 层** (`scripts/cli.py`)：注册式分发器，把 `--strict`、`--gate` 等开关路由到具体 validator。社区 #179 指出，被 `publish.py` 调用的 `run()` 包装器把 `timeout=300` 硬编码到了所有子命令，对大型 pytest 套件明显不够。
- **斜杠命令层** (`commands/`)：把 CLI 重新包装成 Claude Code 可识别的自然语言入口；`cpv-main-menu` 负责导航，`cpv-remote-validate` 负责严格模式。
- **Agent 层** (`agents/cpv-agent.md`)：当 Claude 在 CI preflight 中需要「自带判定」时，自动选择校验策略，并解释 MAJOR/NIT/NONE 三档严重度。

资料来源：[scripts/cli.py:1-80]()，[commands/cpv-main-menu.md:1-30]()，[commands/cpv-remote-validate.md:1-30]()，[agents/cpv-agent.md:1-40]()。

## 3. 共享原语与子审阅器

`cpv_validation_common.py` 是所有 validator 的「底座」：它定义 frontmatter 解析、文件作用域过滤、评分分级、以及被 bandit / ruff / pytest 共同依赖的常量。社区 #172 指出，这个文件里的某些数据常量会被 bandit B108 命中，并因此让所有 `publish.py --gate` 走不通，说明它确实被多个 Python 脚本共享。

`skillaudit.py` 是 CPV 内置的反注入审计器，关注文件系统类与 agent 操作类两类反模式。它的输出遵循 `skillaudit:<分类> <规则>` 形式，例如 `skillaudit:filesystem FS_WRITE`（#177）与 `skillaudit:agent_manipulation MCP_SCHEMA_POISON`（#178）。该子审阅器与 `cpv-remote-validate` 共享同一份 `NONE/NIT/MAJOR` 严重度语义。

资料来源：[scripts/cpv_validation_common.py:1-60]()，[scripts/skillaudit.py:1-80]()。

## 4. Canonical Pipeline 与发布闭环

「Canonical pipeline」是 CPV 把它对 *自己* 用的发布流程模板化后，开放给下游插件复用。它本身由 `scripts/publish.py` 实现，并由 `.github/workflows/release.yml` 在每次 tag 时触发。流程是：build → validate → publish。

但社区已经记录该闭环的几处真实缺陷：

- #180：validate 阶段在 `ubuntu-latest` 上挂死约 25–30 分钟，最终被 runner 自身超时杀；它发生在 build 成功之后（4s），因此与冷编译无关，release 会带着缺失资产发出去。
- #175：`publish.py` 升级时会被整体重生成（3,492 行），旧的「Rust + shell」门禁被静默丢弃，意味着插件作者若用 Rust 组件，没有任何 gate 拦住它。
- #176：`--strict` 范围过宽，把 `project-memory/`、测试 fixture、甚至 gitignored 文件都纳入了校验，导致 CI 永远红。
- #179：通用 `run(timeout=300)` 让 pytest gate 事实上不可满足。

因此读懂仓库结构的同时，也必须理解 *canonical pipeline 是模板*：它把 CPV 暴露的 BP 同等地应用到下游插件，而这些 issue 集中在「别让模板反过来咬自己」。

资料来源：[scripts/publish.py:1-80]()，[.github/workflows/release.yml:1-60]()。

---

<a id='page-3'></a>

## Pipeline & CLI Architecture

### 相关页面

相关主题：[Repository Structure & Component Map](#page-2), [Validation Engines (25 validate_*.py Scripts, 190+ Rules)](#page-4), [Batch, Fleet & Parallel Operations](#page-9)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [scripts/remote_validation.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/remote_validation.py)
- [scripts/validate_plugin.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_plugin.py)
- [scripts/cpv_validation_common.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_validation_common.py)
- [scripts/cpv_batch_orchestrator.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_batch_orchestrator.py)
- [scripts/cpv_batch_aggregator.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_batch_aggregator.py)
- [scripts/cpv_sarif_writer.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_sarif_writer.py)
- [scripts/publish.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/publish.py)
</details>

# Pipeline & CLI Architecture

## 概述与定位

Claude Plugins Validation (CPV) 是一套以 Python CLI 为核心、面向 Claude Code 插件的验证流水线。其"Pipeline & CLI Architecture"由两层组成：用户可见的命令行入口（`cpv-remote-validate` / `cpv batch`），以及背后被消费方模板化的"canonical pipeline"（即 `scripts/publish.py`）。CLI 负责把单插件或批插件树送入校验、`skillaudit`、SARIF 输出等阶段；canonical pipeline 则把这些阶段编排进 GitHub Actions 的 build / validate / publish 步骤，供所有下游插件统一复用。

资料来源：[scripts/remote_validation.py:1-40]() [scripts/publish.py:1-80]()

## CLI 入口与子命令

CLI 的对外形态是一个 argparse 风格的入口脚本，它把"远程单插件校验"和"批处理编排"分成独立子命令：

- `cpv-remote-validate plugin <path> [--strict]`：针对单个插件目录做端到端校验；`--strict` 会提升发现等级（CRITICAL / MAJOR / NIT）并触发 `ci-preflight` 评分。
- `cpv batch`：进入批处理编排模式，由 `cpv_batch_orchestrator.py` 负责分派、`cpv_batch_aggregator.py` 负责汇总。
- `cpv remote-validate`：CI 中调用同一组核心校验逻辑的远程包装形态。

通用共享（参数解析、错误码、SARIF 写入路径协商、日志格式）集中在 `cpv_validation_common.py`，所有子命令都从这里导入，以保证 CLI 与批处理两条路径行为一致。

资料来源：[scripts/remote_validation.py:41-120]() [scripts/cpv_validation_common.py:1-60]()

## 流水线阶段（canonical pipeline）

canonical pipeline 在 `scripts/publish.py` 中被固化为多阶段流水线，典型顺序如下：

| 阶段 | 职责 | 关键调用 | 备注 |
|------|------|----------|------|
| build | 编译 CPV 自身、生成 bundled 校验器入口 | `cpv` 自举 | 冷启动 ~4s（#180 实测） |
| validate | 跑 `cpv-remote-validate plugin . --strict` 与 skillaudit | `cpv-remote-validate` | 触发 `FS_WRITE` / `MCP_SCHEMA_POISON` 等检测器 |
| gate | bandit 等静态扫描，必须通过才能进入 publish | `run(cmd)` | 共享同一个 `timeout=300` |
| publish | 将通过 gate 的产物发到市场 / GitHub Release | gh release | 依赖前序阶段全部成功 |

每一阶段都通过一个共享的 `run(cmd)` 帮助函数包装 subprocess 调用；该函数硬编码 `timeout=300`（#179 中已明确指出这与"真实 pytest 套件"不匹配），所有阶段继承同一个超时阈值。

资料来源：[scripts/publish.py:1-120]() [scripts/publish.py:run():120-180]()

## 批处理编排与 SARIF 汇聚

`cpv_batch_orchestrator.py` 与 `cpv_batch_aggregator.py` 共同构成"多插件并行校验"的子流水线：

- **orchestrator**：把目标列表切分成 worker，分发到子进程 / 线程；v3.23.1 的修复明确指出"进度标记必须由 dispatcher 而不是 worker 线程发出"，说明早期实现存在进度信号被埋在子线程、导致 CI 卡顿的隐患。
- **aggregator**：把每个 worker 的 JSON 结果汇聚成统一报告，并由 `cpv_sarif_writer.py` 转写成 SARIF 2.1.0，供 GitHub Code Scanning 渲染。

批处理与单插件模式共用同一组 detector；aggregator 还会做一次等级去重与跨插件交叉抑制，避免重复告警。这一层与 canonical pipeline 解耦，因此 `--strict` 与 batch 模式可独立开关。

资料来源：[scripts/cpv_batch_orchestrator.py:1-80]() [scripts/cpv_batch_aggregator.py:1-80]() [scripts/cpv_sarif_writer.py:1-60]()

## 已知架构痛点与权衡

社区已暴露数条与 Pipeline & CLI 紧密相关的痛点：

- **validate 阶段卡死 25–30 分钟**（#180）：build 已 4s 成功，但 validate 阶段被 `timeout` 上限杀死；根因不是冷启动，而是 canonical pipeline 对 pytest / bandit 的超时模型假设过紧。
- **`run()` 硬编码 300 秒**（#179）：任何走 `run()` 的子命令都共享同一超时，pytest 调用点无法独立放大——这是"通用 helper 误吞语义"的典型反模式。
- **`--strict` 范围过宽**（#176）：会扫到 `project-memory/`、测试夹具以及 `.gitignore` 中的非发布文件，说明 strict 模式与"shippable surface"的概念没有在管线中显式区分。
- **regen 静默丢步**（#175）：从语言无关模板重新生成 `scripts/publish.py` 时，Rust / shell 的门控步骤会被整体剥离，说明模板与插件语言检测没有强耦合。
- **vendoring 自伤**（#172）：`cpv_validation_common.py` 自身数据常量触发 bandit B108，导致所有把它 vendor 进自己仓库的插件在自身 `publish.py --gate` 里失败——这是 canonical pipeline"既当裁判又当运动员"的结构性冲突。

资料来源：[scripts/publish.py:run():120-180]() [scripts/remote_validation.py:strict-scope:80-160]() [scripts/cpv_validation_common.py:1-60]()

---

延伸阅读：配合 *Detector Catalog* 与 *SARIF Output Schema* 两页，可把"阶段 → 检测器 → 报告格式"这条主线完整串起来。

---

<a id='page-4'></a>

## Validation Engines (25 validate_*.py Scripts, 190+ Rules)

### 相关页面

相关主题：[Pipeline & CLI Architecture](#page-3), [Security Scanning & Skillaudit (FP-handling Pipeline)](#page-5), [Known False-Positives, Failure Modes & Community Bugs](#page-10)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- 资料来源： [scripts/validate_plugin.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_plugin.py)
- 资料来源： [scripts/validate_skill.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_skill.py)
- 资料来源： [scripts/validate_hook.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_hook.py)
- 资料来源： [scripts/validate_security.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_security.py)
- 资料来源： [scripts/validate_marketplace.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_marketplace.py)
- 资料来源： [scripts/validate_local_scope.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_local_scope.py)
</details>

summary>

以下源码文件用于生成本页说明：

- [scripts/validate_plugin.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_plugin.py)
- [scripts/validate_skill.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_skill.py)
- [scripts/validate_hook.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_hook.py)
- [scripts/validate_security.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_security.py)
- [scripts/validate_marketplace.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_marketplace.py)
- [scripts/validate_local_scope.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_local_scope.py)
- [scripts/validate_frontmatter.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_frontmatter.py)
- [scripts/skillaudit.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/skillaudit.py)
- [scripts/cpv_validation_common.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_validation_common.py)
- [scripts/publish.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/publish.py)
</details>

# Validation Engines (25 validate_*.py Scripts, 190+ Rules)

## 概述与设计目标

Validation Engines 是 Claude Plugins Validation (CPV) 项目的核心检测层，由 **25 个独立 `validate_*.py` 脚本**与 **190+ 条规则**组成，覆盖 Claude Code 插件在结构、Skill/MCP/Hook 契约、安全模型、市场分发元数据等所有可机校验维度。`cpv-remote-validate plugin . --strict` 是其主入口，CI 发布流水线 `scripts/publish.py --gate` 复用同一规则集作为发布门槛。Engine 在设计上遵循"单一职责 + 共享 registry"原则：每个脚本只负责一类资源（plugin、skill、hook、marketplace…），严重等级、退出码、报告格式则由 `cpv_validation_common.py` 统一管理。  
资料来源：[scripts/validate_plugin.py]()、[scripts/cpv_validation_common.py]()

## 架构与执行流水线

25 个 `validate_*.py` 共享 `cpv_validation_common.py` 中的规则注册器（registry）、严重等级（NIT / MAJOR / CRITICAL）与退出码策略。每个脚本遵循三段式：发现（discover）→ 规则评估（evaluate）→ 报告汇聚（report / aggregate）。`validate_plugin.py` 作为顶层 orchestrator，决定调用哪些子 validator；`skillaudit` 作为横切安全审计模块，被 `validate_security.py` 与 `--strict` 集成。

```mermaid
flowchart TD
    A[cpv-remote-validate plugin . --strict] --> B[validate_plugin.py<br/>orchestrator]
    B --> C[validate_skill.py]
    B --> D[validate_hook.py]
    B --> E[validate_marketplace.py]
    B --> F[validate_local_scope.py]
    B --> G[validate_frontmatter.py]
    B --> H[validate_security.py]
    H --> I[skillaudit.py<br/>FS_WRITE / MCP_SCHEMA_POISON / injection]
    C --> J[cpv_validation_common.py<br/>registry + severity + exit code]
    D --> J
    E --> J
    F --> J
    G --> J
    H --> J
    J --> K{exit code 0/1/2}
    K -->|publish gate| L[scripts/publish.py]
```

资料来源：[scripts/validate_plugin.py]()、[scripts/validate_security.py]()、[scripts/skillaudit.py]()

## 规则分类与典型条目

`190+ Rules` 按资源域归类：

- **结构与清单**：`validate_plugin.py` / `validate_marketplace.py` 校验 `marketplace.json`、`plugin.json` 必备字段、版本与依赖一致性，对应 #175 提出的"按语言门控 Rust + shell"诉求。
- **Skill / Hook 契约**：`validate_skill.py` 与 `validate_hook.py` 校验 frontmatter 已知字段、事件名、命令路径；`validate_frontmatter.py` 维护已知字段白名单，#173 报告 Claude Code v2.1.218 新增的 `background` 字段尚未识别。
- **作用域与边界**：`validate_local_scope.py` 控制 `--strict` 仅扫描 shippable 表面，#176 指控当前实现误扫 `project-memory`、测试 fixture 与 `.gitignore` 文件。
- **安全审计**：`validate_security.py` + `skillaudit` 覆盖 4 大类检测器（agent_manipulation、filesystem、injection、schema_poison），是 MAJOR 的主要来源；#177、#178 即属此类误报。
- **通用数据常量**：`cpv_validation_common.py` 内置路径/正则常量，#172 指出其触发 bandit B108，使所有 vendoring 插件的 `publish.py --gate` 失败。

资料来源：[scripts/validate_skill.py]()、[scripts/validate_local_scope.py]()、[scripts/skillaudit.py]()、[scripts/validate_frontmatter.py]()

## 严重等级、超时与社区反馈

引擎统一返回三档严重级：NIT（不阻塞）、MAJOR（`--strict` 阻塞）、CRITICAL（任何模式阻塞）。`scripts/publish.py` 的 `run()` helper 对所有子命令硬编码 `timeout=300`，#179 指控该值不足以运行真实 pytest 套件，#180 进一步报告 CPV validate 在 `ubuntu-latest` 上挂死 25–30 分钟后被自动 kill，导致带空资产的 release 漏出。修复方向集中在三方面：按域拆分超时（#179/#180）、放宽 skillaudit 对反注入 guardrail 的识别（#170）、`--strict` 显式排除非 shippable 路径（#176）。

资料来源：[scripts/publish.py]()、[scripts/validate_security.py]()

---

<a id='page-5'></a>

## Security Scanning & Skillaudit (FP-handling Pipeline)

### 相关页面

相关主题：[Validation Engines (25 validate_*.py Scripts, 190+ Rules)](#page-4), [Known False-Positives, Failure Modes & Community Bugs](#page-10)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [scripts/cpv_skillaudit_native.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_skillaudit_native.py)
- [scripts/_skillaudit_python_context.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/_skillaudit_python_context.py)
- [scripts/_skillaudit_shell_context.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/_skillaudit_shell_context.py)
- [scripts/_skillaudit_markdown_context.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/_skillaudit_markdown_context.py)
- [scripts/validate_security.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_security.py)
- [scripts/cpv_snyk_agent_scanner.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_snyk_agent_scanner.py)
</details>

# Security Scanning & Skillaudit (FP-handling Pipeline)

## 概述与职责

`skillaudit` 子系统是 CPV（Claude Plugins Validation）安全扫描层的核心，专注于审查插件中可能改变 Agent 行为的代码与文档片段——也就是「会被 Agent 作为指令加载」的内容。其职责覆盖两类风险：

1. **依赖型漏洞**：通过 [scripts/cpv_snyk_agent_scanner.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_snyk_agent_scanner.py) 调用 Snyk 扫描第三方依赖中的已知 CVE。
2. **逻辑型风险（agent-context writers）**：通过 `skillaudit` 原生检测器扫描插件自身代码，识别会向 agent 上下文写入可疑内容的能力组件——参见 Issue [#174](https://github.com/Emasoft/claude-plugins-validation/issues/174) 对该类风险的定义。

整套扫描被 [scripts/validate_security.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_security.py) 作为顶层编排脚本纳入 `cpv-remote-validate` 流程，并支持 `--strict` 模式以提升某些 NIT 等级（参见 Issue [#170](https://github.com/Emasoft/claude-plugins-validation/issues/170)）。

资料来源：[scripts/validate_security.py:1-1]()

## 检测器与上下文分类

原生入口 [scripts/cpv_skillaudit_native.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_skillaudit_native.py) 根据文件类型路由到三个上下文提取器，每个提取器负责判断「该行是否真的在被执行/注入」，从而为后续 FP 降级提供依据：

| 文件类型 | 上下文提取器 | 提取的关键信号 |
|---|---|---|
| Python | [_skillaudit_python_context.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/_skillaudit_python_context.py) | 是否位于 AST 函数体/类体内、是否在 docstring/注释中、是否命中字符串字面量 |
| Shell | [_skillaudit_shell_context.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/_skillaudit_shell_context.py) | 注释行（以 `#` 开头）标记为 PROSE；heredoc 内部按纯文本处理 |
| Markdown | [_skillaudit_markdown_context.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/_skillaudit_markdown_context.py) | frontmatter 区段、代码围栏语言、是否处于引用/链接中 |

上下文提取器输出的「行级语义标签」（`CODE` / `PROSE` / `FRONTMATTER` / `COMMENT` 等）是 FP 降级的核心输入。Issue [#177](https://github.com/Emasoft/claude-plugins-validation/issues/177) 中 `FS_WRITE` 在 shell 注释里被误报为 MAJOR，正是因为缺少对 PROSE 行的语义降级。

资料来源：[scripts/cpv_skillaudit_native.py:1-1](), [scripts/_skillaudit_shell_context.py:1-1]()

## FP-handling 流水线

下面是检测器命中后到最终入库的流水线：

```mermaid
flowchart LR
    A[扫描文件] --> B{按扩展名路由}
    B -->|*.py| C[Python 上下文]
    B -->|*.sh| D[Shell 上下文]
    B -->|*.md| E[Markdown 上下文]
    C --> F[检测器匹配<br/>如 FS_WRITE / MCP_SCHEMA_POISON]
    D --> F
    E --> F
    F --> G{语义标签 = PROSE?}
    G -->|是| H[降级为 NIT<br/>demoted, needs review]
    G -->|否| I{是 --strict?}
    I -->|是| J[保留原等级]
    I -->|否| K[按默认阈值过滤]
    H --> L[写入报告]
    J --> L
    K --> L
```

关键节点说明：

- **PROSE 降级**：Issue [#177](https://github.com/Emasoft/claude-plugins-validation/issues/177) 中 bash 注释内提到 `~/.zshrc` 即被识别为 PROSE 行，命中 `skillaudit:filesystem FS_WRITE` 后降级为 NIT（`demoted, needs review`）。
- **frontmatter 例外**：Issue [#178](https://github.com/Emasoft/claude-plugins-validation/issues/178) 表明 `MCP_SCHEMA_POISON` 在 wikimem memory-note 的 `description:` 字段同样走 PROSE 路径；Issue [#173](https://github.com/Emasoft/claude-plugins-validation/issues/173) 中 CC v2.1.218 的合法 `background` 字段若被识别为 FRONTMATTER 而非未定义字段，亦可避免误报。
- **能力 vs 实时分离**：Issue [#174](https://github.com/Emasoft/claude-plugins-validation/issues/174) 要求「capability vs live」分别打分，扫描器需区分「具有写入能力」与「运行时实际写入」两类信号。

资料来源：[scripts/cpv_skillaudit_native.py:1-1](), [scripts/_skillaudit_markdown_context.py:1-1]()

## 已知限制与社区共识

根据近期 issue 追踪，该 FP-handling 流水线仍存在以下已公开的限制：

- **被自身 gate 反伤**：[scripts/cpv_validation_common.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_validation_common.py)（不在本页直接列出，但与 `validate_security.py` 同源）会触发 bandit B108，阻断每个 vendoring 该文件的插件的 `--gate`（Issue [#172](https://github.com/Emasoft/claude-plugins-validation/issues/172)）。
- **扫描范围过宽**：Issue [#176](https://github.com/Emasoft/claude-plugins-validation/issues/176) 指出 `--strict` 模式会把 project-memory、test fixtures、gitignored 内容一并送入扫描器，导致大量与可分发插件无关的命中。
- **回溯破坏绿色发布**：Issue [#170](https://github.com/Emasoft/claude-plugins-validation/issues/170) 报告了 4 个检测器把「防御性反注入护栏」反判为注入，NIT 等级在 `--strict` 下会卡住历史已通过的发布。
- **超时门不可达**：Issue [#179](https://github.com/Emasoft/claude-plugins-validation/issues/179) 显示 `publish.py` 的 `run()` 助手硬编码 `timeout=300`，真实测试套件无法在 300 秒内完成——这是上游流水线问题，但与 `validate_security.py` 在同一条 gate 链路上。

运维建议：在 CI 中启用 `skillaudit` 前，应先用 `--strict` 在本地跑一遍 `cpv-remote-validate plugin .`，对被降级为 NIT 的 PROSE 命中逐条确认是否为真实的写入意图。

资料来源：[scripts/validate_security.py:1-1](), [scripts/cpv_snyk_agent_scanner.py:1-1]()

---

<a id='page-6'></a>

## AI Agents — Routing, Diagnose, Fix, Devitalize, Harden

### 相关页面

相关主题：[Skill Catalog & The Skills Menu](#page-7), [Batch, Fleet & Parallel Operations](#page-9)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agents/cpv-agent.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/agents/cpv-agent.md)
- [agents/cpv-plugin-validator-agent.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/agents/cpv-plugin-validator-agent.md)
- [agents/cpv-plugin-fixer-agent.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/agents/cpv-plugin-fixer-agent.md)
- [agents/cpv-plugin-devitalizer-agent.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/agents/cpv-plugin-devitalizer-agent.md)
- [agents/cpv-plugin-leaks-preventer-agent.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/agents/cpv-plugin-leaks-preventer-agent.md)
- [agents/cpv-plugin-diagnoser-agent.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/agents/cpv-plugin-diagnoser-agent.md)
</details>

# AI Agents — Routing、Diagnose、Fix、Devitalize、Harden

## 概述与角色分工

CPV（Claude Plugins Validation）通过一组分工明确的 AI Agent 协作完成插件生命周期的关键环节。`cpv-agent` 作为总入口与路由层（router），根据用户调用的子命令（例如 `cpv-validate`、`cpv-fix`、`cpv-remote-validate`）将工作分派给对应的专业 Agent。这些专业 Agent 之间通过解耦的职责（诊断 / 修复 / 失效化 / 加固）形成流水线，使得每个阶段都能被独立运行或组合运行。资料来源：[agents/cpv-agent.md]()

| Agent | 职责 | 触发场景 |
|---|---|---|
| `cpv-plugin-validator-agent` | 静态与策略层面的校验 | 用户执行 `validate` 子命令 |
| `cpv-plugin-diagnoser-agent` | 在校验失败后定位根因 | 校验产生 NIT/Major 报告时 |
| `cpv-plugin-fixer-agent` | 自动修复可处理的诊断问题 | `fix` 子命令 |
| `cpv-plugin-devitalizer-agent` | 失效化危险或被弃用的组件 | `devitalize` 子命令 |
| `cpv-plugin-leaks-preventer-agent` | 加固抗注入与凭据泄露防护 | `harden` 子命令 |

## 路由与编排（Routing）

`cpv-agent` 是整个 Agent 体系的入口和分发器。最新发布 v3.23.1 中专门标注：「`orchestrator`: Emit progress markers from the dispatcher, not worker threads」，说明路由层的职责已经明确：分发器（dispatcher）负责把任务投递给 worker，并把进度标记（progress marker）打印回主线程，而 worker 线程不再直接对外暴露进度事件。这一改动避免了多个 worker 并行执行时进度信号互相覆盖的问题。资料来源：[agents/cpv-agent.md]()  

在实际使用中，路由层处理两类主要信号：用户通过命令行传入的子命令，以及验证阶段产出的 `cpv_validation` 报告对象。当报告对象的严重级别超过预定义阈值时，路由层不会再次执行 `validator`，而是直接分派 `diagnoser` 进行根因分析；如果用户在同一会话中显式调用 `--apply-fix`，路由层则把上下文传给 `fixer` Agent。资料来源：[agents/cpv-agent.md:1-120]()

## 诊断与修复（Diagnose → Fix）

诊断与修复是紧密耦合的两阶段：`diagnoser` 读取 `validator` 产出的结构化报告，使用一套独立于检测器的规则来识别「同一根因引发的多条命中」。例如 issue #177 和 #178 中描述的 `skillaudit:filesystem FS_WRITE` 与 `skillaudit:agent_manipulation MCP_SCHEMA_POISON` 误报，都属于 PROSE（说明文本）触发的同一类问题；`diagnoser` 应识别这种「词法相似但语义无关」的模式，避免它们被分别提交给 `fixer` 重复处理。资料来源：[agents/cpv-plugin-diagnoser-agent.md:1-80]()  

`fixer` Agent 接受 `diagnoser` 输出的「可操作子集」，每一项都附带修复策略（如「移除文件写入指令」「将 `description:` 字段重写为不含命令语法」）。它的执行边界是：只对 `MAJOR` 且修复成本低于风险扩散成本的问题自动应用补丁；其余条目生成候选补丁并交回用户审阅。这一设计呼应 issue #176 中 `--strict` 模式误把非交付文件纳入校验范围的问题——`fixer` 在应用前会校验目标文件确实属于发布产物树。资料来源：[agents/cpv-plugin-fixer-agent.md:1-100]()

## 失效化与加固（Devitalize → Harden）

失效化（devitalize）与加固（harden）是相互独立的"防御层"。`cpv-plugin-devitalizer-agent` 的目标是：识别仍以可执行形式（如保留的脚本、可被外部触发的 hook）存在于仓库中、但已经不应再被激活的组件，并把它们的入口点替换为「no-op stub + 弃用日志」。常见触发来自 issue #175 中所述的场景：当 canonical pipeline 重生成 `publish.py` 后，原本应由语言无关模板承担的工作被静默丢弃，导致遗留在旧产物路径下的旧脚本仍可被 CI 调用。资料来源：[agents/cpv-plugin-devitalizer-agent.md:1-60]()  

`cpv-plugin-leaks-preventer-agent`（亦即 `harden`）关注的是凭据、令牌与抗注入加固。它的工作集合与 issue #170 描述的「防御性反注入护栏被自身告警为注入」密切相关：`harden` Agent 通过白名单机制保护合规的反注入模板不被 `skillaudit` 误报命中。它同时承担 issue #172 的工作：检查 `cpv_validation_common.py` 等被多个插件 vendored 的常量文件，确保其中声明的硬编码值不会触发 bandit 等下游安全门禁。资料来源：[agents/cpv-plugin-leaks-preventer-agent.md:1-90]()  

## 端到端工作流

```mermaid
flowchart LR
  U[用户/CLI] --> R[cpv-agent<br/>路由层]
  R --> V[validator-agent]
  V -- 报告 --> D[diagnoser-agent]
  D -- 可操作项 --> F[fixer-agent]
  D -- 不可修复 --> X[devitalizer-agent]
  R -- 加固请求 --> H[leaks-preventer<br/>harden-agent]
  V -. 严重级别 .-> R
```

需要注意的是，`harden` 步骤在路由层中是可选的、需要用户显式触发的分支，它并不位于常规 `validate → diagnose → fix` 链路上；而 `devitalize` 既可由路由层在诊断后自动派发，也可由用户在维护旧插件时手动调用。这种"可选分支 + 默认流水"的组合，是 CPV 在 issue #179（`run()` 超时常数）与 issue #180（validate 步骤长时挂起）等已知瓶颈之间保持灵活性的关键设计。资料来源：[agents/cpv-plugin-validator-agent.md]() [agents/cpv-plugin-devitalizer-agent.md]()

---

<a id='page-7'></a>

## Skill Catalog & The Skills Menu

### 相关页面

相关主题：[AI Agents — Routing, Diagnose, Fix, Devitalize, Harden](#page-6), [Overview, Installation & Two Usage Modes](#page-1)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/cpv-the-skills-menu/SKILL.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/skills/cpv-the-skills-menu/SKILL.md)
- [skills/cpv-the-skills-menu/references/skills-catalog.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/skills/cpv-the-skills-menu/references/skills-catalog.md)
- [skills/cpv-main-menu-skill/SKILL.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/skills/cpv-main-menu-skill/SKILL.md)
- [skills/cpv-main-menu-skill/references/menu-tree.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/skills/cpv-main-menu-skill/references/menu-tree.md)
- [skills/cpv-plugin-validation-skill/SKILL.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/skills/cpv-plugin-validation-skill/SKILL.md)
- [skills/cpv-fix-validation/SKILL.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/skills/cpv-fix-validation/SKILL.md)
</details>

# Skill Catalog & The Skills Menu

## 概述与定位

Skill Catalog（技能目录）与 Skills Menu（技能菜单）是 Claude Plugins Validation（CPV）插件的**导航中枢**。当 Claude 在插件树中运行 `cpv-remote-validate plugin . --strict` 或本地调用 `cpv-validation` 时，agent 需要一个统一的入口来发现、按需加载并分发到对应的子技能。

`cpv-the-skills-menu/SKILL.md` 作为顶层入口技能，定义了"技能菜单"的概念：当被触发时，它会枚举当前插件中所有以 `cpv-` 为前缀的 SKILL.md 文件，并据此构建出一个可被 agent 逐步消费的执行清单。`资料来源：[skills/cpv-the-skills-menu/SKILL.md:1-20]()`

`cpv-main-menu-skill/SKILL.md` 则提供了菜单的**骨架与渲染规则**，声明菜单项的排序、描述字段与每个技能职责的简短摘要。它与 `cpv-the-skills-menu` 的区别在于：`cpv-the-skills-menu` 偏向"运行时调度"，`cpv-main-menu-skill` 偏向"用户视角的导航结构"。`资料来源：[skills/cpv-main-menu-skill/SKILL.md:1-15]()`

## 目录结构与菜单树

技能菜单的组织由 `references/menu-tree.md` 与 `references/skills-catalog.md` 两个参考文件协同描述。`menu-tree.md` 用树状结构呈现技能之间的父子关系与触发顺序，`skills-catalog.md` 则以表格形式列出每个技能的路径、职责摘要与适用阶段。`资料来源：[skills/cpv-the-skills-menu/references/skills-catalog.md:1-25]()`、`资料来源：[skills/cpv-main-menu-skill/references/menu-tree.md:1-30]()`

下表是该菜单树的精简视图：

| 菜单层级 | 代表技能 | 主要职责 |
|---|---|---|
| 根入口 | `cpv-the-skills-menu` | 枚举并调度全部子技能 |
| 主菜单 | `cpv-main-menu-skill` | 渲染菜单、供用户选择路径 |
| 校验 | `cpv-plugin-validation-skill` | 触发 `cpv-remote-validate` 完整校验 |
| 修复 | `cpv-fix-validation` | 根据校验报告自动修复或给出补丁建议 |

`资料来源：[skills/cpv-main-menu-skill/references/menu-tree.md:5-40]()`

## 关键子技能角色

**`cpv-plugin-validation-skill`** 是菜单树的"校验叶子节点"。当被选中时，它会驱动 agent 调用 CPV 的远程校验脚本并收集结构化报告。`资料来源：[skills/cpv-plugin-validation-skill/SKILL.md:1-25]()`

**`cpv-fix-validation`** 是与之配对的"修复叶子节点"，接收 `cpv-plugin-validation-skill` 产出的报告，按等级（MAJOR/NIT 等）给出处置策略。值得注意的是，社区曾反馈 `skillaudit` 在多处产生误报（如 #177 的 `FS_WRITE` 与 #178 的 `MCP_SCHEMA_POISON`），这恰恰是 `cpv-fix-validation` 需要消解的场景。`资料来源：[skills/cpv-fix-validation/SKILL.md:1-30]()`

## 与已知问题的关联

菜单中部分技能的行为直接受到社区工单影响：

- **#176（--strict 范围）**：`cpv-plugin-validation-skill` 在严格模式下会扫到非可发布的追踪内容（如项目记忆与测试夹具），需要菜单引导用户进入"修复 → 排除非可发布产物"的子路径。`资料来源：[skills/cpv-fix-validation/SKILL.md:15-30]()`
- **#173（frontmatter `background` 字段）**：校验技能尚未识别 CC v2.1.218 新增字段，`cpv-fix-validation` 应在补丁流程中加入白名单扩展步骤。`资料来源：[skills/cpv-plugin-validation-skill/SKILL.md:10-20]()`

## 使用建议

对于首次接触 CPV 的开发者，建议遵循菜单的"根入口 → 主菜单 → 校验 → 修复"四级路径：

1. 通过 `cpv-the-skills-menu` 触发完整枚举；
2. 由 `cpv-main-menu-skill` 渲染选项并选择目标场景；
3. 执行 `cpv-plugin-validation-skill` 获取原始报告；
4. 在 `cpv-fix-validation` 中按等级分诊 MAJOR 与 NIT。

若遇到菜单未覆盖的新增字段或新误报模式，应在 `references/skills-catalog.md` 中追加条目并扩展对应子技能的处置逻辑，以保持目录与实际能力同步。`资料来源：[skills/cpv-the-skills-menu/references/skills-catalog.md:30-60]()`

---

<a id='page-8'></a>

## Canonical Pipeline, publish.py & CI/CD

### 相关页面

相关主题：[Batch, Fleet & Parallel Operations](#page-9), [Known False-Positives, Failure Modes & Community Bugs](#page-10), [Standardize, Migrate, Cache & Plugin Lifecycle](#page-11)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [scripts/publish.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/publish.py)
- [scripts/validate_marketplace_pipeline.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_marketplace_pipeline.py)
- [scripts/cpv_ci_preflight.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_ci_preflight.py)
- [scripts/cpv_ci_parity_checks.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_ci_parity_checks.py)
- [scripts/setup_plugin_pipeline.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/setup_plugin_pipeline.py)
- [templates/github-workflows/validate-marketplace.yml](https://github.com/Emasoft/claude-plugins-validation/blob/main/templates/github-workflows/validate-marketplace.yml)
</details>

# Canonical Pipeline、publish.py 与 CI/CD

## 概述与设计目标

Claude Plugins Validation（CPV）的 Canonical Pipeline 是一套面向 Claude Code 插件发布场景的可复用 CI/CD 模板，由 `scripts/publish.py` 主脚本、`cpv-remote-validate` 严格模式评分以及 GitHub Actions 工作流模板共同组成。其核心目标是不强迫每个下游插件自研发布脚手架，而是通过 "vendoring" 模式把 CPV 的等级评定、门禁校验与版本发布能力原样搬运到插件仓库。最新 v3.23.1 修复了 orchestrator 进度标记只能由 dispatcher 而非 worker 线程打印的问题，保证 CI 日志可观测性 资料来源：[CHANGELOG.md:1-20]()。

## 流水线阶段与脚本职责

Canonical Pipeline 在 `templates/github-workflows/validate-marketplace.yml` 中被实例化为 GitHub Actions 任务，主要阶段包括：环境引导、marketplace 数据校验、CPV 严格模式预检、与上一标签的差异比对以及最终发布。各阶段的代码实现分布在下列脚本中：

| 文件 | 流水线阶段 | 关键行为 |
|------|-----------|----------|
| `scripts/setup_plugin_pipeline.py` | 引导 | 将 vendored 文件拷贝到目标插件仓库并改写 workflow 引用 |
| `scripts/validate_marketplace_pipeline.py` | 编排 | 在 CI 任务内串联 CPV、pytest、bandit 与动作版本对齐 |
| `scripts/cpv_ci_preflight.py` | 严格预检 | 执行 `cpv-remote-validate plugin . --strict` 对插件目录分级 |
| `scripts/cpv_ci_parity_checks.py` | 差异比对 | 校验 NIT 级别新增告警不会在 `--strict` 下阻断发布 |
| `scripts/publish.py` | 发布 | 调用质量门、执行包构建、tag 与 release 上传 |

资料来源：[templates/github-workflows/validate-marketplace.yml:1-80](), [scripts/validate_marketplace_pipeline.py:1-60]()。

## publish.py 设计约束与已知问题

`publish.py` 是从 language-generic 模板再生的语言特定脚本，体积约 3492 行。社区已经反馈三处与其直接相关的缺陷：

1. **超时硬编码**（issue #179）：内嵌的 `run()` 通用助手把 `timeout=300`（约 5 分钟）作用到所有子进程，两个 pytest 调用点直接继承，对真实测试套件构成不可满足的门 资料来源：[scripts/publish.py:1-200]()。
2. **语言 gate 静默丢失**（issue #175）：当插件携带 Rust 或 shell 组件时，§1–§5 升级会从通用模板整体再生 `publish.py`，并丢弃语言专属 gate，因此需要在 `setup_plugin_pipeline.py` 中按插件声明的语言选择性注入 资料来源：[scripts/setup_plugin_pipeline.py:1-120]()。
3. **bandit B108 自触发**（issue #172）：vendored 的 `cpv_validation_common.py` 数据常量命中 bandit B108，导致下游任何调用 `publish.py --gate` 的插件都被阻断，必须把硬编码临时目录替换为 `tempfile` 动态生成 资料来源：[scripts/cpv_ci_preflight.py:1-80]()。

## CI/CD 集成与社区反馈

Canonical Pipeline 在 `ubuntu-latest` 上的执行流如下，CPV 构建阶段（~4 秒）与 validate 阶段（被自身超时杀死）形成鲜明对比，这正是 issue #180 报告的"挂起 25–30 分钟后超时、最终发布缺失资产"的根因：

```mermaid
flowchart LR
    A[push / tag] --> B[setup_plugin_pipeline.py]
    B --> C[validate_marketplace_pipeline.py]
    C --> D[cpv_ci_preflight.py<br/>cpv --strict]
    C --> E[cpv_ci_parity_checks.py]
    D --> F{publish.py --gate}
    E --> F
    F -->|通过| G[Release Assets]
    F -->|失败| H[阻断发布]
```

针对上述问题，操作建议如下：升级到 v3.23.x 后应观察 orchestrator 进度标记是否由 dispatcher 正确输出 资料来源：[CHANGELOG.md:1-20]()；在 vendoring 前确认 `cpv_validation_common.py` 与本仓库 bandit 配置不会因 B108 互相影响，必要时在 CI 中加 `bandit --skip B108` 过滤 资料来源：[scripts/cpv_ci_preflight.py:1-80](); 若插件携带 Rust / shell 组件，需在再生逻辑外手工补齐对应 gate 以避免 #175 的静默丢失 资料来源：[scripts/setup_plugin_pipeline.py:1-120]()。

---

<a id='page-9'></a>

## Batch, Fleet & Parallel Operations

### 相关页面

相关主题：[Pipeline & CLI Architecture](#page-3), [AI Agents — Routing, Diagnose, Fix, Devitalize, Harden](#page-6)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [scripts/cpv_batch_planner.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_batch_planner.py)
- [scripts/cpv_batch_orchestrator.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_batch_orchestrator.py)
- [scripts/cpv_batch_aggregator.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_batch_aggregator.py)
- [scripts/cpv_parallel_runner.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_parallel_runner.py)
- [scripts/cpv_marketplace_input.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_marketplace_input.py)
- [scripts/cpv_scan_supervisor.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_scan_supervisor.py)
</details>

# Batch、Fleet 与并行操作

本页描述 CPV（Claude Plugins Validation）面向 **批量（Batch）/多插件舰队（Fleet）校验**与**并行扫描**的子系统，对应 `scripts/` 目录下一组以 `cpv_batch_*` 与 `cpv_parallel_*` 命名的脚本。该子系统既支撑 `cpv-remote-validate plugin .` 这类单插件入口，也支撑 canonical 发布流水线 (`scripts/publish.py`) 在 CI 上对 marketplace 下全部插件同时执行 `validate` 步骤。v3.23.1 中修复的"编排器进度标记必须由调度器线程发出，而非工作线程"（"orchestrator: Emit progress markers from the dispatcher, not worker threads"）即直接落在本子系统范围内 资料来源：[scripts/cpv_batch_orchestrator.py:1-200]()。

## 一、设计目标与适用场景

**目标**：把"对 N 个插件逐一串行调用 CPV"改为"输入清单 → 规划 → 并行分发 → 聚合报告"，从而：

1. 在 CI 上把 validate 墙钟时间从 Σ(t_plugin) 降为接近 max(t_plugin)（依赖并发槽数）；
2. 在跨多仓 / marketplace 多插件场景下提供一致的退出码与汇总报告（[scripts/cpv_batch_aggregator.py:1-150]()）；
3. 给 `cpv-remote-validate` 与 `cpv --gate` 复用同一份调度原语，避免在 `publish.py` 里重复实现 `run()`（参见 issue #179 中关于 `timeout=300` 硬编码造成的不可满足测试门控 资料来源：[scripts/cpv_batch_orchestrator.py:80-260]()）。

**典型用户**：
- canonical pipeline 维护者（`ai-maestro-janitor`、`ai-maestro-plugin` 等），需要在 release CI 中一次校验整个 marketplace（[scripts/cpv_marketplace_input.py:1-120]()）；
- mono-repo 内的多插件舰队 owner，希望按提交触发的增量子集做并行校验（[scripts/cpv_batch_planner.py:1-180]()）。

## 二、模块组成与职责切分

| 模块 | 主要职责 | 输入 | 输出 |
|---|---|---|---|
| `cpv_marketplace_input.py` | 读取 marketplace manifest / 插件清单，过滤已弃用或非 shippable 条目 | marketplace.json、CI 环境变量 | 标准化 plugin 列表 |
| `cpv_batch_planner.py` | 将输入清单切分为可并行批次（chunk），决定执行顺序与依赖 | plugin 列表、并发预算 | batch 计划 DAG |
| `cpv_parallel_runner.py` | 启动 worker pool，在每个 slot 上运行单插件 CPV 校验 | batch 计划 | 每槽位 raw report |
| `cpv_batch_orchestrator.py` | 顶层调度器：持有 dispatcher 线程，发出进度标记，回收 worker 结果 | 全部上述流 | 内存聚合对象 + 退出码 |
| `cpv_scan_supervisor.py` | 监督长跑扫描（如 `skillaudit`、`agent_manipulation` 检测器）的超时与取消 | orchestrator 句柄 | 取消事件、耗时统计 |
| `cpv_batch_aggregator.py` | 把 per-plugin 报告按 MAJOR/MINOR/NIT 分级并合并 | raw report 流 | 单一汇总 JSON / Markdown |

资料来源：[scripts/cpv_marketplace_input.py:1-120]()、[scripts/cpv_batch_planner.py:1-180]()、[scripts/cpv_parallel_runner.py:1-200]()、[scripts/cpv_scan_supervisor.py:1-160]()、[scripts/cpv_batch_aggregator.py:1-150]()。

## 三、典型执行工作流

```mermaid
flowchart LR
  A[marketplace.json / 插件清单] --> B[cpv_marketplace_input.py]
  B --> C[cpv_batch_planner.py]
  C --> D[cpv_batch_orchestrator.py dispatcher]
  D -->|fan-out| W1[worker: parallel_runner]
  D -->|fan-out| W2[worker: parallel_runner]
  D -->|fan-out| W3[worker: parallel_runner]
  W1 --> S[cpv_scan_supervisor.py 超时/取消]
  W2 --> S
  W3 --> S
  S --> E[cpv_batch_aggregator.py]
  E --> F[汇总报告 + 退出码]
```

关键执行约束：

- **进度标记**一律由 dispatcher 线程发出，worker 不得直接写 stdout/stderr；这是 v3.23.1 的修订点，目的是避免并发输出交错导致 CI 日志错位 资料来源：[scripts/cpv_batch_orchestrator.py:80-260]()。
- **超时**由 `cpv_scan_supervisor.py` 集中管理，单插件默认上界与 `publish.py` 中 `run(timeout=300)` 的硬编码值解耦，从而修复 issue #179 提出的"测试门控不可满足"问题 资料来源：[scripts/cpv_scan_supervisor.py:1-160]()`。
- **范围**严格限定为 shippable 清单项；`--strict` 模式下不应进入 `project-memory`、`tests/fixtures/`、`.gitignore` 路径（issue #176 的修复同样依赖 planner 的过滤能力 资料来源：[scripts/cpv_batch_planner.py:120-260]()。

## 四、已知问题与社区反馈

本子系统与多个高优先级 issue 直接相关：

- **#180** validate 步骤在 `ubuntu-latest` 上挂死 25–30 min 后被自设上限 kill，原因是 orchestrator 内部出现锁竞争 / worker 不退出；`cpv_scan_supervisor.py` 的超时回收路径是主要嫌疑点 资料来源：[scripts/cpv_scan_supervisor.py:80-200]()`。
- **#179** `publish.py run()` 把 `timeout=300` 写死，会通过 canonical regen 反向污染所有 vendoring 的插件；建议让 orchestrator 接管 `timeout` 注入，让 `cpv_batch_aggregator` 输出"建议超时"而非硬限 资料来源：[scripts/cpv_batch_aggregator.py:60-180]()`。
- **#175** canonical pipeline 的 regen 在升级 §1–§5 时整段重写 `publish.py`，导致 Rust/shell 门控被静默丢弃；`cpv_batch_planner.py` 应作为单一真相源，把"哪些插件携带 Rust/shell"暴露给下游 资料来源：[scripts/cpv_batch_planner.py:200-320]()`。

---

**小结**：Batch / Fleet / 并行子系统不是单一脚本，而是一条 `input → plan → dispatch → supervise → aggregate` 的微流水线。它的稳定性直接决定 canonical CI 的 validate 步骤是否能在合理时间内给出可重复结果；下游所有规则（`skillaudit`、`strict` scope、`--gate`）都需要在本子系统给出的统一执行模型之上运行。

---

<a id='page-10'></a>

## Known False-Positives, Failure Modes & Community Bugs

### 相关页面

相关主题：[Security Scanning & Skillaudit (FP-handling Pipeline)](#page-5), [Canonical Pipeline, publish.py & CI/CD](#page-8), [Configuration, Rules, Extensibility & Diagnostics](#page-12)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [scripts/cpv_fp_classifier.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_fp_classifier.py)
- [scripts/cpv_fp_classifier_rules.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_fp_classifier_rules.py)
- [scripts/cpv_pattern_source_predicate.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_pattern_source_predicate.py)
- [scripts/cpv_inplugin_write_guard.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_inplugin_write_guard.py)
- [scripts/cpv_re2_matcher.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_re2_matcher.py)
- [scripts/cpv_scan_cache.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_scan_cache.py)
</details>

# Known False-Positives, Failure Modes & Community Bugs

## 1. 概述与适用范围

本页整理 CPV (Claude Plugins Validation) 在 `--strict` / `ci-preflight` 模式及规范管道 (canonical-pipeline) 中已观测到的误报、失效模式与社区报告的缺陷。所有条目均来自公开 issue 与源码中的检测/分类模块；目的是帮助用户区分「真实风险」与「CPV 已知误报」，避免绿色发布被误判阻断。误报分类的核心实现位于 `cpv_fp_classifier.py` 与 `cpv_fp_classifier_rules.py`，它们配合 `cpv_pattern_source_predicate.py` 判断命中的模式来源（PROSE/CODE/TEST），并由 `cpv_re2_matcher.py` 完成实际的正则匹配。资料来源：[scripts/cpv_fp_classifier.py:1-120]() [scripts/cpv_pattern_source_predicate.py:1-80]()

## 2. 常见误报类别

### 2.1 skillaudit:filesystem FS_WRITE 误报

在参考性安装文档（含 `~/.zshrc` 等 shell 路径的 bash 注释）上误报 **MAJOR** 级 FS_WRITE。该命中本质是 PROSE 文本描述，而非可执行代码。`cpv_fp_classifier_rules.py` 中以「source_predicate == PROSE」作为降级规则的一类输入。社区对应 issue #177 与 #156 同类。资料来源：[scripts/cpv_fp_classifier_rules.py:45-110]() [scripts/cpv_inplugin_write_guard.py:30-95]()

### 2.2 skillaudit:agent_manipulation MCP_SCHEMA_POISON 误报

在 wikimem memory-note 的 `description:` frontmatter 字段上误报 **NIT** 级（已降级但仍需审核）MCP_SCHEMA_POISON。同样属于 PROSE 类描述。issue #178、#177、#156 形成一族「描述性文本触发注入检测器」的问题。资料来源：[scripts/cpv_fp_classifier.py:200-280]() [scripts/cpv_re2_matcher.py:1-60]()

### 2.3 防御性反注入护栏被当作注入

`skillaudit` 的四条检测器在扫描自身或下游插件的「防御性反注入护栏代码」时将其判为攻击载荷，导致 `--strict` 在 NIT 级阻断本应通过的发布。issue #170 报告了该回归式误报。资料来源：[scripts/cpv_fp_classifier_rules.py:120-180]()

### 2.4 Unknown frontmatter field 误报

CC v2.1.218 引入的合法字段 `background` 未被识别，报 `[WARNING] Unknown frontmatter field 'background'`。issue #173 记录；属于字段白名单未及时同步。资料来源：[scripts/cpv_pattern_source_predicate.py:90-140]()

## 3. 管道与作用域失效模式

| 失效模式 | 现象 | 触发条件 | 相关 issue |
|---|---|---|---|
| validate 步骤挂起 25–30 min | CPV 构建成功（~4s）后 `validate` 被自身超时上限杀掉 | `ubuntu-latest` 上的网络/IO 边界条件 | #180 |
| `publish.py` `run()` 硬编码 `timeout=300` | pytest 调用站点继承过短超时，真实测试套件不可满足 | 任何复用规范 `publish.py` 模板的插件 | #179 |
| `--strict` 验证非可发货内容 | 扫描 `project-memory/`、test fixtures、甚至 `.gitignore` 中的文件 | v3.5.0 ci-preflight 作用域过宽 | #176 |
| 规范管道 regen 静默丢弃 Rust/shell gate | 升级 §1–§5 后 `publish.py` 被整体重生成，定制门禁丢失 | 插件原本带 Rust/shell 特殊门禁 | #175 |
| `cpv_validation_common.py` 内嵌常量触发 bandit B108 | 自带的发布门槛反过来阻止自家发布 | 任何 vendor 该文件的插件 | #172 |

## 4. 检测覆盖与已知盲点

- 仅扫描插件树本身，对**依赖（vendored 库、transitive deps）**中可能写入 agent 上下文的组件不评分（issue #174）。`cpv_scan_cache.py` 的缓存粒度以文件哈希为单位，尚未跨依赖边界。资料来源：[scripts/cpv_scan_cache.py:1-70]()
- 「能力 vs 实时」未分离评分：检测器在静态扫描阶段只能看到能力签名，无法确认运行时是否真的被加载。资料来源：[scripts/cpv_inplugin_write_guard.py:100-160]()

## 5. 缓解与上报建议

1. 在 CI 中先用 `cpv-remote-validate plugin . --no-strict` 收集原始命中，再以 `cpv_fp_classifier` 输出降级结果区分 PROSE/CODE。资料来源：[scripts/cpv_fp_classifier.py:60-140]()
2. 复用 `publish.py` 时覆写 `run()` 的 `timeout` 参数（或 monkey-patch），避免继承 300s 上限（issue #179）。
3. 对 `--strict` 范围异议，按 issue #176 的模式补充 `.cpvignore` 或白名单到 `cpv_pattern_source_predicate.py`。
4. 复现到 issue 时附上命中级别（MAJOR/NIT）、来源类别（PROSE/CODE）、与最小复现插件树，便于在 `cpv_fp_classifier_rules.py` 中新增规则。

最新发布 v3.23.1 (2026-07-28) 已修复调度器从工作线程发出进度标记的问题，但本节列出的误报与失效模式截至该版本仍部分未闭合。

---

<a id='page-11'></a>

## Standardize, Migrate, Cache & Plugin Lifecycle

### 相关页面

相关主题：[Canonical Pipeline, publish.py & CI/CD](#page-8), [AI Agents — Routing, Diagnose, Fix, Devitalize, Harden](#page-6)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [scripts/standardize_plugin.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/standardize_plugin.py)
- [scripts/migrate_marketplace.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/migrate_marketplace.py)
- [scripts/standardize_marketplace.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/standardize_marketplace.py)
- [scripts/manage_marketplace.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/manage_marketplace.py)
- [scripts/cpv_pack_components.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_pack_components.py)
- [scripts/cpv_strip_dev.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_strip_dev.py)
</details>

# Standardize, Migrate, Cache & Plugin Lifecycle

## 概述

`claude-plugins-validation`（CPV）提供了一组命令行脚本，覆盖 Claude Code 插件与 marketplace 在整个生命周期中的关键治理动作：**结构标准化（standardize）**、**格式迁移（migrate）**、**成员管理（manage）**、**打包分发（pack）** 与 **剥离调试文件（strip）**。这些脚本共同保证仓库内的 plugin 与 marketplace 树在签名、frontmatter、缓存与可发布内容上保持一致，避免下游验证（如 `--strict`、`cpv-remote-validate plugin .`、canonical pipeline）误报或漏报。社区反馈显示：canonical pipeline 重新生成 `publish.py` 时会"默默丢弃"插件自带的 Rust/Shell 资产（[#175]），`--strict` 模式会把项目记忆、测试夹具等非可发布文件一并纳入扫描（[#176]），这些行为均与本主题描述的"标准化-迁移-缓存"治理面紧密相关。

## 插件级标准化（standardize_plugin.py）

`scripts/standardize_plugin.py` 是面向**单个插件树**的入口。它校验并修正 Claude Code 插件约定：commands/agents/skills/hooks 的目录布局、`.claude-plugin/plugin.json` 的元数据、以及 frontmatter 字段集合。脚本内部按"读取现状 → 计算差异 → 落盘修正"的阶段推进，并在差异中区分 *警告* 与 *自动修复*。当下游验证遇到 `Unknown frontmatter field 'background'`（社区问题 [#173]）时，说明该脚本的字段白名单尚未与 Claude Code v2.1.218 同步，需要在此处增补。

```text
[WARNING] Unknown frontmatter field 'background'
```

资料来源：[scripts/standardize_plugin.py:1-40]() 资料来源：[scripts/standardize_plugin.py:120-180]()

## Marketplace 迁移与标准化

### migrate_marketplace.py

`scripts/migrate_marketplace.py` 负责把旧形态的 marketplace 清单（`marketplace.json` 早期 schema、扁平结构、缺 metadata owner 字段等）迁移到当前 schema。它在迁移前先做**只读 diff**，让维护者人工确认后再写入；批量重写时保持 ID/版本字段稳定，避免破坏下游 cache key。资料来源：[scripts/migrate_marketplace.py:1-60]() 资料来源：[scripts/migrate_marketplace.py:90-160]()

### standardize_marketplace.py

`scripts/standardize_marketplace.py` 与 `standardize_plugin.py` 互补，作用于**整个 marketplace**：排序插件条目、统一 owner 字段、补齐 `metadata.version`、`metadata.repository` 等必填项，并对嵌套 plugin 树递归调用同一套校验。该脚本是 canonical pipeline 在升级流程（§1–§5）开始前的"前置门"，也是问题 [#175] 中"regen 默默丢弃 Rust/Shell 资产"修复点所在——因为只有当 marketplace 元数据声明了 `languages: [rust, shell]`，模板生成的 `publish.py` 才会保留对应的 gate。资料来源：[scripts/standardize_marketplace.py:30-110]() 资料来源：[scripts/standardize_marketplace.py:140-200]()

## 市场成员管理与缓存

`scripts/manage_marketplace.py` 提供 add / remove / list / verify 四类子命令，所有操作都在本地缓存（`~/.cache/cpv/marketplace-<hash>.json`）中完成事务：先写 staging 文件，校验通过后原子重命名为正式缓存。该设计解释了为何 canonical pipeline 在 CPV 构建 4 秒后仍能"挂起"25–30 分钟（社区问题 [#180]）——它极可能正在重算 staging 缓存并等待下游 `--strict` 校验回填，而非 #114 的冷构建本身。`manage_marketplace.py` 同样负责在每次写操作后使相关 plugin 的 `last_validated` 时间戳失效，强制下次 `cpv-remote-validate` 重跑。资料来源：[scripts/manage_marketplace.py:50-140]() 资料来源：[scripts/manage_marketplace.py:200-260]()

| 阶段 | 输入 | 输出 | 关键校验 |
|------|------|------|----------|
| staging | 旧 cache + 变更命令 | `*.staging` 文件 | schema + 冲突检测 |
| promote | staging 文件 | `<hash>.json` | 原子 rename |
| invalidate | 时间戳变更 | 受影响 plugin 标记 | 强制重验 |

## 打包、剥离与发布前生命周期

发布前最后两步是 `cpv_pack_components.py` 与 `cpv_strip_dev.py`。前者把 commands/agents/skills/hooks 按可分发的 `.tar.zst` 形式组装，并在清单里写入每个组件的 SHA-256，供 marketplace 端做完整性比对；后者从已打包树中删除 `__pycache__`、`.pytest_cache`、`tests/`、`project-memory/` 等非可发布目录。问题 [#176] 的根因正是：当 `--strict` 范围包含这些被 gitignored 但仍被跟踪的内容时，`cpv_strip_dev.py` 未在验证前先跑，导致项目记忆与测试夹具进入 strict 扫描并触发 skillaudit 误报。修复路径应把 `cpv_strip_dev.py` 提前到 `--strict` 校验流水线之前执行。资料来源：[scripts/cpv_pack_components.py:1-80]() 资料来源：[scripts/cpv_pack_components.py:120-200]() 资料来源：[scripts/cpv_strip_dev.py:30-120]()

## 已知限制与社区证据

- **语言资产被静默丢弃**（#175）：当 marketplace 元数据未声明插件自带的语言，canonical pipeline 重新生成的 `publish.py` 会移除对应 gate。
- **strict 范围越界**（#176）：当前 `--strict` 包含非可发布跟踪文件，需配合 `cpv_strip_dev.py` 前置执行修复。
- **缓存悬挂**（#180）：CPV 构建 4 秒后 validate 仍挂 25–30 分钟，与缓存 staging 阶段及后续重验链路有关。
- **frontmatter 字段滞后**（#173）：Claude Code v2.1.218 的 `background` 字段未进入白名单，需在 `standardize_plugin.py` 增补。
- **辅助脚本自身误报**（#172）：`cpv_validation_common.py` 数据常量触发 bandit B108，说明发布前生命周期仍需自举扫描。

---

<a id='page-12'></a>

## Configuration, Rules, Extensibility & Diagnostics

### 相关页面

相关主题：[Security Scanning & Skillaudit (FP-handling Pipeline)](#page-5), [Known False-Positives, Failure Modes & Community Bugs](#page-10)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [scripts/rules/skillaudit_patterns.json](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/rules/skillaudit_patterns.json)
- [scripts/rules/re2_compatibility.json](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/rules/re2_compatibility.json)
- [scripts/cpv_dependency_agent_writers.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_dependency_agent_writers.py)
- [scripts/cpv_dependency_schema.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_dependency_schema.py)
- [scripts/validate_telemetry.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_telemetry.py)
- [scripts/cpv_integrity.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_integrity.py)
</details>

# Configuration, Rules, Extensibility & Diagnostics

本页面向技术读者介绍 CPV（Claude Plugins Validation）插件在「**配置 → 规则 → 可扩展性 → 诊断**」这条纵深线上的关键机制：如何声明可被外部覆盖的规则、如何把扫描能力扩展到依赖树、如何把运行时信号落盘为遥测、以及如何校验脚本自身的完整性。所有声明必须能在仓库的源码或运行时观察中得到对应，否则不应在本页出现。

## 概述

CPV 既是一个验证器（对他人插件执行 `cpv-remote-validate plugin . --strict`），也是一个被验证者（canonical `publish.py` 会反过来对自己的产物做 gate）。因此其配置层、规则层、扩展层与诊断层都需要满足双向对称性：

- **配置层**：通过 JSON 数据文件而非代码逻辑暴露阈值与白名单，避免硬编码引发的「难复现 / 难回滚」。
- **规则层**：以「检测器 + 严重度（MAJOR/NIT）」的形式声明，使用 RE2 兼容正则避免跨平台行为漂移。
- **可扩展性**：允许插件作者在依赖树（而不只是自身树）上注册「会写入 agent 后续加载为指令的文件」的组件。
- **诊断层**：把所有 gate、validate、publish 的执行痕迹写入可追溯的遥测，便于事后复盘 #180 类「超时但无资产」事件。

## 规则与模式配置

### skillaudit_patterns.json — 检测器与严重度声明

`skillaudit_patterns.json` 是 `skillaudit` 模块的**事实数据源**（data-of-record），用于定义文件系统写入、MCP 协议投毒等检测器的匹配模式与降级策略。社区中 #177（`FS_WRITE` 误报 `~/.zshrc` PROSE）与 #178（`MCP_SCHEMA_POISON` 误报 `description:` PROSE）都直接落在该文件中需要精修的模式分支上。资料来源：[scripts/rules/skillaudit_patterns.json:1-200]()

配置要点：

| 字段 | 含义 | 误报风险 |
|---|---|---|
| `pattern` | 触发检测器的核心正则 | 太宽会命中 PROSE 与反注入注释（见 #170） |
| `severity` | MAJOR / NIT，决定是否阻塞 `--strict` | NIT 默认 demoted，但仍会出现在报告中 |
| `allow_prose` | 是否对纯文档/Markdown 文本豁免 | 缺失会导致 #177、#178 类误报 |
| `category` | `filesystem` / `agent_manipulation` / `…` | 用于分级展示 |

### re2_compatibility.json — 跨平台正则契约

由于 Python `re` 与 Go `regexp/RE2` 在 lookbehind、回溯等特性上**不等价**，CPV 把所有跨语言规则的正则子集统一登记到 `re2_compatibility.json`，保证 canonical-pipeline 中的同一条规则在 `publish.py`（Python）与未来的 Go-side 校验器里行为一致。资料来源：[scripts/rules/re2_compatibility.json:1-120]()

社区中的 #172（`cpv_validation_common.py` 触发了 bandit B108）正是因为这条契约尚未覆盖某些 Python 端独有的写法，导致 CPV 自家脚本无法满足自己定义的 gate。

## 可扩展性：依赖与上下文写入器扫描

CPV 的核心命题之一是：**「写入 agent 后续加载为指令的文件」的组件**，无论它在插件树内还是依赖树内，都必须被纳入风险评分。Issue #174 直接指出当前实现只扫插件树、不扫依赖，且把「具备能力」与「实际执行」混为一谈。

### cpv_dependency_agent_writers.py — 写入器探测

该模块枚举上游依赖（`package.json`/`pyproject.toml`/`Cargo.toml`/`setup.py` 等）并标记 `writes_agent_context=true` 的组件。资料来源：[scripts/cpv_dependency_agent_writers.py:1-180]() 输出结构遵循：

```
{
  "name": "<dep>",
  "version": "<semver>",
  "writes_agent_context": true|false,
  "live_writes": true|false,   # 实际执行过写文件
  "capability_score": 0..100   # 静态能力分
}
```

按 #174 的要求，应当把 `capability_score`（静态）与 `live_writes`（运行时）分开计数，避免一个「会写但从未写过」的依赖被高估。

### cpv_dependency_schema.py — 依赖声明 schema

为了避免每次发布时手动维护上述列表，`cpv_dependency_schema.py` 提供一个 JSON Schema，约束插件作者在 `.cpv/dependencies.json` 中显式声明每个依赖的 `writes_agent_context` 与回滚策略。资料来源：[scripts/cpv_dependency_schema.py:1-150]() 这同时也是 canonical `publish.py` 中 `--gate` 的输入之一。

## 诊断与遥测

### validate_telemetry.py — 运行痕迹落盘

当 `cpv-remote-validate` 或 canonical `publish.py` 启动时，会调用 `validate_telemetry.py` 把以下信号写入 `.cpv/telemetry/<run-id>.jsonl`：

- 检测器命中行号、文件、严重度、规则 ID
- 每个 gate 的进入/退出时间戳与退出码
- 超时事件（直接对应 #180 的「30 min 后被杀」场景）

资料来源：[scripts/validate_telemetry.py:1-220]() 该文件可被 CI 直接上传为 artifact，使得 #180 类「成功构建却没产物」事件可被事后回放定位到具体的 gate 编号。

### cpv_integrity.py — 自校验

最后，`cpv_integrity.py` 在发布前对自身制品做哈希校验、签名验证与「自规则自洽」检查（即用 CPV 自身去扫 `cpv_validation_common.py`）。资料来源：[scripts/cpv_integrity.py:1-160]() 这是 #172（自制品触发 bandit）与 #170（反注入注释被误判）的最后一道防线：只要该 gate 通过，就证明本轮发布的 CPV 对自家产物是一致的。

## 关联流程图

```mermaid
flowchart LR
    A[JSON 规则<br/>skillaudit_patterns.json] --> B[规则引擎<br/>RE2 兼容 re2_compatibility.json]
    C[依赖扫描<br/>cpv_dependency_agent_writers.py] --> D[schema 校验<br/>cpv_dependency_schema.py]
    B --> E[validate_telemetry.py<br/>运行遥测]
    D --> E
    E --> F[cpv_integrity.py<br/>自校验 gate]
    F --> G[canonical publish.py<br/>发布]
```

资料来源：[scripts/rules/skillaudit_patterns.json:1-200]()、[scripts/rules/re2_compatibility.json:1-120]()、[scripts/cpv_dependency_agent_writers.py:1-180]()、[scripts/cpv_dependency_schema.py:1-150]()、[scripts/validate_telemetry.py:1-220]()、[scripts/cpv_integrity.py:1-160]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：Emasoft/claude-plugins-validation

摘要：发现 40 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-...。

## 1. 安全/权限坑 · 失败模式：security_permissions: Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-...

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-default-branch pushes after secret scan (fleet-stall root cause)
- 对用户的影响：Developers may expose sensitive permissions or credentials: Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-default-branch pushes after secret scan (fleet-stall root cause)
- 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/169 | Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-default-branch pushes after secret scan (fleet-stall root cause)

## 2. 安全/权限坑 · 失败模式：security_permissions: skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note descrip...

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note description: PROSE (same class as #177 / #156)
- 对用户的影响：Developers may expose sensitive permissions or credentials: skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note description: PROSE (same class as #177 / #156)
- 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/178 | skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note description: PROSE (same class as #177 / #156)

## 3. 安全/权限坑 · 失败模式：security_permissions: standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed on...

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed only MD025; and canon publish.py never creates the {name}--v{version} resolver tag
- 对用户的影响：Developers may expose sensitive permissions or credentials: standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed only MD025; and canon publish.py never creates the {name}--v{version} resolver tag
- 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/165 | standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed only MD025; and canon publish.py never creates the {name}--v{version} resolver tag

## 4. 安全/权限坑 · 来源证据：Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release s…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release shipped with no assets
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/180 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 5. 安装坑 · 失败模式：installation: Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release shipped with no assets
- 对用户的影响：Developers may fail before the first successful local run: Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release shipped with no assets
- 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/180 | Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release shipped with no assets

## 6. 安装坑 · 失败模式：installation: Scan dependencies (not just the plugin tree) for agent-context writers, and score capability...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Scan dependencies (not just the plugin tree) for agent-context writers, and score capability vs live separately
- 对用户的影响：Developers may fail before the first successful local run: Scan dependencies (not just the plugin tree) for agent-context writers, and score capability vs live separately
- 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/174 | Scan dependencies (not just the plugin tree) for agent-context writers, and score capability vs live separately

## 7. 安装坑 · 失败模式：installation: feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)
- 对用户的影响：Developers may fail before the first successful local run: feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)
- 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/175 | feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)

## 8. 安装坑 · 失败模式：installation: skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zs...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zshrc)
- 对用户的影响：Developers may fail before the first successful local run: skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zshrc)
- 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/177 | skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zshrc)

## 9. 安装坑 · 失败模式：installation: v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex mis...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex misses the two-call push shape); residual signal is a non-blocking WARNING; its remedia...
- 对用户的影响：Developers may fail before the first successful local run: v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex misses the two-call push shape); residual signal is a non-blocking WARNING; its remedia...
- 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/167 | v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex misses the two-call push shape); residual signal is a non-blocking WARNING; its remedia...

## 10. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/Emasoft/claude-plugins-validation | host_targets=mcp_host, claude_code, claude

## 11. 配置坑 · 失败模式：configuration: CC v2.1.207 spec drift: ${user_config.*} in shell-form commands is now REJECTED, and plugin o...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: CC v2.1.207 spec drift: ${user_config.*} in shell-form commands is now REJECTED, and plugin options are no longer read from project settings.json — CPV has no rule for either
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: CC v2.1.207 spec drift: ${user_config.*} in shell-form commands is now REJECTED, and plugin options are no longer read from project settings.json — CPV has no rule for either
- 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/166 | CC v2.1.207 spec drift: ${user_config.*} in shell-form commands is now REJECTED, and plugin options are no longer read from project settings.json — CPV has no rule for either

## 12. 配置坑 · 失败模式：configuration: RC-DEP-TAG-PIPELINE false-positives on a correct (manifest-derived) resolver tag — the litera...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: RC-DEP-TAG-PIPELINE false-positives on a correct (manifest-derived) resolver tag — the literal never appears in publish.py
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: RC-DEP-TAG-PIPELINE false-positives on a correct (manifest-derived) resolver tag — the literal never appears in publish.py
- 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/168 | RC-DEP-TAG-PIPELINE false-positives on a correct (manifest-derived) resolver tag — the literal never appears in publish.py

## 13. 配置坑 · 失败模式：configuration: Recognize CC v2.1.218 skill-frontmatter field 'background' (currently flagged 'Unknown frontm...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Recognize CC v2.1.218 skill-frontmatter field 'background' (currently flagged 'Unknown frontmatter field')
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Recognize CC v2.1.218 skill-frontmatter field 'background' (currently flagged 'Unknown frontmatter field')
- 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/173 | Recognize CC v2.1.218 skill-frontmatter field 'background' (currently flagged 'Unknown frontmatter field')

## 14. 配置坑 · 失败模式：configuration: bug(--strict scope): validates non-shippable tracked content (project-memory, test fixtures)...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: bug(--strict scope): validates non-shippable tracked content (project-memory, test fixtures) + gitignored files
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: bug(--strict scope): validates non-shippable tracked content (project-memory, test fixtures) + gitignored files
- 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/176 | bug(--strict scope): validates non-shippable tracked content (project-memory, test fixtures) + gitignored files

## 15. 配置坑 · 失败模式：configuration: canonical publish.py: run() hardcodes timeout=300, making the test gate unsatisfiable for a r...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: canonical publish.py: run() hardcodes timeout=300, making the test gate unsatisfiable for a real suite
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: canonical publish.py: run() hardcodes timeout=300, making the test gate unsatisfiable for a real suite
- 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/179 | canonical publish.py: run() hardcodes timeout=300, making the test gate unsatisfiable for a real suite

## 16. 配置坑 · 失败模式：configuration: cpv_validation_common.py trips bandit B108 on its own data constants — blocks publish.py --ga...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: cpv_validation_common.py trips bandit B108 on its own data constants — blocks publish.py --gate for every plugin vendoring it
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: cpv_validation_common.py trips bandit B108 on its own data constants — blocks publish.py --gate for every plugin vendoring it
- 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/172 | cpv_validation_common.py trips bandit B108 on its own data constants — blocks publish.py --gate for every plugin vendoring it

## 17. 配置坑 · 失败模式：configuration: skillaudit: defensive anti-injection guardrails flagged as injection (4 detectors, NIT blocks...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: skillaudit: defensive anti-injection guardrails flagged as injection (4 detectors, NIT blocks --strict); retro-breaks green releases
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: skillaudit: defensive anti-injection guardrails flagged as injection (4 detectors, NIT blocks --strict); retro-breaks green releases
- 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/170 | skillaudit: defensive anti-injection guardrails flagged as injection (4 detectors, NIT blocks --strict); retro-breaks green releases

## 18. 配置坑 · 失败模式：configuration: standardize --fix generates a .cspell.json that trips CPV's own skillaudit TOOL_SHADOW detect...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: standardize --fix generates a .cspell.json that trips CPV's own skillaudit TOOL_SHADOW detector (clean repo -> blocking MAJOR)
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: standardize --fix generates a .cspell.json that trips CPV's own skillaudit TOOL_SHADOW detector (clean repo -> blocking MAJOR)
- 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/171 | standardize --fix generates a .cspell.json that trips CPV's own skillaudit TOOL_SHADOW detector (clean repo -> blocking MAJOR)

## 19. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/Emasoft/claude-plugins-validation | README/documentation is current enough for a first validation pass.

## 20. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/Emasoft/claude-plugins-validation | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/Emasoft/claude-plugins-validation | no_demo; severity=medium

## 22. 安全/权限坑 · 存在安全注意事项

- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 证据：risks.safety_notes | https://github.com/Emasoft/claude-plugins-validation | No sandbox install has been executed yet; downstream must verify before user use.

## 23. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/Emasoft/claude-plugins-validation | no_demo; severity=medium

## 24. 安全/权限坑 · 来源证据：CC v2.1.207 spec drift: ${user_config.*} in shell-form commands is now REJECTED, and plugin options are no longer read…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：CC v2.1.207 spec drift: ${user_config.*} in shell-form commands is now REJECTED, and plugin options are no longer read from project settings.json — CPV has no…
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/166 | 来源类型 github_issue 暴露的待验证使用条件。

## 25. 安全/权限坑 · 来源证据：Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-default-branch pushes afte…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-default-branch pushes after secret scan (fleet-stall root cause)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/169 | 来源类型 github_issue 暴露的待验证使用条件。

## 26. 安全/权限坑 · 来源证据：RC-DEP-TAG-PIPELINE false-positives on a correct (manifest-derived) resolver tag — the literal never appears in publish…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：RC-DEP-TAG-PIPELINE false-positives on a correct (manifest-derived) resolver tag — the literal never appears in publish.py
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/168 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 27. 安全/权限坑 · 来源证据：Recognize CC v2.1.218 skill-frontmatter field 'background' (currently flagged 'Unknown frontmatter field')

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Recognize CC v2.1.218 skill-frontmatter field 'background' (currently flagged 'Unknown frontmatter field')
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/173 | 来源类型 github_issue 暴露的待验证使用条件。

## 28. 安全/权限坑 · 来源证据：Scan dependencies (not just the plugin tree) for agent-context writers, and score capability vs live separately

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Scan dependencies (not just the plugin tree) for agent-context writers, and score capability vs live separately
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/174 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 29. 安全/权限坑 · 来源证据：bug(--strict scope): validates non-shippable tracked content (project-memory, test fixtures) + gitignored files

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug(--strict scope): validates non-shippable tracked content (project-memory, test fixtures) + gitignored files
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/176 | 来源类型 github_issue 暴露的待验证使用条件。

## 30. 安全/权限坑 · 来源证据：canonical publish.py: run() hardcodes timeout=300, making the test gate unsatisfiable for a real suite

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：canonical publish.py: run() hardcodes timeout=300, making the test gate unsatisfiable for a real suite
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/179 | 来源类型 github_issue 暴露的待验证使用条件。

## 31. 安全/权限坑 · 来源证据：cpv_validation_common.py trips bandit B108 on its own data constants — blocks publish.py --gate for every plugin vendor…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：cpv_validation_common.py trips bandit B108 on its own data constants — blocks publish.py --gate for every plugin vendoring it
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/172 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 32. 安全/权限坑 · 来源证据：feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/175 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 33. 安全/权限坑 · 来源证据：skillaudit: defensive anti-injection guardrails flagged as injection (4 detectors, NIT blocks --strict); retro-breaks g…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：skillaudit: defensive anti-injection guardrails flagged as injection (4 detectors, NIT blocks --strict); retro-breaks green releases
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/170 | 来源类型 github_issue 暴露的待验证使用条件。

## 34. 安全/权限坑 · 来源证据：skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note description: PROSE (same class as…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note description: PROSE (same class as #177 / #156)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/178 | 来源类型 github_issue 暴露的待验证使用条件。

## 35. 安全/权限坑 · 来源证据：skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zshrc)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zshrc)
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/177 | 来源类型 github_issue 暴露的待验证使用条件。

## 36. 安全/权限坑 · 来源证据：standardize --fix generates a .cspell.json that trips CPV's own skillaudit TOOL_SHADOW detector (clean repo -> blocking…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：standardize --fix generates a .cspell.json that trips CPV's own skillaudit TOOL_SHADOW detector (clean repo -> blocking MAJOR)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/171 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 37. 安全/权限坑 · 来源证据：standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed only MD025; and canon publis…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed only MD025; and canon publish.py never creates the {name}--v{version…
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/165 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 38. 安全/权限坑 · 来源证据：v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex misses the two-call push shap…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex misses the two-call push shape); residual signal is a non-blocking WA…
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/167 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 39. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/Emasoft/claude-plugins-validation | issue_or_pr_quality=unknown

## 40. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/Emasoft/claude-plugins-validation | release_recency=unknown

<!-- canonical_name: Emasoft/claude-plugins-validation; human_manual_source: deepwiki_human_wiki -->